Page History

Introduction

In addition, an 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

Permissions

In the default configuration users with either the root or the application manager roles are able to import documentation items.

Formats Supported

The documentation function is intended for use with documents that users have created outside the scheduling environment with tools such as JSDoc and which are then imported and saved in the Reporting database. The following formats are supported:

• HTML (not all 'component' file types - e.g. .eot font files - are supported)
• XML
• html
• xml
• markdown (must have the file extension 'md' or 'markdown')
• pdfPDF
• zip 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 XSL (xml XML with the file extension 'xsl' or 'xslt')
  • images (gifGIF, jpegJPEG, pngPNG)
  • javascriptjavaScript
  • cssCSS
• 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 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 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 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.is not included in the virtual path.

The next screenshot shows the folder structure of the imported documentation item and the 'main' HTML file. The files from the CSS and images files can be accessed if required.

Image Added

Anchor
jitl jitl

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 view in the ./sos/jitl-jobs virtual folder tree.

The next screenshot shows the top part of the JITL jobs documentation items:

Image Added

Assigning Documentation

Permissions

While all of the default roles except the administrator have permission to view documentation, only the root and application manager roles have permission to assign documentation to scheduling objects.

The Assign Procedure

Documentation is assigned to a JobScheduler object using the Additional Options menu as shown in the screenshot below:

Image Added

Image Added

The Select from Tree folder symbol shown in the above screenshot opens a view of the Documentation virtual tree, which is shown below.

Image Added

The Submit button is used to complete the assigning procedure after the documentation has been selected. This is shown in the screenshot below.

Image Added

Once the documentation has been assigned to a JobScheduler object a documentation symbol is shown alongside the Job Chain node state as shown in the screenshot below. Note that a few seconds after this screenshot was made the JOC Cockpit added the documentation alongside the second node of the JobChain, as this node uses the same simple_test_job_01 Job as the first.

Image Added

Clicking on the documentation symbol will cause the documentation to be opened in either a new browser tab or window, depending on the configuration in the user's profile described in the next section.

Assigning to Other Objects - Job Chains

The procedure described above can also be used to assign documentation to a job chain as shown in the next screenshot.

Image Added

Updating Documentation

The import procedure described above can be used to update documentation files in the reporting database after changes. There is no provision for in-situ editing of files.

The updated version of a documentation file will be immediately available for all the objects the documentation has been assigned to. It is not necessary to reassign updated filesText ...

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 Modified

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

...

Documentation items can 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 the ones 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.

Deployment: e.g. from Development to Production

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.

Image Added

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"
    } ]
  } ]
}

  ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ Show If

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.