IT Automation: Job Documentation Version Management with SAP Solution Manager
An important capability of efficient and effective operations and a conditio sine qua non for intelligent enterprise and digital transformation is automation management, aka background job management or job management. The concept and toolsets are by no means new, please find a recent overview here. In this article, a specific detail of the background job/IT automation request and documentation management in and with SAP Solution Manager 7.2 is briefly outlined which has been causing a few questions and frustrations recently: Job Documentation Versioning. The presented process instance and example case reflects an actual implementation, therefore some data has been masked.
General Job Management Recap
End-to-End Background Job Request and Documentation Management enables an IT organization to establish an integrated automation life cycle management. After approval and documentation of background jobs, they are scheduled, monitored (Event Management) and optimized (Continuous Improvement) by the Operations Control Center using SAP Solution Manager Job Management.
The general process follows this document flow. A popular variant is visualized below. Job Request is used to request Job Scheduling. Business users (Run, aka Ops) or project members (Build, aka Dev) submit job requests when they want to have a new job scheduled, an existing job changed, or an existing job retired. The job request is processed, i.e. approved or rejected. If approved, a Job Documentation is created (if new) or updated (if existing). This job documentation document per background job stores all job relevant information like job description, contact persons, error handling, further attachments and much more and ensures that all the overall solution documentation includes background jobs and IT automation.
A more detailed explanations of Job Management process variants please find in this article.
Specific Job Management Challenge: Job Documentation Version Management
The job documentation document is the central artifact of the Job Management process, in any of its variants. It allows the central documentation of background processing/IT automation for your entire system and solution landscape in one location in SAP Solution Manager. This documentation repository (i.e. the job documentation status management) is embedded in Solution Documentation.
Create Job Documentation
After the Job Request is approved, the Job Documentation is created (we assume for this example that it does not already exist). After the data taken from the Job Request is reviewed and the Job Documentation document is set to ‘In Process’, further data is maintained (Dropdown: Further Details), to ensure that all details are provided (see 1).
The Job Documentation document is validated (button: Validation) (see 2). After the validation checks, it is set to status ‘Validated’ (button: Set to Validated) (see 3). Thereafter, the Job Documentation document is in status ‘Validated’ (document status) (see 4), the Job Request ticket is in status ‘Approved’ (processing status) (see 5). Thereafter, the Job Documentation document is in version 1 (Ver. 1) (see 6).
Update Job Documentation
The life cycle of a Job Documentation document (single version), i.e. the document status, is outlined below:
Status ‘In Process’, ‘Validated’, and ‘Production’ are referred to as active status. Some important behavior of the Job Documentation document versioning is worth noting and remembering.
- The same version of a Job Documentation document allows to go back and forth in documentation status, prior to document status ‘Production’, without creating new versions of the Job Documentation document.
- New versions of the Job Documentation document can be created without embedding it into the processing status, i.e. without wrapping a request process instance around document status change. Via menu ‘Further Actions –Create new Version’, a new version of the existing Job Documentation document can be created.
Dependent on the implementation of Job Management, there can be several ‘active’ status of a job documentation document (status In Process, Validated, or Production) at the same time.
However, there is only one productive status, i.e. document status ‘Production’, at a time. Hence, the Job Documentation document version becomes important. Whenever a Job Documentation document is set to ‘Production’, the previous one becomes obsolete, i.e. document status ‘Obsolete’. Vice versa should not work, e.g. if the productive Job Documentation document, i.e. document status ‘Production’, is set to ‘In Process’, any existing Job Documentation document in document status ‘Obsolete’ will stay obsolete.
For Job Documentation documents in document status ‘In Process’ new versions can be created without embedding in processing status via menu ‘Further Actions – Create new Version’. When embedded in the processing status, i.e. when following the process instance from Job Request form to Job Documentation document within the Job Request ticket (in Solution Manager or external ITSM solution) (as visualized in the first paragraph in this article), there is a new version of the Job Documentation document created as long as there exists already a Job Documentation document. This means, a change request comes with a new version automatically. Please note: Before a new version of a Job Documentation document can be set to status ‘Production’ (document status), the processing status of any job request ticket of previous versions of this Job Documentation document has to be set to ‘Confirmed’ (or equivalent) (processing status).
Further Job Documentation Document Version Management Details
In SAP Solution Manager 7.2 Support Package 11 (SP11) and lower, SAP Solution Manager provides an internal blocking mechanism to avoid that any older version of a Job Documentation document is changed. In the example above, when trying to set e.g. version 2 from document status ‘Obsolete’ to ‘In Process’, an error message is displayed (version 3 is the production version).
Validating an older version is not allowed either. When trying to set e.g. version 4 from document status ‘In Process’ to ‘Validated’, an error message is displayed (version 3 is the production version).
In SAP Solution Manager 7.2 Support Package 12 (SP12) and higher, SAP Solution Manager provides an internal blocking mechanism with a slightly different system behavior. Please note the difference, using the same example as above.
The status of any currently processed Job Documentation document version can always be set to one of the options offered in the header with no block, but possibly a warning. In the example above, when trying to set e.g. version 2 from document status ‘Obsolete’ to ‘In Process’, a warning message is displayed (version 3 is the production version). But it allows the change of document status.
Validating an older version is allowed. When trying to set e.g. version 4 from document status ‘In Process’ to ‘Validated’, a warning message is displayed (version 3 is the production version).
However, if the status of any currently processed Job Documentation document version is set to document status ‘Production’ and another version is already existing in document status ‘Production’, then the change of status to ‘Production’ (of the currently processed version) is allowed, and the already existing version will be set to documentation status ‘Obsolete’.
Side remark: Another potential for misunderstandings is the standard display behavior of Job Documentation documents in the SAP Solution Manager Fiori Application Job Documentation (group Job Management).
The application displays existing Job Documentation documents and is as such very important for Operations Control Centers and alike. In standard queries the so called “current version” is presented, which is the last changed version. Using the example above, one might expect to be presented with the productive Job Documentation document (which is version 3 in the example above), i.e. display by document status. However, the standard configuration of the query (POWL – Personalized Object Work List) displays the latest version, i.e. display by version. The latter might not be the productive Job Documentation document which you need to display and process.
If you want to get the productive Job Document displayed, change the POWL query to filter Documentation Status = PRODUCTIVE only (not to any other document status in addition).
Of course, you can also use the Quick Search. It will display all versions, including the Job Documentation document with document status ‘Production’ (should it exist).
Job Documentation documents can be assigned a business process context and a Solution Documentation context. This can be recommended and offers an additional means of organization and discipline. However, in the latter case, by default only Job Documentation documents assigned to the Production Branch of Solution Documentation are displayed. This can lead to confusion and frustration, e.g. when not finding active Job Documentation documents any more.
Therefore note: If Job Documentation documents are assigned to a branch different than Production Branch, change the selection in the POWL query search criteria (POWL – Personalized Object Work List). Use field “Solution Documentation ID” and select the branch and/or type (scenario, business process, or business process step). Refer to SAP Note 2666323 for further details and configuration. For latest features and improvements in SAP Solution Manager 7.2 Operations functionalities (i.e. Application and Business process Operations), refer to SAP Help Portal.
More details please find in the SAP Solution Manager 7.2 Media Center. The SAP Solution Manager 7.2 Public Demo System invites interested parties to log on to an SAP Solution Manager 7.2 and try for yourselves.