Packages and item components

An item component is one entry in the contents of a package item: it names the component item, how many of it go into the package, and whether it is always included, included by default or optional. When someone adds the package to an order, invoice, quote, opportunity, purchase order or requisition, xMatix reads these components and adds a line for each one under the package line.

You set up components on the package item in the item master, after the package item and its component items exist. From then on, every document line for the package follows them. The configurator on the document lets the user add or remove optional components; see Product configurator and demos.

Overview

A package is an ordinary item with Package switched on under Behaviour. Its contents are a list of item component records, one per component, on the item's Related tab. Each component record holds:

• the Item it belongs to (the package);
• the Component Item and, if needed, a Component SKU that goes on the added line;
• the Quantity per package, with an optional Min Quantity and Max Quantity for the added line;
• switches that decide whether it is added automatically (Is Mandatory, Is Selected), how it is priced (Is Bundled) and whether its quantity can change (Is Quantity Editable);
• filters that limit where it applies: Item SKU, Applicable For, Partner Account and Partner Account Group.

Each component record gets a number from the IPPN series when it is saved. Components are not in an app or menu of their own; you reach them through the package item.

When to use it

Use components when one product is sold or bought as a set: a machine with its standard accessories, a kit of parts, or a product whose customer chooses some extras. If you only need a list of items allowed with a model for service work, use Item relations instead. Item relations don't add any lines.

How xMatix handles it

When a line for a package item is saved, xMatix adds one line under it for each component that passes all of these tests:

1. Feature Type is Product Configurator. A component with an empty Feature Type is stored but never added and never offered in the configurator.
2. Is Mandatory or Is Selected is on. Optional components (both off) are left for the configurator.
3. Item SKU is empty, or matches the SKU on the package line.
4. Applicable For is empty, or matches the document: Sale for orders, invoices and quotes; Purchase for purchase orders and requisitions; Service for opportunities.
5. Partner Account is empty, or is the document's Partner Account; and Partner Account Group is empty, or the document's Partner Account is a member of that group.

Components are added in Sort Order. Each added line takes the Component Item and Component SKU, points to the package line (for example through Package Opportunity Line or Package Quote Line), and records the component in its Item Component field. On order, invoice, quote and opportunity lines, Is Bundled becomes the line's Price Bundled flag. Purchase order and requisition lines don't get this flag.

The added line's quantity depends on Package Type:

• Multiple Of Package — the component Quantity times the package line's quantity. When the package line's quantity changes, these lines are recalculated.
• Independent Of Package, or empty — the component Quantity as it is, whatever the package quantity. Changing the package quantity leaves these lines alone.

What happens to the package line later:

• Item changed — the old package's component lines are removed and the new item's components are added. Invoice lines don't allow the item to change, and neither do order lines that are packages or components.
• Deleted — its component lines are deleted with it.
• Copied to another document — when a document is created from another, for example an order from a quote or a purchase order from a requisition, the component lines copied with it are kept under their package line and no second set is added. An invoice line raised from an order line never adds components of its own.

Components are read when lines are added or changed. Editing a component record later doesn't change lines that already exist, except that a later quantity change on a package line uses the component's current Quantity.

Delivery orders, service orders, goods receipts, bills, transfers and adjustments never add component lines.

Prerequisites

• The package item and every component item exist and are active.
• If you use a Component SKU, it is a SKU of the component item. The SKU picker only lists the component item's SKUs.
• You can create and edit item components under your security profile.

Procedure

Step 1 — Mark the item as a package

Open the item and switch Package on. It is in the Behaviour section of the record page, and on the Behavior tab of the item form. Save. Only items with Package on add component lines. See Items.

Step 2 — Add a component

On the item's Related tab, find the item components list and choose New. The form has four tabs. Item is already filled with the package.

1. Above the tabs, set Feature Type to Product Configurator. Without it the component is never used. Leave Item SKU empty unless the component belongs to one SKU of the package only. Set Sort Order to place it in the list.
2. Components tab — choose the Component Item, and the Component SKU if the component has variants. Choose a Package Type.
3. Quantity tab — enter the Quantity per package. It must be above zero. Enter Min Quantity and Max Quantity if users may change the quantity on the document but only within limits, and switch Is Quantity Editable on if they may change it at all.
4. Behaviour tab — switch on Is Mandatory for a component that must always be there, or Is Selected for an optional component that is added by default. Switch on Is Bundled when the component's price is included in the package price. Applicable For is described under Configuration.
5. Partners Applicable tab — leave both fields empty unless the component applies to one company (Partner Account) or to the companies in an account group (Partner Account Group).

Save. The component appears in the item's list with its number.

Step 3 — Group optional components (optional)

Open a component from the list. Under Information, set Product Packages to an option group of the item, for example Accessories. The configurator shows components grouped under these names. The field is only on the component's record page, not on the New form. Option groups are item feature records; see Item features (option groups) for how to create them.

Step 4 — Check the result on a document

Add the package item to a quote or order and save the line. The mandatory and selected components appear as lines under it. Open the configurator on the document to see the optional components as well; see Product configurator and demos.

Step 5 — Change or remove a component

Use the row's Edit on the item's list, or open the component and choose Edit in its header. Fields on the record page can also be edited in place. Choose Delete to remove a component. Changes apply to lines added from then on.

Fields

Header (above the tabs)

Components

Quantity

Behaviour

Partners Applicable

The record also has an Item Lot Type field, which no form shows and no process reads.

Business rules

• Only Product Configurator components count. Adding component lines and the configurator both ignore every other Feature Type value.
• Component lines are checked when they change. On order, invoice, quote, opportunity, purchase order and requisition lines, changing a component line's quantity is refused when:
  • it is below Min Quantity: Quantity cannot be less than … for this component.;
  • it is above Max Quantity: Quantity cannot exceed … for this component.;
  • the component is mandatory and the quantity is 0: Quantity must be greater than zero for mandatory component.;
  • Is Quantity Editable is off: Quantity cannot be changed for this component.
• Mandatory components stay. Deleting a mandatory component line on its own is refused with Mandatory package component cannot be removed. Deleting the package line, or changing its item, removes it.
• Bundled lines carry no price. An order line with Price Bundled and a unit price above zero is refused (This is a bundled item. You can not specify price for it). On an invoice line the message is Unit Price should be zero for bundled items. Quote and opportunity lines have no such check, but the price list doesn't price them.
• Only Sold In Package on a component's own item is checked on invoice lines only: an invoice line for that item must belong to a package (Item can only be sold as part of a package.).
• Item and SKU are locked on order lines that are packages or components (Key fields are not editable once the related objects are added.).
• The component record itself has no other checks. A wrong Package Type or a Max below Min is saved as it is.

Example

A workshop supplier sells a Service Starter Kit package. The item has Package on and four components, all with Feature Type Product Configurator:

A sales user adds 3 Service Starter Kits to a quote and saves. xMatix adds three lines under it: Tool Trolley 1, Socket Set 3 and Hand Cleaner 6. The trolley and socket set are Price Bundled, so they carry no price; the hand cleaner is priced from the price list. Spare Gloves is not added.

The customer wants gloves, so the user opens the configurator, ticks Spare Gloves and applies: a line for 15 is added. The user then changes the kit quantity to 4. Socket Set becomes 4, Hand Cleaner 8 and Spare Gloves 20; the trolley stays at 1. Trying to delete the Socket Set line on its own is refused, because it is mandatory.

Training

Practice exercise

In a sandbox, create items Practice Kit, Part A and Part B. Switch Package on for Practice Kit. Add two components: Part A with Quantity 2, Multiple Of Package, Is Mandatory; Part B with Quantity 1, Independent Of Package, Is Selected, both with Feature Type Product Configurator. Add Practice Kit with quantity 5 to a new order and save the line.

Expected result: two lines under the kit, Part A 10 and Part B 1. Change the kit to 2: Part A becomes 4, Part B stays 1. Deleting the Part A line on its own gives Mandatory package component cannot be removed. Now clear Part B's Feature Type and add another kit line: only Part A is added.

Quick reference

• Package on the item, components on its Related tab.
• Feature Type must be Product Configurator, or the component does nothing.
• Mandatory or Selected components are added automatically; the rest wait for the configurator.
• Multiple Of Package scales with the package quantity; Independent Of Package doesn't.
• Quantity must be above 0; Min and Max of 0 mean no limit.
• Is Bundled means no price on the component line.
• Empty filters (Item SKU, Applicable For, Partner Account, Partner Account Group) mean "applies everywhere".
• Editing a component doesn't change lines that already exist.

Permissions

Viewing, creating, editing and deleting item components follow your security profile's access to the Item Component entity. In the shipped profiles, Clone is granted to Standard User, Sales Executive and System Admin. Without access to item components, the list on the item's Related tab is empty or read-only.

Lines are added from components whatever the user's access to item components. Choosing optional components on a document needs the configurator actions on that document; see Product configurator and demos. Access is set under Security profiles.

Configuration

• Package flag — Package on the item's Behaviour tab makes that item add component lines. Only Sold In Package on a component item stops it being invoiced on its own.
• Applicable For values — the field's three values, Sale, Purchase and Service, are shipped inactive, so the list offers nothing and every component applies everywhere. To use it, open Setup → Design Studio → Entities, choose Item Component, open the Applicable For field's row menu, choose Manage PickList Values and activate the values. Keep their stored values exactly as shipped. Opportunities use Service, not Sale, so a component marked Sale is not added on an opportunity, though it is on the quote and order. See Create an entity.
• Feature Type values — only Product Configurator has any effect. Adding other values creates components that are never used.
• Numbering — component numbers come from the item component document name setting (series IPPN), under the entity's Logic → Document Settings in Design Studio.
• Forms — the New form and record page can be changed in the layout designer; see Design a form layout. The Product Packages group is only on the record page as shipped.

Common problems

I added a package line but no component lines appeared

Check, in order: the item has Package on; each component has Feature Type Product Configurator; the component is Is Mandatory or Is Selected; its Item SKU is empty or matches the line's SKU; its Applicable For, Partner Account and Partner Account Group fit the document. An invoice line raised from an order line never adds components; they come from the order.

The configurator shows "No components for this product"

None of the item's components passes the Feature Type, SKU, Applicable For and partner tests for this document. The configurator lists optional components too, so the cause is one of those filters, not the Mandatory or Selected switches.

"Quantity cannot be 0 or negative." when I save a component

Quantity starts at 0. Enter the quantity per package, above zero.

"Quantity cannot be changed for this component."

Is Quantity Editable is off on the component. Change the package line's quantity instead (components of type Multiple Of Package follow it), or ask an administrator to switch the setting on.

"Mandatory package component cannot be removed."

The component is mandatory. Delete the package line to remove all its components, or have the component's Is Mandatory switched off for future documents.

"This is a bundled item. You can not specify price for it"

The line is a bundled component. Clear its unit price, or have Is Bundled switched off on the component if it should be charged separately.

I changed a component but my existing quote still shows the old contents

Components are read when a line is added. Delete the package line and add it again, or use the configurator, to pick up the new contents.

Common questions

Do components reserve or move stock?

Not by themselves. The component lines are ordinary document lines, so they behave like any other line of their document. The package line stays on the document too, and what it does with stock depends on the package item's own settings, such as Track Inventory. See Items.

Can a component be a package itself?

Its lines are added with the component item, but a component line never adds components of its own: only lines that are not already under a package add components. Put all the parts on the top-level package instead.

What do Standard Package and Optional Package mean?

The field reference lists them as Feature Type values, but they are not shipped as choices and xMatix acts only on Product Configurator. Use Is Mandatory for standard contents and leave both switches off for optional ones.

Does the mobile app handle packages?

Yes. The mobile app doesn't add component lines itself; the same server rules add them when its lines are saved. The mobile configurator offers the optional components. On mobile, a component is chosen by giving it a quantity above zero.

Related topics

• Items — the package flag and the item's Related tab.
• Product configurator and demos — choosing optional components on a document.
• Order lines, Quote lines and Opportunity lines — how package lines behave on each document.
• SKUs (item variants) and Item relations.
• Item Component field reference.
• Item — entity reference