Introduction

Users wish to find an approval process in JOC Cockpit for situations in which users perfrom interventions such as adding or cancelling orders.

The following roles are involved:

• An Operator requests to perform an intervention that requires approval.
• An Approver confirms or denies the Operator's Approval Request.

The basic functionality of the Approval Process includes:

• to implement the 4-eyes principle: an Approver must confirm the intervention of an Operator.
• to keep track of pending Approval Requests.
• to offer fallback to a number of Approvers.
  
  

Prerequisites

Profiles

Operator profiles and Approver profiles are required to specify

• supported Notification Channels in their preferred order,
• one or more Notification Endpoints matching supported Notification Channels:
  • An e-mail address for receipt of Notifications,
  • A phone number for receipt of Notifications for mobile devices.

Internet Connection

JOC Cockpit, Controller and Agents are operated without internet connection.

Definitions

Notifications

Notification Channels include

• Internal Notifications
  • Notifying recipients in JOC Cockpit provided that an active session exists in JOC Cockpit for the recipients.
• External Notifications
  • Sending e-mail to recipients.
  • Sending SMS messages to mobile devices by e-mail using an SMS Gateway Provider that accepts e-mail which is converted to SMS messages and is forwarded to the recipient.
    • SMS Gateways are commercial services offered at low cost from a vast number or providers such as Twilio, Telnyx, Bird etc.
  • Sending WhatsApp messages to mobile devices using https://developers.facebook.com/docs/whatsapp/cloud-api/.
    • The Facebook Cloud API requires prior registration.
    • Consider that use of 3rd-party APIs and Services for sending WhatsApp messages is illegal. Use of the Facebook Cloud API only is legitimate.
  • Sending Signal messages to mobile devices using https://github.com/signalapp/libsignal

Users configure available Notification Channels and configure the ordering by which Notification Channels are triggered.

Notification Channels that require internet access, for example when sending messages to mobile devices, make use of the JOC Cockpit API Server that is operated from a separate machine with internet access.

• JOC Cockpit can access the API Server to send and to receive Notifications. The API Server does not establish a connection to JOC Cockpit.
  • Connections are established using mutual TLS authentication between JOC Cockpit and the API Server.
• The API Server offers a REST API to send Notifications and to receive Notifications.

Operator Groups and Approver Groups

Operators and Approvers are managed from groups:

• Operators are assigned a given JS7 role. A number of JS7 roles can be used to populate an Operator Group: Operators are selected from a given role and are added to the group in specific ordering.
  • This implies that user accounts that are not assigned a given JS7 role cannot create Approval Requests.
  • This implies that user accounts that are not assigned a given JS7 role cannot perform Approval.
  • Any user accounts are individually added to an Operator Group or Approver Group. Role assignment to groups remains in place and is checked at run-time for a given user account.
• Approvers are assigned a given JS7 role. A number of JS7 roles can be used to populate an Approver Group: Approvers are selected from a given role and are added to the group in specific ordering.
  • The same applies for role assignment as for Operators.

More than one Operator Group and Approver Group can be created. Each group is assigned matching folder permissions. The relation of folder permissions, Operator Group and Approver Group is persisted.

The following applies to the mapping of Approvers to Approval Requests:

• Any member of an Operator Group can prompt an Approver who is a member of the matching Approver Group for confirmation of an intervention.
  • For a given Approval Request the Operator can specify the preferred Approver (identified from the Approver's account) from the matching Approver Group.
  • If no preferred Approver is specified then the first Approver of the matching Approver Group will be assigned the Approval Request.
• Any member of an Approver Group matching the requesting Operator Group can handle Approval Requests.
  • The preferred Approver specified by the Operator for an Approval Request will be assigned and notified first.
  • If the preferred Approver will not respond to the Approval Request within a configurable period, then the next Approver in the Approver Group will be assigned and notified.

Approval Process Flow

The process flow works like this:

digraph structs {
    compound=true;
    # rankdir=LR;

    Operator [label="   Operator   ",style="filled",fillcolor="orange",fontname="Arial",fontsize="12pt"]
    Operator2 [label="   Operator   ",style="filled",fillcolor="orange",fontname="Arial",fontsize="12pt"]
    Approver [label="   Approver   ",style="filled",fillcolor="dodgerblue",fontname="Arial",fontsize="12pt"]
    Approval_Request [label="   Approval Request   ",style="filled",fillcolor="limegreen",fontname="Arial",fontsize="12pt"]
    Approver_Notification [label="   Notification   ",style="filled",fillcolor="limegreen",fontname="Arial",fontsize="12pt"] 
    Operator_Notification [label="   Notification   ",style="filled",fillcolor="limegreen",fontname="Arial",fontsize="12pt"] 
    Intervention [label="   Intervention   ",style="filled",fillcolor="limegreen",fontname="Arial",fontsize="12pt"]
 
    API_Server1 [label="   API Server   ",style="filled",fillcolor="grey",fontname="Arial",fontsize="12pt"]
    API_Server2 [label="   API Server   ",style="filled",fillcolor="grey",fontname="Arial",fontsize="12pt"] 
    Authorization_Server [label="   Authorization Server   ",style="filled",fillcolor="grey",fontname="Arial",fontsize="12pt"]
    Authorization_Code [shape="ellipse",label="   Authorization Code   ",style="filled",fillcolor="green",fontname="Arial",fontsize="12pt"]
    Authorization_Code2 [shape="ellipse",label="   Authorization Code   ",style="filled",fillcolor="green",fontname="Arial",fontsize="12pt"]

    Create_ApprovalRequest [shape="rectangle",label="Create/Sign",fontname="Arial",fontsize="10pt",style="filled",fillcolor="white"]
    Send_APIServer [shape="rectangle",label="Send",fontname="Arial",fontsize="10pt",style="filled",fillcolor="white"]
    Create_ApproverNotification [shape="rectangle",label="Create",fontname="Arial",fontsize="10pt",style="filled",fillcolor="white"]
    Notify_Approver [shape="rectangle",label="Notify",fontname="Arial",fontsize="10pt",style="filled",fillcolor="white"]

    Connect_AuthorizationServer [shape="rectangle",label="Connect",fontname="Arial",fontsize="10pt",style="filled",fillcolor="white"]
    Create_OperatorNotification [shape="rectangle",label="Create",fontname="Arial",fontsize="10pt",style="filled",fillcolor="white"]
    Notify_Operator [shape="rectangle",label="Notify",fontname="Arial",fontsize="10pt",style="filled",fillcolor="white"]
 
    Authenticate_AuthorizationServer [shape="rectangle",label="Authenticate",fontname="Arial",fontsize="10pt",style="filled",fillcolor="white"]
    Create_AuthorizationCode [shape="rectangle",label="Create",fontname="Arial",fontsize="10pt",style="filled",fillcolor="white"]
    Apply_AuthorizationCode [shape="rectangle",label="Apply",fontname="Arial",fontsize="10pt",style="filled",fillcolor="white"]

    subgraph encrypt {
        fontname="Arial";
        fontsize="12pt";

        Operator -> Create_ApprovalRequest -> Approval_Request [label="",fontname="Arial",fontsize="10pt"];
        Approval_Request -> Send_APIServer -> API_Server1 -> Create_ApproverNotification [label="",fontname="Arial",fontsize="10pt"];
        Create_ApproverNotification -> Approver_Notification -> Notify_Approver -> Approver;

        Approver -> Connect_AuthorizationServer -> Authorization_Server ->  Authenticate_AuthorizationServer -> Create_AuthorizationCode -> Authorization_Code -> API_Server2;
        API_Server2 -> Create_OperatorNotification -> Operator_Notification -> Notify_Operator -> Operator2 -> Apply_AuthorizationCode -> Authorization_Code2 -> Intervention;
    }
}

Use Cases

Operator prompts Approver to confirm Intervention

• The Operator is prevented from directly performing an intervention. Instead, a Notification is created for the requested intervention that is sent to an Approver.

• Fail-over and switch-over of JOC Cockpit must be supported.

• Approval Requests are persisted, and the list of pending requests is available in JOC Cockpit, allowing Operators to cancel pending Approval Requests.

Anchor
approver_connected_joc_cockpit approver_connected_joc_cockpit

Approver connected to JOC Cockpit

• An Approver who is connected to JOC Cockpit from an active session receives an Internal Notification within JOC Cockpit for pending Approval Requests. The Notification explains affected objects and the type of intervention.

  • The Approver confirms/denies the intervention in JOC Cockpit.
• If an Approver connected to JOC Cockpit from an active session does not respond to the Internal Notification within a configurable period, for example 5 minutes, then the process applies as explained from chapter Approver not connected to JOC Cockpit.

Anchor
approver_not_connected_joc_cockpit approver_not_connected_joc_cockpit

Approver not connected to JOC Cockpit

If an Operator prompts for confirmation of an intervention and the Approver is not connected to JOC Cockpit from an active session or does not respond to a JOC Cockpit Internal Notification, then the Approver will be notified externally.

The Approval Process is supported by an OIDC Identity Provider allowing to connect to JOC Cockpit and to approve the intervention. Any approval is performed inside JOC Cockpit.

• The Operator creates and digitally signs the Approval Request. The request includes the object, for a example an order, on which the intervention is performed and the type of intervention (delete, update, execute).
• The authorization flow corresponds to https://www.ory.sh/docs/oauth2-oidc/authorization-code-flow
  • The Approver clicks a link in the Notification message for the Approval Request.
  • The Approver is redirected to the Authorization Server, where they authenticate themselves and grant permission to the requested intervention.
  • The Authorization Server generates an authorization code and redirects the user back to the JS7 API Server with the authorization code.
  • The Approver is logged in to the JS7 API Server that stores the authorization code related to the Approval Request and logs out the Approver.
    • The JOC Cockpit that originated the Approval Request pulls the authorization code from the API Server and notifies the Operator. The Operator can enter the authorization code for the matching Approval Request to perform the intervention.

Capabilities

Prompt Notification

When an Operator prompts an Approver to confirm an intervention, then the Approver receives an Internal and/or External Notification. If an Approver confirms or denies an Approval Request, then the Operator receives an Internal and/or External Notification.

• Notifications include details about the internvention and about the Approver's response (confirmed/denied).

• Users can customize notification preferences. In case that the Approver is not available, another Approver should receive a notification in JOC Cockpit and via e-mail.

Approver Fallback

When an Approver does not pick up an Approval Request, then the next Approver in the Approver Group is notified to take over confirmation/denial of the suggested internvention to ensure that the Approval Process is not interrupted.

• If a number of Approvers receives Notifications for the same Approval Request, then only one Approver can confirm/deny the Approval Request.
• If an Approval Request is confirmed/denied then remaining Approvers who previously have been notified receive a Notification about completion of the Approval Request.

Pending Approval Requests

Along with real-time Notification of Approval Requests, Approvers receive a summary of pending Approval Requests.

Bulk Approval 

No bulk approval is supported. Approvers must confirm/deny Approval Requests individually.

Audit Log Entries

The Audit Log contains all operations and approval information to allow users to identify inconsistencies. The Audit Log records all operations, confirmations and denials. The Audit Log includes the User IDs of both Operator & Approver and intervention details.