Integrating with Gainsight

About Integrating with Gainsight

Gainsight is a customer success platform for enhancing customer engagement, improving retention, and driving expansion.

You can integrate your Qualtrics account with Gainsight to pass data between platforms and trigger a Qualtrics workflow based on events in Gainsight. For example, if a customer completes an onboarding journey which is tracked in Gainsight, you can send them a follow-up survey via Qualtrics asking them about their onboarding experience.

Step 1: Creating an Authentication Header

To set up the connection with Gainsight, you’ll need a basic authentication header. This header is a Base64 encoded string that contains your Qualtrics username and your API token separated by a colon. To create the header:

1. Find your Qualtrics username and your Qualtrics API token.
   Attention: If you already have an API token, do not generate a new one.
2. Create an authorization string in the following format: “username:APItoken”.
3. Encode your string using a Base64 encoder.
4. Save this key for later.

Step 2: Setting up a JSON Event

Next, create a new Qualtrics workflow to receive data sent from Gainsight. This workflow can be used purely as a trigger, or it can also ingest data that may be useful in later workflow steps.

1. In Qualtrics, navigate to the Workflows page.
2. Click Create a workflow.
3. Select Started when an event is received.
4. Give your workflow a name.
5. Save your workflow as a Stand-alone workflow.
6. Click Create workflow.
7. Choose the JSON event.
8. In your JSON event, click Copy URL. Save this URL for later.

At this point, the JSON event created in the steps above can be used to set up the integration and to trigger other tasks in the workflow. If you simply need to start your workflow, you can skip the additional steps below and save the JSON event. However, if you want to pass additional data to Qualtrics from Gainsight (for example, “Company GSID” or “Renewal Date”), then you must add those fields into the JSON event:

1. Go to the Advanced settings section of the JSON event.
2. Click Add a JSON field.
3. Enter the JSON field name.
4. Define the JSON path expression (for simple key value pairs, use “$.[fieldName]” e.g. “$.companyGSID”).
5. Click Save.

These JSON fields will now be available in subsequent workflow tasks as “Event Data: User-Defined Field”. They can be accessed via the piped text menu, {a}.

Step 3: Creating a Custom Gainsight Connector

Next, you must create a new custom connector in Gainsight to connect with Qualtrics. This connector will store your authentication token from earlier, and will be used to send data to Qualtrics via External Actions in Gainsight.

You only need 1 connector for Qualtrics. If a custom connector for Qualtrics already exists, then skip to the next section about configuring an External Action in Gainsight.

1. In Gainsight, navigate to Administration.
2. Select Integrations and then Connectors 2.0.
3. Click Create Connection.
4. Select Custom Connector.
5. Name your connection.
6. Select Authorization Type: Token Based.
7. Enter the following Header key-value pair:
   • Key: “Authorization”
   • Value: “Basic {{encoded username and token value from earlier}}”
     Example: Your value will look something like this:
     Basic ZGVtb0BxdWFsdHJpY3MuY29tOmY4Z0lLN0c2R0ZIOTg1WTQ=
     Refer to the HTTP BASIC AUTH section of this support page for more information.
8. Enter a description for the connector so you know its purpose.
9. Click Save.

Step 4: Configuring Gainsight External Action

After creating the custom connector, you can configure an external action in Gainsight to send a request to your Qualtrics JSON event. If you’d like to create multiple workflows triggered by Gainsight, then you will need to create a separate external action for each workflow.

Remember, you only ever need 1 connector for Qualtrics. All external actions used to interact with Qualtrics should be under the same Qualtrics custom connector.

1. In Gainsight, navigate to Administration.
2. Select Integrations and then External Actions.
3. Click Create Action at the top of the page.
4. Select the Qualtrics custom connector that you created earlier.
5. Enter a name for the action. This can not be edited later.
6. Choose POST for the method.
7. Paste the JSON event URL you copied earlier into the URL field of the new external action.

Next you will need to configure the payload of your request. If you plan on using this Gainsight external action solely as a trigger and do not need to send any additional data, then you only need to add an opening and closing curly bracket to the payload before saving, e.g. { }. Otherwise, if you intend to send additional data from Gainsight to Qualtrics, then you will need to add key-value pairs to the payload:

1. Enter a key-value pair for each field that you intend to send to Qualtrics.
   • • Each key should exactly match the JSON field name from the JSON event in Qualtrics.
     • Each value can be configured as a static value, or tokenized to accept input from other areas in Gainsight like the Rules Engine.
     • Each key-value pair should be separated from the next by a comma.
       Example: Below is the JSON payload for the fields we configured earlier. Both key-value pairs in this example will accept parsed values input from a Rules Engine Action.
       {
"companyGSID" : "{{Company_GSID}}",
"recipientEmailAddress" : "{{Recipient_Email}}"
}
2. Click Create at the top of the page to save your external action.

Testing the Connection

To test the connection:

1. In Qualtrics, open the JSON event you created earlier.
2. Click Run test. You will see a message that an event is awaited.
3. In Gainsight, go to the external action you created earlier.
4. Click Test at the top of the page.
5. Enter values for each key-value paid you’d like to test.
6. Click Test Action.

A successful test will return a Status Code 202, eventId, and requestId.

You will also see the test key-value pairs appear in the “JSON captured from most recent test” within Qualtrics.

Step 5: Using Gainsight External Actions in the Rules Engine

In order to use your newly configured external action, you will need to use the “Call External API” action within the Rules Engine. Each row submitted to this action will execute independently, so a dataset of 100 records using the Call External API action will result in 100 separate API calls.

1. In Gainsight, navigate to Administration.
2. Select Rules Engine.
3. Create a rule that includes that data you want to send to Qualtrics. These fields that make up the dataset will be unique to your use case.
4. In the “Action Setup” section of the rule, click the plus sign (+).
5. Click Skip This Step on the “Add Criteria” screen.
6. Click Create Action and select Call External API.
7. Choose the Qualtrics connector you created earlier.
8. Choose the external action you created earlier.
9. Map your Source Field values (from the rule dataset) to the Action Field keys (from the JSON payload).
   Qtip: You can set a static value as the source field instead of mapping a field from the dataset.
10. Click Save Actions.