PX-CS Configuration Options
This article explains the configuration options available to sync your data from Gainsight PX to Gainsight CS. This article is applicable to Gainsight users who are tracking their customer’s usage data through PX, and wish to sync data from PX to CS and analyze the data in Adoption Explorer.
Overview
You can sync data from Gainsight PX to CS, using the PX Connector. However, before you sync your data, you must identify how your organization is using PX to store data. You might either be using the 1:1 setup or 1:M setup in PX.
This article helps you identify how you are using PX to store data and then accordingly directs you to other articles to complete the sync setup.
Scenarios in 1:1 vs 1:M
A 1:1 account setup is one in which you are using a single account in PX to track all of your customer’s data. For instance, assume that you have a customer called Abbett Ltd that has three divisions; Abbett Electronics, Abbett Ceramics, and Abbett Interiors. You sold into all of them. Let us consider the following two use cases to address the scenario:
Single Account per Customer
In your PX instance, if you have a single account to track Abbett Ltd. (unique account id AL104) customer, this setup is known as a 1:1 configuration, where all users at a customer roll into the same unique user id. Looking at the above example of Abbett Ltd, John Smith (user JS258) may work at Abbett Electronics, but his usage falls with all users rolling up to Abbett Ltd. You may be able to group or filter using certain User attributes, but the main unique account id for all users is the same (AL104).
-
If you are using a 1:1 Account, 1:1 User setup, and have a Unique ID in CS and PX on Company, refer to the 1:1 UID Present in Company Object section of this article.
-
If you are using a 1:1 Account, 1:1 User setup, and have a Unique ID in CS and PX but not on the Company object, refer to the 1:1 UID not Present in Company Object section of this article.
Note: If your CS or PX instance does not have Unique IDs, Gainsight does not support such configurations.
Multiple Accounts per Customer
If you are using three accounts to track each of Abbett LTD’s (unique account id AL104) divisions, this setup is known as a 1:M configuration, where all users at a division will first rollup their unique account division id (Electronics id AL104-01, Ceramics id AL104-02, Interiors id AL104-03), before rolling up to the overall unique account id (AL104). Even though there may be a field with the id AL104 on each of the divisions account records, the fact that multiple accounts exist that can still be further aggregated to a single point makes it 1:M.
-
If you are using a 1:M Account, 1:1 User setup, and have a Unique ID in CS and PX on Company, refer to 1:M Accounts, 1:1 Users - UID Present in Company Object section of this article.
-
If you are using a 1:M Account, 1:1 User setup, and have a Unique ID in CS and PX but not on the Company object, refer to 1:M Accounts, 1:1 Users - UID not Present in Company Object section of this article.
Note: If your CS or PX instance does not have Unique IDs, Gainsight does not support such configurations.
Quick Review of 1:1 vs. 1:M
Within the PX Account Explorer structure, the field called id is the unique key for determining whether an account exists already or does not. If the id exists, it will just update the information, otherwise, it creates a new account. If you can find multiple accounts in the explorer that will still further rollup to one main Customer, such as the example of the Electronics, Ceramics, and Interiors divisions of Abbett Ltd., then you are 1:M. If there is only one PX account and one Customer, then you are 1:1.
Single Contact on Multiple Accounts
There can be scenarios in which a contact may be working for multiple accounts. In such scenarios, the configuration is said to be 1:1 Account, 1:M User.
With this scenario, Gainsight only supports the account level configuration. In this scenario, when you configure the PX Connector, you can retain only a single Person value. Also, in Adoption Explorer, lookup is supported only for a single User.
If UID is not present in the Company object, the configuration is not supported.
1:1 UID Present in Company Object
When your Unique ID is present on the Company object, you must perform the configurations specified in this section.
Prerequisites
-
Ensure that you have the CS Org Id, location of UID on CS, CS S3 bucket credentials, PX Company ID, and API Key.
-
Log in to the PX subscription and perform the following tasks:
-
Go to Accounts Explorer and document the attribute in Accounts Explorer with the UID, matching with CS UID.
-
Go to Rest API, create an API key, and document the same (the API key is displayed only once).
-
-
Log in to your CS subscription and perform the following tasks:
-
Document the Org ID of the tenant.
-
Document the field in the Company object that has the UID matching with PX UID.
-
Configurations
You must perform the following configurations in the CS instance.
-
Create a String Data type field PX User ID in the Person object. For more information about creating custom fields, refer to the Add Custom Fields section of the Gainsight Data Management article from the Additional Resources section.
-
Use the PX Connector to establish a connection to your PX instance. You must enter the REST API key generated previously, to authenticate the connection.
-
In PX Connector data sync jobs, perform the following field mappings. For more information about PX Connector, refer to the Gainsight PX Connector article from the Additional Resources section.
|
CS Object |
Fields to be Mapped |
|---|---|
|
Company |
PX UID from Account - CS UID from Company |
|
Person |
Email from PX with Email |
|
Person |
ID from PX with User ID from CS |
|
Person |
First Name from PX with First Name from CS |
|
Person |
Last Name from PX with Last Name from CS |
-
Create a new Project in Adoption Explorer. For more information, refer to the Get PX Data of Single PX Accounts section of the Enable Gainsight PX Data in Adoption Explorer article from the Additional Resources section.
1:1 UID not Present in Company Object
Prerequisites
-
Ensure that you have the CS Org Id, location of UID on CS, CS S3 bucket credentials, PX Company ID, and API Key.
-
Log in to your PX subscription and perform the following tasks:
-
Go to Accounts Explorer and document the attribute in Accounts Explorer with the UID, matching with CS UID.
-
Go to Rest API, create an API key, and document the same (the API key is displayed only once).
-
-
Log in to your CS subscription and perform the following tasks:
-
Document the Org ID of the tenant.
-
Document the field in the Company object with the UID matching with PX UID.
-
Configurations
You must perform the following configurations in the CS instance.
-
Create a custom field on the Company object to hold the UID value. For more information, refer to the Add Custom Fields section of the Data Management article from the Additional Resources section.
-
Create a rule to fetch data from the object that has the UID value. For more information, refer to the Fetch Dataset section of the Rules engine article from the Additional Resources section.
-
Use the Load to Company action type to load the fetched data to the UID field of the Company object. For more information, refer to the Load to Company section of the Setup Rule Actions article from the Additional Resources section.
-
Create a String Data type field PX User ID in the Person object.
-
Use the PX Connector to establish a connection to your PX instance. You must enter the REST API key generated previously, to authenticate the connection.
-
In PX Connector data sync jobs, perform the following field mappings. For more information, refer to the Gainsight PX Connector article from the Additional Resources section.
|
CS Object |
Fields to be Mapped |
|---|---|
|
Company |
PX UID from Account - CS UID from Company |
|
Person |
Email from PX with Email |
|
Person |
AptrinsicID from PX with PXUserID fields from CS |
| Person |
IdentifyID from PX with Existing External ID/New attribute from CS |
|
Person |
First Name from PX with First Name from CS |
|
Person |
Last Name from PX with Last Name from CS |
-
Create a new Project in Adoption Explorer. For more information, refer to the Get PX Data of Single PX Accounts section of the Enable Gainsight PX Data in Adoption Explorer article from the Additional Resources section.
1:M Accounts, 1:1 Users - UID Present in Company Object
Prerequisites
-
Ensure that you have the CS Org Id, location of UID on CS, CS S3 bucket credentials, PX Company ID, and API Key.
-
Log in to the PX subscription and perform the following tasks:
-
Go to Accounts Explorer and document the attribute in Accounts Explorer with the UID, matching with CS UID.
-
Document the INSTANCE ID of the PX subscription. This Id can be domain, tenant, subscription etc
-
Go to Rest API, create an API key, and document the same (the API key is displayed only once).
-
Use the AWS integration to push data from PX to CS’s S3 bucket. The data in CS S3 bucket can be used to create a Rule and associate User ID with the Instance ID.
-
-
Log in to your CS subscription and perform the following tasks:
-
Document the Org ID of the tenant.
-
Document the field in the Company object that has the UID matching with PX UID.
-
Ensure that the Instance Id field resides in an MDA object. If not, replicate it in any of the MDA object.
-
Configurations
You must perform the following configurations in the CS instance.
-
Create three custom fields on the Person object with the following configurations:
|
Field Name |
Data Type |
Lookup required? |
|---|---|---|
|
PX User ID |
String |
No |
|
Instance ID |
String |
Yes. Create a lookup relationship on this field to the MDA object that has the Instance ID field. |
|
Company ID |
String |
Yes. Create a lookup relationship to the GSID field of the Company object. |
-
Configure the PX connector with the API key. You need to establish the connection to your PX instance but you don’t need to configure any data sync jobs.
-
Create a rule with the following Datasets:
|
Dataset Type |
Configurations required |
|---|---|
|
S3 Dataset |
Fetch from the S3 bucket into which data from the PX instance was ingested. |
|
Dataset |
Fetch data from the MDA object that has the instance Id field. Include the Instance Id field and GSID field from the Company object (through lookup) in the Show section. |
|
Merge |
Retain all the unique records from both datasets. Set the merge criteria mapping between accountID field from user object and Instance Id field from the Instance object. |
-
Create the Load to Person action type and perform the following mappings:
|
Dataset Fields |
Person Fields |
|---|---|
|
|
|
|
aptrinsicID Note: This is an internal ID generated by PX. This ID is required for mappings in Survey and Journey Orchestrator integrations. |
PX User ID |
|
id Note: This is the value that you pass for Identify call. It can be an external ID or any other attribute of Person object. |
Identify ID |
|
accountID |
Instance ID |
|
Company GSID |
Company ID |
-
Create a new Project in Adoption Explorer. For more information, refer to the Get PX Data of Multiple PX Accounts section of the Enable Gainsight PX Data in Adoption Explorer article from the Additional Resources section.
1:M Accounts, 1:1 Users - UID not Present in Company Object
Prerequisites
-
Ensure that you have the CS Org Id, location of UID on CS, CS S3 bucket credentials, PX Company ID, and API Key.
-
Log in to the PX subscription and perform the following tasks:
-
Go to Accounts Explorer and document the attribute in Accounts Explorer with the UID, matching with CS UID.
-
Document the INSTANCE ID of the PX subscription. This Id can be domain, tenant, subscription, etc.
-
Go to Rest API, create an API key, and document the same (the API key is displayed only once).
-
Use the AWS integration to push data from PX to CS’s S3 bucket. The data in CS S3 bucket can be used to create Rule and associate User ID with the Instance ID.
-
-
Log in to your CS subscription and perform the following tasks:
-
Document the Org ID of the tenant.
-
Document the field in the Company object that has the UID matching with PX UID.
-
Ensure that the Instance Id field resides in an MDA object. If not, replicate it in any of the MDA objects.
-
Configurations
You must perform the following configurations in the CS instance.
-
Create three custom fields on the Person object with the following configurations:
|
Field Name |
Data Type |
Lookup required? |
|---|---|---|
|
PX User ID |
String |
No |
|
Instance ID |
String |
Yes. Create a lookup relationship on this field to the MDA object that has the Instance ID field. |
|
Company ID |
String |
Yes. Create a lookup relationship to the GSID field of the Company object. |
-
Configure the PX connector with the API key. You need to establish the connection to your PX instance, but you don’t need to configure any data sync jobs.
-
Create a rule with the following Datasets:
|
Dataset Type |
Configurations Required |
|---|---|
|
S3 Dataset |
Fetch from the S3 bucket into which data from the PX instance was ingested. |
|
Dataset |
Fetch data from the MDA object that has the instance Id field. Include the Instance Id field and GSID field from the Company object (through lookup) in the Show section. |
|
Merge |
Retain all the unique records from both datasets. Set the merge criteria mapping between accountID field from user object and Instance Id field from the Instance object. |
-
Create the Load to Person action type and perform the following mappings:
|
Dataset Fields |
Person Fields |
|---|---|
|
|
|
|
aptrinsicId
|
PX User ID |
|
id |
Identify ID |
|
accountId |
Instance ID |
|
Company GSID |
Company ID |
-
Create a new Project in Adoption Explorer. For more information, refer to the Get PX Data of Multiple PX Accounts section of the Enable Gainsight PX Data in Adoption Explorer article from the Additional Resources section.