Setting Up Approval Profile Actions in the SAM Workflow

You use the Approval Profile Actions dialog box to set up the approval profile actions for the SAM workflow steps. In this dialog box, you can define the actions and their results when the listed conditions are met. The results include:

Update the Approval Request’s status
Send notification email
Update fields on the associated issue tracking system record
Execute an SCM delivery script

The following table describes the fields in the Approval Profiles Action dialog box.

Field/Column	Description
Action Name	The action name will be the name of the action button that is displayed in the Approval Request page.
Result Status	The status of the approval request. When a user clicks on this action button, the status of the Approval Request page will be updated to this value. For example, assume that the value in the Action Name field is Save Draft and the value in the Result Status is Draft. When users click Save Draft on the Approval Request page, the approval request is saved and its status changes to Draft.
Validate?	Selection indicates that the approval request must be validated against the values in the Validation Values column. If the approval request does not pass the validation, then this action button will be disabled.
Default Submit?	When in Multiple Issue Approval mode, selection indicates that this action will be executed for the child request when the Submit for the original record is executed.
Validate SCM?	Selection indicates that the approval request must be validated against the values that users entered in the SCM Profile section on the Approval Request Details page. Note: There must be at least one entry in the SCM Profile section. If there are no entries, then the button will still be disabled even though there are no SCM validation errors.
Approve?	Selection indicates that the action that is set in the Action Name field is an Approval action. The approval requests that have an action that has Approve? selected and meet the conditions in this workflow step for the currently logged in user will be displayed in the Pending My Approval list on the SAM home page.
Email To	The role or roles to receive the notification emails once this action is executed.
Email Cc	The role or roles of any other recipient to receive the notification emails once this action is executed.
Email Subject	The template of email subject to be used to send email to the owner. For more information, see Specifying Messages.
Email Body	The template of email body to be used to send email to the owner. For more information, see Specifying Messages.
Action Id	The REST API action ID as a unique identifier for this profile’s action. This field is read-only and populated after the action has been initially saved. It can be used by external systems to execute an action through a SAM REST API. For example, if the current action is Save Draft, then the administrator can call a REST API that executes the Save Draft action on a particular request. For more information, see REST APIs for SAM.

The following table describes the fields in the Update section.

Field/Column	Description
Update Type	The type of system that will be updated : either Issue Tracking or SCM. For Issue Tracking systems, SAM will update the specified field to a given value. For SCM systems, SAM will execute the REST API defined in this system's Write/Delivery Method. If you have multiple update entries for the same system, then it will only execute once, passing the arguments specified in the different update entries in that single call.
External System	The name of the system that will be updated. Only systems that have a Write/Delivery Method defined in the System Administration page are shown here.
Field	Issue Tracking systems. The field (belonging to the selected External System) that will be updated. SCM systems. The name of the SCM field/argument (as defined in the System Administration page) to pass to the Write/Delivery Method.
Value Type	The Exact Value or Message (see the following for Value).
Value	Issue Tracking systems. If the Value Type is set to Exact Value, then the value used to update the selected Field is the exact string that is entered here is. If the Value type is set to Message, then the value used to update the selected Field is the evaluated message (as defined in Message Administration) that is selected here. For example, this section enables users to write comments or status back to the third-party issue tracking systems. For example, if, The action name is Submit for Approval. The update type is Issue Tracking. The external system is Sample Bug System. The field is Description. The value type is Exact Value. The value text is comment This bug has been submitted. Then, when users click Submit for Approval on the Approval Request Details page, the SAM application executes the Sample Bug System’s Write/Delivery REST API to update the Description field to This bug has been submitted. SCM systems. If the Value Type is set to Exact Value, then the value that is sent as an argument is the exact string that is entered here is. If the Value type is set to Message, then the value that is sent as an argument is the evaluated message (as defined in Message Administration) that is selected here. For SCM delivery using SCM entry details (as collected in the Approval Request page), the built in field called source is to be defined in Message Administration screen. This Message is then selected to make the value passed to the Field selected. Note: This feature is only supported in 2.17.10 and onwards. For example, to create deliver a workspace change upon a request’s approval, do the following: Prerequisites: You have configured the Write/Delivery Method and Fields as described in the System Administration example. You have created the message Source for Workspace Delivery with the text {source}. Add a new update row. In the new row, for Update Type, select SCM. For External System, select your SCM system. For Field, select the SCM field that will be mapped to the source. For Value Type, select Message. For Value, select Source. Note: If you have more than one update entry specified for a single SCM system, then that system’s Write/Delivery API will be invoked only once, passing all of the fields specified in the various update entries in a single URL call.

To add a new approval profile action or modify an existing one

From the SAM home page, select the Main Menu button.
Select the Administration option.
Select the Approval Profiles option from the Administration drop-down list.
The Approval Profiles page appears.
Scroll down to the Workflow section and click the Add Action button (the plus sign that is next to the action in the Actions column) for the starting status that you want to add actions.
Alternatively, to modify an existing approval action, click the action link for the starting status that you want to modify.
The Approval Profile Actions dialog box appears.
Enter an action name in the Action Name field.
The action name will be the name of the action button that is displayed in the Create Approval Request page.
In the Result Status drop-down list, select an option from the list of available statuses.
Optionally, define the following values on the Approval Profile Actions page.
1. Select the Validate option to indicate that the approval request must be validated against the values in the Validation Values column. If the approval request does not pass the validation, then this action button will be disabled.
  Notice that the Validation Values and the Validation Messages columns are in the Fields section on the Approval Profiles page.
2. Select the Default Submit option when in Multiple Issue Approval mode to indicate that this action will be executed for the child request when the Submit for the original record is executed.
3. Select the Validate SCM option to indicate that the approval request must be validated against the values that users entered in the SCM Profile section on the Approval Request Details page.
  Note: There must be at least one entry in the SCM Profile section. If there are no entries, then the button will still be disabled even though there are no SCM validation errors.
4. Select the Approve option to indicate that the action that is set in the Action Name field is an Approval action.
5. Enter the role names into the Email To and Email CC fields so the users with those roles will receive the notification emails once this action executed.
6. Select the email subject and email body using the template in the Email Body and Email Subject fields. For more information, see Specifying Messages.
7. For existing actions, take note of the Action Id value if you will be using the SAM API to execute this action via a REST call.
8. Define the values in the Update section to specify updates to the issue tracking systems or run scripts on the SCM systems that are executed once the users perform this action. For more information on Update section fields, see Setting Up Approval Profile Actions in the SAM Workflow.
Click Save.