Extension Types

Use this topic to understand some of the types of extensions that you can do within the Launch application.

You do these extensions using Application Composer and you will need to refer the Application Composer guide for details on some of the aspects covered in this topic. See About Application Composer.

Here's a quick start to using Application Composer to create extensions:

Access Application Composer at runtime by using the Navigator menu, and selecting Application Composer under the Configuration category.
To make most application changes, you should work in a sandbox. In fact, many functions in Application Composer aren't available until you enter into an active sandbox. You must be an user with Custom Object Administration role to be able to create sandboxes.
You use sandboxes to make application changes and test them without impacting other users in the environment. Wherever possible, make changes to the application in a sandbox rather than making direct changes in the mainline environment.
Make object or schema changes in Application Composer and publish changes.

Note:
After the extensions are published, they can't be reverted.
Make changes to schema files and upload them to UCM via API.
Start using the extended attributes via the APIs.

Simple Attribute Extension

To understand how you can implement a simple attribute extension, let's take the example of a service provider like Vision Inc. To perform an extension, Vision Inc would add a top-level attribute to the ProductOfferingOracle schema and name it ProductOfferingVision.yml.

Go to Application Composer.
Select CRM Cloud from the Application drop-down list.
Click Standard Objects on the Objects Explorer.

All the standard objects shipped by the application are displayed including that of other Oracle Fusion applications.

Note: There are two sections, Custom and Standard. Standard fields are the base fields based on TMF resource specifications and there's no access to edit the standard fields. See the Resource Details table for a list of the TMF 620 Resources, Oracle Fusion applications standard objects that support extension along with their YML schema names. For the example, Product Offering standard object is used.
Click Product Offering > Fields.
On the Fields page, Custom section, click Create.
On the Select Field Type dialog box, select a corresponding type, for example, Text and click OK.

The data type supported in Application Composer includes strings, numbers, boolean, date, datetime, and choice list (enums). In this example, the simple attribute VisionIncName is a text field.
On the Create Text Field dialog box, fill in the following:
1. Display Name: Specify the Display name as Vision Inc Name. The display name is the view name of the attribute in Application Composer.
2. Display Label: Select a Display Label, for example, Vision Inc Name. The Display Label field retains the name of the attribute used for the Application Composer object.
3. API Name: It's auto generated with respect to the DisplayName, by trimming the white space, for example, VisionIncName. This name must be used in the service payload. If you change it, the same must be used in service payload.
4. Description: Provide a description of the attribute
5. Constraints:
  1. Required: Selecting this makes the attribute mandatory with the service payload. It's suggested to not enable this option for a custom attribute because this affects the base object. If you prefer to make an attribute or object as required, you can restrict in schema.
  2. Updatable: This is checked by default. Disabling this will fail the update operation.
  3. Searchable: This is related to Application Composer REST service and isn't used in this scenario.
  4. Indexed: This is related to Application Composer REST service and isn't used in this scenario.
  5. Minimum Length: A text field specific constraint used to define the minimum length supported. By default the value is set to 0.
  6. Maximum Length: A text field specific constraint used to define the maximum length supported. The default length is 80.
6. Default Value: Fixed Value: You can define a static value for the payload, for a boolean field.
Add lookups or enums for the custom attribute:
1. Click Fields within the corresponding standard object.
2. On the Fields page, Custom section, click Create.
3. On the Select Field Type dialog box, select a corresponding type. You must select Choice List and click OK.
4. Enter the following information:
  1. Display Name: This field is mandatory. The display name is visible for a user in Application Composer.
  2. API Name: This gets generated automatically based on the display name and is used in the payload.
  3. Required: Selecting this makes the attribute mandatory with the service payload. It's suggested to not enable this option for a custom attribute because this affects the base object. If you prefer to make an attribute or object as required, you can restrict in schema.
  4. Updatable: This is checked by default. Disabling this will fail the update operation.
  5. Searchable: This is related to Application Composer REST service and isn't used in this scenario.
5. Click Add in the Lookup Type section and add the following information, if the extended field is a lookup type:
  
  Note: You need not perform the following steps if it's a string with a free form text.
  1. Meaning: This field is mandatory as it serves as the display name.
  2. Lookup type: Code to identify lookup. Unique code to identify the list.
  3. Description: Add description about the lookup.
  4. To add values to lookup, click Actions> Create.
  5. Meaning: This field is mandatory as it serves as the display name.
  6. Lookup type: Code to identify lookup value.
  7. Description: Add description about the lookup.
  8. Enabled: Select to either enable or disable a particular value usage.
  9. Display Sequence: Specify the order of display.
Click Save and ensure that the new field, VisionIncName, is added to the Custom Field section.
Go to sandbox and publish the sandbox.

Note: You can perform testing only after publishing the sandbox.

After the sandbox is published, create the schema file with the simple attribute that you just created and refer to the ProductOfferingOracle schema.

Note: The extension will be available in the instance at this point.

title: ProductOfferingVision
type: object
description: 'It's designed to model flexible interface definition in order to provide maximal reuse for existing rating algorithms.'
allOf:
  - $ref: 'ProductOfferingOracle.yml'
  - properties:
      VisionIncName:
        type: string
        description: Name of partner

Save it as ProductOfferingVision.yml and upload to custom folder using schema endpoint.

After the schema is uploaded, use the REST API endpoints to POST and GET data. Here's a sample payload and the steps to go about testing:

Publish the sandbox changes.
Upload the custom schema created with extension attributes to custom folder using schema upload endpoint.
Use the resource endpoint to trigger extension. For example, https://<hostname>/crmRestApi/atcProductCatalog/11.13.18.05/tmf-api/productCatalogManagement/v4/productOffering.

{
    "id": "SUP_PS_WS_ROAM_105",
    "name": "Wireless Roaming PS 105",
    "description": "Product Specification for Wireless Roaming",
    "version": "1.0",
    "lifecycleStatus": "In design",
    "@type": "ProductOfferingVision",
    "@baseType": "ProductOfferingOracle",
    "project": {
        "name": "P_16_9_2020_11_55_15",
        "id": "P_16_9_2020_11_55_15"
    },
    "validFor": {
        "startDateTime": "2020-09-14T00:00:00.000Z"
    },
    "VisionIncName": "Amazefit-v"
}

Complex Attribute Extension: Object and Array

You can perform an aftermarket extension using complex type extension by adding array or object to the existing resources. Application Composer supports only child object as array type, which is the default. There's no place in Application Composer where you can specify the type of child that you want to extend, for example, array or object. This can be achieved with custom schema. During schema creation you must restrict the type of child to be created in Application Composer as array or object. Here's how you can do it.

Object Type Extension

For example, let's introduce a complex object called PartnerDetailsOffering within the product offering resource. The PartnerDetails is an object which contains two text fields PartnerName and PartnerCode. You must begin by enabling Application Composer through sandboxes. You must be an user with Custom Object Administration role to be able to create sandboxes. For more information on how to create and activate sandboxes, see Create and Activate Sandboxes.

Go to Application Composer.
Click Standard Objects.
Click Product Offering.
On the ProductOffering: Overview page, click Create Child Object.
On the Create Child Object dialog box, enter the following information:
1. Display Name: This name is used to display the object in Application Composer. As naming standard display name carries proper white spaces, the object name is displayed as Partner Details. Based on the display name, the rest of the fields get auto populated.
2. API Name: This name used in service payload. The API name gets generated based on the display name, by trimming the white space, and is displayed as PartnerDetails. You can't modify the API name after creating it. Also, you must provide the same name as object name in the payload.
Click Save to create the child object. The same now appears within the ProductOffering object in the Standard Objects section.
Expand the Partner Details child object and click Fields. There will be two sections similar to simple attribute, which are Custom and Standard.
To create PartnerName as well as PartnerCode, click Create in the Custom section.
On the Select Field Type dialog box, select a corresponding type, for this example, Text and click OK.
On the Create Text Field dialog box, fill in the following:
1. Display Name: Specify the display name. All other fields will be auto generated.
2. Display Label: Select a Display Label. This field retains the name of the attribute used for the Application Composer object. However, it isn't used in the payload or on the UI.
3. API Name: It's auto generated with respect to the DisplayName, by trimming the white space. This name must be used in the service payload. If you change it, the same must be used in service payload.
4. Description: Provide a description of the attribute
5. Constraints:
  1. Required: Selecting this makes the attribute mandatory with the service payload. It's suggested to not enable this option for a custom attribute because this affects the base object. If you prefer to make an attribute or object as required, you can restrict in schema.
  2. Updatable: This is checked by default. Disabling this will fail the update operation.
  3. Searchable: This is related to Application Composer REST service and isn't used in this scenario.
  4. Indexed: This is related to Application Composer REST service and isn't used in this scenario.
  5. Minimum Length: A text field specific constraint used to define the minimum length supported. By default the value is set to 0.
  6. Maximum Length: A text field specific constraint used to define the maximum length supported. The default length is 80.
6. Default Value: Fixed Value: You can define a static value for the payload, for a boolean field.
7. Add lookups or enums for the custom attribute:
  1. Click Fields within the corresponding standard object.
  2. On the Fields page, Custom section, click Create.
  3. On the Select Field Type dialog box, select a corresponding type. You must select Choice List and click OK.
  4. Enter the following information:
    1. Display Name: This field is mandatory. The display name is visible for a user in Application Composer.
    2. API Name: This gets generated automatically based on the display name and is used in the payload.
    3. Required: Selecting this makes the attribute mandatory with the service payload. It's suggested to not enable this option for a custom attribute because this affects the base object. If you prefer to make an attribute or object as required, you can restrict in schema.
    4. Updatable: This is checked by default. Disabling this will fail the update operation.
    5. Searchable: This is related to Application Composer REST service and isn't used in this scenario.
  5. Click Add in the Lookup Type section and add the following information:
    1. Meaning: This field is mandatory as it serves as the display name.
    2. Lookup type: Code to identify lookup. Unique code to identify the list.
    3. Description: Add description about the lookup.
    4. To add values to lookup, click Actions> Create.
    5. Meaning: This field is mandatory as it serves as the display name.
    6. Lookup type: Code to identify lookup value.
    7. Description: Add description about the lookup.
    8. Enabled: Select to either enable or disable a particular value usage.
    9. Display Sequence: Specify the order of display.
8. Click Save and verify the changes.
9. Go to sandbox and publish the sandbox.

Here's the custom schema for type object.

title: PartnerDetailsOffering
type: object
description: 'It's designed to model flexible interface definition in order to provide maximal reuse for existing rating algorithms.'
allOf:
  - $ref: 'ProductOfferingOracle.yml'
  - properties:
      PartnerDetails:
        type: object
        description: Partner details Reference
        properties:
          PartnerName:
            type: string
            description: partner name details
          PartnerCode:
            type: string
            description: partner code details

The type of child created is referred to as object so the extension will only support the format of objects. The schema is saved as PartnerDetailsOffering.yml and uploaded to the custom folder using schema endpoint as described in Upload schema section. For more information on uploading schema, see the section in this topic on uploading schema via Launch schema endpoint.

After the schema is uploaded, use the REST API endpoints to POST and GET data. Here's a sample payload and the steps to go about testing:

Publish the sandbox changes and verify the changes.
Upload the custom schema created with extension attributes to custom folder using schema upload endpoint.
Use the resource endpoint to trigger extension. For example, https://<hostname>/crmRestApi/atcProductCatalog/11.13.18.05/tmf-api/productCatalogManagement/v4/productOffering.

To test the scenario, the following payload can be used, with @type as PartnerDetailsOffering to trigger the extension.

{
    "id": "SUP_PS_WS_ROAM_203",
    "name": "Partner Details Spec 203",
    "description": "Product Specification for Wireless Roaming",
    "version": "1.0",
    "lifecycleStatus": "In design",
    "@type": "PartnerDetailsOffering",
    "@baseType": "ProductOfferingOracle",
    "project": {
        "name": "P_16_9_2020_11_55_15",
        "id": "P_16_9_2020_11_55_15"
    },
    "validFor": {
        "startDateTime": "2020-09-14T00:00:00.000Z"
    },
    "PartnerDetails": {
        "PartnerName": "Airtel",
        "PartnerCode": "AT-01"
    }
}

Array Type Extension

The workflow for an array type extension is similar to that of a custom object type. Here the child object is treated as an array type. For the example, an array ConsumerList containing fields, ConsumerName and ConsumerCode, are used. Application Composer can be enabled only through sandboxes. You must be an user with Custom Object Administration role to be able to create sandboxes. For more information on how to create and activate sandboxes, see Create and Activate Sandboxes.

Go to Application Composer.
Click Standard Objects.
Click Product Offering.
On the ProductOffering: Overview page, click Create Child Object.
On the Create Child Object dialog box, enter the following information:
1. Display Name: This name is used to display the object in Application Composer. As naming standard display name carries proper white spaces, the object name is displayed as Consumer List. Based on the display name, the rest of the fields get auto populated.
2. API Name: This name used in service payload. The API name gets generated based on the display name, by trimming the white space, and is displayed as ConsumerList. You can't modify the API name after creating it. Also, you must provide the same name as object name in the payload.
Click Save. The same now appears within the ProductOffering object in the Standard Objects section.
Expand the Consumer List child object and click Fields. There will be two sections similar to simple attribute, which are Custom and Standard.
To create ConsumerName as well as ConsumerCode, click Create in the Custom section.
On the Select Field Type dialog box, select a corresponding type, and click OK.
On the Create Field dialog box, fill in the following:
1. Display Label: Select a Display Label. This field retains the name of the attribute used for the Application Composer object. However, it isn't used in the payload or on the UI.
2. API Name: It's auto generated with respect to the DisplayName, by trimming the white space. This name must be used in the service payload. If you change it, the same must be used in service payload.
3. Description: Provide a description of the attribute
4. Constraints:
  1. Required: Selecting this makes the attribute mandatory with the service payload. It's suggested to not enable this option for a custom attribute because this affects the base object. If you prefer to make an attribute or object as required, you can restrict in schema.
  2. Updatable: This is checked by default. Disabling this will fail the update operation.
  3. Searchable: This is related to Application Composer REST service and isn't used in this scenario.
  4. Indexed: This is related to Application Composer REST service and isn't used in this scenario.
  5. Minimum Length: A text field specific constraint used to define the minimum length supported. By default the value is set to 0.
  6. Maximum Length: A text field specific constraint used to define the maximum length supported. The default length is 80.
5. Default Value: Fixed Value: You can define a static value for the payload, for a boolean field.
6. Add lookups or enums for the custom attribute:
  1. Click Fields within the corresponding standard object.
  2. On the Fields page, Custom section, click Create.
  3. On the Select Field Type dialog box, select a corresponding type. You must select Choice List and click OK.
  4. Enter the following information:
    1. Display Name: This field is mandatory. The display name is visible for a user in Application Composer.
    2. API Name: This gets generated automatically based on the display name and is used in the payload.
    3. Required: Selecting this makes the attribute mandatory with the service payload. It's suggested to not enable this option for a custom attribute because this affects the base object. If you prefer to make an attribute or object as required, you can restrict in schema.
    4. Updatable: This is checked by default. Disabling this will fail the update operation.
    5. Searchable: This is related to Application Composer REST service and isn't used in this scenario.
  5. Click Add in the Lookup Type section and add the following information:
    1. Meaning: This field is mandatory as it serves as the display name.
    2. Lookup type: Code to identify lookup. Unique code to identify the list.
    3. Description: Add description about the lookup.
    4. To add values to lookup, click Actions> Create.
    5. Meaning: This field is mandatory as it serves as the display name.
    6. Lookup type: Code to identify lookup value.
    7. Description: Add description about the lookup.
    8. Enabled: Select to either enable or disable a particular value usage.
    9. Display Sequence: Specify the order of display.
7. Click Save and verify the changes.
8. Go to sandbox and publish the sandbox.

The schema is modified as type array.

title: ConsumerListOffer
type: object
description: 'It's designed to model flexible interface definition in order to provide maximal reuse for existing rating algorithms.'
allOf:
  - $ref: 'ProductOfferingOracle.yml'
  - properties:
      ConsumerList:
        type: array
        description: Consumer List Reference
        items:
          type: object
          description: Consumer List Reference
          properties:
            ConsumerName:
              type: string
              description: Consumer name details
            ConsumerCode:
              type: string
              description: Consumer code details

The schema is saved as ConsumerListOffer.yml and uploaded to the custom folder using schema endpoint as described in Upload schema section. For more information on uploading schema, see the section in this topic on uploading schema via Launch schema endpoint.

After the schema is uploaded, use the REST API endpoints to POST and GET data. Here's a sample payload and the steps to go about testing:

Publish the sandbox and verify the changes.
Upload the custom schema created with extension attributes to custom folder using schema upload endpoint.
Use the resource endpoint to trigger extension. For example, https://<hostname>/crmRestApi/atcProductCatalog/11.13.18.05/tmf-api/productCatalogManagement/v4/productOffering.

To test the scenario, the following payload can be used, with @type as ConsumerListOffer to trigger the extension.

{
    "id": "SUP_PS_WS_ROAM_301",
    "name": "Consumer List Spec 302",
    "description": "Product Specification for Wireless Roaming",
    "version": "1.0",
    "lifecycleStatus": "In design",
    "@type": "ConsumerListOffer",
    "@baseType": "ProductOfferingOracle",
    "project": {
        "name": "P_16_9_2020_11_55_15",
        "id": "P_16_9_2020_11_55_15"
    },
    "validFor": {
        "startDateTime": "2020-09-14T00:00:00.000Z"
    },
    "ConsumerList": [
        {
            "ConsumerName": "Consumer 1",
            "ConsumerCode": "CS-01"
        },
        {
            "ConsumerName": "Consumer 2",
            "ConsumerCode": "CS-02"
        }
    ]
}

Note:

You can't undo the changes for simple attribute or complex attribute objects after publishing the sandbox. Once it's published the changes will remain. So, creating a simple extension attribute with Required as enabled isn't recommended. To make an attribute as required, you must modify the schema and mark it as required within the schema.
Application composer can't handle complex extension types such as object or array specifically. Creating child objects and adding custom fields are common to both the scenarios. You can restrict the type of extension in schema only as explained earlier.

Migration of Extensions

Any implementation of Oracle Applications Cloud usually requires migrating extensions from one environment to another at various points in the subscription lifecycle. It's recommended to start with a test instance, test the changes, and only after validation, apply the changes to the production instance.

The extension configured in one instance can be moved to another either by manually configuring or by using the migration tool for Application Composer related changes.

For schema changes, you must manually move the changes after migrating Application Composer changes. Custom schema can be uploaded to the custom folder using schema endpoint as described in the following section.

Upload Schema via Launch Experience Schema Endpoint

Use the Launch Experience schema endpoint to upload new or updated YML files. Here's how you can go about it:

Go to endpoint: https://<hostname>/crmRestApi/atcProductCatalog/11.13.18.05/v1/schema.
Set Method to POST (to add new schema) or PUT (to overwrite an existing schema).
Request Body: Set mimeType as multipart or form-data.

Add the following rows inside the form:

Key	Value
path	custom
primaryFile	Select the file to be uploaded

Send the request.
Validate to ensure that the extension works.