Start IFS Cloud workflows through a REST API

Explore this learning path

Documentation-based guide draft · Reviewed against sources on 2026-09-27 · Not executed in an IFS environment. IFS references use 26R1 unless stated otherwise. Confirm available APIs, components, and permissions in your installed release.

Start a small, side-effect-free IFS workflow through its REST interface and verify the resulting process instance. This is separate from attaching a workflow to a business projection action: a direct start needs its own workflow access grant.

Before you start

Use a development IFS environment with Workflow Designer access, an integration identity, and permission to grant external access to the specific workflow. The 26R1 extension documentation points to Camunda’s process-definition REST contract, but you must use the IFS-exposed REST base configured for your environment.

Ask the administrator for that base URL and verify it against API Explorer / CamundaRestInterface and the environment’s workflow configuration. Do not expose an internal engine administration port as a shortcut.

1. Create a workflow with no external side effects

Create a workflow with process key labApiGreeting. In the designer, connect Start → Script Task → End. Select JavaScript for the Script Task and use:

var reference = execution.getVariable('reference');
if (reference == null || !/^[A-Z0-9-]{1,40}$/.test(String(reference))) {
  throw new Error('A lab reference is required');
}
execution.setVariable('resultText', 'Accepted reference ' + String(reference));

Inspect it once with reference = LAB-API-017. The output variable should be Accepted reference LAB-API-017. Save, validate, and deploy the version. Keep this lab free of mail, REST writes, or business updates.

2. Grant external execution narrowly

In the relevant Permission Set, open the workflow-grant area and grant External Access to labApiGreeting for the intended integration user/role. Verify any required projection/business-function grants separately.

Do not assign broad workflow administration solely to make a test pass. The same identity should be able to start the approved process while being unable to delete or suspend unrelated definitions.

3. Confirm the deployed definition

Obtain an access token using authentication. In a private Postman collection, define workflow_base as the confirmed IFS workflow REST base and ifs_access_token as a local secret token.

Create a GET request to:

{{workflow_base}}/process-definition?key=labApiGreeting&latestVersion=true

Use Bearer Token authentication. Inspect the returned definition ID, key, and version. An empty result means the key/deployment/access combination is wrong; do not proceed with a guessed process key.

4. Start one instance

Create a POST request to:

{{workflow_base}}/process-definition/key/labApiGreeting/start

Set Content-Type: application/json and use:

{
  "businessKey": "LAB-API-017",
  "variables": {
    "reference": { "value": "LAB-API-017", "type": "String" }
  },
  "withVariablesInReturn": true
}

Send once. Save the returned instance ID, definition ID, business key, and variables. The synchronous, side-effect-free lab should return its expected result variable if the installed REST contract supports that response option.

A business key is a correlation value; it is not automatically a unique constraint or idempotency guarantee. Do not retry a start simply because a response was lost.

5. Verify completion and access behavior

Use the instance ID in the workflow administration/monitoring tools. Since this lab can finish immediately, it may not appear in the active-instance list. Check the appropriate execution/history view permitted by your environment rather than treating “not active” as “never started”.

Test missing reference, wrong variable type, expired token, and an identity without external access. Confirm that invalid input does not create a successful business result and denied callers cannot start the process.

6. Prepare recovery before adding business work

For a real process, record the incoming request reference in a durable system and define how you will find a prior instance after timeout. Use an atomic duplicate check/claim appropriate to the business operation; a preflight search alone can race with another caller.

If later tasks write externally, test their persistent effects separately. An exception later in the workflow does not undo a completed external REST write.

Remove the lab external grant and retire the deployed test process using supported administration actions once no instances need it. Preserve only sanitized request/response evidence with the installed release and deployment version.

REST contract reference: Camunda process-definition operations.

Sources and scope

Older IFS Applications examples are historical context, not evidence of Cloud compatibility. No third-party code, screenshots, or downloadable workflows are reproduced.