Tray Embedded / Advanced Topics / Using the Call Connector API

Using the Call Connector API

This mutation can be used to call a specific connector operation.

This powerful feature is used in combination with a User Token and Authentication Id, to pull data from a particular service connector operation and display it in your app.

As an example, for a particular End User of your Embedded application, you could use it to display all of the 'Warm' Salesforce Leads assigned to them, or display all the customers with overdue payments.

You could also use such data as this to build graphical displays and charts.

Required tokenNotes
UserObtained after creating a user and authorizing a user
The User Token is a persistent token (valid for 2 days) that should be securely stored in your application
It must be passed as the bearer to use the user's authentications in the connector operation

The mutation accepts the following arguments:

InputRequiredNote
connectorYesThe programatic connector name. Obtained from the workflow builder, see example below
versionYesThe version of the connector being used. Obtained from inspecting the Advanced settings of the input panel in the workflow builder, see example below
operationYesThe programmatic name of the operation. This is usually the name of the operation visible in the workflow builder input panel, converted to snake case. Please reach out to support@tray.io if you get the error message The connector operation ### was not found
authIdYessee prerequisites below on obtaining an authId
inputYesThe stringified JSON body representing the input parameters to the operation, see example below on how to generate
clientMutationIdNoOnly relevant if using the Relay GraphQL client

It returns the following data:

Returned DataNotes
outputThe stringified JSON body representing the data returned from the connector
clientMutationIdOnly relevant if using the Relay GraphQL client

Prerequisites - a User Access Token and Authentication ID

As specified in the 'Required Token' table above, calls with this mutation will have to be made with a User Access Token as the bearer - obtained by creating a user and authorizing a user

The authId field in the query will also require the id of an authentication (i.e. linked to that user) with the service whose connector operation you wish to call.

Authentications can be made for users via several methods:

End Users' authIds can be retrieved at any time using the List Authentications

They can also be mapped and edited as described in Mapping and Editing Auths

Example mutation 1 - Salesforce

The following is a query which could be used in Insomnia or the GraphQL playground. It retrieves the first 10 leads from Salesforce

Note: the mutation name is abritrary and does not have to be 'callSalesforce'. Also note that you can make multiple calls within one mutation.

Here we make one called listLeads. In the Bonus Step step below we make two calls - listAllLeads and listWarmLeads:

mutation callSalesforce {
listLeads: callConnector(input: {
connector: "salesforce",
version: "4.0",
operation: "find_records",
authId: "########-####-####-####-############",
input: "{\\"limit\\":10,\\"conditions_type\\":\\"Match all conditions\\",\\"fields\\":[\\"Id\\",\\"Name\\"],\\"object\\":\\"Lead\\"}"
}) {
output
}
}

1 - Get the connector name and version

To understand how this is constructed, create a new workflow with a Manual Trigger, and add the Salesforce connector after the trigger:

Now we can get the first two field names for the above mutation:

connector: in the workflow builder, the grey step title which reads salesforce-1 next to the connector tile represents the programatic connector name, by removing the -1 from the end (this is added to make the step name unique in the workflow).

version: to find the version of the connector that is being used, scroll to the bottom of the input panel for the Salesforce step, and click 'Show advanced settings'. Then scroll back to the top of the input panel. You should now see a grey field called Connector Version:

2 - Get the operation name

Now we can get the following field:

operation: this example uses the Find records operation. Note how in the example mutation snippet above, we've applied the snake case transformation to the operation name Find records to get its programatic name of find_records:

3 - Get the input

In the above screenshot note how the record type, the fields and the limit on number of records returned have been set (no matching conditions have been set here - see the Bonus Step for what this would look like).

Now run the workflow. Going into the Debug panel of the workflow, find the latest workflow run, and inspect the Input of the salesforce-1 step:

This is the JSON we use as the contents for the input parameter of the API query. However, we first need to convert the JSON to a text string in order to use it. This can be achieved easily in your workflow. First, we parse the JSON that we copy from this Input. Then we stringify it and use this output.

Add the Object Helpers to the workflow after the Salesforce step, and set the operation to JSON Parse. The value of the Text field will be the Input to the Salesforce step we just ran:

Next, duplicate this step, and change the operation in the newly created step to JSON Stringify. Set the value to a jsonPath referencing the output from the preceeding Object Helpers step:

Now run the workflow again. When you inspect the Output of this final Object Helpers step, you will see a property called result, and its contents will contain a JSON string you can use in the input property for the GraphQL query:

You can then copy this to create the input string as per the above mutation snippet:

input: "{\\"limit\\":10,\\"conditions_type\\":\\"Match all conditions\\",\\"fields\\":[\\"Id\\",\\"Name\\"],\\"object\\":\\"Lead\\"}"

## Bonus step - making multiple calls in one

If we wanted to make two calls within the mutation - one which lists all leads, and one which lists only warm leads, we could have set the filter in the Salesforce operation:

This would ultimately have given us the stringified result:

"{\\"conditions_type\\":\\"Match all conditions\\",\\"fields\\":[\\"Id\\",\\"Name\\"],\\"conditions\\":[{\\"field\\":\\"Rating\\",\\"operator\\":\\"Equal to\\",\\"value\\":\\"Warm\\"}],\\"object\\":\\"Lead\\"}"

We could then have used this to build the second call within the mutation - leaving our mutation looking like this:

mutation callSalesforce {
listAllLeads: callConnector(input: {
connector: "salesforce",
version: "4.0",
operation: "find_records",
authId: "########-####-####-####-############",
input: "{\\"limit\\":10,\\"conditions_type\\":\\"Match all conditions\\",\\"fields\\":[\\"Id\\",\\"Name\\"],\\"object\\":\\"Lead\\"}"
}) {
output
},
listWarmLeads: callConnector(input: {
connector: "salesforce",
version: "4.0",
operation: "find_records",
authId: "########-####-####-####-############",
input: "{\\"conditions_type\\":\\"Match all conditions\\",\\"fields\\":[\\"Id\\",\\"Name\\"],\\"conditions\\":[{\\"field\\":\\"Rating\\",\\"operator\\":\\"Equal to\\",\\"value\\":\\"Warm\\"}],\\"object\\":\\"Lead\\"}"
}) {
output
}
}

This will return a result such as:

{
"data": {
"listAllLeads": {
"output": "{\\"total\\":10,\\"next_page_offset\\":null,\\"records\\":[\n\t{\\"Id\\":\\"00Q4J000002yVgAUAU\\",\\"Name\\":\"John doe\\"},\n\t{\\"Id\\":\\"00Q4J000001IRLpUAO\\",\\"Name\\":\\"Steven Wright\\"},\n\t{\\"Id\\":\\"00Q4J000001b5X1UAI\\",\\"Name\\":\\"Bertha Boxer\\"},\n\t{\\"Id\\":\\"00Q4J000001b5X2UAI\\",\\"Name\\":\\"Phyllis Cotton\\"},\n\t{\\"Id\\":\\"00Q4J000001b5X3UAI\\",\\"Name\\":\\"Jeff Glimpse\\"},\n\t{\\"Id\\":\\"00Q4J000001b5X4UAI\\",\\"Name\\":\\"Mike Braund\\"},\n\t{\\"Id\\":\\"00Q4J000001b5X5UAI\\",\\"Name\\":\\"Patricia Feager\\"},\n\t{\\"Id\\":\\"00Q4J000001b5X6UAI\\",\\"Name\\":\\"Brenda Mcclure\\"},\n\t{\\"Id\\":\\"00Q4J000001b5X7UAI\\",\\"Name\\":\\"Violet Maccleod\\"},\n\t{\\"Id\\":\\"00Q4J000001b5X8UAI\\",\\"Name\\":\\"Kathy Snyder\\"}]}"
},
"listWarmLeads": {
"output": "{\\"total\\":2,\\"next_page_offset\\":null,\\"records\\":[\n\t{\\"Id\\":\\"00Q4J000001b5X6UAI\\",\\"Name\\":\\"Brenda Mcclure\\"},\n\t{\\"Id\\":\\"00Q4J000001b5XIUAY\\",\\"Name\\":\\"Jack Rogers\\"}]}"
}
}
}

Example mutation 2 - Mailchimp

The following is a query which could be used in Insomnia or the GraphQL playground. It lists the recipients in a Mailchimp campaign.

Note that the mutation name is abritrary and does not have to be 'callMailchimp':

mutation callMailchimp {
listRecipients: callConnector(input: {
connector: "mailchimp",
version: "3.5",
operation: "list_campaign_recipients",
authId: "c2eee911-xxxx-xxxx-xxxx-c88f00ff8259",
input: "{\\"per_page":100,\\"page\\":1,\\"campaign_id\\":\\"39xxxx176\\"}"
}) {
output
}
}

1 - Get the connector name and version

Create a new workflow with a Manual Trigger, and add a Mailchimp connector after the trigger:

Now we can get the first two field names for the above mutation:

connector: in the workflow builder, the grey step title which reads mailchimp-1 next to the connector tile represents the programmatic connector name, by removing the -1 from the end (this is added to make the step name unique in the workflow).

version: to find the version of the connector that is being used, scroll to the bottom of the input panel for the Mailchimp step, and click 'Show advanced settings'. Then scroll back to the top of the input panel. You should now see a grey field called Connector Version:

2 - Get the operation name

Here we can get the following field:

operation: this example uses the List campaign recipients operation. Note how in the example mutation snippet above, we've applied the 'snake case' transformation to the operation name List campaign recipients to get its programmatic name of list_campaign_recipients:

3 - Get the input

In the above screenshot note how the Campaign ID and the page and number of recipients per page have also been set.

Now run the workflow. In the Debug panel of the workflow, find the latest workflow run, and inspect the Input of the mailchimp-1 step:

This is the JSON we use as the contents for the input parameter of the API query (minus the access token).

However, we first need to convert the JSON to a text string in order to use it. This can be achieved easily in your workflow. First, we parse the JSON that we copy from this Input. Then we stringify it and use this output.

Add the Object Helpers to the workflow after the Salesforce step, and set the operation to JSON Parse. The value of the Text field will be the Input to the Salesforce step we just ran (minus the access token):

Next, duplicate this step, and change the operation in the newly created step to JSON Stringify. Set the value to a jsonPath referencing the output from the preceeding Object Helpers step:

Now run the workflow again. When you inspect the Output of this final Object Helpers step, you will see a property called result, and its contents will contain a JSON string you can use in the input property for the GraphQL query:

You can then copy this to create the input string as per the above mutation snippet:

input: "{\\"per_page\\":100,\\"page\\":1,\\"campaign_id\\":\\"392xxx176\\"}"