JOB SCHEDULER JOB DOCUMENTATION EDITOR

Transcription

1 Job Scheduler - Job Documentation Editor JOB SCHEDULER JOB DOCUMENTATION EDITOR Instructions for Creating Job Documentation August 2006 Software- und Organisations-Service GmbH Giesebrechtstr. 15 D Berlin Telefon (030) Telefax (030)

2 scheduler_editor 2 Contact Information Software- und Organisations-Service GmbH Giesebrechtstr. 15 D Berlin Telephone (030) Telefax (030) Mail info@sos-berlin.com Web Last Updated: 31st August 2006

3 scheduler_editor 3 Table of Contents 1 Summary Job Elements Process Elements Script Elements Monitor Scripts Documentation Releases Resources File Resources Database Resources Example Resources Job Configuration Job Parameter Elements Payload Elements Settings Documentation Appendix A: XML Schema / XSLT Style Sheet Appendix B: Example HTML Documentation

4 Summary 4 1 Summary The Editor is a tool to assist in the creation of documentation of jobs for the Job Scheduler. The documentation is made 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 job configuration. 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 XML with 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 can be 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: 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 the documentation appears as a standard HTML page Note: obligatory fields in the job documentation Editor have a yellow background

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

6 Job Elements 6 2 Job Elements The 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 a job chain and contains the parameters for one or more jobs in the job chain. The following entries are allowed: yes: no: both: The job is order controlled. The job does not process orders. The job can be started by orders or job starts. 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 Elements A <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 the documentation. 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 each environment variable are specified in turn. After these have been entered, the variable is added to the environment variable list by clicking the Apply button. A sample <process> element configuration is shown in the screen shot below: 2.2 Script Elements A <script> element is used when either a Java or Com class or a JavaScript, PerlScript or VBScript file is to be executed. 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 the job to be disabled and deleted from the documentation.

7 Job Elements 7 The following radio buttons are available: Java Com Javascrip t PerlScript VBScript The job is to execute a Java class. In this case the name of the class must be entered in the Java Class field. A Com class is to be executed by this job. The name of the class should be entered in the Com Class field. A JavaScript file is to be executed by this job. In this case the JavaScript file name must be entered in the include file list. The job is to execute a PerlScript file. The file name should be entered in the list of include files. A VBScript file is to be executed by the job. In this case the VBScript file name must be entered in the include file list. Resources which are required by a job are identified by a resource ID. This ID is entered in the Resource ID field and 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 been added 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 then added to the list of include files by way of the Apply button. Example <script> element configurations: 2.3 Monitor Scripts Monitor 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: spooler_process_before spooler_process_after spooler_task_before spooler_task_after Monitoring scripts can be used for standard jobs in order to check if the job should run at all, before its processing is started. For example, are resources available, or have other starting conditions been satisfied? The spooler_task_before() function must only return false in order to stop a job processing script from being carried out. In the same way, spooler_task_after() is used to post process a job. Monitor scripts can access

8 Job Elements 8 the Job Scheduler API and therefore can check the task Status, Exit-Code, etc. Depending on these parameters, a monitoring script can then start individual post-processing functions such as deleting any temporary files a job has created. A monitor script with spooler_process_before() can determine for order controlled jobs whether the order should be carried out in a particular job or, for example, whether it should be given a new status or processed by another job in the chain. spooler_process_after() can be used to start post processing according to specific conditions. A <monitor> element is configured in the same way as a <script> element: a program language is selected and the name 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:

9 Documentation Releases 9 3 Documentation Releases A job documentation must be released at least once. This is done by clicking on the New Release button: A release ID (e.g. 1.0) as well as creation and change dates must be specified for each release. The creation and change dates are initialised with the current date - the Date button can be used to call another date from a calendar. 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 the changes log can be made available in the HTML version in more than one language - at the moment, provision has been 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 address have been entered, 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 job documentation 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 shown first. The "Show previous releases" link in the HTML version allows previous releases, if available, to be made visible. For example:

10 Documentation Releases 10

11 Resources 11 4 Resources Jobs 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 a value 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 minimum ammount of disk space be required by a job. The Space Notes button may be used to add a comment about the disc space requirements. 4.1 File Resources A job also requires file resources, such as a Java archive containing a class with the program code required for the job, DLLs, etc. The New File button is used to document file resources. The file name and type (Java, binary, other) and the operating 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 the information about this resource to the list of documented file resources. 4.2 Database Resources A 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 whether or not the database must be used is compulsory. Entries documenting a database are added to the list of documented database resources using the Apply DB button. Database objects are documented by first of all selecting a database from the list of documented databases. The New button is then used to open the form with which the database object is entered. The object name and type are entered 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 objects for the database.

12 Resources Example Resources In the generated HTML documentation, the Resources area could appear as shown below:

13 Job Configuration 13 5 Job Configuration Jobs for the Job Scheduler can be configured in a number of ways: using job parameters set in the XML job configuration with settings made in a Job Scheduler profile (the factory.ini file) using database settings Note that the following settings hierarchy is observed: job parameters have priority over settings written in the factory.ini file; settings specified in the factory.ini file have priority over database settings and database settings overwrite job presets. A general description can be added to a job configuration, which shown in the HTML documentation page before more 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 the documentation editor. 5.1 Job Parameter Elements Job parameters are set in the job XML configuration file with the <params> element, e.g.

14 Job Configuration 14 Before individual job parameters are documented, it is recommended that a general ID is set for the configuration job 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 a reference 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 database settings. It is also possible to refer to other settings: in this case the ID of the element to be referenced should be entered in the Reference field. Should, for example database settings already have been documented, then the ID of the relevant 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 enter the properties of individual parameters. The parameter Name field is mandatory, all other properties are optional:

15 Job Configuration 15 Required Default Value Reference ID Note Specify whether or not a job parameter is mandatory or optional A default value can be specified for a parameter Enter the ID of the element (for example, a profile or database setting) to be referenced. Set an ID for the current job parameter. This ID can then be used so that other elements can refer to this parameter. 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 documented job parameters. 5.2 Payload Elements Order 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 external XML 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 from other parameters or settings. References to other settings can also be made: the ID of the element to be referenced can be either entered in or selected from the Reference box. A general description can be added the order parameters of a job: this is done by clicking the Parameter Note button. Individual order parameters are documented using the New Param button - which opens the form fields for the entry of the properties of individual order parameters. The Name of an order parameter is mandatory, all other properties are optional: Required Default Value Reference ID Note Specifies whether an order parameter is mandatory or optional. Allows a default value to be set for a parameter. The ID of an element to be referenced to. Add an ID to a job parameter. This ID can be used by other elements to refer to thís job parameter. 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 Settings Jobs 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.

16 Job Configuration Profile Elements In order to document the settings within a profile, the form for documenting a new profile should first be opened using the New Profile button. In general, only one profile is required for a job. However, it is possible to create more if required. Should the profile not be given a name, then the value "default" will appear in the Name field. This means 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 Editor window. The new profile is added below the Profiles node and the name of the new profile appears in the square brackets. The next step is to describe the individual sections of the new profile. The profile to be described is opened by clicking 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 hand Editor window. This form has fields for entering the following information: Name Referenc e ID The section name, e.g. "Job Section", which is mandatory. The ID of an element, such as a job parameter, which is to be referenced, is entered here. It is recommended that each section is given an ID. This then allows other elements to refer to this section. 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 window below 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 is opened 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 the individual setting: The setting Name is mandatory, all other properties are optional: Required Default Value Type Reference ID Note Specifies whether a setting is optional or mandatory. A default value can be given for a setting. The type of data can be specified for a setting: integer, double, float, string, boolean, clob or blob. The ID of an element (e.g. a job parameter or a database setting) which is to be referenced to. It is recommended that every setting is given its own ID. This then allows the setting to be referenced to from other elements. 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.

17 Job Configuration Database Connections Jobs can be configured with settings held in so-called logical tables in a database. The logical tables are held in a physical table on the Job Scheduler database - generally the SETTINGS table. Each individual setting belongs to a section 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 the New Connection button in the form to the right. Should no name be specified for the connection, then "default" will appear in the Name field. This means that the connection specified in the configuration file (the factory.ini profile) is the 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 list of database connections. After a database connection has been documented, it is added to the tree menu below the Connections node in the form 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 for the database connection to be described. The New Application button in the right hand window is then used to access the fields for entering the application properties: Name Referenc e ID The application name (mandatory). The ID of an element to be referenced to. 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 documented applications list. After an application has been documented, a new Sections[Appl.:..] node will appear in the tree menu below the Applications 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 tree menu. The New Section button in the right hand window should then be clicked to reach the section fields for entering the section properties: Name Referenc e ID The section name must be specified. It can be advantageous here to use the job name as the name of the database section. The ID of an element to which a reference is to be made (e.g. job parameter) is entered here. It is recommended that each section is given its own ID. This allows the section to be referenced by other elements such a job parameters.

18 Job Configuration 18 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 the Sections node. 4. Describe the Settings: In the last step, the individual settings within the application section are described. The settings to be described reached 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 properties of the individual settings: The Name of a setting is a mandatory entry, all other properties are optional: Required Default Value Type Reference ID Note Defines whether or not a setting itself is mandatory. The default value for the setting - if any. The data type for setting: integer, double, float, string, boolean, clob or blob. The ID of any element such as a job parameter or a database setting, which is to be referenced to. An ID for the setting itself. With this ID other, elements can reference the setting. 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.

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

20 XML Schema / XSLT Style Sheet 20 Appendix A: XML Schema / XSLT Style Sheet The directory in which the XML format job documents are saved must also contain the scheduler_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 with navigation elements. Show Source Code

21 Example HTML Documentation 21 Appendix B: Example HTML Documentation The Documentation Editor is used to create a job documentation which is saved in XML format. The XML file is then 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 Scheduler XML job configuration file (factory.xml). An example:

22 Example HTML Documentation 22