Selling scope and partner account mappings

A partner account mapping is a dated rule that allows or blocks items, or whole item groups, for one sales executive, optionally narrowed to a selling company, branch, customer or group. Take Order reads these rules to decide which products the executive may sell. Together with the selling company's store, they make up the executive's selling scope. The rules sit between your master data (resources, partner assignments, stores, item groups) and order taking: you set them up once per executive and territory, and they apply every time that executive opens Take Order for a customer.

Overview

Two things decide what an executive sees in Take Order:

1. The store. The selling company's store sets the full range. Only items the store stocks can be offered.
2. The partner account mappings. These narrow that range for one executive. Rows marked as blocked remove items. Rows marked as allowed turn the range into a whitelist.

xMatix works out the selling scope on the server and sends the device only the result: the allowed, blocked and stocked item lists. Because of this, the executive needs no read access to the mapping rows, the resource record or the item group memberships behind the result. A rule an administrator writes therefore applies to the executive it names, even though that executive may not be able to open the rule.

Mobile Take Order and web Take Order ask for the same answer and apply the same rule to each item. Once the selling company's store is found, one executive selling to one customer sees the same range on both.

When to use it

• An executive may sell only part of the catalogue, for example one brand's item group, in a territory.
• An item must be kept away from one customer, one customer group or one distributor for a period, for example while a listing is disputed.
• A distributor has agreed exclusions with you, and those should apply only while that distributor's terms are in force.

Do not use partner account mappings to store lists such as "frequently ordered items". Every row that names an item takes part in the allow/block decision. Writing top-N rows here changes what executives may sell. Frequently ordered items are calculated by Take Order itself.

How xMatix handles it

When an executive opens Take Order for a customer, xMatix resolves the scope step by step.

1. The executive's resource. xMatix looks for the active Resource whose User is the signed-in user. If none exists, the catalogue is not scoped.
2. The selling company and branch. If the visit carries a partner account (and branch), those are used. Otherwise xMatix uses the resource's Default Partner Account and Default Branch when both are set. If they are not both set, it uses the first current Partner Resource assignment, ordered by Assignment Sequence Number. If there is no current assignment either, it uses whichever default is set. Orders are stamped with the same partner account and branch when they are saved, so the catalogue and the saved order always agree.
3. The mapping rows that apply. xMatix collects every mapping whose Resource is this executive's resource. It keeps only the rows that are in date today and whose every filled condition matches:

A blank condition matches anything. A filled condition cannot match when xMatix does not know the value, for example an Account condition when Take Order is opened without a customer.

1. Allow and block. Among the matching rows, only those that name an Item or an Item Group affect the catalogue. An item group means all of its active member items.
   • Is Allowed = No blocks those items. A block always wins over an allow.
   • Is Allowed = Yes allows them. As soon as at least one matching allow row exists, the executive sees only allowed items.
   • Is Allowed blank means "not stated". The row neither allows nor blocks.
   • A row that names no item and no item group allows or blocks nothing, so it never empties the catalogue.
2. The store. xMatix looks for the selling company's store in this order:
   • a Store whose Partner Account is the selling company;
   • a Partner Store link for that company, preferring links for the selling branch or links with no branch;
   • a Store whose Partner Account Group is a group the company belongs to.

If more than one store qualifies, the newest is used. The items in the store's categories are the full range.

Each item is then judged in this order:

1. Not stocked by the store: hidden.
2. Blocked: hidden.
3. Allowed list in force and the item is not on it: hidden.
4. Otherwise: shown.

The scope always fails open, so an executive is never locked out of ordering:

• No resource or a failed request. The full catalogue is shown when the user has no active resource or when the request fails. On mobile, the scope is not stored for offline use, so Take Order opened without a connection also shows the full catalogue.
• No selling company, no store or an empty store. The store does not narrow the range when no selling company is found, the company has no store, or the store's categories hold no items. On mobile, the executive's matching allow and block rows still apply to the whole catalogue. On the web, the mappings are not applied, and the catalogue follows the web's own store lookup for the order (see Catalogue and pricing).

The scope governs what may be added to an order. Lines already on an order stay on it when you edit the order, even if the executive's mappings have changed since.

Prerequisites

• We run multiple companies is switched on under Setup → Feature Hub → Administration → Org Settings. When it is off, partner account mappings are hidden, along with the other partner-only records.
• Each executive has an active Resource linked to their user, with a Default Partner Account (and Default Branch where you use branches) or a current Partner Resource assignment.
• The selling company has a store whose categories contain items.
• The item groups and account groups you plan to name exist and have active members.

Procedure

Step 1 — Open partner account mappings

Partner account mappings are not part of any app's navigation in the standard setup. An administrator adds Partner Account Mappings to an app under Setup → Design Studio → Apps with Manage Items. The list opens on the All Partner Account Mapping view, with the columns Name, Partner Account Group, Account, From Date and To Date.

Step 2 — Create a mapping

Choose New. The New form asks for Partner Account, Partner Account Group and Account. Under Mapping Controls it asks for Item, Item Group, From Date and To Date. From Date is required. The Partner Account lookup lists only active accounts marked as partner accounts. The Account lookup lists only active customer accounts. Save, and the record is given a document number in the PAM series.

Step 3 — Set the resource and the allow/block flag

In the standard data model, Resource and Is Allowed are inactive and appear on none of the standard forms. A row without a Resource never takes part in Take Order's selling scope, whatever else it names. A row whose Is Allowed is blank neither allows nor blocks. Before you rely on a mapping, confirm with your administrator how your organization fills these two fields.

Step 4 — Review or change a mapping

Open a mapping from the list. The record page shows a Details tab with:

• an Information section: Partner Account, Branch, Partner Account Group, Account, Item, Item Group, From Date, To Date;
• a System Information section: Created By, Owner.

When you edit the record in the standard layout, Item Group and From Date are both required. Changes take effect the next time Take Order resolves the scope.

Step 5 — End a mapping

To stop a rule from a given date, set its To Date. This keeps the row as history. Delete removes the row outright. Clone copies a row as the starting point for a similar one.

Fields

The field reference lists every stored column: Partner Account Mapping — entity reference.

Business rules

• Numbering. New rows are named from the Partner Account Mapping Document Name Settings: series PAM, an eight-digit counter and a day-month-year date part.
• No save-time validation. Beyond the required fields on the form, xMatix does not check a mapping when it is saved. Conflicting or overlapping rows are allowed. Their effect is settled when the scope is resolved: block beats allow.
• Dates are inclusive. A row applies on its From Date and on its To Date.
• Allow-list mode is per executive and context. It switches on only when at least one row matching this customer, company and branch allows an item or item group. The same executive can therefore have a whitelist for one customer and the full store range for another.
• Partner business transfers leave mappings behind. When a partner's business is handed over with Transfer Partner Business, the outgoing partner's mapping rows are neither moved nor copied. They encode terms agreed with that partner. Set up the incoming partner's own rows as part of the handover.

Example

A beverage distributor's executive covers two retail chains for one company. The company's store stocks 400 items. The administrator sets up three rows for the executive's resource:

When the executive opens Take Order for an outlet in Chain A, rows 1 and 2 match. Allow-list mode switches on, and the catalogue shows only juices and carbonated drinks the store stocks.

For an outlet in Chain B, all three rows match. Any energy drink that is also in the Carbonated group is blocked, because a block always wins.

From 1 July, row 3 is out of date and Chain B sees the same range as Chain A.

Training

Practice exercise

In a sandbox, pick an executive with an active resource whose selling company has a store with items. Create two mappings for that resource:

• one allowing a small item group;
• one blocking a single item from that group for one customer.

Then open Take Order as the executive:

• For a different customer, you should see only the item group's members that the store stocks.
• For the named customer, you should see the same list without the blocked item.
• On mobile, scanning the blocked item's barcode for that customer should report that it isn't available to you because it is blocked for your account mapping.

Quick reference

• No mapping rows = the full store range.
• One matching allow row that names items = only allowed items.
• A block always beats an allow.
• Blank Is Allowed = "not stated"; the row does nothing.
• A blank condition matches anything; a filled one must match.
• Rows without a Resource never affect Take Order.
• From Date and To Date are inclusive; a blank To Date never expires.
• No store, no resource or no connection = the full catalogue.
• Existing order lines are never removed by a scope change.

Permissions

The standard Sales Executive, Sales Manager, Standard User and System Admin security profiles grant full access to partner account mappings: read, create, edit and delete. Record access follows the standard sharing policy for the entity. Records are user-owned, with hierarchy access, manual sharing and team access switched on. See Record security.

Take Order needs no read access to the mappings. The scope is resolved on the server for the signed-in user, from that user's own resource, so it cannot be used to look at another executive's scope.

Configuration

Common problems

Take Order shows the whole catalogue

The scope declined to narrow it. Check these causes in order:

• The executive has no active resource linked to their user.
• The resource has no default partner account and no current partner assignment.
• The selling company has no store.
• The store's categories hold no items.
• The device was offline.

Each of these shows the full range by design. Without a store, mobile still removes blocked items and applies any allow list, but web does not apply the mappings at all.

My allow rule has no effect

Check the following:

• The row names the executive's Resource.
• Is Allowed is Yes rather than blank.
• Today is inside the dates.
• Every filled condition matches the order's customer, company and branch.
• The row names an Item or Item Group. A row naming neither changes nothing.

The executive suddenly sees far fewer items

An allow row now matches, and allow-list mode is on. Every item not covered by a matching allow row is hidden. Add allow rows for the rest of the range, or narrow the new row's conditions so it applies only where intended.

A scanned item says it "isn't available to you"

The mobile barcode scanner names the reason after the dash:

• blocked for your account mapping: a matching row with Is Allowed = No names the item or a group it belongs to.
• not stocked by your store: the item is outside the store range.
• not in your allowed items: allow-list mode is on and no matching allow row covers the item.

Saving an edited mapping asks for Item Group

The standard record layout marks Item Group as required when editing. Fill it, or ask your administrator to adjust the layout if your rows name single items.

The mapping list is missing

We run multiple companies is off, or the entity has not been added to an app menu.

Common questions

Does an executive with no mapping rows see nothing?

No. With no matching rows, the executive sees everything the selling company's store stocks. Blocks only remove items. The catalogue narrows to a whitelist only once at least one matching row allows a specific item or item group. A row that states an entitlement without naming items, for example one that only names a customer, does not switch the whitelist on. The design ensures that setting up rows gradually never empties an executive's catalogue by accident.

What is the difference between Account and Partner Account?

Partner Account is the selling company, one of your own companies or distributors marked as a partner account. Account is the customer the order is for. The same split applies to the two group fields: Partner Account Group groups selling companies, and Account Group groups customers. Putting a customer group in the partner field, or the other way round, makes the row match the wrong side and usually never match at all.

Do mappings follow a distributor's territory when it changes hands?

No. When a partner's business is transferred, its mapping rows stay with the outgoing partner and no copies are made for the incoming one. Those rows record terms agreed with the previous partner, including exclusions. Create the incoming partner's rows as part of taking the territory on, then check Take Order for one of the transferred outlets.

Does the scope apply offline?

No. On mobile, the selling scope is fetched from the server each time Take Order opens for a customer and is not stored on the device. Without a connection, the catalogue is not narrowed, so the executive can still take the order. Prices and the catalogue itself remain available offline as usual.

Related topics

• Complete a visit
• Creating a sales order
• Catalogue and pricing
• Branches
• Companies and tenants
• Record security
• Partner Account Mapping — entity reference
• Account — entity reference