Item aliases (customer part numbers and nicknames)

An item alias is another name or code for an item, such as the part number a customer prints on their purchase orders or the word a retailer uses for a product, so that people can find and order the item by the name they know.

Aliases belong to the item master. You create them after the item (and, where it matters, its SKUs and lot types) exists. They are then used on document lines. When a sales order, delivery order or opportunity line is added with an alias, xMatix fills in the item, SKU and lot type from it and checks that the alias fits the document's customer and company. In the field app, the order line item picker and order capture find items through their aliases too.

Overview

Each item alias record holds:

• the alias itself, in Name, and an optional second code in Item Alias Code;
• the Item it stands for, optionally narrowed to one SKU and one Item Lot Type;
• optionally, the customer (Account) or company (Partner Account) it is reserved for. Leave both blank and the alias can be used on any document.

One item can have many aliases, for example one per customer who uses their own part numbers.

When to use it

Use item aliases when:

• a customer orders by their own part numbers. Create one alias per part number with the customer as the Account. Your field team can then find the item by that number, and it can't be used on another customer's order by mistake.
• retailers use a short or local name for a product. Create an alias with that name and no account, so anyone can find the item by it.
• a code always means a particular variant or grade. Set the SKU or Item Lot Type on the alias, so the line picks them up without anyone choosing them.

Do not use aliases for:

• substitute items. Use item alternates on the item's Related tab.
• barcodes and item codes. These belong on the item and SKU records themselves (see SKUs).

How xMatix handles it

On sales order, delivery order and opportunity lines. When a line is added with an Item Alias, xMatix:

1. checks the alias's scope against the document. If the alias has a Partner Account, the document's Partner Account must be the same. If it has an Account, the document's Account must be the same. Otherwise the line is refused.
2. checks the line against the alias. A line that already names a different Item or SKU from the alias is refused.
3. fills in what the line left empty: the Item, SKU and Item Lot Type come from the alias. A line that already has a different lot type keeps its own and is not refused.

This happens when the line is added: by hand, from the field app, by import or through the API. On sales order lines, the company check also runs on every later save, so changing an order line's alias on its record page to one reserved for a different company is refused with Item Alias is not valid. The account check and the fill-in do not run again on later saves.

On purchase order and invoice lines. These lines can carry an alias (the purchase order line New form has an Item Alias field, and the field app's invoice line form has one too), but nothing is checked or filled in. The alias is only recorded, so pick the Item as well.

In the field app.

• On a new order line, the Item picker ("Search by name, alias or SKU") also lists matching aliases under Aliases. Picking an alias fills in the line's Item, SKU, Item Lot Type and Item alias in one go. Picking an item directly clears an alias picked earlier.
• When the rep types or says the retailer's order on the order screen, the order is read against item names, SKUs and aliases. When the app is online, the order is read on the server. It uses every alias whose Account, Partner Account and rep are each either blank or the same as this order's, and it matches an alias you created on the web by its Item Alias Code, not by its Name. Offline, the app matches only aliases kept for that outlet or that rep.
• When the rep corrects a captured line by choosing the product by hand, the app tries to save the rep's words as a new alias for that rep and that outlet. These aliases are saved without a Name. In the shipped setup, a record with no name is refused (see Common problems).

Chat ordering. Where your organization uses the messaging ordering assistant, a customer's search also finds items whose alias name or code contains the search term, for aliases reserved for no account or for that customer.

What aliases don't do. Aliases don't change prices, tax or stock. A line priced, taxed and stocked by its Item, SKU and lot type behaves the same however that item was found. The printed document shows the line's item unless your document template is designed to show the alias.

Prerequisites

• The item exists, and so do the SKU and item lot type you want to fix on the alias. See Items, SKUs and Item lot types.
• For a customer- or company-specific alias, the account exists.
• Your security profile lets you create item aliases (see Permissions).

Procedure

Step 1 — Open the item aliases list

Item aliases are not in any shipped app. Open the App Launcher, search for Item Aliases, and choose it from the entity list. The All Item Alias view lists Name, Item, SKU, Item Lot Type, Created By, Created Date and Modified Date.

An administrator can add the list to an app so people don't have to search for it (see Configuration).

Step 2 — Create an alias

1. On the list, select New.
2. Fill in Name, the alias people will type or search for. It is required.
3. Optionally fill in Item Alias Code.
4. Choose the Item.
5. Optionally choose the SKU and the Item Lot Type the alias always means.
6. Save.

The record page opens with three panels: Item Information (Item, SKU, Item Lot Type), Applicability (PartnerAccount, Account) and System Information. The header shows the Name and Item Alias Code.

Step 3 — Reserve the alias for a customer or company

The New form has no Account or Partner Account fields, so you set the scope after the first save:

1. On the alias record page, go to the Applicability panel.
2. Select the pencil next to Account and choose the customer, or next to PartnerAccount and choose the company.
3. Save the field.

From then on, a new line that uses this alias on another customer's or another company's document is refused. Clear the field to make the alias available to everyone again.

Step 4 — Use an alias on a line

• Field app, new order line. In the Item field, type part of the alias. Pick it from the Aliases group. The line's item, SKU and lot type are filled in for you.
• Web, sales order line. The Item Alias field is on the order line's record page. Picking an alias there after the line was saved records it and checks the company scope, but it does not change the line's item or SKU.
• Purchase order line. The Item Alias field on the New line form records the alias only. Choose the Item as well.

Step 5 — Change or delete an alias

• Change. On the record page, select Edit to change the Name, Item Alias Code, Item, SKU or Item Lot Type in a dialog, or use the pencils next to each field.
• Delete. Select Delete on the record page, or Delete on the list row. Lines already saved keep their item, SKU and lot type. They were copied when the line was added.

Changing an alias's Item or SKU doesn't change lines that already used it. Only lines added afterwards follow the new values.

Fields

Business rules

• Scope is checked against the document, not the line. The Account and Partner Account checks read the line's parent order, delivery order or opportunity.
• Checks and fill-in run when a line is added. Sales order lines also re-check the company scope on every save (Item Alias is not valid.). Nothing else re-runs when a line or an alias changes later.
• Fill-in never overwrites. Item, SKU and lot type are copied only into empty line fields. A conflicting Item or SKU refuses the line; a conflicting lot type does not.
• Purchase order, invoice and service order lines. Purchase order and invoice lines store the alias without any check. Service order lines have no alias field.
• No numbering. Item aliases have no document numbering setting in the shipped setup, so every alias needs a typed Name.
• No uniqueness check. Two aliases can have the same name, even for the same customer. Keep names unique yourself so the picker shows one match.

Example

A distributor sells a 500 ml engine oil, item Engine Oil 500 ml, with two SKUs (single bottle and a case of 12). One workshop customer, Riverside Auto Works, always orders the case by its own part number RAW-OIL-12.

1. The inventory administrator opens Item Aliases from the App Launcher and selects New. They enter Name RAW-OIL-12, choose Item Engine Oil 500 ml and SKU Case of 12, and save.
2. On the alias record page, they set Account to Riverside Auto Works in the Applicability panel.
3. A sales rep visits the workshop and opens a new order line in the field app. They type RAW in the Item field and pick RAW-OIL-12 under Aliases. The line now shows the item, the Case of 12 SKU and the alias. The rep enters a quantity of 4 and saves.
4. The next week, the rep starts an order for a different workshop and picks the same alias by mistake. The line is refused with Selected Item Alias belongs to a different Account, Please verify. The rep picks the item directly instead.

Training

Practice exercise

In a sandbox:

1. Create an item alias named PRACTICE-ALIAS-1 for any active item that has SKUs, and choose one SKU.
2. On its record page, set Account to a test customer.
3. In the field app, start an order for that customer, add a line and pick the alias from the Aliases group in the Item field.
4. Start an order for a different customer and pick the same alias.

Expected result: in step 3 the line is filled with the item and SKU and saves. In step 4 the line is refused with Selected Item Alias belongs to a different Account, Please verify.

Quick reference

• Find aliases with App Launcher → Item Aliases; they are in no shipped app.
• Name is required; there is no automatic numbering.
• Account and Partner Account are set on the record page, not on the New form.
• Blank Account and Partner Account mean the alias is for everyone.
• New order, delivery order and opportunity lines take Item, SKU and lot type from the alias.
• A different Item or SKU on the line refuses it; a different lot type does not.
• Purchase order and invoice lines only record the alias.
• Editing an alias never changes lines already saved.

Permissions

Item aliases are governed by the ordinary entity access on the security profile (see Security profiles). In the shipped profiles, Standard User, System Admin, Sales, Sales Executive, Sales Manager and Service have full access (read, create, edit and delete) to Item Alias. A user without read access can't open the list or pick aliases on lines. A user without create access doesn't see New.

Item aliases have no server actions to grant. Clone exists on the entity but is not on the shipped record page.

Configuration

• Put the list in an app. Add Item Alias to an app such as Inventory or Sales through Setup → Design Studio → Apps and the app's Manage Items (see Create an entity for adding an entity to an app's navigation). Until then, users reach it from the App Launcher.
• Add Account and Partner Account to the New form. If you mostly create customer-specific aliases, add the two fields to the Item Alias create layout in the layout designer (see Design a form layout), so the scope is set in one step.
• Narrow the alias picker. No lookup filter is shipped on the line Item Alias fields, so pickers list every alias and the server refuses out-of-scope ones on save. To show only the document customer's aliases, add a lookup filter on the line's Item Alias field. The field app's Aliases search in the order line Item picker uses the same filter.
• Number aliases automatically. To let aliases be saved without a typed name (including the aliases the field app tries to learn from order capture), add a document numbering setting for Item Alias that writes the Name. Open it from Setup → Design Studio → Entities → Item Alias → Logic → Document Settings.
• Show the alias on documents. The standard document templates print the item. To print the customer's part number, add the line's Item Alias to your template.

Common problems

"Selected Item Alias belongs to a different Account, Please verify."

The alias is reserved for another customer than the document's Account. Pick an alias for this customer, pick the item directly, or clear the alias's Account if it should be available to everyone.

"Selected Item Alias belongs to a different Partner Account, Please verify." or "Item Alias is not valid."

The alias is reserved for a different company than the document's Partner Account. The first message appears when the line is added; the second appears when a saved sales order line is changed. Pick an alias for this company or clear the alias's Partner Account.

"Selected Item does not belong to selected Item Alias, Please verify."

The line already named an item, and it is not the alias's item. Clear the line's Item and pick the alias again, or pick the right alias.

"Selected SKU does not belong to selected Item Alias, Please verify."

The line already had a SKU that differs from the alias's SKU. Clear the SKU, or use an alias without a SKU.

"Name is required" when saving an alias

Item aliases are not numbered automatically, so type a Name. The same rule stops the field app from keeping the aliases it learns when a rep corrects a captured order. Add a numbering setting (see Configuration) if you want those to be kept.

I picked an alias on a purchase order line and the item stayed empty

Purchase order lines don't fill anything from the alias. Choose the Item (and SKU) on the line as well.

Common questions

Can one item have several aliases?

Yes. Create as many alias records as you need for the same item, for example one per customer part number, or a short name alongside a long one. Each alias can be scoped to its own customer or company, or left open to everyone. In the field app's Item picker, all matching aliases appear under Aliases, so give them names that are easy to tell apart. xMatix doesn't refuse duplicate names, so keep each name unique for the customers who will see it.

If I change an alias, do existing orders change?

No. When a line is added with an alias, xMatix copies the item, SKU and lot type onto the line at that moment. Changing the alias's item or SKU later, or deleting the alias, leaves those lines as they are. Only lines added after the change follow the new values. If existing open lines need the new item, change them on the lines themselves.

Does an alias give the customer a special price?

No. Prices, discounts and tax come from the line's item, SKU and lot type through your price lists and rules, whether the item was picked directly or through an alias. If a customer needs a different price, set it up in Price lists or Discount groups. An alias that fixes a lot type can still change the price, because price rules can read the lot type.

Related topics

• Items (the item master)
• SKUs (item variants)
• Item lot types
• Order lines
• Item Alias entity reference
• Item — entity reference