Technical Configuration of a Virtual Collection

Overview

This article will walk you through the technical configuration of a virtual collection.  This article assumes you have an endpoint already defined within your environment.  We have outlined two specific endpoints for this article: Salesforce and Zendesk.  Keep in mind that you can use this to fetch data from any endpoint that allows for OAuth2 and query based endpoints.

You must be a Totango Admin to perform these steps.

Step 1:

In Totango go to the Customer Data Hub page, Under Other Available Integrations, click on the Virtual Collection card to start configuring a Virtual Collection which will bring you to the following screen:

  • Choose a widget Name (The name of the Collection that you are creating)
  • Select a connector.
    If the connector you are looking for does not exist, you can create a new connector right from the connector dropdown.  (This knowledge base article can guide you through configuring a connection.)

Step 2:

Define the Query API endpoint, this is where the information comes from.

Screen_Shot_2020-06-03_at_2.41.59_PM.png

  • You can include any Totango account attributes as parameters for the query, use curly braces to specify parameters ie:{parameter} 
    The Account identifier must be included in the API Query endpoint output, it will let Totango correctly associate the relevant information in the account profile
  • You can use any Query API which returns a JSON format and include an array of objects (these objects will become rows in the collection).
  • The Virtual Collection supports direct API query, API query with filters and even full query language API query.
    Examples:
    • Salesforce opportunities virtual collection API query (full query language API query example):
      https://na1.salesforce.com/services/data/v20.0/query?q=select+AccountId,Amount,CloseDate,Name,StageName+from+Opportunity+Where+AccountId='{sf_id}'
    • Zendesk ticket list API query (direct API query example):
      https://[your_sub_domain].zendesk.com/api/v2/organizations/{Resolved zendesk organization id}/tickets.json
    • Jira Service desk ticket list: View configuration here.
    • SAP C4S ticket information API query (API query with filters example):
      https://remotequery.hana.ondemand.com/api/v1/c4s/query?query=[your_C4S_query_name]&systemTier=PROD&filter=ERP_ID eq '{Account Id}'&orderBy=Priority

Step 3:

List mapping define the path in the JSON response that contains the main array of objects.
This list will turn to the rows in the collection (the individual items), so make sure to map the main objects you wish to present.
The mapping is done by typing the list place in the JSON hierarchy while dot sign (“.”) represents a level in the hierarchy.
For example in the below JSON Response the List mapping is ComponentData.tickets

Step 4:

  • Map the JSON keys to Virtual Collection columns. You can define any JSON key to appear as a column in your Virtual Collection (see example below).
    The mapping includes the column title, JSON key mapping, and the value format. The value format will determine how it looks in the Virtual Collection.

    Column mapping example using the JSON response from above.  Notice we have chosen to capture only the id, issuer and created_at keys, and removed the rest of the keys in the mappings:


    Note, These JSON elements are supported as Virtual Collection columns: string, number, date, string array, array of numbers, array of dates, booleans, null.
    You cannot map a JSON object as a column.

Step 5 (Optional):

  • Virtual Collection summaries are aggregations of the widget information. These summaries can be generated by a numeric column aggregation or by selecting a pre-calculated account attributes (this attribute should be pre-defined in Totango).
  • You can select up to 3 summaries.


    Note, in the dropdown only numeric columns and attributes are presented.

Step 6 (Optional):

  • External link - When the external link is defined, a user can click on a collection widget row to open a link to the origin system.
    For example, it can open the support ticket details in your support application once a user clicks on a support ticket collection row.

    You can define an external link by mapping one of the existing keys in the JSON
    or define a custom URL. The custom URL can include any JSON response key in curly braces ie: {json_key_name}.
    Examples:


Limitations:

  • The Virtual Collection is limited to 1000 rows per response per account. If the API query brings more than 1000 rows, only the first 1000 rows will be used.
    It means that only the first 1000 rows will be used in presenting the information, sorting, and summaries.
    Note, in this case, it is recommended to sort the data within the client query.
  • The Virtual Collection supports REST API with JSON response only.
  • The Virtual Collection supports oAuth2.0 authentication scheme only.
  • The Virtual Collection supports only a single object array for the list mapping, in case you have several object arrays, you should choose the right object array for the list mapping. See List Mapping section above for more details.
  • In the column definition, you cannot map a JSON object as a column.
  • Virtual collection can only be consumed in Account Profile.

Common end points:

Salesforce Endpoints

To retrieve data from Salesforce, we are using the data/v20.0/query REST API (learn more about SFDC Rest API). The following definition will retrieve the opportunities, based on the account SFDC id:

  • API Query Endpoint Production SFDC (if using custom Domain replace na1 with your info): 
 https://na1.salesforce.com/services/data/v20.0/query?q=select+AccountId,Amount,CloseDate,Name,StageName+from+Opportunity+Where+AccountId='{sf_id}'
  • API Query Endpoint Sandbox SFDC (if using custom Domain replace na1 with your info): 
 https://test.salesforce.com/services/data/v20.0/query?q=select+AccountI
  • List mapping (Main object): records

Zendesk Endpoints

To retrieve data from Zendesk, we are using the api/v2/search.json REST API. The following definition will retrieve the open tickets, based on the Organization id:

  • API Query Endpoint: 
https://[your_sub_domain].zendesk.com/api/v2/search.json?query=type:ticket status:new status:open status:pending organization_id:{Resolved zendesk organization id}&sort_by=status&sort_order=desc
  • List mapping (Main object): results

Was this article helpful?

1 out of 1 found this helpful

Have more questions? Submit a request