Call REST services and map their responses

26R1 reference · Documentation-based tutorial draft · Not executed in IFS

Workflow learning center

Distinguish REST from an IFS API Task

An IFS REST Task sends an HTTP request. The target operation is outside the workflow’s database transaction. A later failure cannot roll it back, and Troubleshoot still sends the request.

Use a controlled development endpoint with fictional data. For an internal IFS API, prefer the supported IFS API Task where its contract and transaction behavior fit.

Worked pattern: look up delivery status

Suppose a test service returns:

{
  "handover": {
    "reference": "DEMO-HO-021",
    "status": "accepted",
    "receipt": "DEMO-RCPT-8"
  }
}

Configure the task with GET, a full HTTPS URL, and output mappings:

Output key	Path to value
deliveryStatus	$.handover.status
deliveryReceipt	$.handover.receipt

These paths describe the fictional response above. Test missing fields and changed response shapes rather than assuming every success response has the same structure.

Separate environment configuration

Create an appropriate entry on IFS REST Task Configurations. Free Text keys can parameterize endpoint or header content. An illustrative URL field is:

<<CONFIG:DEMO_HANDOVER_BASE>>/handover/status

Define that key in each environment. Do not place credentials in BPMN scripts, exported samples, or public worksheets.

The task supports None, Bearer Token, and OAuth 2.0 authentication. OAuth uses a configured client-credentials entry. “None” means the author is handling any authentication requirement; it does not imply the remote endpoint is public.

Request and response contract

Set the HTTP method, required headers, body format, and content type expected by the endpoint. Dynamic values inserted into JSON must be correctly escaped; string concatenation with arbitrary user text can produce invalid JSON.

The documented response types include JSON, XML, and plain text. Unsupported content types can fail parsing; a missing content type defaults toward JSON handling. For XML, the connector exposes a JSONPath representation with special single-item/list behavior—test zero, one, and multiple child elements.

A blocked-URL error can come from BPA_REST_TASK_BLOCK_URL_PATTERNS. Check the intended endpoint with the administrator instead of broadly removing network restrictions.

Writes require duplicate handling

Before changing GET to POST or PATCH, define what happens if the target succeeds but the response is lost. Use the target’s supported idempotency mechanism or a reconciliation process; there is no universal header that guarantees idempotency for every API.

Test timeout, denied authentication, rate limiting, invalid response, missing mapped field, and a failure after the external write. Confirm both workflow state and target-system state.

During ACP transfer, REST configuration shells are created but authentication details must be supplied in the target. See deployment.

Step-by-step: configure and verify a REST call

1. Establish a controlled response fixture

Use a development HTTPS service that returns the fictional handover JSON shown earlier. Verify it in Postman first and record the response Content-Type. A local server on your laptop is not reachable as localhost from the IFS workflow server; use an approved reachable test endpoint when configuring IFS.

For local client experiments, the REST lab server supplies a small status endpoint and a duplicate-aware test write. Run it with Node.js and read its startup URL. It binds only to localhost and stores lab records in memory; restarting it clears them.

2. Create the environment configuration

Open IFS REST Task Configurations and create a Free Text key DEMO_HANDOVER_BASE containing the approved service’s HTTPS base. If authentication is needed, add the matching Bearer Token or OAuth 2.0 Client Credential configuration and store the credential there.

Create a workflow with Start → IFS REST Call → Script Task → End. Select GET, set URL to <<CONFIG:DEMO_HANDOVER_BASE>>/handover/status, and map the response fields using the JSONPaths in the worked pattern above.

3. Inspect the variables and branch on missing data

Save a version and use Inspect with the controlled test endpoint. Check that deliveryStatus and deliveryReceipt are populated. Add a script that checks both are present before later tasks depend on them. Do not silently convert a missing receipt to a successful business outcome.

Test a response with the receipt removed, an empty body, invalid JSON, and an incorrect content type. Record whether the REST task rejects parsing or returns missing mapped values in your installed release.

4. Add a write with a stable reference

After the read works, create a separate lab workflow for the service’s documented POST operation. Use an input variable requestReference and a Script Task to prepare its JSON:

var reference = execution.getVariable('requestReference');
if (reference == null || !/^[A-Z0-9-]{1,40}$/.test(String(reference))) {
  throw new Error('Valid request reference required');
}
execution.setVariable('handoverBody', JSON.stringify({
  reference: String(reference), status: 'accepted'
}));

Set the REST task Request Body to the expression ${handoverBody} and Content-Type to application/json. Configure POST to the service’s proven write route and map its receipt. The lab server uses /handover for this operation, but your real API may use a different route/schema.

5. Test persistent effects and replay

Send one reference and inspect the remote record. Run the same reference twice; the lab service returns the same receipt for matching data and rejects conflicting reuse. This is an explicitly implemented contract, not a property of every REST service.

Then cause a later workflow failure after a successful remote write. Confirm the remote result remains. Do not assume IFS workflow rollback or Troubleshoot undoes the external operation.

6. Diagnose and clean up

For blocked destinations, have the administrator inspect the configured outbound rules and BPA_REST_TASK_BLOCK_URL_PATTERNS; do not remove broad protections. For auth failures, compare the selected Auth Config Name with the environment’s current credential. For empty outputs, compare the actual response structure and JSONPath.

Remove the lab trigger/workflow and unused REST configurations after testing. Stop the local server to discard its in-memory fixtures. Retain the exact request schema, output mappings, and actual failure behavior as the acceptance evidence for the installed release.

Release sources

• ifs rest call
• ifs rest task considerations
• workflow tooling

Plan outbound writes and authentication together

For a fictional partner dispatch acknowledgement, define a request reference, allowed destination, body schema, expected status/body, and reconciliation lookup before building a POST task. Treat credentials as environment configuration and business values as data. A caller-controlled URL must not be able to redirect a credentialed task to an arbitrary host.

Use the current dedicated REST Task documentation for supported authentication options; older examples that manually fetched or embedded tokens may describe earlier capabilities. Confirm token refresh, expiry, scope, and secret rotation in your environment. Redact Authorization values in task diagnostics.

A useful negative test sends an otherwise valid request with a deliberately invalid business reference. Another simulates a successful remote write followed by a lost response. These cases must take different recovery paths: correct a known business rejection, but reconcile an unknown outcome before replaying it.

For complete designs, follow workflow email, weather enrichment, or the AI assistant. Each is a distinct task built on this shared HTTP boundary.