README.md

Finance API Client library for java

This is a client library for the UW Madison campus REST Finance API. The information on the HR API itself, how to obtain access to, etc. can be found at https://developer.wisc.edu .

IMPORTANT NOTE: This library is implements only a small subset of the available APIs from the Finance REST API.

Including the library in your project

Maven:

<dependency>
  <groupId>edu.wisc</groupId>
  <artifactId>finance-api-client</artifactId>
  <version>1.0.0</version>
</dependency>

You will likely need to include the campus GITLab repository in your POM file:

<repositories>
    <repository>
        <id>uw-madison-gitlab-finaceapi</id>
        <name>UW Madison GITLab</name>
        <url>https://git.doit.wisc.edu/api/v4/projects/89437/packages/maven</url>
    </repository>
</repositories>

Using the library in your code

First thing you will need to do is create a FinanceAPIClient object. Once you have this, you can make calls to the Person API using the public methods.

For example, to get the UW Madison Company info:

import edu.wisc.finance_api.model.Company;
import edu.wisc.finance_api.client.NotFoundException;
import edu.wisc.finance_api.client.FinanceAPIClient;

class mytest {

  public void findMadisonSuporg() {
    try {
      FinanceAPIClient myClient = new FinanceAPIClient("<my app id>", "<my app secret>");
      SupervisoryOrganization madison = myClient.getCompanyById("UWMSN");
    } catch (NotFoundException notfound) {
      log.info("Madison Campus not found>");
    }
  }
}

Application Exit Hang Fix

If you find that your application when done, hangs around (jvm doesn't exit), this is due to a bug in the OKHttp library that could potentially keep some of its threads active for a period of time. A Fix was added to version 1.0.3 of the PersonAPI Client to add a "shutdown" method. Simply call this method before your application exits to force these threads to end.

Authentication

Authentication to use the Person API comes from having an approved application on https://developer.wisc.edu. When you have a registered application with access to the Person API, you can create a pair of API Keys. This pair of key/secret is used when creating the PersonAPIClient object.

No attempt is done upon creating the object to validate the credential. There are two methods provided by the library:

• isAuthenticated()
• Authenticate()

You do not need to call either of these when using the other methods. The library will be doing this on your behalf. It will also track how long the authentication is good for, and renew as needed for long running applications.

Any method may throw the AuthenticationException when called if the credentials provided were invalid.

Finance Data Model

The data model for the Person API is contained in the edu.wisc.finance_api.model.* classes.

The two model entries (AccessToken, OAuthError) are used to manage the authentication processs and can be ignored.

Logging

The client doesn't do any logging above the debug level. However, you can enable the logging intercepter for the OkHttpClient. This will log some basic information to the INFO level about requests going to the Person API.

To enable this logging, call setEnalbeHttpLogging(true). When you call this method, it will force a re-authentication as the client needs to rebuild the OkHttpClient object.

Java Doc

The java class documentation for the Person API Client can be found at https://engr.pages.doit.wisc.edu/finance-api-client/apidocs/index.html

Version History

Version 1.0.0

• Initial Release