From f0a8224b31155bf2a1f333aada1f61fe49bf3b0c Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Tue, 16 Jan 2024 15:45:00 +0100 Subject: [PATCH 1/2] Adhoc - Update table and link (#1252) * update table and link * Update concepts/commerce/checkout-concept/payments.md * Update concepts/commerce/checkout-concept/payments.md Co-authored-by: Micha Hobert --------- Co-authored-by: Micha Hobert --- concepts/commerce/checkout-concept/payments.md | 2 +- .../add-plugin-configuration.md | 4 +--- .../employee-management/guides/index.md | 14 +++++++------- 3 files changed, 9 insertions(+), 11 deletions(-) diff --git a/concepts/commerce/checkout-concept/payments.md b/concepts/commerce/checkout-concept/payments.md index c3e7f9ee7..263d6d642 100644 --- a/concepts/commerce/checkout-concept/payments.md +++ b/concepts/commerce/checkout-concept/payments.md @@ -82,7 +82,7 @@ The actual implementation of payment integrations differs between providers. The ### Session and state -The session should not be used in headless payment integrations. Read more about Session usage [here](../../../resources/guidelines/code/session-and-state) +The session should not be used in headless payment integrations. Read more about [session guidelines](../../../resources/guidelines/code/session-and-state). ### Controllers and API diff --git a/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md b/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md index 58cae9c78..89ff652ab 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md @@ -36,9 +36,7 @@ All you need to do is creating a `config.xml` file inside of a `Resources/config ## Fill your plugin configuration with settings -As we now know how to create your configuration, we can start to fill it with life - -* or options to configure, in this case. +As you now know how to create configurations, you can start to fill it with life using various configuration options. ### Cards in your configuration diff --git a/products/extensions/b2b-components/employee-management/guides/index.md b/products/extensions/b2b-components/employee-management/guides/index.md index ebc35b369..4ad1324bf 100644 --- a/products/extensions/b2b-components/employee-management/guides/index.md +++ b/products/extensions/b2b-components/employee-management/guides/index.md @@ -22,10 +22,10 @@ A permission can be dependent on another permission, without which this permissi ### Shopware base permissions The following permissions are already included and used in the B2B Employee Management component. More "base" permissions will be duly added with future B2B Components. -|Group|Permission|Dependencies| -|---|---|---|---| -|employee|employee.read| | -|employee |employee.edit|employee.read| -|employee |employee.create|employee.read, employee.edit| -|employee |employee.delete|employee.read, employee.edit | -|order|order.read.all| +| Group | Permission | Dependencies | +|---------|----------|-----------| +| employee | employee.read | | +| employee | employee.edit | employee.read | +| employee | employee.create | employee.read, employee.edit | +| employee | employee.delete | employee.read, employee.edit | +| order | order.read.all | | From 3ec933a6144f23e6d168d0131c03582bc7bc29f9 Mon Sep 17 00:00:00 2001 From: Duy Dinh Date: Wed, 17 Jan 2024 16:17:51 +0700 Subject: [PATCH 2/2] NEXT-32619 - Write document for order approval (#1240) * NEXT-32619 - Write document for order approval * Update products/extensions/b2b-components/order-approval/01-entities-and-workflow.md * Update products/extensions/b2b-components/order-approval/01-entities-and-workflow.md * Update products/extensions/b2b-components/order-approval/01-entities-and-workflow.md * Update products/extensions/b2b-components/order-approval/02-order-approval-permissions.md * Update products/extensions/b2b-components/order-approval/02-order-approval-permissions.md * NEXT-32619 - Write document for order approval --------- Co-authored-by: Su <112690947+sushmangupta@users.noreply.github.com> --- products/extensions/b2b-components/index.md | 2 + .../01-entities-and-workflow.md | 49 +++++++++++ .../02-order-approval-permissions.md | 27 ++++++ .../order-approval/03-payment-process.md | 41 +++++++++ .../04-add-new-approval-condition.md | 83 +++++++++++++++++++ .../b2b-components/order-approval/index.md | 14 ++++ 6 files changed, 216 insertions(+) create mode 100644 products/extensions/b2b-components/order-approval/01-entities-and-workflow.md create mode 100644 products/extensions/b2b-components/order-approval/02-order-approval-permissions.md create mode 100644 products/extensions/b2b-components/order-approval/03-payment-process.md create mode 100644 products/extensions/b2b-components/order-approval/04-add-new-approval-condition.md create mode 100644 products/extensions/b2b-components/order-approval/index.md diff --git a/products/extensions/b2b-components/index.md b/products/extensions/b2b-components/index.md index 56c1d11d9..3a935cfb9 100644 --- a/products/extensions/b2b-components/index.md +++ b/products/extensions/b2b-components/index.md @@ -15,6 +15,8 @@ In the world of digital B2B commerce, where businesses engage with other compani * **Quote Managements** covers Sales Representative related jobs around negotiating quotes with customers. +* **Order Approval** allows for a more controlled buying process by introducing an approval workflow. + * **Quick Order and Order List** takes care of distinctive B2B buying behaviors. * **Digital Sales Composables** aims to provide a set of composable frontends to cover more complex Sales Representative jobs. diff --git a/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md b/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md new file mode 100644 index 000000000..21e6f6b9e --- /dev/null +++ b/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md @@ -0,0 +1,49 @@ +--- +nav: + title: Entities and workflow + position: 10 + +--- + + +# Entities and workflow + +## Entities + +### Approval Rule + +The approval rule entity represents a set of conditions that need to be met for an order to be approved. These conditions might be based on the order's total value, the order's currency or orders placed by employees with a specific role. Each approval rule can be assigned to a reviewer with specific role, which means that only employees that only employees possessing that role are authorized to approve orders meeting the rule's conditions. Additionally, it can be assigned to a particular role, requiring employees with that role to seek approval for orders meeting the rule's criteria. The rule also includes a priority, dictating the sequence in which the rules are evaluated. + +### Pending Order + +The pending order entity represents an order that has been placed by an employee that requires approval. It contains the order's data, the employee that placed the order and the approval rule that matched the order. + +## Workflow + +The following diagram shows the workflow of the order approval component: + +```mermaid +flowchart TD + A(Employee places an order) -->B{Approval rule applies} + B-->|No| C[Event: Order Placed] + B-->|Yes| D[Event: Order needs approval] + D-->E{Order approved?} + E-->|No| F[Event: Order declined] + E-->|Yes| G[Event: Order Approved & Event: Order placed] +``` + +## Who can request approval? + +* Employees holding the role designated as the "Effective role" in the approval rule corresponding to the order are authorized to request approval. + +## Who can view pending orders? + +- Employees with the "Can view all pending orders" permission can view all pending orders. +- Employees who requested approval for the order can view their pending orders. +- Business Partners can view all pending orders of their employees. + +## Who can approve or decline pending orders? + +- Employees with the "Can approve/decline all pending orders" permission can approve or decline all pending orders. +- Employees with the "Can approve/decline pending orders" permission can approve or decline pending orders that assigned to them. +- Business Partners can approve or decline all pending orders of their employees. \ No newline at end of file diff --git a/products/extensions/b2b-components/order-approval/02-order-approval-permissions.md b/products/extensions/b2b-components/order-approval/02-order-approval-permissions.md new file mode 100644 index 000000000..53c889709 --- /dev/null +++ b/products/extensions/b2b-components/order-approval/02-order-approval-permissions.md @@ -0,0 +1,27 @@ +--- +nav: + title: Order approval permissions + position: 20 + +--- + +# Order approval permissions + +Below you can find a list of all the order approval rules that are available in the order approval component. You can utilize these rules for assigning roles to your employees. + +### Approval rule permissions + +| Permission | Description | +|-----------------------------|-----------------------------------------------| +| `Can create approval rules` | Allows the employee to create approval rules | +| `Can update approval rules` | Allows the employee to update approval rules | +| `Can delete approval rules` | Allows the employee to delete approval rules | +| `Can read approval rules` | Allows the employee to view approval rules | + +### Pending order Permissions + +| Permission | Description | +|------------------------------------------|---------------------------------------------------------------------| +| `Can approve/decline all pending orders` | Allows the employee to approve or decline all pending orders | +| `Can approve/decline pending orders` | Allows the employee to approve or decline assigned pending orders | +| `Can view all pending orders` | Allows the employee to view all pending orders | \ No newline at end of file diff --git a/products/extensions/b2b-components/order-approval/03-payment-process.md b/products/extensions/b2b-components/order-approval/03-payment-process.md new file mode 100644 index 000000000..dbcd41327 --- /dev/null +++ b/products/extensions/b2b-components/order-approval/03-payment-process.md @@ -0,0 +1,41 @@ +--- +nav: + title: Payment Process + position: 30 + +--- + +# Order approval's payment process + +The payment process of the order approval component is the same as the payment process of the order component. You can select the payment method that you want to use for your orders; however unlike the standard order component, the payment process will be executed only after the order has been approved in case of the online payment method (Visa, PayPal, etc.). + +## Customization + +### Storefront + +The payment process of the order approval component can be customized by extending or overriding this page `@OrderApproval/storefront/pending-order/page/pending-approval/detail.html.twig` + +### Payment process + +Normally, after reviewer approves the order, the payment process will be executed automatically. However, if you just want to approve the order without executing the payment process, you can subscribe to the `PendingOrderApprovedEvent` event and set the `PendingOrderApprovedEvent::shouldProceedPlaceOrder` to `false`. This event is dispatched in the `Shopware\Commercial\B2B\OrderApproval\Storefront\Controller\ApprovalPendingOrderController::order` method. + +```PHP + +use Shopware\Commercial\B2B\OrderApproval\Event\PendingOrderApprovedEvent; + +class MySubscriber implements EventSubscriberInterface +{ + public static function getSubscribedEvents(): array + { + return [ + PendingOrderApprovedEvent::class => 'onPendingOrderApproved' + ]; + } + + public function onPendingOrderApproved(PendingOrderApprovedEvent $event): void + { + $event->setShouldProceedPlaceOrder(false); + } +} +``` + diff --git a/products/extensions/b2b-components/order-approval/04-add-new-approval-condition.md b/products/extensions/b2b-components/order-approval/04-add-new-approval-condition.md new file mode 100644 index 000000000..7150d889f --- /dev/null +++ b/products/extensions/b2b-components/order-approval/04-add-new-approval-condition.md @@ -0,0 +1,83 @@ +--- +nav: + title: How to add a new approval condition + position: 40 + +--- + +# How to add a new approval condition + +The order approval component provides a set of conditions for defining your approval rules. However, if you need to add a new condition, you can do so via an app or a plugin. + +## Plugin + +Each condition is represented by a class that extends the abstract class `Shopware\Commercial\B2B\OrderApproval\Domain\ApprovalRule\Rule\OrderApprovalRule`. To add a new condition, you need to create a new class that extends the `OrderApprovalRule` class and implements the `match` and `getConstraints` methods. The `match` method is used to determine if the condition is met, and the `getConstraints` method is used to define the field, value or operator constraints that can be used in the condition. + +Example: + +```PHP +amount = (float) $amount; + } + + /** + * @throws UnsupportedOperatorException + */ + public function match(RuleScope $scope): bool + { + if (!$scope instanceof CartRuleScope) { + return false; + } + + return RuleComparison::numeric($scope->getCart()->getPrice()->getTotalPrice(), $this->amount, $this->operator); + } + + public function getConstraints(): array + { + return [ + 'amount' => RuleConstraints::float(), + 'operator' => RuleConstraints::numericOperators(false), + ]; + } + + public function getConfig(): RuleConfig + { + return (new RuleConfig()) + ->operatorSet(RuleConfig::OPERATOR_SET_NUMBER) + ->numberField('amount'); + } +} +``` + +And then tag your class with the `shopware.approval_rule.definition` tag: + +```XML + + + +``` + +## App + +We have not yet added support for extending custom `OrderApprovalRules` for the app. \ No newline at end of file diff --git a/products/extensions/b2b-components/order-approval/index.md b/products/extensions/b2b-components/order-approval/index.md new file mode 100644 index 000000000..00548984e --- /dev/null +++ b/products/extensions/b2b-components/order-approval/index.md @@ -0,0 +1,14 @@ +--- +nav: + title: Order Approval + position: 20 + +--- + +# Order approval component + +Order approval component is a part of the B2B Employee Management. It allows you to define rules that determine which orders require approval and which employees can approve them. It also allows you to view all pending orders and approve or decline them. + +## Requirements + +* You need to have Employee Management component installed and activated (see [Employee Management](../employee-management/README.md)).