JS7 JobScheduler

Space shortcuts

Page tree

Introduction

The Audit Log allows compliance and operations reporting requirements for job scheduling activities to be met by providing an automatic and secure record of all actions that users of the JS7 - REST Web Service API - including JOC Cockpit users and external applications - perform on job-related objects. The Audit Log lists the relevant objects - Workflows, Orders, etc. - and any actions that modify their state.

Scope of the Audit Log

The Audit Log is written by the JS7 - REST Web Service API. and is maintained for all job-related objects such as Workflows, Orders, etc., whose states are modified by users carrying out actions such as starting, stopping or suspending an Order. It uses a format that is human and machine readable and fulfills the following main functions:

  • provision of a compliance-conform record in a simple file format that can be archived and handed over to a compliance officer,
  • provision of operational records of job scheduling activities for reporting purposes,
  • provision of an operational record that is readily accessible to operating staff,
  • provision of a second source of operational information if the database used to store operational records is not available.

Users of the JOC Cockpit with the necessary permissions can view the Audit Log in the JOC Cockpit by clicking the Audit Log link in the JOC Cockpit main menu as shown in the screenshot below. This view and, in particular, the Reasons, Time Spent and Ticket Link information is intended to provide users with more relevant operational information than is available from the History.


Explanation:

  • The Audit Log can be displayed for the currently connected Controller and for any registered Controllers.
  • Audit Log entries can be exported to files in Excel format.

Features

Compliance, Reporting and Operational Features

  • The Audit Log is written automatically by the JS7 Web Services:
    • Entries to the Audit Log are made when an action that changes the state of a JS7 Object is initiated in the JOC Cockpit or other application accessing the JobScheduler Web Services.
    •  There is no mechanism for switching off the Audit Log.
  • The Audit Log is written in two locations simultaneously:
    • In the DBMS used by the JS7 Web Services: 
      • This instance is used by the JOC Cockpit to allow operators to view the Audit Log information.
      • It is also used by the JOC Cockpit to generate a Microsoft Excel®-compatible export file for reporting purposes.
    • In the Audit Log file:
      • It is intended that this file is archived and used as a compliance record. System Administrators can make a copy of this file available to operating staff should the DBMS should not be available. 
      • The Audit Log file is named audit.log and located in
        • the jetty_base/logs folder on Linux systems and on Windows where jetty_base is the directory containing the Jetty web server configuration files as described in the JS7 - Log Files and Locations article.
  • All new entries will be added to the Audit Log - neither the log file nor the DBMS records are overwritten.
    • System administrators have to arrange an archiving and housekeeping system for the Audit Log file according to relevant compliance laws and corporate governance.
    • It is the responsibility of system administrators to check compliance requirements such as the retention period for the information contained in the Audit Log file.
  • The Audit Log is visible in the JOC Cockpit to:
  • The Audit Log is read-only for all JOC Cockpit users - only System Administrators that have access to both the file system and to the database can modify the log. 

Key to the Audit Log Entries

  • Created: the point in time when the action was performed.
  • Account: the user account that caused the action.
  • Request URL: the Web Service URL that was invoked by the JOC Cockpit. The URLs represent the object type and action, e.g. /orders/start.
  • Category: identifies the object for which the action was performed, e.g. a Controller for deployment and submissions.
  • Reasons: (can be mandatory or optional - see below) an explanation of why an action was carried out. Reasons are created either by selecting an item from a list of predefined reasons (configurable) or individual free text input. A maximum of 2000 characters can be added to a free text reason.
  • Time Spent: (optional) the number of minutes required for the action can be added.
  • Ticket Link: (optional) a URL can be added that points to a ticket system, e.g. the SOS Ticket System, to identify the underlying ticket for the intervention.

Users carrying out actions are able to add an explanatory comments - Reason, Time Spent and Ticket Link - for each action. These comments are entered as part of the specification of an action and are then saved in the Audit Log. They can then be read by all other JOC Cockpit users that have the necessary permissions. The form for the 'Add Order' action is shown as an example in the following screenshot:


Action Comments are made up of three elements as shown in the screenshot above:

  • Reasons (mandatory or optional):
    • Predefined Reasons which are selected from a drop-down list or 
    • Individual Reasons, which are entered in a text field
  • Time Spent (always optional):
    • in minutes
  • Ticket Link (always optional):
    • has to start with http://

Reasons are intended as an aid to later understanding why an action was carried out - for example, for operators on later shifts or for reporting purposes.

The Time Spent and Ticket Link parameters are intended as basic information for accounting and reporting which, if required, can be made transparent for job scheduling end customers.  

Mandatory or Optional Reasons

Reasons can be mandatory or optional for all users of the JOC Cockpit.

  • If Reasons are mandatory:
    • Users must provide a Reason for each action they carry out.
    • Users will be offered the option of entering Time Spent and Ticket Link parameters.
  • If Reasons are optional:
    • Users still have the possibility of activating them on an individual basis in their User Profile.
      • Activation of Reasons also allows users to enter Time Spent and Ticket Link parameters.
    • Reasons, along with Time Spent and Ticket Link parameters will be added to the Audit Log.

Configuring Mandatory Reasons

The  force_comments_for_audit_log flag is used to make the entry of Reasons mandatory. This parameter is set in the User->Settings menu like this:


Optional Action Notes

If Reasons are not mandatory - i.e. the force_comments_for_audit_log flag is set to false -  users can configure whether they wish to be offered the option of entering Reasons for the actions they carry out. This is configured with the Enable Reasons for Audit Log setting in Users' profiles as shown in the next screenshot:


If this option is not set and Reasons are not mandatory, which are the default settings, then Users will not be presented with the Enter a Reason function e.g. when adding orders.

Predefined Reasons

A predefined set of reasons is delivered with the JOC Cockpit.

Predefined Reasons are found in the User->Settings menu, see the above screenshot of the relevant page.

Individual Reasons

Individual Reasons can be entered in the text field as shown in the screenshot near the top of this page. 

Unicode characters are allowed.

Audit Log View

The Audit Log can be viewed by selecting Audit Log in the JOC Cockpit Main Menu.

An extract from the Audit Log for an individual workflow is visible in the Workflows view.

Request Body

The arrow at the left hand side of each entry in the Audit Log view list allows more detailed information about the request submitted to the JS7 Web Services - the Request Body to be viewed. This opens in a new row in the Audit Log as shown in the following screenshot and includes information about the Controller with which the order is to be processed, as well as the order variables and start time:

Filters

Filters are available to allow selected entries from the Audit Log to be displayed.

Advanced Search

In addition to the preset All, Today, Last hour, etc. filters listed at the top of the Audit Log view, there is an Advanced Search function which is opened with the Advanced Search button at the top right of the view. Note that the last filter selected overwrites any previous filters. For example, if the Today preset filter is selected and then From 09:00:00 To 18:00:00 then all Audit Log entries started between 09:00 and 18:00 will be displayed for all the days covered by the Audit Log.

Audit Log Location

See JS7 - Log Files and Locations

Audit Log Sample

The following sample shows a number of Web Service requests that have been performed by a user logging in with the the root account at 03:06:50, who created a new folder to import and deploy workflows and finally added a number of orders to a workflow:

Audit Log Sample 
2021-08-03T02:54:43,440 INFO  REQUEST: ./orders/add - USER: root - PARAMS: {"controllerId":"testsuite","orders":[{"workflowPath":"/ap/apWarnIfShorterThan","scheduledFor":"now"}],"auditLog":{}} - COMMENT: - - TIMESPENT: - - TICKET: -
2021-08-03T02:54:49,822 INFO  REQUEST: ./orders/add - USER: root - PARAMS: {"controllerId":"testsuite","orders":[{"workflowPath":"/ap/apWarnIfLongerThan","scheduledFor":"now"}],"auditLog":{}} - COMMENT: - - TIMESPENT: - - TICKET: -
2021-08-03T02:56:29,752 INFO  REQUEST: ./inventory/store - USER: root - PARAMS: {"objectType":"WORKFLOW","path":"/ap/apSomethingNew","valid":false,"configuration":{}} - COMMENT: - - TIMESPENT: - - TICKET: -
2021-08-03T03:06:50,940 INFO  REQUEST: ./login - USER: root - PARAMS: - - COMMENT: all - TIMESPENT: - - TICKET: -
2021-08-03T03:06:55,543 INFO  REQUEST: ./inventory/store - USER: root - PARAMS: {"path":"/TestRuns/Test0000000070","objectType":"FOLDER","valid":true} - COMMENT: - - TIMESPENT: - - TICKET: -
2021-08-03T03:06:56,241 INFO  REQUEST: ./inventory/import - USER: root - PARAMS: - - COMMENT: - - TIMESPENT: - - TICKET: -
2021-08-03T03:06:57,581 INFO  REQUEST: ./inventory/deployment/deploy - USER: root - PARAMS: {"controllerIds":["testsuite"],"store":{"draftConfigurations":[{"configuration":{"path":"/TestRuns/Test0000000070","objectType":"FOLDER","recursive":true}}]}} - COMMENT: - - TIMESPENT: - - TICKET: -
2021-08-03T03:07:03,477 INFO  REQUEST: ./orders/add - USER: root - PARAMS: {"controllerId":"testsuite","orders":[{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},{"workflowPath":"/TestRuns/Test0000000070/tcpForkBalanced_001-imported","orderName":"Test0000000070","arguments":{}},
...

Note that the COMMENT is used in the login REQUEST to display the Role a user has.

Explanation:

  • The Audit Log includes the Web Service URL, which allows the object type and operation to be identified. For example, ./orders/resume translates to the action of resuming an order that is identified by its Order ID as specified in the PARAMS part of each log entry.

Audit Log Export

The Audit Log Export function, which is activated with the button with the arrow shown in the next screenshot, allows the Audit Log to be exported in a reporting-friendly format either in whole or filtered.

The filtered table as shown in Audit Log view is exported as a Microsoft Excel® compatible .xlsx file. The next screenshot shows an exported file (opened in Open Office Calc).

Note that the PARAMS part of records (see the Audit Log Sample section above) are not included in the export.

Audit Log Housekeeping & Archiving

Depending on the number of deployments and interventions to the cause of order execution the Audit Log can grow to a considerable size.

The Audit Log in the JS7 database is purged by the JS7 - Cleanup Service. However, users who prefer to implement their own housekeeping and archiving according to their business and compliance requirements can disable purging of the Audit Log by the Cleanup Service.

The Audit Log file on disk is subject to log rotation, see JS7 - Log Rotation.


  • No labels