5Customizing an Application Services Interface
Customizing an Application Services Interface
This chapter describes the ASI framework, extending existing ASIs, and building your own interfaces. Also included is an in-depth description of how to customize your workflows to use ASIs. Topics include:
About ASI Framework
As defined in Defining ASIs, an ASI is a release-independent interface published by Oracle in a standard metadata format and built using the ASI Framework.
The ASI Framework provides the technology in which ASIs are implemented. You can use this framework to extend existing ASIs or to define your own Web service and proxies in a Siebel application for externally defined services. Other interfaces can be built using the ASI Framework, but are not considered to be ASIs. Only Siebel prebuilt ASIs are supported across releases.
Extending an ASI
The following procedure describes extending an existing Siebel ASI to meet specific business needs.
To extend an ASI
Identify the integration objects to modify—the internal integration object and the interface integration object.
Open Siebel Tools, select the internal integration object, and add the required components and fields.
Select the interface integration object and add the required components and fields, matching the component and field names from the internal integration object.
Choose the Tools menu and select Validate Object to check the definition of the integration objects.
Redeploy the project into a Repository, and replace the Repository on the application server with the new Repository.
Open the Siebel Client, select the Administration - Integration menu, choose the Data Maps screen, query for the data map, and click Auto-Map if an explicit map exists for this service.
Clicking Auto-Map automatically creates an explicit map for the newly added components and fields to the ASI. Auto-Map maps the matching root components, fields, and child components between the integration objects, if the names are the same and no current mapping exists. For more information about the Auto-Map feature, see Automatic Mapping for Integration Objects.
Click Validate in the Data Map screen to check any changes to the data map before testing.
If you are using a data map for the ASI, make sure you purge the Data Map cache to remove any traces of the current data map and enable the correct data map to be used.
Caution: Purge the data map only during the development and testing phases of the ASI.Note: To purge the Data Map cache, you need to define a workflow under Business Process Administration. For more information about creating this workflow, see Business Processes and Rules: Siebel Enterprise Application Integration.Test the ASI to make sure it is accurate and correct.
For instructions about defining your own Web service and proxies in a Siebel application for externally defined services, see Integration Platform Technologies: Siebel Enterprise Application Integration.
Customizing Workflows to Use ASIs
Workflows can invoke some ASIs for their processes. You can customize workflows to use the ASIs in the individual Siebel applications. In the scenario described in Customized Workflow Example, the image illustrates a workflow to Synchronize Account, invoking different ASI methods, QuerybyID and Synchronize.
Customized Workflow Example
A customer using an external application needs to update an account within the Siebel database. The following scenario demonstrates how this customized workflow operates.
In the scenario illustrated in the following image, the object ID is used to query for the account being sent. The QueryById method returns the account, which is stored in the SiebelMessage property. The account information is passed to the External Account Proxy, which sends the account information to the external system through Web services. The external system synchronizes the information and returns any new account information. The Synchronize method takes that new account information and synchronizes the information on the internal system.
The QueryById method contains the method arguments shown in the following table.
Table Query By Id Method Arguments
| Name | Display Name | Integration Object | Data Type | Type | Storage Type |
|---|---|---|---|---|---|
PrimaryRowID |
ID |
None |
String |
Input |
Property |
SiebelMessage |
Account Interface |
Account Interface |
Integration Object |
Output |
Hierarchy |
The Synchronize method contains the method argument shown in the following table.
Table Synchronize Method Argument
| Name | Display Name | Integration Object | Data Type | Type | Storage Type |
|---|---|---|---|---|---|
SiebelMessage |
Account Interface |
Account Interface |
Integration Object |
Input/Output |
Hierarchy |
In this example, an interface integration object with the name Account Interface is created to define the external representation of the account. An internal integration object with the name Internal Account Interface is created to describe the structure of the Account business object.
The workflow process properties are used to store data in the workflow. The Object ID property (data type String) is included in each workflow by default. Account Message (data type Integration Object) is defined to store the output of the Query by Account ID step.
The Query by Account step calls the QueryById method of the Siebel Account data synchronization service. The process property Object ID is passed as an input argument. Account Interface is passed as an output argument to the process property Account Message. The External Account Proxy step calls the Synchronize method of the External Account outbound ASI. For the input argument, the process property, Account Message, is passed to the input argument, Account Interface. For the output argument, the method output argument, Account Interface, is passed to the process property, Account Message.
The following table shows the input arguments.
Table Input Arguments
| Input Argument | Type | Property Name | Property Data Type |
|---|---|---|---|
ID |
Process Property |
Object ID |
String |
Account Interface |
Process Property |
Account Message |
Integration Object |
The following table shows the output argument.
Table Output Argument
| Property Name | Type | Output Argument |
|---|---|---|
Account Message |
Output Argument |
Account Interface |
Building Customized Interfaces Using the ASI Framework
You can build your own interfaces using the ASI Framework.
To define an inbound interface
Determine the schema and fields of the integration objects based on your business needs.
Open Siebel Tools, create the internal integration object using the Integration Object Wizard, and deactivate the components and fields that are not required.
Note: Deleting fields is not recommended. For more information about creating integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration.Create the interface integration object in Siebel Tools using one of the following methods:
Copy the internal integration object, if the internal and interface objects are the same.
Use the DTD or XML schema wizard. For more information about using the XML schema wizard, see Integration Platform Technologies: Siebel Enterprise Application Integration.
Create the object manually.
Deactivate the components and fields that are not required.
Deleting fields is not recommended.
Choose the Tools menu and select Validate Object to check the definition of the integration objects.
Deploy the Repository, and import it to the Siebel Server.
Open Siebel Client, select the Administration - Integration menu, and select the Data Maps screen.
Note: Do not create an explicit data map if an object is a subset of another or if the objects are the same. The data synchronization service automatically maps the subsets if the root integration components have the same name.Open the Integration Administration menu and choose the Data Map editor to create an explicit data map if the two objects contain different component or field names.
A map is required for each direction:
From Interface Object to Internal Object
From Internal Object to Interface Object
Click Validate in the Data Map editor to check the data map changes before testing.
Open Siebel Tools, define the business service, and set the class property to CSSEAIDataSyncService.
Within the business service:
Define the methods needed for this service. See Data Synchronization Methods for ASIs for more details.
Define the Business Service User Properties to configure the internal object and the data map names. See Business Service User Properties for ASIs for more details.
Redeploy the projects with the integration objects and business services definition into the Repository.
Open Siebel Client, select the Administration - Web Services menu, and choose the Inbound Web Services screen. Create an entry if the inbound interface is to be made available as a Web service.
To create an outbound interface, you must publish it as a Web service to use it externally.
To define an external interface
Open Siebel Tools and define the integration objects manually or by using the Integration Object Wizard.
Deactivate components and fields that are not required.
Deleting fields is not recommended.
Create interface integration objects manually by copying and changing the internal object, or by importing an XML DTD.
Note: Skip to Step 5 of this procedure if a WSDL file exists for the internal interface. You can run the WSDL Wizard to automatically import the information that is created manually in Step 3 through Step 5 of this procedure. If a WSDL file does not exist, complete Step 2 through Step 4 of this procedure. For more information about using the WSDL Wizard, see Integration Platform Technologies: Siebel Enterprise Application Integration.Open Siebel Tools and define the business service to describe the interface to the ASI, including all methods and parameters for each method.
This business service references the integration objects created in the preceding step in this procedure.
Set the business service’s class to CSSWSOutboundDispatcher.
Set the parameters on methods to type Integration Object and refer to the specified interface object.
Define the Business Service User Properties in Siebel Tools:
Choose a name for the default service, siebel_web_service_name.
Choose the properties for the default port, siebel_port_name.
Register the name on the business service as a user property, and define the service and port name as the proxy’s default service name, siebel_web_service_namespace.
Note: The user property, ApplicationServicesInterface, is set to Y for each ASI Business Service. You can use it for visual identification to differentiate this business service from other business services. The user property has no functional implication.Open Siebel Client, choose the Outbound Web Services screen, and select a name for the default service. Configure the following properties:
Port types are all the published proxy business services used to define the outbound ASI interface. The port name is the business service you created in Siebel Tools earlier in this procedure.
Transports describe the transport type for your particular platform and system. For more information, see Exposing ASIs with Interface Technologies.
Protocols describes the formatting of the integration object being sent. For more information, see Protocols Used with ASIs.
Address is the physical location of the touchpoint files.
Redeploy the projects with the integration objects and business services definition into the Repository.
Define an entry for the outbound ASI in the Outbound Services Administration View.
The port type should reference the business service created for the outbound ASI. The name of the business service and port must match the default names set on the business services definition.
To define the data map
An inbound and outbound data map need to be created for each interface. In Siebel Client, use the Data Maps view under the Administration - Integration menu to create a new data map for new or customized integration objects. See Data Mapping for ASI Release Independence for more information about data mapping.
For more information about creating a data map for the ASI, see Business Processes and Rules: Siebel Enterprise Application Integration.
User Scenarios for ASIs
The Siebel prebuilt ASIs might not be sufficient, depending on your business needs. You can extend existing ASIs for further customization, or you can create new interfaces using the ASI Framework. The following scenarios describe an integration developer who needs to customize the interface to reflect her company’s business needs, rules, and processes. The key activities in these scenarios are:
Extending an ASI
At the ABC company, Jane needs to extend an existing ASI by adding a new field, LifeTimeValue, to the business component, Account, and expose the new field in the ASI, Siebel Account, which uses data synchronization services.
To accomplish these tasks, Jane must:
Create the new field, LifeTimeValue, in the Account business component using Siebel Tools.
Add LifeTimeValue to Account’s internal integration object using Siebel Tools.
Add LifeTimeValue to Account’s interface integration object using Siebel Tools. She must make sure that the two fields in the internal and interface integration objects have matching names.
Redeploy the integration objects and project into a Repository, and test the new ASI.
Use the Auto-Map function in the Siebel Data Mapper to automatically map the new field in the internal integration object to the new field in the interface integration object.
After completing these tasks, the new field is available to the business component, Account, and all ASIs based on it, including Siebel Account.
Defining an Outbound ASI
Jane needs to define an outbound ASI for her company, ABC Company, that submits an order to a back-office system using data synchronization services. She calls the ExternalOrder ASI.
To create this ASI, Jane must do the following in Siebel Tools:
Create an internal integration object, ExternalOrder Internal, with the necessary components and fields based on ABC Company’s business needs.
Create an interface integration object, ExternalOrder Interface, with the same components and field names as the ExternalOrder Internal integration object. Because both integration objects have the same component and field names, Jane does not need to create a data map, because she uses the data synchronization service’s implicit mapping function.
Define a new Business Service, named ExternalOrder, as an outbound ASI, by specifying CSSWSOutboundDispatcher as Class.
Define all the methods used by this ASI.
For each method, create the method argument parameters as Integration Object, String, Hierarchy, Number, or Date, and specify the Type as input or output.
Specify the implementation for the ASI by setting the Business Service User Properties, because she does not have a current WSDL template to import. Consequently, Jane must create the following Business Service User Properties:
Business Service User Property Value siebel_web_service_namespace
ExternalOrder
siebel_web_services_name
ExternalOrder
siebel_port_name
Default
Deploy all integration objects and business services into a Repository for the Siebel Server.
In the Siebel Client, navigate to the Administration - Web Services screen, and then Outbound Web Services.
Define a new outbound ASI called ExternalOrder, provide a namespace, and make it Active.
For the outbound ASI, create the Service Port External Order and reference it to the External Order that was created and deployed in Siebel Tools.
Select the correct transport, WSDL address, and binding.
Under Operations, list the methods needed for this ASI. The new ExternalOrder ASI is created and ready to use.