Protocol Business Agents

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.

Protocol Agents Result Document

<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>

AQ

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.

EMAIL

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.

File

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.

File Read

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.

FTP

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.

FTP Read

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.

HTTP GET

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.

HTTP POST

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.

Internal

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.

MQ Series

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.

Sonic

Class name: XDSonicEmitAgent

Parameter

Description

broker url

Used to reach the Sonic broker.

Other Sonic-specific parameters

Parameters to control the Sonic emit.

TIBCO RV

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.