README.md 2.81 KB
Newer Older
Matija Obreza's avatar
Matija Obreza committed
1 2
# Genesys PGR - Java API Client

Matija Obreza's avatar
Matija Obreza committed
3
**genesys-client-api** library aims to ease integration of your existing accession management software in Java with [Genesys PGR portal](https://www.genesys-pgr.org "Visit Genesys PGR").
Matija Obreza's avatar
Matija Obreza committed
4

5
## Initializing the client
Matija Obreza's avatar
README  
Matija Obreza committed
6

Matija Obreza's avatar
Matija Obreza committed
7 8
```java
// Set server URL
9 10 11 12 13 14 15
String baseUrl = "https://www.genesys-pgr.org";
String clientId = "theClientId@genesys";
String clientSecret = "thesecret";
String callbackUrl = "oob";
String scope = "write"; // write scope is required to manage data on Genesys
GenesysClient genesysClient = new GenesysClient(baseUrl, clientId, clientSecret, callbackUrl, scope);
```
Matija Obreza's avatar
README  
Matija Obreza committed
16

17 18 19 20 21 22 23
### Authentication

```java
// Authenticate the user
String authorizationUrl = genesysClient.getAuthorizationUrl();
// The user must now open the authorizationUrl in the browser and approve the
// request on Genesys website. User gets the verifierCode.
Matija Obreza's avatar
Matija Obreza committed
24 25 26 27 28
String verifierCode = null; // whatever user provides
genesysClient.authenticate(verifierCode);

// Test it with /me
genesysClient.me();
Matija Obreza's avatar
README  
Matija Obreza committed
29

Matija Obreza's avatar
Matija Obreza committed
30
// Tokens are now accessible. The refreshToken must be **safely** stored for future use.
31 32 33 34 35 36 37 38 39 40 41 42 43 44
// genesysClient.getTokens().getAccessToken();
// genesysClient.getTokens().getRefreshToken();
```

### Re-using tokens

If you have existing tokens you can provide the access and refresh tokens when
initializing the client:

```java
GenesysTokens genesysTokens = new GenesysTokens();
genesysTokens.setAccessToken("someaccesstoken");
genesysTokens.setRefreshToken("somerefreshtoken");
genesysClient.setTokens(genesysTokens);
Matija Obreza's avatar
Matija Obreza committed
45 46
```

47 48
## Using the API client

Matija Obreza's avatar
Matija Obreza committed
49
Updating data:
Matija Obreza's avatar
README  
Matija Obreza committed
50

Matija Obreza's avatar
Matija Obreza committed
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
```java
List<AccessionJson> accns=new ArrayList<AccessionJson>();

// In a loop, create, fill and add entries to the list
{
    AccessionJson accn=new AccessionJson();
    accns.add(accn);
}

// Once the appropriate batch size is reached
// (good size is 10 or 20 entries)
// send to server
try {
    genesysClient.updateAccessions(instCode, accns);
} catch (....) {
    // handle exceptions
}
```
Matija Obreza's avatar
README  
Matija Obreza committed
69 70

## How to reference `genesys-client-api`
Matija Obreza's avatar
Matija Obreza committed
71

Matija Obreza's avatar
Matija Obreza committed
72 73 74 75
```xml
<dependency>
	<groupId>org.genesys-pgr</groupId>
	<artifactId>genesys-client-api</artifactId>
76
	<version>1.2</version>
Matija Obreza's avatar
Matija Obreza committed
77 78
</dependency>
```
Matija Obreza's avatar
Matija Obreza committed
79

Matija Obreza's avatar
Matija Obreza committed
80
Or for the development version:
Matija Obreza's avatar
Matija Obreza committed
81

Matija Obreza's avatar
Matija Obreza committed
82 83 84 85
```xml
<dependency>
	<groupId>org.genesys-pgr</groupId>
	<artifactId>genesys-client-api</artifactId>
86
	<version>1.3-SNAPSHOT</version>
Matija Obreza's avatar
Matija Obreza committed
87 88
</dependency>
```
Matija Obreza's avatar
Matija Obreza committed
89

Matija Obreza's avatar
Matija Obreza committed
90
### Your copy of the library
Matija Obreza's avatar
Matija Obreza committed
91

Matija Obreza's avatar
Matija Obreza committed
92 93 94
- In Eclipse, clone the `genesys-client-api` repository into a new project
- Right-click on the `genesys-client-api` project and select Maven ... Install.
- This will install the current version of the library into your **local** maven repository
Matija Obreza's avatar
Matija Obreza committed
95

Matija Obreza's avatar
Matija Obreza committed
96
### Your new project
Matija Obreza's avatar
Matija Obreza committed
97

Matija Obreza's avatar
Matija Obreza committed
98
- Create a new Maven project in Eclipse, if starting from scratch
99
- Add dependency on `org.genesys-pgr:genesys-client-api` artifact to your `pom.xml`
Matija Obreza's avatar
Matija Obreza committed
100 101
- Create your integration project
- Contact helpdesk@genesys-pgr.org for assistance if required