Gainsight PX Java SDK

Overview

Gainsight PX Java SDK is a powerful collection of APIs that allows you to perform various tasks. You can use this SDK to create, read, update, or delete User and Account records. This SDK also provides APIs to view, launch, and pause engagements.

Download

You can download the SDK client from the following locations, based on the version: 

• Java 8
• Java 17

For more information, refer to the Gainsight PX REST API article from the Additional Resources section. 

Create PX REST API Key

The Java SDK needs a PX REST API key to work. You must create a REST Key that can be used in the SDK. 

To create a REST API Key: 

1. Navigate to Administration > REST API.
2. Click New API Key.
3. Create a name for the key by modifying the existing name. 
4. Select the required checkboxes under the API Permissions section.
5. Click Create & View.

IMPORTANT: Once the Key is generated, store it securely. This key is never displayed again.

Initialize

You must use the following code to initialize Gainsight PX.

GainsightPXClient px = GainsightPXClient.builder()
                    .apiToken("{apiKey}")
                    .build();

Replace the {apikey} with the key generated in the previous section.

Handle Response Object

When you execute a call via the client, you receive a PX Response object.  In this code example, you can see how to extract the response-code (Status: 200), the response message, and the response object.

PXResponse<User> userResponse = gainsightPXClient.getUser(identifyId).join();
int responseStatus = userResponse.getStatus();
String responseMessage = userResponse.getMessage();
User user = userResponse.getResponse()

An Example to fetch users by their attributes is shown below:

gainsightPXClient.getUser(identifyId).thenAccept(userResponse ->
{
int responseStatus = userResponse.getStatus();
String responseMessage = userResponse.getMessage();
User user = userResponse.getResponse();
// process user here...
});

Users 

You can use the Users API to create, read, update, and delete the User records.

The following code can be used to get User details by Identify ID:

PXResponse<User> userResponse = gainsightPXClient.getUser(identifyId).join(
User user = userResponse.getResponse();

The following example shows how to fetch users by custom attributes, location and user-agent:

Filter filter =  new Filter()
.addExactMatchCondition("location.cityName", "Portland")
.addExactMatchCondition("lastVisitedUserAgentData.userAgent.browserType", "firefox");

gainsightPXClient.getUsers(filter).thenAccept(usersPageResponse -> {
  UsersPage usersPage = usersPageResponse.getResponse();
  // the number of users that match the filter
  long totalHits = usersPage.getTotalHits();
  // the scrollId in case we want to get the next page
  String scrollId = usersPage.getScrollId();
  List<User> users = usersPage.getUsers();
  // process users here...
});

The following code shows how to fetch the next set of users page, by scroll ID:

String scrollId = "{{scrollId}}" // the scrollId from the getUsers request.
gainsightPXClient.getUsersNextPage.thenAccept(usersPageResponse -> {
  UsersPage usersPage = usersPageResponse.getResponse();
  List<User> users = usersPage.getUsers();
  // process users here...
});

The following code shows how to create a User:

User user = User.builder()
      .identifyId("12345678")
      .firstName("john")
      .lastName("johnson")
      .build();

gainsightPXClient.createUser(user);

The following example shows how to update a user by IdentifyId:

String identifyId = "{{userIdentifyId}}" // The user’s identifyId
User user = User.builder()
.firstName("john")
.lastName("johnson")
.build();
gainsightPXClient.updateUser(identifyId, user);

The following example shows how to delete a user by identifyId:

String identifyId = "{{userIdentifyId}}"// The user's identifyId
gainsightPXClient.deleteUser(identifyId);

Accounts 

You can use the Account API to create, read, update, and delete the User records.

The following code can be used to get an account by Account ID:

PXResponse<Account> userResponse = gainsightPXClient.getAccount(accountId).join();
Account account = userResponse.getResponse();

This section explains various API functions that can be applied to create, edit or delete data related to accounts.

The following example shows how to create an Account:

Account account = Account.builder()
      .id("12345678")
      .name("Google")
      .build();
gainsightPXClient.createAccount(account);

The following code shows how to Update an account:

Account account = Account.builder()
      .name("Google+")
      .industry("Internet")
      .build();
gainsightPXClient.updateAccount("{{accountId}}", account);

The following example shows how to Delete an account:

String accountId = "{{accountId}}";
gainsightPXClient.deleteAccount(accountId);

The following example shows how to fetch accounts data:

Filter filter =  new Filter()
.addGreaterThanCondition("numberOfEmployees", "25");

gainsightPXClient.getAccounts(filter).thenAccept(accountsPageResponse -> {
  AccountsPage accountsPage = accountsPageResponse.getResponse();
  // the number of accounts that match the filter
  long totalHits = accountsPage.getTotalHits();
  // the scrollId in case we want to get the next page
  String scrollId = accountsPage.getScrollId();
  List<Account> accounts = accountsPage.getAccounts();
  // process accounts here...
});

The following example shows how to fetch the next accounts page by scrollId:

String scrollId = "{{scrollId}}" // the scrollId from the getAccounts request.
gainsightPXClient.getAccountsNextPage.thenAccept(accountsPageResponse -> {
  AccountsPage accountsPage = accountsPageResponse.getResponse();
  List<Account> accounts = accountsPage.getAccounts();
  // process accounts here...
});

Custom Event 

Sending custom events

});public static void main(String[] args) {
        String apiKey = null;
    if (args.length != 1) {
      System.err.println("Usage: TestSDK [REST API KEY] not passed, hardcoding API key");
      apiKey = hardcodedapiKey;
    } else {
            apiKey = args[0];
        }
    GainsightPXClient px = null;
    try {
      px = GainsightPXClient.builder()
        .apiToken(apiKey)
        .baseUrl("https://api.aptrinsic.com")
        .build();
      // create a new Custom Event
      //attributes
      Map<String, Object> attribs = new HashMap<String, Object>();
      attribs.put("prop1", "Red");
      attribs.put("prop2", "Green");
      attribs.put("prop3", "Blue");
      attribs.put("prop4", "White");
      CustomEvent ce = CustomEvent.builder()
              .identifyId("xxxxxxx")
              .eventName("Test Java API Custom Event")
              .propertyKey("AP-XXXXXXXXXX-2")
              .eventType("CUSTOM")
              .userType("USER")
              .attributes(attribs)
              .build();
      System.out.println("Creating Custom Event:"+ce.getEventName());
      px.sendCustomEvent(ce).get();
      System.out.println("Done");
    } catch (IOException | QueueOverFlowException e) {
      throw new RuntimeException(e);
    } catch (ExecutionException e) {
      throw new RuntimeException(e);
    } catch (InterruptedException e) {
      throw new RuntimeException(e);
    }
    finally {
      if (px != null) {
        try {
          px.close();
        } catch (IOException e) {
          throw new RuntimeException(e);
        }
      }
    }
  }

Engagements 

The engagements API allows you to perform various tasks via APIs. 

The following code shows how to get engagement by ID:

PXResponse<Engagement> engagementResponse = gainsightPXClient.getEngagement(engagementId).join();

The following code shows how to launch an engagement:

PXResponse<EngagementStateChangeResponse> 
engagementStateResponse = gainsightPXClient.startEngagement(engagementId).join();

The following code shows how to launch an engagement in a specific environment:

PXResponse<EngagementStateChangeResponse> 
engagementStateResponse = gainsightPXClient.startEngagement(engagementId, Environment.STAGE).join();

The following code shows how to launch an engagement to multiple environments:

PXResponse<EngagementStateChangeResponse> 
engagementStateResponse = gainsightPXClient.startEngagement(engagementId, 
Arrays.asList(Environment.STAGE, Environment.QA)).join();

The following code shows how to pause an engagement:

PXResponse<EngagementStateChangeResponse> 
engagementStateResponse = gainsightPXClient.pauseEngagement(engagementId).join();

The following example shows how to get a list of engagements:

Set<ContentTypeOuterClass.ContentType> contentTypes = Collections.singleton(ContentTypeOuterClass.ContentType.IN_APP_DIALOG);
gainsightPXClient.getEngagements(0, 10, contentTypes).thenAccept(engagementsPageResponse -> {
  EngagementsPage engagementsPage = engagementsPageResponse.getResponse();
  List<Engagement> engagements = engagementsPage.getEngagements();
  // process the engagements here
});

Additional Resources

Gainsight PX REST API