Page History

Introduction

The Job documentation feature allows job developers to write their own documentation in a variety number of formats can be imported - i.e. made available to users of the JOC cockpit - and and import this information to the scheduling environment. Once imported, the documentation can be assigned - i.e. linked - to Jobs and other JobScheduler objects such as Job Chains, Process Classes and Locks. This means that job developers Developers can not only integrate documentation describing how jobs and other objects are to be configured but also documentation describing how objects are used in a scheduling environment.

In addition, a export function allows documentation, together with a list of the objects individual documentation items have been assigned to, to be readily moved, for example, from a development to a production environment

See the How to link jobs to custom documentation sources article for information about how to link to documentation with JobScheduler versions up to and including 1.12.7.

Importing Documentation

Formats Supported

The documention function is intended for use with documents that developers have created outside the scheduling environment and which are then imported and saved in the Reporting database. The following formats are supported:

• html
• xml
• markdown (must have the file extension 'md' or 'markdown')
• pdf
• zip (for both Windows and Linux OSs, tar/gz is not supported)
• The following file formats are also allowed, since they can be relatively addressed as external files:
  
  • xsl (xml with the file extension 'xsl' or 'xslt')
  • images (gif, jpeg, png)
  • javascript
  • css
• 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 a HTML file such as audio files can be displayed but need a http address instead of a relative address.
  • Markdown files are converted to html when they are to be displayed and:
    
    • They have to match the syntax of John Gruber.
    • During the 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 which 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

The Import Procedure

The following example uses a simple HTML documentation item: a single HTML file with CSS and image files in subfolders. The files making up the example are zipped to preserve dependencies on bothe Windows and Linux systems.

The screenshot below shows the Import button in JOC Cockpit's Resources.Documentation tab containing only the JITL Job documentation, which is imported per default, as described in the JITL Job Documentation section below:

Image Added 

Clicking the Import Documentation button opens the following modal window:

Image Added

In the above screenshot:

• The Drag and Drop File area and Choose Files to Upload button are used to select the files to be imported.
• The Path field is used to define in which virtual directory the Documentation files are to be saved in. A path specified here does not have to reflect the file structure of any JobScheduler objects that are to be documented and can be used to create an Documentation-specific structure if required. Note that while the folder symbol at the right of the Path field can be used to open a dialog to navigate through the Documentation virtual file structure, it will only show folders that already contain documentation. Folders corresponding with any existing but undocumented folder structure in the JobScheduler live folder must be entered manually.

The next screenshot shows the start of one possible approach to structuring documentation files:

Image Added

The virtual Path specified in the screenshot above reflects the organization of documentation items according to object type, with a folder for jobs, one for Orders, etc. Such a 'centralized' approach to the organization of Documentation fits in well the the concept of reusing JobScheduler objects. 

In addition note that the name chosen for the zip file reflects the Job being documented - this name will be used for the name of the folder containing the documentation.

Anchor
jitl jitl

JITL Job Documentation

Documentation for all the JITL Jobs which are delivered with the JobScheduler is available in automatically imported from the ${SCHEDULER_DATA}/jobs folder where ${SCHEDULER_DATA} is the JobScheduler data directory that has been specified during installationto the JobScheduler's Reporting database when the JobScheduler master is installed. The JITL documentation files are then shown in the JOC Cockpit's Resources.Documentation tab in the ./sos/jitl-jobs virtual folder tree.

Assigning Documentation

Text ...

Configuration

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:Image Added

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

Deleting Documentation Items

Documentation items either be deleted individually, by using the Additional Options (ellipsis symbol) menu for each object as shown in the first screenshot below or by opening all the items within a virtual folder, selecting theones to be deleted and using the "Delete Documentation" button as shown in the second screenshot below.

Image Added

Image Added

Once a virtual folder is empty it will automatically be removed from the virtual file tree, when the file tree is reloaded. This is best achieved by the user logging out from the JOC cockpit and then logging in again.

 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~

...