13.2 API Triggers: Starting Jobs from External Systems over HTTP

13.2 API Triggers: Starting Jobs from External Systems over HTTP

Core Concept: An API trigger wraps an existing process in a custom HTTP endpoint. An external application calls that URL to start a job and, depending on the call mode, receives the job's output arguments. API triggers are listed explicitly in the exam description.

---

Creating an API Trigger

In a folder, go to Automations > Triggers > API Triggers and select Add a new trigger. The form includes:

Further options match other triggers: Schedule ending of job execution (stop, kill, or stop then kill), Generate an alert if the job started and has not completed, and the Execution Target account. A tenant can have at most 1,000 API triggers.

The resulting endpoint has this form:

{AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/t/<INVOKE_URL>

---

Authentication and Permissions

• Calls are authorized with a personal access token in the bearer header, or with OAuth.
• Triggers permissions (View, Edit, Create, Delete) at folder level govern managing API triggers.
• Jobs Create is needed to invoke a trigger, and Jobs View to follow the job until its result is available.

---

Passing Input Arguments

• With POST or PUT, send a JSON body whose keys are the input argument names, for example {"argument1": 123, "argument2": "my string"}.
• With GET, place the parameters in the query string and omit the Content-Type header.
• The optional $callMode key overrides the default call mode for one call: AsyncRequestReply, FireAndForget, or LongPolling.

---

The Three Call Modes

1. Async polling (default)

1. The call creates the job and returns 202 Accepted with a status URI in the Location header.
2. The client polls the status URI.
3. When the job completes, the status call returns 303 See Other, redirecting to the output URI.
4. The client follows the output URI to read the job result: its output arguments, or the error.

2. Async fire & forget

The call creates the job and returns 200 OK without further information. Use it when the caller does not need the result, such as a nightly refresh started by a scheduler.

3. Sync (long-polling)

1. The call creates the job and blocks while the job runs.
2. If the job completes in time, the same response carries the output arguments.
3. If a timeout passes first, the response is 303 See Other to the status URI, which blocks again. This can repeat as a redirect loop until the job completes.
4. The maximum job duration for this mode is 15 minutes.

---

Designing the Process Behind an API Trigger

• Arguments are the contract. Keep input and output argument names stable, because callers depend on them. Output arguments are what the caller receives.
• Validate inputs early. Throw a clear exception when required arguments are missing, so the caller gets a meaningful error instead of a half-run job.
• Choose the runtime deliberately. Short background processes suit serverless robots, while UI automation needs a foreground-capable machine.
• Plan for concurrency. Each call creates a new job, so bursts of calls queue as Pending jobs until runtimes are free.

---

Worked Example

An intranet page lets employees check their remaining leave. The team:

1. Builds a background process GetLeaveBalance with input in_EmployeeId and output out_Balance.
2. Creates an API trigger with verb GET, slug leave-balance, and call mode Sync (long-polling).
3. The page calls the endpoint with ?in_EmployeeId=E1024, and the response contains out_Balance.

If the process sometimes needs more than a few seconds, the page switches to Async polling, shows a spinner, and follows the status URI until the 303 redirect provides the output URI.

---

API Triggers Versus Other Ways to Start Jobs