DuplicateTemplate- Scoped

The DuplicateTemplate API provides methods for users to interact with de-duplication templates by enforcing a set of validations for each method.

De-duplication task remediation can be more time consuming than desirable when handled individually. Duplication templates enable grouping a set of duplicate tasks and running them together. Use the DuplicateTemplate API to create and consume de-duplication templates. This API runs in the sn_cmdb namespace and requires the cmdb_dedup_admin role to access.

When an instance detects duplicate configuration items (CIs) during identification and reconciliation, it groups each set of duplicate CIs into a de-duplication task for review and remediation. De-duplication tasks provide details about the duplication, including a list of all duplicate CIs. For information, see Duplicate CIs remediation.

See also: IdentificationEngine - Scoped

• Template life cycle

  1. Use the CreateTemplate() method to create a template in the draft state.

     You can use the following methods to retrieve or update the template:

     • getTemplate()
     • canAddTasksToTemplate()
     • updateTemplate()
       1. Use the publishTemplate() method to move the template from draft to published state.

     Note: Use the unPublishTemplate() method to return a published template to draft state and update the template.

  2. Optional. Use the CMDBDuplicateTemplateUtil script include to add or remove tasks.

  3. Use the runTemplate() method to run the template.

     To cancel a running task, use the requestCancellation() method.

  4. If the template is no longer needed, you can retire the template using the retireTemplate() method.

  5. Remediating a single task using a template

  To remediate a single task without running the template, you can preview and remediate de-duplication tasks.

  1. Use the previewTemplate() method to preview the remediation of a single-task with a template.
  2. Use the remediateTask() method to remediate the de-duplication task with a template.

Parent Topic:Server API reference

DuplicateTemplate - canAddTasksToTemplate(Array taskIds, String templatId)

Checks if the provided list of tasks can be added to a template.

Use this method to determine whether tasks are suitable for adding to the template. For example, the specified template might be created for Application Server Tomcat, but the specified de-duplication tasks are created for Linux Server. These tasks don’t have a matching template class, so they can’t be added to the template.

{
  "success": [
    "<task_id_1>",
    "<task_id_2>",
    "<task_id_3>"
  ],
  "failed": [
    "<task_id_4>"
  ],
  "skipped": [
    "<task_id_5>"
  ]
}

The following example shows how to check for tasks that can be added to the template.

var taskIds = [];
taskIds.push(<task_id_1>);
taskIds.push(<task_id_2>);
taskIds.push(<task_id_3>);

var result = sn_cmdb.DuplicateTemplate.canAddTasksToTemplate(taskIds, <template_id>);

gs.info('Success:' + result.success);
gs.info('Failed:' + result.failed);
gs.info('Skipped:' + result.skipped);

Output:

Success: <task_id_1>
Failed: <task_id_2>
Skipped: <task_id_3>

DuplicateTemplate - createTemplate(Object template)

Creates a de-duplication template in draft state.

{
  "allow_master_ci_null_update": Boolean,
  "allow_null_attribute_update": Boolean,
  "description": "String",
  "duplicate_ci_action": "String",
  "duplicate_ci_updates": [Array],
  "master_ci_condition": "String",
  "master_ci_option": "String",
  "merge_related_items": "String",
  "merge_related_items_condition": [Array],
  "merge_relations_condition": "String",
  "merge_relations": "String",
  "most_related_items_merge_attributes": "String",
  "most_relations_merge_attributes": "String",
  "name": "String",
  "newest_updated_merge_attributes": "String",
  "oldest_created_merge_attributes": "String",
  "table": "String",
  "task_conditions": "String"
}

"merge_related_items_condition": [
  {
    "related_entry": "String",
    "condition": "String"
  }
]

The following example shows how to create a de-duplication template.

var template = {
  "name": "Test Windows Template",
  "table": "cmdb_ci_win_server",
  "description": "This is a Windows server template",
  "master_ci_option": "oldest_created",
  "master_ci_condition": "",
  "allow_null_attribute_update": false,
  "allow_master_ci_null_update": false,
  "oldest_created_merge_attributes": "serial_number,os_version",
  "merge_relations": "all",
  "merge_relations_condition": "",
  "merge_related_items": "conditional",
  "merge_related_items_condition": [
    {
      "related_entry": "change_request.cmdb_ci",
      "condition": "ramCONTAINS1024"
    },
    {
      "related_entry": "incident.cmdb_ci",
      "condition": "os_versionCONTAINSWindows"
    }
  ],
  "duplicate_ci_action": "delete",
  "duplicate_ci_updates":   [{
    "element": "ram",
    "element_label": "RAM (MB)",
    "value": "1024",
    "display": "1024"
  }],
  "task_conditions": "category=attribute^key=serial_number^value=E2BX1^EQ"
};

var templateId = sn_cmdb.DuplicateTemplate.createTemplate(template);

gs.info(templateId);

Output:

8dfcd36e042b2510f877c1665753a485

DuplicateTemplate - getTemplate(String templateId)

Gets the template object.

{
  "allow_master_ci_null_update": Boolean,
  "allow_null_attribute_update": Boolean,
  "description": "String",
  "duplicate_ci_action": "String",
  "duplicate_ci_updates": [Array],
  "master_ci_condition": "String",
  "master_ci_option": "String",
  "merge_related_items": "String",
  "merge_related_items_condition": [Array],
  "merge_relations_condition": "String",
  "merge_relations": "String",
  "most_related_items_merge_attributes": "String",
  "most_relations_merge_attributes": "String",
  "name": "String",
  "newest_updated_merge_attributes": "String",
  "oldest_created_merge_attributes": "String",
  "table": "String",
  "task_conditions": "String"
}

[
  {
    "element": "String",
    "element_label": "String",
    "value": "String",
    "display": "String"
  }
]

The following example shows how to retrieve a template.

var template = sn_cmdb.DuplicateTemplate.getTemplate('<template_id>');
gs.info(JSON.stringify(template));

Output:

{
  "most_relations_merge_attributes": "",
  "task_conditions": "category=attribute^key=serial_number^value=E2BX1^EQ",
  "duplicate_ci_updates": "org.mozilla.javascript.NativeArray@5d3b19ef",
  "description": "This is a Windows server template",
  "master_ci_option": "oldest_created",
  "merge_related_items": "conditional",
  "duplicate_ci_action": "delete",
  "newest_updated_merge_attributes": "",
  "merge_related_items_condition": [
    {
      "condition": "os_versionCONTAINSWindows",
      "related_entry": "incident.cmdb_ci"
    },
    {
      "condition": "ramCONTAINS1024",
      "related_entry": "change_request.cmdb_ci"
    }
  ],
  "most_related_items_merge_attributes": "",
  "merge_relations": "all",
  "task_condition_table": "reconcile_duplicate_task_data",
  "name": "Test Windows Template",
  "allow_null_attribute_update": false,
  "table": "cmdb_ci_win_server",
  "allow_master_ci_null_update": false,
  "oldest_created_merge_attributes": "serial_number,os_version"
}

DuplicateTemplate - previewTemplate(String templateId, String taskId)

Generates a preview of how different template options were applied to the de-duplication task and how it’s to be remediated.

This method validates all the required attributes before generating the preview for the task using the template. Templates can be created or updated without specifying the required attributes. The required attributes must be provided to preview any de-duplication task.

The following attributes are required:

• duplicate_ci_action
• master_ci_option
• merge_related_items
• merge_relations
• name
• table

Note: Although this method validates all of the attributes, there’s no requirement for the template to be in the published state for a preview.

Use the remediateTask() method to remediate de-duplication tasks.

{
  "allClassCIMap": {Object},
  "duplicateCIAction": "String",
  "duplicateCIUpdates": [Array],
  "masterCI": "String",
  "mergeRelations": Boolean,
  "relatedTablesMerged": [Array],  
  "resolvedFieldCIMap": [Array],
  "taskId": "String",
  "tooManyDuplicates": Boolean
}

[
  {
    "element": "String",
    "element_label": "String",
    "value": "String",
    "display": "String"
  }
]

"resolvedFieldCIMap": [
  {
    "element": "String",
    "sys_id": "String"
  }
]

The following example shows how to get a preview of de-duplication remediation for a specified template.

var preview = sn_cmdb.DuplicateTemplate.previewTemplate("<template_id>", "<task_id>");
gs.info(JSON.stringify(preview));

Output:

{
  "taskId": "<task_id>",
  "masterCI": "<ci_sys_id_1>",
  "allClassCIMap": {
    "cmdb_ci_computer": [
      "<ci_sys_id_1>",
      "<ci_sys_id_2>"
    ]
  },
  "resolvedFieldCIMap": [
    {
      "element": "ram",
      "sys_id": "<ci_sys_id_2>"
    },
    {
      "element": "os_version",
      "sys_id": "<ci_sys_id_2>"
    }
  ],
  "mergeRelations": true,
  "relatedTablesMerged": [
    "incident.cmdb_ci",
    "change_request.cmdb_ci"
  ],
  "duplicateCIAction": "delete",
  "duplicateCIUpdates": [],
  "tooManyDuplicates": false
}

DuplicateTemplate - publishTemplate(String templateId)

Publishes a template. When successful, the template moves from draft to published state.

This method validates all the required attributes before publishing the template. You can create or update templates without specifying the required attributes, but the attributes must be provided before publishing a template.

The following attributes are required:

• duplicate_ci_action
• master_ci_option
• merge_related_items
• merge_relations
• name
• table

In published state, you can run the template using the runTemplate() method.

See also:

• previewTemplate()
• unPublishTemplate()
• updateTemplate()

The following example shows how to publish a template and display results.

var isPublished = sn_cmdb.DuplicateTemplate.publishTemplate('<template_id>');
gs.info(isPublished);

Output:

true

DuplicateTemplate - remediateTask(String templateId, String taskId)

Remediates a de-duplication task using the template.

If the template isn’t in the published state, the template can't be run and the method throws an exception.

Use the previewTemplate() method to preview how de-duplication tasks are to be remediated.

See also.

• Duplicate CIs remediation
• publishTemplate()
• Remediate a de-duplication task (manual)

The following example shows how to remediate a de-duplication task.

var mergeResolutionId = sn_cmdb.DuplicateTemplate.remediateTask("<template_id>", "<task_id>");
gs.info(mergeResolutionId);

Output:

<merge_resolution_id>

DuplicateTemplate - requestCancellation(String templateRunId)

Cancels an existing template run.

A cancel request can only be made for a template run if it's in draft, ready, or running state.

After a template run cancel request, the template run state changes to the intermediate stage Cancel Requested.

Running this method doesn’t automatically cancel template runs in Ready or Draft state. The template run state doesn’t change to Cancelled until any tasks running are complete. At that point any remaining tasks staged for remediation change from cancel requested to canceled.

See also:

• publishTemplate()
• runTemplate()
• retireTemplate()

The following example shows how to cancel a template run and display whether the operation is successful.

var isCancelled = sn_cmdb.DuplicateTemplate.requestCancellation("487c67e2046b2510f877c1665753a4cc");
gs.info(isCancelled);

Output:

true

DuplicateTemplate - retireTemplate(String templateId)

Retires a template.

Use this method to move a template to the retire state if it’s no longer needed.

The template can't be retired and the method throws an exception under the following conditions:

• The template is in the published state.
• The template is running or scheduled to run.

See also:

• publishTemplate()
• runTemplate()
• requestCancellation()
• DuplicateTemplate - unPublishTemplate(String templateId)

The following example shows how to retire a template and display results.

var isRetired = sn_cmdb.DuplicateTemplate.retireTemplate(<template_id>);
gs.info(isRetired);

Output:

true

DuplicateTemplate - runTemplate(String templateId)

Schedules a remediation run for a de-duplication template in the published state. A template can be run multiple times but you can only schedule one run at a time.

If the template isn’t in published state, it can't be run and the method throws an exception. Use the publishTemplate() method to move the template from draft to published state.

To cancel a running task, use the requestCancellation() method.

The following example shows how to schedule a run for a published de-duplication template.

var template = sn_cmdb.DuplicateTemplate.runTemplate('<template_id>');
gs.info(JSON.stringify(template));

Output:

487c67e2046b2510f877c1665753a4cc

DuplicateTemplate - unPublishTemplate(String templateId)

Unpublishes a template.

This method moves the template from the published state to the draft state, which enables updating the template. The template can't be unpublished if it is running or scheduled to be run.

See also:

• publishTemplate()
• requestCancellation()
• updateTemplate()

The following example shows how to unpublish a template and display results.

var isUnPublished = sn_cmdb.DuplicateTemplate.unPublishTemplate(<template_id>);
gs.info(isUnPublished);

Output:

true

DuplicateTemplate - updateTemplate(String templateId, Object template)

Updates a de-duplication template in draft state.

See also:

• unPublishTemplate()
• canAddTasksToTemplate()

{
  "allow_master_ci_null_update": Boolean,
  "allow_null_attribute_update": Boolean,
  "description": "String",
  "duplicate_ci_action": "String",
  "duplicate_ci_updates": [Array],
  "master_ci_condition": "String",
  "master_ci_option": "String",
  "merge_related_items": "String",
  "merge_related_items_condition": [Array],
  "merge_relations_condition": "String",
  "merge_relations": "String",
  "most_related_items_merge_attributes": "String",
  "most_relations_merge_attributes": "String",
  "name": "String",
  "newest_updated_merge_attributes": "String",
  "oldest_created_merge_attributes": "String",
  "table": "String",
  "task_conditions": "String"
}

"merge_related_items_condition": [
  {
    "related_entry": "String",
    "condition": "String"
  }
]

The following example shows how to update several properties of an existing de-duplication template.

var template = {
  "name": "Test Windows Template",
  "table": "cmdb_ci_win_server",
  "description": "This is a windows server template",
  "master_ci_option": "newest_updated",
  "master_ci_condition": "",
  "allow_null_attribute_update": false,
  "allow_master_ci_null_update": false,
  "oldest_created_merge_attributes": "",
  "newest_updated_merge_attributes": "ram,cpu_count",
  "most_relations_merge_attributes": "",
  "most_related_items_merge_attributes": "",
  "merge_relations": "all",
  "merge_relations_condition": "",
  "merge_related_items": "conditional",
  "merge_related_items_condition": [
    {
      "related_entry": "change_request.cmdb_ci",
      "condition": "ramCONTAINS1024"
    },
    {
      "related_entry": "incident.cmdb_ci",
      "condition": "os_versionCONTAINSWindows"
    }
  ],
  "duplicate_ci_action": "delete",
  "duplicate_ci_updates": "",
  "task_conditions": "category=attribute^key=serial_number^value=E2BX1^EQ"
};

sn_cmdb.DuplicateTemplate.updateTemplate(<template_id>, template);

Output:

true