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:
  2. 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.
  3. (Optional) Use the CMDBDuplicateTemplateUtil script include to add or remove tasks.
  4. Use the runTemplate() method to run the template.

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

  5. If the template is no longer needed, you can retire the template using the retireTemplate() method.
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.

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.

Table 1. Parameters
Name Type Description
taskIds Array Array of sys_ids of the de-duplication tasks to add to the template.
templateId String Sys_id of the template listed in the Reconcile Duplicate Template [reconcile_duplicate_template] table.
Table 2. Returns
TypeDescription
Object Result object containing what tasks can be added, skipped, or failed.
{
  "success": [
    "<task_id_1>",
    "<task_id_2>",
    "<task_id_3>"
  ],
  "failed": [
    "<task_id_4>"
  ],
  "skipped": [
    "<task_id_5>"
  ]
}
failed Error occurred while checking if the task is compatible with the template. See also Detecting duplicate CIs.
skipped The tasks are incompatible because they don’t have a matching template class, so the task was skipped.
success The task matches the template class and can be added to the template.

Example

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.

Table 3. Parameters
NameTypeDescription
template Object The template object with different options for creating the template. 
{
  "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"
}
template.allow_null_​attribute_update Boolean Optional. Flag that indicates if main CI attributes are updated with null values from duplicate CIs when resolving attribute conflicts for CIs within a de-duplication task.
Valid values:
  • true: The main CI attributes are updated with null values from duplicate CIs.
  • false: The main CI attributes aren’t updated with null values from duplicate CIs.

Default: False
template.allow_master_ci_​null_update Boolean Optional. Only includes updates from duplicate CIs if the main CI value is null.

Flag that indicates whether to include only updates from duplicate CIs if the main CI value is null.

Valid values:
  • true: Only include updates from duplicate CIs if the main CI value is null.
  • false: Include updates from all duplicate CIs.

Default: False
template.description String Optional. Description to store more information about the template.
template.duplicate_​ci_action String Optional. Specifies if the duplicate CI is to be deleted or updated with unique custom values.
Possible options:
  • delete
  • update (requires specifying duplicate_ci_updates)
template.duplicate_​ci_updates Array Optional, unless the setting for duplicate_ci_action is update. Array of objects specifying how the duplicate CI values are updated.
[
  {
    "element": "String",
    "element_label": "String",
    "value": "String",
    "display": "String"
  }
]
template.duplicate_​ci_updates.element String The system dictionary name of a reference field.
template.duplicate_​ci_updates.element_label String The label that the reference field displays.
template.duplicate_​ci_updates.value String Value for a reference field, that is, the contents of the reference field.
template.duplicate_​ci_updates.display String Display value for a reference field.
template.master_ci_​option String Optional. Specifies how the main CI is selected for a de-duplication task when applying this template.
Possible options:
  • conditional (must specify master_ci_condition)
  • most_related_items – Attributes to be merged from the CI with the most related items to the main CI.
  • most_relations – Attributes to be merged from the CI with the most relationships to the main CI.
  • newest_created – separated attributes to be merged from the most recently updated CI to the main CI.
  • oldest_created – Comma-separated attributes to be merged from the oldest-created CI to the main CI.
template.master_ci_condition String Optional (required if the value of master_ci_option is conditional). Encoded query to specify how the main CI is selected. If multiple CIs or no CIs match the query, the method selects the most recently updated CI as the main CI. The encoded query is evaluated for the template table. This table is identified in the table property.

For details, see Encoded query strings .
template.merge_relations String Optional. Specifies how the relationships for duplicate CIs within a de-duplication task are merged when applying this template.
Possible options:
  • all
  • conditional
  • none
template.merge_relations String Optional. Specifies how the relationships for duplicate CIs within a de-duplication task are merged when applying this template.
Possible options:
  • all
  • conditional
  • none
template.merge_relations_​condition String Optional (required if the value of merge_relations is conditional). Encoded query to specify if all or none of the relationships from duplicate CIs are merged. The query is evaluated on the main CI that is selected for the de-duplication task. If the query returns true, all relationships are merged. If false, no relationships are merged.

The encoded query is evaluated for the template table. This table is identified in the table property.

For details, see Encoded query strings .
template.merge_related_items String Optional. Specifies which related tables for duplicate CIs within a de-duplication task are merged to the main CI when applying this template. See also Remediate a de-duplication task (legacy).
Possible options:
  • all_available – Includes the default-related tables and any related tables that reference duplicate CIs for the de-duplication task remediated via the template.
  • conditional
  • default – Includes related entries provided by the Duplicate CI Remediator Default Related Items module.
  • none
template.merge_related_items_​condition Array Optional. List of related entries with an encoded query for each related entry. Each query is evaluated on the main CI that is selected for the task. If the query returns true, the related entries are merged during the remediation of a de-duplication task. If false, related entries aren’t merged.
"merge_related_items_condition": [
  {
    "related_entry": "String",
    "condition": "String"
  }
]

For details, see Encoded query strings .
template.most_relations_​merge_attributes String Optional. Comma-separated attributes to be merged from the CI with the most relationships to the main CI.
template.most_related_items_​merge_attributes String Optional. Comma-separated attributes to be merged from the CI with the most related items to the main CI.
template.name String Name of the template.
template.newest_updated_​merge_attributes String Optional. Comma-separated attributes to be merged from the most recently updated CI to the main CI.
template.oldest_created_​merge_attributes String Optional. Comma-separated attributes to be merged from the oldest-created CI to the main CI.
template.table String Table for which the template is created.
template.task_conditions String Optional. Encoded query to be evaluated when the template runs. This query is evaluated on the Reconcile Duplicate Task Data [reconcile_duplicate_task_data] table. All tasks returned from this query are considered during the template evaluation.
Note: Even if a task is returned as a part of the query, it doesn’t guarantee that the template run processes the task. Other factors might cause the task to be skipped during template processing.

For details, see Encoded query strings .
Table 4. Returns
Type Description
String Sys_id of the template created in the Reconcile Duplicate Templates [reconcile_duplicate_template] table.

Example

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.

Table 5. Parameters
Name Type Description
templateId String Sys_id of the template listed in the Reconcile Duplicate Template [reconcile_duplicate_template] table.
Table 6. Returns
TypeDescription
Object The template object with different options for creating the template.
{
  "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"
}
<Object>.allow_null_ attribute_update Flag that indicates if main CI attributes are updated with null values from duplicate CIs when resolving attribute conflicts for CIs within a de-duplication task.
Valid values:
  • true: The main CI attributes are updated with null values from duplicate CIs.
  • false: The main CI attributes aren’t updated with null values from duplicate CIs.

Data type: Boolean
<Object>.allow_master_ci_ null_update Only includes updates from duplicate CIs if the main CI value is null.
Valid values:
  • true: Only include updates from duplicate CIs if the main CI value is null.
  • false: Include updates from all duplicate CIs.

Data type: Boolean
<Object>.description Description to store more information about the template.

Data type: String
<Object>.duplicate_ ci_action Specifies if the duplicate CI is to be deleted or updated with unique custom values.
Possible options:
  • delete
  • update (requires specifying duplicate_ci_updates)

Data type: String
<Object>.duplicate_ ci_updates Array of objects specifying how the duplicate CI values are updated.
[
  {
    "element": "String",
    "element_label": "String",
    "value": "String",
    "display": "String"
  }
]

Data type: Object
<Object>.duplicateCIUpdates.element The system dictionary name of a reference field.

Data type: String
<Object>.duplicateCIUpdates.element_label The label that the reference field displays.

Data type: String
<Object>.duplicateCIUpdates.value Value for a reference field, that is, the contents of the reference field.

Data type: String
<Object>.duplicateCIUpdates.display Display value for a reference field.

Data type: String
<Object>.master_ci_ option Specifies how the main CI is selected for a de-duplication task when applying this template.
Possible options:
  • conditional (must specify master_ci_condition)
  • most_related_items – Attributes to be merged from the CI with the most related items to the main CI.
  • most_relations – Attributes to be merged from the CI with the most relationships to the main CI.
  • newest_created – separated attributes to be merged from the most recently updated CI to the main CI.
  • oldest_created – Comma-separated attributes to be merged from the oldest-created CI to the main CI.

Data type: String
<Object>.merge_relations Specifies how the relationships for duplicate CIs within a de-duplication task are merged when applying this template.
Possible options:
  • all
  • conditional
  • none

Data type: String
<Object>.merge_related_items Specifies which related tables for duplicate CIs within a de-duplication task are merged to the main CI when applying this template. See also Remediate a de-duplication task (legacy).
Possible options:
  • all_available – Includes the default-related tables and any related tables that reference duplicate CIs for the de-duplication task remediated via the template.
  • conditional
  • default – Includes related entries provided by the Duplicate CI Remediator Default Related Items module.
  • none

Data type: String
<Object>.merge_related_items_ condition List of related entries with an encoded query for each related entry. Each query is evaluated on the main CI that is selected for the task. If the query returns true, the related entries are merged during the remediation of a de-duplication task. If false, related entries aren’t merged.

For details, see Encoded query strings .

Data type: Array
<Object>.most_relations_ merge_attributes Comma-separated attributes to be merged from the CI with the most relationships to the main CI.

Data type: String
<Object>.most_related_items_ merge_attributes Comma-separated attributes to be merged from the CI with the most related items to the main CI.

Data type: String
<Object>.name Name of the template.

Data type: String
<Object>.newest_updated_ merge_attributes Comma-separated attributes to be merged from the most recently updated CI to the main CI.

Data type: String
<Object>.oldest_created_ merge_attributes Comma-separated attributes to be merged from the oldest-created CI to the main CI.

Data type: String
<Object>.table Table for which the template is created.

Data type: String
<Object>.task_condition_table Location of the table task conditions, that is, the Reconcile Duplicate Task Data [reconcile_duplicate_task_data] table. The value never changes and the table is intended for internal use only.

Data type: String
<Object>.task_conditions Encoded query to be evaluated when the template runs. This query is evaluated on the Reconcile Duplicate Task Data [reconcile_duplicate_task_data] table. All tasks returned from this query are considered during the template evaluation.
Note: Even if a task is returned as a part of the query, it doesn’t guarantee that the template run processes the task. Other factors might cause the task to be skipped during template processing.

For details, see Encoded query strings .

Data type: String

Example

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.

Table 7. Parameters
Name Type Description
templateId String Sys_id of the template listed in the Reconcile Duplicate Template [reconcile_duplicate_template] table.
taskId String Sys_id of the de-duplication task listed in the Remediate Duplicate Task [reconcile_duplicate_task] table.
Table 8. Returns
TypeDescription
Object Preview object with values showing how the de-duplication tasks can be remediated using the template.
{
  "allClassCIMap": {Object},
  "duplicateCIAction": "String",
  "duplicateCIUpdates": [Array],
  "masterCI": "String",
  "mergeRelations": Boolean,
  "relatedTablesMerged": [Array],  
  "resolvedFieldCIMap": [Array],
  "taskId": "String",
  "tooManyDuplicates": Boolean
}
<Object>.allClassCIMap List of sys_ids of the CIs within a de-duplication task, grouped by CI class. For example, cmdb_ci_computer.
"allClassCIMap": {
  "<ci_class_name>": [
    "<ci_sys_id_1>",
    "<ci_sys_id_2>"
  ]
}

Data type: Object
<Object>.duplicateCIAction Specifies if the duplicate CI is to be deleted or updated with unique custom values.
Possible options:
  • delete
  • update (requires specifying duplicate_ci_updates)

Data type: String
<Object>.duplicateCIUpdates Array of objects specifying how the duplicate CI values are updated.
[
  {
    "element": "String",
    "element_label": "String",
    "value": "String",
    "display": "String"
  }
]

Data type: Array
<Object>.duplicateCIUpdates.element The system dictionary name of a reference field.

Data type: String
<Object>.duplicateCIUpdates.element_label The label that the reference field displays.

Data type: String
<Object>.duplicateCIUpdates.value Value for a reference field, that is, the contents of the reference field.

Data type: String
<Object>.duplicateCIUpdates.display Display value for a reference field.

Data type: String
<Object>.masterCI Sys_id of the CI that was selected as the main CI.

Data type: String
<Object>.mergeRelations Specifies how the relationships for duplicate CIs within a de-duplication task are merged when applying this template.
Possible options:
  • all
  • conditional
  • none

Data type: String
<Object>.relatedTablesMerged Specifies which related tables for duplicate CIs within a de-duplication task are merged to the main CI when applying this template. See also Remediate a de-duplication task (legacy).
Possible options:
  • all_available – Includes the default-related tables and any related tables that reference duplicate CIs for the de-duplication task remediated via the template.
  • conditional
  • default – Includes related entries provided by the Duplicate CI Remediator Default Related Items module.
  • none

Data type: Array
<Object>.resolvedFieldCIMap Array of elements to be merged from duplicate CIs to the main CI.
"resolvedFieldCIMap": [
  {
    "element": "String",
    "sys_id": "String"
  }
]

Data type: Array
<Object>.resolvedFieldCIMap.​element Name of the element to be merged from a duplicate CI to the main CI.

Data type: String
<Object>.resolvedFieldCIMap.​sys_id Sys_id of the element to be merged from a duplicate CI to the main CI.

Data type: String
<Object>.taskId Sys_id of the de-duplication task listed in the Remediate Duplicate Task [reconcile_duplicate_task] table.

Data type: String
<Object>.tooManyDuplicates Flag that indicates whether the task has more than the maximum number of CIs. The threshold is determined by comparing the value of the system property glide.duplicate_ci_ remediator.max.cis (default value 1000 CIs).
Valid values:
  • true: Task number of CIs exceeds the maximum number of CIs.
  • false: Task number of CIs don't exceed the maximum number of CIs.

Data type: Boolean

Example

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:
Table 9. Parameters
Name Type Description
templateId String Sys_id of the template listed in the Reconcile Duplicate Template [reconcile_duplicate_template] table.
Table 10. Returns
Type Description
Boolean

Flag that indicates whether the template was published.

Valid values:
  • true: The template was published.
  • false: The template wasn’t published.

Example

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.
Table 11. Parameters
Name Type Description
templateId String Sys_id of the template listed in the Reconcile Duplicate Template [reconcile_duplicate_template] table.
taskId String Sys_id of the de-duplication task listed in the Remediate Duplicate Task [reconcile_duplicate_task] table.
Table 12. Returns
Type Description
String If successful, the merge resolution ID for the de-duplication task remediation. This merge resolution ID the sys_id of a record in the Duplicate CI Remediation [cmdb_duplicate_ci_remediation] table. If unsuccessful, the template might not be in the published state.

Example

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:
Table 13. Parameters
Name Type Description
templateRunId String Sys_id of the template run listed in the De-Duplication Template Run [reconcile_duplicate_template_run] table.
Table 14. Returns
Type Description
String

Flag that indicates whether the cancel request was successful.

Valid values:
  • true: The cancel request was successful.
  • false: The cancel request wasn’t successful.

Example

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:
Table 15. Parameters
Name Type Description
templateId String Sys_id of the template listed in the Reconcile Duplicate Template [reconcile_duplicate_template] table.
Table 16. Returns
Type Description
Boolean Flag that indicates whether the template is retired.
Valid values:
  • true: The template is retired.
  • false: The template couldn’t be retired because it was running, scheduled to be run, or in published state

Example

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.

Table 17. Parameters
Name Type Description
templateId String Sys_id of the template listed in the Reconcile Duplicate Template [reconcile_duplicate_template] table.
Table 18. Returns
Type Description
String Sys_id of the template that was run listed in the De-Duplication Template Run [reconcile_duplicate_template_run] table. If unsuccessful, the template might not be in published state.

Example

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:
Table 19. Parameters
Name Type Description
templateId String Sys_id of the template listed in the Reconcile Duplicate Template [reconcile_duplicate_template] table.
Table 20. Returns
Type Description
Boolean

Flag that indicates whether the template was successfully unpublished.

Valid values:
  • true: The template was successfully unpublished.
  • false: The template wasn’t successfully unpublished. The template might be running or scheduled to be run.

Example

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:
Table 21. Parameters
NameTypeDescription
templateId String Sys_id of the template listed in the Reconcile Duplicate Template [reconcile_duplicate_template] table.
template Object The template object with different options for creating the template. 
{
  "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"
}
template.allow_null_​attribute_update Boolean Optional. Flag that indicates if main CI attributes are updated with null values from duplicate CIs when resolving attribute conflicts for CIs within a de-duplication task.
Valid values:
  • true: The main CI attributes are updated with null values from duplicate CIs.
  • false: The main CI attributes aren’t updated with null values from duplicate CIs.

Default: False
template.allow_master_ci_​null_update Boolean Optional. Only includes updates from duplicate CIs if the main CI value is null.

Flag that indicates whether to include only updates from duplicate CIs if the main CI value is null.

Valid values:
  • true: Only include updates from duplicate CIs if the main CI value is null.
  • false: Include updates from all duplicate CIs.

Default: False
template.description String Optional. Description to store more information about the template.
template.duplicate_​ci_action String Optional. Specifies if the duplicate CI is to be deleted or updated with unique custom values.
Possible options:
  • delete
  • update (requires specifying duplicate_ci_updates)
template.duplicate_​ci_updates Array Optional, unless the setting for duplicate_ci_action is update. Array of objects specifying how the duplicate CI values are updated.
[
  {
    "element": "String",
    "element_label": "String",
    "value": "String",
    "display": "String"
  }
]
template.duplicate_​ci_updates.element String The system dictionary name of a reference field.
template.duplicate_​ci_updates.element_label String The label that the reference field displays.
template.duplicate_​ci_updates.value String Value for a reference field, that is, the contents of the reference field.
template.duplicate_​ci_updates.display String Display value for a reference field.
template.master_ci_​option String Optional. Specifies how the main CI is selected for a de-duplication task when applying this template.
Possible options:
  • conditional (must specify master_ci_condition)
  • most_related_items – Attributes to be merged from the CI with the most related items to the main CI.
  • most_relations – Attributes to be merged from the CI with the most relationships to the main CI.
  • newest_created – separated attributes to be merged from the most recently updated CI to the main CI.
  • oldest_created – Comma-separated attributes to be merged from the oldest-created CI to the main CI.
template.master_ci_condition String Optional (required if the value of master_ci_option is conditional). Encoded query to specify how the main CI is selected. If multiple CIs or no CIs match the query, the method selects the most recently updated CI as the main CI. The encoded query is evaluated for the template table. This table is identified in the table property.

For details, see Encoded query strings .
template.merge_relations String Optional. Specifies how the relationships for duplicate CIs within a de-duplication task are merged when applying this template.
Possible options:
  • all
  • conditional
  • none
template.merge_relations String Optional. Specifies how the relationships for duplicate CIs within a de-duplication task are merged when applying this template.
Possible options:
  • all
  • conditional
  • none
template.merge_relations_​condition String Optional (required if the value of merge_relations is conditional). Encoded query to specify if all or none of the relationships from duplicate CIs are merged. The query is evaluated on the main CI that is selected for the de-duplication task. If the query returns true, all relationships are merged. If false, no relationships are merged.

The encoded query is evaluated for the template table. This table is identified in the table property.

For details, see Encoded query strings .
template.merge_related_items String Optional. Specifies which related tables for duplicate CIs within a de-duplication task are merged to the main CI when applying this template. See also Remediate a de-duplication task (legacy).
Possible options:
  • all_available – Includes the default-related tables and any related tables that reference duplicate CIs for the de-duplication task remediated via the template.
  • conditional
  • default – Includes related entries provided by the Duplicate CI Remediator Default Related Items module.
  • none
template.merge_related_items_​condition Array Optional. List of related entries with an encoded query for each related entry. Each query is evaluated on the main CI that is selected for the task. If the query returns true, the related entries are merged during the remediation of a de-duplication task. If false, related entries aren’t merged.
"merge_related_items_condition": [
  {
    "related_entry": "String",
    "condition": "String"
  }
]

For details, see Encoded query strings .
template.most_relations_​merge_attributes String Optional. Comma-separated attributes to be merged from the CI with the most relationships to the main CI.
template.most_related_items_​merge_attributes String Optional. Comma-separated attributes to be merged from the CI with the most related items to the main CI.
template.name String Name of the template.
template.newest_updated_​merge_attributes String Optional. Comma-separated attributes to be merged from the most recently updated CI to the main CI.
template.oldest_created_​merge_attributes String Optional. Comma-separated attributes to be merged from the oldest-created CI to the main CI.
template.table String Table for which the template is created.
template.task_conditions String Optional. Encoded query to be evaluated when the template runs. This query is evaluated on the Reconcile Duplicate Task Data [reconcile_duplicate_task_data] table. All tasks returned from this query are considered during the template evaluation.
Note: Even if a task is returned as a part of the query, it doesn’t guarantee that the template run processes the task. Other factors might cause the task to be skipped during template processing.

For details, see Encoded query strings .
Table 22. Returns
Type Description
Boolean

Flag that indicates whether the template was updated.

Valid values:
  • true: The template was updated.
  • false: The template was updated. The template might not be in draft (unpublished) state.

Example

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