Product Hub to CX Commerce (OCC) Catalog Sync: Part One - The Plumbing

October 19, 2020 | 7 minute read
Patrick Mc Erlean
Architect | A-Team – Cloud Solution Architects
Text Size 100%:

Introduction

This first part of this blog article describes how to connect Product Hub (OPHC) to CX Commerce for the purposes of catalog synchronization. In a future article (i.e. Part Two) we will address some of the more specific details of the data mapping and import into CX Commerce. In the meantime Part One will focus on the connections and events, i.e. the plumbing.

High Level Architecture

The diagram below shows the high level architecture:

The master catalog is managed in Oracle Product Hub. Periodically, changes to the master catalog must be synced to the spoke applications. It could be any spoke application but for the purposes of this article we will use CX Commerce.

When catalog changes are published within OPHC, the resultant data file is copied to Universal Content Management (UCM), and an Item Publication event is generated. That Item Publication event is picked up by an integration workflow in Integration Cloud (OIC), which in turn is passed to a custom process (i.e. named Import Manager in this case) that will handle the event.

In some scenarios we could handle all of the integration requirements within the OIC workflow, but in this scenario we need the custom process because of the complexity of the mapping and import process for CX Commerce. This process handles complex mappings (e.g. the collection hierarchy), import file batching & sequencing, some of which requires the process to wait on one phase completing before another begins. 

The Import Manager uses the event to retrieve the catalog file from UCM. The catalog file processing and subsequent import into CX Commerce will be covered in Part Two of this blog article.

Configure the OIC User Account (in OPHC)

In order to send the Item Publication event to OIC, OPHC must be configured with an OIC account. Your OIC account must already have been created, with the service role assigned.

The first step for configuring OPHC with the OIC account is to access the SOA Composer. The URL used to access the composer is, https://{cloud-instance}/soa/composer/faces/home, where {cloud-instance} is the root URL of your Fusion cloud instance. When you enter that URL into the browser you will be presented with the following screen:

Click on the Manage Security link at the top right of the screen. You will now be presented with the following form:

The first field you must enter is known as the csf-key. It is a concatenation of the Identity Domain and Service Instance values from your OIC account. To get this information, log into your OIC account and click on your account icon in the top right hand corner, and then click on About. You will see a similar image to the one below. Copy the Identity Domain and Service Instance values.

Now, concatenate the Identity Domain and Service Instance values and paste the result into the csf-key field. Enter your OIC User Name & Password, and click on Register. Ok, so that’s OPHC all ready to communicate with OIC.

Subscribe to the Item Publication Event (from OIC)

In this section we are going to show you how to subscribe to the Item Publish event from an OIC integration workflow. We are going to assume you are already familiar with the creation of OIC connections and workflows, so we can simply highlight the most important parts here.

Before creating the workflow, you will need to create a connection to your Fusion instance using the ERP OIC Adapter. Select Oracle ERP Cloud when creating the connection (see below).

In the next screen, choose Trigger as the role. You’ll also need to enter your Fusion instance root URL and your login credentials.

Now you can create the integration workflow. Use the App Driven Orchestration option and drag your ERP connection onto the canvas (see below):

 

 

Next you need to select the event to subscribe to. In this case it is a Business Event, and it’s named Item Publication Event.

Next you should create another connection for the custom Import Manager (or whatever custom process you develop to handle the published file). Your workflow should look something like this:

Next we need to configure the mapping between the publish event and your custom process. It’s pretty straight forward. Look at the mapping screen below:

In terms of the event fields we are only interested in the DocumentId->newValue field. This document ID is used to retrieve the file from UCM. The mapping on the right of the above image is for our particular implementation of the custom process, i.e. Import Manager. You will map the document ID onto your own custom connection. Ok, now that your custom process has the document ID it’s time to pull the file from UCM.

Retrieving the Published File (from UCM)

Your custom process will need to use a couple of UCM APIs in order to retrieve the published file. First you’ll use the SearchTool API to locate the filename using the document ID, and then you’ll use the DownloadTool API to pull the file from UCM.

These APIs are available using the Oracle Webcenter Content Document Transfer Utility. To install this utility see, https://blogs.oracle.com/fusionhcmcoe/installing-oracle-webcenter-content-document-transfer-utility. It is recommended to use the SOAP Based Transfer Utility option and further information is available here, https://blogs.oracle.com/fusionhcmcoe/invoking-document-transfer-utility-using-java-program.

The first step is to use the document ID (we mapped from the event), to find the published file name. To do this we need to use the SearchTool API (from oracle.ucm.idcws.client.SearchTool). Next we use the DownloadTool API (oracle.ucm.idcws.client.DownloadTool) to retrieve the file. The following code fragment demonstrates how to use these APIs:

public class UcmSample {
    private String username = <username>;
    private String password = <password>;
    private String url = "<root url>/idcws";
    private String securityGroup = "FAFusionImportExport";
    private String downloadFolder = <download folder>;

    public void downloadFile(String docId){
        //As the event only contains the Id, if we want to use the origional filename as the name of our downloaded
        //file we need to find the document metadata.
        String filename = getFilename(docId);
        //If it all went wrong, then lets just move on and use the docId as the filename.
        if(filename==null)filename = docId;
        //And now to download to our totally work folder
        Path hereIAm = getFile(docId,filename);
    }

    private String getFilename(String docId){
        List<string> coreArgs = new ArrayList<>();
        coreArgs.add("url="+url);
        coreArgs.add("username="+username);
        coreArgs.add("password="+password);
        coreArgs.add("policy=oracle/wss_username_token_over_ssl_client_policy");
        coreArgs.add("dSecurityGroup="+securityGroup);
        coreArgs.add("dID="+docId);
        coreArgs.add("silent=true");
        SearchTool searchTool = new SearchTool();
        String[] args = coreArgs.toArray(new String[0]);
        String filename = null;

        try {
            SearchTool.SearchResults searchResults = searchTool.run();
            //There should only be one result, but lets just loop through and use the last filename we find.
            for(SearchTool.SearchResult result : searchResults.getResults()){
                filename = result.getDOriginalName();
            }
            searchTool.logout();
        }catch(Exception ex){
            System.out.println("Rut Row... it broke.");
        }

        return filename;
    }
    private Path getFile(String docId,String filename){
        String downloadFile=downloadFolder+filename;
        List<string> coreArgs = new ArrayList<>();
        coreArgs.add("url="+url);
        coreArgs.add("username="+username);
        coreArgs.add("password="+password);
        coreArgs.add("policy=oracle/wss_username_token_over_ssl_client_policy");
        coreArgs.add("dID="+docId);
        coreArgs.add("outputFile="+downloadFile);
        coreArgs.add("silent=true");
        DownloadTool downloadTool = new DownloadTool();
        String[] args = coreArgs.toArray(new String[0]);

        try {
            downloadTool.setup(args);
            DownloadTool.DownloadResult result = downloadTool.run();
            downloadTool.logout();
            return Paths.get(downloadFile);
        }catch(Exception ex){
            System.out.println("Well... good thing this is just a sample program.");
        }

        return null;
    }
}

Note: the other option for retrieving the file from UCM is to use the process outlined in OIC and ICS File based integrations for Oracle HCM Cloud using UCM webservices . However, in this case, since we require a custom import process, it is more efficient to use the APIs as it rules out the need for an additional SFTP service.

Now that the file has been downloaded, it is ready for processing and import into CX Commerce (or any other spoke application). We will talk about file processing and import into CX Commerce in Part Two.

Patrick Mc Erlean

Architect | A-Team – Cloud Solution Architects

The A-Team is an elite team of deeply technical Solution Architects and Software Engineers focused on the success of our SaaS customers. Our mission is to enable customer success with Oracle Cloud Technology and Services through multi-disciplined technical expertise. Our value add to our customers is our ability to operate at the points of intersection across our product lines coupled with our ability to operate at the technical boundaries of Oracle’s products. As a part of its charter the A-Team closely partners with its product development counterparts across the entire SaaS organization and contributes heavily to multiple engineering efforts.

My primary area of expertise is solutions that include any or all of, Commerce Cloud (OCC), Service Cloud (OSvC), and Configure, Price & Quote (CPQ). My focus is on all of the technical aspects of such solutions including, but not limited to: architecture, data integrations, identity management & security, performance & scalability, reliability, extensibility, and customization. I also have specific expertise in B2B and in the communications industry vertical. My research area is machine learning and it's applications.


Previous Post

Hierarchical Text Classification

Patrick Mc Erlean | 5 min read

Next Post


Oracle Analytics Cloud (OAC) - BI Publisher (BIP) - RTF Template Tips and Tricks

Jay Pearson | 8 min read