Product Knowledge Base

Space shortcuts

Page tree

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

Introduction

The Job documentation feature allows job developers to write their own documentation in a number of formats 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. 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

FEATURE AVAILABILITY STARTING FROM RELEASE 1.12.8

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:

 

Clicking the Import Documentation button opens the following modal window:

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:

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.

JITL Job Documentation

Documentation for all the JITL Jobs which are delivered with the JobScheduler is automatically imported from the ${SCHEDULER_DATA}/jobs folder to 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:

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.

 

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.

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

Current Situation

  • Users can create job documentation in XML files. The JOE job editor provides the functionality to generate the respective XML files from user input.
  • Such documentation files have to be linked to a job, e.g. by storing files in the ./jobs directory and following the given naming convention.

Desired Behavior

  • Users would like to create documentation with any sort of tool:
    • this includes - but is not limited to - use of JSDoc that would document sources of JavaScript jobs and monitors.
      • JSDoc generated documentation includes the JavaScript source code and therefore would make visible JavaScript files that are used in jobs and monitors via the <include> element. Currently users cannot visualize the contents of such files - not with JOE and not with the JOC Cockpit.
      • JSDoc generated documentation comes as a single HTML file that should be visible with the JOC Cockpit.
    • this suggests to support any sort of HTML based documentation created with an HTML editor or generator.
    • this suggests support for lightweight markup for HTML representation as e.g. created with markdown syntax.
    • this suggests ongoing support for structured documentation in an XML format such as used by the JOE job editor. However, the presentation should be done in HTML, e.g. by use of individual stylesheets.
  • Users would like to add documentation to any JobScheduler objects such as jobs, job chains, process classes, locks etc.
  • The documentation should be visible with the JOC Cockpit for individual objects.

Limitations

  • The import of documentations doesn't allow all file formats. Allowed formats are primarily:
    • html
    • xml
    • markdown (must have the file extension 'md' or 'markdown')
    • pdf
  • 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.
  • Further file formats which are used as embedded objects in an html file such as an audio file can be displayed but needs an http address instead of a relative address.
  • Markdown files are converted to html when they are to be displayed
    • 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

Deployment

I have to add the documentation info of the job and of a permanent order if exist inside the ./job_chains and ,/job_chain api response if "compact":false which actually only contain volatile information.
So, the response should contain

{
	"deliveryDate": "2018-12-10T09:33:14.081Z",
	"jobChains": [{
		...
		"nodes": [{
			"job": {
				...
				"documentation": "/sos/jitl-jobs/CreateDailyPlan"
			},
			...
			"orders": [{
				"_type": "PERMANENT",
				...
				"documentation": "/sos/dailyplan/CreateDailyPlan",
			}]
		}],
	}]
}

Deployment of documentation is supported with export/import.

  • the exported file is a zip file containing the original folder structure and at the import of this zip file this folder structure will be adopted.

 

 

  • No labels