Approval Workflow - Handbook

This handbook covers the approval workflow. The approval workflow is used when creating new documents. Using the approval workflow, it is possible to create an approval process to notify selected users.

Business Use Case

The following is a use case appropriate for implementation of a Workflow:

The Pricing manager wants to create a centralized approval process which is defined by the roles of the team. Selected users will receive an email notification and the user is able to approve or deny, via the email, or in the Pricefx application. The process should have these conditions:
- Deals above the target margin are approved automatically.
- Deals between the target margin and the target floor will trigger the approval workflow.
- Deals below the floor can be rejected or sent for approval as defined by the customer.

Concept

Pricefx enables user approval for documents. Using the Approval Workflow we can add approvers who can either approve or deny the submitted documents but we can also add watchers who will just be notified. The Approval Workflow comes into play after the draft stage, when the document is submitted. The approvers are notified and then decide if they want to approve or deny the document and provide any reasons for their decision.

Figure 1. Placement of Approval Workflow in the Document Lifecycle Status. Example with a Quote.

Only the Quote status of Offer is invoked by workflow actions, while the remaining statuses are invoked by Quote actions.

Flow

Figure 2. Document Creation and Approval Workflow

As the workflow changes its status, the Quote, Rebate Agreement or Agreement/Promotion remains in the Draft status. After the workflow is approved, the Quote status changes to Offer, Rebate Agreement and Agreement/Promotion status changes to Approved. Additionally, workflow can end up in an Invalidated status. This happens when the workflow fails due to internal reasons.

States and Actions

Workflow logic defined in Workflow Builder is evaluated only when you submit a document and its state changes from Draft, Denied or Withdrawn to Submitted.

At that point a new workflow is generated (or the document passes through without approval).

'No approval required' happens when: * There is no workflow logic. * The workflow logic is evaluated and generates no approval step.

As the workflow changes its status, the Quote, Rebate Agreement or Agreement/Promotion remains in the Draft status. After the workflow is approved, the Quote status changes to Offer, Rebate Agreement and Agreement/Promotion status changes to Approved. Additionally, workflow can end up in an Invalidated status. This happens when the workflow fails due to internal reasons.

The Approver, who was notified by email, can approve or deny in three different ways:

Directly from the email, using the direct Approval or Denial link.
On the screen with the detail of the Quote, open the Workflow there and approve using the green button.
On a special screen found in menu User Profile › My Workflows, find the Quote document, and approve it.

Approvable Documents

The following document types can have a workflow:

Quote
Agreement/Promotion
Rebate Agreement
Rebate Record
Price Grid Item
Price List
Data Change Request
Ship and Debit Claim
Compensation Plan
Compensation Record
Standalone Custom Form
Optimization Model

Logic

The workflow logic verifies business conditions or thresholds which determine whether a document needs to go for an approval. The logic generates a sequence of Approval Steps which are of two types: Approval step and Watcher step.

Workflow logic is created similar to other logics, with the important exception that you check the radio button for "Workflow logic" instead of "Pricing logic" and then you pick the Workflow type according to the document you want to create the workflow for.

Binding Variables

Workflow logic will have the following binding variables available:

Document type variable - There you can access the document via binding variable called “quote”, “pricelist”, “pricegriditem”, “rebateagreement”, “contract”, “dcr”, “rebaterecord”, depending on the document for which you write the workflow logic. Provides ability to access and loop thru the individual line items in the document (folders and products).
Workflow - The Steps you can create using the object WorkflowDTO (DTO=DataTransferObject) are accessible via variable “workflow”. This object retains all of the approval steps and the ability to modify them. So it allows you to add Approval and Watcher Steps, and further you can setup those Approval steps to have specific users, reasons, etc.
Submitter - A Groovy Map object that contains all of the submitters for a specific workflow.

Build Steps

The logic builds the Workflow steps based on the information found in the document (for example a Quote), which needs the approval.

The Workflow logic is executed every time, when the user clicks on the button “View Workflow” and then also when the User submits the document for approval.

Code snippet of adding an approval step

workflow.addApprovalStep("Sales Manager")
        .withApprovers("john.price")
        .withReasons("Sales manager needs to approve this quote")

This code example is from an element called BuildSteps which adds a step in the approval workflow.

When the Workflow logic cannot find important data needed for building the approval steps, then it should throw an exception, which immediately stops the submission process.

    if(!lineItemTotalInvoicePrice){
        api.throwException("Unable to build workflow. Missing Total Invoice Price")
    }

Every workflow step can be either Approver or a Watcher. Approver will be requested to Approve or Deny, whereas a Watcher will only be notified but the workflow will not wait for them and it will continue to next step.

The Workflow Step can be a Group of users (defined in User Group administration) or a set of specific users. You can also specify, how many users must Approve so that the Step is actually approved and the flow can continue to the next step.

And, of course, users would like to know “why” they are required to approve, so it is a good practice to provide a Reason.

Testing

As with any other logic, it is advised to test it in IntelliJ before deployment.

For a demonstration, let’s use an Approval workflow for Quotes. Since we are using Quotes, the context of the logic will be Quote. When testing Approval workflow for different documents it is important to select the correct Context based on the document.

Set the parameters, use a Quote which exists in your partition.
Test the logic and view the results.
1. In the Results view, double-click on the box as indicated in the screen capture (to the right of the last row, beneath the binoculars).
2. Switch tab to Grid → Examine the results.

Server Configuration

After the deployment of the logic, you need to configure your Pricefx application to use it.

As an example with a Quote, you can assign the new Workflow logic into the “Default” Quote Type. Navigate to Quoting › Quote Types and assign the new Workflow logic to the ( Default ) Quote Type.

You can configure your workflows in the Administration › Configuration › System Configuration › My Workflows.

After the configuration of the document, you need to fetch these setting into the project. The reason for this is that all the settings must also be in Git, otherwise it will not get to QA and PROD.

Summary

Approval Workflow is a powerful tool used to either add approval steps or to notify desired users. Use it to create approval processes defined by your specific business needs for any approvable document.