5Configuring Siebel Approval Manager
Configuring Siebel Approval Manager
If you are assigned the Siebel Approval Manager Administrator role, you can use the Administration option from the Main Menu to perform Siebel Approval Manager (SAM) administrative tasks.
This chapter describes how to perform SAM administrative tasks. This chapter includes the following topics:
Adding Users
Use the Users page to add new users into the SAM application. The following table describes the fields in the Users page.
Table Fields in Users page
| Field/Column | Description |
|---|---|
Add (plus) button |
Click this button to add a new user. |
Name column |
This column contains the displayed name for the given SAM user. |
Email Address column |
This column lists the email address for the given SAM user. Note that the email address must be unique for each user ID |
Manager column |
This column lists the default approving manager for the given SAM user. The named manager is the approver for requests that are created by the given user when the approver is configured as Approving Manager. |
Roles column |
This column lists the roles that the given SAM user has. You can click the values here to modify the roles of that user. |
Reset Password column |
Click the Reset Password button to reset the password of the corresponding user and send the same user an email notification with a new, random password. |
Delete button |
Click the Delete button to delete the corresponding user from the SAM application |
To add a new user
From the SAM Home page, select the Main Menu button.
Select the Administration option.
Select the Users option from the Administration drop-down list.
The Users page appears.
Click the Add button in the Users page.
Enter the user name and email address.
Select an approval manager from the Manager drop-down list.
Tab out of the Manager drop-down list.
The user record is created.
The user and email address that you just added to the SAM system receives a notification email with a new system-generated password. That user can change the password from within the SAM application.
Add roles to the new user.
In the Users page, click the role value of the user that you want to add role.
The User Roles dialog box appears.
In the Available Columns box, select the role that you want to assign to the current user and click the move-right icon.
The selected role is moved to the Selected Columns box.
Optionally, repeat the previous step to add more roles to the current user.
Alternatively, you can click the Move All button to assign all available roles to the current user.
Click the OK button.
Adding User Roles and Assigning Users to User Roles
A role is way of grouping one or more responsibilities and assigning them to particular users. Roles are useful for managing large collections of responsibilities. You can assign approver responsibilities and send notification emails to an individual role.
You can use the Roles page to add new user roles to the SAM application and assign user IDs to the user roles. The following table describes the fields in the Roles page.
Table Fields in the Roles page
| Field/Column | Description |
|---|---|
Add (plus) button |
Click this button to add new user roles. |
Role Name column |
This column lists the display name of the given role. |
# of Members column |
This column lists the number of users that have the given role. You can click the member count link to view the members of each role |
Delete button |
Click the Delete button to delete the corresponding user role from the SAM application |
To add a new user role
From the SAM Home page, select the Main Menu button.
Select the Administration option.
Select the Roles option from the Administration drop-down list.
The Roles page appears.
Click the Add button in the Roles page.
Enter a role name.
Tab out of the Role Name field.
The new role is listed under the Role Name section. Notice that the newly created role has zero members (users).
To assign a user to a user role
From the SAM Home page, select the Main Menu button.
Select the Administration option.
Select the Roles option from the Administration drop-down list.
The Roles page appears.
In the # of Members column, click the value of the role for which you want to add users.
The User Roles dialog box appears.
Select a user from the Select User drop-down list.
Click the Add button.
Optionally, repeat Steps 5 and 6 to add more users to the current user role.
Optionally, click the Remove button to remove any user from the current user role.
Click the Close (X) button to finish adding or moving users, and return to the Roles page.
Defining the Fields for Use Throughout the SAM Application
Oracle Siebel delivers numerous defined internal fields with the SAM application. You can use the Fields page to add the defined fields to be displayed throughout the SAM application and modify the default labels for each of the fields.
In other words, the Fields page enables you to reuse many of the shipped fields to store the data that is populated from your issue tracking system. The fields that are shipped, such as CUSTOMER or PRIORITY, can be reused for any purpose by changing the default label. This new label is then displayed throughout the SAM application instead of the old default label. The following table describes the fields in the Fields page.
Table Fields in the Fields page
| Field/Column | Description |
|---|---|
Field column |
This column contains the internal system fields in the Fields page. |
Default Label column. |
This column contains the default label of the current field. To change any label, click that label and type the new label over the current one. If it is left blank, the system name is displayed. |
List Order column |
This column contains the order of the current field in the Approval Requests section on the SAM Home page. If a field has a List Order set to Hidden, that field is not displayed in a table on the Approval Requests section. |
To define the fields that will be displayed on the SAM Home page
From the SAM Home page, select the Main Menu button.
Select the Administration option.
Select the Fields option from the Administration drop-down list.
The Fields page appears.
Optionally, modify the default labels.
In the Default Labels column, click the label of the field that you want to modify.
Type the new label.
Repeat step 4a and step 4b to modify additional labels.
Optionally, modify the list order of the fields.
In the List Order column, click the list order of the field that you want to modify and type the new list order number.
To set a field to Hidden, remove the current value of the field in the List Order column and click (or tab) out of that field.
The value automatically changes to Hidden.
Repeat step 5a and step 5b to modify the list order of other fields.
Setting up the Third-Party Systems
You can use the Systems page to register and set up the third-party systems that integrate with the SAM application.
Examples of the issue tracking systems that integrate with the SAM application are Bugzilla, Jira, or Review Board.
Examples of the Software Configuration Management (SCM) systems are ClearCase, SVN, and Siebel Workspace.
The following table describes the fields in the Systems page.
Table Fields in the Systems page
| Field/Column | Description |
|---|---|
Add (plus) button |
Click this button to add new system. |
System Type column |
This column lists the type of the third-party system. Two system types are available: Issue Tracking and SCM (Software Configuration Management). |
System column |
This column lists the name of the integrated system and this is a user-entered display name. |
Read/Update column |
Use the button in this column to display the Read/Update Method dialog box.
|
Write/Delivery column |
Use the button in this column to display the Write/Delivery Method dialog box.
For more information on how to invoke these REST API calls in the Updates table, refer to Setting Up Approval Profile Actions in the SAM Workflow.
Note: This feature for SCM systems is only supported in 2.17.10 and onwards.
|
Drilldown URL column |
Use the button in this column to display the Drilldown URL dialog box where you can add or modify the URL that the SAM application uses to drill down to the tracking systems.
Note: This is only for Issue Tracking systems.
This is an example of the Drilldown URL for issue tracking system: http://hostname:8880/bugzilla/show_bug.cgi?id={ISSUE_ID}. This example points to the URL of Bugzilla. When users click the Drilldown URL button next to the bug ID on the Create Approval Request page, the SAM application opens the bug in Bugzilla. |
Fields column |
Use the button in this column to display the Config Fields dialog box where you can configure this system’s fields that are available to use throughout SAM. To load the list of fields, enter the URL for the system’s field JSON file and click the Get Fields JSON button. For more information regarding the field JSON format, refer to the section Importing System Fields. The following properties can be configured for each field:
Issue Tracking systems: These are the issue tracking system fields that are available within SAM to be displayed on the Approval Request page and updated when an approval status changes. SCM systems: These are the fields that SAM can pass to the SCM system’s Write/Delivery REST API when an approval status changes (for example, delivering workspace changes when a request is approved). When data is sent to these REST APIs, each field is mapped in the Workflow>Actions>Update section for that profile and is sent with dynamic data bound with the help of Messages. For more information, see the Fields in the Update section table.
Note: This feature for SCM systems is only supported in 2.17.10 and onwards.
|
Delete button |
Click the Delete button to delete the corresponding system type from the SAM application. |
To set up an Issue Tracking third-party system
From the SAM Home page, select the Main Menu button.
Select the Administration option.
Select the Systems option from the Administration drop-down list.
The Systems page appears.
Click the Add button in the Systems page.
Select Issue Tracking from the System Type drop-down list.
Two system types are available: Issue Tracking and SCM.
Enter the name of the third-party system into the System field.
Tab out of the System field.
Add the REST API URL that the SAM application will use to read the data from the tracking system.
Suppose that in the Administration\Fields page, you have set the default label of the ISSUE_ID field to Bug # and plan to store the Bugzilla Bug Number value in that field. For the Read/Update REST API to work properly, you will need to pass the Bug ID into the URL.
Locate the tracking system that you just added and click its corresponding Read/Update button.
The Read/Update Method dialog box appears.
Enter the hardcoded portion of the URL.
For example, http://hostname:<port number>/bugzillarest/bugs/.
Place the cursor where you want to insert the Bug Number field value.
In this case, that is at the very end of the string.
From the Insert Field Value into URL drop-down list, select the name of the field whose value you want to insert into URL, which is Bug # in this example.
The text {ISSUE_ID} is inserted into the URL where you placed your cursor so the resulting URL is http://hostname:<port number>/bugzillarest/bugs/{ISSUE_ID}.
Click the OK button.
When a user accesses the Create Request page, enters the value 1234 into the Bug ID field, and clicks the Enter key, the SAM application invokes http://hostname:<port number>/bugzillarest/ bugs/1234 to pull data from the issue tracking system into the page.
Add the REST API URL that the SAM application will use to write the data back from the SAM application to the tracking systems.
Locate the tracking system that you just added and click its corresponding Write/Delivery button.
The Write/Delivery Method dialog box appears.
Enter the hardcoded URL into the Write/Delivery URL field.
This is an example of the Write/Delivery URL: http://hostname:<port number>/BugzillaRESTService/bug/.
Click the OK button.
Add the URL that the SAM application will use to drilldown to the tracking systems.
Locate the tracking system that you just added and click its corresponding Drilldown URL button.
The Drilldown URL dialog box appears.
Add a URL into the Drilldown URL field.
This is an example of the drilldown URL: http://hostname:<port number>/bugzilla/ show_bug.cgi?id={ISSUE_ID}.
Note: You can use the Insert Field Value into URL drop-down list to select the name of the field and insert it into URL. For more information on how to insert field value into URL, see step 8.Click the OK button.
Configure the issue tracking fields that are used by the SAM application.
Locate the system that you just added and click its corresponding Fields button.
The Config Fields page appears.
In the URL field, enter the URL of the tracking system's field JSON file. For more information on the expected JSON format, see Importing System Fields.
Click the Get Fields JSON button.
The SAM application lists all available fields that are populated from the tracking system.
In the Label column, modify the labels as needed.
Select the Active option for the fields that you want to be used within SAM.
In the Default Status column, select the radio button in the Default Status column for the issue tracking system's status field.
For example, this would be the status field in Bugzilla.
In the Key Field column, select the radio button in the Key Field column for the issue tracking system's unique identifier field.
For example, this would be the bug number field in Bugzilla.
Modify the listing order of the fields using the values in the List Order column.
Click the OK button.
To set up an SCM third-party system
From the SAM Home page, select the Main Menu button.
Select the Administration option.
Select the Systems option from the Administration drop-down list.
The Systems page appears.
Click the Add button in the Systems page.
Select SCM from the System Type drop-down list.
Two system types are available: Issue Tracking and SCM.
Enter the name of the third-party system into the System field.
Tab out of the System field.
Add the REST API URL that the SAM application will use to validate the approval request's SCM source (private branch or workspace name for example).
Locate the SCM system that you just added and click its corresponding Read/Update button.
The Read/Update Method dialog box appears.
Enter the hardcoded portion of the URL.
For example, http://hostname:<port number>/workspace/wsname/.
Place the cursor where you want to insert the private branch name or workspace name
In this case, that is at the very end of the string.
From the Insert Field Value into URL drop-down list, select the field source.
Note: This is an in-built field to store private branch name or workspace name that is also used when delivery is triggered from SAM.The text {source} is inserted into the URL where you placed your cursor so the resulting
URL is http://hostname:<port number>/workspace/wsname/{source}
Note: You can configure a more complex URL with multiple parameters.For example,
http://hostname:<port number>/github/repo/{repository}/pbname/{source}
In this case, the element {repository} is not available as an item in the Field drop-down list and must be manually entered. When an SCM entry is added to an approval request, these two elements are prompted to get entered.
Click the OK button.
When a user creates a request and adds an SCM entry for delivery, a prompt for {source} will be displayed. On clicking the Validate button, a pop-up screen appears where {source} and the similar elements like {repository}, if configured, will get populated for input.
On clicking the OK button in the pop-up screen, if the user entered dev_mypb as their private branch, for example, the SAM application invokes http://hostname:<port number>/workspace/wsname/dev_mypb to validate the SCM entry.
For the complex scenario, if the user entered staging for the {repository} prompt, the following URL is invoked:
http://hostname:<port number>/github/repo/staging/pbname/dev_mypb
Add the REST API URL that the SAM application will use to deliver the SCM entry changes.
Note: The Write/Delivery method of SCM system is only supported in 2.17.10 and onwards.Locate the SCM system that you just added and click its corresponding Write/Delivery button.
The Write/Delivery Method dialog box appears.
Enter the hardcoded URL into the Write/Delivery URL field. The SAM application will use this REST API URL to deliver the SCM entry changes.
For example, http://<servername>:<port number>/workspacedelivery/workspace/
For more information refer to Deploying and Configuring Workspaces.
Click the OK button.
Configure the SCM fields that are used by the SAM application for delivery parameters.
Locate the SCM system that you just added and click its corresponding Fields button.
The Config Fields page appears.
In the URL field, enter the URL of the SCM system’s field JSON file. For more information on the expected JSON format, see Importing System Fields.
Click the Get Fields JSON button.
The SAM application lists all available fields that are populated from the SCM system.
For example, for the URL entered in the step b, the two fields that display are requestid and wsname. Select Key Field option button for requestid and Default Status option for wsname.
In the Label column, modify the labels as needed.
Select the Active option for the fields that you want to be used within SAM.
Modify the listing order of the fields using the values in the List Order column.
Click the OK button.
Defining the Approval Request Statuses
You can use the Statuses page to create, edit, or remove the approval request statuses based on the desired workflow at your corporation. The following table describes the fields in the Statuses page.
Table Fields in the Statuses page
| Field/Column | Description |
|---|---|
Add (plus) button |
Click this button to add new approval request statuses. |
Status Name column |
This column contains the approval request statuses in the SAM application. |
Delete button |
Click the Delete button to delete the corresponding approval request status from the SAM application. |
To add an approval request status
From the SAM Home page, select the Main Menu button.
Select the Administration option.
Select the Statuses option from the Administration drop-down list.
The Statuses page appears.
Click the Add button in the Statuses page.
In the Status field, enter a name for the new approval request status.
Tab out of the Status field.
To modify an approval request status
From the SAM Home page, select the Main Menu button.
Select the Administration option.
Select the Statuses option from the Administration drop-down list.
The Statuses page appears.
In the Status Name column, click the status that you want to modify.
Enter the new name for the approval request status over the current name.
Tab out of the Status Name field.
Specifying Messages
You use the Messages page to create and customize the messages that are used in validation error messages, email communication, or tracking system updates. For example, if you want a validation error when an invalid value occurs for the Target Release field, you could create a message with the text Invalid value for {TARGET_RELEASE}. The following table describes the fields in the Messages page.
Table Fields in the Messages page
| Field/Column | Description |
|---|---|
Add (plus) button |
Click this button to add new messages. |
Message Name column |
This column contains the name of the given message. Notice that the message name must be unique for each message. |
Text column |
This column contains the text of the given message. You can click the link to open the Message Details dialog box where you can edit the corresponding message. |
Delete button |
Click the Delete button to delete the corresponding message from the SAM application. |
To add a new message
From the SAM Home page, select the Main Menu button.
Select the Administration option.
Select the Messages option from the Administration drop-down list.
The Messages page appears.
Click the Add button in the Messages page.
The Message Details dialog box appears.
In the Message Name field, enter the name of the message.
In the Message Text field, enter a message text.
Optionally, use the Insert Field Value into Text drop-down list to insert the field value from the approval request record.
Place the cursor in the message text where you want to insert the field value.
From the Insert Field Value into Text drop-down list, select the name of the field whose value you want to insert into the message text.
Click the OK button.
To modify an existing message
From the SAM Home page, select the Main Menu button.
Select the Administration option.
Select the Messages option from the Administration drop-down list.
The Messages page appears.
In the Text column, click the text link for the message that you want to modify.
The Message Details page appears.
Modify the message name and message text as required.
Optionally, use the Insert Field Value into Text drop-down list to insert the field value from the approval request record.
Place the cursor in the message text where you want to insert the field value.
From the Insert Field Value into Text drop-down list, select the name of the field whose value you want to insert into the message text.
Click the OK button.
Configuring Emails
This topic describes how to configure SAM for sending email and approving by email.
Configuration for sending email: This configuration is in the installer screen SAM Email Configuration Input. This screen captures the SMTP server, port number, User Id, and password of SMTP server authentication for sending email. Configurations also include capturing a no reply email Id and an email Id to receive reply action emails.
Configuration for approval by email: The screen Email REST API Input is used to configure inbound emails for approval actions. This includes the configuration of the email Id to receive approval emails, the password, the default folder for Email REST API to look for the incoming emails, such as Inbox, the IMAP server URL, IMAP server port number, SAM being hosted in http or https, port number of the SAM hosting.
Reconfiguring Emails
This topic describes how to reconfigure the email sending mechanism and the Approval by Email feature.
Reconfiguring Send Email
To reconfigure the email sending mechanism, modify the following files:
The configuration of SMTP is defined in the file, sam\resources\spring\mail\mail.xml
Note: By default SMTP authentication is disabled.Values of this configuration can be modified in the file, applicationcontainer\conf\mail.properties
Following items are available for modification,
mail.smtp.hostname=<SMTP host URL>
mail.smtp.port=<SMTP server port number>
mail.username=<email id for SMTP auth>
mail.password=<password of the email id>
mail.noreply=<noreply@sam.com>
mail.mailto=<email id of the inbox that will receive approval emails>
Reconfiguring Approval Email
To reconfigure the Approval by Email feature
The configuration for IMAP settings are stored in the file, emailapprover\resources\spring\context\context-integration.xml
Setting can be found under the section, <mail:inbound-channel-adapter id="imapAdapter" …
The values for these settings can be modified in applicationcontainer\conf\email.properties
Following items are available for modification,
email.id=<email id of the inbox that will receive approval emails>
email.pwd=<encrypted password>
email.folder=<inbox>
email.uri=<server name>:<port number>
email.samURL=http://<server name>:<port number>
email.samUserName=<email id of the SAM user which is needed for approval actions via API calls>
email.samPassword= <encrypted password>
To update the passwords, use the following URL to get encrypted password,
http://<server name>:<port number>/emailapprover/encrypt/<new password>
Configuring Approval Profiles
An approval profile describes how the Approval Request pages appear, which systems are used, and defines the Approval workflow. You should create different approval profiles for different types of approval requests. For example, you should create different profiles for different approval workflows, different issue tracking or SCM systems, different sets of fields that are required to be displayed, different validation rules, and so on.
This topic describes how to manage and create the approval profiles in the SAM application. It includes the following information:
Managing the Approval Profiles
You can use the Approval Profiles page to manage approval profiles such as activating, deactivating, or deleting the existing approval profiles. This page also enables you to access the Approval Profiles detail page where you can view the detailed information of the existing approval profiles or create new approval profiles. The following table describes the fields in the Approval Profiles page.
Table Fields in the Approval Profiles page
| Field/Column | Description |
|---|---|
Add (plus) button |
Click this button to add new approval profiles into the SAM application. |
Profile Name column. |
This column contains the name of the corresponding approval profile. Click on the name to access the Approval Profiles detail page where you can edit the selected approval profiles. |
Issue Tracking System(s) column |
This column displays the tracking systems for the corresponding approval profile. |
SCM System(s) column |
This column displays the SCM systems for the corresponding approval profile. |
Active column |
This column indicates whether the approval profile is active. Notice that only active approval profiles can be used to create approval requests. |
Delete button. |
Click the Delete button to delete the corresponding approval profile from the SAM application. |
Creating New Approval Profiles
You can use the Approval Profiles detail page to create an approval profile that will be used to identify which fields are displayed on the Approval Request page. You can also use this page to define the approval workflow and map which software configuration systems are used in the approval profiles.
You can define the following options for an approval profile:
Profile names.
The names that are displayed in the Create Approval Request drop-down list on the Home page.
Specific issue tracking system.
For example, Bugzilla or Jira.
Set of fields that are identified to populate the data from the issue tracking system along with what their display labels, display order, and acceptable (valid) values.
A set of allowed software configuration connectors for this specific source.
For example, ClearCase, SVN, or Workspaces.
A specific set of approval workflow steps and approval workflow.
The following table describes the fields in the Approval Profiles detail page.
Table Fields in the Approval Profiles detail page
| Field/Column | Description |
|---|---|
Profile Name |
The name that is displayed in the Create Approval Request drop-down list on the Home page. |
Active? |
On selection, the approval profile gets activated. Only active profiles can be used to create approval requests. |
Issue Tracking System(s) |
The systems that help track and fix issues. For example, Bugzilla or Jira. |
Primary Tracking System |
The issue tracking system that is selected as the primary tracking system. |
Issue Tree Open Statuses |
Specifies a comma-delimited list of status values that indicate an Open status with the primary issue tracking system. |
Issue Tree Open Statuses |
Specifies a comma-delimited list of status values that represent a Closed status. |
SCM System(s) |
The SCM systems where SAM initiates the check-in process to deliver the associated changes. For example, ClearCase, SVN, or Workspaces. |
Save button |
Saves the approval profile. The Fields and Workflow sections are active and available. The newly created approval profile is listed under the Create New Approval Request drop-down list on the SAM Home page if the profile is Active. The Save button only saves the first section of the page. The data within the Fields and Workflow sections are saved once you exit a row you are editing/adding. |
Back button |
The page reverts to the Approval Profiles page. On clicking the Back button without saving approval profile, the profile details are lost. |
To create a new approval profile
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.
Click the Add button in the Approval Profiles page.
In the Profile Name field, enter the name for the new approval profile.
Note: Each approval profile must have a unique name.Select the Active option to activate the approval profile.
Note that only active profiles can be used to create approval requests.
Click the search (magnifier) icon next to the Issue Tracking Systems field.
Select one or more issue tracking systems from the list of available options.
Note: If multiple issue tracking systems are chosen, they must share a common unique key.Click the OK button.
Click the search icon next to the Primary Tracking System field.
Select one primary tracking system from the list of available options, which are displayed based on your selection in the Issue Tracking Systems field.
For example, if Bugzilla and a Code Review system are chosen, then Bugzilla is the primary issue tracking system and the Bugzilla Bug number (#) field would be the unique key for both Bugzilla and the Code Review system.
Optionally, enter the values in the Issue Tree Open Statuses field and the Issue Tree Closed statuses field.
Issue Tree Open Statuses: Specifies a comma-delimited list of status values that indicate an Open status with the primary issue tracking system.
Issue Tree Closed Statuses: Specifies a comma-delimited list of status values that represent a Closed status.
Click the search icon next to the SCM System(s) field and select one or more SCM systems from the list of available options.
Click the OK button.
Click the Save button.
The Fields and Workflow sections are active and available after you save the approval profile. The newly created approval profile is listed under the Create New Approval Request drop-down list on the SAM Home page if the profile is Active.
For more information on the Fields section, see following section.
Identifying Fields Displayed on the Approval Request Page
Use the Fields section to determine which fields are displayed on the Approval Request page. Thus, the Fields section on the Approval Profiles detail page enables you to identify which fields are displayed on the Approval Request page and map which internal fields the issue tracking data is stored in. The following table describes the fields in the Fields section on the Approval Profiles detail page.
Table Fields section on the Approval Profiles detail page
| Field/Column | Description |
|---|---|
Add (plus) button |
Click this button to add new fields that will be displayed on the Approval Requests page. |
Order column |
This column displays the number denoting the order in which to place the corresponding field. On the larger screens fields are displayed in two columns and ordered left, right, left, right, and so on based on this field. For example, they are displayed like this: 1 2 3 4 5 6 On smaller screens (i.e. mobile devices), there is only one column of fields and they are ordered by this field value. |
Source column |
The column contains the system from where the corresponding field originates. This can either be one of the issue tracking systems defined for this profile or Internal to denote that this field is a SAM internal field. |
Source Field column |
This column contains the name of the field (from the system selected in the source column) whose value is used to populate the corresponding field. You can optionally select the <DIVIDER> option in the System fields to add a line to the approval profile to separate the fields on the page. |
Mapped System Field column |
This column contains the SAM field where the external system data, as identified in the two previous columns, will be stored.
Note: The Mapped System Field is inactive if the Source column is set to Internal.
This column value is optional. If it is not specified, then the external field value is only displayed and will not be stored within SAM. |
Override Label column |
This column contains the override field label that is optional and will be displayed next to the corresponding field on the Approval Request page. If no value is entered here, then the default field label is used as the label. These default labels are specified in the Field Administration page. For example, suppose that you select the following field values:
That means that the SAM application will pull the ID field from Sample Bug System, display it in a field labeled Bug # on the Approval Request page, and then store it in Bug Number internal field. |
Default View column |
If this check box is selected, then the field is displayed in the expanded record.
Note: If Multiple Issue Approval is not enabled, then this field can be ignored.
|
Header column |
If this check box is selected, then the field is displayed in the header of the collapsed record.
Note: If Multiple Issue Approval is not enabled, then this field can be ignored.
|
Enable URL column |
If this check box is selected, then the drilldown icon will be displayed next to this field on the Approval Request page. |
Validation Values and Message columns |
These columns display the validation values and corresponding messages. When no value is added, the column displays None. A regular expression can be optionally entered in the Validations Values field. When the Approval Request page is loaded, the value of the field is compared with this regular expression and the following happens:
The following are a few examples of regular expressions:
|
Delete button |
Click the Delete button to delete the corresponding field from the Fields list. The deleted field will not be displayed on the Create Approval Requests page. |
Defining Approval Workflows
You use the Workflow section on the Approval Profiles detail page to define the SAM approval workflows. In this section, you can identify which conditions must be met for the approval actions to be available, including the starting statuses, action owners, and additional configurable fields with matching conditions.
For example, when the status of a request is New and the logged in user is the Owner of the request, then the request can be submitted to be reviewed by their manager. When the status is Pending Approval and the logged in user is the manager of the owner of the request, then the request can either be Approved or Rejected.
The following table describes the fields in the Workflow section on the Approval Profiles detail page.
Table Fields in the Workflow section
| Field/Column | Description |
|---|---|
Add (plus) button |
Click this button to add new starting statuses. |
Starting Statuses column |
This column contains the status or statuses that the request must be in for this workflow step to apply. |
Action Owners column |
This column displays the role responsible for the completion of the corresponding workflow step. The logged in user must be in at least one of the roles for this workflow step to apply. The Role can either be Owner (the creator of the request), Approving Manager (the manager of the request’s creator as defined in the User administration page) or one of the roles defined in the Role administration page. |
Conditions column |
This column displays any additional conditions that must be met for this workflow step to apply. Click on the link to open the Workflow Steps Conditions dialog box where you can enable conditional workflows in the SAM application. For more information, see Enabling Conditional Workflows in the SAM Application. |
Actions column |
This column lists the actions that can be taken by the logged in user when all of the conditions defined in the previous columns have been met. Click on the link to access the Approval Profile Actions dialog box where you can modify the existing approval actions. For more information, see Setting Up Approval Profile Actions in the SAM Workflow. |
Delete button |
Click the Delete button to delete the corresponding starting status from the SAM application. |
To add a new workflow row
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.
Click the profile where you want to add a new workflow row.
Scroll down to the Workflow section and click the Add button.
In the Starting Statuses field, select the starting statuses.
Click the search (magnifier) icon next to the Starting Status field.
The Choose Starting Statuses dialog box appears.
Select one or more starting statuses from the list of available options.
Click the OK button.
In the Action Owners field, select the action owners.
Click the search (magnifier) icon next to the Action Owners field.
The Choose Approvers dialog box appears.
Select one or more approvers from the list of available options.
Click the OK button.
Tab out of the Action Owners field.
Locate the starting status that you just created. Notice that its condition is None and its action value is No Actions Defined.
For more information on how to enable conditional workflow in the SAM application, see Enabling Conditional Workflows in the SAM Application.
For more information on how to set up approval profile actions in the SAM application, see Setting Up Approval Profile Actions in the SAM Workflow.
Enabling Conditional Workflows in the SAM Application
You can use the Workflow Step Conditions dialog box to add additional conditions to the expressions of each step within the SAM workflow. These conditions compare a field with a regular expression (that is similar to the field validation). However, adding additional conditions is optional.
The SAM application evaluates the conditions grouped together by the operator ANDs. In other words, the SAM application puts parentheses around each set of operator ANDs (without displaying the parentheses). For example, if you define the following conditions:
Status matches 25
AND Fix By matches IP2016
OR Status matches 16
AND Fix By matches CIR4
AND Assignee matches SAMUEL
OR Status matches 39|40
AND Assignee matches SADMIN
Then SAM evaluates the conditions as following:
(Status = 25 AND Fix By = IP2016) OR (Status = 16 AND Fix By = CIR4 AND Assignee = SAMUEL) OR (Status = 39|40 AND Assignee = SADMIN)
The following table describes the fields in the Workflow Step Conditions dialog box.
Table Fields in the Workflow Step Conditions dialog box
| Field/Column | Description |
|---|---|
Add (plus) button |
Click this button to add new conditions to the expressions of each step within the SAM workflow. |
Order column |
This column displays a number denoting the order in which to list the corresponding condition. |
AND/OR column |
This column displays the values of AND and OR and it is not available for the first condition. |
Field column |
This column contains the field that is used to match against for this condition. The field can be selected from all fields that are mapped to system fields and some additional system fields such as Owner ID and Manager ID. |
Expression field |
Use this text field to enter the regular expression to match against the field's value. For more information, see Validation Values and Message Columns in the Fields section on the Approval Profile details table. |
Delete button |
Click the Delete button to delete the corresponding workflow step condition from the workflow step. |
To add new conditional workflow steps to the SAM application
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 condition link for the starting status that you want to add condition.
The Workflow Step Conditions dialog box appears.
Click the Add button.
Enter a condition list order number using the Order field.
Select the operator AND, OR from the AND/OR drop-down list.
This list is not available for the first workflow step condition.
Select a field from the Field drop-down list.
Enter an expression in the Expression text field to match against the field's value.
Tab out of the Field drop-down list.
Click the Close button to return to the Approval Profiles detail page.
To modify an existing condition within the SAM workflow step
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 condition link for the starting status that you want to modify.
The Workflow Step Conditions dialog box appears.
Click the field values that you want to modify and type the new values over the current ones.
Tab out of the field.
Click the Close button to return to the Approval Profiles detail page.
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.
Table 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 the Save Draft button 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, 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, 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 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, 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.
Table Fields in the Update section
| Field/Column | Description |
|---|---|
Update Type |
The type of system that will be updated – either Issue Tracking or SCM.
|
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 |
|
Value Type |
The Exact Value or Message (see below for Value). |
Value |
Note: Note that if you have more than one update entry specified for a single SCM system, 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.
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, 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.
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.
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, the button will still be disabled even though there are no SCM validation errors.Select the Approve option to indicate that the action that is set in the Action Name field is an Approval action.
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.
Select the email subject and email body using the template in the Email Body and Email Subject fields. For more information, see Specifying Messages.
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.
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 the Save button.
Configuring Multiple Issue Approval Mode
This is a special request submission mode that is available within SAM. The Multiple Issue Approval allows users to submit requests for multiple issues at once if they are all in the same hierarchy.
Identifying issues in the same hierarchy
On the Profile Admin page,
In the Issue Tree Open Statuses field, a comma-delimited list of status values is specified that indicate an Open status with the primary issue tracking system.
In the Issue Tree Closed Statuses field, a comma-delimited list of status values is specified that represent a Closed status.
There is a special field in an issue tracking system to hold a Parent Id that is the Id of its parent issue.
In the Create Approval Request page when an issue Id is entered, REST API connected to SAM will use the Parent Id field and find all issues in the primary issue tracking system that are in the same hierarchy and have one of the statuses defined in the Issue Tree Open Statuses field. These issues are further filtered in SAM.
For example, if there are 6 issues identified,
| Issue Id | Parent Id | Status |
|---|---|---|
1 |
2 |
Open |
2 |
3 |
Open |
3 |
Closed |
|
4 |
3 |
Awaiting review |
5 |
6 |
Open |
6 |
Open |
and if the Issue Tree Open Statuses is set to Open, Awaiting review,
in the Create Request page when the issue Id 2 is entered, then REST API connected to SAM would find all issues in that hierarchy:
It would find issue 1 because 1 is a child of 2
It would find issue 3 because 3 is 2's parent
It would find issue 4 because 4 shares the same parent as 2
It would not find issues 5 or 6 since they are not related at all to 2
So 1, 2, 3 and 4 are found by REST API. However only 1, 2 and 4 have a status value listed in Issue Tree Open Statuses, so 3 is ignored. Hence, REST API connected to SAM finds issues from 1-4, SAM filters out issue 3 and SAM shows issues, 1, 2 and 4. For more information, see REST APIs for SAM.
Submitting Multiple Issues
On the Create Approval Request page, all issues are displayed in the tree with an open status.
Each issue is collapsed in its own section on the page.
Only the fields that are flagged as Header on the Profile administration page are displayed in the head of the collapsed record.
When a collapsed section is expanded, only the fields with Default View set on the Profile administration field are displayed.
A Close button is displayed on each of the collapsed records that can be used to close that issue.
On clicking the Close button, it allows to pick one of the status values defined in the Issue Tree Closed Statuses on the Profile administration page. After selecting a value, when the submit button is clicked, the status field of that issue tracking system record is updated to the selected closed value.
The Refresh icon can be used to refresh the page. The closed record no longer appears on the page.
A drop-down list is displayed for each record that will allow to specify which profile to use for that approval request since they may be different for each issue in the hierarchy.
Events after Submission for Multiple Issues
When the approval request is submitted, SAM will submit approval requests for all of the records on the page (assuming none have validation errors).
For each of the issues found (not including the issue that was initially entered on the page), SAM will look at its selected profile and find the available action that has the Default Submit flag set and execute that action for the request.
Note: The issue initially entered on the page is not included because, for the original issue, it will use the profile that was selected when launching this page.Approval requests are created for each of the issues involved and approvals are to be done individually for each issue. Multiple Issue Approval mode is only for bulk submission and not for bulk approval.
Deploying and Configuring Workspaces
Deploying workspaces is a two-step process.
Configuring SAM to setup and deliver workspace
Deploying workspace file
Configuring SAM
The following information describes the process of configuring SAM.
To setup workspace delivery
Set up your workspace system in SAM.
Refer to To set up an SCM third-party system.
Configure messages. Add two new messages for the SCM system. .
Refer to Specifying Messages
For the first message, create message Approval ID for Workspace delivery with text {APPROVAL_ID}.
For the second message, create message Source for Workspace delivery with text {source}.
Add one new status for Pending Delivery and optionally two additional statuses for Delivery Completed and Delivery Failed.
Refer to Defining the Approval Request Statuses.
Open the Approval Profile screen and locate the profile that you want to configure workspace delivery.
Add a workflow according to your process step, for example an approval for delivery.
Add an action by clicking the Plus (+) sign under Action(s) header for the newly created workflow.
In the Approval Profile Actions pop-up window, select Pending Delivery in the Result Status drop-down list. Configure other fields.
Refer to Setting Up Approval Profile Actions in the SAM Workflow.
Add update entries for Action(s) as following in the next part of the Approval Profile Actions to initiate the delivery.
Create the following update entry to pass the approval ID to the workspace API:
Update Type: SCM
External System: The Workspace system you configured
Field: requestid
Value Type: Message
Value: Approval ID for Workspace delivery
Create the following update entry to pass the workspace name to the workspace API:
Update Type: SCM
External System: The Workspace system you configured
Field: wsname
Value Type: Message
Value: Source for Workspace delivery
This is an optional step for receiving a post-delivery action in SAM. You can add a success action and failure action to flip a success and failure status in SAM request. These actions can be additionally configured to record a message or flip a status on the Issue Tracker.
To receive a delivery status update, add a new workflow with Starting Status as Pending Delivery and two Action Result Status as Delivery Successful and Delivery Failed.
The Action IDs of the configured status Approval Profile Actions must be used when configuring the workspace REST API. For more information, refer to Step 4.
Note: Make sure you have a SAM user and role defined for the user who has the action ownership. Refer to Adding User Roles and Assigning Users to User Roles. This user must also be configured in workspace.properties as value for jdbc.samUsername. In this example user is deliv@oracle.com and role is Delivery Agent. Refer to Step 4.
Deploying Workspaces
The following information describes the process of deploying workspaces.
To deploy workspace file
Find the workspace.war file from the SAM installed folder and rename it to workspacedelivery.war.
Copy the workspacedelivery.war file to Tomcat Webapps folder. This deployment is done on the server where Siebel Tools is installed.
Note: If SAM is not setup in this server, then copy US_export_policy.jar and local_policy.jar from the bin folder in the SAM installed folder and place it in lib/security under your Java home.Change the content of <Siebel Tomcat home>\webapps\workspacedelivery\resources\properties\workspace.properties to match the workspace database connection. Choose from the following properties based on your database type:
Oracle DB
jdbc.driverClassName=oracle.jdbc.driver.OracleDriver jdbc.url=jdbc:oracle:thin:@<server name>:<portnumber>/<instance name> jdbc.username=<TBLO> jdbc.password=<encrypted password> jdbc.tblo=<TBLO>
DB2 UDB
jdbc.driverClassName=com.ibm.db2.jcc.DB2Driver jdbc.url=jdbc:db2://<server name>:<portnumber>/<DB Alias> jdbc.username=<TBLO> jdbc.password=<encrypted password> jdbc.tblo=<TBLO>
DB2 390
jdbc.driverClassName=com.ibm.db2.jcc.DB2Driver jdbc.url=jdbc:db2://<server name>:<portnumber>/<DB Alias> jdbc.username=<database user> jdbc.password=<encrypted password> jdbc.tblo=<TBLO>
MS SQL DB
jdbc.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver jdbc.url=jdbc:sqlserver://<server name>\\<instance name>:<portnumber>;databaseName=<TBLO> jdbc.username=<TBLO> jdbc.password=<encrypted password> jdbc.tblo=<TBLO> jdbc.intBranchName=<workspace branch where you want to deliver your changes> jdbc.siebelUsername=<Siebel user name> jdbc.siebelPassword=<Encrypted Siebel password> jdbc.logPath=<Create a local folder for API to write log files to, like C:/workspace> jdbc.toolsPath=<Siebel Tools path, eg: C:/Siebel/18.0.0.0.0/18_03_Tools> jdbc.siebelDSN=<Siebel DSN>
Note: Place a copy of your DB2 license jar file (db2jcc_license_cisuz.jar) to your Siebel Tomcat lib folder and bounce Tomcat server in case your Siebel DB is DB2 UDB or DB2 390 (z/OS).This step is optional. Use this for workspacedelivery REST API to call back SAM to record success and failure actions.
jdbc.samURL=http://<Server name>:<portnumber>/sam jdbc.samUsername=<A user who has a role which has ownership to do success and failure actions for example delivery@<emaildomain.com> jdbc.samPassword=<Encrypted SAM password> jdbc.samSuccessActionID=<Action Id for post successful delivery> jdbc.samFailureActionID=<Action Id for post failed delivery>
Note: To encrypt password, use the link http://<server name>:<port number>/emailapprover/encrypt/<password to encrypt>Restart Tomcat server and open the link http://<servername:portnumber>/workspacedelivery/ in any browser to see the welcome message, Welcome to Siebel Workspace Delivery Adaptor!!!
Note: Restart Tomcat server only after finalizing the configuration or making any changes during configuration and testing.
To test the workspace delivery REST API
You may use Postman or any similar utility to test the API functionality before configuring SAM. After bringing up Workspacedelivery application as mentioned in step 1 through 4 (You can leave the optional section for the testing), use the Postman to do a POST action on the URL http://<server name>:<port number>/workspacedelivery/workspace/. Provide the following raw JSON content after altering the value according to your workspace name and request id.
{
"wsname":"test",
"requestid":"test"
}
This would start a Siebel Tools instance and it would try to deliver the workspace. You will get a successful delivery message or a failure message accordingly. If you find any issues, check the workspace.properties, make corrections, and bounce Tomcat before you retest delivery.