Creating Custom Actions

Syncari provides a set of standard actions but you may need one that isn't yet available. No problem! You can use the framework we have made available to create any number of Custom Actions you want.

See our short video on creating Custom Actions

Custom Actions allow you to extend your pipeline functionality by utilizing APIs to perform GET, POST, PUT and DELETE requests in external systems where you have REST API access.

There are multiple ways to use custom actions in your pipeline. For example, you can configure a custom action to validate an email address or phone number for a new lead using an external service.  

Prerequisites:

• Understand the external system API that will be used with the Custom Action
• Access to the end system's REST API (Custom Actions only support REST APIs) 
• Pipeline Basics

Create a new Custom Action

Log into Syncari, navigate to Sync Studio and double click any entity on the canvas.

Under the actions tab, select Action Studio and click Under the actions tab, select Action Studio and click Create Action.

The next steps will provide instructions for working in the Custom Action editor.

Step 1: Basic Settings

1. Enter a Display Name
2. Enter a Description
3. Enter an API name for the Custom Action
4. Enter Basic help text that will display when hovering a mouse pointer over the Custom Action help icon
5. Enter a Help link. This will be useful for linking to a separate help document for your Custom Action.  

Step 2: Action setup

Configure the API Endpoint

1. Select the HTTP Method for the API Request. In this example we select the POST method. 
2. Configure the Endpoint URL. The Endpoint URL may be configured with variables by placing the variable name in double curly brackets, {{variableName}}. See below for more details on variables.
   Example: https://api.company.com/record?email={{varEmail}}

Configure the Authentication

1. Click the Authentication tab
2. Select the Authentication type
   • API Key - The API Key will be passed in both the header (header name, X-API-KEY) and url parameter (parameter name, api_key)
   • OAuth with Client Credentials - Will retrieve an OAuth token by using the Client Credentials Flow.
   • Bearer Token - This option will allow you to set an Authentication Bearer token as the authentication. Use this for a static bearer token.
   • Synapse Credentials - If you are using the API of a connected Synapse, you can utilize the same credentials for your custom action requests.
3. Credential - The modal for entering credentials will differ based on the authentication type selected. 
   • API Key type
     • Click New Credential
     • Enter a Name for the API Key
     • Enter the API Key value
   • OAuth with Client Credentials type
     • Click New Credential
     • Enter a Name for the Client Credentials
     • Enter the Client ID
     • Enter the Client Secret
     • Enter the Endpoint for retrieving an OAuth token
   • Bearer Token Credentials type
     • Click New Credential
     • Enter a Name
     • Enter the Bearer Token
   • Synapse Credentials
     • Select the Synapse from the list

Configure the request headers

Select the Headers tab to add any request header key/values that are required for the API request. Click Add to enter additional header key/values.

Configure the request body

Enter the request body for the API request. The request body can be formatted by using the Twig Template language. Reference the Twig Template documentation.

Configure the variables

The Variables tab is where you to define the inputs for running your Custom Action. Variables can be referenced in the endpoint url, headers and body of the Custom Action configuration by setting the variable name in double curly brackets, {{variableName}}.

 Set the following properties when defining a variable:

• Name - This is the variable name that will be referenced when using the variable in the endpoint url, header or body of the custom action configuration.
• Display Name - This will display on the node configuration when using the custom action in your pipeline.
• Data Type - Set the data type for the variable. The available data types are boolean, date, datetime, double, integer, string, textarea, url and timestamp.
• Help Text - The help text will display when hovering over the variable when configuring the custom action node in your pipeline.
• Required - Set this to true or false.

Testing your configuration

The Testing tab will allow you to test your configuration by sending an API request to the endpoint. You will have the ability to provide variable values when running the test.

1. Click the Testing tab
2. Enter all necessary variable values
3. Click Run test

Running a test will allow you to inspect the request payload and response by clicking the Payload or Response tabs. 

Click Next to move on to the Review step.

Step 3: Review

The review step will give you a summary of your custom action configuration. Review all the settings and click Next to finalize your Custom Action or click Previous to go back and re-configure any settings. 

Click Next to move on to the Confirmation step.

Step 4: Confirmation

Click Finish to close the Custom Action configuration modal. The Custom Action configuration will be saved in a draft version until you publish.

Final Step: Publish the Draft

Congratulations! You've built your first custom action. There is one final step before you can use the Custom Action in your pipelines.

Publish the draft of your Custom Action by clicking the kebab Menu icon on the Custom Action and select Publish.

What's next?

• Working with Custom Action Responses