Product Specification Use Cases

I want to
Request Type
Example URL
Retrieve and display details of a requested product specification.GET by ID{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/{ID}

NOTE:
For invalid category ID, you will receive HTTP 404 error.
Based on the provided field values, retrieve and display details of a particular product specification ID.GET by ID and Fields{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/{ID}?fields=name,description,isBundle
List all the product specifications present in the system.GET List{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification
List all the product specifications present in the system
based on the provided field values.		GET List with Fields{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?fields=name,description,isBundle
List all the product specifications present in the inventory based on the provided field values and filter applied.GET List by Fields and Filtering{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?fields=name,description,isBundle&isBundle=false
Limit the number of product specification to a maximum of specified limit and
display results from the page specified by an offset.		GET List by limit and offset{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?limit=2&offset=2
Create a product specification.POST{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification
Update a product specification.PATCH{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/{ID}
Delete a product specification.DELETE{https://MyDomainLoginUrl}/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/{ID}

Consider you want to retrieve details of a product specification from the inventory.

The handleOverriddenAttributes flag provides flexibility and control over how product attributes are retrieved in scenarios involving base products and bundled products. It supports selective retrieval for both base products and bundled products, reducing payload size and query overhead.

For Base Products

  • true: Returns only the product’s original (non-overridden) attributes. Excludes overridden attributes from other bundles to keep the response lightweight and avoid SOQL offset issues.
  • false (default): Returns all attributes, including overridden ones from associated bundles.

For Bundled Products

  • true: Returns only the original (non-overridden) attributes and the overridden attributes of child products, while the bundle itself returns its own attributes. Helps prevent heap or SOQL limit breaches in complex bundles.
  • false (default): Returns only the bundle’s attributes and minimal child product metadata (name, Id, href), as per the current model.
  • The changes apply to both ProductOffering and ProductSpecification APIs.
  • The changes apply only to GET APIs. There are no changes to POST, PATCH, or DELETE operations.
  • The changes are not applicable to GET by List APIs, as including detailed attribute information in list responses can impact performance.
  • GET by List APIs continue to return existing details, and users can still control overridden attributes using the available flag.
  • To retrieve child product attribute details, users must use the GET by ID API.

As part of the handleOverriddenAttributes = true enhancement, users must update their Data Mapper mappings to retrieve attributes for child products in bundles and only the original (non-overridden) attributes for base products.

To enable child product attribute retrieval, the following mappings are added to the TMFTMForumProductSpecificationResponseTransform.

For ProductSpecification (TMFTMForumProductSpecificationResponseTransform):

  • outputResponse:bundledProductSpecification:productSpecCharacteristic - Maps child product characteristics
  • outputResponse:bundledProductSpecification:productSpecCharacteristic:configurable - Maps configurability
  • outputResponse:bundledProductSpecification:productSpecCharacteristic:name - Maps characteristic names
  • outputResponse:bundledProductSpecification:productSpecCharacteristic:productSpecCharacteristicValue - Maps characteristic values

To use the new feature, users can choose one of the following options:

  • Use the enhanced Data Mapper provided with the package. This replaces existing mappings, so users must manually reapply any customizations.

  • Update existing Data Mapper TMFTMForumProductSpecificationResponseTransform by adding the required mappings.

    • Remove productChildItems:href (having Formula__c),productChildItems:lifecycleStatus(havingFormula__c) andbundledProductSpecification

    • Change the output JSON for the following:

      • productChildItems:href → productChildItemWithAttributeDetails:href
      • productChildItems:lifecycleStatus → productChildItemWithAttributeDetails:lifecycleStatus
      • productChildItems:%vlocity_namespace%__ParentProductId__r:%vlocity_namespace%__GlobalKey__c → productChildItemWithAttributeDetails:productChildItem:%vlocity_namespace%__ParentProductId__r:%vlocity_namespace%__GlobalKey__c
      • productChildItems:%vlocity_namespace%__ParentProductId__r:Name → productChildItemWithAttributeDetails:productChildItem:%vlocity_namespace%__ParentProductId__r:Name

    • Add the following mappings:

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic
        Input Path: (empty - container)
        Field Type: List

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:productSpecCharRelationship
        Input Path: (empty - container)
        Field Type: List

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:productSpecCharacteristicValue
        Input Path: (empty - container)
        Field Type: List

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:configurable
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:attributeAssignment:%vlocity_namespace%__IsConfigurable__c

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:description
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:attributeAssignment:Description

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:displayName
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:attributeAssignment:%vlocity_namespace%__AttributeDisplayNameOverride__c

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:name
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:attributeAssignment:Name

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:productSpecCharacteristicValue:isDefault
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:listOfValues:IsDefault

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:productSpecCharacteristicValue:value
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:listOfValues:Value

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:productSpecCharacteristicValue:valueType
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:listOfValues:ValueType

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:productSpecCharacteristicValue:validFor:endDateTime
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:attributeAssignment:%vlocity_namespace%__AttributeId__r:%vlocity_namespace%__EffectiveUntilDate__c

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:productSpecCharacteristicValue:validFor:startDateTime
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:attributeAssignment:%vlocity_namespace%__AttributeId__r:%vlocity_namespace%__EffectiveFromDate__c

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:valueType
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:attributeAssignment:%vlocity_namespace%__ValueDataType__c

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:validFor:endDateTime
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:attributeAssignment:%vlocity_namespace%__AttributeId__r:%vlocity_namespace%__EffectiveUntilDate__c

      • Output Path: outputResponse:bundledProductSpecification:productSpecCharacteristic:validFor:startDateTime
        Input Path: productChildItemWithAttributeDetails:attributeAssignments:attributeAssignment:%vlocity_namespace%__AttributeId__r:%vlocity_namespace%__EffectiveFromDate__c

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?id=59e0f2ab-d7ba-9703-c545-61939e9d5564&handleOverriddenAttributes=true

The bundledProductSpecification node contains details of child products, and its productSpecCharacteristic node lists their attributes. Since handleOverriddenAttributes = true, the bundle response includes the child product attributes.

Sample URL

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/59e0f2ab-d7ba-9703-c545-61939e9d5564&handleOverriddenAttributes=false

NOTE: If handleOverriddenAttributes is not provided as a parameter, its value defaults to false.

For example, consider the following URL.

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/59e0f2ab-d7ba-9703-c545-61939e9d5564

When the handleOverriddenAttributes is set to false, the productSpecCharacteristic node under bundledProductSpecification is not included. Only the child product’s metadata is returned within the bundle product response.

Consider you want to retrieve details of the product specification ID = f58d3bce-e229-74c5-6a4c-40aa68714c53 and get the name, description and isBundle details in the output.

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification/f58d3bce-e229-74c5-6a4c-40aa68714c53?fields=name,description,isBundle

Consider you want to retrieve details of all the product specifications in the inventory.

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification

Consider you want to retrieve all the product specifications by applying the requested fields.

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?fields=name,description,isBundle

Consider you want to retrieve all the product specifications by a specified filter.

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?fields=name,description,isBundle&isBundle=false

Consider you want to retrieve perform the following.

  • Limit the number of product specifications to a maximum of specified limit
  • Display results from the page specified by an offset

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/{namespace}/tmforum/productopenapi/v1/productSpecification?offset=1&limit=2

Consider you want to create a new product specification.

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification

Consider for the product offer ID = f58d3bce-e229-74c5-6a4c-40aa68714c53 you want to update first level attributes and sub-resources.

Consider you want to delete a product offering ID: 3830.

https://vlocity-1f5-dev-ed.develop.my.salesforce.com/services/apexrest/vlocity_cmt/tmforum/productopenapi/v1/productSpecification/3830