SalesforceSalesforce is a cloud based customer relationship management software suite.
Salesforce provides customer relationship management service software, and has a complementary suite of enterprise applications as well. These are focused on customer service, marketing automation, analytics, and application development. It is the market leader in CRM solutions.
When using the Salesforce connector, the first thing you will need to do is go to your Tray.io account page, and select the workflow you wish to work on. Once in the workflow dashboard itself, search and drag the Salesforce connector from the connectors panel (on the left hand side) onto your workflow.
With the new Salesforce connector step highlighted, in the properties panel on the right, click on 'New Authentication' which is located under the 'Settings' heading.
You will then need to select the 'scopes' for your authentication to configure exactly what access your Tray workflow will have to Salesforce:
Note that for standard use, you will always need to tick the Api scope.
In the next screen you will then be prompted to enter the credentials of the Salesforce user you will be authenticating with.
This user must be set up correctly in the Salesforce Admin UI, to ensure that you will be able to correctly access all of the available connector operations.
The Tray Salesforce connector gives you full access to all of your Salesforce data including leads, contacts, custom objects/fields, and even workflow rules and outbound messages.
Therefore you will need to make sure that the user you authenticate with has access to the correct objects and record types - in a read, write and create capacity, depending on need.
Managing permissions for users in Salesforce can be done using Profiles and Permission Sets.
NOTE: Currently the Salesforce connector can only be used on the Enterprise Edition of Salesforce, and higher. You may use the Salesforce connector on Professional Edition, but ONLY if you've requested API access from your Salesforce account manager. However, you will not be able to use instant WebHooks on the Professional Edition.
In Salesforce you can allocate a user to a pre-set profile, or you can create your own custom profile.
The available profiles depend on the type of License that a user has.
For example, a Salesforce Platform-licensed user can only have a Standard Platform User profile; while a Salesforce-licensed user (https://help.salesforce.com/articleView?id=users_license_types_available.htm&type=5) can have multiple profiles including Contract Manager and System Administrator which gives comprehensive 'super user' access to all functions and objects.
The Contract Manager profile is more suited to the access level that is required by the Tray Salesforce trigger and connector. This can be seen by looking at the 'Standard Object Permissions' section of the Contract Manager profile settings:
Contract Manager Profile - Standard object permissions
You will note that the Standard Platform User does not have the same set of object permissions - for example it has access to Accounts but no access to Leads, Campaigns or Assets:
Standard Platform User - Standard object permissions
So a good approach would be to clone the Contract Manager profile, and then edit the permissions, bearing in mind the following:
In the Standard Object Permissions section you can set basic read and write access to objects such as contracts, leads and accounts.
In the Administrative Permissions section certain basic key permissions can be set - for example API Enabled must be ticked or the authentication will not work.
Several permissions in the General User Permissions section are relevant in that they allow extra functionality that cannot be granted purely through object-level permissions. For example Activate Contracts must be ticked in order for it to be possible to activate a contract, because the Edit permission on Contracts and Orders is not enough to allow contract activation (you can test activating contracts in Tray with the Update Record operation for the Contract record type - setting the Status field to 'Activated').
This applies to several other options in the General User Permissions section, such as Manage Cases and Activate Orders.
The Salesforce admin UI has tooltips which tell you what object settings are also required for certain permissions:
The following article also provides a useful reference for the object permissions which are required for certain General User Permissions, as well as the required editions:
For example 'Activate Contracts' links to the following page:
This tells you that you need to select Activate Contracts in General User Permissions and set Read and Edit rights on the contracts object in Standard Object Permissions - as already described above.
In Salesforce it is also possible to use 'Permission Sets' to extend users' functional access without changing their profiles.
So you could create a Permission Set which has all the necessary access and then assign it to a particular user to make the necessary adjustments without affecting the profile they are assigned to.
When you create a Permission Set, you can specify the License that it is available for:
If you wish your workflow to be kicked off by a particular action in Salesforce, you can use the Salesforce Trigger.
The Salesforce trigger allows you to receive notifications and trigger workflows when given events occur associated with the selected trigger operation.
The Salesforce trigger is somewhat unique in that not only can you White-labelling the trigger (adjust objects with prefixes), but it also has two types of trigger events available:
- Handling Events from the Salesforce Trigger (See immediately below)
- Standard trigger events
- Manually-created trigger events
From version 2.7 and above the Salesforce Trigger receives trigger events as an 'events' array, instead of an object which can be directly queried.
So any attempts to directly query an object with a jsonpath such as
$.steps.trigger.Id will fail.
If you are creating a new Salesforce trigger, or updating your trigger from version 2.6 or earlier, you will need to set up a loop to go through the events array and take whatever action is needed for each item in the loop. Sometimes the trigger will return multiple events, but it can also return single events (which will then only trigger a single run of the loop).
The Loop Events step will need to set
$.steps.trigger.events as the list to loop through. Then, as an example, a Get account Salesforce step could retrieve the account by pulling the id with
The default behaviour of the trigger is to prefix the newly created objects with the string
From connector version 2.8 onwards, this prefix can be customised using the
Object prefix field found in advanced settings.
The string provided will then be used as the prefix for objects created in Salesforce.
This type of trigger event is where Tray.io creates a number of Salesforce Objects which results in Salesforce sending notifications when a certain event occurs. These objects are the following:
RemoteSiteSetting: Before any notification can be sent the target URL has to be registered as a RemoteSiteSetting.
Workflow rule: A WorkflowRule is created to tell Salesforce when it should send an Outbound message to the workflow.
Outbound message: An OutboundMessage is created and it defines what data is sent to the workflow.
The operations that fall under this category are:
- On custom workflow formula
- On create
- On create/update
- On field change
- On multiple field changes
- On update
Full list of Salesforce operations can be found HERE
This type of trigger event is where you have to login into Salesforce and create/configure a number of Salesforce Objects which results in Salesforce sending notifications to your workflow.
The trigger events that fall under this category are:
- On Apex Trigger
- On Outbound Message
Full list of Salesforce operations can be found HERE
The Salesforce Trigger uses the same authentication method which is described in the first section of this page.
Note that when using the Salesforce trigger, you currently must use a permission set and add it to the User that you will be authenticating with. This permission set must have the 'Modify all Data' permission.
For more details on this operation please see our demo below called Trigger: Outbound message.
Salesforce has a few operations that - due to the inherent nature of the API itself -IMPORTANT: Please note that for warrant further explanation:
- IMPORTANT: Batch operations (see immediately below)
- Handling Leads
- Bulk operations
- SOQL Query & SOSL Query
It is important to take certain steps to handle errors with the Batch Update operation which may pass undetected.
This is because, even though some error statuses might be returned by the Salesforce API, the fact that a response has been returned at all is treated as a successful execution by the Tray.io Salesforce connector.
For example a status of 404: NOT FOUND might be returned and, as you can see, in the debug output it has still returned green:
So you will need to set up a system of dealing with these errors. A very rudimentary approach would be a workflow which takes the following steps:
- Uses a boolean to check if the above output log returns hasErrors: true
- Sends a timestamp of the batch run to Slack
- Loops through the results from the Salesforce output
- Extracts all those whose status was not 204
- Sends a message to a batch errors channel in Slack for each errored account/lead etc.
The end result would be notifications such as:
Another approach might be to use a script like the following which would dig back into the original update list you had compiled to replicate the info that was sent to Salesforce:
And produce a result such as:
Tray.io lets you handle Leads in Salesforce with ease. Using the Salesforce connector, you can find a list of records from Salesforce, using the "Find Records" operation.
Please note that LEADS CAN BE CONVERTED.
Once a lead is converted, you cannot update them in any way, and they are no longer available in the Salesforce interface.
Behind the scenes in the API, Salesforce uses a "Converted" field which is either true or false. You can use this in the Salesforce connector to get a list of leads who haven't been converted yet, for example.
Going a step further, leads can be converted into Contacts, Opportunities, and Accounts. In tray it's possible to get the "ID" of the relevant new converted objects using the "Converted Account ID", "Converted Opportunity ID" and "Converted Contact ID" fields.
The Salesforce connector uses the Bulk API, which follows a slightly different process when manipulating records. When using any operation with the word Bulk in the name, this means that the Bulk API is being used. When a bulk operation is used, Salesforce does not process the data immediately, instead it starts a Bulk Data Load job. The time in which it takes for this job to finish depends on resources available in your Salesforce instance.
The asynchronous nature of bulk data loading in Salesforce means that in the workflow, you would use a bulk data operation and then you would receive a
Job ID (or just
ID as shown in the connector step output).
ID can then be used to poll for the status of the job. Only when the job shows a status of
JobComplete has the data been successfully processed in Salesforce.
For more details on this operation please reference the demo below called Operation: Leads - 'Bulk Upsert'.
The Salesforce Object Query Language (SOQL) and Salesforce Object Search Language (SOSL) APIs can be used to search your organisation’s Salesforce data.
Generally speaking when using these query operations, you should use SOQL to query one operation at a time, and SOSL when you want to search text, email, phone fields, etc (basically when searching multiple objects simultaneously). This is why the latter is better to use when querying a relationship between objects and such.
Here are some points you need to consider when choosing between the two query operations:
Use SOQL when you know which objects the data resides in, and you want to:
- Retrieve data from a single object or from multiple objects that are related to one another.
- Count the number of records that meet specified criteria.
- Sort results as part of the query.
- Retrieve data from number, date, or checkbox fields.
IMPORTANT: Please note that for for SOQL Query to accept your date references, the format MUST BE: YYYY-MM-DD. Please see the SOQL API Documentation for more details.
Use SOSL when you don’t know which object or field the data resides in, and you want to:
- Retrieve data for a specific term that you know exists within a field. Because SOSL can tokenize multiple terms within a field and build a search index from this, SOSL searches are faster and can return more relevant results.
- Retrieve multiple objects and fields efficiently where the objects might or might not be related to one another.
- Retrieve data for a particular division in an organization using the divisions feature.
- Retrieve data that’s in Chinese, Japanese, Korean, or Thai. Morphological tokenization for CJKT terms helps ensure accurate results.
The language used is crucial for your search patterns. In principal, it is extremely similar to SQL in text style.
With the above taken into consideration, below is an example of a SOQL query, which also involves using the Date & Time helper connector (notice how the 'Format' has been deliberately set up to suit Salesforce protocols):
This image demonstrates the way one may use the SOSL query operation to run through 'All Fields' available, in order to return any and all account names and IDs found (unlike the above query example, this is tailored towards multiple )
For further information regarding the Salesforce Object Query Language (SOQL) and Salesforce Object Search Language please see their API Documentation site for more details.
TRAY POTENTIAL: Tray.io is extremely flexible. By design there is no 'fixed' way of working with it - you can pull whatever data you need from other services and work with it using our core and helper connectors. This demo which follows shows only one possible way of working with Tray.io and this connector. Once you've finished working through this example please see our Introduction to working with data and jsonpaths page and Data Guide for more details.
Below are a few examples of ways in which you could potentially use the Salesforce connector, depending on your use case and level of skill. Please choose the one most relevant to you and enjoy the demo.
Below is an example of a way in which you could potentially use the Salesforce trigger AND connector, to integrate with Trello. In this imagined scenario, upon creation of a Salesforce record, the workflow checks who created said card and if it was a Partner referral. Should this be the case, the Tray.io workflow will set a time limit for contact to be made.
The steps will be as follows:
- Setup the trigger and the first connector step in order to get the new record information.
- Create a boolean condition to base your output on.
- If a partner referral is not confirmed, create a Trello card as standard.
- If a partner referral is confirmed, set a contact due date on said Trello card.
The final outcome should look like this:
Once you have clicked 'Create new workflow' on your main Tray.io dashboard (and named said new workflow), select the 'Salesforce Trigger' from the trigger options available:
Once you have been redirected to the Tray.io workflow dashboard, choose your Salesforce authentication, and set the operation to 'On Record Create'. You will see the option to select 'Record type' is mandatory. Choose from the dropdown options available: 'Lead'.
Note: If you click on 'Show advanced properties' you will see the 'Object prefix' option mentioned earlier in the Trigger -> demo app section of this documentation page.
Next, add the first Salesforce connector step. Search and drag over the connector from the left hand panel, into your workflow. Set the operation to 'Find records' and 'Record type' to 'Lead'.
While this step will seem similar to the first one, its purpose is different. The trigger is activated upon a new Lead record being created. The connector step finds said record to get the record info.
Below this section is an input field that is mandatory - 'Conditions matching'. As this is pre-filled to 'Match all conditions' you need not worry about it for this example.
Add another connector step to your workflow, this time utilising the Boolean core connector.
It is here that the conditions are set regarding the two alternative outputs we intend to make.
The first value is generated using jsonpaths and the connector-snake.
CONNECTOR-SNAKE: The simplest and easiest way to generate your jsonpaths is to use our feature called the Connector-snake. Please see the main page for more details.
The first input will be:
$.steps.salesforce-1.records.LeadSource. This means that the the
LeadSource found in the step previous will be what is tested.
The 'Comparison type' is set to:
Equal to which is self explanatory. The final section is what the
LeadSource is queried against:
NOTE: Please make sure to double check your input selectors are set accurately! The first condition is set as a jsonpath, while the next two are strings. If this is not correct then your workflow will come back with an error.
On the left hand branch of the boolean condition, aka the 'FALSE' branch, drop and drag a Trello connector.
Add your Trello authentication as appropriate, and set the operation to 'Create new card'.
If you dont have your Trello authentication set up, please see our Trello docs for more details
Your 'Board ID' will be available from a list of dropdown options, as will your 'List ID'. The 'Name' field we can generate via utilising the connector-snake once more and linking it to "Salesfroce step 1" again as it has all the information regarding said record (including its name).
In the description field our demo is using Tray.io's own interpolation method to auto-generate the output so that it can be displayed easily.
INTERPOLATION: When you wish to include JSON generated data within another input/ output/ result, use our Interpolation method as described here.
Your connector should look similar to this be the end of setup:
Notice that the 'Due Date' is left blank here, as we have not set it (check the bottom right hand corner of the above image). While this is not a mandatory field, it will be important on the 'TRUE' branch later.
On the right hand branch of the boolean condition, aka the 'TRUE' branch, drop and drag a Date & Time Helper connector.
This connector will be used to get the current time stamp for the workflow being processed. Set the operation to do just that by selecting 'Get current timestamp'. choose your timezone, and your preferred format as well.
Take a second Date & Time Helper connector and place it below the first one. In this case the operation will be creating a set time: 'Add to date'. The only other field we need fill in is the 'business days' option, which in this demo will be 1 day.
Finally add a Trello step and fill it in as described previously. This time you may wish to highlight the fact that this was a partner referral within the card description.
Using the connector-snake once more, fill in the due date the time helpers step 2 result:
Your final step should be filled out as follows - you will notice that we have also included the due date in the description step as well:
Once you run your workflow, depending on your outcome you will now auto-generate Trello cards, both will have descriptions attached as per our interpolation within the descriptions we made earlier.
Below is an example of one card that is in viewing mode, which has a partner referral and therefore also includes a due date:
Congratulations! your Salesforce workflow is now complete.