Read and update data with IFS API Tasks
26R1 reference · Documentation-based tutorial draft · Not executed in IFS
Select the contract first
Section titled “Select the contract first”Use API Explorer to identify the supported API, entity set, keys, writable attributes, and action/function signature. Confirm that the intended execution user can use the operation.
An IFS API Task selects an Action and API Name. CRUD tasks also require an EntitySet Name and ETag Variable Name; CALL tasks require a Call Name. Use the designer’s metadata choices rather than constructing endpoint names from page labels.
Worked pattern: read one related record, then update it
Section titled “Worked pattern: read one related record, then update it”The fictional requirement is to add a note to one related handover record.
- Add a READ task for the actual target API and entity set.
- Filter by the complete business key. Select only the properties needed by the next steps where the tooling supports it.
- Decide whether absence should fail or follow an explicit alternate path.
- Store the record’s ETag using a variable distinct from the originating record’s ETag.
- Add the UPDATE task for the same target identity and use the ETag variable from that read.
- Map only the intended writable properties.
- Test concurrent modification between read and update.
Do not reuse a parent’s ETag for a child or a second record. The designer’s Override ETag option separates an API’s ETag from the default ETag; verify both tasks refer to the same target-specific variable.
For a bound action/function, the documented pattern first reads the relevant entity so the task has its binding/ETag context. Select the real call and follow its supported parameter contract.
Explicit payloads and errors
Section titled “Explicit payloads and errors”For CREATE, Only Explicit Parameters is selected by default. Keeping an explicit mapping helps prevent unrelated workflow variables from becoming payload fields.
Log Errors changes behavior: the exception is treated as handled and execution can continue. If enabled, add a decision checking the error variable before consuming results. An empty read caused by permissions is not automatically proof that a record should be created.
Upsert requires the documented preceding READ with Log Errors enabled. Establish which absence conditions you accept and how uniqueness is enforced before using it.
Collections and supported shapes
Section titled “Collections and supported shapes”READ returns a single record unless Read Collection is enabled. Give a collection its own variable and use a bounded sequential subprocess.
The 26R1 task-considerations reference documents ceilings of 10,000 records and 2,097,152 characters for a collection read. They are ceilings, not recommended batch sizes.
CALL input supports primitive values and enums; do not assume List or Structure inputs work. Returned structures have additional restrictions, including nested structures and Time attributes. Nested entity access is limited to the main entity plus one nested level.
For CLOB handling, the source pages differ: the general API page retains a blanket exclusion, while the more specific task-considerations page documents inline LONG_TEXT support with a 64,000-character ceiling. Treat CLOB use as requiring explicit target-version verification.
Transaction check
Section titled “Transaction check”APIs containing COMMIT, ROLLBACK, or SAVEPOINT are excluded from IFS API Tasks. Autonomous transaction blocks have separate behavior and can persist effects during troubleshooting. Replacing the task with REST changes the transaction boundary; it is not an equivalent fix.
Acceptance evidence: correct row, correct changed properties, unchanged unrelated rows, no-access behavior, stale-ETag behavior, and a deliberate missing-record outcome.