This article describes how to add an optional approval step(s) called Request for status change, to a workflow. It also explains how to use AutoRequest so that once one request is completed, a subsequent request is triggered automatically.


Prerequisites


Request to Change Status

A <Request> tag is used to add one approval step for issues moving from one status to another status. This tag is required to activate the request process. It is placed in the "target" <Status>, i.e., the status that the issues are moving to. A <Status> can have one <Request> element.


In the simple example below, issues following this workflow and transitioning from "New" status trigger a Request for status change to "In progress" status. 

<Workflow initialStatus="New">
  <Status name="New">
    <NextStatuses>
      <NextStatus name="In progress"/>
    </NextStatuses>
  </Status>

  <Status name="In progress">
      <Request>
      </Request>
      <NextStatuses>
      <NextStatus name="New"/>
    </NextStatuses>
  </Status>
</Workflow>

The Request configuration has three available options: Assignees, Auto-completion, and Restrictions.


Pre-defined Assignees

The <Users> tag can be used to configure who shall be assigned to review the status change request. It is placed in the <Request> in the "target" <Status>. The Assignees list (i.e., those who are assigned to review the request), is defined by the required select attribute which executes a valid Path expression that results in a list.


In the below example, issues transitioning from "In progress" status trigger a Request for status change to the "Validation" status. Upon triggering the request, the users pre-selected in the Set of Users attribute with SID=TEST on the issue are assigned to review the status change request. It's important to note that the users must be set in the attribute prior to triggering the request. 

<Workflow initialStatus="In progress"/>
  <Status name="In progress">
  <NextStatuses>
    <NextStatus name="Validation"/>
  </NextStatuses>
</Status>

<Status name="Validation">
  <NextStatuses>
    <NextStatus name="In progress"/>
  </NextStatuses>
  <Request>
    <Users select="@TEST"/>
  </Request>
  </Status>
</Workflow>

Auto-completion of Requests

The <Complete> tag can be used to define a condition (e.g., more than 1 assignee has approved the request) that must be fulfilled for a status change request to be auto-completed, i.e., moved to the "target" status. It is placed in the <Request> in the "target" status(es). Because it auto-completes, there is no need to click the Complete request button once the review is completed. It has two attributes.  

  • The status attribute is optional, and defines which status the issue will be set to if the condition is met. The status does not need to be the next status in the workflow; it can be set to any valid status in the workflow.  
  • The test attribute is required, and defines a SystemWeaver Path expression that must evaluate to true. 


In this example, a request to transition from "New" to "In progress" will be completed automatically as soon as one or more assignees approve the request. And, if one or more assignees reject the request, the issue will be moved to the "Blocked" status.

<Workflow initialStatus="New">
  <Status name="New">
    <NextStatuses>
      <NextStatus name="In progress"/>
    </NextStatuses>
  </Status>

  <Status name="In progress">
    <NextStatuses>
      <NextStatus name="New"/>
    </NextStatuses>
    <Request>
      <Users select="@DEVV"/>/>
      <Complete status="In progress" test="ActiveRequest.RequestAcks[AckStatus.ToString ='Approved'].Count > 0"/>
      <Complete status="Blocked" test="ActiveRequest.RequestAcks[AckStatus.ToString = 'Rejected'].Count > 0"/>
    </Request>
  </Status>

  <Status name="Blocked">
    <NextStatuses>
      <NextStatus name="In progress"/>
    </NextStatuses>
  </Status>  
</Workflow>

Restrictions on Requests

The <Restrictions> element, as described in Defining a Workflow Configuration, can be set on Request for status change. Restrictions on requests are configured in the "source" status, i.e., in the <Status> that the issue is moving from. By default (i.e., without restrictions), all operations are available. For a complete list of the fields that can be restricted related to Request for status change, see Restrictions in the swExplorer Reference Manual in the application Help.


In this example, status change requests for issues moving from "New" to "In progress" must be reviewed, and to reject, assignees must include a comment. Requests for issues moving from "In progress" to "Ready for test" must also be reviewed, and to approve or to reject, assignees must include a comment. 

<Workflow initialStatus="New">
  <Status name="New">
    <NextStatuses>
      <NextStatus name="In progress"/>
    </NextStatuses>
    <Restrictions>
      <Restriction field="Reject" test="false"/>
    </Restrictions>
  </Status>

  <Status name="In progress">
    <NextStatuses>
      <NextStatus name="Ready for test"/>
    </NextStatuses>
    <Request>
      <Users select="CurrentUser"/>
    </Request>
    <Restrictions>
      <Restriction field="Approve" test="false"/>
      <Restriction field="Reject" test="false"/>
    </Restrictions>
  </Status>

  <Status name="Ready for test">
    <NextStatuses>
      <NextStatus name="Done"/>
    </NextStatuses>
    <Request>
      <Users select="@TEST"/>
    </Request>
  </Status>
</Workflow>

Auto-transition to Next Request

<AutoRequest> can be used to transition issues automatically to a next Request in the workflow, when the current Request is completed, either manually or through auto-completion.


The tag is added to the "source" status, and requires the existence of <Request> in the next status. It has two attributes. 

  • The status attribute is required, and defines which status the issue will be set to if the condition is met. The status does not need to be the "target" status; it can be set to any valid status in the workflow. 
  • The test attribute is optional, and defines a SystemWeaver Path expression that must evaluate to true. 


The below example is completely automated with the exception of the assignees approving or rejecting the requests. Once a request is completed, it triggers the next request, etc. 

<Workflow initialStatus="New">
 <Status name="New">
  <NextStatuses>
   <NextStatus name="In progress"/>
  </NextStatuses>
  <AssignedTo user="CurrentUser"/>
 </Status>
 
 <Status name="In progress">
  <Request>
   <Users select="User('debby.clark')"/>
   <Complete status="In progress" test="ActiveRequest.RequestAcks[AckStatus.ToString ='Approved'].Count > 0"/>
   <Complete status="Blocked" test="ActiveRequest.RequestAcks[AckStatus.ToString = 'Rejected'].Count > 0"/>
  </Request>
  <NextStatuses>
   <NextStatus name="Ready for test"/>
  </NextStatuses>
  <AutoRequest status="Ready for test"/>
 </Status>
 
 <Status name="Ready for test">
  <Request>
   <Users select="User('tracy.klein')"/>
   <Complete status="Ready for test" test="ActiveRequest.RequestAcks[AckStatus.ToString ='Approved'].Count > 0"/>
   <Complete status="Blocked" test="ActiveRequest.RequestAcks[AckStatus.ToString = 'Rejected'].Count > 0"/>
  </Request>
  <NextStatuses>
   <NextStatus name="Done"/>
  </NextStatuses>
  <AutoRequest status="Done"/>
 </Status>
 
 <Status name="Blocked">
  <NextStatuses>
   <NextStatus name="In progress"/>
    <NextStatus name="Ready for test"/>  
   <NextStatus name="Done"/>
  </NextStatuses>
 </Status>
 
 <Status name="Done">
  <Request>
   <Users select="User('jim.smith')"/>
   <Complete status="Done" test="ActiveRequest.RequestAcks[AckStatus.ToString ='Approved'].Count > 0"/>
   <Complete status="Blocked" test="ActiveRequest.RequestAcks[AckStatus.ToString = 'Rejected'].Count > 0"/>
  </Request>
  <NextStatuses>
   <NextStatus name="In progress"/>
  </NextStatuses>
 </Status>
</Workflow>