Page History

...

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

...

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:

...

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.