Business unit group

Customers, trusted agents and projects can belong to a business unit group: a group of business units (stores) from Business Unit Management. The group decides two things:

• which business units see the record when the till searches, and
• who may read and write it, for users whose access is limited to some business units or groups.

A record without a group is shared by every business unit, and reading or writing it needs access to all business units of your tenant.

The CRS group type

CRS only knows groups from one hierarchy in Business Unit Management: the hierarchy whose root group has the group type b2b-customer-registry ("B2B Customer Registry"). In Business Unit Management the group type is set on the root group and applies to every group below it, and a group type can be set on at most one hierarchy per tenant. This page calls a group in that hierarchy a CRS group.

A group id is valid as businessUnitGroup when the group is in that hierarchy and has at least one business unit assigned to it directly. A parent group that has no business units of its own is not known to CRS.

CRS learns which business units belong to which group from Business Unit Management, when a business unit is created, changed or assigned to a group. ⚠ Setting the group type on a hierarchy that already exists does not by itself make its groups known to CRS.

A group CRS does not know returns:

{
  "statusCode": 409,
  "message": "Business Unit Group does not exist, or is not part of Customer Registry type",
  "error": "Conflict"
}

CRS checks this when:

• a customer or a project is created or restored with a group, and
• an agent is written with PUT /api/v1/agents, every time, against the customer's group.

Updates of an existing customer or project, and records without a group, are not checked.

How a business unit maps to groups

A business unit belongs to the CRS group it is assigned to directly. Its parent groups do not count. In Business Unit Management a business unit appears at most once in a hierarchy, so a business unit is in at most one CRS group.

Give each customer the group its business units are assigned to directly. A customer in a parent group is not found by a search for a business unit in a group below it.

Which group a record has

Record	Its group
Customer	The businessUnitGroup sent when it was created, or none.
Trusted agent	Always its customer's group.
Project	Its own businessUnitGroup, sent with the project, or none. Through external ingest it is the customer's group.

The group is fixed once a record exists. Writing a record by its CRS id with another group, with a group when it has none, or without its group returns 409 businessUnitGroup cannot be changed on an existing customer (or ... existing project, ... existing trusted agent). To move a customer to another group, delete it and create it in the other group.

External ids are unique per group

Your own customer ids are unique per tenant and business unit group, not per tenant. The same externalCustomerId can exist once in each group and once without a group; "no group" is a scope of its own, and each of those is a separate customer. externalAgentId is unique within its customer, and externalProjectId within the customer's externalCustomerId and the project's group.

Always send the same businessUnitGroup for a record. When you write by your own ids, the group is part of the key, so another group, or none, addresses a different record. A PUT creates a second record instead of updating yours, and an external ingest PATCH or DELETE returns 404. See External ingest.

Search by business unit

GET /api/v1/customers, /agents and /projects take a businessUnitId parameter: the business unit the search is for. It returns the records in the business unit's CRS group plus every record that has no group. Records in other groups are left out.

• businessUnitId combines with the other filters: a record must match all of them.
• A business unit that is in no CRS group gets only the records without a group. That is not an error.
• Only groups with the type b2b-customer-registry count.

Who may read and write which records

Two checks decide whether a request goes through.

1. The permission. Each endpoint needs one permission, such as crs.customer.read or crs.project.write. Without it, the request is refused with 403 and an empty body before it reaches CRS.

2. The scope. CRS then checks the permission against a business unit or a group:

Request	Checked against
Search with businessUnitId	that business unit
Search without businessUnitId	all business units
Read by id and project restrictions; PUT, PATCH and DELETE on /customers, /agents and /projects	the record's group, or all groups if it has none
External ingest of customers and projects	the group in the body, or all groups if there is none
POST /customers/{customerId}/credit-limit:validate	crs.customer.read on the customer's group, in addition to crs.credit-limit.validate
POST /customers:create	the businessUnitId in the body

A denied scope returns:

{ "message": "Forbidden", "statusCode": 403 }

Who has which scope follows the Hii Retail access rules:

• An OCMS client (machine-to-machine, see OCMS) that has the permission has it for every business unit and group of its tenant.
• A user has it for every business unit and group when at least one of their roles with the permission has no resource bindings. Otherwise the user has it only for the business units and groups bound to those roles, combined. See Resources.
• A binding to a group covers that group, every group below it and every business unit in them. A binding to a business unit covers only that business unit.
• Roles a user gets only from their identity provider carry no bindings, so they give access to every business unit and group.
• Business units and groups are resolved in the Business Unit Management hierarchy. A user with bindings is refused for a business unit or group that is not in it.

🛑 A user bound only to a business unit can search for that business unit, but cannot read by id or write the records in its group. Search checks the business unit; reads by id and writes check the record's group. Bind the role to the group, or a group above it, for users who maintain customers, agents or projects.

Records without a group need access to all groups, so a user whose access is limited by bindings cannot read them by id or write them.