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:

1. Project
2. Category
3. Catalog
4. Balance Element
5. Price List
6. Tax Service Provider
7. Attributes
8. Customer Profile Specification
9. Custom Profile Specification
10. Service Specification
11. Usage Specification
12. Product Specification
13. Product Line
14. Product Offer Price
15. Product Offer
16. Pricing Logic Algorithm
17. Pricing Constraints
18. Product Rule
19. Promotion
20. Entitlement
21. PriceTag

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>'

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>'

{
  "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"
}

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

{

    "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"
}

Use this topic to know the different ways using which you can export catalog entities from the Launch application.

You can export product catalog entities either through REST APIs or through UI (applicable only for initiatives) and retrieve the exported data files from a known location. The records are exported into a single JSON file or a ZIP file containing multiple JSON files, based on the number of records, which can later be used for importing into another Launch Cloud Service environment.

When the number of objects in the memory reaches this specified limit, it starts dumping into files in between and clears the memory. This results in the generation of multiple files that are zipped into a single ZIP file at the end.

Here are the ways to export catalogs:

Export by Resource Types

Here are some of the primary export resource types available in the ExportJob resource. Export job allows exporting of specific resource types using the resourceType attribute. Following are some of the TMF and non-TMF object types that can be specified when submitting export jobs:

• productoffering

• productOfferingPrice

• productLine

• constraint

• pricingLogicAlgorithmSpecification

• promotion

• productSpecification

• serviceSpecification

• usageSpecification

• customerProfileSpecification

• customProfileSpecification

• taxServiceProvider

• pricelist

• balanceElement

• catalog

• category

• productRule

• attribute

• entitlement

• priceTag

Additionally, here are some of the product offering resource sub-types available to you.

• package

• commercial_bundle

• service_bundle

• service

• device

The following export options are also supported for a resource-based export. However, it's only the latest version of the resource that gets exported.

• Name: Allows exporting objects in a specific resource type based on name attribute. This attribute also supports % search to export all objects based on a name pattern.

• Lifecycle Status: Allows exporting objects across multiple resource types based on a valid lifecycle status attribute.

• Last Update: Allows exporting objects filtered based on their lastUpdate attribute for a specified date range, whenever name attribute isn't used.

  "lastUpdate": {
             "startDateTime": "yyyy-MM-dd'T'HH:mm:ss.SSSZ",
             "endDateTime": "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
          			}

  For a sample payload with lastUpdate, see REST API Reference for Launch Cloud Service.

Export by References

You can export resources that contain the exportReferenced attribute to indicate if the references present in exported resources must also be exported from the application. This results in multiple resource types being exported, so that they can be imported into another Launch Cloud Service environment.

Export by Project

You can export the resources associated to an initiative using the project attribute available in the export job. Initiatives in In design status aren't supported for export.

Export by File Name Prefix

You can provide a specific file name prefix for the file containing the exported objects in the fileNamePrefix attribute. The exported file's name is then set to <fileNamePrefix>_<ExportJob_ID>. If the fileNamePrefix isn't provided, then the exported file's name is defaulted to export_<ExportJob_ID>.

What you must know

• For Export by Resource Types

  • Name

    • Must be a value or pattern (with search %) already present in the application.

    • Attribute isn't supported when exporting more than one resource types.

    • Attribute isn't supported when exporting for date range specified using lastUpdate attribute.

  • Lifecycle Status

    • Must be a value configured in the application.

    • Attribute isn't supported for exact name match (without search %).

  • ResourceType values can be only one of the supported values.

  • ResourceType doesn't support a TMF object type and its corresponding sub type together when creating an export job.

  • Project attribute isn't supported.

• For Export by Project

  • Initiatives in In design status aren't supported for export.

  • The initiative name or ID is required and must be a value already present in the application.

  • The resourceType attribute isn't supported.

  • The lifecycleStatus attribute isn't supported.

  • The lastUpdate attribute isn't supported.

• For Export by File Name Prefix: The fileNamePrefix is optional but the length is limited to 30 characters.

• A Zip file is generated if there are more than 1000 objects that need to be exported.

How to initiate an export

Through API

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

• Creating payloads using the export template. For sample schema files, see REST API Reference for Launch Cloud Service.

• Using the REST endpoints:

  • Method: POST

  • URL: https://hostName/crmRestApi/atcProductCatalog/11.13.18.05/tmf-api/productCatalogManagement/v4/exportJob

  • Header:

    • Content-Type: Use application or JSON.

    • Authorization: Use Standard Basic Authorization, provide encoded user name and password.

Through UI

1. Go to Initiatives.

2. Select and View the initiative that needs to be exported.

3. Click Export.

   The export job is initiated and the Job ID is notified to you.

Track the job in the Administration>Export Job UI page. The Administration>Export Job UI lists all the export jobs that have been triggered. You can monitor and track the progress of the export job on the page. Once the job succeeds, the view page would have download links to download the exported content.

How to review the export status

To verify the export job status, do a GET by ID API call on the export endpoint using the following curl command and check the response field status.

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

Here's the response for the curl command:

{
  "id": <ID>,
  "@type": "ExportJobOracle",
  "href": "https://hostName/crmRestApi/atcProductCatalog/11.13.18.05/tmf-api/productCatalogManagement/v4/exportJob/<ID>",
  "status": "RUNNING",
  "creationDate": "2021-01-21 07:11:38.641",
  "completionDate": "",
  "exportOptions": {
    "exportReferenced": true,
    "filenamePrefix": "exp",
    "resourceType": [
      "productOffering"
    ],
    "id": "TestProductOfferId123",
    "name": "Test Product Offer"
  },
  "createdBy": "booth",
  "path": "productOffering"
}

In this GetByID export API response, the field called status, indicates the current job status.

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

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

You can see the exportSummary parameter in response to easily identify the summary of a successfully exported resource. The ExportSummary shows the totalExportedObjects as well as a resource-wise split up of each resource being exported.

Use this topic to understand how to troubleshoot some of the errors that occur during Import job. These errors may occur when the input data file used for import is incorrect.

You must use the error information provided by the errorLog and errorLogUrl attributes in the importJob GET by ID response to identify and address the issue in the input data file. The errorLog attribute provides a summary of errors that has occurred in the import job, while the errorLogUrl gives an error log file URL which shows the exact resource ID, resource name, and the error message. A new import job may be submitted with the fixed data file.

Here's the list of potential errors along with some troubleshooting tips.

jobId: 102465|id:
500TextMessage|name:
500 Text Message
|resource:
productOffering|
errorMessage: <Actual 
Error for this record>
 | status: FAILED|
The following record(s) were rolled
back due to 1 error(s) in the Import
Batch sub job:-
jobId: 102465|id: SpotifyMusic|
name: Spotify Music|resource:
productOffering|status: ROLLBACK|
jobId: 102465|id:
ModCaseClearM15M25M35|name: Moderna
Case Clear - M15/M25/M35|resource:
productOffering|status: ROLLBACK|

Here's how you can troubleshoot export job and validation errors: