3Creating and Using Dispatch Rules

Creating and Using Dispatch Rules

This chapter gives an overview on the EAI Dispatch Service, transforming output, and implementing a new dispatch service. It contains the following topics:

• Overview of EAI Dispatch Service

• Output Transformation

• EAI Dispatch Service

• Implementing EAI Dispatch Service

• Testing Your EAI Dispatch Service Using Argument Tracing

• Differences Between EAI Dispatch Service and Workflow

• ProcessAggregateRequest Method

• EAI Dispatch Service Scenarios

• Examples of Search Expression Grammar

• Examples of Dispatch Output Property Sets

Overview of EAI Dispatch Service

The EAI Dispatch Service is a rule-based dispatching business service that invokes business services based on the properties of its input property set. The EAI Dispatch Service can execute transformations on an input property set before dispatching it to the target business service. Such transformations can be useful for setting business service arguments or workflow process properties. They can also be used to do limited hierarchy manipulation such as discarding the envelope of an XML document. The following illustrates the EAI Dispatch Service process.

Although the EAI Dispatch Service is a utility to invoke one business service from another business service based on specified rules, one of its primary uses is to accomplish inbound and outbound integration. The EAI Dispatch Service can be the first business service of the inbound integration to decide which business service should process an incoming document. It can also be the last step of the outbound integration to send the outgoing document to the right transport. The EAI Dispatch Service is similar to the branching in Siebel Workflow. To determine whether to use Siebel Workflow or the EAI Dispatch Service, see Differences Between EAI Dispatch Service and Workflow.

EAI Dispatch Service Rule Hierarchy

The EAI Dispatch Service has a three-layer rules hierarchy as illustrated in the following figure.

Rule Sets

Rule Sets are sets of rules that you define in a particular sequence. EAI Dispatch Service parses the input document using these rules in sequence until it finds a rule that matches the input.

Rules

Rules are individual entities in a rule set. Each rule consists of data transformations, search expression grammar, and zero or more rule transforms. You define rules by using search expression grammar to establish how you want an input message to be routed. For details, see Search Expression Grammar.

Data Transformation

A transform specifies how the intermediate output is going to be generated before it is dispatched to the service and the method you specified in the rule. For details, see Output Transformation.

EAI Dispatch Service Methods

EAI Dispatch Service uses the methods described in the following table.

Method	Description
Dispatch	This method parses the input against the rules and dispatches it to the appropriate business service and business service method for further processing.
Lookup	This method returns the intermediate output generation as specified by the rule output properties without dispatching it to any business service. You use this method for debugging purposes, as well as manipulating property sets within business service or workflow.
ProcessAggregateRequest	This method allows multiple invocations of business services in a single request. The output for each request will be combined into a single Siebel property set or XML document. The input to this method is an XML document. For details, see ProcessAggregateRequest Method.
Purge	The Purge method clears any data that has been cached by the EAI Dispatch Service and does not take in any input arguments.

The EAI Dispatch Service executes the following at run time:

• Matches the input with a dispatch rule.

• Evaluates the transforms.

• Dispatches the output to a business service if the method is set to Dispatch.

Search Expression Grammar

Search expression grammar is used by the EAI Dispatch Service to parse incoming messages and determine the course of action. Search expression grammar is based on the XPath standard. The following information presents the definitions you use to construct a search expression.

Symbols	Description
/	A forward slash indicates a new level in the hierarchy. The first slash indicates the root of the hierarchy.
@	An at symbol indicates the attribute.
*	An asterisk indicates no specific criteria and that everything matches in the input. Asterisks cannot be used with attributes.
Name	This is the literal value for which the EAI Dispatch Service searches the document.

Note: See Examples of Search Expression Grammar for additional information and examples.

Output Transformation

Before dispatching the incoming hierarchy to the business service, EAI Dispatch Service can be used to perform some transformations to the hierarchy to make it appropriate for the target business service. A transform specifies how the intermediate output, in the memory, is going to be generated before it is dispatched to the service and the method you specified in the rule.

If you do not define any transforms, the EAI Dispatch Service will send the input directly to the business service. However, if you define transforms, the EAI Dispatch Service will create intermediate output based on the values of the transforms before sending the input to the business service you have defined in your rule.

Transforms are specified using one or more of the following targets in permissible combination.

RootHierarchy

This target creates a new output root hierarchy based on the source expression. The source expression specifies a node in the input hierarchy. The hierarchy rooted at this node is copied as the target root hierarchy. You can use the root hierarchy for minor modifications, such as adding a property, to the input hierarchy.

Only one root hierarchy transform can be specified because this transform always creates a new hierarchy. The root hierarchy transform is always executed before any other transforms in the combination.

Note: For the following targets, if an output hierarchy does not exist at the time of invoking the target, an output hierarchy is first created with just an empty root node before the target is applied.

ChildHierarchy

This target creates a new hierarchy as a child of the current output root hierarchy, based on the source expression. The source expression specifies a node in the input hierarchy. The hierarchy rooted at this node is copied as a new child hierarchy. You can use the child hierarchy for adding service arguments to an incoming document before dispatching to workflow or business service.

Type

This target sets the Type field to Source Expression in the root node of output hierarchy.

Value

This target sets the Value field to Source Expression in the root node of output hierarchy.

Property

This target creates or overwrites a property with name Property Name and value Source Expression in the root node of output hierarchy. You can use property to add business service arguments or workflow process properties.

As described in the following table, for certain targets, in addition to the dispatch grammar, literal values can be used for the Source Expression property to retrieve the data from the input message.

Target	Source Expression	Property Name
Property	Dispatch grammar or a literal value enclosed in quotes to search for a value	Name of the Property
ChildHierarchy	Grammar to search for the hierarchy	N/A
RootHierarchy	Grammar to search for the hierarchy	N/A
Type	Dispatch grammar or Literal value enclosed in quotes to search for a value	N/A
Value	Literal value enclosed in quotes	N/A

Note: You can combine one or more of the preceding transforms to achieve the desired transformation. The combination should not include more than one Root Hierarchy transform, Type transform, or Value transforms. However, it can include multiple Property transforms, as long as the names of the properties are different. Also if you do not want to transform the input data, but need to add an entry in transform—for example the process name of the dispatching workflow, you have to add another entry to the transform with Target: RootHierarchy, Source Expression: /*, and no Property Name. If you do not have a RootHierarchy transform, an empty PropertySet will be created and the called dispatching service will receive an invalid hierarchy data.

EAI Dispatch Service

You can use the EAI Dispatch Service to:

• Respond to a request from an external system. This can be a request to query data or a request to insert data into the Siebel Database. See Inbound Requests.

• Send data to an external system based on an event in Siebel applications. See Outbound Requests.

The EAI Dispatch Service works with the hierarchy in the property set, which may be in some cases different from the hierarchy in your document. When dispatching XML documents, you should use the XML Hierarchy Converter because it generates a hierarchy matching the hierarchy in the XML document.

Note: For details on the XML Hierarchy Converter, see XML Reference: Siebel Enterprise Application Integration.

Use the business service argument tracing facility provided by the EAI Dispatch Service to understand the input property set hierarchy. This facility dumps the input and the output of the EAI Dispatch Service as XML. For details, see Testing Your EAI Dispatch Service Using Argument Tracing.

Inbound Requests

The steps for creating an inbound or an outbound EAI Dispatch Service are very similar, as illustrated in the following figures.

The following illustrates the high-level architecture of an inbound EAI Dispatch Service.

Outbound Requests

The steps for creating an outbound EAI Dispatch Service are the same as the steps for an inbound EAI Dispatch Service with some differences in the workflow. The following illustrates the high-level architecture of an outbound Dispatch Service. For details on how to create an outbound workflow, see Outbound Scenario.

Implementing EAI Dispatch Service

The following checklist lists the steps you need to take to implement a new EAI Dispatch Service. These steps are the same whether an external system is requesting data from a Siebel application, or inserting data into a Siebel application, or when a Siebel application sends a request to an external system.

	Checklist
□	Create a workflow to be called by the EAI Dispatch Service. For details, see Creating a Workflow.
□	Define a Rule Set. For details, see Defining Rule Sets.
□	Define Rules. For details, see Defining Rules.
□	Define Transforms. For details, see Defining Transforms.
□	Set up the EAI Dispatch Service to invoke the workflow. For details, see Creating a Workflow.
□	Test your EAI Dispatch Service. For details, see Testing Your EAI Dispatch Service Using Argument Tracing.

Creating a Workflow

Design a workflow process to be called by EAI Dispatch Service upon receiving a request from an external system.

Note: For details on how to use Workflow Process Manager, see Siebel Business Process Framework: Workflow Guide.

To design a workflow to receive a request from an external system

1. In Siebel Tools, set up a workflow process to include the following steps: Start, EAI Data Mapping Engine, EAI Siebel Adapter, End.

   

2. Create process properties to pass incoming data from the EAI Dispatch Service.

   Because you have to pass data (as a hierarchy) from the EAI Dispatch Service to the workflow, you need to create a process property of type Hierarchy to receive this data. The name of the property should match the root tag of the hierarchy you are passing. If you use XML Hierarchy Converter with the EAI Dispatch Service, then you use the property XMLHierarchy.

   Also, you may want to pass other parameters, such as what data map to use, from the EAI Dispatch Service. Create process properties of type String to receive such parameters. The name of the property should match the Property Name used in your dispatch transform.

Defining Rule Sets

Rule sets are used by the EAI Dispatch Service to search the incoming data for specific criteria.

To define a rule set

1. Navigate to Administration - Integration, then the EAI Dispatch Service View.

2. Click New on the Rule Sets list applet to create a new rule set.

3. Give this rule set a meaningful name such as AribaAccountToSiebel.

4. Save the rule set.

Defining Rules

This topic describes how to define rules.

To define rules

1. Click New on the Rules list applet on the EAI Dispatch Service View.

2. Provide the following fields for this record:

   • Sequence. Enter a sequence number. This determines the sequence in which the application evaluates the rules.

   • Search Expression. Actual logic behind what the rule is looking for in the input. Define the Search Expression using Dispatch Rule Grammar. For details, see Search Expression Grammar.

   • Property Value (Optional). Populate this field with the value for the property that the input is to be matched with.

   • Dispatch Service. The business service that you want to dispatch the input to. You leave this blank if you intend to use the Lookup method.

   • Dispatch Method. Pick a method for the business service you defined in the Dispatch Service field.

3. Save your rules.

   The system validates search expression grammar. If you have not set your rules properly, you will receive an error message. See Examples of Search Expression Grammar for examples of valid search expressions.

Defining Transforms

This topic describes how to define transforms.

To define transforms

1. Click New on the Transforms list applet on the EAI Dispatch Service View to create a new transform.

2. Provide the following fields for the new record:

   • Target. Defines how the intermediate output is going to be generated before it is dispatched to the service and the method you specified in the rule. For details, see Output Transformation.

   • Source Expression. The source expression is used to assign a value to the target. You can either use a search expression pointing to a node in the input hierarchy or a literal value enclosed in quotes. For details, see Search Expression Grammar.

   • Property Name. The name of the property to be set. This value is only used when the Target is set to Property. For the other Target types this field is inactive.

   Note: See EAI Dispatch Service Scenarios and Examples of Search Expression Grammar for more details on these parameters.

3. Save your transform.

   This saves and validates your transform.

Invoking a Workflow Process From an EAI Dispatch Service

Once you created your workflow, you need to set up your EAI Dispatch Service to invoke it.

To invoke a workflow process with an EAI Dispatch Service

1. Navigate to Administration - Integration, then the EAI Dispatch Service View.

2. Select the target rule set.

3. Select the rule that invokes the workflow process.

4. For the selected rule set the following values:

   • Dispatch Service. Workflow Process Manager

   • Dispatch Method. Execute Process

5. For the selected rule insert a new record in the Transforms applet and fill in the following values:

   • Target. Property. You can select the Property value from a list of values.

   • Source Expression. Name of the workflow process to run. Make sure you include double quotes around the name, for example, "my workflow process".

   • Property Name. Process Name. You can select the Property Name value from a list applet.

Testing Your EAI Dispatch Service Using Argument Tracing

You should use the Business Service Simulator to test your EAI Dispatch Service before using it in your production environment. You can use argument tracing to write the input and the output of the EAI Dispatch Service as XML.

Note: For details on how to use the Business Service Simulator, see Integration Platform Technologies: Siebel Enterprise Application Integration.

To use the EAI dispatch service argument tracing

1. Set the server parameter EnableServiceArgTracing to true.

2. Set the appropriate event level for EAIDispatchSvcArgTrc on your server component:

   • Event level 3. Leads to input arguments being written out when errors occur.

   • Event level 4. Leads to both input and output being written out.

   If arguments are written out, there will be a trace log entry indicating the filename in the log directory. The filenames will have the following form:

   service name_input or output_args_a big number.dmp
   

   For example:

   EAIDispatchService_input_args_270613751.dmp
   

   Note: To open the file in a XML editor, you can rename the extension to XML.

Differences Between EAI Dispatch Service and Workflow

Although the EAI Dispatch Service is very similar to Siebel Workflow in initiating a task based on a condition, there are some limitations in Siebel Workflow that you can overcome using the EAI Dispatch Service. Siebel Workflow operates on business components as opposed to property sets, so Siebel Workflow can only branch based on fields in a business component. Furthermore, with Siebel Workflow you cannot route incoming documents based on property sets, because the workflow decision points cannot search inside of arbitrary property sets.

The following table provides some guidance to help you determine the best method for your business requirements.

Requirements	EAI Dispatch Service	Workflow	Notes
Need to route the incoming document based on its structure or content	Yes		The EAI Dispatch Service can route incoming documents based on property sets, whereas workflow can only branch based on fields in a business component.
Multiple dispatch targets	Yes		The EAI Dispatch Service is a better choice because writing a workflow to include every branch can be unwieldy, but you can have many EAI Dispatch Service rules.
Need to change input property set before dispatching	Yes		The EAI Dispatch Service is the better choice since it has more powerful mapping capabilities than workflow.
Need more complex processing on the input message before dispatching		Yes	The EAI Dispatch Service can branch based on the content of the input document, whereas workflow can branch based on business service.
Workflow options are sufficient for your requirements		Yes	In this case, Siebel Workflow is the best choice.

ProcessAggregateRequest Method

The ProcessAggregateRequest method allows you to perform multiple invocations of business services in a single request. The method bundles the output for each request into a single Siebel property set or XML document.

When using the ProcessAggregateRequest method with the EAI Dispatch Service business service, you need to define an input argument called AggregatedServiceRequest, with type Hierarchy for the EAI Dispatch Service to use to store the incoming data.

The following example is the input argument for this method, using XML to represent the PropertySet.

....
<PropertySet>
   <AggregatedServiceRequest> 

This is the input/output method argument for the ProcessAggregatedRequest method. The EAI Dispatch Service with ProcessAggregateRequest Method looks for this XML tag within the XML document to determine where it needs to start reading the document.

   <BusinessServiceWrapper 

wrapper around the business service. The name of the wrapper has no effect on the EAI Dispatch Service.

   BusinessServiceName=... 

XML tag for business service

   BusinessServiceMethod=...>

XML tag for business service method

   <ArgumentWrapper 

wrapper around the business service arguments. The name of the wrapper has no effect on the EAI Dispatch Service.

   XMLTagArgument1=...

XML tag for the first argument. Replace this tag with the correct XML tag for the argument your business service method is using.

   XMLTagArgument2=...

XML tag for the second argument. Replace this tag with the correct XML tag for the argument your business service method is using.

   .../>
   </BusinessServiceWrapper>

Note: For examples, see Outbound Scenarios Using ProcessAggregateRequest.

EAI Dispatch Service Scenarios

The following business scenarios explains how you might accomplish commonly performed tasks using the EAI Dispatch Service.

Outbound Scenario

For this scenario, you want to dispatch a service request as soon as it is created. The scenario assumes that:

• You are only interested in service requests logged against EAI.

• You know how to design a workflow that gets triggered as a new service request is created.

  Note: There are number of different ways to trigger a workflow process. For details, see Siebel Business Process Framework: Workflow Guide.

• You want the other non-EAI service requests to be sent to an MQSeries.

The following illustrates this scenario.

To create this scenario

1. Create a rule set with a search expression to check if the Service Request Area is set to EAI.

2. Create a workflow that is triggered when the criterion defined in Step 1 is matched.

   Your workflow should contain the following steps:

   • Start

   • EAI Dispatch Service

   • End

Inbound Scenario

For this scenario, you want to receive an XML document from an external system through MQ, HTTP, MSMQ, or other means and have the EAI Dispatch Service write to an error file if certain criteria are not met, as illustrated in the following figure. The scenario assumes that:

• You are only interested in the message if it contains an OrderReport element; otherwise, you want an error written to the error log.

• You know how to create a workflow.

To create this scenario

1. Create a rule set with a rule that searches the message for the OrderReport element.

2. Create a workflow that contains the following steps:

   • Start

   • EAI Data Mapping Engine

   • EAI Siebel Adapter

   • End

3. Create an EAI Dispatch Service that triggers your workflow, once the criteria in Step 1 are matched.

Outbound Scenarios Using ProcessAggregateRequest

The ProcessAggregateRequest method allows you to have multiple invocation of one or more methods in one or more business services using a single request. The following examples illustrate the use of this method to query account and employee information.

Querying the Account Integration Object

The following example shows how you can invoke multiple business services and setting arguments for each of the services. This is done using simple arguments for the services and by having the aggregate request invoke the QueryPage method of the EAI Siebel Adapter twice, with different searchspecs.

<?xml version="1.0" encoding="UTF-8"?>
<?Siebel-Property-Set EscapeNames="true"?>
<PropertySet>
   <AggregatedServiceRequest> 
      <BusinessServiceWrapper 
      BusinessServiceName="EAI Siebel Adapter"
      BusinessServiceMethod="QueryPage">
         <Argument Wrapper 
         PageSize="4" 
         StartRowNum="0" 
         OutputIntObjectName="Sample Account" SearchSpec="[Account.Name] LIKE 'Aa*'"/>
      </BusinessServiceWrapper> 
      <BusinessServiceWrapper 
      BusinessServiceName="EAI Siebel Adapter"
      BusinessServiceMethod="QueryPage">
         <ArgumentWrapper 
         PageSize="4" 
         StartRowNum="0" 
         OutputIntObjectName="Sample Account" SearchSpec="[Account.Name] LIKE 'Bb*'"/>
      </BusinessServiceRequest> 
   </AggregatedServiceRequest> 
</PropertySet>

Querying the Employee Integration Object

The following example shows how you can set complex type business service method arguments. The aggregate request invokes the EAI Siebel Adapter twice, and, instead of using searchspec, uses query by example by passing in a SiebelMessage.

Note: All simple arguments are attributes of the ArgumentWrapper element, and the complex argument is a child element.

<?xml version="1.0" encoding="UTF-8" ?>
<?Siebel-Property-Set EscapeNames="true"?>
<PropertySet>
<AggregatedServiceRequest>
   <BusinessServiceWrapper 
   BusinessServiceName="EAI Siebel Adapter"
   BusinessServiceMethod="Query">
   <ArgumentWrapper>
   <SiebelMessage
      MessageType="Integration Object"
      IntObjectName="Sample Employee"
      IntObjectFormat="Siebel Hierarchical">
      <ListOfSampleEmployee>
         <Employee EMailAddr="[e-mail]" />
      </ListOfSampleEmployee>
   </SiebelMessage>
   </ArgumentWrapper>
   </BusinessServiceWrapper>
   <BusinessServiceWrapper 
      BusinessServiceName="EAI Siebel Adapter"
      BusinessServiceMethod="Query">
      <ArgumentWrapper>
      <SiebelMessage
         MessageType="Integration Object"
         IntObjectName="Sample Employee"
         IntObjectFormat="Siebel Hierarchical">
         <ListOfSampleEmployee>
            <Employee FirstName="John" LastName="Doe"/>
         </ListOfSampleEmployee>
      </SiebelMessage>
      </ArgumentWrapper>
   </BusinessServiceWrapper>
</AggregatedServiceRequest>
</PropertySet>

Examples of Search Expression Grammar

In the following example, assume that the XML document is a typical document your system receives and that you want to set some rules for the EAI Dispatch Service to use to parse this document.

<?xml version="1.0" encoding="UTF-8" ?> 
- <cXML payloadID="[e-mail]" timestamp="1999-03-12T18:39:09-08:00" 
xml:lang="en-US">
- <Header>
   - <From>
      - <Credential domain="AribaNetworkUserId">
         <Identity>[e-mail]</Identity> 
      </Credential>
      - <Credential domain="AribaNetworkUserId" type="marketplace">
         <Identity>[e-mail]</Identity> 
      </Credential>
      - <Credential domain="BT">
         <Identity>2323</Identity> 
      </Credential>
   </From>
   - <To>
      - <Credential domain="DUNS">
         <Identity>942888711</Identity> 
      </Credential>
   </To>
   - <Sender>
      - <Credential domain="AribaNetworkUserId">
         <Identity>[e-mail]</Identity>
         <SharedSecret>abracadabra</SharedSecret> 
      </Credential>
      <UserAgent>Ariba.com Network V1.0</UserAgent> 
   </Sender>
</Header>
   - <Request deploymentMode="test">
      -<OrderRequest>
         - <OrderRequestHeader orderID="DO1234" orderDate="1999-03-12" type="new">
      - <Total>
         <Money currency="USD">12.34</Money> 
      </Total>
   - <ShipTo>
.......
.......

The following table provides some valid search expression examples.

Search Expression	Description
/*/Header	Go to the second level and look at the type value of each property set and check whether it is of value Header.
/*/*@DeploymentMode	Go to the second level and look at the properties of each property set and check whether any of them has the name (not the value) of DeploymentMode.
/*/*/Request@DeploymentMode	Go to the third level and look at each property set for type of value Request and property of name DeploymentMode.
/cXML/*/OrderRequest	Search at the highest level for type with value cXML and then upon matching, find a grandchild (not child) of type with value OrderRequest.

Following are examples of invalid rules:

Rule

/*/*@DeploymentMode/Request/SiebelMessage

Description

This is not a valid rule. A search for a property value must be specified at the very end. A correct form would be the following, which will have a different result.

/*/Request/*@DeploymentMode 

Rule

/*@PayLoadID@TimeStamp

Description

This also is not a valid rule. It is not possible to specify more than one property name. The correct form would use two different rules to represent this:

/*@PayLoadID 

and

/*@TimeStamp

Examples of Dispatch Output Property Sets

This example shows different output property sets generated by EAI Dispatch Service based on the hierarchy input shown in the following image and certain Target and Source Expression as shown in the first table in this topic.

The following table presents the intermediate output based on the value of the Target.

Target	Source Expression	Property Name	Output Property Set
RootHierarchy	/*	N/A
RootHierarchy	/*/B	N/A
RootHierarchy	/*/*@C1	N/A
ChildHierarchy	/*	N/A
ChildHierarchy	/*/*/D	N/A
Type	"abc"	N/A
Type	/*/B	N/A
Type	/*/*@B1	N/A
Value	"abc"	N/A
Property	"Any Expression"	Briefing
Property	/*/*/*@D1	Briefing

You can also combine different Targets to search the input message as shown on the following table.

Target	Source Expression	Property Name	Output Property
RootHierarchy ChildHierarchy ChildHierarchy Type Property Property	/* /*/*/D /*/*@C1 "demo" "this" "that"	N/A N/A N/A N/A A1 f
ChildHierarchy ChildHierarchy Type Property Property	/*/*/D /*/*@C1 "demo" "this" "that"	N/A N/A N/A A1 f