In this article, you will go through some common use cases of Custom JS in your embedded solutions. Alternatively, You can check out our Custom JS repository with use cases and walkthrough videos.

For examples 1, 2 and 3, we have set up an Embedded project which you can download and install to test yourself.

It is a data mapping integration between Salesforce and a fictional CRM called Acme:

Salesforce is a real world CRM while Acme is another mock CRM system which is a placeholder for the service you want to build a custom integration with.

Prerequisites for Example 1-3

You have to do these steps if you want to see the examples 1,2 and 3 in action. You may skip this and navigate to standalone examples in Use Cases (standalone) section.

Create Salesforce account (optional)

Set up the project

Import the mock API workflow

Edit webhook URLs

You will then need to edit the webhook urls in the following screens to match that of your Acme API service workflow:

Test using the Embedded demo app

You will then:

  1. Publish your solution

  2. Test your solution either by creating instance from the UI or through the marketplace app.

  3. Once you have created a Solution Instance for an End User test by adding a new contact/account etc. to Salesforce and you will then see a successful run for that End User:

In all the Custom JS below, the headers, parameters, url etc. entered are specific to the mock Acme API service we have created. When using your own service, you will need to adjust these accordingly

Examples (using ACME service)

The examples shown below can also be found at our Github repository.

1 - Generating dropdown lists

Normally when you want to display a dynamic list in the config wizard, this is quite intuitive - you create the config slot on a field that is a dropdown list in the workflow (see Config and drop-down lists).

However, this only works when we have the correct connector operations and dropdown lists.

There may be times when you want to define a new list. You can achieve this using custom javascript.

In this example, when pushing records to Acme, we want to prompt the end user to select what object type they want to push new Salesforce records to:

This is done with the following steps:

2 - Customising the data mapping component

As in the example of generating dropdown lists, there are times when you might want to use the Data Mapping component with dynamic lookups but we don't support the connector operation you need to set this up.

In this case when an End User has selected e.g. 'Contacts' as the Acme object to sync to in step 1 above, we want the available fields to dynamically respond to the fields available for a 'contact'.

On the right hand side, we want the user to be able to select from the list of available Acme fields for the object they have chosen:

In order to achieve the above functionality, we do the following:

3 - Showing / hiding slots based on dependencies

In order to improve the user experience of the wizard you may wish to show or hide slots based on the value of another. In this solution, on the final screen we present the option to the user of either:

  • using the default mapping if the user so chooses

  • making use of a user-defined mapping

The native Data Mapper feature doesn't support the ability to be hidden or visible based on the value of another slot.

So we set up the external_use_default_mapping slot in the following manner:

More Examples (standalone)

1 - Validating the auth or input data

This example illustrates another use case of Custom JS and does not employ the Acme-Salesforce integration use case we used to illustrate examples 1, 2 and 3.

Data validation is a very common use case where you might want to use Custom JS. You can perform a sanity check on the data entered by the user in the config wizard and display an error message if data entered does not pass the tests given by you.

1a - Use case for data type validation

You can download the project from here and import to test this example end to end.

If you are taking a config value like 'Email' or 'phone number' from the user in the config wizard, you can use custom JS to check for a valid email address/phone number.

Here we show you an example where end user has to enter a valid email address for the field 'username'.

If the entered email is not a valid email, config wizard throws an error and the user can' move to the next step and has to go back to the previous step to fix the error.

Below are steps how you can achieve this:

1b - Use case with a connector operation

You can download the project from here and import to test this example end to end.

This example shows how you can use Call Connector function to validate user supplied data in the config wizard.

This integration runs the google analytics report for a website from a start date to an end date and feeds the data to a storage (like Amazon S3).

The connector's 'Generate report' operation expects the end date to be greater than the start date and so if a user goes ahead and chooses a start date later than end date, the config wizard throws the error returned by the connector, instead of running the integration end to end. User can go back and correct the date order and proceed as usual.

Here's how you can achieve this with custom JS:

2 - Showing / hiding slots based on dependencies

Here's another example of this use case.

You can download the project from here and import to test this example end to end.

You want to send a slack notification for workflow success and failure to the end user's configurable slack channel.

The default option sends notification to the same channel but if user unselects the default check box, you could show a slot to configure the channel for error notification.

It is up to you to decide how you want to provide best user experience.