7 Constructing the ABCS

Before you begin constructing an ABCS, ensure that:

• The relevant development SOA server with a SOA Core Extension is installed and running.

  Refer to How to Set Up AIA Workstation.

• The application entities' schemas (Application Business Message [ABM] schemas) are accessible from Metadata Service (MDS) repository. They should not be part of each ABCS project.

  Refer to Using MDS in AIA.

• Enterprise Object Library containing Enterprise Business Objects (EBOs) and Enterprise Business Messages (EBMs) are accessible in the MDS Repository. EBOs and EBMs should not be part of each ABCS project.

  Refer to Using MDS in AIA.

• All the abstract WSDLs of EBS or participating applications should be accessible from the MDS Repository.

  Tip:

  The abstract WSDL of an ABCS that is being developed should be accessed from MDS. The exceptions to this rule are:

  • The EBS references WSDLs that define PartnerLink types

  • Participating applications reference WSDLs that define PartnerLink types

  • The adapter WSDLs that are generated by JDeveloper

  • Abstract WSDLs of the services defined at ABCS extension points

  For more information, see Using MDS in AIA.

• Requester and provider participating applications have been identified.

• EBOs and EBMs have been identified.

• Functionality mapping between EBS and participating applications is complete. This mapping should include:

  • Data element spreadsheet mapping between the EBO and participating application messages.

  • Operations mapping between the EBS and participating applications.

• The style of interaction (MEP: request-response, fire and forget, asynchronous request, and delayed response) is defined.

  See Choosing the Appropriate MEP.

• The communication protocols with the participating applications are identified.

  For more information about how an ABCS interacts with participating applications, see Establishing Resource Connectivity.

• Any participating application-specific requirements such as error handling or security have been identified.

AIA services (ABCSs and EBSs) can be developed as a composite application built using SCA building blocks. Four SCA elements apply to these services:

• Service

  Represents an entry point into the SCA component or a composite.

• Reference

  Represents a pointer to an external service outside the scope of the given SCA component.

• Implementation type

  Defines the type of implementation code for a given SCA component that is used for coding the business logic. Example implementation types include BPEL and Mediator.

• Wire

  Represents the mechanism by which two components can be connected to each other. Usually a reference of one component is connected to a service exposed by another component.

An SCA component may expose one or more services, may use one or more references, may have one or more properties defining some specific characteristics, and may be connected to one or more components using SCA wiring.

The building blocks of SCA can be combined and assembled to create composite applications. A composite application can be thought of as a composition of related SCA components that collectively provide a coarse-grained business function.

A composite application can be thought of as a composition of related SCA components that collectively provide a coarse-grained business function. A composite may contain certain components that might be required only for the internal implementation of the composite and for which interfaces might not be required outside the scope of the composite in context.

Components may exist that can be used just for the internal implementation of the composite and are thus not required to expose services, references, or both.

A requester ABCS composite as shown in Figure 7-1 can be built using a single component that is exposed as service.

The component can use one reference representing an EBS or more references representing the outbound interactions with other applications.

Figure 7-1 Example of a Requester ABCS Composite

Similarly, a Provider ABCS composite as shown in Figure 7-2 can be built using a single component that is exposed as service.

The component can use one or more references representing the outbound interactions with the applications.

Figure 7-2 Example of a Provider ABCS Composite

1. In JDeveloper, create an SOA composite project.
2. Open the composite.xml in design mode.
3. Add a BPEL component in the Components swim lane.
4. Add a web service as external reference service in the References swim lane.

   This reference service could represent an EBS, an Adapter Service, or a participating application. An abstract WSDL of the EBS, Adapter Service, or participating application should be accessible from the MDS Repository.

5. Wire the BPEL component to the external reference component created in step 4.
6. Complete the following for handling the faults.

   • Add a web service as external reference service in the References swim lane. Provide the reference to the abstract WSDL of the AIAAsyncErrorHandlingBPELProcess in the MDS repository.

   • Wire the BPEL component to the AIAAsyncErrorHandlingBPELProcess service.

   For more information about fault handling in AIA services, see Configuring Oracle AIA Processes for Error Handling and Trace Logging.

Figure 7-3 illustrates a requester ABCS composite.

Figure 7-3 Example of a Requester ABCS Composite

After you have developed the composite in design mode using JDeveloper, the ABCS that is implemented as a BPEL process component should be constructed to its completion.

In the ABCS, the following tasks are accomplished:

• Message enrichment

• Message header population

• Message content transformation

• Error handling and logging

• Extensibility

• CAVS enablement

• Security context implementation

For more information about completing ABCS development, see Completing ABCS Development.

• For each target, add a reference.

  • The target can be a web service or adapter.

  • If the target service requires transformation, create a mediator component in between.

• For each interface, add a service.

  • The service can be a web service or adapter.

  • If the adapter interface requires transformation, create a mediator component in between.

SOA Suite 12c has introduced a central repository, Metadata Service (MDS), that backs up your application (and hence your composites) at design time and runtime. MDS is like a version management system, where you can store and use the shared common artifacts at design and runtime.

AIA leverages the MDS repository to store common design time artifacts that are shared with all developers. There is a common directory of abstract WSDLs in the MDS, which is a centrally accessible endpoint.

The artifacts that are stored in the MDS include:

• Schemas: EBO schemas and ABM schemas

• WSDLs: Abstract WSDLs of EBS, ABCS, Adapter Services, CBPs and EBFs

All the abstract WSDLs of all AIA services are put in MDS. You build your consuming AIA service composite application using the abstract WSDL of a referenced service. No dependency exists on the order of deployment for composites.

Since there is no dependency on the referenced services during the deployment of the composites, there is no dependency on the order of deployment for the composites. A referenced service does not have to be deployed to be referenced by another service. This also resolves the cases where there are cyclic references involved among the services.

To get a better understanding of why this is recommended, see Separation of Concerns.

For details of how MDS is used in AIA, refer to Using MDS in AIA.

For ABCSs and Adapter services, the abstract WSDLs are to be located in MDS at:

AIAMetaData/AIAComponents/ApplicationConnectorServiceLibrary/<PRODUCT_CODE>/<Version Number>/<Service Type>

Possible values for <Service Type> are RequesterABCS, ProviderABCS, AdapterServices.

Possible values for <Version Number> are V1, V2.

The utility for moving artifacts to MDS is described in Using MDS in AIA.

Examples:

AIAMetaData/AIAComponents/ApplicationConnectorServiceLibrary/Siebel/V1/RequesterABCS
AIAMetaData/AIAComponents/ApplicationConnectorServiceLibrary/Siebel/V1/ProviderABCS

Sometimes an automatic correction of data or a reversal of what has been done in requester service is needed. The typical scenario is one in which an error occurs in the transaction and the transactions cannot be rolled back.

In these situations, the requester application can implement the compensation service operation and pass the name of the service operation to the provider ABCS. The provider ABCS invokes this compensation service operation if there are errors. There may be a requirement to implement a compensating service for the requesting service.

To invoke the correct compensating service from the providing service:

1. Populate the EBMHeader/Sender/WSAddress/wsa:FaultTo/wsa:ServiceName with the name of the compensating service in the transformation used for constructing the request EBM.

   Example of the name of the compensation service: CompensateCreateOrderSiebelReqABCSImpl

   For more information about naming, see Oracle AIA Naming Standards for AIA Development.

   Figure 7-4 illustrates the structure of the WSAddressType.

Figure 7-4 Structure of the WSAddressType

This information is used in the compensate operation of the EBS to route the request for compensation to the correct compensating service.

For information about implementing this MEP, see Implementing Provider ABCS in an Asynchronous Message Exchange Scenario.

For information about ensuring transactions, see How to Ensure Transactions in AIA Services.

For information about error handling, see Configuring Oracle AIA Processes for Error Handling and Trace Logging.

1. Populate the EBMID.

   This is used for correlation of the response to the correct requesting service instance.

   Figure 7-5 illustrates the structure of the CreateSalesOrderEBMType.

   Figure 7-5 Structure of the CreateSalesOrderEBMType

   
2. Set the EBMHeader/Sender/WSAddress/wsa:ReplyTo/wsa:ServiceName to the name of the requesting service name in ABM to EBM transformation as shown in Figure 7-6.

   This is the name of the service that must be invoked by the EBS for processing the response message. In most of the situations, it is the same requester ABCS that is also be responsible for processing the response message coming from provider ABCS.

   Figure 7-6 Structure of the SWSAddressType

   

   This information is used in the response operation of the EBS to route the response from the providing service to the correct requesting service.

3. Set the responseCode attribute of the EBM verb.

   The responseCode attribute of the EBM verb is set to indicate to the providing service that the requesting service is expecting a response. This is evaluated in the providing service to send back a response.

4. Set correlation information in the requesting service partner link.

   The delayed response from the providing service routed by a response EBS would be received by a Receive activity. After the Invoke step is performed in the requesting service and the process moves to the Receive step, the BPEL process instance is suspended and dehydrated. This restarts after the response is received. To facilitate this behavior, a correlation set has to be specified on the partnerLink for the Receive.

   The requester ABCS process should look like the example in Figure 7-7. This is the process for which you must set the correlation IDs.

   Figure 7-7 Example of Requester ABCS Process

   

In the process described in How to Populate the EBM Header for Asynchronous-Delayed Response you must set the correlation in two places:

• Correlation Set

  Add a correlation ID and create a correlation set for the Invoke activity where the process would go into the dehydration store

  Add a correlation ID and create a correlation set for the Receive activity where the process would be recalled from the dehydration store after getting a delayed response from the provider/edge application.

• Correlation Property

  Add a standard name-value pair for each partnerLink that is linked to the Invoke or Receive activities where the correlation sets are defined as mentioned previously. The property should always be defined as correlation = correlationSet.

This section discusses programming models for:

• Using a separate service for error handling

• Using JMS queue as milestone between RequesterABCS and the EBS

• Using a parallel routing rule in the EBS

For details about the tasks see Implementing Provider ABCS in an Asynchronous Message Exchange Scenario.

1. Populate the EBM header of the request message in the providing service with fault information.

   If an error occurs in the provider service before evaluation of the requirement of a response and an exception is issued, enter the fault information in the request message EBM header. This facilitates passing the entire request EBM along with the fault message to the catch block for processing.

2. Implement Error Handling in the providing service.

   If a particular error needs compensation service to be invoked, then the compensate operation of the EBS is invoked for routing the request to the compensation service.

   For more information, see Configuring Oracle AIA Processes for Error Handling and Trace Logging.

3. Enter the correlation information in the EBM header in the providing service.

   Use the EBMID in the EBM header for correlation of the response message to the correct requesting service instance. To facilitate correlation, the EBMID in the EBM header of the request message must be copied to the RequestEBMID in the EBM header of the response message in the ABM to EBM transformation of the providing service as shown in Figure 7-11.

   Figure 7-11 Structure of CreateSalesOrderResponseEBMType Element

   

   For information about the technique of passing the EBMHeader of the request message in a variable into the ABM to EBM XSLT, see Working with Message Transformations.

   This is required to copy the relevant information from the EBM header of the Request EBM to the EBM header of the Response EBM.

4. Populate the EBM header of response message in the providing service with fault information.

   If an error occurs in the provider service after evaluation of the requirement of a response, you must populate the fault information in the response message EBM header fault component. This facilitates passing the response EBM along with fault message to the catch block for processing.

   The requesting service receives a response with fault elements populated.

If you use the programming models found in Programming Models for Handling Error Response in the Asynchronous Request-Delayed Response MEP for the request-delayed response pattern, follow these guidelines.

Programming Model 1: Using a Separate Service for Error Handling

The provider ABCS should publish the messages to JMS Queue in both successful message processing and error scenarios, if the provider ABCS is required to send the response or the error message.

Programming Model 2: Using JMS Queue as a Milestone Between the Requester ABCS and the EBS

In the case of successful message processing, the provider ABCS invokes the response EBS, using a native binding call, in the existing transaction.

If an error occurs during the message processing, the provider ABCS publishes the errored-out message into another JMS queue. The response EBS picks up the message and invokes the fault handler service

Programming Model 3: Using a Parallel Routing Rule in the EBS

The provider ABCS has two references to the response EBS composite. Follow the naming conventions to name the provider ABCS 's second reference to the EBS.

For details on naming conventions, see Oracle AIA Naming Standards for AIA Development.

Figure 7-12 illustrates the asynchronous provider ABCS composite with a second reference to the ResponseEBS. The label for the second reference is <EBSName>ErrorResponseEBS.

Figure 7-12 Async Provider ABCS Composite with a Second Reference to ResponseEBS

When the message is processed successfully, the provider ABCS invokes the callback operation on the response EBS. The response EBS routes the response to the requester ABCS by invoking another receive activity. When en error occurs during the processing of the message, the provider ABCS invokes the response EBS through its second reference to the response EBS. In this case, the responseEBS is invoked using a SOAP call, not a native call. This is achieved by having the following property set on the second reference to the response EBS, in the composite of the provider ABCS.

<binding.ws port="<port>" location="<url>"/>
      <property name="oracle.webservices.local.optimization type="xs:boolean">false</property>
  </binding.ws>

For more information about ensuring transactions, see How to Ensure Transactions in AIA Services.

See Configuring Oracle AIA Processes for Error Handling and Trace Logging.

This MEP need not support transactions. No break points such as midprocess Receive, wait, Pick, onMessage activities should be in any of the BPEL processes participating in implementation of this MEP.

For more information about ensuring transactions, see How to Ensure Transactions in AIA Services.

See Configuring Oracle AIA Processes for Error Handling and Trace Logging.

Because this MEP involves implementation of transient services (no break point activities and hence, no dehydration in the middle), Oracle AIA highly recommends that the audit details for BPEL services are persisted only for faulted instances. The service instances associated with the successfully completed integration flows are not visible using Oracle Enterprise Manager. This approach significantly improves the response time.

auditLevel property sets the audit trail logging level. This configuration property is applicable to both durable and transient processes. This property controls the amount of audit events that are logged by a process. Audit events result in more database inserts into the audit_level and audit_details tables, which may impact performance. Audit information is used only for viewing the state of the process from Oracle Enterprise Manager Console. Use the Off value if you do not want to store any audit information. Always choose the audit level according to your business requirements and use cases.

For synchronous BPEL processes, AIA recommends nonpersistence of instance details for successfully completed instances. For this, set the auditLevel property to off at the service component level. This general guideline could be overridden for individual services based on use cases.

The Create verb indicates a request to create a business object using the information provided in the payload of the Create message. It is used in operations that are intended to create an instance of a business object.

When to Use the Create Verb

If both the service requester and service provider have the same object, then Sync would be a more appropriate verb to use. However, the usage of Sync is conditional on the service provider having an implementation of a Sync operation.

A typical use of a Create operation is a front-end customer management system that could take service requests from customers and based on the information provided, request a work order system to create a work order for servicing the customer.

The Create verb is not used for composite operations; it always involves the creation of one (or more for List) instance of a business object.

Content Payload

The payload of an operation that uses a Create verb is typically a complete business object, and in general every business object has only two messages with a Create operation (Single and List).

Verb Attributes

The Create verb has an optional ResponseCode attribute that communicates the payload that is expected in the response message to the Create request. The possible values for the ResponseCode are restricted to either ID (response payload is expected to be the Identifier of the object that was created) or OBJECT (response payload is expected to be the entire object that was created).

Corresponding Response Verb

The Create verb has a paired CreateResponse verb that is used in the response message for each Create EBM. The response is expected to be provided by the target application only if the original request message explicitly requests a response by setting the ResponseCode attribute in the Create message.

Response Content Payload

The payload type of the response verb is always based on the payload type of the Create Request operation. It is implemented as a different type to support user customization if needed.

The Update verb indicates a request to a service provider to update an object using the payload provided in the Update message. It is used in operations that are intended for updating one or more properties of a business object or array of business objects.

Operations that use the Update verb must create or update content and should not be an orchestration of other operations.

When to Use the Update Verb

Similar to Create, a business process invokes an Update operation mainly in cases in which the source event that triggers the invocation is not the updating of the object in the requesting system. If both the service requester and service provider have the same object, then Sync would be a more appropriate verb to use. However, use of Sync would be conditional to the service provider having an implementation of a Sync operation.

An example of an Update operation is a receiving system updating a purchase order line with the quantity of items received, or an order capture system updating the customer record with customer address and other information.

The content included in the business payload of an EBM using the Update verb is assumed to be only the fields that must be updated in the target application. The Update verb uses the ActionCode property of the business components and common components to communicate processing instructions to the target system. This is necessary for hierarchical, multilevel objects when the update happens at a child level.

The ActionCode property exists in an EBO for all components that have a multiple cardinality relationship with its parent. The possible values for the ActionCode are Create, Update, and Delete. It is intended for use only with the Update verb to communicate the processing action to be applied to that business component. Ensure that the ActionCode applies only if the object has child business components-if not, an ActionCode is not needed and the verb alone is sufficient to convey this information.

A use case for ActionCode is a case in which a requisition is updated in a self-service requisitioning system, and this updated information must be communicated to the Purchasing system, which also maintains a copy of the requisition.

Assume that a user updates a requisition and does the following actions (in a single transaction):

• Updates the description in the requisition header

• Adds a new requisition line (line number 4)

• Modifies the item on a requisition line (line number 3)

• Deletes a requisition line (line 2)

• Modifies the accounting distribution of a requisition line, and adds a new accounting distribution (line 1)

The content of the DataArea business payload in the instance XML document that communicates the preceding changes is shown in Example 7-1.

Content Payload

The payload of an operation that uses an Update verb is typically the entire EBO and in general every business object has only two messages with an Update operation (single and list).

Situations may occur in which subsets of an EBO must be updated, in which case multiple update messages may possibly exist, each with a distinct payload. An example is a possible UpdateSalesOrderLineEBM message with a payload that contains only SalesOrderLine.

Verb Attributes

The Update verb has an optional ResponseCode attribute that is intended to communicate the payload that is expected in the response message to the Update request. The possible values for the ResponseCode are restricted to either ID (response payload is expected to be the Identifier of the object that was created) or OBJECT (response payload is expected to be the entire object that was created).

Corresponding Response Verb

The Update verb has a paired UpdateResponse verb that is used in the response message for each Update EBM. The response is expected to be provided by the target application only if the original request message explicitly requests a response by setting the ResponseCode attribute in the Update message. The payload of the response is either the ID or the entire object that was updated, depending on the ResponseCode specified in the Update request.

Response Content Payload

The payload type of the response verb is always based on the payload type of the Update Request operation. It is implemented as a different type to support user customization if needed.

<UpdateRequisition actionCode="Update">   Root Action Code not processed
    <Description>New Description</Description>
   <RequisitionLine actionCode="Update"> Indicates that some property or 
association of this line is being updated. In this example, the accounting 
distribution Percentage has been updated for Line 1, and a new 
AccountingDistribution line has been added  
         <Identification>
               <ID>1</ID>
         </Identification>
         < RequisitionAccountingDistribution actionCode="UPDATE">
               <Identification>
                     <ID>1</ID>
               </Identification>
               <AccountingDistribution>
                     <Percentage>15</Percentage>
               </AccountingDistribution>
         < /RequisitionAccountingDistribution>
         < RequisitionAccountingDistribution actionCode="ADD">
               <Identification>
                     <ID>3</ID>
               </Identification>
               <AccountingDistribution>
                     <Percentage>15</Percentage>
               </AccountingDistribution>
         < /RequisitionAccountingDistribution>
   </RequisitionLine>
   <RequisitionLine actionCode="DELETE"> Indicates this line has been deleted
         <Identification>
               <ID>2</ID>
         </Identification>
   </RequisitionLine>
   <RequisitionLine actionCode="UPDATE">
         <Identification>
               <ID>3</ID>
         </Identification>
<ItemReference>
<Identification>
                     <ID>1001</ID>
               </Identification>
</ItemReference>
   </RequisitionLine>
   </RequisitionLine>
   <RequisitionLine actionCode="ADD"> Indicates this line has been added
         <Identification>
               <ID>4</ID>
         </Identification>
<ItemReference>
<Identification>
                     <ID>1005</ID>
               </Identification>
</ItemReference>
   </RequisitionLine>
</UpdateRequisition>

The Delete verb is a request to a service provider to delete the business object identified using the object Identification provided in the payload of the Delete message.

When to Use the Delete Verb

The Delete verb is used for operations that are intended to delete a business object.

Operations that use the Delete verb must delete content and should not be an orchestration of other operations.

Content Payload

The payload of the Delete verb must be only an identification element that uniquely identifies the business object to be deleted.

Verb Attributes

The Delete verb has an optional ResponseCode attribute that is intended to communicate the payload that is expected in the response message to the Update request. The only possible value for the ResponseCode for Delete is ID (response payload is expected to be the Identifier of the object that was created).

Corresponding Response Verb

The Delete verb has a paired DeleteResponse verb that is used in the response message for each Delete EBM. The Response is expected to be provided by the target application only if the original request message explicitly requests a response by setting the ResponseCode attribute in the Delete message. The only allowed value for the ResponseCode is ID.

The Sync verb indicates a request to a service provider to synchronize information about an object using the payload provided in the Sync message.

When to Use the Sync Verb

The Sync verb is used in situations in which applications provide operations that can accept the payload of the operation and create or update business objects as necessary.

Operations that use the Sync verb must create or update content and should not be an orchestration of other operations.

The primary usage scenario for Sync is generally batch transactions in which the current state of an object is known, but what has changed between the previous sync and the current sync is not known. Sync can also be used to synchronize individual instances of objects. The initiator of Sync is generally the system that owns the data to be synchronized.

Using the Sync operation implies that the object exists in both the source and the target system, and the result of Sync is that both the source and target have the same content. Sync is different from the other verbs in that it assumes a dual processing instruction-Sync can both create and update existing content.

The content of the Sync reflects the current state of the object in the system generating the message. In this mode, a single Sync message can contain multiple instances of nouns, with none of them having any specific change indicator. The source system generates the message, and all systems that subscribe to the message are expected to synchronize their data to reflect the message content.

Sync is probably the most practical approach for master data management scenarios in which change is not frequent, and it may not be practical or necessary from an operational point of view to synchronize data on a real-time basis.

The Sync verb has an optional syncActionCode attribute that can be used to further instruct the recipient of a Sync message about the expected processing behavior. The possible values for the syncActionCode are:

• CREATE_REPLACE:

  This is the default behavior of Sync when no syncActionCode is specified. The target system that receives a Sync message with no syncActionCode attribute, or with a syncActionCode attribute value of NULL or CREATE_REPLACE, is expected to create the object if it does not exist in the target system, or if it does exist, the entire object is to be replaced with the definition that has been provided in the Sync message.

• CREATE_UPDATE:

  A Sync message with the value of syncActionCode as CREATE_UPDATE is expected to be processed as follows: create the object if it does not exist in the target system, or if it does exist, update the object with the content that has been provided in the Sync message.

Content Payload

Generally speaking, there is only one Sync message per EBO (with a single and list implementation) and the payload of the message is the entire EBO.

Sync should always be used to synchronize the entire business object. Multiple Sync messages may exist in cases in which different named views of the business object exist, but never for synchronizing a specific component of a business object.

Verb Attributes

The Sync verb has an optional ResponseCode attribute that is intended to communicate the payload that is expected in the response message to the Sync request. The possible values for the ResponseCode for Sync is restricted to OBJECT (response payload is expected to be the entire object that was created or updated) and ID (response is only the ID of the object that was created or updated)

Corresponding Response Verb

The Sync verb has a paired SyncResponse verb that is used in the response message for each Sync EBM. The response is expected to be provided by the target application only if the original request message explicitly requests a response by setting the ResponseCode attribute in the Sync message.

Response Verb Content Payload

The payload type of the response verb is always based on the payload type of the Sync Request operation. It is implemented as a different type to support user customization if needed.

The Validate verb is a request to a service provider to validate the content provided in the payload of the message. It is used for operations that are intended to verify the validity of data.

When to Use the Validate Verb

Operations that use the Validate verb do not create or update business objects, and can internally be implemented as an orchestration of other operations. For example, validating a purchase order for approval may involve validating whether a budget is available, if the supplier is still active, if the requisitions that need the items on the line are still valid, and so on.

Content Payload

The payload of any operation that falls in the Validate category can be a business object, a business component of a business object, or any other user-defined payload.

Verb Attributes

Not applicable.

Corresponding Response Verb

The Validate verb has a paired ValidateResponse verb that is used in the response message for each Validate EBM. The Validate verb is always implemented synchronously.

Response Content Payload

The response payload of a Validate operation is user-definable.

The Process verb is a request to a service provider to perform the corresponding operation on the business object associated with the service. It is generally used for operations that orchestrate multiple other operations, are intended to achieve a specific business result, or both.

When to Use the Process Verb

Process is used as a single verb to categorize all business operations that result in content updates but do not fall in the Create/Update/Delete category to avoid a proliferation of verbs for specific business object actions.

Operations that use the Process verb must always result in creation or updating of one or more business objects and may represent an orchestration of other operations.

The Process verb can also be used for operations that act on a single business object, but have specific business semantics that cannot be communicated using an Update operation. In general, such actions are implemented in applications with distinct access control, and specific business rules that are applicable when the action is performed. Examples of such actions are state changes, updating meter readings on equipment, and so on.

Because multiple operations can be performed by the Process verb, potentially multiple Process verbs can be used in any given EBS.

Content Payload

The nature of the operation performed by a Process verb may require properties and values that are not part of the business object on which the operation is being performed, but are required by the business rules that are implemented by the operation. For example, approval of a sales order can record a comment as part of the approval, but the comment in itself may not be a property of the sales order.

In general, the request and response payload of operations that use the Process verb need the ability to reflect the method signature of the application, without a restriction that the content that forms the payload must come from the business object to which the service operation is associated.

To support the preceding, the payload of each Process operation is not restricted to content from the EBO definition. This is unlike all the other EBOs for which the EBM business content must be the same as or a subset of the EBO content.

The List pattern used in the other generic verbs is also applicable here, but does not apply generically; that is, in an EBS, both a single and List implementation of a Process operation may exist, or just one or the other. Unlike the other generic verbs for which single and list are both consistently created for all EBOs, Process is driven by the requirements of the corresponding operation.

Verb Attributes

Not applicable.

Corresponding Response Verb

The Process verb has a paired ProcessResponse verb that is used in the response message for each Process EBM.

Response Verb Payload

The payload of the response verb is specific to each process operation and is determined by the objective of the operation. Similar to the Process verb payload, there is no restriction that the content of the response is restricted to the content of the EBO.

The Query verb is a request to a service provider to perform a query on a business object using the content provided in the payload of the Query message, and return the query result using the corresponding response message associated with the query. The requester can optionally request a specific subset of the response payload.

When to Use the Query Verb

Similar to the other verbs, the Single and the List pattern apply to queries also. The use of Query for each of these patterns has been listed separately in the following sections.

Single Object Query Intended to Return One and Only One Instance

The Single Object Query operation is a simple get by ID operation that enables callers to look up an EBO by its identifier. It is intended to request a single instance of a business object by specifying the ID of the object and optionally a QueryCode and ResponseCode with a set of parameters and their values. The identifier of the object is specified in the DataArea of the Query EBM.

The single object query does not support any other query criteria to minimize the possibility of the query returning multiple objects, and the response payload for the simple query is restricted to a single instance of the object being queried.

The Single Object Query contains the following elements:

• QueryCode within the Query element (optional)

  The QueryCode in a single object Query is used mainly as a supplement to the Identification element provided in the DataArea of the Query. The Query Code can be used for a single object query for cases in which there is a need to communicate more than the ID to the query service provider to successfully run the query. The code could be used to either refine the query, or to select the object to be queried based on the Query Code.

  Tip:

  For this to happen, the service provider should implement the processing of such a code. Currently, Oracle AIA does not predefine any generic Query Codes as part of the EOL.

• ResponseCode within the Query Element (optional)

  The ResponseCode is a predefined code that instructs a query service provider to filter the response content of the EBO to a specific subset of the response object.

  The return payload for a generic Query is always the entire EBO; that is, by default, the response payload for a QuerySalesOrder operation is always the entire SalesOrder with lines, shipment, and so on. If the requester wants the service provider to provide only the SalesOrder header with none of the child components, then the ResponseCode can be used as an instruction to the service provider to build the response payload accordingly.

  Tip:

  For this to happen, the service provider should implement the processing of such a code. Currently, Oracle AIA does not predefine any generic Request or Response Codes as part of the EOL.

Content Payload

The payload of a single object query is always the ID of the object to be queried. This is specified within the Identification element of the DataArea as shown in Example 7-2.

Verb Attributes

The simple Query can have an optional getAllTranslationsIndicator to indicate whether the service provider is expected to provide all translations to be populated in the response for all translatable elements. The default is to bring back data in the language of the request only.

Based on the preceding, there are ways in which in which a simple query can be constructed:

• Simple Query with just ID:

  An example of querying for a single object would be querying Purchase Order with ID="3006". No other code or parameters are needed in this example.

• Simple Query with QueryCode:

  As an example, consider an application that maintains a distinction between a person as a customer versus an organization as a customer. A single Customer Query service exists, but to successfully run the query, the service provider must be told whether the ID to be queried belongs to an organization or to a person. In this case, the QueryCode can be used to communicate the Person/Organization information.

List Query That Can Return Multiple Instances

The single object query does not support any search criteria beyond a simple search by identification, and can return only one instance of an object. All other queries are treated as List queries.

A List Query may return multiple records in response to the query and supports the ability to build complex queries.

The List Query is implemented using the following elements:

QueryCode within the Query element (optional)

The QueryCode in a List Query serves as a means for a service provider to limit the possible queries that can be built using a List Query. In the absence of a QueryCode, a service provider should be able to generically support all possible queries that can be communicated using the QueryCriteria element explained subsequently.

For this to happen, the service provider should implement the processing of such a code. Currently, Oracle AIA does not predefine any generic Query Codes as part of the EOL.

ResponseCode within the Query Element (optional)

The ResponseCode is a predefined code that instructs a query service provider to filter the response content of the EBO to a specific subset of the response object. For list queries, this can serve as an alternate mechanism instead of specifying the ResponseFilter element of a Query.

The return payload for a generic Query is always the entire EBO. For example, by default, the response payload for a QuerySalesOrder operation is always the entire SalesOrder with lines, shipment, and so on. If the requester wants the service provider to provide only the SalesOrder header with none of the child components, then the ResponseCode can be used as an instruction to the service provider to build the response payload accordingly.

For this to happen, the service provider should implement the processing of such a code. Currently, Oracle AIA does not predefine any generic Request or Response Codes as part of the EOL.

QueryCriteria (1 to n instances)

The QueryCriteria element enables a user to build a complex query statement on a specific node of the object being queried. At least one QueryCriteria element must be specified for a List Query.

Multiple QueryCriteria elements can be present in a Query if the query spans multiple nodes of the object being queried. Multiple Query criteria is similar to a subselect in that the result set of one Query Criteria is filtered by the second to arrive at a smaller subset of records.

Each QueryCriteria element consists of:

• QualifiedElementPath (0 or 1 instance):

  This enables the user to specify the node on which the QueryCriteria applies. If the element is not included in the Query, or if it is included with no value or a NULL value, or if it has a value of /, the query criteria applies to the root element of the object.

  QueryExpression (exactly 1 instance, with optional nesting of other QueryExpressions within it): This element is the container for the actual query. The QueryExpression is a nested construct that enables you to define complex queries. Each QueryExpression consists:

  • A logicalOperatorCode attribute that can have a value of either AND or OR. These attributes can be specified to indicate the logical operation to be performed on the content (nested multiple QueryExpressions or list of ValueExpressions) within the QueryExpression.

  • A choice of one or more QueryExpressions or one or more ValueExpressions.

    • A QueryExpression may contain other QueryExpressions when you must combine multiple AND or OR operations in a query.

    • If the Query can be expressed with a single AND or OR operator, then it can be built using multiple ValueExpressions within an outer QueryExpression.

• ValueExpression (1 or more instances):

  Each ValueExpression represents an assignment of a value to a specific node within the node represented by the QualifiedElementPath (or the root node if the QualifiedElementPath is not present). The ValueExpression is specified using:

  • An ElementPath element that represents either a node (expressed as a simpleXPath expression) to which the query value is being assigned, or a Code in case the element cannot be found in the document. For example, /SalesOrderLine/Status/Code or just StatusCode. No explicit way is available to indicate whether the ElementPath contains a code or an Xpath expression.

  • Value element that contains the value assigned to the ElementPath, for example, Approved.

  • A queryOperatorCode attribute that specifies the operator applicable to the Value assigned to the ElementPath. The possible operators are EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_EQUALS, LESS_THAN, LESS_THAN_EQUALS, CONTAINS, DOES_NOT_CONTAIN, LIKE, NOT_LIKE, LIKE_IGNORE_CASE, NOT_LIKE_IGNORE_CASE, IS_BLANK, IS_NOT_BLANK, BETWEEN, NOT_BETWEEN, IN, NOT_IN

• SortElement (0 or more instances):

  Each QueryCriteria can have one or more SortElements defined, as shown in Example 7-4. A SortElement is used to request the Query result set to be sorted using the criteria specified in the SortElement. Each SortElement has an optional sortDirectionCode attribute that identifies the order of sorting-ASC (ascending) or DESC (descending).

  In Example 7-4, the result set of the QueryExpression is to be sorted in descending order of OrderDateTime and ascending order of Description.

  If multiple QueryCriteria exist, then each can have its own SortElement, as shown in Example 7-5. The result set of one QueryCriteria is sorted, and then after the next QueryCriteria filter is applied, the resultant subset is sorted using the SortElement specified for that QueryCriteria.

  In Example 7-5, the SalesOrder root query is sorted by OrderDateTime and Description, while the child node SalesOrderLine is sorted by price.

QueryCriteria Examples

Example

Query with a Single QueryCriteria Element and Single Query Expression

Example 7-3 is an example of a query with a single QueryCriteria element and a single QueryExpression element that contains only ValueExpression elements. The query to be run is Query SalesOrder, in which "SalesOrder/CurrencyCode = "USD" AND "SalesOrder/OrderDateTime = "2003-12-04". The query expression is defined for the root node; hence, the QualifiedElementPath is not present (optional).

This is modeled as two ValueExpressions nested within a QueryExpression. The logicalOperatorCode on the QueryExpression indicates the operation (AND) to be performed across the two ValueExpressions.

Query with a Single QueryCriteria and Nested QueryExpressions

Figure 7-13 is an example of a Query with a single QueryCriteria but with nested QueryExpressions. The query to be run is Query SalesOrders, in which SalesOrder/CurrencyCode=USD AND SalesOrder/OrderDateTime<2003-12-04 OR SalesOrder/Description CONTAINS "BMW 520i". Both the query expressions are defined for the root node; hence, the QualifiedElementPath is not present (optional).

Note: When nested QueryExpressions exist, they are all on the same QualifiedElementPath.

This is modeled as two QueryExpressions nested within an outer QueryExpression.

The outer QueryExpression identifies the operand to be applied to the two inner QueryExpressions (OR). The ValueExpressions contain the actual query data with the query operator to be applied to the data element as shown in Figure 7-13.

Figure 7-13 Example of Query with Nested Query Expressions

Query with Multiple QueryCriteria

Example 7-6 is an example of a Query with multiple QueryCriteria. When multiple QueryCriteria exist, no logical operation is present that is applicable across them-they are the equivalent of running the query specified in the first QueryCriteria element, then applying the second QueryCriteria to the result of the first.

The query to be executed is: Query CustomerParty where Type = GOLD and filter the result set to only accounts whose status is "ACTIVE".

This is implemented as two QueryCriteria. The first is to query the CustomerParty and retrieve all Customers of TYPE-"GOLD". This query is run on the CustomerParty root node.

The result set of this query is then filtered by applying the second Query Criteria. This queries the CustomerParty/Account node to get all CustomerParty Accounts that have STATUS = "ACTIVE".

ResponseFilter (0 to 1 instance)

The ResponseFilter enables a requester to indicate which child nodes he or she is interested or not interested in. The excluded child nodes are not populated by the application when the response to the query is being built. If supported by participating applications, this feature improves performance by not querying the nodes that are excluded from the query.

Example

Request for Single Return to QueryInvoice Message

Example 7-7 illustrates requesting only the InvoiceLine to be returned in response to a QueryInvoice message.

Request for Specific Message Return to QueryInvoice Message

Example 7-8 is an example of returning all QueryInvoice message content except for Charge and PaymentTerm.

Tip:

In the absence of a very comprehensive framework for processing queries, this option is difficult to implement practically, because in theory infinite ways are available by which the query can be built, and the service provider would not be able to process all possible ways in which the QueryCriteria is specified.

Content Payload

No content payload for a List Query is available-the query is defined entirely within the Verb element of the DataArea.

Verb Attributes

• getAllTranslationsIndicator(optional):

  A Query can have an optional getAllTranslationsIndicator to indicate whether the service provider is expected to provide all translations to be populated in the response for all translatable elements. The default is to bring back data in the language of the request only.

• recordSetStart(optional):

  This is an instruction to the query service provider to return a subset of records from a query result set, with the index of the first record being the number specified in this attribute.

  As an example, consider a query that returns 200 records in the result set. The requester can invoke the query with a recordSetStart parameter set to "101", in which case the service provider is expected to process this value and build a result set that contains the 101st to the 200th record of the result set.

• recordSetCount(optional):

  The presence of this attribute is an instruction to the service provider to return the same attribute with the count of the number of records in the response to the Query. Absence of this attribute indicates that a record set count is not expected in the response to the query.

• maxItems(optional):

  This is an instruction to the query service provider that the maximum number of records returned in the query response should not exceed the value specified for this attribute.

  The result set of a query may result in multiple records that meet the query criteria, but the query service Requester may be able to process only a specific number of records at a time. For example, a query might result in a result set of a 1000 records, but the query Requester can process only 100 records at a time. The service Requester can use the maxItems attribute to instruct the service provider to return only 100 records in the response.

Corresponding Response Verb

The Query Verb has a paired QueryResponse verb that is used in the response message for each Query EBM.

Response Verb Payload

The payload of the response verb is typically the entire business object.

<QueryAccountBalanceAdjustmentEBM>
<corecom:EBMHeader>
        
   </corecom:EBMHeader>
   <DataArea>
         <Query>
         </Query>
         <QueryAccountBalanceAdjustment>
               <corecom:Identification>
                     <corecom:ID>1005</corecom:ID>

               </corecom:Identification>
               <Custom/>
         </QueryAccountBalanceAdjustment>
   </DataArea>
</QueryAccountBalanceAdjustmentEBM>

<Query>
<QueryCriteria>
         <QueryExpression logicalOperatorCode="AND">
               <ValueExpression queryOperatorCode="EQUALS">
                     <ElementPath>/SalesOrderBase/CurrencyCode</ElementPath>
                     <Value>USD</Value>
               </ValueExpression>
               <ValueExpression queryOperatorCode="GREATER_THAN_EQUALS">
                     <ElementPath>/SalesOrderBase/OrderDateTime</ElementPath>
                     <Value>2003-12-04</Value>
               </ValueExpression>
         </QueryExpression>
   </QueryCriteria>
</Query>

<QueryCriteria>
<QueryExpression>
         <ValueExpression>
              
         </ValueExpression>     
   </QueryExpression>           
   <SortElement sortDirection="DESC">/OrderDateTime</SortElement>
   <SortElement sortDirection="ASC">/Description</SortElement>
</QueryCriteria>

<QueryCriteria>
<QueryExpression>
         <ValueExpression>
              
         </ValueExpression>     
   </QueryExpression>           
   <SortElement sortDirection="DESC">/OrderDateTime</SortElement>
   <SortElement sortDirection="ASC">/Description</SortElement>
</QueryCriteria>
<QueryCriteria>
   <QualifiedElementPath>/SalesOrderLine/SalesOrderLineBase</QualifiedElementPath>
   <QueryExpression>
   ...
   </QueryExpression>
   <SortElement>/SalesOrderLine/SalesOrderLineBase/ListPrice</SortElement>
</QueryCriteria>

<Query>
<QueryCriteria>
         <QueryExpression>
               <ValueExpression queryOperatorCode="EQUALS">
                     <ElementPath>/Type</ElementPath>
                     <Value>GOLD</Value>
               </ValueExpression>
         </QueryExpression>
         <SortElement>/LastName</SortElement>
   </QueryCriteria>
   <QueryCriteria>
         <QualifiedElementPath>/CustomerAccount</QualifiedElementPath>
         <QueryExpression>
               <ValueExpression queryOperatorCode="EQUALS">
                     <ElementPath>/CustomerAccount/Status/Code</ElementPath>
                     <Value>ACTIVE</Value>
               </ValueExpression>
         </QueryExpression>
   </QueryCriteria>
</Query>

<Query>
<QueryCriteria>

   </QueryCriteria>
         <ResponseFilter>
               <ChildComponentPath>InvoiceLine</ChildComponentPath>
         </ResponseFilter>
</Query>

<Query>
<QueryCriteria>

   </QueryCriteria>
   <ResponseFilter>
         <ExclusionIndicator>true</ExclusionIndicator>
         <ElementPath>Charge</ElementPath>
         <ElementPath>PaymentTerm</ElementPath>
   </ResponseFilter>
</Query>

For the inbound interactions of applications with the ABCS:

1. Start with identifying the participating applications.

2. Analyze the integration capabilities of each participating application.

3. Work with the application providers (developers) to decide the best way to interact with the application to achieve the needed functionality.

   The interaction mechanism can be one of the following:

   • SOAP WebService

   • Events/Queues

   • JCA

4. Obtain relevant details from the applications in situations in which the interactions between the participating applications and the ABCS happen through a message queue adapter or a JCA Adapter.

   These details are used in configuring the adapters. The configuration results in the WSDL creation. Care must be taken to ensure that the environment-specific details are configured in relevant resource files on the server and not directly in the WSDLs.

When the Requester ABCS is invoked by the transport adapters, the interaction between ABCS and the transport adapters is using either SOAP Web Service or native binding.

More details are specified in Interfacing with Transport Adapters.

The details on establishing the inbound connectivity between adapters and the ABCS are given in Establishing Resource Connectivity.

An EBS invokes:

• A provider ABCS, which implements an EBS operation. This is true because an EBS provides the mediation between the requesting services and providing services.

• A requester ABCS to send the response to it. In scenarios in which a requesting service is waiting for a delayed response, the delayed response from the providing service can be routed by a Response EBS to the waiting Requester ABCS.