Regular Work Items
Every regular work item has as a set of common properties. These common properties are not present for the synchronization work items or the token processor work items.
Every regular work item has a property called name. The name value should be a unique name in the workflow to identify a particular instance. This name is used by Workflow Manager when it reports the completed and in-progress work items inside a workflow. The name is also used by the workflow probe that collects statistics. White spaces are replaced by the underscore character (_).
Every regular work item also has two timeout properties, the Pause Timeout and the Processing Timeout. The Pause Timeout specifies the maximum amount of time allowed for a work item to pause. This property establishes a deadline for the work item to pause after receiving a Pause() message from the container workflow. If the work item fails to meet this deadline, an error is reported to the workflow engine, which will consider this work item to have reached a bad state and will cancel it. This will, in turn, provoke the cancellation of the whole workflow. Thus, this property must be set with care. Its minimum value is 15 seconds, which is usually enough for most of the cases; but certain work items, such as the HTTP work item, might need more when recovering from an error condition (for example, server unavailable).
The Processing Timeout property specifies the maximum amount of time allowed for the work item to complete before failing. This property establishes a deadline for the work item to complete. For example, a Receive E-mail work item may be configured to fail after a week waiting for a confirmation message from an operator. With the proper logic, this configuration allows an e-mail to be sent to the operator's supervisor, who will take care of the subject. The default value for this property is zero, which means no timeout. However, the work item can increase the timeout if it requires more time to finish. More details on how to perform the extension can be seen in Script Work Item.
Send E-Mail Work Item
This work item sends e-mails via an SMTP server. It has the ability to generate messages with token-dependent content. The content of the bodyText property is used to generate the content of the sent e-mail. Text in the form %tokenparameter% is replaced with actual values taken from the input token. The work item also embeds session information, which is necessary in case a reply e-mail is requested. The session information is distinguished from the free-form text by its prefix, a double pound sign (##) at the beginning of each line in the form <parameter name>=<value>, where <parameter name> is one of the values of the inputParameters property and <value> is its value obtained from the input token.
In the case of cancellation, a message can be sent to undo what was done as a consequence of the message. This message is sent to the same recipients of the original message and has the same other settings, except for the subject and the text, which are respectively specified by the UndoSubject and UndoBodyText properties.
To send an e-mail to a customer/user, specify the name of the recipient in the recipient property; for example; %ID%@ovelcom.net. This results in mail being sent to recipientname@ovelcom.net
The use of this work item is shown in the example in the next section. Its property sheet is shown in Figure 15.
The meaning of each property is described in Table 34.
Receive E-Mail Work Item
This work item will wait to receive e-mail through the E-mail Adapter. The E-mail Adapter is the part of the workflow engine responsible for receiving e-mail and sending events to the subscribing workflows and work items. It connects to a given host executing a POP3 or IMAP e-mail server and get messages from a specific account.
The routing of the e-mails from the adapter to the work item is based on the session information of the originating message. It is not possible to process a generic e-mail, only one that is a response to another sent by the SDX workflow application. Although a workflow ID exists, it is not embedded in the session information. This technique allows a workflow to act based on a response to an e-mail sent by another workflow, although this situation is not very common.
Matching a received e-mail to a workflow is based on the inputParameters property specified on the Send E-mail work item and the InputCriteria property of this work item. A match occurs only if all the parameters specified in the InputCriteria property are found in the message and have the expected value (the value of this parameter is obtained from the input token of this work item). If the property's host, bindDN, and bindPassword are not specified (default), the work item connects to the same directory that the workflow engine is connecting to and with the same credentials.
The property sheet is shown in Figure 16.
The OutputParameters is an indexed property that specifies which parameters are expected from the incoming message and put into the output token. Values must be provided for all OutputParameters; otherwise, the event will not be accepted and the work item will keep waiting for another e-mail.
Logger Work Items
These work items are just simple examples. Both simply expect that the properties Name and Address are defined in the input token and print a message on the console containing both data. The Logger work item performs this action immediately.
The Lazy Logger work item takes a while. We provide it to demonstrate how the pausing mechanism works. The amount of time it takes to do that can be configured by the expert properties of the bean:
- MinCalls—Minimum number of calls to the task method; every call takes one second of CPU time
- MaxCalls—Maximum number of calls to the task method
- TimeDelay—Delay in milliseconds to complete after the task is finished
The total number of calls made is randomly chosen to be between the limits specified above. This value is logged on the execution log. After the task is finished (all calls complete), the work item subscribes to a timer event to occur TimeDelay milliseconds in the future and prints the same message as the Logger work item, but to the execution log. Once the event arrives, the work item prints to the console the information about the event received and completes.
If the sleep threshold parameter of the workflow engine is configured to be less than the amount of time the work item takes to finish the task, the workflow engine will pause the workflow and send it to persistent storage. The same can happen after the work item subscribes to the event if it takes longer than the sleepthreshold to arrive. When the Timer Adapter dispatches the event to the workflow engine, the workflow is awakened and then finally completes.
This work item is ideal to test not only the persistence subsystem but also the Processing Timeout feature of the work item and the Execution Timeout feature of the workflow.
Directory Lookup Work Item
Given an objects DN, this work item retrieves the object from a directory, and copies the object's attributes to the output token. The attributes to be retrieved, as well as their corresponding names in the workflow domain, are specified by the translation table property.
The objectDN property specifies the DN of the object to be accessed. Its value can be taken from a token parameter, can be statically configured or a combination of the two. A string between '%' is considered a token parameter and will be replaced by its value. The '%%' sequence represents the '%' character. Each translation table entry is in the form <parameter name><W*>=<W*><ldap name>[|<default value>], where:
- <parameter name> is a string specifying the workflow parameter name.
- <ldap name> is a string specifying an attribute name of the directory object.
- <W*> represents a sequence of zero or more white spaces.
- <default value> is a string specifying a value to be assigned to the parameter if the object does not have the given attribute. <default value> can be the empty string. White spaces are significant.
This work item fails only if it cannot obtain a mandatory attribute (as specified in the translation table and not in the directory schema) or if fails to finish before the specified processing timeout expires. If the directory cannot be accessed after a specified number of retries, the work item will terminate.
The property sheet for the Directory Lookup work item is shown in Figure 17. Each property is described in Table 35.
Directory Update Work Item
Given the DN of an object, the Directory Update work item updates the object in a directory through LDAP, taking the values of its attributes from the input token. The attributes to be updated, as well as their corresponding names in the workflow domain, are specified by the translation table property.
The objectDN property specifies the DN of the object to be accessed. Its value can be taken from a token parameter, can be statically configured can be a combination of a token parameter and a static configuration. A string between '%' is considered a token parameter and will be replaced by its value. The '%%' sequence represents the '%' character.
Each translation table entry is in the form <parameter name><W*>
=<W*><ldap name>, where:
- <parameter name> is a string specifying the workflow parameter name.
- <ldap name> is a string specifying an attribute name of the directory object.
- <W*> represents a sequence of zero or more white spaces.
This work item fails only if, due to an LDAP error, the update fails or if it is specified a Processing Timeout and it takes longer than the deadline to complete. If the directory cannot be accessed after a specified number of retries, it will terminate.
The properties are the same as those for the Directory Lookup work item. However, the bindDN property must specify a user with write privileges. Also, the format of the translation table is slightly different, as specified above.
Directory Query Work Item
This work item performs an LDAP search in the directory and returns the result as an XML document. The XML document follows the DSMLv1 specification (http://www.dsml.org). The directory host must support LDAPv3. If the operation cannot be performed, the work item terminates. The resulting document is placed in a configurable token parameter.
You can specify static values or strings of token parameters for the search parameters. A string between '%' is considered a token parameter and will be replaced by the value of the token parameter. The '%%' sequence represents the '%' character.
By default, the work item connects to the same directory and uses the same connection settings as the workflow engine. If you want to connect to a different directory or use different connection settings, click the Show expert features button in the Directory Query Work Item property sheet (Figure 18), and specify values for all the expert properties.
Figure 18 shows the property sheet. Table 36 describes the properties for this work item.
Directory Modify Work Item
The Directory Modify Work item modifies the directory by using entries from an XML document. The XML document follows the DSMLv1 specification (www.dsml.org). If you want to use this work item, the directory server must support LDAPv3. The document comes from a token parameter, which you can configure.
The XML document contains a list of entries that the work item will add to or delete from the directory. When the work item deletes entries, it matches the DNs of entries in the XML document with corresponding entries in the directory, and removes those entries from the directory. The work item ignores attributes for deletion purposes.
However, when the work item adds entries, it matches all attributes in the XML document with those in the directory, removes any information from the directory that is not listed in the XML document, and overwrites existing entries in the directory. This overwriting means that in the XML document, you must:
- Specify only entries that you want to appear in the directory.
- Specify all mandatory attributes for those entries.
- Check that the names of the entries match the names of the entries in the directory.
By default, the work item connects to the same directory and uses the same connection settings as the workflow engine. If you want to connect to a different directory or use different connection settings, click the Show expert features button in the Directory Modify Work Item property sheet (Figure 19), and specify values for all the expert properties.
Figure 19 shows the property sheet. Table 37 lists the properties for this work item.
External Program Work Item
This work item generates an external program and waits for its completion. It works together with the Process Adapter (see the Chapter 5, Configuring the Workflow Application, for information about configuring this event adapter). The program to be started is specified by a command line through the commandLine property. The command line can be constructed statically or dynamically with token parameters specified between percents ('%').
The work item terminates only if the external program cannot be started or is abnormally interrupted without returning a value to the operating system (process death).
If the work item terminates, you can specify an undo external program operation through the undoCommandLine property.
The workflow engine communicates with the external process as follows:
- The input token is passed to the external process through its environment. Each token attribute corresponds to an environment variable with the same name prefixed with "TOKEN_". For multivalued properties, a suffix "_N" (N > 1) is added to each additional value. The names are case sensitive.
- The return value of the process determines the success or failure of the work item. If it is zero, it is successful. Any other value indicates failure of some kind.
- The standard output of the external process can be used to communicate the output token to the workflow engine. It is optional and is specified during design time by the appropriate work item property.
The token is passed back through the standard output if the property GenerateOutToken is set to true. If the TokenNeeded property is false, the GenerateOutToken property will automatically be set to false, because the work item cannot create the output token if it does not receive the input token. The output token is passed as a string in the following format as a regular expression:
<name>=<value>('|'<name>=<value>)*, where
- <name> is the token property name and <value> is its value.
- <name> is in the format: ([a-zA-Z0-9_])+.
- <value> can be any string not containing the '|'.
- '|' is the separator.
If a <name> instance is present more than once in the output, <name> is interpreted as a multivalued property.
The property sheet for the work item is shown in Figure 20, and the property descriptions are given in Table 38.
HTTP Work Item
The HTTP work item performs an HTTP or HTTPS request. The specified URL can be static or dynamically composed with token parameters. Token parameters are specified between percents ('%') and are replaced by their values in run time. The '%%' sequence represents the '%' character.
The request type can be Get or Post. Data to be uploaded, in the case of a Post, comes from a token parameter. The returned data is put in the output token as a parameter so it can be used by others. This work item in its current version can manipulate only text data.
The default behavior is simply to forward the input token with the proper result of the request, if it was successful or not, for example, an HTTP error was returned instead. If the resource cannot be found, it also fails. If the socket cannot be created or any other network specific error occurs, it is cancelled.
The property sheet for the work item is shown in Figure 21, and descriptions are given in Table 39.
Script Work Item
The Script work item embeds scripts written in Python. Scripts can be both directly entered or referenced through a filename.
The scripts interact directly with the workflow framework. Three scripts can be specified, each serving a different purpose: the task, the event, and the undo scripts.
The task script is executed first. For the task script to interact with the workflow framework, it must not take longer than the value specified for Pause Timeout to return. If the processing is long, it can be divided into several steps, each of which is performed in different executions. After the whole processing is complete, which is communicated to the workflow framework by the script, the event script is eligible to be executed.
The event script is executed on receipt of an event. For a work item to receive events, it must subscribe to them. This is done through the register() operation of the work item. A work item can subscribe to as many events as necessary. The subscription can be performed in the task script or the event script; but for the event script to be executed for the first time, at least one subscription must be done in the task script.
The sources of the events are the event adapters. Each event adapter produces events of a particular type. For example, the Timer Adapter produces Timer Events. To make the SDX Workflow application an open tool, the workflow engine can plug in different event adapters, so the application can be customized to interface with a variety of systems. For a work item to register to a specific kind of event it must create an event criterion, which is passed as an argument to the register() method. According to its type, the criterion is delivered to the proper adapter. Every time an event is produced, it is addressed to all work items that registered matching criteria. Once a work item receives an event that satisfies the criterion it provided when the item registered itself for an event, it must explicitly consume it, so it will not receive other events with to that same criterion. If the received event is not the expected one, it can simply be ignored. In the same fashion as the task processing, the event script must communicate to the workflow framework that it has completed its processing.
After the completion of the event script, the work item completes. If the work item cancels itself or if its container is cancelled, the undo script is executed. Unlike the other two scripts, the undo script is executed in one pass. Because the cancellation is an abnormal occurrence due to an unexpected condition, the undo script should not take long to perform its task. Thus it minimizes the external resources it allocates.
The task script must be specified. The event and undo scripts are optional. The scripts have access to the following objects, which can be used to communicate with the workflow framework:
- inputToken—Input token, such as a dictionary mapping names to lists of strings
- outputToken—Output token
- deadline—Long value containing the deadline for this work item to be completed before failing due to a Processing Timeout, in milliseconds from 01/01/1970 UTC. Changing this value also changes the deadline. The deadline can only be extended, never reduced. Zero means no deadline; any changes will have no effect. Changing this value to zero cancels the deadline. The deadline is set for the first time when the work item starts; the Processing Timeout is added to the work item.
- result—Integer specifying the result of the work item: 0 = failure, non-zero = success. It must be set before the work item's completion.
- complete—Integer specifying if the processing (task or event) is complete: 0 = false, non-zero = true
- event—Event descriptor that caused the event script to be executed (available only for event and undo scripts)
- this—Reference to the WorkItem object, to provide access to the native work item functionality; namely, the register() and consume() methods
The property sheet of the work item is shown in Figure 22, and its description is in Table 40.
Script or full pathname that is executed in response to an event |
|
Maximum time that the work item can take to complete the process |
|
Status Logger Work Item
This work item logs a free-form message in the workflowStatus attribute of a transactional object. The string to be logged will be appended to the current content together with a new line character that serves as a separator.
The objectDN property specifies the DN of the object to be updated. Its value can be taken from a token parameter, can be statically configured, or can be a combination of a token parameter and a static configuration. A string between '%' is considered a token parameter and will be replaced by its value. The '%%' sequence represents the '%' character. The logEntry property specifies what to log. Its value can be taken from a token parameter, can be statically configured, or a combination. The property eraseOnCancellation determines whether the log entry should be removed in case of cancellation.
The property sheet is shown in Figure 23, and the properties are described in Table 41.
XML Decoder Work Item
This work item interprets an XML document and puts the information in the output token. The document is retrieved from the input token and then processed. The parameter from which the document is taken can be configured.
The interpretation of the XML document is done in two steps:
- Translating it to an XML Workflow token document using user-provided rules in XSLT
- Extracting the token parameters from this simpler document and putting them into the output token
After the interpretation, all the data is stored in the output token.
The XSL rules document can be specified through a file or entered directly. As an option, instead of fully translating the document to a token, an XML document can be created and embedded as a token parameter. This happens only if the OutputParameterName property is specified.
This work item never fails. If a parsing or translation error occurs, the work item will terminate.
The document type definition (DTD) of the Workflow Token document is given in the screen display below. The generated document should have a DOCTYPE tag referencing this DTD so that a proper validation is performed before the output token is created.
<!ELEMENT token (attribute)*>
<!ELEMENT parameter (value)+>
<!ELEMENT value (#PCDATA)>
<!ATTLIST parameter name CDATA #REQUIRED>
The screen sample below is an example of a valid Workflow Token document.
<?xml version='1.0'?>
<!DOCTYPE token SYSTEM "lib/WorkflowToken.dtd">
<token>
<parameter name="Name">
<value>Test User</value>
</parameter>
<parameter name="Address">
<value>667 Elm St.</value>
</parameter>
</token>
The property sheet for the work item is shown in Figure 24 and the properties description in Table 42.
XML Encoder Work Item
This work item is responsible for creating an XML document and placing it in the output token. The document is generated by substituting special tags in a template XML document by parameters from the incoming token. The template document can be specified through a filename or directly entered. If a DTD is provided, the document can be validated. The parameter to which the document will be written can also be configured.
To specify token parameters inside the template document, enclose them in percents ('%'). To represent the percent character use '%%' instead.
This work item cannot fail. It terminates if the produced document is not valid, any other properties are not properly set, or a specified token parameter is not present in the input token.
The property sheet of the work item is shown in Figure 25 and the properties description in Table 43.
