TIF ENOVIA/3DExperience Connector - Scheduled Jobs

23 August 2013

1. Scheduled Jobs

TIF provides support for running jobs at a scheduled time or period. The scheduled jobs are defined within a file called timetable.xml within the directory ${ROOT_DIR}/modules/enovia/etc.

You can have instance specific timetable definitions. This is accomplished by adding more timetable files, within the same directory, following this naming convention:

  • timetable.xml

  • timetable-{instance-id}.xml

  • timetable-{node-id}.xml

  • timetable-{node-id}-{instance-id}.xml

The file names are case-insensitive

TIF does not contain any timetable files per default. However, a sample file called timetable.xml.sample is provided in the same directory containing information and examples how to register scheduled jobs.

1.1. Configuration Format

The root element of the XML file is <timetable>. Below this element you may have the following elements:

  • group

  • job

Jobs may be put into groups or un-grouped. Within the group element you may only have "job" elements.

The <group> element must have an attribute called "id" containing the ID of the group (unique among all groups). An example is shown below:

<timetable>
    <job id="job1">...
    <job id="job2">...
    <group id="g1">
        <job id="job3">...
        <job id="job4">...
        ...
    </group>
    <group id="g2">
        <job id="job5">...
    </group>
</timetable>

1.2. Job Element

The <job> element defines the details of the scheduled job. You may configure a job to do one of the below

  • Execute a Java class

  • Execute a Script

  • Execute a MQL statement

  • Execute / Run a Job definition

The job element must have one attribute called "id" containing a unique identifier for the job.

The possible child elements for the job element is shown in the table below:

Child Element Description Required Example

<args>

Used to provide the job with arguments

No

 
<args>
    <arg name="arg0" value="true" type="boolean"/>
    <arg name="arg1" value="test" type="string"/>
</args>

<schedule>

Defines when the job is executed.

A cron format is used for specifying the time/period.

See below for details.

Yes

 
<schedule> <!-- @ 3 o clock -->
    <second>0</second>
    <minute>0</minute>
    <hour>3</hour>
</schedule>

<java>

Executes a Java class. See below for details

<java>com.acme.schedule.Job1</java>

<script>

Executes a script file. See below for details

<script>tvc:script/Test.js</script>

<mql>

Executes a MQL statement (or statements)

<mql>execute program abc</mql>

<jobcfg>

Executes a TIF job. Note that a TIF job typically requires an object as input, hence you need also some kind of "id provider" mechanism. See below for details

<jobcfg idProvider="tvc:dataset/ReleasedDocuments.xml">tvc:jobcfg/SomeJobConfig.xml</jobcfg>
One of java, script, mql or jobcfg is required.

1.3. Arguments (<args>)

The arguments section are used to pass in arguments to the job. The syntax below is used.

<args>
    <arg name="the name" value="the value" type="string | int | integer | long | real | double | bool | boolean | float"/>
    ...
</args>

1.4. Schedule (<schedule>)

The <schedule> element defines when the job should be executed. This element may have the following child elements.

<schedule>
    <second>..</second>
    <minute>..</minute>
    <hour>..</hour>
    <day-of-month>..</day-of-month>
    <month>..</month>
    <day-of-week>..</day-of-week>
    <year>..</year>
</schedule>

  • Support for specifying both a day-of-week and a day-of-month value is not supported.

  • If the second field is omitted, 0 is the default value.
Field Name Allowed Values Allowed Special Characters

second

0-59

,-*/

minute

0-59

,-*/

hour

0-23

,-*/

day-of-month

1-31

,-*?/LW

month

1-12 or JAN-DEC

,-*/

day-of-week

1-7 or SUN-SAT

,-*?/L#

year

1970-2099

,-*/

Special characters:

  • * ("all values") - used to select all values within a field.

  • ? ("no specific value") - useful when you need to specify something in one of the two fields in which the character is allowed, but not the other.

  • - Used to specify ranges. For example, "10-12" in the hour field means "the hours 10, 11 and 12".

  • , Used to specify additional values. For example, "MON,WED,FRI" in the day-of-week field means "the days Monday, Wednesday, and Friday".

  • / Used to specify increments. For example, "0/15" in the seconds field means "the seconds 0, 15, 30, and 45".

  • L ("last") - has different meaning in each of the two fields in which it is allowed.

    For example, the value "L" in the day-of-month field means "the last day of the month".

    If used in the day-of-week field by itself, it simply means "7" or "SAT".

    But if used in the day-of-week field after another value, it means "the last xxx day of the month" - for example "6L" means "the last friday of the month".

  • W ("weekday") - used to specify the weekday (Monday-Friday) nearest the given day.

    As an example, if you were to specify "15W" as the value for the day-of-month field, the meaning is: "the nearest weekday to the 15th of the month".

  • # used to specify "the nth" XXX day of the month. For example, the value of "6#3" in the day-of-week field means "the third Friday of the month" (day 6 = Friday and "#3" = the 3rd one in the month).

    Other examples: "2#1" = the first Monday of the month and "4#5" = the fifth Wednesday of the month.

  • The 'L' and 'W' characters can also be combined in the day-of-month field to yield 'LW', which translates to "last weekday of the month".

1.5. Java (<java>)

To execute a Java class, use the <java> element to specify your class to be executed.

This class must implement the interface com.technia.tif.enovia.scheduling.ScheduledJob, which is defined like this:

package com.technia.tif.enovia.scheduling;

public interface ScheduledJob {
    void execute(JobContext ctx) throws Exception;
}

The JobContext argument is defined like this:

package com.technia.tif.enovia.scheduling;

import java.util.Iterator;
import java.util.Map;

public interface JobContext {
    String getId();
    String getGroupId();
    Iterator<String> getParamNames();
    String[] getValues(String name);
    String getValue(String name);
    Integer getIntValue(String name);
    Double getDoubleValue(String name);
    Long getLongValue(String name);
    Boolean getBoolValue(String name);
    Map<String, String[]> toParamMap();
}

Custom classes are placed inside some JAR file within the ${TIF_HOME}/modules/enovia/lib/custom directory.

1.6. Script

You may instead of implementing a Java class implement the scheduled job in a script file.

Within the <script> element, point out the script file to be executed. For example:

<script>tvc:script:background/Job1.js</script>

This would refer to the file

${TIF_ROOT}/modules/enovia/cfg/background/script/Job1.js

The script must have a function like below:

function execute(jobCtx, objectIds) {
}

The last argument may be optional and might be null depending on if an "idProvider" attribute has been set on the script element.

Example with id provider:

<script idProvider="tvc:dataset:background/FindSomeObjects.xml">
      tvc:script:background/JobThatDoesSomethingWithObjectsInEnovia.js
</script>

In order to use the importClass and importPackage functions in the Javascript files, you need to include a compatibility script first in your script. This is done like this:

try{load("nashorn:mozilla_compat.js");}catch (e){}

Another alternative is to use the JavaImporter to import the required packages/classes. Please read the Java documentation related to the Nashorn Engine for a more detailed description.

1.6.1. Example: Scripted Job

To illustrate how the scripted capabilities could be used, lets look at an example.

The example below will execute a particular MQL command at some regular interval, and store the output of the command into a file in a certain directory.

The timetable.xml file contains the following definition:

<timetable>
	<group id="monitoring">
		<job id="eno-monitor-memory" displayName="ENOVIA:Monitor Memory">
			<schedule>
				<second>0</second>
				<minute>0/5</minute>
				<hour>0-23</hour>
			</schedule>
			<script>RunMQL.js</script>
			<args>
				<arg name="command" value="monitor memory" />
				<arg name="logDir" value="/var/log/enovia/memory" />
				<arg name="logFilePrefix" value="eno_memory_" />
			</args>
		</job>
	</group>
</timetable>
try{load("nashorn:mozilla_compat.js");}catch (e){}

importClass(com.technia.tvc.core.db.MQLUtils)
importClass(com.technia.tvc.core.db.DateUtils)
importClass(java.lang.System)
importClass(java.time.ZonedDateTime)
importClass(java.time.ZoneOffset)
importClass(java.time.format.DateTimeFormatter)
importClass(java.nio.file.Files)
importClass(java.nio.file.Paths)
importClass(java.nio.file.Path)

function execute(jobCtx, objectIds) {
	// get some input args...
	var command = jobCtx.getValue("command");
	if (command == null) {
		command = "monitor memory";
	}

	var logDir = jobCtx.getValue("logDir");
	if (logDir == null || logDir.length() == 0) {
		logDir = "C:/temp";
	}

	var prefix = jobCtx.getValue("logFilePrefix");
	if (prefix == null) {
		prefix = "mql_";
	}

	// run mql and save to file.
	var result = MQLUtils.mql(command);
	var ts = ZonedDateTime.now(ZoneOffset.UTC)
		.format(DateTimeFormatter.ofPattern("yyyyMMdd_HHmmss"));
	var file = Paths.get(logDir, prefix + "_" + ts + ".txt");
	Files.write(file, result.getBytes());
}

1.7. MQL

The <mql> element may be used if to execute MQL or MQL/TCL code in the ENOVIA/3DExperience database.

See below for configuration details:

<mql>
    execute program BackgroundJob;
</mql>

or

<mql idProvider="tvc:dataset:background/SomeDataSet.xml" tcl="true">
    mql delete bus ${OBJECTID}
</mql>

The attributes available on the <mql> element are:

idProvider

Points out an ID provider, for example a data set that returns the objects used as input.

Note the usage of the macro ${OBJECTID} in conjunction with the use of an idProvider. The MQL code is executed once for each object found by the "id provider" and the macro is replaced with the actual object-id value.

tcl

True if the code is MQL/TCL.

resolveMacro

True if to resolve any symbolic names prior to running the code.

1.8. Job Config

The <jobcfg> element may be used to launch an existing Job configuration.

See below for configuration details:

<jobcfg idProvider="tvc:dataset/MyDataSet.xml">
    tvc:jobcfg/SomeJobConfig.xml
</jobcfg>

The job defined by the configuration is executed once per object found by the "id provider".

1.9. Built-in Scheduled Jobs

1.10. Start / Stop Service Activator on Schedule

A service activator, such as a directory listener or a ENOVIA/3DExperience queue listener etc, can be started / stopped via a scheduled job.

Below is an example how to use this to start a directory listener at 4AM and stop it at 7AM.

<timetable>
    <group id="test">
		<job id="start-dir-listener-1" displayName="Start/Stop Dir Listener 1">
			<schedule>
				<second>0</second>
				<minute>0</minute>
				<hour>4</hour>
			</schedule>
			<java>com.technia.tif.enovia.scheduling.job.StartStopServiceActivator</java>
			<args>
				<arg name="match" value="DirectoryListener:*import_json.xml*" type="string"/>
				<arg name="mode" value="start" type="string" />
			</args>
		</job>

		<job id="start-dir-listener-1" displayName="Start/Stop Dir Listener 1">
			<schedule>
				<second>0</second>
				<minute>0</minute>
				<hour>7</hour>
			</schedule>
			<java>com.technia.tif.enovia.scheduling.job.StartStopServiceActivator</java>
			<args>
				<arg name="match" value="DirectoryListener:*import_json.xml*" type="string"/>
				<arg name="mode" value="stop" type="string" />
			</args>
		</job>
    </group>
</timetable>

The above could also be written like this:

<timetable>
    <group id="test">
		<job id="start-dir-listener-1" displayName="Start/Stop Dir Listener 1">
			<schedule>
				<second>0</second>
				<minute>0</minute>
				<hour>4/3</hour>
			</schedule>
			<java>com.technia.tif.enovia.scheduling.job.StartStopServiceActivator</java>
			<args>
				<arg name="match" value="DirectoryListener:*import_json.xml*" type="string"/>
				<arg name="mode" value="toggle" type="string" />
			</args>
		</job>
    </group>
</timetable>

The arguments this job accepts are:

match

The pattern string to match with the description of the service activator

mode

One of start, stop or toggle.