Associates overview

Definitions

Seller

In a B2B context, a Seller is a merchant offering goods and services to companies.

Buyer

A Buyer is a company or a representative of the company purchasing goods and services from a Seller. They are represented by Associates in Business Units.

Business Unit

A Business Unit represents a Buyers organization. It can be used to model companies in hierarchical structures and determine which Associates can act on behalf of the company.

Associate

An Associate is a Customer who represents a company. They have specific roles that determine their permissions to access and perform actions, like creating carts or placing orders.

Associate Role

An Associate Role is created and managed by Sellers and defines the granular Permissions associated with each role. It is assigned to an Associate in a Business Unit through an AssociateRoleAssignment. Associates and their roles can be inherited within the hierarchy of Business Units.

B2B resources

Carts, Orders, Quotes, and Quote Requests that exist within the context of a Business Unit. In practice, this means the resource has its businessUnit field set.

Permission

Permissions provide controlled access to B2B resources, and their naming convention represents the action allowed for a given resource type, for example, CreateMyCarts.

Inheritance

Inheritance refers to the process by which Associates and their roles are passed down within the hierarchy of Business Units.

Approval Rule

An Approval Rule outlines the conditions under which an Order that matches a predicate needs approval from an approver before it can be ordered by a requester within a Business Unit.

Approval Flow

An Approval Flow matches Approval Rules to Orders and manages the approval state. This includes information about whether the Order is approved or not and the approval status of each approver.

Buyer portal

A Buyer portal is a frontend interface hosted and implemented by the Seller. It is used by the Associates of a Buyer company to manage their B2B resources, Permissions, and Approval Rules.

Associate Roles and Permissions

Associates can be assigned specific roles through an AssociateRoleAssignment, which grants an Associate Role to an Associate within a Business Unit. Each Associate Role includes a set of Permissions that provide controlled access to B2B resources.

The following diagram shows three example Associate Roles, each with a set of Permissions.

Sellers' Role in Managing Permissions

Sellers create and manage Associate Roles, including defining the granular Permissions associated with each role. They can make roles assignable by Buyers using the buyerAssignable property of an Associate Role.

Permission Naming Convention

The naming convention for Permissions represents the action allowed for a given resource type. Most Permission names consist of the action name, either the My or Others keyword and the resource type (for example, UpdateMyOrders, ViewOthersCarts). Permissions with the My keyword grant access to an Associate's own resources, while Others Permissions provide access to resources belonging to other Associates.

Distinct 'My' and 'Others' Permissions

Others Permissions don't imply My Permissions. This behavior allows for maximum flexibility in modeling complex B2B use cases. For instance, granting an Associate the CreateMyCart Permission alongside ViewOthersCarts and CreateOrdersFromOthersCarts Permissions enables a setup where Buyers can create carts but require approval from others to place an order.

Interacting with B2B resources

The API provides three different ways to access B2B resources:

• Using the general endpoints, such as /{projectKey}/carts.
• Using the me endpoints, such as /{projectKey}/me/carts.
• Using the associate endpoints, such as /{projectKey}/as-associate/{associateId}/in-business-unit/key={businessUnitKey}/carts.

Through the general endpoints

When accessing resources using the general endpoint, the API has no knowledge of the Associate behind the API call. Therefore, no Associate Role Permissions are validated. As such, the general endpoints are intended for a Seller that wants to manage access and permissions outside of Composable Commerce.

Example use case: back office operations, customer support.

Through the me endpoint

When using the me endpoints, the API can derive which Associate is behind a given API call using the password flow token. This allows the API to check whether the Associate has the right level of Permissions to perform actions on a given resource. However, the me endpoint can only grant access to the Associate's own resources, and not to resources that belong to other Associates.

Example use case: mobile app for Buyers to make purchases.

Through the associate endpoint

The associate endpoints require an Associate to be specified as a URL parameter along with a Business Unit. This Business Unit is what the Associate's Permissions are checked against. These endpoints are designed specifically for Sellers that want to provide controlled access for their Buyers using the Permissions.

Example use case: B2B storefront using trusted middleware.

Permission evaluation

Permission evaluations and requirements differ based on the endpoint type. The following table provides an overview of the types of Permissions required depending on which method is used to access a resource.

On the me endpoints

The me endpoints validate that the acting Associate has sufficient Permissions on a given B2B resources. In addition, the Associate must be a Customer on the resource and be an Associate of the referenced Business Unit.

My Business Unit

When interacting with Business Units using the My Business Unit endpoints, the API performs validations on certain actions to ensure that the Associate has the correct Business Unit Permissions.

My Carts

For B2B Carts, the My Carts endpoints perform validations to ensure that the Associate has the correct CartPermissions.

Additionally, the Customer on the Cart must be an Associate of the referenced Business Unit.

My Quotes

For B2B Quotes, the My Quotes endpoints perform validations to ensure that the Associate has the correct QuotePermissions.

My Quote Requests

For B2B Quote Requests, the My Quote Requests endpoints perform validations to ensure that the Associate has the correct QuoteRequestPermissions.

My Orders

For B2B Orders, the My Orders endpoints perform validations to ensure that the Associate has the correct OrderPermissions.

On the associate endpoints

The associate endpoints validate that the acting Associate has sufficient Permissions on a given resource. In addition, the Associate must have access to the referenced Business Unit. In contrast to the me endpoints, the associate endpoints can also provide access to resources that do not belong to the Associate directly. For example, the ViewOthersCarts Permission allows an Associate to view B2B Carts where the Customer on the Cart is another Associate.

Associate Carts

For B2B Carts, the Associate Carts endpoints perform validations to ensure that the Associate has the correct Cart Permissions.

Associate Quotes

For B2B Quotes, the Associate Quotes endpoints perform validations to ensure that the Associate has the correct Quote Permissions.

Associate Quote Requests

For B2B Quote Requests, the Associate Quote Requests endpoints perform validations to ensure that the Associate has the correct Quote Request Permissions.

Associate Orders

For B2B Orders, the Associate Orders endpoints perform validations to ensure that the Associate has the correct Order Permissions.

Associate Business Units

The Associate Business Unit endpoints perform validations to ensure that the Associate has the correct Business Unit Permissions.

Inheritance of Associates and their roles

Associates and their roles can be inherited within the hierarchy of Business Units. The inheritance behavior is determined by the inheritance property of individual AssociateRoleAssignments together with the AssociateMode of a Business Unit.

Conditions for inheritance

When the AssociateMode of a Business Unit is set to Explicit, the Business Unit is not allowed to inherit any Associates. In this case, only Associates defined directly on the Business Unit can act on its behalf. With the ExplicitAndFromParent AssociateMode, the Business Unit can have both directly assigned Associates and inherited ones from a parent unit.

For a Business Unit to inherit Associates from a parent unit, the following two conditions must be met:

• The AssociateMode of the Business Unit must be set to ExplicitAndFromParent, allowing the Business Unit to inherit Associates.
• A parent unit of the Business Unit must have at least one Associate with an inheritable role, meaning that the inheritance property of the AssociateRoleAssignment is set to Enabled.

The following diagram illustrates how Business Units with ExplicitAndFromParent AssociateMode inherit Associates from parents, whilst a Business Unit with `Explicit AssociateMode does not.

Eventual consistency of inherited Associates

The inheritedAssociates array of a Business Unit contains the Associates that are inherited. In cases where inheritance applies, this property is automatically populated by a background task. It is updated each time an Associate in a parent Business Unit is added, updated, or removed. However, since this process is subject to eventual consistency, changes in inherited roles might have a delayed effect on role evaluations.

Accumulative permissions of inherited roles

The Permissions of an Associate are the sum of all permissions included on the Associate Role assigned to the Associate directly, and those from inherited roles. The following example demonstrates how permissions accumulate.

Preventing inheritance

By setting the AssociateMode of a Business Unit to Explicit, the inheritance mechanism will be disabled for all Associates of that unit. To prevent the inheritance of a single Associate, disable the inheritance property for all assigned roles of that Associate. This ensures that the Associate is not inherited by any child Business Units. If an Associate is both inherited and explicitly defined in the same Associate Role, the explicitly defined AssociateRoleAssignment determines inheritance.

Buyer Approval Flows

Buyer Approval Flows provide a flexible Order approval process for Business Units. They define conditions that necessitate the requirement for an Order to be approved. This mechanism is useful especially when structuring multi-tiered approval processes for B2B ordering processes.

Approval Flows are linked to Orders and are initiated by matching Approval Rules. The Approval Rule encapsulates the conditions an Order must meet to qualify for the rule's approval process. Approval Rules consist of one or more levels, that are referred to as tiers within an approver hierarchy. Each tier encapsulates one or more Associate Roles that must authorize the Order before it advances to the subsequent tier.

Intended workflow

Approval Flows represent the Order approval process. For Approval Flows to come into effect, Buyers are required to configure Approval Rules as per their organizational requirements.

The following steps describe the intended workflow, alongside a corresponding diagram:

1. A Requester creates a new Order.
2. The Composable Commerce API checks whether any Approval Rules match the Order.
   1. If the Order matches one or more Approval Rules:
      1. A new Approval Flow is initiated in a Pending state to track the approval process.
      2. Approvers provide their approvals or rejections, conforming to the specified tier hierarchy.
      3. If all required Approvers provide approval, the Approval Flow's status changes to Approved.
      4. If any rejections occur, the Approval Flow's status changes to Rejected.
   2. If the Order doesn't match any Approval Rules, it bypasses the approval process.

Configuring Approval Rules

Approval Rules provide a flexible approach to defining approval requirements for Orders using boolean logic. Approvers are designated by Associate Roles, preventing the need to bind Approval Rules to specific individuals.

The configuration supports multiple tiers of approver expressions, allowing for the next level of approvers to be notified only when the preceding level has approved the Order. To streamline the approval process, higher-level approvers also have the option to approve an Order before they receive a notification. This early approval automatically approves all lower levels.

An Approval Rule is made of at least one tier in the ApproverHierarchy. Each tier must be composed of at least one ApproverConjunction that contains at least one ApproverDisjunction holding the RuleApprovers.

ApproverDisjunction and an ApproverConjunction refer to specific components of logical expressions within an Approval Rule. In an ApproverDisjunction, if any of the conditions is true, the whole expression is true. Applied to the approval process, an ApproverDisjunction represents a scenario where any one of a set of approvers can approve an Order for it to pass.

In an ApproverConjunction, all conditions must be true for the whole expression to be true. For the approval process, an ApproverConjunction means that all specified approvers must approve an Order for it to pass.

With up to five levels per Approval Rule, an Order can pass through a maximum of five sequential approval stages. Each level corresponds to an approval stage, starting from the initial stage at the first level to the final approval at the fifth level.

Example configuration of an Approval Rule

Let's look at an example of an approver hierarchy. In this configuration, for an Order to be fully approved, the following approvers must approve:

1. The Project Team Lead OR their substitute AND the Engineering Manager
2. Head of Procurement
3. CEO

The approval process is sequential based on the tiers. In this case, the Head of Procurement won't be required to approve the Order until both the Project Team Lead and Engineering Manager have approved. If either of them doesn't approve the Order, the Head of Procurement and all subsequent tiers (in this case, the CEO) will not have to review it. The following diagram denotes the conjunctions and disjunctions necessary to express this hierarchy.

The JSON notation for the same hierarchy can be expressed as follows:

{
  "tiers": [
    {
      "and": [
        {
          "or": [
            {
              "associateRole": {
                "typeId": "associate-role",
                "key": "project-team-lead"
              }
            },
            {
              "associateRole": {
                "typeId": "associate-role",
                "key": "project-team-lead-substitute"
              }
            }
          ]
        },
        {
          "or": [
            {
              "associateRole": {
                "typeId": "associate-role",
                "key": "engineering-manager"
              }
            }
          ]
        }
      ]
    },
    {
      "and": [
        {
          "or": [
            {
              "associateRole": {
                "typeId": "associate-role",
                "key": "head-of-procurement"
              }
            }
          ]
        }
      ]
    },
    {
      "and": [
        {
          "or": [
            { "associateRole": { "typeId": "associate-role", "key": "ceo" } }
          ]
        }
      ]
    }
  ]
}