Application Services Interfaces

This chapter describes the underlying structure of an Application Services Interface (ASI) and the specialized types of ASIs used by business services. It also explains the relationship between ASIs, EAI, and Web services, as well as authentication and security issues. Topics include the following:

About ASI Structure

As defined earlier, an ASI is an interface whose implementation is defined by a business service or workflow. A specialized class of business services is implemented as data synchronization services.

The following image shows an example of the structure of the Account ASI. For information regarding specific ASIs, see Predefined Application Service Interfaces and Siebel Communications, Media, and Energy ASIs

About Integration Object Structure

Integration objects are metadata structures that represent hierarchical objects using components and fields. For example, the Contact integration object might have the following components—Personal Address, Account, and Opportunity. The following image shows a sample of the Contact integration object, and the integration object instance containing the data for Contact. The structure of integration objects includes:

For data synchronization services, there are two types of integration objects. For more information about data synchronization services, see ASI Data Synchronization Services.

For more information about integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Integration Object and Integration Object Instance

Components and Fields in Integration Objects

Components define the hierarchy of an integration object, and a component contains one or more fields and child components. In the image shown in About Integration Object Structure, the Contact integration object has these components: Contact_Personal Address, Contact_Account, and Contact_Opportunity; Personal Address has the additional fields, PersonalAddressState and PersonalAddressZip.

By default, all fields are active. However, you can deactivate these fields to satisfy the different requirements for each ASI and to increase performance of the ASI. For more information about deactivating field components, see Deactivating ASI Components and Fields.

List of Value Fields in Integration Objects

Fields can map to a Siebel predefined List of Values (LOV). The fields in the integration components that are based on such fields can take values only from that list—the fields are bound to the values of that LOV. For example, in the image shown in About Integration Object Structure, PersonalAddressState can map to an LOV of the different states in the U.S. (such as AZ, CA, FL, and so on).

These LOV fields should use a language-independent representation. For each LOV field, the internal integration object returns a Language Independent Code (LIC) if the user property, AllLangIndependentVals, is set to Y at the object level.

The integration object can expose the Siebel LIC or map the field to an industry standard code.

Related Business Component Selection in Database Updates

When a row is inserted or updated in the Siebel database, it is often necessary to create relationships with other business components through a foreign key. For example, an account has a many-to-one relationship with Price List—an account is associated with one price list; the same price list can be used with different accounts. The correct price list is identified by the foreign key Price List Id, which exists in the Account component. This relationship is implemented through the picklist.

For this type of integration, a pointer to the appropriate price list row is stored in the account row, where it is identified by a foreign key.

Unique Keys in Integration Objects

Internal integration objects implement user keys that the Siebel application creates for each component, based on the user primary key defined for the underlying table. User keys are a group of fields whose values uniquely identify only one Siebel record. When an ASI executes, it searches the list of user keys to find the first key present in the component instance and uses it to determine whether the record has a match in the Siebel database.

You can deactivate, modify, or create additional keys for an ASI depending on your business and application needs. However, it is recommended that each component contain a set of three unique keys:

Row ID. The Siebel Row ID.
Integration ID. A cross-reference that links the Siebel application to the corresponding record in the external application.
User Key. Corresponds to the U1 index of the underlying table.

ASI Data Synchronization Services

A data synchronization service is a specialized type of business service used by a class of ASIs. Data synchronization services import and export data from Siebel applications and are based on the framework provided by the EAI Siebel adapter. For more information about the EAI Siebel adapter, see Integration Platform Technologies: Siebel Enterprise Application Integration. The components of a data synchronization service include:

Many inbound ASIs are built using data synchronization services, and can also be used to populate the parameters of an outbound ASI. The inbound ASI isolates the interface of the outbound ASI and provides an interface that is independent from the data model by isolating the underlying data model through the use of a data map.

Note: Data mapping cannot be specified for outbound ASIs using the internal integration object and data map business service user properties. These user properties are only for use by the data synchronization business service.

Data synchronization services use a pair of integration objects—the internal integration object and the interface integration object—that define the schema of the release-independent interface. Both objects must be provided, even if they are exactly the same, for the ASI to be upgraded at a later date. An internal integration object mirrors the schema of the Siebel business object, while an interface integration object defines the external representation of the data.

The following image illustrates these concepts.

Component and field names of the internal integration object must match the names of the underlying Siebel business object’s components and fields. The interface integration object’s components and fields do not need to match; you determine them based on your business requirements.

Data Mapping for ASI Release Independence

Within data synchronization, a data map translates the data in the form of integration objects between an internal integration object and an interface integration object, making ASIs release-independent.

Data synchronization services use data mapping to translate data between integration objects and support a subset of methods that are used by the EAI Siebel adapter, such as Insert, Update, and Delete. See Data Synchronization Methods for ASIs for more information. An ASI usually requires two types of data maps—one for each direction, as shown in the following image. For more information about data mapping, see Business Processes and Rules: Siebel Enterprise Application Integration.

For ASIs using data synchronization services, there are two types of data mapping—implicit data mapping and explicit data mapping.

Implicit Data Mapping for Integration Objects

Data synchronization services support implicit data mapping when the internal integration object is a subset or exactly the same as the interface integration object; the reverse also holds true. Implicit mapping occurs when:

A source component maps to a target component with the same name.
A source component maps to a target component and both components have fields with the same name.
Data synchronization service does not specific a data map.

Every component, field, and child component is mapped between integration objects.

The following image shows an example of implicit mapping between two integration objects. In this diagram, components and fields with the same name are automatically mapped; data synchronization services map these fields when a data map is not specified.

In the image, the child component, Organization, which appears on the interface integration object only, is not mapped because it is not considered important to the ASI. Consequently, the two integration objects are sufficiently similar, and a data map is not necessary. Implicit mapping ignores any components and fields unique only to the interface or internal integration object, but not both.

Note: Implicit data mapping requires that the root components of the internal and interface integration objects have the same name.

Explicit Data Mapping for Integration Objects

You must define an explicit data map whenever a component or field name of an interface integration object does not exactly match the component or field name of the internal interface object.

Oracle provides prebuilt explicit data maps for its ASIs. These data maps make sure that the ASIs are release-independent.

Note: To preserve the release-independent properties of fields, do not alter Siebel-defined explicit data maps except when you deactivate fields.

Automatic Mapping for Integration Objects

You can automatically extend a data map for an integration object whenever new components and fields have been added to an existing ASI. Within the Data Map Administration screen, the Auto-Map feature enables you to automatically create submaps for these new components and fields. The Auto-Map feature checks the definition of the internal integration object and the interface integration object, finds components and fields of the same name with no current map, and creates the data map for it.

You can use automatic mapping and explicit mapping together.

Upgrading Data Maps for Integration Objects

When the Siebel application is upgraded, a three-way merge is performed on the internal and interface integration objects. This merge makes sure that the customer's extensions to these objects carry forward to the new version.

If an explicit data map exists in the previous version of the ASI, a new version of the map replaces the old with the Siebel application upgrade. Any automatic mapping is regenerated. The automatic mapping exposes the customer's extensions through the new version of the interface.

Data Synchronization Methods for ASIs

Data synchronization services use a subset of methods supported by the EAI Siebel Adapter, as listed in the following table. However, an ASI might not use all of the methods listed; you can define which methods an ASI uses. For more information, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Table Data Synchronization Methods

Method	Description	Input	Output
QueryByExample	Queries for objects based on the example object provided.	Interface Integration Object	One or more integration objects that matches the query.
QueryById	Queries for objects based on the primary row ID.	Primary Row ID	An integration object that matches the specific row ID. If no row ID exists, no object is returned.
QueryPage	Queries for a given number of objects based on the example object.	Interface Integration Object PageSize StartRowNum ViewMode	One or more integration objects up to <pagesize> number of integration objects that match the query. Boolean LastPage argument indicates whether the last record is returned.
Insert	Creates the object in the database.	Interface Integration Object	The status key of all the objects created. If the object exists, this request errors out. See Using Status Keys for information about status keys.
Update	Updates the object in the database. If the object does not exist, the request returns an error.	Interface Integration Object	The status key of all objects updated.
InsertOrUpdate	Merges the object with the same object in the database or creates a new object if none exists in the database.	Interface Integration Object	The status key of all objects created or updated.
Synchronize	Synchronizes the database object to exactly match the input object.	Interface Integration Object	The status key of all objects created or updated.
Delete	Deletes the object.	Interface Integration Object	The status key of all objects deleted.

Data Synchronization Input Method Arguments for ASIs

The following table describes the arguments of the various methods. For more information about the input arguments, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Table Input Method Arguments

Argument	Display Name	Type	DataType	Description
Interface Integration Object	None	Input/Output	Integration Object	The integration object or set of integration objects that is either passed to or returned to the method. The name of the method argument can be anything, but you should use SiebelMessage if the ASI is to be used in a workflow process with other EAI services. The integration object attribute must specify the name of the interface integration object.
LastPage	Last Page	Output	Boolean	Indicates whether the last record has been returned by the QueryById method.
PageSize	Page Size	Input	Number	The default is 10. This argument indicates the number of records to be returned for the QueryPage method.
PrimaryRowID	Object ID	Input	String	The ID that corresponds to the Siebel business component row ID for the primary integration component. This argument is only applicable to the QueryById method.
StartRowNum	Starting Row Number	Input	Number	The default is 0. The row number to start retrieving records for the QueryPage method.
RowID IntegrationId UserKey	None	Output	Status key	See the Using Status Keys section of this topic for more information about this output argument.
ViewMode	None	Input	String	Specifies the visibility mode applied to the parent integration object. Applicable only to the QueryPage method.

Using Status Keys

A status key is an integration component key of the type Status key. Status keys are similar to unique keys (see Unique Keys in Integration Objects), and need to be defined for the output arguments. It is recommended that each component contain a set of these three unique keys:

Row ID. The Siebel Row ID.
Integration ID. A cross-reference that links the Siebel application to the corresponding record in the external application.
User Key. Corresponds to the U1 index of the underlying table.

For more information about status keys, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Handling Error Messages

If a method cannot find the integration object as specified by the method arguments, a SiebelMessage returns containing an empty list of integration objects.

However, if an error occurs during the execution of a method:

The Business Service returns an error.
A SOAP message is returned if the method is invoked as a Web service. See Handling Errors for ASIs for more information about Web services error messages.

Business Service User Properties for ASIs

User properties, as listed in the following table, control the behavior of an ASI. These values become input arguments to the service that invokes the ASI.

For example, an ASI using the Synchronize method can specify that an input data map for Synchronize is used—for example, Input Data Map (Synchronize). If Input Data Map (Synchronize) is not specified, the default data map, Input Data Map, is used instead. If a default data map is not specified, implicit mapping is used.

For more information about Business Service User Properties, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Table Business Service User Properties

Argument	Required	Description
Internal Integration Object	Yes	Name of the integration object defining the business object to expose.
Input Data Map	No	Name of the default data map for the input arguments. If no map or method is specified, implicit mapping occurs between the internal and input interface objects.
Output Data Map	No	Name of the default data map for the output arguments. If no map and method are specified, implicit mapping occurs between the internal and output interface objects.
Input Data Map (name of method)	No	Name of the data map for the input arguments for the specified method—for example, Input Data Map (Synchronize).
Output Data Map (name of method)	No	Name of the data map for the output arguments for the specified method—for example, Output Data Map (Update).

XML Method Example

The following XML example demonstrates an upsert-and-delete operation:

<SiebelMessage MessageId="" MessageType="Integration Object" IntObjectName="Sample 
Account">

<ListofSampleAccount>
   <Account operation="upsert">
        <Name>A. K. Parker Distribution</Name>
        <Location>HQ-Distribution</Location>
        <Organization>North American Organization</Organization>
        <Division/>

        <CurrencyCode>USD</CurrencyCode>

        <Description>This is the key account in the AK Parker
               Family</Description>

         <HomePage>www.parker.com</HomePage>

         <LineofBusiness>Manufacturing</LineofBusiness>

        <ListOfContact>
           <Contact operation="delete">
                <FirstName>Stan</FirstName>
                <JobTitle>Senior Mgr of MIS</JobTitle>
                <LastName>Graner</LastName>
                <MiddleName>A</MiddleName>
                <PersonalContact>N</PersonalContact>
                <Account>A. K. Parker Distribution</Account>
             <AccountLocation>HQ-Distribution</AccountLocation>
           </Contact>
        </ListOfContact>

     </Account>
   </ListofSampleAccount>

</SiebelMessage>

Exposing ASIs with Interface Technologies

ASIs can be exposed through any of Siebel's interface technologies, which includes the Web Services Framework as well as the broader EAI Framework. The Web Services Framework supports Web service-related standards, including SOAP, WSDL, and XML Schema. You can use the broader EAI Framework for more flexibility in XML formatting and in choice of transport.

ASIs use supported transport technologies including HTTP, MQSeries from IBM, and MSMQ from Microsoft. For more information about XML processing, see XML Reference: Siebel Enterprise Application Integration. For more information about transports, see Transports and Interfaces: Siebel Enterprise Application Integration.

About ASIs and Web Services

Web services can make ASIs externally available by using information protocols (such as HTTP) and data formats (such as XML), and other communication protocols, such as SOAP, Universal Description Discovery and Integration (UDDI), and WSDL. Because ASIs are business services, ASIs can be exposed externally as Web services. However, while ASIs can be published as Web services, not all Web services are ASIs.

For more information about Web services and how to use them, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Topics in this section include:

Protocols Used with ASIs

ASIs support the standard XML envelope for Web services and SOAP. Siebel applications support two types of SOAP protocols—SOAP-Remote Call Procedure (RPC) and SOAP-DOC. If an inbound ASI supports an industry standard other than the protocols that Oracle supports, the ASI cannot be defined as an inbound Web service. The ASI must be defined and supported through the existing EAI framework.

The following table lists the various types of transport and protocols available. The Null Protocol implements a loopback—a call back into the Siebel servers. Any method arguments passed using the Null Protocol or that are not directly specified are forwarded to the local business service or local workflow. When testing an ASI, you can use the File protocol.

Table Protocols

Transport	SOAP-RPC	SOAP-DOC	Null
HTTP	Inbound/Outbound	Inbound/Outbound	Not Applicable
MQ	Inbound/Outbound	Outbound	Not Applicable
MSMQ	Inbound/Outbound	Outbound	Not Applicable
Local Business Service	Inbound/Outbound	Not Applicable	Not Applicable
Local Web Service	Outbound	Outbound	Outbound
Local Workflow	Outbound	Outbound	Outbound
File	Outbound	Outbound	Outbound

Handling Errors for ASIs

The SOAP fault message returns any errors for inbound and outbound ASIs.

Errors for Inbound ASIs

The SOAP fault block returns any inbound error messages, as defined by the SOAP 1.1 specification. The faultcode contains either a Client or Server value, and the faultstring contains a description of the error. The error message <siebel:errormsg> details the problems with the request. The information in the SOAP fault block can be extracted and displayed to the user.

The following XML shows an example of a fault message.

<?xml version="1.0" encoding="UTF-8" ?> 
<?Siebel-Property-Set EscapeNames="false"?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> 

<SOAP-ENV:Body> 

   <SOAP-ENV:Fault xmlns:siebelf="http://www.oracle.com/ws/fault"> 

      <faultcode>Client</faultcode> 

      <faultstring>
        Supplied input is not well formed or does not contain the 
        expected data.
      </faultstring> 

   <detail> 
      <siebelf:errorstack> 
        <siebelf:error> 
        <siebelf:errorsymbol /> 

        <siebelf:errormsg>Supplied input is not well formed 
              or does not contain the expected data.
        </siebelf:errormsg> 

        </siebelf:error> 

        <siebelf:error>
        <siebelf:errorsymbol>
              IDS_XMLCNV_ERR_EMPTYMSG
        </siebelf:errorsymbol> 

        <siebelf:errormsg>XML Hierarchy Converter error - empty
           input message, expecting an XML document in <Value> of
           input arguments
        </siebelf:errormsg> 

        </siebelf:error> 

      </siebelf:errorstack> 
   </detail> 
</SOAP-ENV:Fault> 
</SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

Errors for Outbound ASIs

If an error occurs during an outbound ASI that has been exposed as a Web service, the business service raises the error and returns the SOAP fault message as the output method argument, soap:fault, for the application to process. The error is represented as an XML hierarchy property set.

Authentication and Security for ASIs

The authentication and security for ASIs depend on the underlying transport used to access the ASI and standard Siebel login logic. HTTP enables the authentication of individual Siebel users, while the MQ Series and MSMQ rely on the operating system’s level of security of the underlying transport.

For more information about authentication and security, see the Siebel Security Guide.

Note: The Siebel Bookshelf is available on Oracle Technology Network (OTN) and Oracle Software Delivery Cloud. It might also be installed locally on your intranet or on a network location.