{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":383,"path":"api-reference/developer-guides/product-order_dev-guide.md","title":"Product Order Open API Developer Guide","bundle":null,"doc_type":null,"release":"australia","body":"\n# Product Order Open API Developer Guide\n\nUse the Product Order Open API to create, update, and retrieve product order information.\n\nThis developer guide provides information on how to extend the [Product Order Open API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/tmf622_product_ordering-api.md) to make various customizations.\n\n## Extending the Product Order Open API\n\nThe Product Order Open API can be extended by editing script includes.\n\nThese script includes should only be edited with an understanding of the consequences of the changes.\n\n-   `TMFProductOrderAPIUtil`: Contains functions to handle POST requests.\n-   `TMFProductOrderGetAPIUtil`: Contains functions to handle GET requests.\n-   `ProductOrderExtensionOOB`: Contains helper functions that support functions in `TMFProductOrderAPIUtil` and `TMFProductOrderGetAPIUtil`.\n-   `ProductOrderProcessor`: An empty script include file. Use this file to define any functions that you want to override from `ProductOrderExtensionOOB`.\n\nExtend the Product Order Open API to make the following customizations.\n\n### Required parameters\n\nTo change which request body parameters are required or not required to create a product order, override the function `getProductOrderSchema()` contained in the `ProductOrderExtensionOOB` script include.\n\nThe function `getProductOrderSchema()` reads the schema from the `TMFOrderAPIConstants` script include. `TMFOrderAPIConstants` is protected and can't be edited, so you can't just update the schema. Instead, a new schema must be read from a different file. You can override `getProductOrderSchema()` to read a new schema. To override `getProductOrderSchema()`, write a function with the same name in the `ProductOrderProcessor` script include. The new function in `ProductOrderProcessor` will be called by `TMFProductOrderAPIUtil` to replace the default `getProductOrderSchema()` function in `ProductOrderExtensionOOB`.\n\nIn this example, `getProductOrderSchema()` returns a custom schema that is defined in a new constant file.\n\n```\n// ProductOrderProcessor\n\nvar ProductOrderProcessor = Class.create();\nProductOrderProcessor.prototype = Object.extendsObject(ProductOrderExtensionOOB, {\n   // Define overriding functions here\n   // Function name and parameters must be identical to the function it overrides\n\n   getProductOrderSchema: function() {\n      //Define your own custom schema in a new constant file\n      return JSON.parse(Constants.SCHEMA.CREATE_PRODUCT_ORDER);\n   },\n\n   type: 'ProductOrderProcessor'\n});\n```\n\n### Request body validation\n\nTo perform additional validation on the request body, override `ProductOrderExtensionOOB` functions. `ProductOrderExtensionOOB` contains the following four helper functions that return `true` by default.\n\n-   `validatePostRequest()` - Called by `processCreateOrder()` in `TMFProductOrderAPIUtil`.\n-   `validateProductObj()` - Called by `processCreateOrder()` in `TMFProductOrderAPIUtil`.\n-   `validateRelatedPartyObj()` - Called by `processCreateOrder()` in `TMFProductOrderAPIUtil`.\n-   `validateGetRequest()` - Called by `processGetOrder()` in `TMFProductOrderGetAPIUtil`.\n\nIf a helper function returns `false`, it stops the API operation. To apply custom validation, override `ProductOrderExtensionOOB` helper functions by creating functions with identical names and parameters in `ProductOrderProcessor`. These new `ProductOrderProcessor` functions will be called by `TMFProductOrderAPIUtil` and `TMFProductOrderGetAPIUtil` to replace the default `ProductOrderExtensionOOB` helper functions.\n\nIn this example, a function in `ProductOrderProcessor` overrides a default function in `ProductOrderExtensionOOB` to perform validation on the **productOrderItem** attribute.\n\n```\n// ProductOrderProcessor\n\nvar ProductOrderProcessor = Class.create();\nProductOrderProcessor.prototype = Object.extendsObject(ProductOrderExtensionOOB, {\n    // Define overriding functions here\n    // Function name and parameters must be identical to the function it overrides\n\n    validatePostRequest: function(orderObject, details) {\n        // Returning false terminates the POST request\n        // Make sure to push error message in details array in case of error\n        if (gs.nil(orderObject.productOrderItem)) {\n            details.push(new TMFCommonOrderAPIUtil().getErrorDetailsObj(TMFOrderAPIConstants.MESSAGES.MISSING_ORDER_ITEM, '/'));\n            return false;\n        }\n        return true;\n    },\n\n    type: 'ProductOrderProcessor'\n});\n```\n\n### Additional REST operations\n\nTo create additional operations beyond the existing GET and POST operations, [create additional scripted REST resources](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/t_CreateAScriptedRESTAPIResource.md) for the Product Order Open API. The logic of the new scripted REST resources should be consistent with the existing operations. Define functions for the new operations in a new script include.\n\n### Field mapping\n\nWhen creating records, the API maps request body parameters to record fields. When retrieving records, the API maps record fields to response object attributes.\n\n`ProductOrderExtensionOOB` contains the following functions to map a POST request body to a GlideRecord.\n\n-   `transformOrderGr()`\n-   `transformOrdLineItemGr()`\n-   `getLineItemPrice()`\n-   `transformPriceOrderTypeAndState()`\n-   `transformCustLineItmContact()`\n-   `transformOrderItemChar()`\n\n`ProductOrderExtensionOOB` contains the following functions to map a GlideRecord to a response object for GET or POST requests.\n\n-   `transformPostOrderResponse()`\n-   `transformGetOrderResponse()`\n-   `transformProductObj()`\n-   `transformRelatedPartyCustomerLineItem()`\n-   `transformOrderItemRelationship()`\n-   `transformGetOrdLineItmResponse()`\n-   `transformProductCharacteristics()`\n-   `transformProductSpecification()`\n\nCustomize field mappings to add and retrieve data for additional fields, or to change the default mappings for fields. To customize the field mappings, override `ProductOrderExtensionOOB` mapping functions by creating functions with identical names and parameters in `ProductOrderProcessor`. These new `ProductOrderProcessor` functions will be used by `TMFProductOrderAPIUtil` and `TMFProductOrderGetAPIUtil` to replace the default `ProductOrderExtensionOOB` mapping functions.\n\nIn this example, two functions in `ProductOrderProcessor` override the default functions in `ProductOrderExtensionOOB` to create mappings for the **external\\_id** and **sys\\_id** fields.\n\n```\n// ProductOrderProcessor\n\nvar ProductOrderProcessor = Class.create();\nProductOrderProcessor.prototype = Object.extendsObject(ProductOrderExtensionOOB, {\n    // Define overriding functions here\n    // Function name and parameters must be identical to the function it overrides\n\n    transformOrderGr: function(requestObject, orderGr) {\n        orderGr.external_id = requestObject.externalId;\n        return orderGr;\n    },\n\n    transformPostOrderResponse: function(orderObject, orderGr) {\n        orderObject.id = orderGr.getValue('sys_id');\n        return orderObject;\n    },\n\n    type: 'ProductOrderProcessor'\n});\n```\n\n"}}