The following section lists and describes different metadata methods used for XML schemas in iWay Service Manager.
This optional metadata call returns the XML schema for the input document processed by the business agent or adapter. The engine uses the String to present the adapter description as a SOAP method.
This optional metadata call returns the XML schema for the output document returned by the business agent or adapter. The engine uses the String to present the adapter description as a SOAP method.
This method exists only in acknowledgement business agents. It is called by the rule engine to post errors that can be handled when the actual execute() method is called later. The input consists of the rule node (the node of the rule that detected the error, the node on which the error was detected, the child of the node in error, the offset component into that child, and the identifier of the EDI segment in error). Some of these fields may not be meaningful in non-EDI situations.
Acknowledgement business agents are expected to mark the document tree with the error, probably using the getAssociatedVector() and setAssociatedVector() calls to post the error objects to the appropriate node. Later, in the execute() method, a tree walk can locate the errors for construction of the acknowledgement.
Acknowledgement business agents can be scheduled for input rules violations and for output document rules violations. The execute() method for the input case generates an output document that is immediately emitted. The business agent scheduled for the output case receives the document and can modify it but is not expected to emit its own document. It can redirect the output by using set/addReplyTo() and set/addErrorTo() calls to change destinations. It can also set special registers that can be used in routing logic later in the cycle, such as in selection of a reviewer or preemitter.
In iWay Service Manager 5.5.SP2 and above the execute() method is available to replace the transform() method. The preparser will need to examine the input document and set the output document appropriately for passing on through the channel.
The return should always be "success" unless the preparser throws an exception.
In iWay Service Manager Release 5.3 and higher, the execute() method is recommended to replace the deprecated process() method. If the engine encounters a business agent with a process() method that executes without throwing an exception, it behaves as if the agent had an execute() method that returned "success".
The execute() method is called by iWay Service Manager to perform the business processing on the document. Your execute method should build the output document to be passed on to the next business agent, or to be emitted.
You should return a string describing the result of the execute() operation. Normally, this should be "success". The name is meaningful in a process flow. It is the name of the processing path (edge) to be followed by the resultant output document. For example, you might write a sophisticated dispatching business agent that analyzes a financial document and returns "asset" or "liability". The process flow might have two defined edges, one each for asset and liability. The name returned informs iWay Service Manager which path this document should follow. The normal path name in a process flow is "success" which is the default for a process() method.
A common business agent error is neglecting to load the output document for a router/analyzer. You MUST clone the output from the input document to the output document. The available service routine copyTree(in,out) can assist you in doing this in an efficient manner.
The execute() method returns the list of edges to be followed in a process flow. Implement this method to return the list of possible edges that the execute() method might return. The iWay Designer uses this information to manage the edges that can be described in the flow.
Return null if you cannot predict the set of values returned from execute().
The default method (if you do not implement your own) returns an array signifying that "success" is the only possible result. By default, "error" is returned when your execute() method throws an exception, and is always permitted by the Designer program. If execute() returns an unpredicted result (one for which there is no edge defined) the process flow attempts to go down the default edge. If no such edge is defined, error is used. If no error is defined on the node, the flow throws an exception.
String[] getOPEdges() { String[] rts = {"asset","liability"}; return rts; }
If your exit returns any token beginning with fail_, such as fail_connect or fail_operation, it causes the process flow to look first for the specific name on a wired edge. If it does not find the specific name, it looks for fail. This enables a general fail edge to manage all failures, but allows for finer distinction if desired.
The XDAgent object from which your exit descends provides a set of standard edge names to make process services appear more consistent. iWay recommends use of standard edge names for all agents to simplify process designs and documentation. Note that these edge names may not always denote a failure. For example, a service to check if a key is already in a database should return duplicate, which may be a perfectly reasonable and desired result. In other cases, such as an SQL update, this might be an error.
Name | Description |
---|---|
closed | Resource being tested is closed. |
duplicate | Some operation denoted a duplicate situation. |
fail_connect | Unable to connect to a resource. |
fail_operation | Some other activity failed not covered by another return. |
fail_parse | Parsing operation has failed. |
fail_partner | External resource issued a failure. For example, an SAP system signaled a failure to update a database. |
fail_security | Security failure. Possibly an encryption or decryption operation failed or a password was incorrect. |
fail_timeout | Operation timed out. |
notfound | Some operation denotes that a resource was not found, such as a key in a database. |
open | Resource being tested is open. |
reissued | Resource that had been previously handled has been provided again. An example might be a token being extracted from a security system. |
replace | Resource was replaced in a database or other collection. |
success | Service completed successfully. |
The return from the execute() method can be a list of edge names. For example,
return "duplicate,replace,success"
This offers the designer of the flow a selection of possible edges that might be appropriate to a specific purpose.
The return statement can also return edge names other than those in the metadata list. The SQL Service object uses this capability to return XOPEN SQL codes. In some cases, the SQL result might not be interpretable by the SQL Service. For example, an SQL GRANT command might result in an XOPEN code of 01007, meaning "privilege not granted". The SQL Service returns:
return "01007,fail_operation"
This allows the designer to follow the failure edge or the specific edge if known. The designer allows relations (edges) to be wired for the specific codes returned by getOPEdges as well as user codes, in this case 01007. Naturally, the process flow designer needs to be aware of the possible [situational] returns and design accordingly.
Note: When making returns with lists of edges, always return the list in the order of most specific to least specific. For example in an http emitter:
return("fail_501,fail_5xx,fail_server");
The interpreter will continue on the list looking for a wired edge, so if your node is wired to take fail_501 as specific and fail_5xx for the general case of all other 500-level errors, then you want the 501 edge to be taken and not the 5xx.
Developers should also bear in mind the distinction between errors and failures. The OnError edge is used when either:
This behavior makes the error edge the last resort. An exit cannot return errors, and signals problems by failures. If the failures are not wired as described above, then the process flow will follow the error edge.
Some agents can emit a status document to describe their operation. A standard status document is constructed by the MakeStdStatusTree XDAgent, which returns an XDNode of a tree that can be stored as the root of the agent's output document. The agent can populate the tree accordingly, provided that downstream components can work with the changed document.
The document from the standard call is shown in the following image.
The following is an XML schema that represents the document from the standard call:
<?xml version="1.0" encoding="UTF-8" ?> - <!-- edited with XMLSpy v2009 (http://www.altova.com) by Richard Beck (Information Builders) --> - <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> - <xs:element name="emitstatus"> - <xs:annotation> <xs:documentation>General error document from agents that emit a status document</xs:documentation> </xs:annotation> - <xs:complexType> - <xs:sequence> - <xs:element name="protocol"> - <xs:annotation> <xs:documentation>Value is the typr of protocol, such as File, MQ, etc.</xs:documentation> </xs:annotation> </xs:element> - <xs:element name="parms"> - <xs:annotation> <xs:documentation>Evaluated parameters used for this instance of the service</xs:documentation> </xs:annotation> - <xs:complexType> - <xs:sequence minOccurs="0"> - <xs:element name="parm" maxOccurs="unbounded"> - <xs:annotation> <xs:documentation>Value is the ebaluated value of the parameter.</xs:documentation> </xs:annotation> - <xs:complexType> <xs:attribute name="name" use="required" /> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> - <xs:element name="timestamp"> - <xs:annotation>
<xs:documentation>The time to millisecond at which this document was created.</xs:documentation> </xs:annotation> </xs:element> - <xs:element name="status" type="xs:integer"> - <xs:annotation> <xs:documentation>Status code relating to the error. By standards, status 0 is success, but the status code is decided by the component.</xs:documentation> </xs:annotation> </xs:element> - <xs:element name="msg" minOccurs="0"> - <xs:annotation> <xs:documentation>Explanatory message</xs:documentation> </xs:annotation> - <xs:complexType> - <xs:sequence minOccurs="0"> - <xs:element name="SUB_MSG" minOccurs="0" maxOccurs="unbounded"> - <xs:annotation> <xs:documentation>Zero or more further messages better describing the error.</xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:complexType> </xs:element> - <xs:element name="channel" minOccurs="0"> - <xs:annotation> <xs:documentation>The name of the channel from which this error originated</xs:documentation> </xs:annotation> </xs:element> - <xs:element name="nodename" minOccurs="0"> - <xs:annotation> <xs:documentation>The name of the pflow node that generated this error</xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
Note: For simplicity, metadata calls are not shown.
import com.ibi.edaqm.*; /** * This is the plug-in agent used to move the document from input to output. * This is the simplest possible agent. It can be called to service any document type. * * This class extends the XDAgent class, which provides several services, such as * tracing. * * @author R. Beck * @since July, 2000 */public final class XDMoveAgent extends XDAgent //XDAgent extends XDExitBase { /** * Agents have a null constructor. It must be public as it is reached from the * edaqm package. */ public XDMoveAgent() { super(); } /** * Execution of the agent begins at the execute method. The input document and * the output document are passed in. This particular execute() method simply * copies the message tree from the input document to the output document. This * agent is, in effect, a NOP. Upon completion of this agent, the output document * is passed to the next stage. * * @param docIn Input document. * @param docOut Output document to create. * @exception XDException (unused in this implementation) */ public String execute(XDDocument docIn, XDDocument docOut) throws XDException { docIn.moveTo(docOut); //service method in XDExitBase return “success”; } }
From time to time the server finds it necessary to cancel a current operation. That can come about due to a timeout in a process flow or a component of the flow such as a join that is not satisfied. An exception in a process flow object can also trigger a need to cancel the remainder of the flow.
The server provides for two methods of signaling a desire to cancel:
The simplest method to test this is to use a Java call: Thread.currentThread()isInterrupted() and escape the current adapter if it is true. Please do not reset the interrupted flag, as other threads may need to interrogate it. Proper use of this facility is discussed in relevant Java documentation.
iWay Software |