How You Integrate with Other Applications

You can integrate Configurator with an application, such as quoting or order capture, to provide an interactive configuration experience for configuring products and services.

Configurator is agnostic about the technology stack of an external application and implements a standards-based approach for a seamless UI integration experience. The integration approach leverages Representational State Transfer (REST) APIs for creating the intent to configure a complex item and for retrieving the final configuration, and an entry point URL for launching the configurator runtime UI, either within an IFrame or within a browser window. REST isn't a technology, but rather a client-server architectural style in which participants perform actions on data-oriented resources.

Integration Architecture

Integration to launch Configurator from an external application and return after a configuration session consists of the elements described in the following table.

Integration Element	Purpose
REST resources	Provide data-oriented services for: Creating an intent to start a configuration session Retrieving configuration details, such as lines, line attributes and messages Performing custom configuration actions.
External application data model entities	Provide data from the host application that's needed by Configurator to establish integration, such as a unique identifier for a configuration header.
Public entry point URL	Provides the entry point for launching a configurator user interface session.
REST input and output payloads	Carry the specific inputs to and outputs from a a configuration session.
Integration tasks	Actions required to complete an integration.

REST Resources

External applications can leverage these Configurator REST resources to interact with configurations

Initialization Parameters: External applications must use this resource to specify the intent to configure a product or service interactively by passing an input payload which provides details that the configurator uses at run time to start a configuration session.

At a minimum the following information must be posted to this REST resource:
- CallingApplicationCode: The application code registered in the Manage Trading Community Source Systems task in the case of external non Oracle applications or the FND Application short name (code) for Oracle applications.
- Line: A JavaScript Object Notation (JSON) document serialized in string format. For each field, a name-value pair corresponds to the sales context line entity definition.
The Initialization Parameters resource is used to load the appropriate model and user interface to launch an interactive configuration session.

The Initialization Parameters resource can be used only once to launch Configurator, then the resource is marked as expired and can't be reused. The purpose of this restriction is to prevent attacks such as distributed denial of service.
Configurations: External applications must use this resource to retrieve the details of a configuration, using the configuration identifiers that are returned by Configurator after finishing a configuration session.

The Configurations resource consists of one root entity and encompasses three child entities:
- ConfigurationLines: a collection resource that describes all the lines in a configuration.
- ConfigurationLineAttributes: a collection resource that describes all the transactional attribute lines in a configuration.
- ConfigurationMessages: a collection resource that describes one or more messages added in a configuration.
The Configurations resource by default filters out option class lines when returning configuration results. An external application can request the full result by specifying the OuptutMode query parameter value as full.
The Configurations resource supports the following custom actions that can be performed on a configuration:
- copy: Copy a configuration mirroring the copy action on a quote/order line.
- validate: Validate a configuration before submitting a quote or order to Oracle Order Management for fulfillment to eliminate quote or order errors before submission.

See the REST API for Oracle Supply Chain Management Cloud guide for full details on:

Descriptions of parameters and query examples for the Initialization Parameters and Configurations REST endpoints
Examples of use cases for the custom actions

Note: The REST API for Oracle Supply Chain Management Cloud guide is the comprehensive reference for working with SCM REST resources, and includes information on getting started with REST APIs.

External Application Data Model Entities

To persist configuration-related information, all external applications integrating with Configurator must add the following attributes in their entity that represents a configuration line.

Attribute	Purpose
ConfigHeaderId	Configurator-generated unique identifier for a configuration header
ConfigRevisionId	Configurator-generated unique identifier for a revision of a configuration
ConfiguratorPath	Configurator-generated runtime inventory ID path to an item for a configuration line

The combination of ConfigHeaderId and ConfigRevisionId uniquely identifies a configuration. The identification attributes must be passed to Configurator during reconfiguration flows, and to Oracle Order Management when submitting a quote or order for fulfillment.

In addition to the attributes that identify a configuration, external applications can add the following attributes in their configuration line entity, to synchronize with existing quote or order lines during a reconfiguration session, instead of deleting and recreating the quote or order lines. This information is retrieved using the Configurations resource when you expand the child resources.

Attribute	Purpose
ConfigLineId	Configurator-generated unique identifier for a configuration line
ParentConfigLineId	Configurator-generated unique identifier to indicate the parent configuration line from a child line
ConfigLineAttributeId	Configurator-generated unique identifier for a configuration line attribute representing a transactional attribute associated to an Item.

Public UI Entry Point URL

Configurator provides a public entry point URL to launch the configurator runtime UI, either within an IFrame or within a browser window.

The URL entry point to launch the configurator runtime UI is publicly available, and secured to provide access to an authenticated user. The entry point expects the following URL parameters:

ParameterId: An initialization parameter resource identifier generated by the Initialization Parameters REST API while creating the intent to configure, which identifies a set of initialization parameter attribute-value pairs. If this parameter value isn't specified or is invalid then an error dialog will be displayed to the user and configurator will redirect to the ReturnUrl.
ReturnUrl: A fully qualified URL of the host application to return to after finishing a configuration session. An HTTP 400 error code will be returned if this parameter value isn't passed.

The entry point URL syntax is:

<protocol>://<host>:<port>/fscmUI/faces/ConfigLaunch.jspx

Example:

https://acme.cloud.enterprise.com/fscmUI/faces/ConfigLaunch.jspx?ParameterId=123456&ReturnUrl=https://acme.cloud.quote.com/context/processResults.jsp

In the case of an error either during or while starting a configuration session, Configurator navigates to the ReturnUrl with an ExitStatus of error. The host application can perform a REST GET operation on the Initialization Parameters resource, with the ParameterId passed as part of the ReturnUrl, to obtain the full error message details.

Integration Tasks

To prepare to call the runtime configurator from a host application, and to prepare and process input and output payloads, follow these high-level steps.

Register the external application:

Go to the Setup and Maintenance work area, then go to the task:
- Offering: Product Management
- Functional Area: Product Spoke Systems
- Task: Manage Trading Community Source Systems
For details, see Product Spoke Systems.

Then create or register your external application as a source system.

When an application is registered, you can define applicability parameters for modified user interfaces, in the Configurator Models work area, so that those user interfaces are displayed when the application calls Configurator.
Enable the allowed origins white list:

This step is required if launching the runtime configurator in an IFrame. By default, Oracle Applications will not render contents in an IFrame except when called from the same origin. You can use a configurable white list mechanism to specify the list of allowed external origins that can render contents in an IFrame. You control the allowed origins by setting the profile option ORACLE.ADF.VIEW.ALLOWED_ORIGINS, using the Manage Administrator Profile Values task in the Setup and Maintenance work area.

This step isn't required for launching the runtime configurator in a browser window.

Call the runtime configurator UI, in an IFrame or browser window, using the public entry point URL:

The public entry point URI is /fscmUI/faces/ConfigLaunch.jspx. The URL parameters ParameterId and ReturnUrl are required.

The following steps are required for calling the runtime configurator.

Prepare an initialization payload.

Prepare a REST payload using the JSON format.

Example, showing the minimum required payload:

{ "CallingApplicationCode":"CZ",
   "Line":"{\"InventoryItemNumber\":\"AS100\",\"RequestOn\":\"2017-01-22T09:09:28-0700\",\"InventoryOrganizationCode\":\"V1\"}"
}

Post the payload to the Initialization Parameters resource.

Send the payload to the Initialization Parameters REST resource using the POST operation, using the following URI

/fscmRestApi/resources/latest/initializationParameters

You can replace latest with the string that specifies the desired installed release of Oracle Supply Chain Management, such as 11.13.18.02.The string latest is a synonym for the latest installed release.

Example, using the cURL command-line tool:

curl ' https://acme.cloud.enterprise.com:7000/fscmRestApi/resources/latest/initializationParameters' \
-i \
-X POST \
-H "Content-Type:application/json" \
-u myuserid:mypass \
-d '{  "CallingApplicationCode":"CZ",
   "Line":"{\"InventoryItemNumber\":\"AS100\",\"RequestOn\":\"2017-01-22T09:09:28-0700\",\"InventoryOrganizationCode\":\"V1\"}"}'

For the payload request shown in the example, the response from the Initialization Parameter resource is like the following:

{
    "ParameterId": 300100116074154,
    "CallingApplicationCode": "CZ",
    "Header": null,
    "Line": "{\"UnitQuantity\":1,\"InventoryItemNumber\":\"AS100\",\"RequestOn\":\"2018-01-11T09:09:28-0700\",\"InventoryOrganizationCode\":\"V1\",\"InventoryOrganizationId\":204,\"InventoryItemId\":300100016171847}",
    "CustomParameters": null,
    "ManualPriceAdjustments": null,
    "PageTitlePrefix": null,
    "ExpiredFlag": false,
    "ErrorMessageText": null,
    "TerminalActionCaption": null,
    "ValidationCannotAlterFlag": true,
    "ValidationFailFastFlag": true,
    "links": [
        {
            "rel": "self",
            "href": "<a target="_blank" href="https://node001.my.srvr.com:7021/fscmRestApi/resources/latest/initializationParameters/300100116074154",">https://node001.my.srvr.com:7021/fscmRestApi/resources/latest/initializationParameters/300100116074154",</a>
            "name": "initializationParameters",
            "kind": "item"
        },
        {
            "rel": "canonical",
            "href": "<a target="_blank" href="https://node001.my.srvr.com:7021/fscmRestApi/resources/latest/initializationParameters/300100116074154",">https://node001.my.srvr.com:7021/fscmRestApi/resources/latest/initializationParameters/300100116074154",</a>
            "name": "initializationParameters",
            "kind": "item"
        }
    ]
}

Extract the ParameterId.

The external application must process the response payload from the POST operation to obtain the parameter identifier ParameterId generated by the Initialization Parameters REST resourcewhen initializing the configuration. The value from the example is:
```
"ParameterId": 300100116074154
```
Call the public entry point URL.

The value obtained for ParameterId is passed as a URL parameter value when calling the public entry point ConfigLaunch.jspx. The resulting example URL, which launches the runtime Configurator user interface in a session that configures the products specified in the initialization payload, is like:
```
https://acme.cloud.enterprise.com/fscmUI/faces/ConfigLaunch.jspx?ParameterId=300100089663945&ReturnUrl=https://acme.cloud.quote.com/context/processResults.jsp
```

The end user interactive configuration session happens at this point.

The end user can complete an interactive configuration session and exit the configurator by using one of the following actions, by clicking the corresponding button in the runtime configurator user interface:
- Cancel: The end user can simply cancel the configuration session. A warning dialog is displayed to the end user about losing the changes made to configuration. An exit status of cancel is specified in the ReturnUrl parameter to indicate to the host application that there no changes to process upon return.
- Save for Later: The end user decides to save the configuration to finish it at a later point in time. An exit status of save is specified in the ReturnUrl parameter to indicate to the host application that there are changes to the configuration. The host application can use the configuration identifiers ( ConfigHeaderId with ConfigRevisionId ) to retrieve the configuration details.
- Finish or Finish and Review: The end user completes the configuration, by implicitly running the autocompletion process, and returns to the host application. An exit status of save is specified in the ReturnUrl parameter to indicate to the host application that there are changes to the configuration. The host application can use the configuration identifiers ( ConfigHeaderId with ConfigRevisionId ) to retrieve the configuration details.
Process the configuration results:

When the end user completes an interactive configuration session and exits, Configurator navigates to the ReturnUrl that was provided when launching the configuration session, and appends the configuration identifiers and exit status as URL parameter values. The external application must use the URL parameter values to determine the exit status and take the necessary action to navigate to its appropriate page.
- The ExitStatus parameter indicates the exit method. Possible values are save, cancel and error.
- When the exit status is save, the following configuration identifiers are included:
  - ConfigHeaderId: Identifier for the configuration.
  - ConfigRevisionId: Identifier for the configuration revision.
  When used together, the combination of ConfigHeaderId and ConfigRevisionId uniquely identify a configuration. Example:
```
q=ConfigHeaderId=300100112392208;ConfigRevisionId=300100112392209
```
- If the ExitStatus is save, then the external application must obtain the configuration results by passing URL parameter values to the Configurations REST resource. The URI for the Configurations REST resource is:
```
/fscmRestApi/resources/latest/configurations
```
  The required URL parameters are:
```
q=ConfigHeaderId=000;ConfigRevisionId=000
```
  Example URL that queries the Configurations REST resource for a specified configuration and returns all its configuration lines, including option class lines (OutputMode=full), and transactional attribute lines (expand=ConfigurationLines,ConfigurationLineAttributes):
```
https://acme.cloud.enterprise.com:7000/fscmRestApi/resources/latest/configurations?q=ConfigHeaderId=300100112392208;ConfigRevisionId=300100112392209;OutputMode=full&expand=ConfigurationLines,ConfigurationLineAttributes&onlyData=true
```
  This REST resource produces a JSON document in the following structure for one configuration:
```
Configuration
    ConfigurationLines (collection)
        ConfigurationLine [0...n]
    ConfigurationLineAttributes (collection)
        ConfigurationLineAttribute [0...n]
    ConfigurationMessages (collection)
        ConfigurationMessage [0...n]
```
  The external application must process the JSON document to create quote or order lines from it.
Reconfiguration flow.

An external application can perform a reconfiguration of an existing configuration by following the same integration steps as for a new configuration, but must include the configuration identifiers and configurator path information for the root line in the initialization parameters payload. Example, showing the minimum required payload:
```
{
  "CallingApplicationCode":"ABC_CPQ",
  "Line": "{\"InventoryItemNumber\":\"AS100\", \"InventoryOrganizationCode\":\"V1\",\"RequestOn\":\"2016-04-07 13:00:00\"}",
\"ConfigHeaderId\":300100112392208, \"ConfigRevisionId\":300100112392209, \"ConfiguratorPath\":\"987654321\"}
}
```
Based on the exit status, an external application can obtain the configuration results using the configuration identifiers. Instead of deleting and recreating quote or order lines, an external application can use the configuration line identifiers to synchronize the existing lines. The important point to note is that Configurator returns the same line identifiers for reconfiguration flows as for new configuration flows. However, the lines in the configuration aren't ordered, and you can't provide a sorting order.

For details and examples, go to REST API for Oracle Supply Chain Management Cloud, then expand:

Order Management > Configuration Initialization Parameters
Order Management > Configurations
Use Cases > Configurator