How the IFS Cloud OData API works
Projections, queries, ETags and actions, and where integrations go wrong.
The short answer
IFS Cloud exposes its data as OData projections, and each call has to get enumerations, ETags, defaults and actions right.
The query options you will use
Projections are OData services, each with its own entity sets. These options shape every read.
| Option | What it does | Watch for |
|---|---|---|
$select | Returns the fields you name | Ask for what you show |
$filter | Keeps the records that match | Use enum values, not labels |
$expand | Pulls in related records | Each expand adds weight |
$orderby, $top, $skip | Sorts and pages results | Page large sets |
$count | Counts the matches | Size a list first |
A read, then a safe update
One customer order projection, called as the signed-in user.
const ORDERS = 'https://ifs.example.com/main/ifsapplications'
+ '/projection/v1/CustomerOrderHandling.svc';
const quote = (v: string) => `'${v.replace(/'/g, "''")}'`;
// Orders for one site, read as the signed-in user.
// Each row carries its @odata.etag.
export async function ordersForSite(site: string, userToken: string) {
const filter = encodeURIComponent(`Contract eq ${quote(site)}`);
const url = `${ORDERS}/CustomerOrderSet?$filter=${filter}`
+ '&$select=OrderNo,CustomerNo,WantedDeliveryDate&$top=50';
const headers = { Authorization: `Bearer ${userToken}` };
const res = await fetch(url, { headers });
if (!res.ok) throw new Error(`IFS read failed: ${res.status}`);
return (await res.json()).value;
}
// Move a delivery date, unless someone changed the order
// after it was read.
export async function moveDelivery(
order: { OrderNo: string; '@odata.etag': string },
date: string,
userToken: string,
) {
const key = `OrderNo=${quote(order.OrderNo)}`;
const res = await fetch(`${ORDERS}/CustomerOrderSet(${key})`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${userToken}`,
'If-Match': order['@odata.etag'],
'Content-Type': 'application/json',
},
body: JSON.stringify({ WantedDeliveryDate: date }),
});
const changed = 'The order changed after it was read. Read it again.';
if (res.status === 412) throw new Error(changed);
if (!res.ok) throw new Error(`IFS update failed: ${res.status}`);
} - Line 1
The customer order projection, an official IFS Cloud OData service.
- Line 11
The user’s own token, so IFS applies their permissions.
- Line 29
The ETag from the read. If the order changed since, IFS answers 412 and nothing is overwritten.
Four details that break integrations
-
Enumerations
A filter needs the valid enum value. The label a user sees returns nothing, or the wrong records.
-
ETags
Send the record’s current ETag on every update or delete, or risk overwriting a newer change.
-
Defaults
Many entities expect server defaults before a create. Fetch them with the _Default() call.
-
Actions
Release, approve and cancel are bound actions. Call the action, so IFS runs its own logic.
Questions IFS teams ask
What is an IFS projection?
A projection is a published OData REST service over part of the IFS model: a set of entities, fields and actions made for one purpose. Integrations read and write through projections, not the database.
Why do IFS OData updates need an ETag?
IFS uses ETags for optimistic concurrency. Sending the current ETag with an update or delete means the write is refused if someone changed the record after you read it, instead of silently overwriting their change.
Should an integration call bound actions or update fields?
Call the action. Release, approve and cancel are operations with their own IFS logic, and the bound action is how a projection exposes them.
Why is IFS integration slow to build by hand?
Each new integration repeats the same digging: find the projection, read its spec, resolve enumerations and required fields, handle ETags and defaults, call the right action, then add sign-in and paging. NgageCode does that digging with 16 IFS Cloud tools, and a person reviews what it writes.
Describe the integration you need
One sentence is enough to start. We build the app with you on your IFS test environment.