Item groups

An item group is a named set of items that other records can name in one step. Instead of listing every product on a trade scheme, a discount rule, a tax rule or an incentive target, you name the group, and xMatix checks whether the item on the line belongs to it. You set groups up in the Sales or Procurement settings, keep their members current, and then pick them on the records they scope.

Overview

A group has three parts, each on its own tab of the group's record page:

• Rules: conditions on item fields (for example Item Family equals Coolers) that can build the member list for you.
• Members: the items that belong to the group. This is the list every feature actually reads.
• Details: the group's name, type, description and how its rules combine.

Members come from two sources, and one group can use both. You can add items by hand on the Members tab, or you can let Process Members add every item that matches the rules. A rule-built list does not update itself. It changes only when someone runs Process Members again.

The Item Group Type matters to two features only. Trade schemes look only at Scheme groups, and discount group rules look only at Discount groups. Every other feature that accepts an item group ignores the type.

When to use it

Use an item group when the same treatment applies to many items and you expect the list to change:

• a brand or category that a trade scheme rewards or excludes (Scheme group on the scheme condition or benefit);
• a range that gets a contract discount (Discount group on a discount group rule);
• items that share a tax treatment (a group on a tax group rule);
• a product line an incentive target measures, a set of items a cycle count covers, or the items a sales executive may sell (selling scope).

If only one item is involved, name the item directly on the record instead.

How xMatix handles it

When a feature checks a group, it looks for a member row that links the line's item to the group. Membership is read when the document is priced, taxed, checked for schemes or counted, so changes to a group affect documents processed after the change, not documents already saved.

Features differ in what they check on the member row:

"Skipped" means a member whose Is Active is switched off is ignored. A member whose Is Active is empty still counts there. Members you add by hand have an empty Is Active, because the standard member form does not show the field.

Some records have an Item Group field that nothing reads: GL accounts, KPI configurations, visit plans, visit routes and posting definitions. An inventory valuation policy scoped to an item group never matches at posting time (see inventory valuation).

Process Members rebuilds the rule-based part of the list:

1. It reads the group's conditions in their order on the Rules tab.
2. It finds every item that satisfies them, combined according to Rule Success Criteria.
3. It adds one member for each of those items, with Is Active switched on and no SKU or lot type.
4. It removes the members that the previous Process Members run created.

Members you added by hand are never removed by a run. If an item is both added by hand and matched by the rules, it appears twice. That does no harm to matching, but it is untidy.

Prerequisites

• Access to the Settings entry of the Sales app or the Procurement app, and permission to create item groups.
• For a rule-based group, an administrator has added the Rule Success Criteria values (see Configuration). Without them the criteria stays empty, and Process Members adds every item.
• The item fields your rules test are filled in on the items. A condition on an empty field matches nothing.

Procedure

Step 1 — Open the item group list

In the Sales app, select Settings, then Item Group. The same list is also in the Procurement app's Settings. The list shows each group's Name, Item Group Type, Dynamic Member Type and Rule Success Criteria, with created and modified details. The view switcher offers All Item Groups (the default), All Discount Item Groups, All Scheme Item Groups and All Tax Item Groups.

Step 2 — Create the group

1. Select New.
2. Enter a Name and choose the Item Group Type: Complaint, Tax, Discount or Scheme.
3. Add a Description that says which items belong in the group.
4. To build members from rules, choose a Rule Success Criteria under Field Filter Criteria. For a group you fill by hand, leave it empty.
5. Save.

The group's record page opens on the Rules tab.

Step 3 — Add members by hand

1. Open the Members tab and select New.
2. Pick the Item. To limit the membership to one variant or grade, also pick a SKU (the list shows only that item's SKUs) or an Item Lot Type.
3. Save. The item appears in the members list.

Repeat for each item. To take an item out of the group, select Delete on its row. Only trade schemes read a member's SKU and Item Lot Type; incentive targets read the SKU. Every other feature matches the item whatever SKU or lot type the member names.

Step 4 — Define membership rules

1. Open the Rules tab and select Add condition.
2. In the new row choose the Field (any visible item field, including custom fields), the operator and the value. The operators offered depend on the field. Lookups offer Equals, Not equal, In list and Not in list. Numbers and dates also offer the less-than and greater-than comparisons. Text also offers Contains.
3. Add more conditions as needed. Drag a row by its handle to change the order.
4. Select Save under the conditions. You see Membership rules saved.

Saving the rules does not change the members. The rules are applied only when you run Process Members, in the next step.

Step 5 — Build the members

On the group's record page, select ProcessMembers in the page header. You see the message Action Executed. That message means the rebuild has been queued, not that it has finished. It runs in the background. Open the Members tab and refresh it after a short while to see the result.

Run ProcessMembers again whenever you change the rules, or when items change in ways the rules test, such as a new product being added. Nothing reruns it for you.

Step 6 — Use the group

Open the record you want to scope and pick the group in its item group field. Use a Scheme group on trade scheme conditions and benefits, and a Discount group on discount group rules. For the other features in the table under How xMatix handles it, any type works. The lookups list every group whatever its type, so check the type before you pick.

Step 7 — Change or remove a group

Edit the fields on the Details tab, or select Edit in the page header. To retire a group, first remove it from the schemes, rules, targets and mappings that name it, then select Delete. Clone copies the group's details only, not its rules or members.

Fields

Item group

The Details tab also shows Created By, Created Date, Modified By and Modified Date. The page header shows Item Group Type and Rule Success Criteria as summary figures.

Member

Condition (Rules tab)

Business rules

• No conditions, or no criteria, means every item. If Process Members runs on a group with no conditions, an empty Rule Success Criteria or Always (No Criteria), every item becomes a member.
• Criteria values. Any Rule Is Met adds an item that satisfies at least one condition. All Rules Are Met requires every condition. Custom Logic Is Met uses Rule Success Custom Logic. Any other value is treated as All Rules Are Met.
• Inactive items are not skipped. The rebuild tests only your conditions. To keep inactive items out, add the condition Active Equals true.
• No member checks. Adding a member by hand does not check that the item is active or that a required SKU is filled in.
• A run replaces the previous run. Members created by the last run are removed; members added by hand stay.
• Type must match exactly for trade schemes and discount group rules. The type is compared as stored text.
• No automatic rebuild. Editing rules, items or the group never changes members until Process Members runs.

Example

Your company sells about 400 products. A summer scheme rewards outlets that buy the cooling range.

1. You create the group Cooling range, type Scheme, Rule Success Criteria Any Rule Is Met.
2. On Rules, you add two conditions, Item Family Equals Air Coolers and Item Family Equals Fans, and save.
3. You select ProcessMembers. A minute later the Members tab lists the 28 matching items.
4. You add one accessory by hand on Members.
5. On the scheme condition, you set Item Group to Cooling range.
6. An order with a fan and the accessory counts both towards the scheme. An order with only a refrigerator does not.
7. Next month two new fans are created. You run ProcessMembers again: the 28 rule-built members are replaced by a fresh set of 30, and your hand-added accessory stays.

Training

Practice exercise

In a sandbox where the Rule Success Criteria values have been added:

1. Create an item group Training – Discount range, type Discount, Rule Success Criteria Any Rule Is Met.
2. Add a condition on an item field that a few items share, save the rules, and run ProcessMembers.
3. Add one other item by hand on Members.
4. Change the condition to a different value, save, and run ProcessMembers again.

Expected result: after step 2 the members are the matching items. After step 4 they are the items matching the new value plus the one item you added by hand. The first set is gone.

Quick reference

• The Members tab is what features read; the Rules tab only feeds ProcessMembers.
• Saving rules changes nothing until you run ProcessMembers.
• Hand-added members survive every rebuild; rule-built members are replaced each time.
• Scheme → trade schemes, Discount → discount group rules; every other feature accepts any type.
• An empty Rule Success Criteria or no conditions means every item.
• Add Active Equals true to keep inactive items out of a rule-built group.
• Member SKU and Item Lot Type narrow the group for trade schemes only (incentive targets also read the SKU).

Permissions

Access is granted per entity in the user's security profile. Item Group (the group), Item Group Member (the Members tab) and Item Group Rule (the Rules tab) each need read access, plus create, edit or delete as required. In the standard profiles, Sales, Sales Manager, Sales Executive, Service, Standard User and System Admin can work with groups, members and rules.

ProcessMembers is a server action and is granted separately. In the standard setup only the Standard User and System Admin profiles have it; the sales profiles do not. To let sales managers rebuild groups, grant the action on their profile.

Configuration

Common problems

ProcessMembers added every item

The group has no conditions, or its Rule Success Criteria is empty or Always (No Criteria). In a standard setup the criteria list is empty until an administrator adds the values. Add the values, choose a criteria, and run ProcessMembers again. The run replaces the previous rule-built members.

I can't choose a Rule Success Criteria

The field has no standard values. An administrator adds them (see Configuration).

The group has no members after I saved the rules

Saving rules does not build members. Select ProcessMembers on the group, wait for the background run, and refresh the Members tab.

The scheme (or discount rule) ignores my group

Check the group's Item Group Type: it must be Scheme for trade schemes and Discount for discount group rules. Then check that the item is on the Members tab. For a scheme, also check that the member's SKU and Item Lot Type are empty or match the line.

Inactive items appear in a rule-built group

The rebuild does not skip inactive items. Add the condition Active Equals true and run ProcessMembers again.

Incentive performance does not count an item I added by hand

Incentive performance figures count only members whose Is Active is on, and the standard member form leaves it empty. Ask an administrator to add Is Active to the member layout, or let ProcessMembers add the item through the rules.

Common questions

Does the group update itself when items change?

No. A rule-based group is a snapshot taken when ProcessMembers last ran. Hand-added members change only when you change them. If your rules test fields that change often, make running ProcessMembers part of your routine, for example after you add new products. Documents that were already priced, taxed or checked for schemes keep what they got. Only documents processed after the rebuild see the new membership.

Can one group be used by several features?

Yes, with one limit. Trade schemes need a Scheme group and discount group rules need a Discount group, so a group cannot serve both. Tax group rules, incentive targets, cycle counts, selling scope and bookings accept any type. A Scheme group can therefore also drive an incentive target or a cycle count. If you need the same items for schemes and discounts, create two groups with the same rules and different types.

Can I mix rules and hand-picked items?

Yes. Keep the rules and add the extra items on Members. Each ProcessMembers run replaces only the members it created, so your additions stay. To exclude an item the rules pick up, refine the conditions instead. A deleted rule-built member comes back on the next run.

Does the mobile app use item groups offline?

Yes, for pricing on the device. The offline scheme calculation uses Scheme group members, including their SKU and lot type, and offline discounts use Discount group members. Offline tax does not read a tax rule's Item Group, so a tax rule scoped to a group can give a different result on the device than on the server.

Related topics

• Trade schemes
• Pricing, discounts and taxes
• Account groups
• Selling scope
• Incentive plans
• Cycle counting
• Items (the item master)
• Item Group entity reference
• Item Group Member entity reference
• Item Group Rule entity reference
• Item — entity reference