Company user roles and permissions overview

Last updated:
Edit on GitHub

Usually, employees within a company have different roles (for example, purchasing, administration, supervision). These roles are related to company users and are referred to as Company Roles. A role can be default (the is_default option), which means that it is used for all new users automatically.

Upon initial creation of the first company user, the default role is Admin. After the Admin user has been created, they create the structure of the company and can define the default role to be used further on.

roles.png

Permissions

Each Company role contains a set of permissions in the form of Permission keys attributed to them.

The Permission keys define what the users are allowed to do.

For example, a user can be allowed to add products to the cart.

Permissions that can be used are not limited in any way—you can create and integrate any permissions. Each of the permissions is represented as a plugin in the code.

Here is another example of the connection between company roles and permissions:

  • When a user registers a company in the system, they actually create a request for a company account registration.
  • After the company account has been approved, this first company user becomes the company administrator.
  • Therefore, one of the roles within the company is an administrator who has all the permissions with regard to the company profile creation and management, user accounts, and user rights.

One and the same user can have several Company Roles assigned to them. It means that the same user can be a junior sales manager and team leader, which in its turn implies that this user has permissions assigned to both roles: junior sales manager and team leader.

The permissions, entitling the user with more rights, win. For example, suppose junior sales managers are allowed to place an order for up to 1000 Euro, whereas team leaders can place orders for up to 2000 Euro. If a user has both roles assigned to him, they can place orders for up to 2000 Euro, and not 1000 Euro.

Or, for example, if junior sales managers can’t view specific products, but team leaders can, the users having both a junior sales manager and team leader roles can view those products.

roles-permissions.png

Company roles and permissions and their relation to the organizational structure can be schematically represented as follows:

roles_structure.png

Permission types

Permissions can be simple and complex.

Permission Type Description Example
Simple Simple permissions are those that do not have any logic behind them and answer the question "Does a customer have a permission?". Simple permissions implement only `PermissionPluginInterface` (Shared).

A company user is allowed (or not allowed) to access product details page.
Complex Complex permissions have some logic behind them and answer the question "Does the customer have a permission with some parameters and business logic?". Complex permissions implement ExecutablePermissionPluginInterface (Shared).

A company user is allowed (or not allowed) to place an order with grand total over 1000 Euro.
Infrastructural Some permissions can't be managed in the UI, but programmatically. Infrastructural permissions implement `InfrastructuralPermissionPluginInterface` (Shared).

Read shared cart, which is managed by the Shared Carts feature.

Some permissions can be configured for specific roles—for example, for a junior support engineer, allow adding no more than X items to cart.

Or for example, some specific products are not allowed to be viewed by anyone but Admin and top managers.

These values are referred to as Company Role Permissions.

Permission can also be Yves-side and Zed-side.

  • Yves permissions do not need to get any data from the database. They refer to key-value storage or search to check the right for actions.

For example, the permission to view a product, page, or permission to place an order, permission to place an order with grand total less than X would be Yves-side permissions.

  • Permissions that require some data from the database or additional business logic on top to check the rights for actions are referred to as Zed permissions.

For example, the permission to add to cart up to X [order value] is a Zed-side permission. In this case, the process of permissions check is as follows:

  1. After the user clicks Add to cart, the request comes to Zed, and the prechecks are made following the “add to cart” request.
  2. Then, the calculations are run. The calculations apply discounts per items, and then per cart (total). The logic behind this is simple: a user might have a discount for a specific item and a discount for an order starting from a specific order value. The order value is calculated taking the discount per items into account, and therefore the discount per cart is applied after all discounts per items have been calculated.
  3. After the calculations have been made, the cart is saved.

The permissions can’t be checked at the step when the user just clicks Add to cart because the actual order value has not been calculated yet (prechecks have not been made yet, discounts have not been calculated). Also, the permissions check request can’t be started after the cart has been updated—that would be too late, as, the cart has already been persisted. The request for the rights check is made somewhere in between—specifically, right after the discounts have been calculated. That is why the so-called “termination hooks” have been implemented deep in logic, where the permissions checks are made.

The termination hooks (plugin stack) do not allow the permissions to sneak into the business logic foundation so it remains clean from the permissions and not overwhelmed with “can” “if not; then…”.

termination_hooks.png

The termination hooks are performed one by one, and process termination can happen for any reason, and one of them would be the permissions.

Company permissions on the Storefront

Every company role includes a set of permissions that can be enabled/disabled according to your needs by switching the toggle in Enable column:

  • Add company users—allows adding company users. With this permission enabled, a user has the Create User button on the Company Users page.
  • Invite users—allows inviting company users. With this permission enabled, a user has the Invite Users button on the Company Users page.
  • Enable / Disable company users—allows enabling and disabling company users. With this permission enabled, a user can switch a toggle in the Enable column on the Company Users page.
  • See Company Menu—allows access to the company menu. With this permission enabled, a user can navigate to a company menu from the header of the shop interface.
  • Add item to cart—allows adding products to the cart. Without this permission, the user gets the “This action is forbidden” error when trying to add the product to the cart.
  • Change item in cart—allows changing products in the cart (changing the quantity or adding notes).
  • Remove item from cart—allows deleting the products from the cart.
  • Place Order—allows placing the order. Without this permission enabled, a user gets an error when trying to submit the order. If the Approval Process feature is integrated into your project, then Buy up to grand total permission is also required to place an order.
  • Buy up to grand total (Requires “Send cart for approval”)—sets a limit for the grand total of the cart. If the amount in the cart is larger than the limit set in this permission, the user can’t proceed to checkout. Works with Send cart for approval permission. This permission is available after enabling the Approval Process feature.
  • Approve up to grand total—with this permission enabled, a user can approve the cart. For more details, see Approval Feature Overview.
  • View Business Unit orders—with this permission enabled, a user can see not only their own orders but also the orders of their business unit.
  • View Company orders—with this permission enabled, a user can see not only their own orders, orders of their business unit, but also the orders of their company.
  • Send cart for approval (Requires “Buy up to grand total”)—lets a user send the cart for approval. Works together with Buy up to grand total permission. See Approval Feature Overview for more details.
BACK OFFICE USER GUIDES
Create company roles
Edit company roles
Create company users
Edit company users
Developer guides

Are you a developer? See Company Account feature walkthrough for developers.

See next

Business on Behalf overview