Integrating Order Management with Oracle ATG Web Commerce

This chapter describes how to integrate Siebel Business Applications with Oracle ATG Web Commerce. It includes the following topics:

About Integrating Siebel Business Applications with Oracle ATG Web Commerce

Siebel Business Applications have special features for offline or assisted channels, such as contact centers and partners, which enable you to manage core business data, such as customers and products, and to integrate presales and postsales processes.

Oracle ATG Web Commerce has special features for online channels, such as Web stores, mobile devices, and kiosks. These features provide the performance, flexibility, and customer experience that are required for online channels.

Integrating Siebel Business Applications with Oracle ATG Web Commerce provides the following benefits:

Provides a combined solution that gives you a unified view of the customer and enables you to work on all channels.
Enables you to harness the full power of each application.
Enables you to integrate all objects in the Siebel product catalog entities with ATG Web Commerce, while supporting the full, life-cycle requirements of these entities

For more information about integrating Siebel Business Applications with Oracle ATG Web Commerce, see 1358285.1 (Article ID) on My Oracle Support, Siebel ATG Implementation Guide.

Architecture of the Integration of Siebel Business Applications with Oracle ATG Web Commerce

The following figure shows the overall architecture of the integration of Siebel Business Applications with Oracle ATG Web Commerce.

The important elements of this architecture include:

ATG Integration Layer. For more information, see ATG Web Commerce and Siebel Reference Integration, document Id 1358285.1 on My Oracle Support.
Siebel Web Services. For more information, see Siebel CRM Web Services Reference.
Siebel Commerce Object Aggregator (SCOA). This application acts as an intermediary between Siebel Web services and ATG Web services. For more information, see About Siebel Commerce Object Aggregator.

About Siebel Commerce Object Aggregator

Siebel Commerce Object Aggregator (SCOA) is a Java 2 Platform, Enterprise Edition (J2EE) Web application used to synchronize Siebel products, catalogs and price lists with ATG Web Commerce. SCOA is a reference application and is delivered as source code for each customer or system integrator to modify and compile. Oracle expects customers to modify the Java code of SCOA to suit their middleware needs.

The following figure shows that SCOA acts as an intermediary between Siebel Web services and ATG Web services.

SCOA does the following:

Optimizes Siebel Web commerce job details
Stores the result of this job in an in-memory Java database
Invokes inbound Siebel Web Services to request Siebel contents for each Export Job Detail record
Aggregates replies from the Siebel application using Java technologies such as Java Objects or XLST/XML transformation
Creates XML output files in a designated directory under the job name, where ATG Web Commerce integration layer retrieves these files

SCOA uses the following Siebel Web services:

CatalogWebService
ISS Web Commerce Export Attributes
ISS Web Commerce Export Class
ISS Web Commerce Export Contents
ISS Web Commerce Export Error
ISS Web Commerce Export Price Lists
ISS Web Commerce Export Recommended Products
ISS Web Commerce Export Volume Discounts
SCOAExportWS

These Web services are all inbound except SCOAExportWS. For more information about these Web services, see Siebel CRM Web Services Reference.

SCOA uses the following ATG Web services:

importFromSiebel
getJobStatus

SCOA is delivered as reference source code and can be compiled into a Web application repository file. It can be deployed on any full scale J2EE application server or on any Java application server that runs servlet containers.

About Exporting Siebel Product Catalogs to Oracle ATG Web Commerce

The following figure shows how Siebel product catalogs are exported to ATG Web Commerce.

Note: The administrator must manually add entities used by the Siebel Product Catalog, such as price lists, products, volume discounts, and so on, to a Web Content Export Content Job, in order to make these associated entities available in ATG Web Commerce.

When you export product catalogs, the Siebel application:

Aggregates Siebel Product Catalog entities into an export job
Exports any level of Siebel structured object. The functionality ensures that the parent object exists in ATG Web Commerce.
Supports both product initialization and product updates of entities in the Siebel product catalog
Supports lifecycle changes of these entities, with the object in the Siebel application viewed as the master
Includes the full structure of exported promotions and configurable products
Automatically exports a product’s class when you export the product
Automatically exports a price list line item’s Volume Discount when you export the line item

Exporting Siebel Catalogs to ATG Web Commerce

Setup Tasks for Integrating Siebel Business Applications with Oracle ATG Web Commerce

You must install Siebel Commerce Object Aggregator.

In addition, you can use a number of system preferences to set up the integration of Siebel Business Applications with Oracle ATG Web Commerce. These setup tasks are not required. The Siebel application exports records to Oracle ATG Web Commerce if you do not change the default values of these system preferences. However, you might have to change these system preferences to make the Siebel application behave in the way that you want.

These installation and setup tasks are described in the following topics:

Installing Siebel Commerce Object Aggregator

You must install Siebel Commerce Object Aggregator (SCOA) before setting up ATG Web Commerce Integration.

To install Siebel Commerce Object Aggregator

Navigate to the REPPATCH directory of your Siebel Tools installation.
Download and extract the file SCOA-Snapshot.zip.
This file contains documentation about how to install SCOA.

Enabling ATG Web Commerce Integration

The System Preference SiebelCommerceInteg is set to true by default. This is the value that is needed, so you do not have to change it to enable the integration of Oracle ATG Web Commerce.

The Siebel application checks the value of SiebelCommerceInteg when one of the Siebel product catalog entities is physically deleted by the administrator. When this system preference is set to TRUE, the Siebel application inserts a record into the open Job with a type of <entity>-Delete.

For example, if a user deletes a category from a catalog, and this preference is TRUE, then the Siebel application finds an open Export Job (or creates one) and inserts a new record with a type of Category-Delete. Runtime events for each of the Siebel product catalog business components control this behavior through conditional expressions.

Thus, this system preference helps to keep the data in Oracle ATG Web Commerce synchronized with the data in the Siebel application, by deleting entities in Oracle ATG Web Commerce if they are deleted in the Siebel application.

The following business components contain logic in the PreDeleteRecord Runtime Event that checks the SiebelCommerceInteg system preference. If the system preference is TRUE, then the application does not insert a marker record in the Web Commerce Export Details when a user physically deletes a record in one of these business components:

Product Catalog
Catalog Category Admin
Internal Product
Price List
Price List Item
TNT SHM Volume Discount
Volume Discount
Volume Discount Item
ISS Promotion
Key Feature
Sales Tool by Product
Product Recommendation

If this system preference is mistakenly set to False, rather than the default value of True, then you can enable integration once again using the following procedure.

To enable ATG Web Commerce integration

Set the system preference SiebelCommerceInteg to True.

To modify specific entity behavior for record deletion

Query the runtime events for the business components listed in Enabling ATG Web Commerce Integration, or query for %InsertMarkerRecord% in the Action Set Name List Column of the view Administration - Runtime Events, Events view.
Call a custom business service for desired behavior.

Enabling Cascading Deletions of Web Content Export Job Details

The system preference, SiebCommIntPhysicalDeletes, determines whether there is a cascading deletion of related export job details when the reference record (Catalog or Category record) is physically deleted from the business component. The default value of this system preference is N, and you must change it to enable cascading deletions.

If this system preference is set to Y, then all Web commerce export details of the open export job that are of type Category or Category Product are physically deleted from the job when the reference record is deleted. The deletion of the child records occurs in a cascade format where the parent field is set to object name.

To enable cascading deletions of Web content export job details

Set the system preference SiebCommIntPhysicalDeletes to Y.

Enabling the Export of Nested Catalog Hierarchies to Oracle ATG Web Commerce

The system preference, SiebCommExpCtlgCtgyHier, determines whether the full category hierarchy is exported when you create Web content export jobs. The default value is N. You must change the value to Y to use a full catalog export if the Siebel catalog contains many layers of nested categories.

To enable the export of nested catalog hierarchies to Oracle ATG Web Commerce

Set the system preference SiebCommExpCtlgCtgyHier to Y.

Note: Setting this System Preference to Y may have a performance impact on jobs with many detail records.

Creating Separate Web Content Export Jobs for Each User

The system preference, SiebCommIntOpenJobSearchSpec, determines which export job header the export job detail records are added to. The system preference applies to the business component ISS Web Commerce Export Contents - Header. The default value is as follows:

[Status] = "Open"

This setting means that the detail records are added to the header record that is open. If you want each user to have an export job header of his or her own, with only the details that the user creates, then you can change this search specification and filter the search by user.

To create separate Web content export jobs for each user

Set the value of the system preference SiebCommIntOpenJobSearchSpec as follows:
```
[Created By] = LoginName() and [Status] = "Open"
```

Process of Exporting Records to Oracle ATG Web Commerce

Exporting records to ATG Web Commerce requires the following:

Web content export job details. You must create one or more Web content export job details by selecting and exporting records in the Administration - Product, Administration - Pricing or Administration - Catalog screen.
Web content export job header. You must submit the Web content export job header that has these Web content export job details as line items.

The Siebel application automatically creates and maintains Export Contents - Header records in the Administration - Order Management screen. When you create Web content export job details, the Siebel application automatically adds them to an Export Contents - Header record as line items.

The appropriate header record is found based on the search specification for SiebCommIntOpenJob, as described in Creating Separate Web Content Export Jobs for Each User. If none is found, then it creates one base on the value.

Each user can have only one Web content export job header that has not been submitted. If you do not have any unsubmitted Web content export job headers, then the Siebel application automatically creates one when you create a Web content export job detail and adds the Web content export job detail to the job header as a line item. If you do have an unsubmitted Web content export job header, then the Siebel application adds Web content export job details that you create to this header as additional line items.

To export records from the Siebel application to ATG Web Commerce, perform the following tasks:

Creating Web content export job details in one or more of the following ways:
Submitting an Export Contents Job
Correcting Errors in an Export Contents Job

Creating a Web Content Export Job Detail for Siebel Products or Promotions

You may include any type of product in an export job, without limitation based on data value. Because Siebel Business applications treat promotions as a type of product, you can export promotions in the same way that you export products.

The following best practices are recommended:

Use Siebel Query By Example to construct predefined queries used to build the set of products to send to ATG.
Make sure the resulting set of products is of reasonable size, because larger record sets can negatively impact performance. It is best to build jobs with a few hundred records or less.

You can create an export job by using the Update Commerce App button or menu option on the following views of the Administration - Product screen:

Products view (button)
Product Definitions view (button)
Any view that includes the Product Form as its header, which you navigate to by clicking the view tabs in the Products view (menu option)

The following procedure uses the Products list as an example, but you can also perform the same task in the other views.

To create a Web content export job detail for Siebel products

Navigate to the Administration - Product screen, then the Products view.
Query for the products that you want.
Select or make a multiple selection of the records of the products that you want.
Click Update Commerce App.
Optionally, select or deselect the following check boxes in the Update Commerce App dialog box:
- Include Related Products. If this check box is selected, then the Siebel application checks whether there are any upsell recommendations or cross-sell recommendations for selected root products. If recommendations exist, then the Siebel application creates an Export Job - Detail record of Type = Product for each associated product recommendation. It also sets the Include Related Products flag to True, so SCOA calls the product recommendation's Web service to include the appropriate associated products for the root product.
- Full Structure. This check box is selected by default. If it is selected, then SCOA retrieves the full structure of products, both breadth (attributes of the classes that products belong to) and depth (the full hierarchy of each product or promotion), and the Siebel application sends this structure to ATG. This functionality applies to only product definitions that have a structure, and it ignores nonstructured products.
  
  Note: Export Full Structure does not send the product definition of each component of the hierarchy to ATG. You must manually create an Export Job - Detail record for each component of the hierarchy.
- Include Collateral. If this check box is selected, then the export includes images, key features, literature, and news that are attached to the products in the Administration - Product screen, Collateral view.
In the dialog box, click Export.
Review the message that indicates the number of records that have been sent for export.

Creating a Web Content Export Job Detail for Siebel Catalogs

To export nested Siebel categories correctly, you must set the system preference SiebCommExpCtlgCtgyHier to Y. This setting turns on the functionality that exports all children of a given level within the catalog hierarchy as well as all parents. For more information, see Enabling Cascading Deletions of Web Content Export Job Details.

Only catalogs of the type Buying can be exported to Oracle ATG Web Commerce. If an export job includes catalogs of other types, then SCOA does not create XML files for these nonbuying catalogs, so they are not exported to ATG Web Commerce.

The following best practices are recommended for exporting catalogs:

Try to aggregate related commerce data by creating Web content export job details for catalogs and for the corresponding products and price lists that are line items of one separate, export contents job.
Create exports at the appropriate level of granularity. For example, if many products in a category have been modified, then export the category. If only a few products in a category have been modified, then export only those products
Make sure the resulting set of catalogs is of reasonable size, because larger record sets can negatively impact performance. It is best to build jobs with a few hundred records or less.

You can create an export job by using the Update Commerce App button or menu option on the following views of the Administration - Catalog screen:

Catalogs view (button)
More Info view (button)
Smart Answer Settings view (button)
Categories view (button)
Access Groups view (button)
Catalog Translations view (button)
Catalog Detail view (menu option)
Category Detail view (menu option)

The following procedure uses the Catalogs view as an example, but you can also perform the same task in the other views.

Note: Adding a catalog to a job does not automatically add the Product records of the catalog to the job. An administrator must manually add the products of the catalog to the job.

To create a Web content export job detail for Siebel catalogs

Navigate to the Administration - Catalog screen, then the Catalogs view.
Query for the catalogs that you want.
Select or make a multiple selection of the records of the catalogs that you want.
Click Update Commerce App.
In the Update Commerce App dialog box, click Export.
Review the message that indicates the number of records that have been sent for export.

Creating a Web Content Export Job Detail for Siebel Price Lists

You can include any price list in an export job without any limitations that are based on data values.

The following best practices are recommended for exporting catalogs:

Try to aggregate related commerce data by creating Web content export job details for price lists and for corresponding products and catalogs that all are line items of one separate export contents job.
Create export jobs at the appropriate level of granularity. For example, if many line items in a price list have been modified, then export the price list. If only a few line items in a price list have been modified, then export just those line items.
Make sure the resulting set of price lists is of reasonable size, because larger record sets can negatively impact performance. It is best to build jobs with a few hundred records or less.

You can create an export job using the Update Commerce App button or menu option on the following views of the Administration - Pricing screen:

Price Lists view (button)
More Info view (button)
Price List Line Items view (button)
Service Pricing view (button)
Volume Discounts view (button)
Volume Discount Line Items view (menu option)

The following procedure uses the Price List view as an example, but you can also perform the same task in the other views.

Note: Adding a price list to a job does not automatically add the Product records of the price list to the job. An administrator must manually add the products of the price list to the job.

To create a Web content export job detail for Siebel price lists

Navigate to the Administration - Pricing screen, then the Price Lists view.
Query for the price lists that you want.
Select or make a multiple selection of the records of the price lists that you want.
Click Update Commerce App.
(Optional) Complete the following check boxes in the Update Commerce App dialog box:
- Use Effective Date Of. If you enter a date in this field, then Price List Line Item records are included in the Export Job only if they are valid on this date. For a line item to be included, the date in this field must be between the Start and End Effective Date of both the Price List and Price List Line Item
- Include Volume Discounts. If this check box is selected, then the Siebel application checks the Price List Line Item records of selected price lists to find any associated Volume Discount records and creates an Export Job Detail record for each Volume Discount record.
In the dialog box, click Export.
Review the message that indicates the number of records that have been sent for export.

Submitting an Export Contents Job

After creating Web content export job details for products, catalogs, and price lists, you export them to a format that can be used by Oracle ATG Web Commerce by submitting the export contents job that has these export job details as its detail records.

The details of the export contents job are submitted to SCOA through the Web service SCOAExportWS. For more information about this Web service, see Siebel CRM Web Services Reference.

To submit an export contents job

Navigate to the Administration - Order Management screen, then the Web Commerce Export Contents view.
Select one unsubmitted Export Contents - Header record.

(Optional) Check the Export Contents - Detail records to make sure that you have added the Web content export job details that you want with the options that you want.

The Detail fields, which are filled in by the Siebel application when you create Web content export job details, are described in the following table.

Field	Comments
Type	The values are: Catalog, Category, Category Product, Class, Price List, Price List Line Item, Product, Promotion, and Volume Discount. These values represent the entity that was exported in the Web content export job.
Action Code	The values are: User Requested. This value is assigned to records explicitly selected by the user. Reference. This value is assigned to any parent record if the user requested records that the Siebel application has added because the records are required in Oracle ATG Web Commerce. For example, if the user selects a category, then the Siebel application automatically adds the parent catalog. Delete. This value is assigned to any record if the user deletes the corresponding entity record after creating the Web content export job.
Object Name	Displays the name of the entity. For example, if you are exporting a product, then this field displays the product name.
Parent Name	Displays the name of the entity’s parent record. For example, if you are exporting a category record, then this field displays the name of the catalog that contains this category. If there is no parent record, then this field is blank.
Use Effective Date Of	If you are exporting a price list, and if you selected the Use Effective Date option, then this field displays the date that you specified. For more information, see Creating a Web Content Export Job Detail for Siebel Price Lists.
Full Structure	If you are exporting a product, and if you selected the Full Structure option, then this check box is selected. For more information, see Creating a Web Content Export Job Detail for Siebel Products or Promotions.
Include Related Products	If you are exporting a product or promotion, and if you selected the Related Products option, then this check box is selected. For more information, see Creating a Web Content Export Job Detail for Siebel Products or Promotions.
Include Volume Discounts	If you are exporting a price list, and if you selected the Include Volume Discounts option, then this check box is selected. For more information, see Creating a Web Content Export Job Detail for Siebel Price Lists.
Include Collateral	If you are exporting a product, and if you selected the Include Collateral option, then this check box is selected. For more information, see Creating a Web Content Export Job Detail for Siebel Products or Promotions.

In the Export Contents - Header record, select a value in the Error Handling Instruction field, described in the following table.

Field	Comments
Error Handling Instruction	Select one of the following values: Abort On Error. ATG Web Commerce aborts the job on the first error encountered and restores any changes that might have occurred. Complete With Errors. ATG Web Commerce completes the job even if there are nonfatal errors. Rollback With Errors. ATG Web Commerce aborts the job on the first error encountered and restores any changes that occurred, but it continues to process all records to find any additional errors that might exist.

Field

Comments

Error Handling Instruction

Select one of the following values:

Abort On Error. ATG Web Commerce aborts the job on the first error encountered and restores any changes that might have occurred.
Complete With Errors. ATG Web Commerce completes the job even if there are nonfatal errors.
Rollback With Errors. ATG Web Commerce aborts the job on the first error encountered and restores any changes that occurred, but it continues to process all records to find any additional errors that might exist.

Click Submit Job.

While the job is running, click Refresh periodically to refresh the screen, so you can view the progress of the export job by looking at the two status fields of the Export Contents - Header record, described in the following table.

Field	Comments
Status	This field has the following values: Open. The Siebel product administrator is adding job line items using the Update Commerce functionality. Submitted. The Siebel product administrator has clicked Submit to submit this job. In Progress - SCOA. SCOA has received the new job. Error Processing. SCOA has found errors while processing the job. In Progress - ATG. SCOA has sent a request to ATG to retrieve the job. Error Extracting. ATG has found errors while extracting the job from the SCOA XML files. Error Mapping. ATG has found errors while mapping the job from the SCOA XML files. Error Importing. ATG has found errors while importing the Job from the SCOA XML files. Completed. ATG has completed the job.

Field

Comments

Status

This field has the following values:

Open. The Siebel product administrator is adding job line items using the Update Commerce functionality.
Submitted. The Siebel product administrator has clicked Submit to submit this job.
In Progress - SCOA. SCOA has received the new job.
Error Processing. SCOA has found errors while processing the job.
In Progress - ATG. SCOA has sent a request to ATG to retrieve the job.
Error Extracting. ATG has found errors while extracting the job from the SCOA XML files.
Error Mapping. ATG has found errors while mapping the job from the SCOA XML files.
Error Importing. ATG has found errors while importing the Job from the SCOA XML files.
Completed. ATG has completed the job.

Correcting Errors in an Export Contents Job

If an export job has errors, then you can revise the export job to correct the error. The fact that there are errors is indicated by the header’s Status field, which has one of the following values: Error Extracting, Error Importing, or Error Mapping.

To correct errors in an export contents job

Navigate to the Administration - Order Management screen, then the Web Commerce Export Contents view.
Select the job that you want in the Export Contents - Header List.
Click Revise.

Note: Revise is only available if one of the following values is in the Status field: Error Mapping, Error Extracting, Error Importing.
The Siebel application performs a cascade copy of the contents of this job into the current export contents job with the status of open, or into a new export contents job if there is no current one with the status of open. It copies only the Export Content Details that have a status not equal to Complete.
Select this new job header record.
Click the Error Messages tab to view the error messages generated by the previous job.
Return to the originating data and correct the problems causing the errors.
For example, the Oracle’s ATG Web Commerce might have generated an error when trying to associate a category product to a product because the Product record was never exported. In this case, you must find the Product record and add it to this job.
Click Submit Job to resubmit the new job.
Because this new job contains only the records that have not been processed successfully during the previous job, processing time is minimized.

Maintaining Product Data for Integration with Oracle ATG Web Commerce

This topic describes the methods that you must use to work with product-related data in the Siebel application to have the results reflected properly in Oracle ATG Web Commerce. These methods give the Siebel application and ATG Web Commerce access to identical versions of the product and their supporting objects in both applications, which is necessary to avoid incorrect cross-channel orders.

In most cases, you must use End Effective Date to make the object unavailable. However, you can delete nonversioned product data, such as collateral, literature, or recommended products.

Removing a Product from a Catalog and Category

To remove a product from a catalog and category in both the Siebel application and ATG Web Commerce, set the effective end date in the Category view for the product, and then create a Web content export job to export the change to ATG Web Commerce.

To remove a product from a catalog and category

Navigate to the Administration - Product screen, then the Products view.
Select the product that you want.
Click the Category tab.
In the categories list, for all categories that you want, enter a value in the Effective End Date field that is before the current date.
To verify your work:
1. Navigate to the Administration - Catalog
2. In the Catalogs list, click the Name field of the catalog that contains the category that you removed the product from.
3. In the Categories list, select the category that you removed the product from.
4. Click the Products tab, and confirm that the Product is no longer in this category.
Click Update Commerce App.

Removing a Catalog

To remove a catalog, including its categories and its categories’ products, from both the Siebel application and ATG Web Commerce, set the effective end date of the catalog, and then create a Web content export job to export the change to ATG Web Commerce.

Physically deleting a Catalog record, Category record or Category Product record is also supported, but it is not recommended because it becomes impossible to trace which objects have been removed.

To remove a catalog

Navigate to the Administration - Catalog screen, then the Catalog view.
In the record for the catalog that you want, enter a value in the Effective End Date field that is before the current date.
This field is in the Administration - Catalog applets:
- Catalog Admin Catalog List Applet
- Catalog Admin Catalog Detail Applet
Click Update Commerce App.

Removing a Price List

To remove a price list, including its line items, from both the Siebel application and ATG Web Commerce, set the effective end date of the price list, and then create a Web content export job to export the change to ATG Web Commerce.

Physically deleting a price list and price list line item record is also supported, but it is not recommended because it becomes impossible to trace which objects have been removed.

To remove a price list

Navigate to the Administration - Pricing screen, then the Price Lists view.
In the record for the price list that you want, enter a value in the Effective To field that is before the current date.

Deleting Product Collateral

Product records cannot be deleted. However, collateral, literature and recommended products that are attached to a product can be deleted.

To make collateral, literature and recommended products unavailable in Oracle ATG Web Commerce, you can delete the record in the Siebel application instead of using End Effective Date. If you delete this data, and the system preference for SiebelCommerceInteg is set to True, then a record of type Delete is inserted in the Export Job Details applet, and SCOA sends this record to Oracle ATG Web Commerce.

9Integrating Order Management with Oracle ATG Web Commerce