Package net.pricefx.common.dto

Class WorkflowDTO.ApprovalStepDTO

Object
WorkflowDTO.StepDTO<WorkflowDTO.ApprovalStepDTO>
ApprovalStepDTO
Enclosing class:
WorkflowDTO
public static class WorkflowDTO.ApprovalStepDTO extends WorkflowDTO.StepDTO<WorkflowDTO.ApprovalStepDTO>
An approval step of the workflow: the document must be approved (or denied) by the step's approvers before the workflow continues with the next step. Returned by WorkflowDTO.addApprovalStep(String).

The approvers are either users or user groups, not both. By default, one approval is enough; use withMinApprovalsNeeded(int) or withMinApprovalsForGroups(Integer...) to require more.

Example: 


 workflow.addApprovalStep("Sales Manager")
   .withApprovers("david.newman", "abhijit.gupta")
   .withMinApprovalsNeeded(2)
   .withReasons("Total Price is over threshold.")
See Also:

  • Constructor Details

  • Method Details

    • withApprover

      @Deprecated public WorkflowDTO.ApprovalStepDTO withApprover(String userLoginName)
      Deprecated.
      Use withApprovers(String...) instead.
      Last invoked of withApprover(String), withUserGroupApprover(String) wins
      Parameters:
      userLoginName - The login name of the approver
      Returns:
      The approval step itself.

    • withApprovers

      public WorkflowDTO.ApprovalStepDTO withApprovers(String... userLoginNames)
      Sets the users who approve this step. Last invoked of withApprovers(String...), withUserGroupApprovers(String...) wins

      By default, the step is approved when one of the users approves it. The same user cannot approve the document more than once, except a Workflow Admin.

      Example: 

      
 workflow.addApprovalStep("Sales Manager")
   .withApprovers("david.newman", "abhijit.gupta")
   .withReasons("Total Price is over threshold.")
      Parameters:
      userLoginNames - The login names of the approvers
      Returns:
      The approval step itself.
      See Also:

    • withNotificationOnlyToUsers

      public WorkflowDTO.ApprovalStepDTO withNotificationOnlyToUsers(String... userLoginNames)
      Subset of approvers that should receive the email notification

      Typically used when the step is assigned to a user group and only some of its members should be notified. The other approvers can still approve the step.

      Parameters:
      userLoginNames - The login names of the users to notify
      Returns:
      The approval step itself.
      See Also:

    • withUserGroupApprover

      @Deprecated public WorkflowDTO.ApprovalStepDTO withUserGroupApprover(String userGroupUniqueName)
      Deprecated.
      Use withUserGroupApprovers(String...) instead.
      Last invoked of withApprover(String), withUserGroupApprover(String) wins
      Parameters:
      userGroupUniqueName - The unique name of the approving user group
      Returns:
      The approval step itself.

    • withUserGroupApprovers

      public WorkflowDTO.ApprovalStepDTO withUserGroupApprovers(String... userGroupUniqueNames)
      Sets the user groups whose members approve this step. Last invoked of withApprovers(String...), withUserGroupApprovers(String...) wins

      Use withMinApprovalsForGroups(Integer...) to require a number of approvals from each group.

      Example: 

      
 workflow.addApprovalStep("Approval Step1")
   .withUserGroupApprovers("Sales Mgmt", "Regional Mgmt")
   .withMinApprovalsForGroups(1, 1)
      Parameters:
      userGroupUniqueNames - The unique names of the approving user groups
      Returns:
      The approval step itself.
      See Also:

    • withUserGroupApprover

      @Deprecated public WorkflowDTO.ApprovalStepDTO withUserGroupApprover(String userGroupUniqueName, boolean excludeSubmitter)
      Deprecated.
      Use withUserGroupApprovers(String...) together with withExcludeSubmitter(boolean) instead.
      Same as withUserGroupApprover(String) but the submitter is excluded in case they are a member of the group Last invoked of withApprover(String), withUserGroupApprover(String) wins
      Parameters:
      userGroupUniqueName - The unique name of the approving user group
      excludeSubmitter - true to exclude the submitter from approving
      Returns:
      The approval step itself.

    • withExcludeSubmitter

      public WorkflowDTO.ApprovalStepDTO withExcludeSubmitter(boolean excludeSubmitter)
      Set exclude submitter

      When true, the user who submitted the document cannot approve or deny this step, even as a member of an approving user group, and is not sent the group's approval notification.

      Parameters:
      excludeSubmitter - true to exclude the submitter, false otherwise
      Returns:
      The approval step itself.
      See Also:

    • setReason

      @Deprecated public WorkflowDTO.ApprovalStepDTO setReason(String reason)
      Deprecated.
      Use withReasons(String...) instead.
      Set an explanation reason for the approval step.
      Parameters:
      reason - The reason
      Returns:
      The approval step itself.

    • withReasons

      public WorkflowDTO.ApprovalStepDTO withReasons(String... reasons)
      Sets explanation reasons for approvers of the approval step.

      Example: 

      
 workflow.addApprovalStep("Approval Step1")
   .withApprovers("A1", "A2")
   .withReasons("Margin below 10%", "Discount above 20%")
      Parameters:
      reasons - The reasons why each approver needs to approve. The reasons match approvers, e.g. if you have 3 approvers (A1, A2, A3), you can specify up to 3 reasons (R1, R2, R3) and then reason R1 applies to approver A1, reason R2 applies to approver A2, etc. If you want to put multiple reasons to a single approver, you need to join the reason messages together into one string and provide such single combined reason for the approver.
      Returns:
      The approval step itself.
      See Also:

    • addProperty

      public WorkflowDTO.ApprovalStepDTO addProperty(String name, Object value)
      Adds a custom property to the step. The properties are stored with the workflow step.
      Parameters:
      name - The property name
      value - The property value
      Returns:
      The approval step itself.
      See Also:

    • withApprovalRequiredEmailAttachment

      public WorkflowDTO.ApprovalStepDTO withApprovalRequiredEmailAttachment(Object attachment)
      Adds one attachment, or a filter selecting attachments, to the approval-required email of this step. Same as withApprovalRequiredEmailAttachments(Object).
      Parameters:
      attachment - The attachment reference, see withApprovalRequiredEmailAttachments(Object)
      Returns:
      The approval step itself.

    • withApprovalRequiredEmailAttachments

      public WorkflowDTO.ApprovalStepDTO withApprovalRequiredEmailAttachments(Object attachments)
      Adds attachments of the document to the approval-required email of this step.

      Pass either the id, typedId or file name of one attachment of the document being approved, or a filter (a Filter or an advanced-criteria map) that selects several of its attachments. References that match no attachment are ignored. The number of attachments (2 by default) and their total size are limited by the server configuration; exceeding a limit fails the workflow.

      Example: 

      
 workflow.addApprovalStep("Finance Approval")
   .withApprovers("Mary")
   .withApprovalRequiredEmailAttachments("pricing-summary.pdf")
      Parameters:
      attachments - The attachment reference or filter, as described above
      Returns:
      The approval step itself.
      See Also:

    • getApprover

      @Deprecated public String getApprover()
      Deprecated.
      Use getApprovers() instead.
      Return the current approver in case of single approver set (or null if none set or if group approval)
      Returns:
      The user name

    • getApprovers

      public List<String> getApprovers()
      Return the current approvers (or null if none set or if group approval)
      Returns:
      The user names
      See Also:

    • getNotificationOnlyToUsers

      public List<String> getNotificationOnlyToUsers()
      Returns the subset of approvers that should receive email notification.
      Returns:
      The user names, or null if all approvers are notified
      See Also:

    • getReason

      @Deprecated public String getReason()
      Deprecated.
      Use getReasons() instead.
      Returns the reason text
      Returns:
      The reason

    • getReasons

      public List<String> getReasons()
      Returns the reasons text
      Returns:
      The reasons, or null if none were set
      See Also:

    • getExcludeSubmitter

      public Boolean getExcludeSubmitter()
      Returns status if the submitter is excluded in case of group approval
      Returns:
      true if excluded; null if not set
      See Also:

    • getUserGroupApprover

      @Deprecated public String getUserGroupApprover()
      Deprecated.
      Use getUserGroupApprovers() instead.
      Gets user group name in case of single group approval (or null otherwise)
      Returns:
      The user group unique name as a String, or null

    • getUserGroupApprovers

      public List<String> getUserGroupApprovers()
      Gets user group names in case of group approval (or null otherwise)
      Returns:
      The user group unique names as a List of String, or null
      See Also:

    • withMinApprovalsNeeded

      public WorkflowDTO.ApprovalStepDTO withMinApprovalsNeeded(int minApprovalsNeeded)
      A minimum number of approvals needed to consider this step as approved. Default is 1

      For a step assigned to users, assign at least as many users as the number of approvals needed.

      Example: 

      
 workflow.addApprovalStep("Sales Manager")
   .withApprovers("david.newman", "abhijit.gupta")
   .withMinApprovalsNeeded(2)
      Parameters:
      minApprovalsNeeded - The minimum number of distinct approvals
      Returns:
      The approval step itself.
      See Also:

    • withMinApprovalsForGroups

      public WorkflowDTO.ApprovalStepDTO withMinApprovalsForGroups(Integer... minApprovalsForGroups)
      A minimum number of approvals needed for each group, to consider this step as approved. Default is 0 for each group. If withMinApprovalsNeeded(int) is not set, the total number of approvals needed is the sum of these values.

      Example: 

      
 workflow.addApprovalStep("Approval Step1")
   .withUserGroupApprovers("Sales Mgmt", "Regional Mgmt")
   .withMinApprovalsForGroups(1, 2)
      Parameters:
      minApprovalsForGroups - The minimum number of approvals for each group, in the order of the groups passed to withUserGroupApprovers(String...)
      Returns:
      The approval step itself.
      See Also:

    • withPostStepLogic

      public WorkflowDTO.ApprovalStepDTO withPostStepLogic(String logicUniqueName)
      Sets post step logic name that should be run after this step is executed (i.e. Approved, Denied or Withdrawn)

      Example: 

      
 workflow.addApprovalStep("DefaultApproval")
   .withApprovers("user1")
   .withPostStepLogic("")
      Parameters:
      logicUniqueName - Workflow Post Step Logic unique name. If null, WorkflowDTO.withDefaultPostApprovalStepLogic(String) will be used, if empty string, no logic will be used even if there is WorkflowDTO.withDefaultPostApprovalStepLogic(String) set
      Returns:
      The approval step itself.
      See Also:

    • getPostStepLogicName

      public String getPostStepLogicName()
      Returns the post step logic set for this step.
      Returns:
      The logic unique name; an empty String if disabled, null if the default logic applies
      See Also:

    • withConditionRecordLogic

      public WorkflowDTO.ApprovalStepDTO withConditionRecordLogic(String logicUniqueName)
      Sets condition record logic name that should be run after final step is executed (i.e. Approved or Denied) or after each approved contract recalculation.

      Example – Condition Record logic defined at the level of a specific step. This means that you can run specific CR logic on deny, approve, and different for certain WF steps: 

      
 workflow.addApprovalStep("DefaultApproval")
                 .withApprovers("user1")
                 .withConditionRecordLogic("ApprovalCRLogic")
                 .withReasons("Standard approval")

      Example – disabling the default Condition Record logic by defining an empty string on the step: 

      
 workflow.addApprovalStep("DefaultApproval")
                 .withApprovers("user1")
                 .withConditionRecordLogic("")
                 .withReasons("Standard approval")
      Supported object types:
      • quote
      • pricegriditem
      • calculationgriditem
      • rebateagreement
      • contract
      • dcr
      • pricelist
      • rebaterecord
      • modelrecord
      • claim
      • dealplan
      • model
      • customform
      • compensation
      • compensationrecord
      • rebaterecordgroup
      Parameters:
      logicUniqueName - Condition Record Logic unique name. If null, WorkflowDTO.withDefaultConditionRecordLogic(String) will be used, if empty string, no logic will be used, even if there is WorkflowDTO.withDefaultConditionRecordLogic(String) set.
      Returns:
      The updated ApprovalStepDTO instance with the specified condition record logic.
      Since:
      13.0 - Rampur
      See Also:

    • getConditionRecordLogicName

      public String getConditionRecordLogicName()
      Returns the Condition Record logic set for this step.
      Returns:
      The logic unique name; an empty String if disabled, null if the default logic applies
      See Also:

    • getApprovalRequiredEmailAttachments

      public List<Object> getApprovalRequiredEmailAttachments()
      Returns the attachment references added by withApprovalRequiredEmailAttachments(Object).
      Returns:
      The attachment references and filters as a List; empty if none were added
      See Also:

    • toMap

      public Map<String,Object> toMap()
      Overrides:
      toMap in class WorkflowDTO.StepDTO<WorkflowDTO.ApprovalStepDTO>

    • fromMap

      public void fromMap(Map<String,Object> values)
      Overrides:
      fromMap in class WorkflowDTO.StepDTO<WorkflowDTO.ApprovalStepDTO>

    • withDenialReasons

      public WorkflowDTO.ApprovalStepDTO withDenialReasons(List<String> denialReasons, boolean isDenialReasonOptional)
      Denial Reasons is a list of predefined text options, which will be presented to the approver, while denying the item. The user would be able to either select one of them, or alternatively write free text reason. Providing the denial reasons can be optional or mandatory

      The reasons are added to any reasons defined earlier for this step. The flag overrides the value inherited from WorkflowDTO.withDenialReasons(List, boolean).

      Example: 

      
 workflow.addApprovalStep("step1")
   .withApprovers("admin")
   .withDenialReasons(["Price too low", "Missing information"], false)
      Parameters:
      denialReasons - Predefined workflow denial reasons
      isDenialReasonOptional - False, if the denial reasons should be mandatory
      Returns:
      The approval step itself.
      See Also:

    • getDenialReasons

      public List<String> getDenialReasons()
      Returns all denial reasons defined for this approval step
      Returns:
      The denial reasons as a List of String; empty if none were defined for this step
      See Also:

    • isDenialReasonOptional

      public boolean isDenialReasonOptional()
      Returns whether the denial reasons are optional in this approval step. If they're not optional, then they're mandatory
      Returns:
      true if denial reasons are optional, false if mandatory
      See Also:

    • getMinApprovalsNeeded

      public Integer getMinApprovalsNeeded()
      Returns the minimum number of approvers needed for this approval step
      Returns:
      The number set by withMinApprovalsNeeded(int); null if not set
      See Also:

    • getMinApprovalsForGroups

      public List<Integer> getMinApprovalsForGroups()
      Returns the minimum number of approvers needed for each user group in this step. The list is in the same order, in which is the list of Groups for this step
      Returns:
      The minimum approvals per group as a List of Integer; empty if not set
      See Also:

    • isMultiApprovalAllowed

      public Boolean isMultiApprovalAllowed()
      Returns whether a user who is a member of several approving groups can approve the step once for each group.
      Returns:
      The value set by withSingleUserMultiApprovalAllowed(boolean); null if not set (not allowed)
      See Also:

    • isParallelStepApprovalAllowed

      public Boolean isParallelStepApprovalAllowed()
      Returns whether a single approval can approve for all of the user's groups at once.
      Returns:
      The value set by withParallelStepApprovalAllowed(boolean); null if not set (not allowed)
      See Also:

    • getMandatoryComments

      public List<String> getMandatoryComments()
      Returns mandatory comments for this approval step
      Returns:
      The actions ("APPROVE", "DENY") that require a comment; null or empty if none
      See Also:

    • withMultipleApprovalByGroupsAllowed

      @Deprecated public WorkflowDTO.ApprovalStepDTO withMultipleApprovalByGroupsAllowed(boolean multipleApprovalByGroupsAllowed)
      Deprecated.
      Use withSingleUserMultiApprovalAllowed(boolean) instead.
      Same as withSingleUserMultiApprovalAllowed(boolean).
      Parameters:
      multipleApprovalByGroupsAllowed - When true, the user can approve the same step as many times as the group setting allows
      Returns:
      The approval step itself.

    • withSingleUserMultiApprovalAllowed

      public WorkflowDTO.ApprovalStepDTO withSingleUserMultiApprovalAllowed(boolean multiApprovalAllowed)
      Lets a user who is a member of several approving user groups approve or deny the step separately on behalf of each of those groups. By default, a user acts for one group only.

      Example: 

      
 workflow.addApprovalStep("Approval Step1")
   .withUserGroupApprovers("Sales Mgmt", "Regional Mgmt")
   .withMinApprovalsForGroups(1, 1)
   .withSingleUserMultiApprovalAllowed(true)
      Parameters:
      multiApprovalAllowed - When true, the user can approve the same step as many times as the group setting allows
      Returns:
      The approval step itself.
      See Also:

    • withParallelStepApprovalAllowed

      public WorkflowDTO.ApprovalStepDTO withParallelStepApprovalAllowed(boolean parallelStepApprovalAllowed)
      Lets a user who is a member of several approving user groups approve for all of them with one action.

      In the workflow dialog, the user approves for all their groups when no group is selected; the Approve button in the email does the same. Only works together with withSingleUserMultiApprovalAllowed(boolean).

      Example: 

      
 workflow.addApprovalStep("Approval Step1")
   .withUserGroupApprovers("Sales Mgmt", "Regional Mgmt")
   .withMinApprovalsForGroups(1, 1)
   .withParallelStepApprovalAllowed(true)
   .withSingleUserMultiApprovalAllowed(true)
      Parameters:
      parallelStepApprovalAllowed - When set to true and the multiApprovalAllowed option is enabled, the approver approves all parallel steps that the group he is a member of allows.
      Returns:
      The approval step itself.
      See Also:

    • withMandatoryComments

      public WorkflowDTO.ApprovalStepDTO withMandatoryComments(String... actions)
      Makes comment mandatory for certain actions.

      Example: 

      
 workflow.addApprovalStep("ApproverWithDefault")
   .withUserGroupApprovers("Group1", "Group2", "Group3")
   .withMandatoryComments("DENY", "APPROVE")
   .withMinApprovalsForGroups(1, 1, 2)
      Parameters:
      actions - for which comment is mandatory. This method accepts only values "APPROVE" and "DENY". Other values will be ignored.
      Returns:
      The approval step itself.
      See Also: