An item relation links a parent item to one related item, and the full set of relations for a parent is the list of items allowed with it. Today one process reads that list: a service order for an asset accepts only lines whose item is related to the asset's item.
You set up relations in the item master, after the parent item (usually the model of equipment you service) and the related parts and labour items exist. From then on, every service order raised for an asset of that model is checked against the list when its lines are saved.
Overview
Each item relation record holds one pair:
- the Item, which is the parent, for example a machine model that customers own as assets;
- the Related Item, which is an item that may be used with it, for example a filter, a belt or a labour item for that model.
A parent with ten allowed parts has ten item relation records, all with the same Item. Each record gets a name such as IR-13102026-000001 when it is saved.
The record also has SKU, Quantity, Price and Coordinates fields. You can record them, but no xMatix process reads them, so they are notes for your own reference.
When to use it
Use item relations when a service team should only fit parts and charge labour that belong to the equipment in front of them, so that a technician cannot add a part for a different model to a job card by mistake.
Do not use them for:
- substitute items. Use item alternates on the item's Related tab (see Items).
- package contents. Use item components (see Items, Step 6).
- sales orders, quotes or invoices. Item relations are not checked on any document other than the service order.
How xMatix handles it
When a service order line is saved, xMatix works out the parent item from the order itself: it takes the order's Asset and reads that asset's Item. It then looks up the item relations whose Item is that parent:
- No asset on the order, or an asset with no item. Nothing is checked.
- The parent has no item relations. Nothing is checked. The restriction is opt-in per parent item.
- The parent has item relations. The line's Item must be the Related Item of one of them. Otherwise the save is refused with "The selected item is not eligible or not mapped for this asset."
The check runs when a line is added and when a line's Item is changed. It applies to every line on the order, labour items as well as parts, however the line was added: by hand, by import, through the API or when an estimate is copied to a job card. Deleted relations do not count. Relations with no Related Item are ignored.
The check reads the asset's item at the moment the line is saved. Lines already on the order are not checked again when you change the order's asset, add relations or delete relations.
The Item picker on a service order line is not narrowed by item relations in the shipped setup. It lists every Work Item and Part item, and the check happens when you save.
Prerequisites
- The parent item and every item you want to allow exist in the item master. See Items.
- The assets you service carry the parent item in their Item field.
- Your security profile allows you to create item relations (see Permissions).
- Item relations can be reached in your apps. The shipped apps have no list for them, so an administrator may need to add one first (see Configuration).
Procedure
Step 1 — Open the Item Relations list
Open the app in which your administrator placed Item Relations, and select it in the navigation bar. The list opens in the All Item Relations view, with the columns Name, Item, Related Item and Quantity.
Step 2 — Add a related item
Select New. The Create Item Relations form asks for:
- Item. Pick the parent item, the model the asset is registered against. This field is required.
- SKU. Optional, for your reference.
- Related Item. Pick the part or labour item that is allowed with the parent. Leave it empty and the record has no effect.
- Quantity and Price. Optional, for your reference.
Save. The record gets its IR-… name and appears in the list. Repeat for each item you want to allow. Clone on an open record is a quick way to add the next one: it copies the record, and you then change the Related Item on the copy.
From now on, a service order for an asset of this model accepts only the related items you have listed.
Step 3 — Check or change a relation
Select a relation's Name to open it. The record page shows Item Details: Related Item, Quantity, Price and Coordinates, followed by System Information (who created and last changed it, and when). Select a field's pencil to change it in place. The page header offers Clone and Delete.
The parent Item is not on the record page, and the shipped list has no Edit row action. To move a relation to a different parent, delete it and create a new one.
Step 4 — Remove a related item
Open the relation and select Delete, or select Delete on its row in the list. The item stops being accepted on new service order lines for that model at once. Lines already on orders keep their item.
If you delete the last relation for a parent item, the restriction is lifted: its service orders accept any item again.
Step 5 — Add a line on a service order
Open the service order, go to the Lines tab and add a line as usual (see Service order lines). If the order's asset has a model with related items and the item you picked is not one of them, the save is refused with "The selected item is not eligible or not mapped for this asset." Pick a related item, or ask whoever maintains item relations to add the item.
Fields
The create form shows Item, SKU, Related Item, Quantity and Price, in that order. The record page shows Related Item, Quantity, Price and Coordinates.
| Field | What it means | Notes |
|---|---|---|
| Name | The relation's number, such as IR-13102026-000001. | Set automatically when the record is saved. |
| Item | The parent item, the model of the asset that service orders are raised for. | Required. Not shown on the record page, so it can't be changed after saving with the shipped forms. |
| SKU | A variant of the item, for your reference. | Optional. Not read by any process. |
| Related Item | The item allowed with the parent. | Optional on the form, but a relation without it has no effect. The picker lists all items. |
| Quantity | A quantity, for your reference, for example how many of the part a typical service uses. | Optional. Not read by any process, and not copied onto service order lines. |
| Price | A price, for your reference. | Optional. Not read by any process. Service order lines are priced from price lists, not from here. |
| Coordinates | Free text, for your reference, for example where the part sits on an exploded diagram. | Record page only. Not read by any process. |
The data model also has Item Lot Type, Label and External Id fields. No shipped form shows them and no process reads them. The full list is in the Item Relation reference.
Business rules
- Numbering. The name comes from the Item Relation Settings document-name setting: series IR, the date as DDMMYYYY, and a six-digit counter, joined by hyphens.
- Opt-in per parent. A parent item with no relations, or only relations without a Related Item, puts no limit on service orders.
- Parent comes from the asset. The parent is the Item of the service order's Asset, read when each line is saved, not a copy stored on the line.
- When the check runs. It runs when a service order line is added and when its Item is changed. Changing the order's asset, or the relations themselves, does not re-check existing lines.
- Every line counts. Labour (Work Item) lines are checked as well as parts. List the labour items for the model too, or they are refused.
- Duplicates are harmless. Nothing stops two relations with the same pair, and they are treated as one.
- Service orders only. No other document checks item relations.
Example
A workshop services two models of floor scrubber, FS-200 and FS-500. Both are items, and every customer machine is an asset whose Item is one of them.
The service manager creates four item relations with Item FS-200: the Related Item values are Brush Head 200, Squeegee Blade 200, Drive Belt 200 and Labour – Scrubber Service. Nothing is set up for FS-500.
A technician opens a job card for a customer's FS-200 asset and adds Squeegee Blade 500. The save is refused with "The selected item is not eligible or not mapped for this asset." They change the line to Squeegee Blade 200, and the line saves and is priced as usual.
On a job card for an FS-500 asset, any part or labour item can be added, because FS-500 has no relations yet.
Training
Practice exercise
In a sandbox:
- Pick an item that an existing asset uses as its Item, and note a part item that is not related to it.
- Create an item relation with that item as Item and a different part as Related Item.
- Open a service order for the asset and add a line with the part from step 1.
Expected result: the line is refused with "The selected item is not eligible or not mapped for this asset." Adding a line with the related part saves normally. Delete the relation from step 2, and the part from step 1 saves too.
Quick reference
- One relation is one parent item and one allowed related item.
- The parent is the item of the service order's asset.
- No relations for a parent means no limit.
- Labour items must be listed as well as parts.
- The check runs on save, and the line picker is not narrowed.
- Quantity, Price, SKU and Coordinates are for reference only.
- Existing lines are not re-checked when relations change.
Permissions
Item relations follow the entity permission for Item Relation in the user's security profile. The seeded Sales, Sales Executive, Sales Manager, Service, Standard User and System Admin profiles grant full access: view, create, edit and delete. Clone is a server action and is granted separately on the profile's actions. The seeded Sales Executive, Standard User and System Admin profiles have it.
Anyone who can edit item relations can change which parts service teams may use. If that should be one team's job, remove create, edit and delete from the other profiles. See Security profiles.
Configuration
| What | Where | Effect |
|---|---|---|
| A list for Item Relations | Setup → Design Studio → Apps, open an app, Manage Items | The shipped apps have no Item Relations entry. Add Item Relation to the app that your service or item-master team uses. See Create an entity. |
| A list on the item page | The Item entity's layout in Design Studio | Add a related list using the Item Relations relation (parent side) to show an item's allowed items on its own page. See Design a form layout. |
| Forms and list columns | The Item Relation entity's layouts and views | The create form has no Coordinates field and the record page has no Item field. Add them if your team maintains them, or activate the Edit list-row action so the parent can be changed. |
| Numbering | The Item Relation Settings document-name setting | Changes the IR series, date format, separator or counter length for new records. |
| Who may maintain relations | Security profiles, entity permission Item Relation | See Permissions. |
| Bulk loading | The Data Import wizard, entity Item Relation | Load many pairs at once. Include Item and Related Item on each row. See Importing data. |
Common problems
"The selected item is not eligible or not mapped for this asset."
The service order's asset has an item with related items, and the line's item is not one of them. Pick a related item. If the item should be allowed, add an item relation for the asset's item with this item as Related Item, then save the line again.
Labour lines are refused after we set up relations
The check covers every line, not only parts. Add relations for the labour items used on that model.
Service orders still accept any part
Check three things:
- the order has an Asset, and the asset has an Item;
- the relations use that item as Item, not as Related Item;
- each relation has a Related Item.
Lines saved before the relations existed are not re-checked.
I can't find Item Relations anywhere
The shipped apps have no entry for them. Ask an administrator to add Item Relation to an app (see Configuration).
Common questions
Do item relations change prices or quantities on the service order?
No. The Quantity and Price on a relation are for reference only. Nothing copies them onto service order lines, and no process reads them. A service order line is priced from the price lists and rules described in Service order lines, and you enter its quantity yourself. Use the two fields to record a typical quantity and a reference price for your team if that helps, but keep price lists as the place where prices are maintained.
Do item relations limit sales orders or invoices?
No. Only service order lines are checked, and only when the order has an asset whose item has relations. Quotes, sales orders, invoices, purchase documents and inventory documents accept any item that their own rules allow. If you need to stop a part being sold with the wrong product on those documents, item relations will not do it. Use price list rules, item groups or the document's own validations instead.
Why does the line picker still show items that will be refused?
The shipped setup narrows the service order line's Item picker only to Work Item and Part items. It does not filter by item relations, so a technician can pick an item that the save then refuses. The refusal names the problem, and changing the line's item to a related one fixes it. Keeping the relations list short and well named helps technicians find the right part first time.
What happens to open service orders when I change the relations?
Nothing changes on lines already saved. The check runs only when a line is added or its item is changed, so lines that were valid before stay on the order after you delete a relation. Lines that would now be refused also stay. New lines, and lines whose item you change, are checked against the relations as they are at that moment.