Introduction

JS7 allows users to provide their own User Documentation for scheduling objects in a number of formats and which can be imported to the JOC Cockpit. Once imported, the User Documentation can be linked to workflows, jobs etc. 

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

JS7 ships with a number of JS7 - Job Templates that include documentation by default.

User Documentation Formats

The User Documentation can be provided 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 either has to be imported as well or an HTTP address can be used.
• Additional file formats that 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 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 considered 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

Manage User Documentation

Import User Documentation

Permissions

By default user accounts assigned the application manager role are granted permissions for importing documentation items.

Import Procedure

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

Import Procedure for PDF Documents

When using the Import Documentation 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 that will be created on-the-fly.
• The Path is used to specify to which folder 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 assigned the User 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 Documents

The following example uses a simple HTML User 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:

Download: sample_test_job.zip

When clicking the Import Documentation button the archive is uploaded like this:

Explanation:

• For import the path /Samples is specified that points to a new folder that is created on-the-fly.
• The Path is used to specify to which folder 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 assigned the User Documentation.

After import the Resources->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 User Documentation

Permissions

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

Assignment Procedure

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

Klick the "More Options" checkbox to enable the Documentation input field.

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

Clicking theicon left to the job name opens the User Documentation in a new browser window or tab, depending on the configuration in the user account's profile, see Profile Settings.

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

Update User Documentation

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

The updated User Documentation will be immediately available for all objects it has been assigned to.

Delete User Documentation

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

In addition, documentation items 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:

Export User Documentation

User Documentation assigned a scheduling object is not subject to JS7 - Rollout of Scheduling Objects.

Instead, User Documentation can be exported and imported into another JS7 environment.

The Export Documentation button is displayed after a documentation item has been selected like this:

The export file (.zip) then is offered for download.

Manage Documentation Items

For documentation items included with a User Documentation a number of operations are available from the documentation item's action menu like this:

Explanation:

• Edit Documentation
  
  • The operation brings up the following popup window:
    
    
    
    
• Preview Documentation
  • Opens the User Documentation in a new browser tab or new browser window.
• Export
  • See Export Documentation
• Delete
  • See Delete Documentation
• Show Usage
  
  • The operation brings forward a popup window that displays the list of scheduling objects that are assigned the User Documentation like this:
    
    

Job Template Documentation

During setup of JOC Cockpit the User 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 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 Job Template the Documentation input field is automatically populated with the User Documentation entry like this:

With the User 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:

Profile Settings

Users can specify if the User Documentation should be displayed from a new browser tab or from a new browser window. This is specified in the user account's JS7 - Profiles like this:

The default setting is to open User Documentation in a new browser tab.