Package net.pricefx.common.dto

Class WorkflowDTO

Object
WorkflowDTO
public class WorkflowDTO extends Object
This class is basically the type of object, which is exposed in the workflow logic by the binding variable workflow

In your workflow logic you would call methods on that class instance to add approval nodes and/or watcher nodes and supply further details

The methods are designed to be used in a simple flow pattern.

You never create this object yourself. It is available in a logic of type Workflow with the Default nature, which is executed when a document is submitted for approval. The document itself is available as the approvable binding variable, and the user who submitted it as submitter. If the logic throws an exception, no workflow steps are built and the submit operation is canceled.

Simple example: 


 workflow.addApprovalStep("First Approval").withApprovers("admin").withReasons("Admin needs always approve")
See Also:

  • Constructor Details

    • WorkflowDTO

      public WorkflowDTO(WorkflowType type, String typedId, String submitReason, boolean isMassUpdate)

    • WorkflowDTO

      public WorkflowDTO(WorkflowType type, String typedId)

  • Method Details

    • addApprovalStep

      public WorkflowDTO.ApprovalStepDTO addApprovalStep(String uniqueName)
      Adds a new approval step at the end of the approval workflow.
      The isDenialReasonOptional() flag value is inherited from the approval workflow and can be changed by withDenialReasons(List, boolean)

      The flag is copied when the step is added, so call withDenialReasons(List, boolean) before adding the steps that should inherit it.

      Example: 

      
 def total = out.TotalPriceValue
 if (total != null && total > 1000) {
   workflow.addApprovalStep("approval")
     .withApprovers("Mary", "Bob")
     .withReasons("Total Price went over threshold.")
 }
      Parameters:
      uniqueName - Name of the step, it must be unique inside one approval workflow. If an approval step with the same unique name already exists, the existing step is kept and the new step is not added to the workflow. Use getStep(String) to change a step added earlier.
      Returns:
      The Approval Step itself, but if an approval step with this name already exists, the returned object is not part of the workflow and settings chained on it have no effect; use getStep(String) instead.
      See Also:

    • addWatcherStep

      public WorkflowDTO.WatcherStepDTO addWatcherStep(String uniqueName)
      Adds a watcher step to the end of the approval workflow. A watcher step cannot approve or deny, but will receive a notification when it becomes active.

      Example: 

      
 workflow.addWatcherStep("Review")
   .withUserGroupWatchers("Managers")
   .withReasons("Status update")
      Parameters:
      uniqueName - Name of the step. It must be unique inside one approval flow. If a watcher step with the same unique name already exists, the existing step is kept and the new step is not added to the workflow. Use getStep(String) to change a step added earlier.
      Returns:
      The Watcher Step itself, but if a watcher step with this name already exists, the returned object is not part of the workflow and settings chained on it have no effect; use getStep(String) instead.
      See Also:

    • getType

      public WorkflowType getType()
      Returns the type of the workflow. Corresponds to the underlying approvable document:
      • QUOTE("quote")
      • PRICEGRIDITEM("pricegriditem")
      • CALCULATIONGRIDITEM("calculationgriditem")
      • REBATEAGREEMENT("rebateagreement")
      • CONTRACT("contract")
      • DATACHANGEREQUEST("dcr")
      • PRICELIST("pricelist")
      • REBATERECORD("rebaterecord")
      • MODELRECORD("modelrecord")
      • CLAIM("claim")
      • MODEL("model")
      • CUSTOMFORM("customform")
      • COMPENSATION("compensation")
      • COMPENSATIONRECORD("compensationrecord")
      • REBATERECORDGROUP("rebaterecordgroup")
      • IMPORTMANAGER("importmanager")
      • PRICINGPLANREVISION("pricingplanrevision")

      Example: 

      
 if (workflow.getType().name() == "QUOTE") {
   workflow.addApprovalStep("Sales Manager").withApprovers("admin")
 }
      Returns:
      The Type of the Workflow.

    • removeStep

      public boolean removeStep(String uniqueName)
      Removes the approval step with the given name (if it exists).

      Example: 

      
 workflow.addApprovalStep("Optional Approval").withApprovers("admin")
 if (out.TotalPriceValue < 1000) {
   workflow.removeStep("Optional Approval")
 }
      Parameters:
      uniqueName - The name of the step
      Returns:
      true if a step was removed, false if no matching step was found
      See Also:

    • getStep

      public WorkflowDTO.StepDTO getStep(String uniqueName)
      Retrieves a workflow step with given name (if it exists)

      Use it to change a step that was added earlier in the logic.

      Example: 

      
 def step = workflow.getStep("approval")
 if (step != null) {
   step.withEmailAttachment(true)
 }
      Parameters:
      uniqueName - The name of the step
      Returns:
      The approval or watcher step with the given name as a StepDTO, or null if there is none
      See Also:

    • getSubmitReason

      public String getSubmitReason()
      Gets reason entered by submitter
      Returns:
      The comment entered by the submitter when submitting the document, as a String; null if none was entered
      See Also:

    • setSubmitReason

      public void setSubmitReason(String submitReason)
      Overrides reason entered by submitter

      The workflow stores this value instead of the comment the submitter entered.

      Example: 

      
 if (!workflow.getSubmitReason()) {
   workflow.setSubmitReason("Submitted without comment")
 }
      Parameters:
      submitReason - The submit reason to store, as a String
      See Also:

    • addItemReason

      public void addItemReason(String itemTypedId, String reason)
      Adds an approval reason for an individual item of the document being approved.

      Note: The item reasons are currently only applied to Data Change Request (DCR) items. For all other document types they are ignored.

      Example: 

      
 workflow.addItemReason(dcrItemTypedId, "Price change above 10%")
      Parameters:
      itemTypedId - The typedId of the item as a String
      reason - The approval reason for that item as a String
      See Also:

    • getItemReasons

      public Map<String,String> getItemReasons()
      Returns the item approval reasons added by addItemReason(String, String).
      Returns:
      A map of item typedId to approval reason; null if no item reason was added
      See Also:

    • withDenialReasons

      public WorkflowDTO withDenialReasons(List<String> denialReasons, boolean isDenialReasonOptional)
      Defines denial reasons for the whole workflow. Denial Reasons is a list of predefined text options presented to the approver when denying the document.

      The reasons are added to any reasons defined earlier. The isDenialReasonOptional flag is inherited by the approval steps added after this call. A step can define its own reasons and flag with WorkflowDTO.ApprovalStepDTO.withDenialReasons(List, boolean).

      Example: 

      
 workflow.withDenialReasons(["Price too low", "Missing information"], false)
 workflow.addApprovalStep("step1").withApprovers("admin")
      Parameters:
      denialReasons - Predefined workflow denial reasons as a List of String
      isDenialReasonOptional - false if selecting or entering a denial reason should be mandatory
      Returns:
      The workflow itself, for chaining further settings
      See Also:

    • getDenialReasons

      public List<String> getDenialReasons()
      Returns the denial reasons defined for the whole workflow.
      Returns:
      The workflow-level denial reasons as a List of String; empty if none were defined
      See Also:

    • isDenialReasonOptional

      public boolean isDenialReasonOptional()
      Returns whether denial reasons are optional at the workflow level.
      Returns:
      true (the default) if denial reasons are optional, false if they are mandatory
      See Also:

    • getTypedId

      public String getTypedId()

    • getSteps

      public LinkedHashSet<WorkflowDTO.StepDTO> getSteps()

    • withAddStepRestrictedToWFAdmin

      public WorkflowDTO withAddStepRestrictedToWFAdmin()
      Restricts adding extra approval or watcher steps to the running workflow to Workflow Admins only. Same as withAddStepRestrictedToWFAdmin(true).

      Example: 

      
 workflow.withAddStepRestrictedToWFAdmin()
   .addApprovalStep("Approver")
   .withApprovers("admin")
      Returns:
      The workflow itself, for chaining further settings
      See Also:

    • withAddStepRestrictedToWFAdmin

      public WorkflowDTO withAddStepRestrictedToWFAdmin(boolean isAddStepRestrictedToWFAdmin)
      Sets whether adding extra approval or watcher steps to the running workflow is restricted to Workflow Admins.
      Parameters:
      isAddStepRestrictedToWFAdmin - true to allow only Workflow Admins to add steps, false (the default) to allow the other users too
      Returns:
      The workflow itself, for chaining further settings
      See Also:

    • isAddStepRestrictedToWFAdmin

      public boolean isAddStepRestrictedToWFAdmin()
      Returns whether adding extra steps to the running workflow is restricted to Workflow Admins.
      Returns:
      true if only Workflow Admins can add steps, false otherwise (the default)
      See Also:

    • withSelectStepOnDeny

      public WorkflowDTO withSelectStepOnDeny(boolean isSelectStepOnDeny)
      Lets the approver select, when denying the document, the step from which the workflow restarts after the document is submitted again.

      The approver can pick a step in the deny dialog or leave the selection empty. The selected step name is available in the next run of the workflow logic as selectedStepOnDeny of api.findPreviousWorkflowInfo(); the logic decides which steps to mark as already satisfied.

      Example: 

      
 def previous = api.findPreviousWorkflowInfo(quote.typedId, "DENIED")
 workflow.withSelectStepOnDeny(true)
   .addApprovalStep("Sales Manager")
   .withApprovers("John Newman")
   .withAlreadySatisfied(previous?.selectedStepOnDeny == "Account Manager" ? "Skipped" : null)
      Parameters:
      isSelectStepOnDeny - true to let the approver select the step, false (the default) otherwise
      Returns:
      The workflow itself, for chaining further settings
      See Also:

    • isSelectStepOnDeny

      public boolean isSelectStepOnDeny()
      Returns whether the approver can select the step to restart from when denying the document.
      Returns:
      true if the step selection is enabled, false otherwise (the default)
      See Also:

    • getDataMap

      public Map<String,Object> getDataMap()
      Returns the additional data available in the workflow email templates.
      Returns:
      The data map as a Map; empty if no data was set
      See Also:

    • withDataMap

      public WorkflowDTO withDataMap(Map<String,Object> dataMap)
      Sets dataMap map, which is available then in email templates

      The map replaces any data map set earlier.

      Example: 

      
 workflow.withDataMap([region: "EMEA", totalPrice: out.TotalPriceValue])
      Parameters:
      dataMap - The map with additional data needed to render the template.
      Returns:
      The workflow itself, for chaining further settings
      See Also:

    • withDefaultPostApprovalStepLogic

      public WorkflowDTO withDefaultPostApprovalStepLogic(String postApprovalStepLogicUniqueName)
      Sets a logic that will be executed after every approval step.

      The logic is a Workflow Post Step logic. It runs after each approval step is approved, denied or withdrawn, unless the step sets its own logic with WorkflowDTO.ApprovalStepDTO.withPostStepLogic(String) or disables it with withPostStepLogic(""). Calling this method again replaces the logic.

      Example: 

      
 workflow.withDefaultPostApprovalStepLogic("DefaultPostLogic")

 workflow.addApprovalStep("DefaultApproval")
   .withApprovers("user1")
   .withPostStepLogic("")
      Parameters:
      postApprovalStepLogicUniqueName - Unique name of wf post step logic
      Returns:
      The workflow itself, for chaining further settings
      See Also:

    • getDefaultPostApprovalStepLogicName

      public String getDefaultPostApprovalStepLogicName()
      Returns the unique name of the default post step logic.
      Returns:
      The logic unique name as a String; null if none was set
      See Also:

    • withDefaultConditionRecordLogic

      public WorkflowDTO withDefaultConditionRecordLogic(String conditionRecordLogicName)
      Adds a logic that will be executed after the final approval step or after each approved contract recalculation.

      Example – Condition Record logic defined as a part of the Workflow Logic definition: 

      
 workflow.withDefaultConditionRecordLogic("DefaultCRLogic")
      Supported object types:
      • quote
      • pricegriditem
      • calculationgriditem
      • rebateagreement
      • contract
      • dcr
      • pricelist
      • rebaterecord
      • modelrecord
      • claim
      • dealplan
      • model
      • customform
      • compensation
      • compensationrecord
      • rebaterecordgroup
      Parameters:
      conditionRecordLogicName - Unique name of the condition record logic to be executed.
      Returns:
      The updated WorkflowDTO instance with the specified condition record logic.
      Since:
      13.0 - Rampur
      See Also:

    • getDefaultConditionRecordLogicName

      public String getDefaultConditionRecordLogicName()
      Returns the unique name of the default Condition Record logic.
      Returns:
      The logic unique name as a String; null if none was set
      Since:
      13.0 - Rampur
      See Also:

    • withRunDefaultPostApprovalStepLogicOnEmptyWorkflow

      public WorkflowDTO withRunDefaultPostApprovalStepLogicOnEmptyWorkflow(boolean runDefaultPostStepLogicOnEmptyWorkflow)
      Decides if default post step logic should be executed also in case the wf has no approval steps (i.e. empty or all steps are watcher steps).

      Example: 

      
 workflow
   .withDefaultPostApprovalStepLogic("myDefaultPostStepLogic")
   .withRunDefaultPostApprovalStepLogicOnEmptyWorkflow(true)
      Parameters:
      runDefaultPostStepLogicOnEmptyWorkflow - Default is false.
      Returns:
      The workflow itself, for chaining further settings
      See Also:

    • getRunDefaultPostApprovalStepLogicOnEmptyWorkflow

      public boolean getRunDefaultPostApprovalStepLogicOnEmptyWorkflow()
      Returns whether the default post step logic also runs when the workflow has no approval steps.
      Returns:
      true if it runs on an empty workflow, false otherwise (the default)
      See Also:

    • withAutoConvertToDeal

      public WorkflowDTO withAutoConvertToDeal(boolean autoConvertToDeal)
      If true then automatically converts quote to deal when quote is approved

      This also applies when the quote needs no approval. If this method is not called, the autoConvertQuotes configuration setting decides. Only applies to Quotes.

      Example: 

      
 workflow.withAutoConvertToDeal(true)
      Parameters:
      autoConvertToDeal - flag if should be automatically converted
      Returns:
      The workflow itself, for chaining further settings
      See Also:

    • isAutoConvertToDeal

      public Boolean isAutoConvertToDeal()
      Returns whether the quote is automatically converted to a deal when approved.
      Returns:
      true or false if set by withAutoConvertToDeal(boolean); null if not set, in which case the autoConvertQuotes configuration setting applies
      See Also:

    • isMassUpdate

      public boolean isMassUpdate()
      Tells whether the workflow logic runs because the document was submitted by a mass update job.

      Example: 

      
 if (!workflow.isMassUpdate()) {
   workflow.addApprovalStep("Manual Review").withApprovers("admin")
 }
      Returns:
      true If workflow is called from mass update job