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 token	Notes
User	Obtained after using Users/Mutations/Create User Token. The User Token is a persistent token that should be securely stored in your application for future use (expires after 2 days)

The mutation accepts the following arguments:

Input	Required	Note
connector	Yes	The programatic connector name. Obtained from the workflow builder, see example below
version	Yes	The version of the connector being used. Obtained from inspecting the Advanced settings of the input panel in the workflow builder, see example below
operation	Yes	The 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`
authId	Yes	see prerequisites below on obtaining an authId
input	Yes	The stringified JSON body representing the input parameters to the operation, see example below on how to generate.
clientMutationId	No	Only relevant if using the Relay GraphQL client

It returns the following data:

Returned Data	Notes
output	The stringified JSON body representing the data returned from the connector
clientMutationId	Only relevant if using the Relay GraphQL client

Prerequisites - a User Access Token and Authentication ID
Copy

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:

By launching the Config Wizard
By using the Auth-only Dialog - including a postMessage which returns the authId
By using the createUserAuthentication API (which returns an authId) as detailed in Create User Authentication and Importing Authentications (NOTE unless you are the owner of the service this cannot be done for services which use OAuth as their authentication method - see the Note on OAuth Services)

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
Copy

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:

1mutation callSalesforce {
2 listLeads: callConnector(input: {
3  connector: "salesforce",
4  version: "4.0",
5  operation: "find_records",
6  authId: "########-####-####-####-############",
7  input: "{\\"limit\\":10,\\"conditions_type\\":\\"Match all conditions\\",\\"fields\\":[\\"Id\\",\\"Name\\"],\\"object\\":\\"Lead\\"}"
8 }) {
9  output
10 }
11}

1 - Get the connector name and version
Copy

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
Copy

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
Copy

You can explore the input schema for all connectors and their operations' in the operations explorer app.

You can also find it in the builder using the steps below:

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
Copy

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:

1"{\\"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:

1mutation callSalesforce {
2 listAllLeads: callConnector(input: {
3  connector: "salesforce",
4  version: "4.0",
5  operation: "find_records",
6  authId: "########-####-####-####-############",
7  input: "{\\"limit\\":10,\\"conditions_type\\":\\"Match all conditions\\",\\"fields\\":[\\"Id\\",\\"Name\\"],\\"object\\":\\"Lead\\"}"
8 }) {
9  output
10 },
11
12 listWarmLeads: callConnector(input: {
13  connector: "salesforce",
14  version: "4.0",
15  operation: "find_records",
16  authId: "########-####-####-####-############",
17  input: "{\\"conditions_type\\":\\"Match all conditions\\",\\"fields\\":[\\"Id\\",\\"Name\\"],\\"conditions\\":[{\\"field\\":\\"Rating\\",\\"operator\\":\\"Equal to\\",\\"value\\":\\"Warm\\"}],\\"object\\":\\"Lead\\"}"
18 }) {
19  output
20 }
21
22}

This will return a result such as:

1{
2 "data": {
3  "listAllLeads": {
4   "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\\"}]}"
5  },
6  "listWarmLeads": {
7   "output": "{\\"total\\":2,\\"next_page_offset\\":null,\\"records\\":[\n\t{\\"Id\\":\\"00Q4J000001b5X6UAI\\",\\"Name\\":\\"Brenda Mcclure\\"},\n\t{\\"Id\\":\\"00Q4J000001b5XIUAY\\",\\"Name\\":\\"Jack Rogers\\"}]}"
8  }
9 }
10}

Example mutation 2 - Mailchimp
Copy

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':

1mutation callMailchimp {
2 listRecipients: callConnector(input: {
3  connector: "mailchimp",
4  version: "3.5",
5  operation: "list_campaign_recipients",
6  authId: "c2eee911-xxxx-xxxx-xxxx-c88f00ff8259",
7  input: "{\\"per_page":100,\\"page\\":1,\\"campaign_id\\":\\"39xxxx176\\"}"
8 }) {
9  output
10 }
11}

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\\"}"

Using the Call Connector API

Prerequisites - a User Access Token and Authentication IDCopy

Example mutation 1 - SalesforceCopy

1 - Get the connector name and versionCopy

2 - Get the operation nameCopy

3 - Get the inputCopy

Bonus step - making multiple calls in oneCopy