1. Developing Open Storefront Framework Applications for Commerce Experience
  2. Configure Custom Models

Configure Custom Models

You use Buying and Billing REST APIs to retrieve data for displaying it in the UI.

The API model doesn't always suit the requirements of the UI and sometimes it can be difficult to efficiently extract the required information from large API responses. To avoid this, you can configure a custom model to assist in extracting only the required information from an API response by using the app-config/index file. You can configure the settings in the packages/apps/dx4c-store/config/app-config/index.js file manually.

Here's a sample app-config/index.js file for extracting data from the Buying and Billing API responses:

{     
      phoneCategoryName: 'Smart Phone',
      productCharacteristics: ['Color', 'Capacity'],
      characteristicMetaData: {
        Color: {
          control: 'ColorPicker',
          color: true
        },
        Capacity: {
          control: 'ProductOption',
          sort: true
        }
      },
      productLineName: 'Mobile Phones',
      planMetaData: {
        'Supremo Byod': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Wireless Unlimited Line', 'Wireless Unlimited Voice Service', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo Basic': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Wireless Line', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo Premium': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Wireless Line', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo Kids Text and Data': {
          phoneRequired: true,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Wireless Text & Data', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo Lite': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Wireless Line', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo Zoom': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Wireless Line', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo Unlimited': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Wireless Line', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo Kids': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Wireless Line', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo Gold': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Mobile Bundle', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo Silver': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Mobile Bundle', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo Bronze': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Mobile Bundle', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo 5G Premium': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Wireless Line', 'SIM Card'],
          defaultUsageType: 'Data'
        },
        'Supremo 5G Lite': {
          phoneRequired: false,
          simCardName: 'SIM Card',
          planToServiceHierarchy: ['Wireless Line', 'SIM Card'],
          defaultUsageType: 'Data'
        }
      }
    }

Let's see how you can use the following fields in the sample app-config/index.js file to determine the data to be retrieved from the API response:

phoneCategoryName

The category name of a phone or device. Use this as a query parameter to filter the phones or devices when calling the Get all product offers Buying API.

For example, when you set this field to smartphone as shown in the sample file, the query for the Get all product offers API is set as productCatalogManagement/v4/productOffering?category.name=Smart%20Phone. This ensures that only smartphone offers are returned in the API's response.

Similarly, you can use this to find the compatible devices for a given plan.

productLineName

The name of the Product Line. Used to identify the product line which defines the compatible devices for a plan.

productCharacteristics

The properties of the product. Use this to transform the response from the Get a product Buying API. By setting this parameter, you can filter out any product characteristics that aren't required to be displayed on the UI.

Typically, products include a number of characteristics. Here's a sample API response file with six product characteristics. However, when you set this field to Color and Capacity as shown in the sample file, only those product characteristics are retrieved to be displayed in the UI. All the other characteristics are hidden.

"prodSpecCharValueUse": [
    {
        "@type": "ProductSpecificationCharacteristicValueUseOracle",
        "name": "Model",
        "valueType": "string",
        "isConfigurable": true,
        "productSpecCharacteristicValue": [...],
        "@baseType": "ProductSpecificationCharacteristicValueUse",
        "@schemaLocation": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/describe"
    },
    {
        "@type": "ProductSpecificationCharacteristicValueUseOracle",
        "maxCardinality": 1,
        "minCardinality": 1,
        "name": "Color",
        "valueType": "string",
        "isConfigurable": true,
        "productSpecCharacteristicValue": [...]
        "@baseType": "ProductSpecificationCharacteristicValueUse",
        "@schemaLocation": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/describe"
    },
    {
        "@type": "ProductSpecificationCharacteristicValueUseOracle",
        "maxCardinality": 1,
        "minCardinality": 1,
        "name": "Capacity",
        "valueType": "number",
        "isConfigurable": true,
        "productSpecCharacteristicValue": [...],
        "@baseType": "ProductSpecificationCharacteristicValueUse",
        "@schemaLocation": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/describe"
    },
    {
        "@type": "ProductSpecificationCharacteristicValueUseOracle",
        "maxCardinality": 1,
        "minCardinality": 1,
        "name": "IMEI",
        "valueType": "string",
        "isConfigurable": true,
        "productSpecCharacteristicValue": [...],
        "@baseType": "ProductSpecificationCharacteristicValueUse",
        "@schemaLocation": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/describe"
    },
    {
        "@type": "ProductSpecificationCharacteristicValueUseOracle",
        "name": "Supported 3rd Party Apps",
        "isConfigurable": true,
        "productSpecCharacteristicValue": [...],
        "@baseType": "ProductSpecificationCharacteristicValueUse",
        "@schemaLocation": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/describe"
    },
    {
        "@type": "ProductSpecificationCharacteristicValueUseOracle",
        "description": "Brand",
        "name": "Brand",
        "valueType": "string",
        "isConfigurable": false,
        "productSpecCharacteristicValue": [...],
        "@baseType": "ProductSpecificationCharacteristicValueUse",
        "@schemaLocation": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/describe"
    }
]

characteristicMetaData

Each characteristic in the application is modeled using this field. Use this to map the product characteristics to an individual UI widget.

Also, you can use it to specify whether the options for that characteristic need to be sorted to ensure consistent display in the UI. Based on the values shown in the sample file, the Color characteristic is displayed using the ColorPicker component and the Capacity characteristic is displayed using the ProductOption control in the UI.

planMetaData

Each plan in the application is modeled using this field. The sample file contains the following metadata:

  • phoneRequired: This value determines whether the delete icon should be displayed for the cart items associated with the given plan. If the phoneRequired value is set to true, the delete icon isn't displayed for that cart item in the plan.

  • simCardName: The name of the SIM Card. Used to identify the SIM Card in the overall service hierarchy.

  • planToServiceHierarchy: An array which lists the various services that are bundled with the plan. The various services listed in the sample file form a hierarchical path that ends with SIM Card. With this, it's easier for you to locate the SIM Card service and parent services.

  • defaultUsageType: This value determines the usage type to display it in the Service Summary component.

For example, let's consider the following as the bundledProductOffering structure for the Supremo Basic plan:

"bundledProductOffering": [
    {
        "id": "88-1WZKQ6",
        "href": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/88-1WZKQ6",
        "name": "Wireless Lite Voice Service",
        "bundledProductOfferingOption": {
            "numberRelOfferDefault": 1,
            "numberRelOfferLowerLimit": 1,
            "numberRelOfferUpperLimit": 1
        }
    },
    {
        "id": "88-1WZGJQ",
        "href": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/88-1WZGJQ",
        "name": "Wireless Text Service",
        "bundledProductOfferingOption": {
            "numberRelOfferDefault": 1,
            "numberRelOfferLowerLimit": 1,
            "numberRelOfferUpperLimit": 1
        }
    },
    {
        "id": "88-1WZGDM",
        "href": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/88-1WZGDM",
        "name": "Wireless Lite Data Service",
        "bundledProductOfferingOption": {
            "numberRelOfferDefault": 0,
            "numberRelOfferLowerLimit": 0,
            "numberRelOfferUpperLimit": 1
        }
    },
    {
        "id": "88-1WZCBE",
        "href": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/88-1WZCBE",
        "name": "X-Hot Spot",
        "bundledProductOfferingOption": {
            "numberRelOfferDefault": 0,
            "numberRelOfferLowerLimit": 0,
            "numberRelOfferUpperLimit": 1
        }
    },
    {
        "id": "88-1WZFOQ",
        "href": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/88-1WZFOQ",
        "name": "Amazon Prime Video",
        "bundledProductOfferingOption": {
            "numberRelOfferDefault": 0,
            "numberRelOfferLowerLimit": 0,
            "numberRelOfferUpperLimit": 1
        }
    }
]

In the sample file, the value for the planToServiceHierarchy for the Supremo Basic plan is ["Wireless Lite Voice Service", "SIM Card"]. If you browse through the productOffering hierarchy, you can find that the bundledProductOffering for the Wireless Lite Voice Service is within this structure, where SIM Card is the last entry in the hierarchy. The bundledProductOffering section looks similar to the following:

"bundledProductOffering": [
    {
        "id": "88-1WZF81",
        "href": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/88-1WZF81",
        "name": "5G Lite Voice Service",
        "bundledProductOfferingOption": {
            "numberRelOfferDefault": 1,
            "numberRelOfferLowerLimit": 1,
            "numberRelOfferUpperLimit": 1
        }
    },
    {
        "id": "88-1WZDMX",
        "href": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/88-1WZDMX",
        "name": "Wireless Voice Features",
        "bundledProductOfferingOption": {
            "numberRelOfferDefault": 1,
            "numberRelOfferLowerLimit": 1,
            "numberRelOfferUpperLimit": 1
        }
    },
    {
        "id": "88-1WZDLM",
        "href": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/88-1WZDLM",
        "name": "SIM Card",
        "bundledProductOfferingOption": {
            "numberRelOfferDefault": 1,
            "numberRelOfferLowerLimit": 1,
            "numberRelOfferUpperLimit": 1
        }
    },
    {
        "id": "88-1WZDKI",
        "href": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/88-1WZDKI",
        "name": "National Roaming",
        "bundledProductOfferingOption": {
            "numberRelOfferDefault": 1,
            "numberRelOfferLowerLimit": 1,
            "numberRelOfferUpperLimit": 1
        }
    },
    {
        "id": "88-1WZDJF",
        "href": "https://<SERVER-INFO>/productCatalogManagement/v4/productOffering/88-1WZDJF",
        "name": "International Roaming",
        "bundledProductOfferingOption": {
            "numberRelOfferDefault": 0,
            "numberRelOfferLowerLimit": 0,
            "numberRelOfferUpperLimit": 1
        }
    }
]