MD Link Jython code interacts with the MD Link engine through an object called engine. Below are the fields and functions available on that object from within a Custom Task. To call any of these from your script, you must preceed the name of the field or function with a reference to engine - for example:
print engine.solnId
or:my_id = 'key_'+engine.transId
An engine object will be available to Jython scripts in all of a Custom Task's scripts - 'Load', 'Run', and 'Unload'. However, some of the fields and functions described below are only available from within certain scripts - for example from the 'Run' script, but not the 'Load' or 'Unload' scripts. For each field or function which has such limited availability, this is documented below. If an attempt is made by your Jython code to access a field or function that is not available in the current context, then an exception will be raised. This exception will by default appear in the logs, and will interrupt the control flow of your script. The exception will contain an error message noting the cause.
Read-only property. This is the version of MD Link that is currently running (major and minor version numbers only) encoded as an integer such that, for example:
4.3.14.2 becomes 4030000
5.12.5 becomes 5120000
Read-only property. This is the ID of the enclosing task - for example, T20.
logdebug (type: python file-like object)
Read-only property. This is a Jython output file stream that is redirected to MD Link's debug-level logs. You can use it as part of a print statement like this:
print >> engine.logdebug, 'Some debug info.'
loginfo (type: python file-like object)
Read-only property. This is a Jython output file stream that is redirected to MD Link's info-level logs. You can use it as part of a print statement like this:
print >> engine.loginfo, 'Some info-level info.'
A simple print statement like this:
print 'Some info-level info'
will accomplish the same thing. This field is just provided for convenience in some programming scenarios.
logwarn (type: python file-like object)
Read-only property. This is a Jython output file stream that is redirected to MD Link's warning-level logs. You can use it as part of a print statement like this:
print >> engine.logwarn, 'Some warning info.'
logerror (type: python file-like object)
Read-only property. This is a Jython output file stream that is redirected to MD Link's error-level logs. You can use it as part of a print statement like this:
print >> engine.logerror, 'Some error info.'
inputDom (type: Java DOM object - i.e. org.w3c.dom.Document)
Available from the 'Run' script only. This is the input message to the current task execution (post data-mapping). It is a DOM (Document Object Model) document object, so familiarity with that API is necessary to work with it. Please see the documentation for the Java DOM implementation.
The document tree provided by this field is not read-only. Your script may modify it as you wish. This may be useful if for example you are copying the input document to the output document with little or not modifications.
outputDom (type: Java DOM object - i.e. org.w3c.dom.Document)
Available from the 'Run' script only. This is the output message of the current task execution. This is a DOM object, like inputDom. Unlike inputDom, the value of this field will be None by default; it is the responsibility of the Custom Task implementer to create a useful document object and point this field at that document. One way to do that is:
engine.outputDom = util.makeXMLDocument('TaskData')
Or if the input and output schemas of this task are compatible, one can also do this:
engine.outputDom = engine.inputDom
Only a single message per task execution can be output with this field. For certain business logic, you may want to output multiple messages from one task execution. To do that, use outputDoms instead.
outputDoms (type: a Java vector (java.util.Vector) containing DOM documents (org.w3c.dom.Document))
Available from the 'Run' script only. Use this field if you want to output more than one message from the current task execution. (Unlike outputDom, which is used to output a single message. Only one of the two fields can be used at a time; otherwise the engine will raise an error.) This field is a Java Vector, and contains no elements by default. Use it like this:
# First, create a local variable containing the first of many output message DOM documents:
dom1 = util.makeXMLDocument('TaskData')
# Then build that output message in a useful way:
util.appendText(dom1, 'payload 1')
# ... add any other document-building steps that are desired ...
# Then add the local dom1 variable to the engine's output message list:
engine.outputDoms.add(dom1)
# Then create a second output message:
dom2 = util.makeXMLDocument('TaskData')
util.appendText(dom2, 'payload 2')
# and add the second local dom variable to the engine's output message list:
engine.outputDoms.add(dom2)
# Repeat this process as many times as desired.
# Of course this is usually done within a loop of some kind.
Read-only property. This is the ID of the solution of which this task is a part, as assigned by the engine. eg. SOLN3.
solutionFilename (type: string)
Read-only property. This is the absolute filename of the solution file of which this task is a part.
Read-only property. Available from the 'Run' script only. This is the ID of the current transaction, as assigned by the engine. eg. TRANS99. Generally, every firing of an event will create a new transaction ID, and all task executions caused (directly or indirectly) by that firing will have the same transaction ID.
Read-only property. Available from the 'Run' script only. This is the ID of the current task execution, as assigned by the engine. eg. QELEMID-TRANS7-E2-T3-1-T4-9-T6. This ID will be unique under each solution ID for each task execution, so it is useful for implementers that require such a unique key.
Read-only property. Available from the 'Run' script only. This is True during the first execution of this script since this solution was loaded, and False during all subsequent executions.
Available from the 'Run' script only. This causes no message to be passed to any downstream tasks as a result of the current task execution. The current task execution will cease immediately. Control will not return to the calling Jython code. Info message will be logged.
message - optional. This message string will show up in the log message that results from this call.
An error message will be logged. Control will not return to the calling Jython code.
If this is called from the 'Load' script, then the solution will refuse to load. If it is called from the 'Run' script, then the current task execution will fail. If it is called from the 'Unload' script, nothing will happen except for the error message logged.
message - optional. This message string will show up in the log message that results from this call.
void failAndRetry(string message)
Available from the 'Run' script only. Will cause the current task execution to fail immediately, and attempt retries if the task is so configured. Control will not return to the calling Jython code.
message - optional. This message string will show up in the log message associated with the task failure caused by this call.
void failAndDontRetry(string message)
Available from the 'Run' script only. Will cause the current task execution to fail immediately, and not retry. Control will not return to the calling Jython code.
message - optional. This message string will show up in the log message associated with the task failure caused by this call.
This method causes the Jython script to exit immediately. If this is called from the 'Run' script, then the current task execution will still succeed from the engine's perspective.
void retry(int numMilliseconds)
Available from the 'Run' script only. Will cause the current task execution to request an execution retry from the engine. Will retry regardless of any other retry settings the task may have. Control will not return to the calling Jython code. This task will be executed again from the beginning after the specified number of milliseconds.
void retry(int maxNumRetries, int numMilliseconds)
Available from the 'Run' script only. Will cause the current task execution to request an execution retry from the engine. Will retry regardless of any other retry settings the task may have. Control will not return to the calling Jython code. This task will be executed again from the beginning after the specified number of milliseconds, and to the specified maximum number of retries, after which the execution will be considered failed.
string getVarVal(string variablename)
Gets the value of a variable. This could be a solution or global variable. If there are both solution and global variables defined with the name supplied, then the value of the solution variable will be returned.
Do not include $ or ${} to reference the variable name, as you would when referencing variables in elsewhere in the product.
If the given variable name does not exist, an exception will be raised.
Example:
engine.getVarVal('sender')
might return "LAB".
Given a string containing references to variables, this function substitutes the variable names with their values. Each variable name can be either a solution or global variable. If there are both solution and global variables defined with the name supplied, then the value of the solution variable will be returned.
Unlike getVarVal(), for this function you will need to include $ or ${} to reference the variable names, as you would when referencing variables in elsewhere in the product.
Also unlike getVarVal(), if the given variable name does not exist, then the original variable reference will appear in the return value unmodified. No exception will be raised by this case.
Example:
engine.subVarVals('sender: ${sender}, receiver: ${receiver}')
might return "sender: LAB, receiver: DATABASE"