Introduction

Users find an Approval Process in JOC Cockpit for situations in which users perfrom interventions such as adding or cancelling orders. This can include ony operation that modifies a scheduling object.

The following roles are involved:

• A Requestor requests to perform an intervention that requires approval.
• An Approver confirms or denies the Approval Request.

The basic functionality of the Approval Process includes:

• to implement the 4-eyes principle: an Approver must confirm the intervention of a Requestor before the internvention can be executed in the scope of the Requestor's account, roles and permissions. 
• to keep track of pending Approval Requests.
• to offer fallback to a number of Approvers.
  
  

JOC-1915 - Getting issue details... STATUS

FEATURE AVAILABILITY STARTING FROM RELEASE 2.8.0

Prerequisites

Requestor Role

Creating the Requestor Role

To activate the 4-eyes principle users create a new role using an arbitrary name.

Invoking the  icon in the main menu offers the menu item to "Manage Identity Services" like this:

When clicking the desired Identity Service, by default the list of available roles is displayed. Users add a role with an arbitrary name from the "Add Role" button like this:

The role is assigned permissions to which the 4-eyes principle will apply: any selected operation will be subject to the Approval Process.

• Users are free to select any permissions for use with the Approval Process.
• Generally, view permissions make no sense for use with an Approval Process, users should focus on permissions to modify objects.
  
  

Assigning User Accounts the Requestor Role 

In a next step users assign any accounts the Requestor role that should be subject to the Approval Process.

• Role assignment is performed per Identity Service. If cascading Identity Services are used for authentication, then the role assignment has to be performed for each Identity Service.
• For Identity Services that manage roles with the Identity Provider a related mapping should be added.
  • For example, if the JS7 - LDAP Identity Service is used, then membership in a Security Group can be mapped to assignment of the Requestor role.
• The assignment of the Requestor role does not assign an account the permission to perform the given operation.
  • The account must be assigned some role that holds the permission to perform the operation.
  • The account can be assigned the Requestor role to force approval before performing the operation. This includes that user accounts that are not assigned the Requestor role are not subject to the Approval Process.

In the Manage Identiy Services -> Accounts sub-view, users can assign an account the Requestor role if the Identity Service manages roles, for example like this:

Managing Settings

In a final step users let JOC Cockpit know that the newly created role should be used for the Approval Process.

In the JS7 - Settings page, section joc, users assign the Requestor role like this:

Approver Profiles

Approver Profiles are used to specify which accounts can approve requests in the Approval Process.

Invoking the  icon in the main menu offers the menu item to "Manage Approvals".

The following sub-views are offered to

• manage Approval Requests,
• manage Approver Profiles,
• manage Notification Settings for E-Mail.
  
  

Users can manage Approver Profiles from the related sub-view by using the "New Approver Profile" button and by editing an existing Approver Profile from the related action menu like this:

• The account is specified that identifies the Approver Profile. The account name cannot be changed later on, instead a new Approver Profile must be created.
• If an E-Mail address is specified, then notifications will be sent to the Approver in case of new or updated Approval Requests.
• Any number of Approver Profiles can be added. When an Approval Request is created, then the preferred Approver will be notified. However, any Approver can manage any incoming Approval Request.
  
  

Notification Settings

From the "Notification Settings" sub-view users can specify a number of settings used to send e-mail like this:

Explanations:

• Assignment of a Job Resource that holds settings for the connection to the mail server is required. For details see JS7 - eMailDefault Job Resource.
• Remaining mail settings are common to any system sending mail.
• The subject and body of mail can include placeholders that will be substituted when sending mail. Placeholders are specified using the format ${placeholder}.
  • The following placeholders are available:

• • • ${RequestStatusDate}: Request Status Date
    • ${ApprovalStatusDate}: Approval Status Date
    • ${Title}: Request Title
    • ${Requestor}: Requestor account
    • ${RequestStatus}: Request Status, one of REQUESTED, EXECUTED, WITHDRAWN
    • ${Approver}: Approver account
    • ${ApprovalStatus}: Approval Status, one of APPROVED, REJECTED
    • ${RequestURI}: Request URI
    • ${RequestBody}: Request body holding the details of the REST API request
    • ${Category}: Category
    • ${Reason}: Reason
  • In addition, the following placeholders can be used if specfied from a Job Resource such as eMailDefault. See above first bullet point.
    • ${jocURL}: URL from which JOC Cockpit is accessible.
    • ${jocURLReverseProxy}: same functionality as jocURL, but specifies the URL as availlable from a Reverse Proxy
• Users are free to adjust the subject and body at their will.

Use the "Submit" button to persist changes.

Permissions

The following permissions limit access to operations in the Approval Process:

• Any account assigned the Requestor role or an Approver Profile can access the Manage Approvals page and Approval Requests sub-view.
  • Requestors can access Approval Requests only that they created.
  • Approvers can access any Approval Requests.
• In the Manage Approvals page the Approver Profiles sub-view and Notification Settings sub-view are accessible to accounts holding
  • the joc::administration::accounts::view permission for read access,
  • the joc::administration::accounts::manage permision to apply modifications.

Approval Process

The following explanations assume a Requestor role being in place that forces approval for any operation on orders except for viewing orders.

Step 1 (Requestor): Raising an Approval Request

If users assigned the Requestor role wish to perform an operation on orders such as cancelling an order, then the proceeding is as follows.

Creating an Approval Request

In a first step the user will invoke the related operation to cancel an order, for example from the Workflows view like this:

Instead of immediately performing the operation, a popup window is invoked that requires the user to specify the request, to select an Approver and optionally to add a reason for the Approval Request like this:

The request will be set to the REQUESTED status and can be answered by an Approver or can be withdrawn by the Requestor.

Withdrawing an Approval Request

A Requestor can withdraw an Approval Request from the Manage Approvals page.

The operation is available for Approval Requests

• in status REQUESTED, i.e. before an Approver will have confirmed or rejected the request
• in status APPROVED, i.e. after the Approver approved the request.

Step 2 (Approver): Answering an Approval Request

The Approver will be notified about pending Approval Requests and can approve the request or can reject the request.

Notification to Approver

Notifications apply to the Approver specified with the Approval Request.

Notifications are issued when an Approval Request is created or updated.

Notification from JOC Cockpit GUI

The JOC Cockpit GUI will display a notification icon in the title bar if there are pending Approval Requests. The icon indicates the number of pending Approval Requests like this:

Clicking the notification icon displays a link holding the information about the number of pending requests. Following the link the Approver will navigate to the Manage Approvals page.

Other than from notification any Approver can invoke the Manage Approvals page to manage pending requests.

Notification by E-Mail

If the Approver Profile is assigned an E-Mail address, then the Approver will be sent notification by mail.

A typical E-Mail can look like this:

From the E-Mail the Approver finds a link to navigate to JOC Cockpit, to authenticate and to invoke the Manage Approvals page.

Approving the Request

From the Manage Approvals page and Approval Requests sub-view the Approver finds the "approve" operation from the request's action menu item like this:

When approving a request, then it will be set to the APPROVED status which allows the Requestor to perform the requested operation.

In case that the Approver is not available or that other Approvers prefer to pick up the request, they can invoke the Manage Approvals page with the Approval Requests sub-view to find requests to which they are assigned for approval. Hitting the "All Approval Requests" checkbox will display requests managed by other Approvers too. This allows any Approver to manage Approval Requests in the assigned Approver's place.

Rejecting the Request

Similarly to approving the request, the operation to reject the request is available from the Manage Approvals page and Approval Requests sub-view.

When rejecting a request, then it will be set to the REJECTED status and will not offer further operations on the status of the request.

Step 3 (Requestor): Applying Intervention

Notification to Requestor

If an Approval Request is answered (approved or rejected), then the Requestor will find a notification icon in JOC Cockpit's title bar.

At this stage the Requestor has the following options:

• Apply the intervention of the approved request.
• Dismiss the requested intervention and withdraw the Approval Request.

Executing the Approved Request

When the Approval Request is confirmed by an Approver, then the Requestor can execute the underlying operation within the scope of available permissions.

The Requestor can navigate to the Manage Approvals page and Approval Requests sub-view to apply the "Execute" operation like this:

The request will be executed immediately and the status will be set to EXECUTED.

At this stage, no further notifications are sent.

Further Resources

• JS7 - Settings
• JS7 - Manage User Accounts
• JS7 - eMailDefault Job Resource