Business Agents

Topics:

Provided standard business agents facilitate the development of business activities. When used alone, many of these business agents alone are sufficient to provide a complete business service. They can also be used in stacks and process flows as components of business processing.

Alternate Routing

Class name: XDIsReachable

Tests whether a specific IP target is reachable. If the target can be reached, the agent returns success. This agent is useful for supporting alternate routes such that a message can be directed to a primary or a backup host.

The edges returned are:

success

The host is reachable.

fail_connect

The host is not reachable.

fail_partner

The host is not known. For example, the host is not identifiable in the DNS.

Base64 Services

Class name: XDBase64Agent

This agent encodes or decodes a portion of the document. It is possible to store non-unicode bytes into an internal document even though under XML rules such a document cannot be serialized or deserialized (parsed). This agent enables base64 fields to be replaced with bytes, and such bytes to be represented in base64.

The edges returned are:

success

Successful conversion.

fail_parse

The input could not be converted.

Call Adapter

Class name: XDAdapterAgent

This agent calls an iWay adapter. To use this agent, the adapter must have been configured in an iWay Explorer program.

The edges returned are:

success

Successful operation of the adapter.

fail_operation

The adapter failed and did not report the direct cause.

fail_security

The adapter has returned a security violation.

fail_partner

The adapter reports that it cannot reach the needed system or that system has returned an error.

cancelled

The operation has been cancelled due to a timeout or other cause.

Check Schema

Class name: XDCheckSchema

Evaluates the input document against a specified schema. Optionally this agent can route the document to the fail edge or can simply set the appropriate document state that can later be tested with the iFL statement _hasschemaerror().

The edges returned are:

success

Successful.

fail_parse

The schema could not be parsed or the document fails the schema check.

fail_missingschema

The schema could not be found.

fail_format

The input document was inappropriate for the test (e.g. the input was not XML).

Control

Class name: XDControlAgent

This agent enables or disables a listener. Configuration takes the name of the listener, and the operation to be performed. Operations supported are:

Operation

Description

start

Named listener is started, if necessary. It is enabled for acquiring messages.

passivate

Named listener is disabled for acquiring messages. This may not take effect immediately. The listener remains active and no resources are released.

pulse

Named listener is started/enabled to acquire messages. It runs through one acquisition cycle (for example, reading all rows in a RDBMS table) and is then stopped.

Pulse is not guaranteed to work for all listeners. iWay recommends that this message be used only with extreme caution.

stop

Named listener is stopped. All resources are released.

Using the control agent, the activity on one listener can control another. For example, the detection of a message in an MQ Series queue can trigger an RDBMS listener to begin working with a relational table.

Control Character Filter

Class name: CCharFilter

Some input documents contain control characters such as tabs or bells. This agent replaces or removes such characters.

The edges returned are:

success

Successful conversion.

Copy

Class name: XDCopyAgent

This agent duplicates the existing document. It allows a comment to be emitted and a delay to be configured. Unless the delay or comment is needed, iWay recommends the use of the Move service instead.

Deflate/Compress Document

Class name: XDDeflateAgent

This agent compresses the document for transmission or storage. The document is flattened to a byte stream, and compression algorithms are applied. The output of this agent is a flat document.

The user can select the algorithm to be used.

none

No compression is used.

smallest

The smallest possible output is desired, regardless of the execution times.

fastest

The fastest execution time is desired, even if the degree of compression is reduced.

standard

A compromise between smallest and fastest.

Huffman

An entropic encoding is applied.

The edges returned are:

success

Successful deflation.

fail_operation

Deflation could not be performed.

Emit at EOS

Class name: XDEmitEOSAgent

This agent retains the previous document that was passed through the agent, and emits it as EOS (End of Stream). This allows the document to be sent to emitters only in the EOS state.

The edges returned are:

success

Successful.

Entag a Flat Document

Class name: XDEntagAgent

This agent adds an element tag around a flat document, and optionally, base64 encodes the document. If the input document is not flat, this agent is ignored.

The edges returned are:

success

Successful.

EvalWalk (Evaluate Input)

Class name: EvalWalk

Implements the iWay Active Document within an agent.

The exit evaluates each attribute and entity value in the document, executing all iWay functions. For example, a node:

<node1/ATR1="_ISERROR()">SREG(ip)</node1> 

might become:

<node1/ATR1="false">123.45.678.910</node1>

Fail

Class name: XDFailAgent

The failure business agent always returns an XDException. If the parameter RETRY is used, the exception calls for a retry of the input, if possible. This business agent is useful when debugging rollback logic in a customer business agent.

FFSField

Class name: XDColAgent

This business agent generates an output <eda> <response> document based upon the incoming document. It also uses the properties file as described under FFSRow. The <response> document contains divided rows, with each metadata column (name, type) described in each row. This format is similar to that of many other database systems. It is a convenient exit for transformations.

FFSHotScreen

Class name: XDHotScreenAgent

The hotscreen business agent does not format its responses into an XML file. Rather, it accepts for relay any output generated by the iWay Full Function Server. This can include reports, server-produced XML files, or HTML tables.

FFSRow

Class name: XDStdAgent

This business agent accesses the iWay Full Function Server, and generates a response document that confirms to the eda dtd <response>. The business agent locates the appropriate iWay Data Server by using the server property file. For a TCP server named myserv, the statements might look like:

Jlink.myserv.protocol = tcp
Jlink.myserv.host = somehost
Jlink.myserv.service = 1234

The form of the property file is a sequence of lines in the form

<name>.<token>=value

where the name parameter is the business agent name. For the iWay business agents, the name is jlink.<server>.

Get Channel Information

Class name: XDChanInfoAgent

Information about the current state of the system can be obtained in XML form. Each channel (called a master) is included in the XML output, along with statistics on its current state.

<info>
   <channels>
      <master name="internal" state=" active " type="Internal" completed="0"
           failed="0" active="0" available="1">
         <user mean="0.0" variance="0.0" ehrlang="1.0"/>
         <cpu mean="0.0" variance="0.0" ehrlang="1.0"/>
         <threads group="internal">
            <thread name="W.internal.1"/>
         </threads>
      </master>
      <master name="file1" state=" active " type="FILE" completed="0"
           failed="0" active="0" available="4">
         <user mean="0.0" variance="0.0" ehrlang="1.0"/>
         <cpu mean="0.0" variance="0.0" ehrlang="1.0"/>
         <threads group="file1">
            <thread name="W.file1.1"/>
            <thread name="W.file1.2"/>
            <thread name="W.file1.3"/>
            <thread name="W.file1.4"/>
         </threads>
      </master>
   </channels>
   <internalqs>
      <queue name="internal1" size="0"/>
   </internalqs>
</info>

The edges returned are:

success

Successful extraction.

Inflate/Decompress Document

Class name: XDInflateAgent

The document contains a deflated message which is to be inflated, making the document usable. If the document is intended to be XML, it is parsed.

The edges returned are:

success

Successful completion.

fail_operation

The input data is not deflated in a form that is understood by the inflater.

fail_parse

Following successful inflation, the document could not be parsed into XML. the configuration must specify that the output is to be XML.

Jdbc

Class name: XDJdbcAgent

The JDBC business agent uses industry-standard JDBC to generate the standard <eda> <response> result. Because JDBC standards limit the available database operations that can be performed, the business agent is correspondingly limited. For example, this business agent cannot process the <focus> tag of the input document.

The business agent can, however, avail itself of any configured JDBC driver. This includes the iWay SAP, IMS, and transaction server drivers as well as drivers from third-party providers.

LocalMaster

Class name: LocalMasterAgent

Passes the document to a separate, named workflow and awaits the result. The agent accepts the name of a configured LOCAL protocol which can be configured in any manner desired. The routes are pooled for efficiency.

Unlike using an Internal Emitter to route a document to the Internal protocol, this call is synchronous. Any errors reported by the named workflow are reflected in the calling flow, and any timeout configured for the flow includes time in the called flow.

LocalMasterAgent differs from simply calling an external process flow in the normal manner in that a complete workflow is available including preparsers, reviewers, and so on.

It is strongly recommended that this agent not be used unless no other means is available to accomplish the application purposes.

Log Event

Class name: XDXALogEvent

The transaction activity log records events during the life of the server. Events include start and stop of the channel, each operation within the channel, and errors. User events can be added to the log using this agent.

If no activity log driver is operational, this agent is a functional NOP.

The only edge returned is:

success

Successful completion.

Manage Attachments

Class name: XDAttachOps

Performs supported operation on a document. This service can delete all attachments or a single attachment.

Manipulate Register Namespace

Class name: XDSREGNamespaceAgent

Registers can be set into namespaces. The namespace is the first portion of the register name, for example, request.mimetype. The mimetype special register is considered to be in the request namespace. The namespace is simply the first token of a multi-token register name.

Among the operations that can be performed by this service are to copy, rename or delete a namespace or test for the existence of any registers in a namespace.

Move

Class name: XDMoveAgent

Moves the input to the output without duplicating the information. This is the fastest means of copying from input to output.

Parse to XML

Class name: XDToXML

Parses a flat document into an XML document. If the input is already XML, this service performs no action.

This service is useful if a flat (non-XML) input has been received and must be changed into XML for subsequent operations.

Two possible returns are supported:

  • success indicates successful parsing, in which case the output document consists of the newly parsed material.

    or

  • fail_parse, in which the case output is the original input.

Parsing

Class name: XDToXML

Parses a flat document into an XML document.

The edges returned are:

success

Successful deflation.

fail_parse

The agent was unable to parse the input document.

QA

Class name: XDQAAgent

Emits a flattened copy of the input document to a file named in the init() parameters. The business agent outputs the document (XML or flat) either in QA mode or always, depending upon the setting of a parameter. If the QA mode is not on (set in the Diagnostic System Properties Console Configuration Page) and the always parameter is not set, this business agent acts as a move business agent. This business agent is designed to work as a chained business agent during debugging. The document and all special registers are included in the output.

Registers

Class name: XDSREGAgent

Sets or deletes one or more special registers under program control. The registers can be set to any of the supported scopes (message, flow, or thread) and can be of any defined category (hdr [header], user, or doc). Normally, registers cannot be set above the Message scope. The value to be assigned to any register can be an iFL expression which is evaluated when the service is executed.

The order of register assignment is undefined. You cannot, for example, assume that the following two assignments:

first

10

second

sreg (first) +1

will be executed such that first is assigned before second. The results of such a setting strategy is unpredictable. If such a setting is required, you must use two copies of the register agent.

Run a Shell Command

Class name: XDRunCmdAgent

The agent accepts a shell command such as "copy x y" and passes it to the shell for execution. The command is operating system/shell specific. The command is evaluated for iFL expressions, so that the command can be built from components.

The agent awaits completion of the command, and upon successful completion it returns on the success edge. Failure to complete the command causes a return on the fail_operation edge. The agent cannot detect a successful execution of the command that completes with the intended result, only that the command did indeed return successfully.

The return document contains the result of the execution as the value of the <cmdoutput> cdata element. The interpretation of the output, if any, is the responsibility of the flow.

<status>
  <command>attrib c:\iway7\*.*</command>
  <cmdoutput>	![CDATA[
     A          C:\iway7\iway7.cmd
     A          C:\iway7\license.xml
     A          C:\iway7\uninstall.exe
     ]]>
  </cmdoutput>
  <exitcode>0</exitcode>
</status>

Users are cautioned that not all shell commands can be executed. For example, MS Windows cannot reliably interpret and execute some built-in commands. What commands can be executed are shell-specific.

The edges returned are:

success

Successful deflation.

fail_operation

The shell reported that the command failed.

Run Preemitter

Class name: XDPreemitAgent

Preemitters are intended to convert a document in preparation for emission. This agent executes a named preemitter (which must have previously been defined and configured) and generates formatted output.

The edges returned are:

success

Successful deflation.

fail_preemit

The preemitter reported an error.

Set Constant

Class name: XDConstantAgent

This agent replaces the input document with a constant document. Because all parameters are evaluated with the iWay Functional Language, this agent is frequently used to modify the input or load a file from a disk.

The edges returned are:

success

Successful.

fail_parse

An iFL expression could not be evaluated.

Set Document State

Class name: XDDocAgent

Sets or resets the current document's state.

The states that can be set are:

  • Error: Whether the document is in error state. If this is set when the document leaved the flow, the document is sent to the errorTo address. This state can be tested in iFL by the _iserr() function.

    Status can be set to SET, RESET or LEAVE.

  • Schema Error: If the document has passed through a schema check, this state reflects whether and error was reported.

    Status can be set to SET, RESET or LEAVE.

Snip

Class name: XDSnipAgent

Sends a subtree of the input document to the output document. This business agent is especially useful in pulling bodies from documents that surround the body with a header structure.

SQL

Class name: XDSQLAgent

The XDSQLAgent enables you to execute an arbitrary SQL statement, specified as a service configuration parameter. The service returns an EDA response document, as defined elsewhere.

This agent differs from the more complete RDBMS agents and adapters in that it does not interrogate an iWay response document to obtain its SQL; instead it accepts the SQL as a configuration parameter and modifies the statement based on the current document or environment.

The SQL expression can be modified during execution by iWay standard parameter expressions.

This agent also returns a variety of edges any combination of which can be wired. It can return an edge of the SQL XOPEN state, for example, 42S02 for “Table not found”.

The edges returned are:

cancelled

The operation was terminated by a cancel.

duplicate

The operation detected a duplicate condition such as inserting a tuple with a unique key that already exists in the database.

fail_notfound

The operation was unable to succeed due to a milling component of the SQL DML statement, such as a missing index or table.

fail_operation

The operation failed due to invalid parameters of other error.

notfound

The operation did not return an error but the number of rows affected was 0. note that both notfound and success are returned to permit the application interpret the result as appropriate.

Note: Both notfound and success are returned to allow the application interpret the result as appropriate.

success

The operation completed successfully.

timeout

The SQL operation terminated due to a timeout.

Note: Different SQL implementations may return different results to the service depending on how the conditions are interpreted.

The service sets the SQLcount special register to assist the application in handling return situations. For example, if a select returns no rows, the service returns candidate edges of notfound and success. The application can test the special register on a success edge to route to the appropriate logic. The count in this register is obtained by interrogating the SQL system during a non-select operation (insert, update, or delete) or by counting the returned rows for a select.

Store/Load XML

Class name: XDSREGTreeAgent

The XML contents of the message are stored into a named special register, or can be replaced from a named special register. The XML can be stored from the root or the child of a named parent within the tree. Similarly, the stored tree can be loaded (restored) to the root or as the child of a named parent. There is no requirement that the stored tree be restored to the same location from which it was taken.

Transform

Class name: XDTransformAgent

The transform named in the business agent initialization parameter is applied to each document. The transform name should be an alias specified in the transforms section of the engine configuration. The transformation can be either an iWay transform or an XSLT transform.

The transform business agent is especially useful as part of a sequence of business agents in which the output is chained to another business agent for execution of a business process.

XDTransformAgent(hipaa270)

XML To/From Special Register

Class name: XDSregTreeAgent

This agent assigns the tree in the current XML document, or a subtree, to a special register or extracts a tree in a register and assigns it to the current document. Note that some iFL expressions, including XPATH(), can operate upon a tree in a register.

The edges returned are:

success

Store or extract was successful.

fail_duplicate

The node to extract has siblings and a single root node cannot be determined.

fail_notfound

The node to be operated upon was not found in the document.

fail_operation

Invalid parameters of other error.

ZIP Document Contents

Class name: XDZipOutAgent

The current contents of the input document are replaced with a ZIP-compressed and structured content. This can be written to a file or transmitted; standard ZIP tools can be used to decompress the created output.

The edges returned are:

success

Zip operation performed.