ProductInstance - Scoped, Global

  • Release version: Yokohama
  • Updated January 30, 2025
  • 5 minutes to read

    • The 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.

    This 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.

    A 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.

    Access to install base items requires the Customer Service Install Base Management (com.snc.install_base) plugin.

    See also:

    ProductInstance – generatePID(String className, String modelCategorySysId, Object jsonKeyValues)

    Generates the hashed value of the product instance and returns it.

    This 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.

    A product Instance Identifier (PID) is a unique identifier for a Product Instance and links assets, CIs, and install base items (IBI).

    A PID is generated based on the following items defined in the Product Instance Identifier Configurations [product_instance_identifier_configuration] table:
    • PID configurations (read only)
    • Order assigned to each configuration
    See also Product Instance feature in Hardware Asset Management.
    Table 1. Parameters
    Name Type Description
    className String Table name for the PID to be generated.
    modelCategorySysId String The sys_id of the model category in the Model Categories [cmdb_model_category] table. For information, see Model categories.
    jsonKeyValues Object JSON 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.
    Table 2. Returns
    Type Description
    Object Information used to generate the PID.
    The object returns with an empty product_instance_id property value in the following conditions:
    • The PID is missing the required PID configuration attributes. The PID configuration is in the Product Instance Identifier Configurations [product_instance_identifier_configuration] table.
    • The given class doesn’t have an associated product instance.
    {
  "model_category_sysId": "String",
  "parameters": [Array],
  "product_instance_id": "String"
}
    <Object>.model_category_sysId The 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.

    Data type: String
    <Object>.parameters List 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
    <Object>.product_instance_id PID 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:
    • Assets [alm_asset]
    • Configuration Items [cmdb_ci]
    • Install Base Items [sn_install_base_item]
    Install base items require the Customer Service Install Base Management (com.snc.install_base) plugin.

    Data type: String

    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.

    var output = sn_cmdb.ProductInstance.generatePID('sn_ent_medical_asset', '4b8aa89a77710110dd5fca22fe5a9984', { "serial_number" : "SN1001"});
gs.info(JSON.stringify(output,null,'\t'));

    Output:

    {
  "model_category_sysId": "4b8aa89a77710110dd5fca22fe5a9984",
  "product_instance_id": "tw8QgznsS4cP3b4U0+rSbnbIWxirYpeVSquk3g81K/8=",
  "parameters": [
    "serial_number"
  ]
}

    ProductInstance – getPIDConfig(String className, String modelCategorySysId)

    Gets the PID configuration associated with the model category based on the hierarchy and class name.

    This method scans all the hierarchies for the model category and returns the PID configuration(s) for the first found model category.

    Table 3. Parameters
    Name Type Description
    className String Table name for the PID to be generated.
    modelCategorySysId String The sys_id of the model category in the Model Categories [cmdb_model_category] table. For information, see Model categories.
    Table 4. Returns
    Type Description
    Object JSON object containing the PID configurations associated with the given class name and model category.
    {
  "model_category_sysId": "String",
  "configs": [Array]
}
    <Object>.model_category_sysId The 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.

    Data type: String
    <Object>.configs List of each configuration associated with the given model category.
    
"configs": [
 {
  "configuration_order": Number,
  "parameters": [Array]
 }
]

    Data type: Array
    <Object>.configs.configuration_order Returns the order of the configuration defined in the Product Instance Identifier Parameters [product_instance_identifier_parameters] table.

    Data type: Number
    <Object>.configs.parameters List of all the parameters associated with the configuration and its order.
    "parameters": [
  {
   "parameter_class_attribute_name": "String",
   "parameter_class_name": "String",
   "parameter_name": "String",
   "parameter_order": Number
  }
]

    Data type: Array of Objects
    <Object>.configs.parameters.parameter_class_attribute_name Parameter name associated with the parameter_class_name property. This string represents the name of the column corresponding to that class.

    Data type: String
    <Object>.configs.parameters.parameter_class_name Class name associated with the parameter defined in the Product Instance Identifier Parameters [product_instance_identifier_parameters] table.

    Data type: String
    <Object>.configs.parameters.parameter_name Parameter name defined in the Product Instance Identifier Parameters [product_instance_identifier_parameters] table.

    Data type: String
    <Object>.configs.parameters.parameter_order Order of the parameter defined in the Product Instance Identifier Parameters [product_instance_identifier_parameters] table.

    Data type: Number

    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.

    var config = sn_cmdb.ProductInstance.getPIDConfig('sn_ent_medical_asset', '4b8aa89a77710110dd5fca22fe5a9984');
gs.info(JSON.stringify(config,null,'\t'));

    Output:

    {
  "model_category_sysId": "4b8aa89a77710110dd5fca22fe5a9984",
  "configs": [
    {
      "parameters": [
        {
          "parameter_class_attribute_name": "serial_number",
          "parameter_class_name": "sn_ent_medical_asset",
          "parameter_name": "serial_number",
          "parameter_order": 1
        }
      ],
      "configuration_order": 100
    },
    {
      "parameters": [
        {
          "parameter_class_attribute_name": "parent",
          "parameter_class_name": "sn_ent_medical_asset",
          "parameter_name": "parent_asset",
          "parameter_order": 1
        },
        {
          "parameter_class_attribute_name": "model_component_id",
          "parameter_class_name": "sn_ent_medical_asset",
          "parameter_name": "model_component_id",
          "parameter_order": 2
        }
      ],
      "configuration_order": 200
    }
  ]
}

    ProductInstance – isProductInstance(String modelCategorySysId)

    Checks if a given model category is a product instance.

    If both of the following conditions are met, the model category qualifies as a product instance:
    • The value of the model category's is_model_category flag is true.
    • The model category has a valid configuration defined for it in the Product Instance Identifier Configurations [product_instance_identifier_configuration] table.

    This method can be used in business rules before invoking the generatePID() method.

    Table 5. Parameters
    Name Type Description
    modelCategorySysId String The sys_id of the model category in the Model Categories [cmdb_model_category] table. For information, see Model categories.
    Table 6. Returns
    Type Description
    Boolean Flag that indicates whether the model category provided is a product instance.
    Valid values:
    • true: The model category provided is a product instance.
    • false: The model category provided isn’t a product instance.

    The following example shows how to determine whether the model category provided is a product instance.

    var isProductInstance =  sn_cmdb.ProductInstance.isProductInstance('4b8aa89a77710110dd5fca22fe5a9984');
gs.info(isProductInstance);

    Output:

    true