1. Implementing Launch Experience
  2. Import Catalog Definitions

Import Catalog Definitions

Use this topic to understand how you can import third-party catalogs into the Launch application.

You can import third-party catalogs either through APIs or through the UI using JSON format. It can be a ZIP file containing all the JSON file formats. All the entities imported are assigned to a single project to manage the publish process. The import process is flexible and enables you to import one or more of the entities in a sequence by determining the dependencies between the entities.

You can import catalog definitions in the following ways:

  • One at a time: Enables you to import in bulk, one entity at a time. For example, a set of product specifications, product lines, simple offers, bundle offers, price lists, and so on. However, you must ensure that the referenced entities are either in the same project or already in a lifecycle status of Active or Launched. For example, you could choose to bulk import product specifications, while ensuring that its dependent service specifications, usage specifications are in place. This also applies for the hierarchy while importing product offers to have its associated product specifications in the application.

  • The entire structure in one go: For example, a Package type offer along with its bundles, both commercial and service bundles, simple offers, price lists, terms, product lines and category associations.

The sequence in which the catalog entities are imported are as follows:

  • Project

  • Product Lines

  • Catalog

  • Category

  • Balance Element

  • Price List

  • Customer Profile Specification

  • Custom Profile Specification

  • Promotion

  • Usage Specification

  • Service Specification

  • Product Specifications

  • Pricing Logic Algorithm Specification

  • Pricing Logic Algorithm

  • Pricing Constraints

  • Tax Service Provider

  • Product Offer Price

  • Product Offer

  • Product Rule

  • Entitlement

Getting Ready for Import

Before you begin an import, it's recommended that you increase the number of import threads using the ORA_ATC_IMPORT_THREAD_COUNT profile value. This profile option determines the number of parallel threads that run during the import. The default value is 10.

You can use the following criteria to configure the profile option:

  • Number of ESS servers configured on your instance: You can get this information by contacting Oracle Support.

  • Other active processes: Other application processes that may be simultaneously running on this server and utilizing the same ESS servers.

If the Launch Experience import is the only process running on the instance, you can configure the number of threads up to 10 times the number of ESS servers. If there are other processes likely to be running simultaneously, reduce the number of threads proportionally.

Here's how you can set the profile options for import:

  1. Go to Navigator > My Enterprise > Setup and Maintenance.

  2. In Setup and Maintenance, click Tasks > Search, and enter Manage Administrator Profile Value in the Search field.

  3. On the Manage Administrator Profile Value page, search for ORA_ATC_IMPORT_THREAD_COUNT in the profile option code.

  4. Set the profile value for Profile Level to Site and change the profile value to the appropriate number.

  5. Click Save and Close.

How to prepare data files for import through APIs and UI

As the schema of the import file is based on TMF 620, the third-party catalog import file must be prepared in TMF JSON schema with Oracle shipped extensions. The template schema has resources which are supported by the import job. Each resource is an array of records that must adhere to the seeded schemas for Launch Experience. You must use the template schema to download the seeded schema files that are referred within each resource. See Doc ID 2725039.1 on My Oracle Support for sample template and payload.

Here is a list of some of the key attributes present in the importJob resource:

  • id: Identifier of the import job.

  • @type: Indicates the type of job.

  • contentType: Indicates the content type of file which was used in import job.

  • status: Indicates the status of triggered import job.

  • href: Indicates the url of triggered import job.

  • url: URL of the file containing the import data.

  • errorLog: Indicates the error summary of triggered job.

  • errorLogUrl: Indicates the error log file url. The error file will show the error messages and corresponding IDs of the failed entities with summary information. fileName: indicates the name of the imported file.

  • importSummary: Indicates the success summary of triggered job in terms of each successfully imported resources and their success count.

  • path: Indicates the path of job request file.

  • createdBy: Indicates the submitter of the job request.

  • creationDate: Indicates the time when job was triggered.

  • completionDate: Indicates the time when job was completed.

What you must know

  • Multiple JSON files can be archived and imported as a single ZIP file.

  • The productOfferingPrice subresource within the productOffering resource only supports references to top-level productOfferingPrice resource. So, you must only provide the reference when associating a productOfferingPrice. The complete structure of price must be included in the top-level productOfferingPrice resource array in the same data file, if not already present in the application, when associating a productOfferingPrice. Lifecycle statuses are by default set to In design for all the imported resources.

  • If an existing Launch Experience top-level entity is imported, then the entity is updated. If the entity doesn't exist, then a new entity will be created as version 1.0.

  • If you intend to publish the model to Buying, Catalogs and Categories should be a part of the same initiative. If there are multiple initiatives, none of the reference initiatives should have categories. Initiatives must be in the In Design state until all reference initiatives are imported successfully and published to Buying in the same order.

  • Project and Initiative are used interchangeably.

  • The lifecycle status value for all the imported records is set to In design.

How to use a project for import

Every import job uses one top-level project. If the top-level project isn't provided, the import job implicitly creates a top-level project with ID Import_<Timestamp> and name Import Job <ImportJob_ID> and associates all the imported objects to this project. This top-level project gets imported as In design lifecycle status with all other import file entities associated to it as project items. The project references within all the imported objects are optional and are defaulted to the top-level project used by the import job. If project references are provided, it must refer to the single top-level project provided in the same input file.

Note:

For Zip file imports, the top-level project can be provided in any one of the JSON files contained in the Zip file for import. Ensure that only one file contains the top-level project.

How to initiate an import

Through APIs

You must use the TMF product catalog management import endpoint which involves the following:

  • Creating payloads using the import template. For a sample schema template and payload, see Doc ID 2725039.1 on My Oracle Support.

  • Using the curl command to initiate the import process:

    • Header:

      • Content Type: Use multipart or form data

      • Authorization: Use the standard basic authorization, such as, an encoded user name and password.

    • Form: primaryFile: Use the import data file which you have prepared.

Here's a sample of the curl command that you must use to initiate the import process:

curl --location --request
POST https://<hostName>/crmRestApi/atcProductCatalog/11.13.18.05/tmf-api/productCatalogManagement/v4/importJob/\
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: <ID>' \
--form '<import data file>'

Through UI

  1. Go to Administration > Job Management > Import Jobs.

  2. Click Create Import Job and select the payload prepared for import.

  3. Click Import.

For a sample request payload on initiating the import API, see Doc ID 2725039.1 on My Oracle Support.

How to review the import status

After you have initiated the import job, you can check on the import status and error scenarios, if any, through API. The Oracle Enterprise Scheduler job status can be checked from the Status field of the GetById response. The errorLog attribute in importJob GET by ID response indicates the error summary of the triggered job and must be used to identify the failure and fix the input data file. The importSummary indicates the successfully imported records. The structure of the ImportSummary also includes details like total number of objects successfully imported along with the name and count of each of the individual successfully imported resources. To initiate the import job status, use the following curl command:

curl --location --request 
GET 'https://<hostName>/crmRestApi/atcProductCatalog/11.13.18.05/tmf-api/productCatalogManagement/v4/importJob/<ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: <ID>'

Here's a sample of a successful response:

{
  "id": 149312,
  "@type": "ImportJobOracle",
  "contentType": "application/json",
  "status": "SUCCEEDED",
  "fileName": "testPayload.json",
  "createdBy": "booth",
  "path": "",
  "url": "v1/importFile/testPayload.json",
  "errorLog": "",
  "importSummary": {
    "id": 149312,
    "totalImportObjects": 11,
    "resources": [
      {
        "name": "project",
        "count": 1
      },
      {
        "name": "productOffering",
        "count": 10
      }
    ]
  },
  "errorLogUrl": "",
  "creationDate": "2021-04-07 14:28:00.195",
  "completionDate": "2021-04-07 14:29:26.382",
  "href": "https://hostName/crmRestApi/atcProductCatalog/11.13.18.05/tmf-api/productCatalogManagement/v4/importJob/149312"
}

For a successful response, the importSummary lists out the success summary. To verify a successful import and get summary, use the following curl command:

curl --location --request 
GET 'https://<hostName>/crmRestApi/atcProductCatalog/11.13.18.05/tmf-api/productCatalogManagement/v4/importJob/<ID>' \
--header 'Authorization: <ID>'

Here's a sample of a failed response:

{

    "id": 146623,
    "@type": "ImportJobOracle",
    "contentType": "application/json",
    "status": "ERROR",
    "fileName": "samplePayload.json",
    "createdBy": "booth",
    "path": "",
    "url": "v1/importFile/samplePayload.json",
    "errorLog": "Errors importing data for resource productOfferingPrice. 3 error(s) occurred.\n\nErrors importing data for resource productOffering. 5 error(s) occurred.\n\nErrors importing data for resource constraint. 3 error(s) occurred.\n\nErrors importing data for resource productOfferingPrice. 5 error(s) occurred.\n\nErrors importing data for resource productOffering. 6 error(s) occurred.\n, 6 record(s) rolled back.",
    "importSummary": {
        "id": 146623,
        "totalImportObjects": 110,
        "resources": [
            {
                "name": "project",
                "count": 1
            },
            {
                "name": "category",
                "count": 4
            },
            {
                "name": "productLine",
                "count": 4
            },
            {
                "name": "catalog",
                "count": 1
            },
            {
                "name": "pricelist",
                "count": 2
            },
            {
                "name": "productSpecification",
                "count": 13
            },
            {
                "name": "productOfferingPrice",
                "count": 46
            },
            {
                "name": "productOffering",
                "count": 39
            }
        ]
    },
    "errorLogUrl": "v1/importFile/146623.log",
    "creationDate": "2021-04-06 10:47:01.564",
    "completionDate": "2021-04-06 10:56:44.045",
    "href": "https://hostName/crmRestApi/atcProductCatalog/11.13.18.05/tmf-api/productCatalogManagement/v4/importJob/146623"
}

In the failure response, the errorLog lists out the error summary as well as the total rollback records. As some records are processed successfully as well, they're indicated in the ImportSummary. The errorLogUrl to initiate the case is: https://hostName/crmRestApi/atcProductCatalog/11.13.18.05/v1/importFile/146623.log.