Managing API triggers

Creating an API trigger

1. In a folder, navigate to Automations > Triggers > API Triggers.
2. Click Add a new trigger. The Create a new API Trigger window is displayed.
3. From the Process Name drop-down menu, select an underlying process for your trigger.
4. The Name field is prepopulated with the process name, followed by the trigger type in the format <ProcessName>_<TriggerType>. However, the trigger name can be edited with a different name, if preferred.
5. From the Job Priority drop-down menu, select the priority of the job. The default value is Inherited, meaning that the job priority is the same as the one defined for the selected process.
6. From the Runtime type drop-down menu, select the runtime used to execute the jobs that are launched by the trigger.
7. On the Arguments tab, provide values for input arguments if your process has any. More details about input and output arguments.
8. From the Verb drop-down menu, select the option that depicts the action you want your job to take: DELETE, GET, POST, and PUT.
9. In the Slug field, enter a slug that will be appended to the base URL, thus generating the final URL for the resulting endpoint that you will use in your application. You can see a preview of the full URL under this field.
   The default slug is ${Process_Name}, but you can customize it so as to ensure its uniqueness at the tenant level.

   Note that it does not support slashes.

10. From the Default call mode drop-down menu, select the desired call mode. The available options are:

    • Async polling (this is the default, but it can be changed)

    • Async fire & forget

    • Sync (long-polling)

    Find out more about these options in Starting a job through an API trigger.

11. Turn on the Schedule ending of job execution toggle to select a job termination strategy.
    Note:

    • The amount of time specified here elapses according to the specifications, even if the job is queued. For example, if you schedule a job to run at 1 p.m. and set it to stop after 20 minutes, the job stops at 1:20 p.m. even if it had stayed in a queue until 1:15 p.m., and then started.
    • The Schedule ending of job execution options of a trigger are preserved for manually started jobs.

    For example, say you created the trigger T1 and you activated the following job ending schedules:

    • Schedule ending of job execution: Stop the job after 10 minutes

    • Schedule automatic "Kill", if the job does not stop: Kill the job after 2 minutes

      On the Automations > Triggers page, when you click Start a Job Now for the trigger T1, the Start Job page opens with the job ending schedules already applied, the same ones you configured when you created the trigger.

    Additionally, if you schedule to stop a Pending or Running job after 2 hours and also configure to kill the same job after 3 hours, the job will be killed after 5 hours. This happens because, first, the signal is sent to Orchestrator that the job was indeed stopped after 2 hours. Once the signal has been received, the kill job action is triggered to occur in 3 hours, thus resulting a total of 5 hours.

    • Select Stop from the drop-down - attempts to gracefully end the execution after the defined time interval has passed since the job is stuck in a Pending or Running state (set the time to a minimum of 1 minute, maximum of 10 days, 23 hours and 59 minutes);
      Example: Orchestrator will attempt to stop jobs that have been stuck for at least 10 minutes in Pending or Running.

      

    • Select Kill from the drop-down - attempts to forcefully end the execution after the defined time interval has passed since the job is stuck in a Pending or Running state (set the time to a minimum of 1 minute, maximum of 10 days, 23 hours and 59 minutes);

      Example: Orchestrator will attempt to kill jobs that have been stuck for at least 10 minutes in Pending or Running.

    • Select Stop from the drop-down and enable the If the job does not stop, kill it option - attempts to gracefully end the execution after the defined time interval has passed since the job is stuck in a Pending or Running state and then attempts to forcefully end it after the defined time interval has passed since the job is stuck in a Stopping state (set the time to a minimum of 1 minute, maximum of 10 days, 23 hours and 59 minutes).

      Example: Orchestrator will attempt to stop jobs that have been stuck in Pending or Running for at least 10 minutes. If the termination does not happen, Orchestrator will attempt killing those jobs that have been Stopping for at least 20 minutes.

12. Turn on the Schedule automatic trigger disabling toggle, and enter the date and time when the trigger is to be disabled. The selected time zone influences when the time trigger gets disabled.
13. Turn on the Generate an alert if the job is stuck (in pending or resumed status) toggle, and set the acceptable duration for the job to remain in the pending or resumed status. The minimum configurable duration is one minute. The maximum configurable duration is eleven days. If the job exceeds the configured duration, an "Error" severity alert pop-up informs you about it with the following text: "N jobs for #process {process_number} have been pending or resumed for more than X hours and Y minutes.", where:
    • N - is the number of jobs that triggered the alert;
    • {process_number} - the process identifier;
    • X - the configured number of hours the job exceeded while having the pending or resumed status; Days are converted to hours.
    • Y - the configured number of minutes the job exceeded while having the pending or resumed status.
14. Turn on the Generate an alert if the job started and has not completed toggle, and set the acceptable duration for the job to complete. The configurable duration is minimum one minute and maximum eleven days. If the job exceeds the configured duration, an "Error" severity alert pop-up informs you about it with the following text: "Job for #process {process_number} has been pending been running for more than X hours and Y minutes.", where:
    • {process_number} - the process identifier;
    • X - the configured number of hours the job exceeded while trying to complete; Days are converted to hours.
    • Y - the configured number of minutes the job exceeded while trying to complete.
15. Turn on the Set execution-based trigger disabling toggle if you would like to control when the trigger is disabled once a job fails. This toggle reveals two options:

    Option	Description
    Disable when consecutive job execution fail count	The trigger is disabled after the number of failed executions you choose for this setting. You can choose a value between 0 and 100. The default is 0, meaning that the trigger is never disabled. Stopped jobs are not counted towards this value.
    Grace period on disabling the trigger (days)	The number of days to wait before the trigger is disabled after the first failure of a job. You can choose a value between 0 and 30. The default is 0, meaning that the trigger is disabled as soon as the number of job executions set in the field above is reached for the current day.

    Note:

    If you choose a Cloud - Serverless runtime for the underlying process, the Set execution-based trigger disabling option is automatically enabled, with the following default values (the fields are read-only):

    • Disable when consecutive job execution fail count is set to 10.

    • Grace period on disabling the trigger (days) is set to 0.

    This only applies to you if you are on the Community licensing plan.

16. To keep the same account-machine context configured for starting the job, check the Keep Account/Machine allocation on job resumption box. This optimizes your license and resource usage.

Important:

• Tenant-level execution settings apply to API triggers.

• You can create a maximum of 1.000 API triggers per tenant.

Actions on API triggers

The API Triggers page allows you to perform several actions from the contextual menu of each trigger:

Copy full slug URL

Copy the URL to be used in the third-party application.

For an API trigger with the hw-process slug, it would look like this: https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/6ea73196-ca89-446c-81e1-5279bdd36dc2/hw-process

Edit

Change the properties of the selected API trigger.

Copy slug

Copy the slug in the appropriate format for use in the command line or in existing code. The available options are:

Copy as curl (bash) - for an API trigger with the hw-process slug, it would look like this:

curl '{baseURL_orchestrator}/t/6ea73196-ca89-446c-81e1-5279bdd36dc2/hw-process'  -X 'POST'  -H 'Content-Type: application/json'  -H 'Authorization: Bearer ***INSERT_YOUR_TOKEN***'

Copy as curl (cmd) - for an API trigger with the hw-process slug, it would look like this:

curl "https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/6ea73196-ca89-446c-81e1-5279bdd36dc2/hw-process" ^ -X "POST" ^ -H "Content-Type: application/json" ^ -H "Authorization: Bearer ***INSERT_YOUR_TOKEN***"

Copy as fetch - for an API trigger with the hw-process slug, it would look like this:

fetch("https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/6ea73196-ca89-446c-81e1-5279bdd36dc2/hw-process", { headers: { Authorization: "Bearer ***INSERT_YOUR_TOKEN***", "Content-Type": "application/json" }, "method": "POST" })

Copy as PowerShell - for an API trigger with the hw-process slug, it would look like this:

$headers = @{ "method"="POST" "Authorization" = "Bearer ***INSERT_YOUR_TOKEN***" } Invoke-WebRequest -UseBasicParsing -Uri "https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/6ea73196-ca89-446c-81e1-5279bdd36dc2/hw-process" ` -Headers $headers ` -ContentType "application/json"

Enable

Enable a previously disabled API trigger.

Disable

Disable an already enabled API trigger.

Remove

Remove the selected API trigger. Deleting an API trigger is equivalent to deleting the resulting endpoint. These are the behaviors that you can expect depending on your particular scenario:

Already started jobs

If a job based on a process associated to a deleted API trigger is already started at the time of deletion, it is carried out to completion.

Starting new jobs

Since the URL is no longer available, trying to start a job based on a process associated to a deleted API trigger results in a 404 error.

Editing processes

If you edit a process that is used by at least one API trigger, the trigger is refreshed and the new set of process properties are applied.

Cross-origin resource sharing

You can add domains to the allowlist for incoming traffic by using the CORS allow list for API triggers option on the General tab of your tenant settings.

This is required for browser applications that will make HTTP requests to Orchestrator from your browser (i.e. not from a server). Failing to allowlist domains could lead to a CORS policy error, which you can see in your developer console.

If you want to allowlist more domains, use a comma or press Enter to separate them.

API definition

This page displays a swagger definition of the API triggers you have created, grouped by folder, along with their output. In addition to that, it allows you to execute the jobs pertaining to those triggers.

It can be accessed by clicking the API definition button on the API Triggers page or via https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/swagger/index.html.

The API definition for a tenant with API triggers in a personal workspace and the Shared folder would look like this: