Skip to main content
Gainsight Inc.

Gainsight PX Java SDK

This article explains how to use Gainsight PX’s Java Software Development Kit (SDK).

Overview

This article explains how to use the APIs provided by the PX Java SDK. The 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 this location or read the full REST API doc here.

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 Settings > 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.

Test.GIF

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

key.png

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 PXResponse 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 (using completable future):

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

Users API

You can use the Users API to create, read, update, and delete the User records. The following code can be used to get a 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 (using completable future):

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 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 API

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 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...
});

Engagements API

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

The following code shows how to get an 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 to a specific environment

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

The following code shows how to launch an engagement to a 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
});

 

  • Was this article helpful?