Introduction

The User Documentation feature allows job developers to write their own documentation in a number of formats and to import the documentation to JOC Cockpit. Once imported, the documentation can be linked to workflows, jobs etc. 

In addition, an export operation is available that allows to rollout User Documentation, for example, from a development to a production environment

The JS7 ships with a number of JS7 - Job Templates that include the User Documentation.

Import Documentation

Permissions

By default user accounts assigned the application manager role are granted permissions to import documentation items.

Documentation Formats

The User Documentation can be imported from a number of formats:

• HTML (not all component file types are supported, for example .eot font files)
• Markdown (must use the file extension .md or .markdown)
• XML
• PDF
• Zip (for both Linux and Windows operating systems, tar.gz is not supported)
• The following file formats are also supported since they can be addressed by a relative path to a file:
  
  • XSL (XML with the file extension .xsl or .xslt)
  • images (.gif, .jpeg, .png)
  • JavaScript
  • CSS

Note:

• If an HTML file contains links with a relative address then the linked file has to be imported too or an HTTP address should be used.
• Additional file formats which are used as embedded objects in an HTML file such as audio files can be displayed but need an HTTP address instead of a relative address.
• Markdown files are converted to HTML when they are to be displayed:
  
  • Markdown files have to match the syntax of John Gruber.
  • During HTML conversion, a default .css file (/sos/css/default-markdown.css) is used and the title of the page is the name of the Markdown file.
  • The Markdown can start with reference-style links that are invisible.
    • These links can be used as header information for title and .css file
    • [css]: http://myHost/my.css or relative [css]: my.css
    • [title]: myTitle

Import Procedure

The below screenshot shows the Import button in JOC Cockpit's Resources->Documentation sub-view. The view shows the documents by default available for JS7 - Job Templates: 

Import Procedure for PDF Document

When using the Import button from the Resources->Documentation view then the following popup window is opened:

Explanation:

• The popup window offers to specify the Path to a folder in which to store the uploaded PDF document. An existing folder can be selected or the path to a new folder can be specified.
• The Path is used to specify to which virtual directory the documentation files should be stored. The Path specified does not have to reflect the folder structure used by scheduling objects such as workflows that later on should be linked to the documentation.

Having selected a PDF document for upload and having performed the import then the view displays the entry for the uploaded PDF document like this:

Import Procedure for HTML Document

The following example uses a simple HTML documentation: a single HTML file with CSS and image files in sub-folders. The files making up the example are zipped to preserve dependencies. The sample_test_job.zip archive is assumed to hold a sample_test_job folder that includes the following files and sub-folders:

When clicking the Import button the archive can be uploaded like this:

For import the path /Samples is specified that points to a new folder.

After import the Documentation sub-view looks like this:

Explanation:

• The /Samples folder is available with the sample_test_job sub-folder from the .zip archive. 
  • The sample_test_job.html document is available.
  • The css and images sub-folders are available with respective files.

Assign Documentation

Permissions

By default the application manager role is granted permissions to assign documentation to scheduling objects.

Assignment Procedure

Any scheduling objects can be assigned a documentation from the Configuration->Inventory sub-view like this:

With the documentation being assigned and the workflow or respective scheduling object being deployed the documentation is visible with the Workflows view like this:

Clicking the icon left to the job name opens the documentation in a new browser window or tab, depending on the configuration in the user account's profile

The proceeding to assign documentation is the same for any scheduling objects such as Resource Locks, File Order Sources etc..

Update Documentation

The import procedure described above can be used to update documentation files in case of changes. 

The updated version of a documentation will be immediately available for all objects the documentation has been assigned to.

Delete Documentation

Documentation items are deleted if the folder containing the documentation is deleted. This operation is available from the folder's action menu like this:

In addition, documents can be deleted individually. To this purpose the right panel offers to select documents available in a folder. If documents are selected then the Delete Documentation button is visible like this:

Rollout Documentation

Information about any documentation assigned to a Job us not added to the Job itself. This information is stored in the reporting database and requires to be exported when a scheduling environment is deployed, for example, from dev. to prod.

The Export documentation button is only displayed after documentation to be deployed has been selected as shown in the next screenshot.

The exported file is first saved to the local file system as a .zip file containing the assigned documentation information. This information is in JSON format and can then imported to the target system in the same manner as the documentation files and folders themselves. The order in which the documentation files and folders, and the assigned documentation information are important is not significant.

The following code block shows the assigned documentation information for the simple_test_job example already described in this article.

{
  "jobschedulerId" : "jobscheduler_1.12.8_0",
  "documentations" : [ {
    "documentation" : "/Docs/Jobs/simple_test_job/Simple Hello World Test Job.html",
    "objects" : [ {
      "type" : "JOB",
      "path" : "/demo/simple_test_chain/simple_test_job_01"
    } ]
  } ]
}

JITL Job Template Documentation

During setup of JOC Cockpit the documentation for the JS7 - Job Templates is automatically imported. The job documentation files are available with the Resources->Documentation view in the /sos/jitl-jobs folder like this:

In order to use a JITL Job Template when creating a new job in the Configuration->Inventory sub-view users can chose the Wizard as follows:

When invoking the Wizard then the following popup window opens:

Having selected the JITL Job Template the Documentation input field is automatically populated with the documentation entry like this:

With the documentation being assigned and the workflow being deployed the newly created job is visible from the Workflows view like this:

Consider the icon left to the job name that indicates availability of the job documentation.

When clicking the icon then the job documentation is displayed like this:

Depending on settings in the user account's profile the documentation is displayed in a new browser window or new browser tab.

Profile Settings for Documentation

Users can specify whether a documentation item can be viewed by opening a new browser tab or a new browser window. This is specified in the User Profile as shown in the next screenshot:

The default setting is that documentation items are opened in a new browser tab.