Topics: |
Protocol business agents are standard business agents that can emit a document to a designated target or can read from a source. In the standard situation for output, a <replyto> should be used, however for some circumstances, a protocol business agent can be employed. In all cases, if an emitter can be used it should be used in preference to a protocol business agent.
Each protocol business agent takes initialization parameters appropriate to the protocol type.
<emitstatus> <protocol>name</protocol> <status>status code</status> <parms>stringOfParms</parms> <native>nativeSystemErrorCode</native> <text>error descriptive text</text> <name>nameOfCreatedFile</name> <channel>name of the channel</channel> <nodename>name of the pflow node</nodename> <retries>numberOfRetries</retries> <timestamp>timeOfCompletion</timestamp> </emitstatus>
The document is posted using Oracle AQ.
Class name: XDAQEmitAgent
Parameter |
Description |
---|---|
host |
Network name of the machine where the target system resides. |
password |
Password of this user. |
port |
Service port that Oracle uses to exchange messages. |
qtable |
Database table used to manage queues. |
queue |
Queue to receive documents. |
sid |
Name of Oracle database service. |
user |
User name of access to the target system. |
The result of the post appears in the <native> section of the <emitstatus> result.
The EMAIL emit sends the document to a designated recipient. The document always goes to the recipient specified in the parameters.
Class name: XDEmailEmitAgent
Parameter |
Description |
---|---|
from |
Author. |
host |
Email host. |
subject |
Subject of this message. |
to |
Intended recipient as an email address. |
The File Emit writes the contents of the current document or other specified information to the file system. The source specification can be blank or can specify any iWay expression, including xpath(). If the document is XML and xpath() is specified, each value meeting the xpath() criteria is written as a file; the assigned names are allocated sequentially based on the entered pattern.
Class name: XDFileEmitAgent
Parameter |
Description |
|
---|---|---|
directory |
Directory to which the file is to be written. |
|
pattern |
File name pattern. In the pattern, a * character is replaced by the current timestamp. So T*.out might become T2002-06-25_12:02:24:43.out. A # is considered a unique number. The number of # characters controls the length. |
|
Run Preemitter |
If a preemitter exists on this route for output, this allows it to be bypassed for this emit operation. Perform this action to enable the output file to include non-processed (raw) information. |
|
Return |
Specifies the desired output of this service: |
|
status |
Status document which contains the name for each file written by this service. |
|
input |
Input document as received. |
|
swap |
Swap the input document, but any information written as a result of an xpath() from the document is replaced with the file name to which it was written. |
|
Source |
Source of the data will be written to the file. If this is omitted, the input document is written to the file. If this contains an xpath() expression, for example, xpath(/root/x/value), each located value in the input document is written to a file. This parameter can contain any value, including a constant. For example, specifying file(/x/y.txt) will result in the contents of the named file being written. |
Output Edges | |
---|---|
success |
Standard success edge. |
fail_parse |
Could not parse the xpath expression of other entered function. |
fail_operation |
File write failure occurred. |
notfound |
No information meeting the source criteria was located. |
The local file input accepts a request to read a file from the local file system and outputs this request as an XDTextDocument. The transform business agent and standard output can accept and operate upon this output. The input business agent can operate on flat or XML data, and can emit data in either form.
Class name: XDFileReadAgent
Parameter |
Description |
---|---|
basepath |
Optional directory path to be tried if the passed in name is not absolute. |
encode |
Encoding to be performed on the input. Can be "asis" or "base64". If omitted, no encoding is performed. |
entag |
Optional tag to be set around the input. If omitted or empty, no tag is used. |
format |
Format of the input document. Optional. Can be "flat" or "xml". Default is flat. |
tagname |
Tag of input document whose value is the file name to read. |
The input document must be:
<filename>pathToFile</filename>
assuming that the tagname is set to filename.
If the input format is XML or an entag parameter is used, the output is in XML form. Otherwise, the output is a flat document.
Note: The XDFileReadAgent assumes that the input data format is flat by default, or if the entag option is set to any value even if the XML input data format is selected.
Class name: XDFTPEmitAgent
Parameter |
Description |
---|---|
directory |
Directory on the host system to receive the output. |
duration |
Time to wait (in seconds) before retrying if the FTP system cannot be reached. |
host |
Host system of FTP target. |
maxretries |
Maximum number of time to retry. 0 is the default value. |
password |
Password on the host system. |
pattern |
File name pattern. In the pattern, a * character is replaced by the current timestamp. So T*.out might become T2002-06-25_12:02:24:43.out. |
port |
Integer port number. 21 is the default value. |
user |
User ID on the host system. |
Reads one file through FTP. The service provides many options. The key options are shown in the following table.
Class name: XDFTPReadAgent
Parameter |
Description |
---|---|
hostname |
Name of the FTP host. |
username |
Name of the user to log into the FTP server. |
password |
Password for the user to log into the FTP server. |
tagname |
Name of the tag from the input document that identifies the file name to be read. |
enclosetag |
Tag used to enclose the data read. |
basepath |
Option name of path to use if tagname is not absolute. |
format |
Indicates if data is XML or flat. |
delete |
Indicates if the data should be deleted after the read. |
The GET facility input accepts a URL in the incoming document and issues an HTTP GET through that URL. The transform business agent and standard output can accept and operate upon this output. It is presumed that some output is returned, otherwise an error is raised.
Class name: XDHTTPReadAgent
Parameter |
Description |
---|---|
tagname |
Tag of input document whose value is the URL. |
The input document might be:
<?xml version="1.0"?> <inurl>http://localhost:1234/xmlone.xml</inurl>
assuming that the tagname is set to inurl.
In addition to the URL parameter, any other parameter denoted by <parm>s are treated as GET parms, with the values specified in the parm value. For example:
<agent>emitHttp <parm name='url' required='y'/> <parm name='header1' required='y'/ prompt='first header'> <parm name='header2' required='y'/ prompt='second header'> </agent>
GET parms with no value are ignored. GET parms with values of x=y format are changed such that the x is the name and the y is the value. Thus a deploy user can "fill in the blanks."
The returned information is passed on as the output document. If it begins with a <, it is considered XML; otherwise, a flat document is returned.
The document is posted using HTTP to a designated server.
Class name: XDHTTPEmitAgent
Parameter |
Description |
---|---|
returnresponse |
An enumeration of 'RESPONSE' or 'STATUS'. This parameter is optional, and the default is 'RESPONSE'. |
url |
URL for this post. |
In addition to the URL parameter, any other <parm>s are treated as headers, with the values specified in the parm value. For example:
<agent>emitHttp <parm name='url' required='y'/> <parm name='header1' required='y'/ prompt='first header'> <parm name='header2' required='y'/ prompt='second header'> </agent>
Header parms with no value are ignored. Header parms with values of x=y format are changed such that the x is the name and the y is the value. Thus a user can "fill in the blanks."
The result of the post appears in the <native> section of the <emitstatus> result.
If the returnresponse parameter is STATUS, the status message is always generated. If it is RESPONSE (the default) the actual information returned from the POST is emitted, except in the cases of an error in which case the status information is emitted. The POST is considered successful if the POST can reach its destination and a 200 status is received.
A successful returnresponse is considered to be XML if the first character is a <. Otherwise, a flat document is created.
Class name: XDInternalEmitAgent
The server offers an internal queue facility to which messages can be posted. An Internal Channel can be configured to read from the queue and behave in all other ways like a standard channel. This means one channel can pass work off to another channel, which can have preparsers, splitters, process flows and emitters, and is in no way distinguishable from any other channel.
The emitter specifies whether the channel operation is to be asynchronous (default) or synchronous.
As an asynchronous emit, the emitter immediately proceeds to the next node. This is a "fire and forget" emit operation and no result is returned.
In synchronous mode, the emitter waits for the internal channel operation to complete and returns the result of its default reply to the caller. Naturally, a timeout or cancel can affect this wait.
The edges returned are:
success |
The operation completed successfully. |
fail_notfound |
The named queue was not found. The internal channel had not been started to register the queue, or the queue name is mis-specified. |
cancel |
The emitter was awaiting the synchronous result when a cancel was received. |
timeout |
The emitter was awaiting the synchronous result and timed out. |
Class name: XDMQEmitAgent
Parameter |
Description |
---|---|
correlid |
Correlation ID. |
queuemanager |
Queue Manager name. |
queuename |
Queue name. |
The message ID appears in the <name> element of the <emitstatus> result.
Class name: XDSonicEmitAgent
Parameter |
Description |
---|---|
broker url |
Used to reach the Sonic broker. |
Other Sonic-specific parameters |
Parameters to control the Sonic emit. |
Class name: XDTIBRVEmitAgent
Parameter |
Description |
---|---|
subject |
Subject for the emitted message. |
daemon |
Access daemon. |
network |
Network name. |
Other TIBRV-specific parameters |
Parameters to control the TIBRV emit. |