From 012a80bbbd27bd2409acf607396b24f70b138007 Mon Sep 17 00:00:00 2001 From: Dinh Duy Date: Wed, 20 Dec 2023 16:27:12 +0700 Subject: [PATCH 1/7] NEXT-32619 - Write document for order approval --- products/extensions/b2b-components/index.md | 2 + .../01-entities-and-workflow.md | 50 +++++++++++ .../02-order-approval-permissions.md | 28 +++++++ .../order-approval/03-payment-process.md | 43 ++++++++++ .../04-add-new-approval-condition.md | 83 +++++++++++++++++++ .../b2b-components/order-approval/index.md | 14 ++++ 6 files changed, 220 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..fbba452ae --- /dev/null +++ b/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md @@ -0,0 +1,50 @@ +--- +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 in order for an order to be approved. These conditions can be based on the order's total value, the order's currency or for all orders placed by employees with a specific role. Each approval rule can be assigned the reviewer to a specific role, which means that only employees with that role can approve orders that match the rule's conditions, and it can be assigned to specific role, which means that only employees with that role will need to request approval for orders that match the rule's conditions; and a priority, which is used to determine the order 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 which have the role that is assigned as the "Effective role" of the approval rule that matched the order. + +## Who can view pending orders? + +- Employees with the "Can view all pending orders" permission can view all pending orders. +- Employees which requested approval for the order can view his pending orders. +- Business Partners can view all pending orders of their employees. + +## Who can approve/decline pending orders? + +- Employees with the "Can approve/decline all pending orders" permission can approve/decline all pending orders. +- Employees with the "Can approve/decline pending orders" permission can approve/decline pending orders that assigned to him. +- Business Partners can approve/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..d2c4778ee --- /dev/null +++ b/products/extensions/b2b-components/order-approval/02-order-approval-permissions.md @@ -0,0 +1,28 @@ +--- +nav: + title: Order approval permissions + position: 20 + +--- + +# Order approval permissions +## Introduction + +Below you can find a list of all the order approval rules that are available in the order approval component, which you can use to assign to the roles of 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 pending orders that assigned to him. | +| `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..d9a253d36 --- /dev/null +++ b/products/extensions/b2b-components/order-approval/03-payment-process.md @@ -0,0 +1,43 @@ +--- +nav: + title: Payment Process + position: 30 + +--- + +# Order approval's Payment Process + +## Introduction + +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, with the exception that if this is the online payment method (Visa, PayPal, etc.), the payment process will be executed only after the order has been approved. + +## 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..47ae18b5e --- /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 that you can use to define your approval rules. However, if you need to add a new condition, you can do so via app or plugin. + +## Plugin + +Each condition is represented by a class that extends the abstract class `Shopware\Commercial\B2B\OrderApproval\Domain\ApprovalRule\Rule\OrderApprovalRule` class. 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..e5f4807e9 --- /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)). From 4236cb607974a4f11b09efdc93897675b3da2006 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Mon, 15 Jan 2024 18:36:52 +0100 Subject: [PATCH 2/7] Update products/extensions/b2b-components/order-approval/01-entities-and-workflow.md --- .../b2b-components/order-approval/01-entities-and-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index fbba452ae..5605548ff 100644 --- a/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md +++ b/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md @@ -43,7 +43,7 @@ flowchart TD - Employees which requested approval for the order can view his pending orders. - Business Partners can view all pending orders of their employees. -## Who can approve/decline pending orders? +## Who can approve or decline pending orders? - Employees with the "Can approve/decline all pending orders" permission can approve/decline all pending orders. - Employees with the "Can approve/decline pending orders" permission can approve/decline pending orders that assigned to him. From 1036392bf438f0c407b423bedf240059853f2fbe Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Mon, 15 Jan 2024 18:37:00 +0100 Subject: [PATCH 3/7] Update products/extensions/b2b-components/order-approval/01-entities-and-workflow.md --- .../b2b-components/order-approval/01-entities-and-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 5605548ff..4b2058c5a 100644 --- a/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md +++ b/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md @@ -40,7 +40,7 @@ flowchart TD ## Who can view pending orders? - Employees with the "Can view all pending orders" permission can view all pending orders. -- Employees which requested approval for the order can view his 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? From 891b71362d1e9a6f41c1d9c89994496ae03ac126 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Mon, 15 Jan 2024 18:37:08 +0100 Subject: [PATCH 4/7] Update products/extensions/b2b-components/order-approval/01-entities-and-workflow.md --- .../order-approval/01-entities-and-workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 index 4b2058c5a..f89c62db9 100644 --- a/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md +++ b/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md @@ -45,6 +45,6 @@ flowchart TD ## Who can approve or decline pending orders? -- Employees with the "Can approve/decline all pending orders" permission can approve/decline all pending orders. -- Employees with the "Can approve/decline pending orders" permission can approve/decline pending orders that assigned to him. -- Business Partners can approve/decline all pending orders of their employees. \ No newline at end of file +- 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 From 97d8386d6fb7c59d532370631e817ecacdd209a5 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Mon, 15 Jan 2024 18:37:17 +0100 Subject: [PATCH 5/7] Update products/extensions/b2b-components/order-approval/02-order-approval-permissions.md --- .../order-approval/02-order-approval-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index d2c4778ee..9c6695428 100644 --- a/products/extensions/b2b-components/order-approval/02-order-approval-permissions.md +++ b/products/extensions/b2b-components/order-approval/02-order-approval-permissions.md @@ -10,7 +10,7 @@ nav: Below you can find a list of all the order approval rules that are available in the order approval component, which you can use to assign to the roles of your employees. -### Approval rule Permissions +### Approval rule permissions | Permission | Description | |-----------------------------|-----------------------------------------------| From 8528636a005e6f0ec1a385ffdb3e0354e2fe3d09 Mon Sep 17 00:00:00 2001 From: Su <112690947+sushmangupta@users.noreply.github.com> Date: Mon, 15 Jan 2024 18:37:25 +0100 Subject: [PATCH 6/7] Update products/extensions/b2b-components/order-approval/02-order-approval-permissions.md --- .../order-approval/02-order-approval-permissions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index 9c6695428..a9d5fd38f 100644 --- a/products/extensions/b2b-components/order-approval/02-order-approval-permissions.md +++ b/products/extensions/b2b-components/order-approval/02-order-approval-permissions.md @@ -14,10 +14,10 @@ Below you can find a list of all the order approval rules that are available in | 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. | +| `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 From d55c189748eb1aaba761790893606b62aae6c255 Mon Sep 17 00:00:00 2001 From: Dinh Duy Date: Tue, 16 Jan 2024 10:06:15 +0700 Subject: [PATCH 7/7] NEXT-32619 - Write document for order approval --- .../order-approval/01-entities-and-workflow.md | 5 ++--- .../order-approval/02-order-approval-permissions.md | 13 ++++++------- .../order-approval/03-payment-process.md | 6 ++---- .../order-approval/04-add-new-approval-condition.md | 4 ++-- .../b2b-components/order-approval/index.md | 2 +- 5 files changed, 13 insertions(+), 17 deletions(-) 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 index f89c62db9..21e6f6b9e 100644 --- a/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md +++ b/products/extensions/b2b-components/order-approval/01-entities-and-workflow.md @@ -12,7 +12,7 @@ nav: ### Approval Rule -The approval rule entity represents a set of conditions that need to be met in order for an order to be approved. These conditions can be based on the order's total value, the order's currency or for all orders placed by employees with a specific role. Each approval rule can be assigned the reviewer to a specific role, which means that only employees with that role can approve orders that match the rule's conditions, and it can be assigned to specific role, which means that only employees with that role will need to request approval for orders that match the rule's conditions; and a priority, which is used to determine the order in which the rules are evaluated. +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 @@ -32,10 +32,9 @@ flowchart TD E-->|Yes| G[Event: Order Approved & Event: Order placed] ``` - ## Who can request approval? -- Employees which have the role that is assigned as the "Effective role" of the approval rule that matched the order. +* 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? 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 index a9d5fd38f..53c889709 100644 --- a/products/extensions/b2b-components/order-approval/02-order-approval-permissions.md +++ b/products/extensions/b2b-components/order-approval/02-order-approval-permissions.md @@ -6,9 +6,8 @@ nav: --- # Order approval permissions -## Introduction -Below you can find a list of all the order approval rules that are available in the order approval component, which you can use to assign to the roles of your employees. +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 @@ -21,8 +20,8 @@ Below you can find a list of all the order approval rules that are available in ### 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 pending orders that assigned to him. | -| `Can view all pending orders` | Allows the employee to view all pending orders. | \ No newline at end of file +| 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 index d9a253d36..dbcd41327 100644 --- a/products/extensions/b2b-components/order-approval/03-payment-process.md +++ b/products/extensions/b2b-components/order-approval/03-payment-process.md @@ -5,11 +5,9 @@ nav: --- -# Order approval's Payment Process +# Order approval's payment process -## Introduction - -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, with the exception that if this is the online payment method (Visa, PayPal, etc.), the payment process will be executed only after the order has been approved. +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 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 index 47ae18b5e..7150d889f 100644 --- 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 @@ -7,11 +7,11 @@ nav: # How to add a new approval condition -The order approval component provides a set of conditions that you can use to define your approval rules. However, if you need to add a new condition, you can do so via app or plugin. +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` class. 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. +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: diff --git a/products/extensions/b2b-components/order-approval/index.md b/products/extensions/b2b-components/order-approval/index.md index e5f4807e9..00548984e 100644 --- a/products/extensions/b2b-components/order-approval/index.md +++ b/products/extensions/b2b-components/order-approval/index.md @@ -5,7 +5,7 @@ nav: --- -# Order Approval Component +# 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.