Creating a trigger

You can create a trigger as part of a custom-built connector. You can use custom connector triggers to automatically start automations or processes based on provider events.

How it works

Connector Builder triggers use resource polling to detect provider changes. Resource polling involves calling an API resource on a regular interval to detect when new events are returned.

Once a custom connector is published and the trigger is used in a published automation, the defined URL is used as the polling resource to pull back events and start an automation flow.

Detecting new events

The trigger’s polling URL must include query parameters to filter the provider’s results.

Polling occurs at a scheduled interval (every 5, 10, 15 minutes, etc.). Therefore, one of the provider's query parameters must be a date for filtering results. This way, the polling engine can populate the query parameter value to only include events that occurred since the last polling time.

Limitations

• You can create one trigger per resource. If more than one use case is needed, use a more general polling URL and set up response filter fields that can meet multiple use cases.

• Provider APIs must allow date-based query parameter filtering. If no date-based query parameters are available from the provider, it should not be used as a trigger.

Prerequisites

Provider requirements

The provider's API must offer a resource with a GET endpoint that returns a list of objects. Additionally, the endpoint must allow you to query the resource based on a date parameter.

Example of a valid resource

Pipedrive offers a Get all activities endpoint, which returns a collection of activities. This endpoint includes a since query parameter that filters the results by all activities with an update_time date greater than the since date provided as a value to the query parameter. You can use the since parameter as part of the polling URL to detect any updates to Pipedrive activities. The UiPath polling engine automatically populates this date field to capture events.

Connector requirements

Connector Builder triggers use resources that are already available on the connector as the polling URL. When creating a new trigger, there must be an existing resource on the connector side for the trigger to be associated with.

Triggers use the resource's configuration, so it is important that the existing resource already has:

• Query parameters: triggers can import existing query parameters, so the resource should already have some parameters configured before creating the trigger.

• Response fields: triggers output the response object of the associated resource, as well as allow for activity configuration based on these fields. It's necessary to generate the response fields for the resource by successfully calling the endpoint.

Creating a custom trigger

To create a trigger in Connector Builder, take the following steps:

Add a trigger

1. First, make sure you meet the prerequisites.
2. In Integration Service, open Connector Builder, then select your custom connector.
3. Select the More options menu next to Triggers.
4. Select Add trigger.

Set the name and resource

The Create event pop-up window is displayed. Here you can select which type of event to create. Currently, Polling is the only available option.

1. Select the event type.
2. Add a name for your trigger.
3. Select the resource used for detecting these events.
4. Select Create to start the process of configuring your trigger.

Configure the trigger

The process of creating a trigger consists of three steps:

1. Configure request.
2. Configure response.
3. Configure trigger filters.

These steps correspond to the process of polling a resource URL and working with the response.

Tip: Use the Test trigger functionality throughout the trigger configuration process to ensure that it is working as expected.

Configure request

First, you configure how the polling URL is set up, and how the trigger is displayed in Studio when used in an automation.

The preview layout represents how the trigger is displayed in Studio. You can configure the parameters and response fields to change what fields you see and use in Studio when setting up the trigger for an automation.

Polling URL

The polling URL is displayed at the top of the configuration page. This is the URL used to make requests to the provider to detect new events.

This URL must be configured in a way that filters for events of interest. The polling URL uses a date parameter to filter for new events since the last polling request. It's mandatory to include a date parameter that the polling engine can populate.

Import parameters

Triggers can import resource parameters to use in the polling URL.

If a parameter isn't available in the resource, navigate to the resource and add it, then return to the trigger configuration window to import it.

1. Select Import parameters to view the list of available parameters for a specific resource.
2. Select the parameter you want to use in the polling URL.
3. Once a parameter is added, it's included in the URL preview at the top of the page.

You can mark imported parameters as Required, so that they show up on the trigger canvas. This means you are required to enter a value for the query parameter when using the trigger in an automation.

Important: At least one date-based query parameter is needed for the polling URL. A date-based query parameter is any parameter with a DateTime format. DateTime formats can be found for a parameter with a String or Integer provider data type.

Unless a specific date value is specified, date-based query parameters are automatically populated with a value equal to that of the date and time of the previous polling request.

Test trigger

Use the Test trigger option to make sure that the expected results are being returned.

When you select Test trigger, the Try the request window is displayed, showing:

• Look-back period: this field defines what date should be inserted into the date-based query parameters and replicates the behavior of our polling engine, which automatically fills in this value based on the date of the last polling request.
• The query parameters specified as required.

Select Try request to open the Events Debug panel and see the request trace with a step-by-step breakdown of the request process. The number of results returned is also displayed.

Note: Check that the number of results returned is the number of results expected. The improper usage of query parameters can result in a high level of output objects and unnecessary robot usage once the connector is published and the trigger is used in a workflow.

It is recommended to have response expectations (number of events, types of events, etc.) when testing a trigger to check that the query parameter filters work as expected.

Configure response

At this step, you specify which response field corresponds to the Primary key, or the trigger's output.

1. Use the drop-down list under Primary key to select a field.
2. The selected field is added to the trigger preview, under Output. You can use this output in later steps of your workflow.

The Configure response step also provides a view of the response object associated with the polling resource for review.

Configure trigger filters

Once you configure the request and response, you can further configure the trigger using filters.

You configure event filtering by setting specific values for response fields. These values are specified during the automation setup (in Studio), but the trigger designer also allows you to configure what fields are displayed for filtering.

Hydration

If the resource used as the polling URL doesn't return the entire object needed for the trigger output, it is possible to hydrate the response using a GETBYID endpoint. This process is known as hydration.

Select the Hydration tab, activate the Use hydration toggle button, and specify the endpoint to be used for hydration, and the ID used to query for the object.

Note: The list of possible hydration resources is pulled from the Get records list on the left-side navigation panel. Configure the GETBYID resource before using it as a hydration resource for a trigger.

Using hydration replaces the response fields from the polling response resource fields with the hydrated resource response fields. Then, the hydration response fields become the only fields available for trigger parameters and filters configuration.

Filters

The trigger configuration process offers three options for displaying fields used for filtering. These fields are pulled from the resource response fields of the polling resource or the hydration resource. These options are available under the Show as column of the Filter parameters table:

• Hidden: the field is hidden from the canvas and is not available in Filter builder. If all fields are marked as Hidden, then the Filter builder is also hidden.

• Optional: at design time, the field is displayed as an option in the Filter builder.

• Required: at design time, the field is displayed directly on the trigger canvas and requires user input. Only events with a response field value matching the provided value result in an automation event.

Save the trigger

After you finish configuring the filter, select the Save button. Once saved, the trigger will be included as an event when the connector is published.

Using the trigger

Once a trigger is saved and it is no longer in draft mode, the trigger is available to use as soon as you publish your custom connector.