job scheduler - software- und organisations-service · scheduler_editor 2...

Software- und Organisations-Service GmbH Giesebrechtstr. 15 D-10629 Berlin Telefon (030) 86 47 90-0 Telefax (030) 861 33 35

Job Scheduler - Job Documentation Editor

JOB SCHEDULERJOB DOCUMENTATION EDITOR

Instructions for Creating Job DocumentationAugust 2006

scheduler_editor 2

Software- und Organisations-Service GmbH August 2006

Contact Information

Software- und Organisations-Service GmbHGiesebrechtstr. 15

D-10629 Berlin

Telephone (030) 86 47 90-0Telefax (030) 8 61 33 35Mail [email protected] http://www.sos-berlin.com

Last Updated: 31st August 2006

http://www.sos-berlin.com

mailto:[email protected]

scheduler_editor 3


Table of Contents

1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 Job Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1 Process Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.2 Script Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 Monitor Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

3 Documentation Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114.1 File Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114.2 Database Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114.3 Example Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5 Job Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135.1 Job Parameter Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135.2 Payload Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.3 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

6 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Appendix A: XML Schema / XSLT Style Sheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Appendix B: Example HTML Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Summary 4


1 SummaryThe Editor is a tool to assist in the creation of documentation of jobs for the Job Scheduler. The documentation ismade using a predefined XML format.The XML schema used for the job documentation: scheduler_job_documentation_v1.0.xsd

The documentation is intended to be written by the job developer and assist the user in implementing the jobconfiguration.

The Editor is form based and allows job documentation to be created in XML format without knowledge of XML.The documentation is shown to the user in a browser as a normal HTML page after being transformed from XMLwith the scheduler_job_documentation.xsl XSL style sheet.

The following example shows the HTML documentation for the JobSchedulerCheckSanity job:

The HTML page provides direct navigation to the individual subjects within the documentation such as Resources,Configuration, Releases and Documentation.The Generate Job link is used to generate an XML job configuration with a simple, basic structure. This code canbe copied and pasted into the Job Scheduler factory.xml file if required.

The documentation can be made available in two languages - English and German.

The following procedure should be followed when using the Editor to create the documentation for a job:

Note:

obligatory fields in the job documentation Editor have a yellow background

• select "New Documentation" under File item in the main Editor menu

• relevant information about the job - resources, configuration etc. are then entered

• the documentation is then saved by the Editor in a .xml file in the same directory as the"scheduler_job_documentation_v1.0.xsd" schema and the "scheduler_job_documentation.xsl" style sheet

• the saved XML file is transformed to HTML when opened in a standard web browser where thedocumentation appears as a standard HTML page

Summary 5


explanatory tool tips are available in the Editor and in the generated HTML documentation - these tool tips providea quick help when a user positions their mouse over active form elements such as entry fields, combination boxes,or radio buttons

Job Elements 6


2 Job ElementsThe form for entering job elements is opened by clicking on the Job link in the Editor tree menu.

The job Name und Title must be entered.

The Order field is used to specify whether or not a job is order controlled. An order activates the processing of ajob chain and contains the parameters for one or more jobs in the job chain.

The following entries are allowed:

In addition, a job is defined by either a <process> element or a <script> element.

After the job documentation together with the necessary parameters has been saved (menu item "File / Save" or"File / Save as"), it can be viewed by clicking the Preview button in the Job Elements form.

2.1 Process ElementsA <process> element is used to call an executable file. The Use process radio button should be activated when a<process> element is to be documented.Note that this causes any already existing <script> element description to be disabled and deleted from thedocumentation.

The Name of the executable file should be entered. Should a parameter be handed over when the file is called,then it should be entered in the Parameter field.

The Log field can be used to specify the name for a log file.

In addition, any number of environment variables required by the job can be defined. The Name and Value of eachenvironment variable are specified in turn. After these have been entered, the variable is added to the environmentvariable list by clicking the Apply button.

A sample <process> element configuration is shown in the screen shot below:

2.2 Script ElementsA <script> element is used when either a Java or Com class or a JavaScript, PerlScript or VBScript file is to beexecuted. The Script radio button should be activated before a <script> element can be documented.Note that activating a <script> element causes any already existing <process> element description belonging to thejob to be disabled and deleted from the documentation.

yes: The job is order controlled.

no: The job does not process orders.

both: The job can be started by orders or job starts.

Job Elements 7


The following radio buttons are available:

Resources which are required by a job are identified by a resource ID. This ID is entered in the Resource ID fieldand should be later documented using the Resources form. Should, for example, a job implement a Java class,then an ID for the Java archive containing the class should be specified here. Should resources already have beenadded to the documentation, then these resources may be selected from the list box.

A job can require one or more include files. The names of these files are entered in the form File field and thenadded to the list of include files by way of the Apply button.

Example <script> element configurations:

2.3 Monitor ScriptsMonitor scripts provide functions which are called before and after a task or before and after a spooler_process.The monitor can prevent a task from being started or a spooler_process from running.

The monitoring functions available are:

Monitoring scripts can be used for standard jobs in order to check if the job should run at all, before its processingis started. For example, are resources available, or have other starting conditions been satisfied? Thespooler_task_before() function must only return false in order to stop a job processing script from beingcarried out. In the same way, spooler_task_after() is used to post process a job. Monitor scripts can access

Java The job is to execute a Java class. In this case the name of the class must be entered in the JavaClass field.

Com A Com class is to be executed by this job. The name of the class should be entered in the Com Classfield.

Javascript

A JavaScript file is to be executed by this job. In this case the JavaScript file name must be entered inthe include file list.

PerlScript The job is to execute a PerlScript file. The file name should be entered in the list of include files.

VBScript A VBScript file is to be executed by the job. In this case the VBScript file name must be entered in theinclude file list.

• spooler_process_before• spooler_process_after• spooler_task_before• spooler_task_after

Job Elements 8


the Job Scheduler API and therefore can check the task Status, Exit-Code, etc. Depending on these parameters, amonitoring script can then start individual post-processing functions such as deleting any temporary files a job hascreated.

A monitor script with spooler_process_before() can determine for order controlled jobs whether the ordershould be carried out in a particular job or, for example, whether it should be given a new status or processed byanother job in the chain. spooler_process_after() can be used to start post processing according to specificconditions.

A <monitor> element is configured in the same way as a <script> element: a program language is selected and thename of the class or include file containing the monitor script code specified.Further information can be found in the Script chapter.An example job with a <script> element and a <monitor> element is shown below:

Documentation Releases 9


3 Documentation ReleasesA job documentation must be released at least once. This is done by clicking on the New Release button: Arelease ID (e.g. 1.0) as well as creation and change dates must be specified for each release. The creation andchange dates are initialised with the current date - the Date button can be used to call another date from acalendar.

A release can also be given (optionally) a title such as "Initial Release".

The notes button is used to open a text entry window with which comments about a release can be stored.Changes are logged by way of the text window opened using the changes button. Both the comments and thechanges log can be made available in the HTML version in more than one language - at the moment, provision hasbeen made for English and German. The alternative Languages are selected using the Language button.

Releases are completed with the author information: after the author's Name and e-mail address have beenentered, the Apply button used to add this information to the author list for the release.

The Remove button is used to delete an author from the list of authors.

Documentation can be released after ID, creation and change dates and at least one author have been entered.This is done using the Apply Release button which causes the document release to be added to the list of all jobdocumentation releases.

The Remove Release button is used to remove a release from the job documentation releases list.

Releases are shown in the HTML version of the documentation in reverse order, i.e. the current release is shownfirst. The "Show previous releases" link in the HTML version allows previous releases, if available, to be madevisible. For example:

Documentation Releases 10


Resources 11


4 ResourcesJobs require differing resources:• general resources such as the central memory available or hard disc capacity• file resources• database resources

Should a job require a minimum amount of main memory, then the Memory checkbox should be activated and avalue and units entered. A comment may be added using the Memory Notes button.

Similarly, the Space checkbox should be activated and appropriate values and units added, should a minimumammount of disk space be required by a job . The Space Notes button may be used to add a comment about thedisc space requirements.

4.1 File ResourcesA job also requires file resources, such as a Java archive containing a class with the program code required for thejob, DLLs, etc.

The New File button is used to document file resources. The file name and type (Java, binary, other) and theoperating system on which this type of file is to be used should then be entered.

An ID may be specified for a file resource: the <script> element resource ID will refer to this.

The Notes button may be used to add a comment about a file resource.

After all the information relevant to a file resource has been entered, the Apply File button is used to add theinformation about this resource to the list of documented file resources.

4.2 Database ResourcesA job may require a number of database resources such as a history or tables containing the job settings.

The New DB button is used to document database resources. The database name is an optional entry but whetheror not the database must be used is compulsory.

Entries documenting a database are added to the list of documented database resources using the Apply DBbutton.

Database objects are documented by first of all selecting a database from the list of documented databases. TheNew button is then used to open the form with which the database object is entered. The object name and type areentered together with a comment if required. The form has provision for the following types of database objects:• table• view• index• trigger• function• procedure• Java• other

The Apply button is then used to add a new or changed database object description to the list of database objectsfor the database.

Resources 12


4.3 Example ResourcesIn the generated HTML documentation, the Resources area could appear as shown below:

5 Job ConfigurationJobs for the Job Scheduler can be configured in a number of ways:

Note that the following settings hierarchy is observed: job parameters have priority over settings written in thefactory.ini file; settings specified in the factory.ini file have priority over database settings and database settingsoverwrite job presets.

A general description can be added to a job configuration, which shown in the HTML documentation page beforemore detailed information about individual job parameters or settings. An example configuration is shown below(the JobDocumentFactoryPrintoutSubmit job):

Job and order parameters and settings are then described in detail using the profile or database links in thedocumentation editor.

5.1 Job Parameter ElementsJob parameters are set in the job XML configuration file with the <params> element, e.g.

Job Configuration 13


• using job parameters set in the XML job configuration• with settings made in a Job Scheduler profile (the factory.ini file)• using database settings

Before individual job parameters are documented, it is recommended that a general ID is set for the configurationjob parameters. This ID can then be referenced from other parameters or settings.When this procedure is followed, it is not necessary to document individual profile or database settings when areference to the job parameters already exists.Note that it makes sense to use meaningful names for IDs - such as "job_parameters" for the parameters of a job -in order to allow these parameters to be clearly differentiated from, for example, payload parameters or databasesettings.

It is also possible to refer to other settings: in this case the ID of the element to be referenced should be entered inthe Reference field. Should, for example database settings already have been documented, then the ID of therelevant application within the database can be specified here.

The HTML page generates links for all references, for example:

The New Param button is used to document individual job parameters - this enables the form fields used to enterthe properties of individual parameters.

The parameter Name field is mandatory, all other properties are optional:





Required Specify whether or not a job parameter is mandatory or optional

Default Value A default value can be specified for a parameter

Reference Enter the ID of the element (for example, a profile or database setting) to be referenced.

ID Set an ID for the current job parameter. This ID can then be used so that other elements canrefer to this parameter.

Note This button is used to enter a comment about a job parameter.

The Apply Param button is used to add a job parameter together with all its properties to the list of documentedjob parameters.

5.2 Payload ElementsOrder controlled jobs can have order parameters which are forwarded as payload.

The Payload Note button is used to enter a general description of a job's order payload. In addition, an externalXML document can be documented using the Payload Document Note button.

An overall ID can be set for the job payload parameters. This ID can then be used to refer to the payload fromother parameters or settings.References to other settings can also be made: the ID of the element to be referenced can be either entered in orselected from the Reference box.

A general description can be added the order parameters of a job: this is done by clicking the Parameter Notebutton.

Individual order parameters are documented using the New Param button - which opens the form fields for theentry of the properties of individual order parameters.

The Name of an order parameter is mandatory, all other properties are optional:

Required Specifies whether an order parameter is mandatory or optional.

Default Value Allows a default value to be set for a parameter.

Reference The ID of an element to be referenced to.

ID Add an ID to a job parameter. This ID can be used by other elements to refer to thís jobparameter.

Note This button is used to add a comment to a individual order paremeter.

The Apply Param button is used to add the job order parameters to the list of documented order parameters.

5.3 SettingsJobs can be configured using settings within sections of a profile or a database.

The general information about the type of configuration can be documented within the Setting Note form.



5.3.1 Profile Elements

In order to document the settings within a profile, the form for documenting a new profile should first be openedusing the New Profile button. In general, only one profile is required for a job. However, it is possible to createmore if required. Should the profile not be given a name, then the value "default" will appear in the Name field. Thismeans that the profile will be given the default Job Scheduler name of "factory.ini".

A description of the profile can be added using the Profile Note button.

The Apply Profile button is used to add a new or a changed profile to the documented profiles list.

Once a profile has been created, a new Sections[Profile: ..] node appears in the tree menu in the left hand Editorwindow. The new profile is added below the Profiles node and the name of the new profile appears in the squarebrackets.

The next step is to describe the individual sections of the new profile. The profile to be described is opened byclicking on the appropriate Sections[Profile: ..] entry in the tree menu - in general, this is the default profile, i.e. the"factory.ini" file.

The form for entering the properties of the new section is opened using the New Section button in the right handEditor window. This form has fields for entering the following information:

Name The section name, e.g. "Job Section", which is mandatory.

Reference

The ID of an element, such as a job parameter, which is to be referenced, is entered here.

ID It is recommended that each section is given an ID. This then allows other elements to refer to thissection.

The Apply Section button is then used to add the new or changed section description to the list of sections.

Once a section has been documented, a new Settings[Section: ..] node appears in the Editor tree menu windowbelow the Sections node. The name of the section appears in the square brackets.

The last step is to document the individual settings within the profile section. Here, the section to be described isopened by clicking in the tree view on Settings[Section: ..].

New Setting in the right hand Editor window is then clicked to open the form for documenting the properties of theindividual setting:

The setting Name is mandatory, all other properties are optional:

Required Specifies whether a setting is optional or mandatory.

Default Value A default value can be given for a setting.

Type The type of data can be specified for a setting: integer, double, float, string, boolean, clob or blob.

Reference The ID of an element (e.g. a job parameter or a database setting) which is to be referenced to.

ID It is recommended that every setting is given its own ID. This then allows the setting to bereferenced to from other elements.

Note This button is used to add a comment to an individual setting.

The new or changed setting is then added to the list of documented settings using the Apply Setting button.



5.3.2 Database Connections

Jobs can be configured with settings held in so-called logical tables in a database. The logical tables are held in aphysical table on the Job Scheduler database - generally the SETTINGS table. Each individual setting belongs to asection within an application - this structure is followed in the SETTINGS table data model.

Four steps are required to document database settings - first of all the database itself must be described. After this,the application, the section and then the settings will be described.

1. Describe the Database Connection:

Select the Connections node in the Editor tree menu. The database connection is documented by clicking on theNew Connection button in the form to the right. Should no name be specified for the connection, then "default" willappear in the Name field. This means that the connection specified in the configuration file (the factory.ini profile) isthe Job Scheduler database.

A description of the database connection can be added by way of the Connection Note button.

The Apply Connection button is then used to add the new or updated database connection information to the listof database connections.

After a database connection has been documented, it is added to the tree menu below the Connections node in theform of a Applications[Connection: ..] node. The name of the connection appears within the square brackets.

2. Describe the Application:

Open the form for the database connection to be described by clicking on the Applications[Connection: ..] node forthe database connection to be described.

The New Application button in the right hand window is then used to access the fields for entering the applicationproperties:

Name The application name (mandatory).

Reference

The ID of an element to be referenced to.

ID An ID for the application. This ID allows other elements to refer to the application.

The Apply Application button is used to add the new or updated application information to the documentedapplications list.

After an application has been documented, a new Sections[Appl.: ..] node will appear in the tree menu below theApplications node. The name of the application will appear within the square brackets.

3. Describe the Section:

The application to be described should be opened by clicking on the appropriate Sections[Appl.: ..] link in the treemenu.

The New Section button in the right hand window should then be clicked to reach the section fields for entering thesection properties:

Name The section name must be specified. It can be advantageous here to use the job name as the name ofthe database section.

Reference

The ID of an element to which a reference is to be made (e.g. job parameter) is entered here.

ID It is recommended that each section is given its own ID. This allows the section to be referenced byother elements such a job parameters.



The Apply Section button is used to add the new or amended section documentation to the list of sections.

Once a section has been documented, a new Settings[Section: ..] node is added to the tree menu underneath theSections node.

4. Describe the Settings:

In the last step, the individual settings within the application section are described. The settings to be describedreached by clicking on the appropriate Settings[Section: ..] link in the Editor tree menu.

The New Setting button in the right hand Editor window is then clicked to open the form for entering the propertiesof the individual settings:

The Name of a setting is a mandatory entry, all other properties are optional:

Required Defines whether or not a setting itself is mandatory.

Default Value The default value for the setting - if any.

Type The data type for setting: integer, double, float, string, boolean, clob or blob.

Reference The ID of any element such as a job parameter or a database setting, which is to be referencedto.

ID An ID for the setting itself. With this ID other, elements can reference the setting.

Note This button is used to add a comment to a setting.

The Apply Setting button adds the new or changed setting to the list of documented settings.

Documentation 19


6 DocumentationThe "Documentation" link in the tree menu can be used to add an extended description of a job. This descriptioncan then be accessed directly in the HTML version of the documentation by way of the Documentation link.An Example:

XML Schema / XSLT Style Sheet 20


Appendix A: XML Schema / XSLT Style SheetThe directory in which the XML format job documents are saved must also contain thescheduler_job_documentation_v1.0.xsd XML Schema and the scheduler_job_documentation.xsl XSLT style sheet.

XML Schema for Job Documentation

This schema is used to validate the job documentation XML code.Show Source Code

XSLT Style Sheet for Job Documentation

This style sheet is responsible for the transformation of the documentation from XML format to a HTML page withnavigation elements.Show Source Code

http://www.sos-berlin.com/schema/scheduler_job_documentation.xsl

http://www.sos-berlin.com/schema/scheduler_job_documentation_v1.0.xsd

Example HTML Documentation 21


Appendix B: Example HTML DocumentationThe Documentation Editor is used to create a job documentation which is saved in XML format. The XML file isthen transformed to a HTML page by the user's web browser - a sample documentation with all menu links active(Link Show All selected) is shown below:

The Generate Job link can be used to generate a basic structure for the job documented in the Job SchedulerXML job configuration file (factory.xml). An example:

Example HTML Documentation 22


job scheduler - software- und organisations-service · scheduler_editor 2...

Documents