{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":886,"path":"api-reference/server-api-reference/ProductInstanceBothAPI.md","title":"ProductInstance - Scoped, Global","bundle":null,"doc_type":null,"release":"australia","body":"\n# ProductInstance - Scoped, Global\n\nThe ProductInstance API provides methods to generate a product instance identifier \\(PID\\), retrieve PID configuration data, and determine if a model category is a product instance.\n\nThis API runs in the `sn_cmdb` namespace and requires the category\\_manager or snc\\_internal role. Access is also granted to users with access control lists \\(ACLs\\) for the Model Category \\[cmdb\\_model\\_category\\] table. You can view the ACLs in the Table \\[sys\\_db\\_object\\] table.\n\nA PID is a unique identifier for a product instance and links asset, configuration item \\(CI\\), and an install base item \\(IBI\\) to synchronize updates between common product representations. A product instance is associated with assets of a particular model category.\n\nAccess to install base items requires the Customer Service Install Base Management \\(com.snc.install\\_base\\) plugin.\n\nSee also:\n\n-   [Model categories](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-asset-management/c_ModelCategories.md)\n-   [Product Instance feature in Hardware Asset Management](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-asset-management/product-instance-for-assets.md)\n-   [Create an install base item](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/customer-service-management/create-install-base-item.md)\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## ProductInstance – generatePID\\(String className, String modelCategorySysId, Object jsonKeyValues\\)\n\nGenerates the hashed value of the product instance and returns it.\n\nThis method can be invoked many times without affecting the performance of the calling application. This method doesn’t modify any data in the database and caches the data required to compute the PID.\n\nA product Instance Identifier \\(PID\\) is a unique identifier for a Product Instance and links assets, CIs, and install base items \\(IBI\\).\n\nA PID is generated based on the following items defined in the Product Instance Identifier Configurations \\[product\\_instance\\_identifier\\_configuration\\] table:\n\n-   PID configurations \\(read only\\)\n-   Order assigned to each configuration\n\nSee also [Product Instance feature in Hardware Asset Management](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-asset-management/product-instance-for-assets.md).\n\n<table id=\"table_mxt_n4d_tzb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nclassName\n\n</td><td>\n\nString\n\n</td><td>\n\nTable name for the PID to be generated.\n\n</td></tr><tr><td>\n\nmodelCategorySysId\n\n</td><td>\n\nString\n\n</td><td>\n\nThe sys\\_id of the model category in the Model Categories \\[cmdb\\_model\\_category\\] table. For information, see [Model categories](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-asset-management/c_ModelCategories.md).\n\n</td></tr><tr><td>\n\njsonKeyValues\n\n</td><td>\n\nObject\n\n</td><td>\n\nJSON key-value pair of PID parameters configured in the Product Instance Identifier Configurations \\[product\\_instance\\_identifier\\_configuration\\] table.The key value pairs contain attribute names with their corresponding values. These values vary depending on the configuration properties defined for the PID.\n\n</td></tr></tbody>\n</table><table id=\"table_nxt_n4d_tzb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nObject\n\n</td><td>\n\nInformation used to generate the PID.The object returns with an empty product\\_instance\\_id property value in the following conditions:\n\n-   The PID is missing the required PID configuration attributes. The PID configuration is in the Product Instance Identifier Configurations \\[product\\_instance\\_identifier\\_configuration\\] table.\n-   The given class doesn’t have an associated product instance.\n\n```\n{\n  \"model_category_sysId\": \"String\",\n  \"parameters\": [Array],\n  \"product_instance_id\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.model\\_category\\_sysId\n\n</td><td>\n\nThe sys\\_id of the product category in the Model Categories \\[cmdb\\_model\\_category\\] table.This value might be different from the input value if the model category hierarchy was used to generate the PID.\n\nData type: String\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.parameters\n\n</td><td>\n\nList of parameters used to generate the PID and defined in the Product Instance Identifier Configurations \\[product\\_instance\\_identifier\\_configuration\\] table.Data type: Array of Strings\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.product\\_instance\\_id\n\n</td><td>\n\nPID in the product\\_instance\\_id field of an asset, CI, or install base item.The hashed value of the PID can be set on this property to synchronize common values in objects one of the following tables:\n\n-   Assets \\[alm\\_asset\\]\n-   Configuration Items \\[cmdb\\_ci\\]\n-   Install Base Items \\[sn\\_install\\_base\\_item\\]\n\nInstall base items require the Customer Service Install Base Management \\(com.snc.install\\_base\\) plugin.\n\nData type: String\n\n</td></tr></tbody>\n</table>The following example shows how to create a PID for an asset in the Medical assets \\[sn\\_ent\\_medical\\_asset\\] table. This table is included with the Customer Service Install Base Management \\(com.snc.install\\_base\\) plugin.\n\n```\nvar output = sn_cmdb.ProductInstance.generatePID('sn_ent_medical_asset', '4b8aa89a77710110dd5fca22fe5a9984', { \"serial_number\" : \"SN1001\"});\ngs.info(JSON.stringify(output,null,'\\t'));\n```\n\nOutput:\n\n```\n{\n  \"model_category_sysId\": \"4b8aa89a77710110dd5fca22fe5a9984\",\n  \"product_instance_id\": \"tw8QgznsS4cP3b4U0+rSbnbIWxirYpeVSquk3g81K/8=\",\n  \"parameters\": [\n    \"serial_number\"\n  ]\n}\n```\n\n## ProductInstance – getPIDConfig\\(String className, String modelCategorySysId\\)\n\nGets the PID configuration associated with the model category based on the hierarchy and class name.\n\nThis method scans all the hierarchies for the model category and returns the PID configuration\\(s\\) for the first found model category.\n\n|Name|Type|Description|\n|----|----|-----------|\n|className|String|Table name for the PID to be generated.|\n|modelCategorySysId|String|The sys\\_id of the model category in the Model Categories \\[cmdb\\_model\\_category\\] table. For information, see [Model categories](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-asset-management/c_ModelCategories.md).|\n\n<table id=\"table_nxt_n4d_tzb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nObject\n\n</td><td>\n\nJSON object containing the PID configurations associated with the given class name and model category.```\n{\n  \"model_category_sysId\": \"String\",\n  \"configs\": [Array]\n}\n```\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.model\\_category\\_sysId\n\n</td><td>\n\nThe sys\\_id of the product category in the Model Categories \\[cmdb\\_model\\_category\\] table.This value might be different from the input value if the model category hierarchy was used to generate the PID.\n\nData type: String\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.configs\n\n</td><td>\n\nList of each configuration associated with the given model category.```\n\n\"configs\": [\n {\n  \"configuration_order\": Number,\n  \"parameters\": [Array]\n }\n]\n```\n\nData type: Array\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.configs.configuration\\_order\n\n</td><td>\n\nReturns the order of the configuration defined in the Product Instance Identifier Parameters \\[product\\_instance\\_identifier\\_parameters\\] table.Data type: Number\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.configs.parameters\n\n</td><td>\n\nList of all the parameters associated with the configuration and its order.```\n\"parameters\": [\n  {\n   \"parameter_class_attribute_name\": \"String\",\n   \"parameter_class_name\": \"String\",\n   \"parameter_name\": \"String\",\n   \"parameter_order\": Number\n  }\n]\n```\n\nData type: Array of Objects\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.configs.parameters.parameter\\_class\\_attribute\\_name\n\n</td><td>\n\nParameter name associated with the parameter\\_class\\_name property. This string represents the name of the column corresponding to that class.Data type: String\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.configs.parameters.parameter\\_class\\_name\n\n</td><td>\n\nClass name associated with the parameter defined in the Product Instance Identifier Parameters \\[product\\_instance\\_identifier\\_parameters\\] table.Data type: String\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.configs.parameters.parameter\\_name\n\n</td><td>\n\nParameter name defined in the Product Instance Identifier Parameters \\[product\\_instance\\_identifier\\_parameters\\] table.Data type: String\n\n</td></tr><tr><td>\n\n&lt;Object&gt;.configs.parameters.parameter\\_order\n\n</td><td>\n\nOrder of the parameter defined in the Product Instance Identifier Parameters \\[product\\_instance\\_identifier\\_parameters\\] table.Data type: Number\n\n</td></tr></tbody>\n</table>The following example shows how to retrieve configuration details for a model category named in the in the Medical assets \\[sn\\_ent\\_medical\\_asset\\] table. This table is included with the Customer Service Install Base Management \\(com.snc.install\\_base\\) plugin.\n\n```\nvar config = sn_cmdb.ProductInstance.getPIDConfig('sn_ent_medical_asset', '4b8aa89a77710110dd5fca22fe5a9984');\ngs.info(JSON.stringify(config,null,'\\t'));\n```\n\nOutput:\n\n```\n{\n  \"model_category_sysId\": \"4b8aa89a77710110dd5fca22fe5a9984\",\n  \"configs\": [\n    {\n      \"parameters\": [\n        {\n          \"parameter_class_attribute_name\": \"serial_number\",\n          \"parameter_class_name\": \"sn_ent_medical_asset\",\n          \"parameter_name\": \"serial_number\",\n          \"parameter_order\": 1\n        }\n      ],\n      \"configuration_order\": 100\n    },\n    {\n      \"parameters\": [\n        {\n          \"parameter_class_attribute_name\": \"parent\",\n          \"parameter_class_name\": \"sn_ent_medical_asset\",\n          \"parameter_name\": \"parent_asset\",\n          \"parameter_order\": 1\n        },\n        {\n          \"parameter_class_attribute_name\": \"model_component_id\",\n          \"parameter_class_name\": \"sn_ent_medical_asset\",\n          \"parameter_name\": \"model_component_id\",\n          \"parameter_order\": 2\n        }\n      ],\n      \"configuration_order\": 200\n    }\n  ]\n}\n```\n\n## ProductInstance – isProductInstance\\(String modelCategorySysId\\)\n\nChecks if a given model category is a product instance.\n\nIf both of the following conditions are met, the model category qualifies as a product instance:\n\n-   The value of the model category's is\\_model\\_category flag is true.\n-   The model category has a valid configuration defined for it in the Product Instance Identifier Configurations \\[product\\_instance\\_identifier\\_configuration\\] table.\n\nThis method can be used in business rules before invoking the generatePID\\(\\) method.\n\n|Name|Type|Description|\n|----|----|-----------|\n|modelCategorySysId|String|The sys\\_id of the model category in the Model Categories \\[cmdb\\_model\\_category\\] table. For information, see [Model categories](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-asset-management/c_ModelCategories.md).|\n\n<table id=\"table_nxt_n4d_tzb\" class=\"returns\"><thead><tr><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nBoolean\n\n</td><td>\n\nFlag that indicates whether the model category provided is a product instance.Valid values:\n\n-   true: The model category provided is a product instance.\n-   false: The model category provided isn’t a product instance.\n\n</td></tr></tbody>\n</table>The following example shows how to determine whether the model category provided is a product instance.\n\n```\nvar isProductInstance =  sn_cmdb.ProductInstance.isProductInstance('4b8aa89a77710110dd5fca22fe5a9984');\ngs.info(isProductInstance);\n```\n\nOutput:\n\n```\ntrue\n```\n\n"}}