1. Introduction

This document is a guide which will walk you through SnowMirror REST API. The purpose of the REST API is to allow developers to integrate SnowMirror with other applications.

1.1. URIs of REST API Resources

The API consists of resources identified by URIs. To call the API you have to make HTTP requests on the provided URIs. The URIs have following structure:

http://{hostname}:{port}/api/{api-version}/{resource-name}

  • hostname - name of the server where SnowMirror is running

  • port - port on which SnowMirror is running

  • api-version - the version of the API to be used. Currently the options "v1" and "v2" are available. The "v2" option is preferred. For differences in how to work with resources in different api versions, see the relevant section on resources in this documentation.

  • resource-name - name of the resource you need to operate on. The resources are described in the following chapter

Let’s say you need to get information about a synchronization. Then you will have to make GET HTTP request on a resource called http://yourSnowMirrorServer:9090/api/v2/synchronization

Also note that resources are secured. Please see Authentication and Security chapter for details.

2. Resources

2.1. /synchronization

2.1.1. GET

Returns a list of all synchronizations.

Available Responses:

  • 200 - A list of synchronizations was successfully retrieved. (V2 api)

    Sample Response Body (Content-Type: application/json):

    {
        "syncs": [
            {
                "id": 24,
                "name": "incident",
                "table": "incident",
                "mirrorTable": "incident",
                "columns": [
                    {
                        "name": "active",
                        "sysId": "8f2f4b99e1031100a24720593d95f563"
                    },
                    {
                        "name": "sys_id",
                        "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                    }
                ],
                "allowInheritedColumns": true,
                "referenceFieldType": "BOTH",
                "autoSchemaUpdate": false,
                "encodedQuery": null,
                "deleteStrategy": "AUDIT",
                "active": true,
                "scheduler": {
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07"
                },
                "additionalSchedulers": [
                    {
                        "executionType": "CLEAN_AND_SYNCHRONIZE",
                        "type": "MANUALLY",
                        "beginDate": "2014-08-07"
                    }
                ],
                "schedulerPriority": "NORMAL",
                "mirrorDbId": 1,
                "tags": [
                    {
                        "name": "Daily",
                        "color": "#123123"
                    }
                ]
            },
            {
                "id": 25,
                "name": "incident_sla",
                "view": "incident_sla",
                "mirrorTable": "incident_sla",
                "columns": [
                    {
                        "prefix": "taskslatable",
                        "name": "taskslatable_sla",
                        "sysId": "d9719f5de1031100a24720593d95f53b"
                    },
                    {
                        "prefix": "inc",
                        "name": "inc_priority",
                        "sysId": "c72f4b99e1031100a24720593d95f56d"
                    }
                ],
                "allowInheritedColumns": false,
                "referenceFieldType": "BOTH",
                "autoSchemaUpdate": false,
                "encodedQuery": null,
                "deleteStrategy": "TRUNCATE",
                "active": true,
                "scheduler": {
                    "type": "DAILY",
                    "beginDate": "2014-08-07",
                    "time": "00:00"
                },
                "additionalSchedulers": [
                    {
                        "executionType": "CLEAN_AND_SYNCHRONIZE",
                        "type": "DAILY",
                        "beginDate": "2014-08-07",
                        "time": "00:00"
                    }
                ],
                "schedulerPriority": "NORMAL",
                "mirrorDbId": 1
            },
            {
                "id": 2,
                "name": "u_rest_test_table_backup-ecf7afd3902e46aabc6b4266ae20f694",
                "backup": "u_rest_test_table",
                "mirrorTable": null,
                "columns": [
                    {
                      "name": "sys_id",
                      "sysId": "d58564b74ff112002a9053418110c7d2"
                    }
                ],
                "allowInheritedColumns": false,
                "autoSchemaUpdate": false,
                "referenceFieldType": "SYS_IDS",
                "encodedQuery": null,
                "deleteStrategy": "NONE",
                "active": true,
                "scheduler": {
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07",
                    "time": "04:00",
                    "visible": false
                },
                "schedulerPriority": "NORMAL",
                "synchronizationType": null,
                "masterTable": null,
                "attachmentDirectory": null,
                "retentionPeriod": 30,
                "format": "CSV",
                "updateBeforeSynchronizationRun": false,
                "mirrorDbId": 1,
                "tags": [
                    {
                        "name": "Daily",
                        "color": "#123123"
                    }
                ]
            }
        ]
    }
  • 200 - A list of synchronizations was successfully retrieved. (V1 api)

    Sample Response Body (Content-Type: application/json):

    {
        "syncs": [
            {
                "id": 24,
                "name": "incident",
                "table": "incident",
                "mirrorTable": "incident",
                "columns": [
                    {
                        "name": "active",
                        "sysId": "8f2f4b99e1031100a24720593d95f563"
                    },
                    {
                        "name": "sys_id",
                        "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                    }
                ],
                "allowInheritedColumns": true,
                "referenceFieldType": "BOTH",
                "autoSchemaUpdate": false,
                "encodedQuery": null,
                "deleteStrategy": "AUDIT",
                "active": true,
                "scheduler": {
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07"
                },
                "fullLoadScheduler": {
                	"executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07"
                },
                "schedulerPriority": "NORMAL",
                "mirrorDbId": 1,
                "tags": [
                    {
                        "name": "Daily",
                        "color": "#123123"
                    }
                ]
            },
            {
                "id": 25,
                "name": "incident_sla",
                "view": "incident_sla",
                "mirrorTable": "incident_sla",
                "columns": [
                    {
                        "prefix": "taskslatable",
                        "name": "taskslatable_sla",
                        "sysId": "d9719f5de1031100a24720593d95f53b"
                    },
                    {
                        "prefix": "inc",
                        "name": "inc_priority",
                        "sysId": "c72f4b99e1031100a24720593d95f56d"
                    }
                ],
                "allowInheritedColumns": false,
                "referenceFieldType": "BOTH",
                "autoSchemaUpdate": false,
                "encodedQuery": null,
                "deleteStrategy": "TRUNCATE",
                "active": true,
                "scheduler": {
                    "type": "DAILY",
                    "beginDate": "2014-08-07",
                    "time": "00:00"
                },
                "fullLoadScheduler": {
                	"executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "DAILY",
                    "beginDate": "2014-08-07",
                    "time": "00:00"
                },
                "schedulerPriority": "NORMAL",
                "mirrorDbId": 1
            },
            {
                "id": 2,
                "name": "u_rest_test_table_backup-ecf7afd3902e46aabc6b4266ae20f694",
                "backup": "u_rest_test_table",
                "mirrorTable": null,
                "columns": [
                    {
                        "name": "sys_id",
                        "sysId": "d58564b74ff112002a9053418110c7d2"
                    }
                ],
                "allowInheritedColumns": false,
                "autoSchemaUpdate": false,
                "referenceFieldType": "SYS_IDS",
                "encodedQuery": null,
                "deleteStrategy": "NONE",
                "active": true,
                "scheduler": {
                  "type": "MANUALLY",
                  "beginDate": "2014-08-07",
                  "time": "04:00",
                  "visible": false
                },
                "schedulerPriority": "NORMAL",
                "synchronizationType": null,
                "masterTable": null,
                "attachmentDirectory": null,
                "retentionPeriod": 30,
                "format": "CSV",
                "updateBeforeSynchronizationRun": false,
                "mirrorDbId": 1,
                "tags": [
                    {
                        "name": "Daily",
                        "color": "#123123"
                    }
                ]
            }
        ]
    }

2.1.2. POST

Creates a new synchronization. Returns newly created synchronization including its ID.

Table 1. Request Body Attributes
Attribute Description

name

Display name of the synchronization.

table

Name of the table in ServiceNow. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

view

Name of the view in ServiceNow. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

attachment

Name of the table in ServiceNow which attachments will be synchronized. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

backup

Name of the table in ServiceNow to backup to a file. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

backupAttachment

Name of the table in ServiceNow which attachments you want to backup. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

mirrorTable

Name of the table in mirror database where the data will be migrated.

columns

A list of columns to synchronize. If some of the columns does not exist in ServiceNow then it is ignored in SnowMirror. This attribute is mandatory for tables and view. It must not be used for attachments.
If Auto Schema Update (autoSchemaUpdate field) is Enabled or Enabled (no truncation), you can leave this field empty (colums: []) and SnowMirror will automatically add all columns except for those listed in (columnsToExclude field).
SnowMirror always automatically adds SysId column.
Each column consists of:
prefix - prefix of the column (has to be filled in only when synchronizing views)
name - name of the column to synchronize
sys_id - SysId of the column to synchronize

columnsToExclude

A list of columns not to synchronize. If some of the columns does not exist in ServiceNow then it is ignored in SnowMirror. This attribute is optional.
Each column consists of:
prefix - prefix of the column (has to be filled in only when synchronizing views)
name - name of the column to synchronize
sys_id - SysId of the column to synchronize

allowInheritedColumns

SnowMirror checks if columns exist in ServiceNow. If this flag is set to true, SnowMirror will also consider columns which a table inherited from its parent tables. If set to false, all columns which a table inherited from its parent tables will be ignored.
This flag is only applicable to tables. When synchronizing a view do not specify this attribute.
Allowed values: true, false

referenceFieldType

Defines how to synchronize reference field types. SnowMirror can synchronize sys_ids to the reference field or its display value or both of them.
Allowed values: SYS_IDS, DISPLAY_VALUES, BOTH

updateBeforeSynchronizationRun

Deprecated - use "autoSchemaUpdate" instead. The same as "autoSchemaUpdate".

autoSchemaUpdate

Configures how to check for schema changes in ServiceNow.

Enabled (true) - whenever a synchronization is executed, SnowMirror checks for schema changes in ServiceNow. Automatically adds, updates (data type, max. length of a column) and removes columns. If a new column is added SnowMirror clears the mirror table and downloads all records from scratch.

Enabled (no truncation) (ENABLED_WITHOUT_TRUNCATION) - the same as Enabled option. It handles new columns differently, though. If a new column is added SnowMirror does not clear the mirror table. Instead, it creates the column and populates it with a default value (which is defined in ServiceNow).

Disabled (false) - SnowMirror does not check for schema changes at all.

Allowed values: true, false, ENABLED_WITHOUT_TRUNCATION

encodedQuery

Encoded query used for filtering data in ServiceNow. See ServiceNow wiki for details

deleteStrategy

Specifies how the data will be deleted from mirror database based on deletes in ServiceNow. For details about the strategies see Delete Strategy section in User Manual.
Allowed values: AUDIT, TRUNCATE, DIFF or NONE

active

true - synchronization is active and can be scheduled to synchronize data from ServiceNow
false - synchronization is deactivated and cannot be scheduled to synchronize data from ServiceNow
Allowed values: true, false

runImmediately

Determines whether initial synchronization should be done
Allowed values: true, false (default)

scheduler

Specifies when the incremental load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON

fullLoadScheduler v1 api only

Specifies when the full load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON.

fullLoadScheduler.executionType v1 api only

Name of an action to perform during synchronization. Allowed values: CLEAN_AND_SYNCHRONIZE, DIFFERENTIAL.

additionalSchedulers v2 api only

Specifies when the additional synchronizations will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON.

additionalSchedulers[].executionType v2 api only

Name of an action to perform during synchronization. Allowed values: INCREMENTAL_SYNCHRONIZATION, INCREMENTAL_BACKUP, DIFFERENTIAL_BACKUP, CLEAN_AND_SYNCHRONIZE, DIFFERENTIAL_SYNCHRONIZATION, SYNC_FROM

schedulerPriority

Execution priority of the job. Allowed values: HIGHEST, HIGH, NORMAL, LOW, LOWEST

retentionPeriod

How many days to keep backups

format

How to store backups. "CSV" - comma separated file. "XML" - XML files. Allowed values: CSV, XML

mirrorDbId

Specifies which database will be used to store synchronized data. Allowed values are ids of configured databases. Please see GET. If parameter is not used, default database will be used.

tags since 5.8.0

Specifies which tags will be assigned to the given synchronization.

Request Body Format:

  • Full Request for Table Synchronization (V2 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "name": "incident",
            "table": "incident",
            "mirrorTable": "incident",
            "columns": [
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                },
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                }
            ],
            "columnsToExclude": [
                {
                    "name": "sys_created_by",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": "",
            "deleteStrategy": "AUDIT",
            "active": true,
            "runImmediately": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "additionalSchedulers": [
                {
                    "executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07"
                }
            ],
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Full Request for View Synchronization (V2 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "name": "incident_sla",
            "view": "incident_sla",
            "mirrorTable": "incident_sla",
            "columns": [
                    {
                        "prefix": "taskslatable",
                        "name": "taskslatable_sla",
                        "sysId": "d9719f5de1031100a24720593d95f53b"
                    },
                    {
                        "prefix": "inc",
                        "name": "inc_priority",
                        "sysId": "c72f4b99e1031100a24720593d95f56d"
                    }
                ],
            "encodedQuery": "",
            "deleteStrategy": "TRUNCATE",
            "active": true,
            "runImmediately": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "additionalSchedulers": [
                {
                    "executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07"
                }
            ],
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Full Request for Attachment Synchronization

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "name": "incident_attachment",
            "attachment": "incident",
            "mirrorTable": "incident_attachment",
            "encodedQuery": "",
            "deleteStrategy": "DIFF",
            "active": true,
            "runImmediately": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "additionalSchedulers": [
                {
                    "executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07"
                }
            ],
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Full Request for Backup Synchronization (V2 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "name": "incident",
            "backup": "incident",
            "columns": [
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                },
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": "",
            "deleteStrategy": "NONE",
            "active": true,
            "runImmediately": true,
    		"retentionPeriod": 30,
    		"format": "CSV",
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "additionalSchedulers": [
                {
                    "executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07"
                }
            ],
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Full Request for Backup Attachment Synchronization (V2 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "name": "incident",
            "backupAttachment": "incident",
            "encodedQuery": "",
            "deleteStrategy": "NONE",
            "active": true,
            "runImmediately": true,
            "retentionPeriod": 30,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07",
                "incLoadExecutionType": "INCREMENTAL_BACKUP"
            },
            "additionalSchedulers": [
                {
                    "executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07"
                }
            ],
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Full Request for Table Synchronization (V1 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "name": "incident",
            "table": "incident",
            "mirrorTable": "incident",
            "columns": [
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                },
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                }
            ],
            "columnsToExclude": [
                {
                    "name": "sys_created_by",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": "",
            "deleteStrategy": "AUDIT",
            "active": true,
            "runImmediately": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "fullLoadScheduler": {
            	"executionType": "CLEAN_AND_SYNCHRONIZE",
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Full Request for View Synchronization (V1 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "name": "incident_sla",
            "view": "incident_sla",
            "mirrorTable": "incident_sla",
            "columns": [
                    {
                        "prefix": "taskslatable",
                        "name": "taskslatable_sla",
                        "sysId": "d9719f5de1031100a24720593d95f53b"
                    },
                    {
                        "prefix": "inc",
                        "name": "inc_priority",
                        "sysId": "c72f4b99e1031100a24720593d95f56d"
                    }
                ],
            "encodedQuery": "",
            "deleteStrategy": "TRUNCATE",
            "active": true,
            "runImmediately": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "fullLoadScheduler": {
            	"executionType": "CLEAN_AND_SYNCHRONIZE",
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Full Request for Attachment Synchronization (V1 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "name": "incident_attachment",
            "attachment": "incident",
            "mirrorTable": "incident_attachment",
            "encodedQuery": "",
            "deleteStrategy": "DIFF",
            "active": true,
            "runImmediately": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "fullLoadScheduler": {
            	"executionType": "CLEAN_AND_SYNCHRONIZE",
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Full Request for Backup Synchronization (V1 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "name": "incident",
            "backup": "incident",
            "columns": [
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                },
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": "",
            "deleteStrategy": "NONE",
            "active": true,
            "runImmediately": true,
    		"retentionPeriod": 30,
    		"format": "CSV",
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "fullLoadScheduler": {
            	"executionType": "CLEAN_AND_SYNCHRONIZE",
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Full Request for Backup Attachment Synchronization (V1 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "name": "incident",
            "backupAttachment": "incident",
            "encodedQuery": "",
            "deleteStrategy": "NONE",
            "active": true,
            "runImmediately": true,
            "retentionPeriod": 30,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07",
                "incLoadExecutionType": "INCREMENTAL_BACKUP"
            },
            "fullLoadScheduler": {
            	"executionType": "CLEAN_AND_SYNCHRONIZE",
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "schedulerPriority": "NORMAL".
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Manual Scheduler

    Sample Request Body With Manual Scheduler:

    {
        "sync": {
            ...
    
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            }
    
            ...
        }
    }
  • Daily Scheduler

    Sample Request Body With Daily Scheduler:

    {
        "sync": {
            ...
    
            "scheduler": {
                "type": "DAILY",
                "beginDate": "2014-08-08",
                "time": "22:00"
            }
    
            ...
        }
    }
  • Weekly Scheduler

    Sample Request Body With Weekly Scheduler:

    {
        "sync": {
            ...
    
            "scheduler": {
                "type": "WEEKLY",
                "beginDate": "2014-08-08",
                "time": "22:00",
                "days": [ "MONDAY", "FRIDAY" ]
            }
    
            ...
        }
    }
  • Periodical Scheduler

    Sample Request Body With Periodical Scheduler:

    {
        "sync": {
            ...
    
            "scheduler": {
                "type": "PERIODICALLY",
                "beginDate": "2014-08-08",
                "time": "22:00",
                "interval": "120"
            }
    
            ...
        }
    }
  • Cron Scheduler

    Sample Request Body With Cron Scheduler:

    {
        "sync": {
            ...
    
            "scheduler": {
                "type": "CRON",
                "beginDate": "2014-08-08",
                "cronExpression": "0 0 12 * * ?"
            }
    
            ...
        }
    }

Available Responses:

  • 200 - Synchronization was successfully created. (V2 api)

    Sample Response Body (Content-Type: application/json):

    {
        "sync": {
            "id": 1,
            "name": "incident",
            "table": "incident",
            "mirrorTable": "incident",
            "columns": [
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                },
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": null,
            "deleteStrategy": "AUDIT",
            "active": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "additionalSchedulers": [
                {
                    "executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07"
                }
            ],
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • 200 - Synchronization was successfully created. (V1 api)

    Sample Response Body (Content-Type: application/json):

    {
        "sync": {
            "id": 1,
            "name": "incident",
            "table": "incident",
            "mirrorTable": "incident",
            "columns": [
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                },
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": null,
            "deleteStrategy": "AUDIT",
            "active": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "fullLoadScheduler": {
            	"executionType": "CLEAN_AND_SYNCHRONIZE",
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • 400 - Could not parse a request or validations failed.

2.1.3. DELETE

Deletes synchronizations. To be able to delete a synchronization it must not be running.

URL parameter Description

deleteTables

Decides if mirrored tables will be kept in database. Allowed values: true, false

* true - tables with mirrored data will be deleted
* false - tables with mirrored data will be kept in database

Request Format:

  • Full Request

    Sample Request body (Content-Type: application/json):

    {
        "ids": [ 1, 42 ]
    }

Available Responses:

  • 200 - Synchronizations has been successfully deleted.

  • 400 - Could not parse a request.

  • 404 - No synchronization was deleted because at least one of the synchronizations could not be found.

2.2. /synchronization/action

2.2.1. GET

Returns a list of all actions which can be performed on synchronizations.

Available Responses:

  • 200 - A list of actions was successfully retrieved.

    Sample Response Body (Content-Type: application/json):

    {
        "actions": [
            "SYNCHRONIZE",
            "CLEAN_AND_SYNCHRONIZE",
            "DIFFERENTIAL_SYNCHRONIZATION",
            "SYNC_FROM",
            "STOP_SYNCHRONIZATION"
        ]
    }

2.2.2. POST

Performs an action on the selected synchronizations.
API ignores synchronizations which are already running. It also ignores synchronizations which are deactivated.
Available actions are "SYNCHRONIZE", "CLEAN_AND_SYNCHRONIZE", "DIFFERENTIAL_SYNCHRONIZATION", "SYNC_FROM", "STOP_SYNCHRONIZATION", "RESUME".

Request Body Format:

  • Full Request

    Sample Request Body (Content-Type: application/json):

    {
      "action": "SYNCHRONIZE",
      "ids": [ 1, 2, 3 ]
    }
  • Full Request for SYNC_FROM

    Sample Request Body (Content-Type: application/json):

    {
      "action": "SYNC_FROM",
      "syncFrom": "2024-16-04",
      "ids": [ 1, 2, 3 ]
    }

Available Responses:

  • 200 - An action has been successfully performed. Note that some synchronizations may be ignored.

    • SYNCHRONIZE sample response

      Sample Response Body (Content-Type: application/json):

      {
          "alreadyRunningSyncIds": [ 1 ],
          "disabledSyncIds": [ 2 ],
          "nonResumeSyncIds": []
      }
    • CLEAN_AND_SYNCHRONIZE sample response

      Sample Response Body (Content-Type: application/json):

      {
          "alreadyRunningSyncIds": [ 1 ],
          "disabledSyncIds": [ 2 ],
          "nonResumeSyncIds": []
      }
    • DIFFERENTIAL_SYNCHRONIZATION sample response

      Sample Response Body (Content-Type: application/json):

      {
          "alreadyRunningSyncIds": [ 1 ],
          "disabledSyncIds": [ 2 ],
          "fullLoadViewIds": [],
          "backupIds": [],
          "cloudIds": []
      }
    • SYNC_FROM sample response

      Sample Response Body (Content-Type: application/json):

      {
          "alreadyRunningSyncIds": [ 1 ],
          "disabledSyncIds": [ 2 ],
          "nonResumeSyncIds": []
      }
    • STOP_SYNCHRONIZATION sample response

      Sample Response Body (Content-Type: application/json):

      {
          "notRunningSyncIds": [ 1 ],
          "disabledSyncIds": [ 2 ]
      }
    • RESUME sample response

      Sample Response Body (Content-Type: application/json):

      {
          "alreadyRunningSyncIds": [ 1 ],
          "disabledSyncIds": [ 2 ],
          "nonResumeSyncIds": []
      }
  • 404 - No action has been performed because at least one of the synchronizations could not be found.

2.3. /synchronization/export

2.3.1. GET

Exports all synchronizations and their settings.

It does not export activity logs. If you import them to some other environment, you should run the synchronizations from scratch. It does not export global setting (Settings → General Settings nor Settings → Advanced Properties).

  • Sample response (V2 api)

    Sample Response Body:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <snowMirrorExport>
        <exportInfo>
            <exportDate>2022-10-11T11:14:28.205Z</exportDate>
            <serviceNowUrl>https://ven01469.service-now.com/</serviceNowUrl>
            <snowMirrorVersion>5.8.0</snowMirrorVersion>
        </exportInfo>
        <synchronizations>
            <synchronization>
                <synchronizationName>incident</synchronizationName>
                <enabled>true</enabled>
                <selectedTable>incident</selectedTable>
                <sncEncodedQuery></sncEncodedQuery>
                <sncObjectType>TABLE</sncObjectType>
                <includeInheritedColumns>true</includeInheritedColumns>
                <referenceFieldType>SYS_IDS</referenceFieldType>
                <deleteType>AUDIT</deleteType>
                <autoSchemaUpdate>DISABLED</autoSchemaUpdate>
                <mirrorTableName>incident</mirrorTableName>
                <checkRecordsMatchingQuery>true</checkRecordsMatchingQuery>
                <consistencyCheckAllowed>SYSTEM</consistencyCheckAllowed>
                <incrementalColumn>sys_updated_on</incrementalColumn>
                <scheduler>
                    <beginDate>2022-09-15T00:00:00Z</beginDate>
                    <executionType>INCREMENTAL_SYNCHRONIZATION</executionType>
                    <schedulerType>MANUALLY</schedulerType>
                </scheduler>
                <additionalSchedulers>
                    <additionalScheduler>
                        <beginDate>2022-09-15T00:00:00Z</beginDate>
                        <executionType>CLEAN_AND_SYNCHRONIZE</executionType>
                        <schedulerType>MANUALLY</schedulerType>
                    </additionalScheduler>
                </additionalSchedulers>
                <schedulerPriority>NORMAL</schedulerPriority>
                <columns>
                    <column>
                        <length>40</length>
                        <name>close_code</name>
                        <nameMapping>close_code</nameMapping>
                        <nameMappingDisplayValue>dv_close_code</nameMappingDisplayValue>
                        <type>string</type>
                    </column>
                    <column>
                        <length>32</length>
                        <name>sys_id</name>
                        <nameMapping>sys_id</nameMapping>
                        <type>GUID</type>
                    </column>
                </columns>
                <excludedColumns/>
                <options>
                    <option>
                        <key>diffCheckUpdates</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>dbCheckUpdates</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>cleanAndSyncToTmpTable</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>rotation</key>
                        <value>NOT_AVAILABLE</value>
                    </option>
                </options>
                <mirrorDbAlias>1</mirrorDbAlias>
                <tags>
                    <tag>
                        <color>#333399</color>
                        <name>Daily</name>
                    </tag>
                </tags>
            </synchronization>
        </synchronizations>
    </snowMirrorExport>
  • Sample response (V1 api)

    Sample Response Body:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <snowMirrorExport>
        <exportInfo>
            <exportDate>2022-10-11T11:14:28.205Z</exportDate>
            <serviceNowUrl>https://ven01469.service-now.com/</serviceNowUrl>
            <snowMirrorVersion>5.8.0</snowMirrorVersion>
        </exportInfo>
        <synchronizations>
            <synchronization>
                <synchronizationName>incident</synchronizationName>
                <enabled>true</enabled>
                <selectedTable>incident</selectedTable>
                <sncEncodedQuery></sncEncodedQuery>
                <sncObjectType>TABLE</sncObjectType>
                <includeInheritedColumns>true</includeInheritedColumns>
                <referenceFieldType>SYS_IDS</referenceFieldType>
                <deleteType>AUDIT</deleteType>
                <autoSchemaUpdate>DISABLED</autoSchemaUpdate>
                <mirrorTableName>incident</mirrorTableName>
                <checkRecordsMatchingQuery>true</checkRecordsMatchingQuery>
                <consistencyCheckAllowed>SYSTEM</consistencyCheckAllowed>
                <incrementalColumn>sys_updated_on</incrementalColumn>
                <scheduler>
                    <beginDate>2022-09-15T00:00:00Z</beginDate>
                    <incLoadExecutionType>INCREMENTAL_SYNCHRONIZATION</incLoadExecutionType>
                    <schedulerType>MANUALLY</schedulerType>
                </scheduler>
                <fullSyncScheduler>
                    <beginDate>2022-09-15T00:00:00Z</beginDate>
                    <executionType>CLEAN_AND_SYNCHRONIZE</executionType>
                    <schedulerType>MANUALLY</schedulerType>
                </fullSyncScheduler>
                <schedulerPriority>NORMAL</schedulerPriority>
                <columns>
                    <column>
                        <length>40</length>
                        <name>close_code</name>
                        <nameMapping>close_code</nameMapping>
                        <nameMappingDisplayValue>dv_close_code</nameMappingDisplayValue>
                        <type>string</type>
                    </column>
                    <column>
                        <length>32</length>
                        <name>sys_id</name>
                        <nameMapping>sys_id</nameMapping>
                        <type>GUID</type>
                    </column>
                </columns>
                <excludedColumns/>
                <options>
                    <option>
                        <key>diffCheckUpdates</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>dbCheckUpdates</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>cleanAndSyncToTmpTable</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>rotation</key>
                        <value>NOT_AVAILABLE</value>
                    </option>
                </options>
                <mirrorDbAlias>1</mirrorDbAlias>
                <tags>
                    <tag>
                        <color>#333399</color>
                        <name>Daily</name>
                    </tag>
                </tags>
            </synchronization>
        </synchronizations>
    </snowMirrorExport>

2.4. /synchronization/import

2.4.1. POST

Imports synchronizations and their settings. Both fullSyncScheduler from V1 api and additionalSchedulers from V2 api are supported in both api versions. However, if fullSyncScheduler is present, additionalSchedulers will be ignored.

This endpoint has to be called with a required "existing" parameter so that SnowMirror know how to deal with existing synchronizations.

URL parameter Description

existing

How to import synchronizations that already exist in SnowMirror. The parameter is required. Allowed values: ignore, rename, update

  • ignore - do not import synchronization that already exist

  • rename - create the synchronization under a different name

  • update - update existing synchronizations

Table 2. Response Body Attributes
Attribute Description

ids

IDs of new or updated synchronizations.

Request Body Format:

  • Import synchronizations with additionalSchedulers and update existing

    Sample Request Body (Content-Type: application/xml), URL: /synchronization/import?existing=update:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <snowMirrorExport>
        <exportInfo>
            <exportDate>2022-10-11T11:14:28.205Z</exportDate>
            <serviceNowUrl>https://ven01469.service-now.com/</serviceNowUrl>
            <snowMirrorVersion>5.8.0</snowMirrorVersion>
        </exportInfo>
        <synchronizations>
            <synchronization>
                <synchronizationName>incident</synchronizationName>
                <enabled>true</enabled>
                <selectedTable>incident</selectedTable>
                <sncEncodedQuery></sncEncodedQuery>
                <sncObjectType>TABLE</sncObjectType>
                <includeInheritedColumns>true</includeInheritedColumns>
                <referenceFieldType>SYS_IDS</referenceFieldType>
                <deleteType>AUDIT</deleteType>
                <autoSchemaUpdate>DISABLED</autoSchemaUpdate>
                <mirrorTableName>incident</mirrorTableName>
                <checkRecordsMatchingQuery>true</checkRecordsMatchingQuery>
                <consistencyCheckAllowed>SYSTEM</consistencyCheckAllowed>
                <incrementalColumn>sys_updated_on</incrementalColumn>
                <scheduler>
                    <beginDate>2022-09-15T00:00:00Z</beginDate>
                    <executionType>INCREMENTAL_SYNCHRONIZATION</executionType>
                    <schedulerType>MANUALLY</schedulerType>
                </scheduler>
                <additionalSchedulers>
                    <additionalScheduler>
                        <beginDate>2022-09-15T00:00:00Z</beginDate>
                        <executionType>CLEAN_AND_SYNCHRONIZE</executionType>
                        <schedulerType>MANUALLY</schedulerType>
                    </additionalScheduler>
                </additionalSchedulers>
                <schedulerPriority>NORMAL</schedulerPriority>
                <columns>
                    <column>
                        <length>40</length>
                        <name>close_code</name>
                        <nameMapping>close_code</nameMapping>
                        <nameMappingDisplayValue>dv_close_code</nameMappingDisplayValue>
                        <type>string</type>
                    </column>
                    <column>
                        <length>32</length>
                        <name>sys_id</name>
                        <nameMapping>sys_id</nameMapping>
                        <type>GUID</type>
                    </column>
                </columns>
                <excludedColumns/>
                <options>
                    <option>
                        <key>diffCheckUpdates</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>dbCheckUpdates</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>cleanAndSyncToTmpTable</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>rotation</key>
                        <value>NOT_AVAILABLE</value>
                    </option>
                </options>
                <mirrorDbAlias>1</mirrorDbAlias>
                <tags>
                    <tag>
                        <color>#333399</color>
                        <name>Daily</name>
                    </tag>
                </tags>
            </synchronization>
        </synchronizations>
    </snowMirrorExport>
  • Import synchronizations with fullSyncScheduler and update existing

    Sample Request Body (Content-Type: application/xml), URL: /synchronization/import?existing=update:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <snowMirrorExport>
        <exportInfo>
            <exportDate>2022-10-11T11:14:28.205Z</exportDate>
            <serviceNowUrl>https://ven01469.service-now.com/</serviceNowUrl>
            <snowMirrorVersion>5.8.0</snowMirrorVersion>
        </exportInfo>
        <synchronizations>
            <synchronization>
                <synchronizationName>incident</synchronizationName>
                <enabled>true</enabled>
                <selectedTable>incident</selectedTable>
                <sncEncodedQuery></sncEncodedQuery>
                <sncObjectType>TABLE</sncObjectType>
                <includeInheritedColumns>true</includeInheritedColumns>
                <referenceFieldType>SYS_IDS</referenceFieldType>
                <deleteType>AUDIT</deleteType>
                <autoSchemaUpdate>DISABLED</autoSchemaUpdate>
                <mirrorTableName>incident</mirrorTableName>
                <checkRecordsMatchingQuery>true</checkRecordsMatchingQuery>
                <consistencyCheckAllowed>SYSTEM</consistencyCheckAllowed>
                <incrementalColumn>sys_updated_on</incrementalColumn>
                <scheduler>
                    <beginDate>2022-09-15T00:00:00Z</beginDate>
                    <incLoadExecutionType>INCREMENTAL_SYNCHRONIZATION</incLoadExecutionType>
                    <schedulerType>MANUALLY</schedulerType>
                </scheduler>
                <fullSyncScheduler>
                    <beginDate>2022-09-15T00:00:00Z</beginDate>
                    <executionType>CLEAN_AND_SYNCHRONIZE</executionType>
                    <schedulerType>MANUALLY</schedulerType>
                </fullSyncScheduler>
                <schedulerPriority>NORMAL</schedulerPriority>
                <columns>
                    <column>
                        <length>40</length>
                        <name>close_code</name>
                        <nameMapping>close_code</nameMapping>
                        <nameMappingDisplayValue>dv_close_code</nameMappingDisplayValue>
                        <type>string</type>
                    </column>
                    <column>
                        <length>32</length>
                        <name>sys_id</name>
                        <nameMapping>sys_id</nameMapping>
                        <type>GUID</type>
                    </column>
                </columns>
                <excludedColumns/>
                <options>
                    <option>
                        <key>diffCheckUpdates</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>dbCheckUpdates</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>cleanAndSyncToTmpTable</key>
                        <value>SYSTEM</value>
                    </option>
                    <option>
                        <key>rotation</key>
                        <value>NOT_AVAILABLE</value>
                    </option>
                </options>
                <mirrorDbAlias>1</mirrorDbAlias>
                <tags>
                    <tag>
                        <color>#333399</color>
                        <name>Daily</name>
                    </tag>
                </tags>
            </synchronization>
        </synchronizations>
    </snowMirrorExport>

Available Responses:

  • 200 - Synchronizations were imported.

    Sample Response Body (Content-Type: application/json):

    {
        "ids": [123,567]
    }

2.5. /synchronization/{id}

2.5.1. GET

Returns detailed information about the synchronization.

Table 3. Response Body Attributes
Attribute Description

sync.id

Id of the synchronization.

sync.name

Display name of the synchronization.

sync.table

Name of the table in ServiceNow. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

sync.view

Name of the view in ServiceNow. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

sync.attachment

Name of the table in ServiceNow which attachments will be synchronized. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

sync.backup

Name of the table in ServiceNow to backup to a file. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

sync.backupAttachment

Name of the table in ServiceNow which attachments you want to backup. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

sync.mirrorTable

Name of the table in mirror database where the data will be migrated.

sync.columns

A list of columns to synchronize. If some of the columns does not exist in ServiceNow then it is ignored in SnowMirror.
Each column consists of:
prefix - prefix of the column (has to be filled in only when synchronizing views)
name - name of the column to synchronize
sys_id - SysId of the column to synchronize

sync.columnsToExclude

A list of columns not to synchronize. If some of the columns does not exist in ServiceNow then it is ignored in SnowMirror.
Each column consists of:
prefix - prefix of the column (has to be filled in only when synchronizing views)
name - name of the column to synchronize
sys_id - SysId of the column to synchronize

sync.allowInheritedColumns

SnowMirror checks if columns exist in ServiceNow. If this flag is set to true, SnowMirror will also consider columns which a table inherited from its parent tables. If set to false, all columns which a table inherited from its parent tables will be ignored.
This flag is only applicable to tables. When synchronizing a view do not specify this attribute.
Allowed values: true, false

sync.referenceFieldType

Defines how to synchronize reference field types. SnowMirror can synchronize sys_ids to the reference field or its display value or both of them.
Allowed values: SYS_IDS, DISPLAY_VALUES, BOTH

sync.updateBeforeSynchronizationRun

Deprecated - use "sync.autoSchemaUpdate" instead. The same as "sync.autoSchemaUpdate".

sync.autoSchemaUpdate

Configures how to check for schema changes in ServiceNow.

Enabled (true) - whenever a synchronization is executed, SnowMirror checks for schema changes in ServiceNow. Automatically adds, updates (data type, max. length of a column) and removes columns. If a new column is added SnowMirror clears the mirror table and downloads all records from scratch.

Enabled (no truncation) (ENABLED_WITHOUT_TRUNCATION) - the same as Enabled option. It handles new columns differently, though. If a new column is added SnowMirror does not clear the mirror table. Instead, it creates the column and populates it with a default value (which is defined in ServiceNow).

Disabled (false) - SnowMirror does not check for schema changes at all.

Allowed values: true, false, ENABLED_WITHOUT_TRUNCATION

sync.encodedQuery

Encoded query used for filtering data in ServiceNow. See ServiceNow wiki for details

sync.deleteStrategy

Specifies how the data will be deleted from mirror database based on deletes in ServiceNow. For details about the strategies see Delete Strategy section in User Manual.
Allowed values: AUDIT, TRUNCATE, DIFF or NONE

sync.active

true - synchronization is active and can be scheduled to synchronize data from ServiceNow
false - synchronization is deactivated and cannot be scheduled to synchronize data from ServiceNow
Allowed values: true, false

sync.scheduler

Specifies when the incremental load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON

sync.fullLoadScheduler v1 api only

Specifies when the full load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON

sync.fullLoadScheduler.executionType v1 api only

Name of an action to perform during synchronization. Allowed values: CLEAN_AND_SYNCHRONIZE, DIFFERENTIAL.

additionalSchedulers v2 api only

Specifies when the additional synchronizations will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON.

additionalScheduler.executionType v2 api only

Name of an action to perform during synchronization. Allowed values: INCREMENTAL_SYNCHRONIZATION, INCREMENTAL_BACKUP, DIFFERENTIAL_BACKUP, CLEAN_AND_SYNCHRONIZE, DIFFERENTIAL_SYNCHRONIZATION, SYNC_FROM

sync.schedulerPriority

Execution priority of the job. Allowed values: HIGHEST, HIGH, NORMAL, LOW, LOWEST

sync.retentionPeriod

How many days to keep backups

sync.format

How to store backups. "CSV" - comma separated file. "XML" - XML files. Allowed values: CSV, XML

sync.mirrorDbId

Specifies which database will be used to store synchronized data. Allowed values are ids of configured databases. Please see GET

sync.tags since 5.8.0

Specifies which tags will be assigned to the given synchronization.

status.status

Allowed values: RUNNING, SUCCESSFUL, FAILED, CANCELING, CLEANING, NEW_SYNCHRONIZATION

status.startedOn

Date and time when the last synchronization run started

status.startedBy

Username of who started the synchronization

status.latestHistoryId

Id of the record in history of synchronization

status.durationInMillis

How long it took to finish the synchronization in milliseconds

status.duration

How long it took to finish the synchronization in human-readable format

status.toInsert

How many records was SnowMirror supposed to insert (create)

status.toUpdate

How many records was SnowMirror supposed to update

status.toDelete

How many records was SnowMirror supposed to delete

status.inserted

How many records SnowMirror actually created

status.updated

How many records SnowMirror actually updated

status.deleted

How many records SnowMirror actually deleted

status.total

Sum of how many records SnowMirror actually processed

Available Responses:

  • 200 - Synchronization was successfully retrieved. (V2 api)

    Sample Response Body (Content-Type: application/json):

    {
        "sync": {
            "id": 1,
            "name": "incident",
            "table": "incident",
            "mirrorTable": "incident",
            "columns": [
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                },
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": null,
            "deleteStrategy": "AUDIT",
            "active": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "additionalSchedulers": [
                 {
                    "executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "MANUALLY",
                    "beginDate": "2014-08-07"
                }
            ],
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        },
        "status": {
            "status": "SUCCESSFUL",
            "startedOn": "2014-08-19 13:07",
            "startedBy": "snowmirror_api",
            "latestHistoryId": 819,
            "durationInMillis": 4000,
            "duration": "4s",
            "toInsert": 75,
            "toUpdate": null,
            "toDelete": null,
            "inserted": 75,
            "updated": 0,
            "deleted": 0,
            "total": 75
        }
    }
  • 200 - Synchronization was successfully retrieved. (V1 api)

    Sample Response Body (Content-Type: application/json):

    {
        "sync": {
            "id": 1,
            "name": "incident",
            "table": "incident",
            "mirrorTable": "incident",
            "columns": [
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                },
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": null,
            "deleteStrategy": "AUDIT",
            "active": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "fullLoadScheduler": {
            	"executionType": "CLEAN_AND_SYNCHRONIZE",
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        },
        "status": {
            "status": "SUCCESSFUL",
            "startedOn": "2014-08-19 13:07",
            "startedBy": "snowmirror_api",
            "latestHistoryId": 819,
            "durationInMillis": 4000,
            "duration": "4s",
            "toInsert": 75,
            "toUpdate": null,
            "toDelete": null,
            "inserted": 75,
            "updated": 0,
            "deleted": 0,
            "total": 75
        }
    }
  • 404 - Could not find the synchronization.

2.5.2. PUT

Updates a synchronization. The request body contains all fields (even those not being modified).

Here is how to modify a single field:

  1. Retrieve the synchronization using GET endpoint.

  2. Take the JSON response from GET endpoint and change the field. Do no touch the other fields.

  3. Send the JSON from the previous step to the PUT endpoint.

Table 4. Request Body Attributes
Attribute Description

id

Id of the synchronization.

name

Display name of the synchronization.

table

Name of the table in ServiceNow. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

view

Name of the view in ServiceNow. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

attachment

Name of the table in ServiceNow which attachments will be synchronized. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

backup

Name of the table in ServiceNow to backup to a file. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

backupAttachment

Name of the table in ServiceNow which attachments you want to backup. One (and only one) of "table", "view", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

mirrorTable

Name of the table in mirror database where the data will be migrated.

columns

A list of columns to synchronize. If some of the columns does not exist in ServiceNow then it is ignored in SnowMirror. This attribute is mandatory for tables and view. It must not be used for attachments.
If Auto Schema Update (autoSchemaUpdate field) is Enabled or Enabled (no truncation), you can leave this field empty (colums: []) and SnowMirror will automatically add all columns except for those listed in (columnsToExclude field).
SnowMirror always automatically adds SysId column.
Each column consists of:
prefix - prefix of the column (has to be filled in only when synchronizing views)
name - name of the column to synchronize
sys_id - SysId of the column to synchronize

columnsToExclude

A list of columns not to synchronize. If some of the columns does not exist in ServiceNow then it is ignored in SnowMirror. This attribute is optional.
Each column consists of:
prefix - prefix of the column (has to be filled in only when synchronizing views)
name - name of the column to synchronize
sys_id - SysId of the column to synchronize

allowInheritedColumns

SnowMirror checks if columns exist in ServiceNow. If this flag is set to true, SnowMirror will also consider columns which a table inherited from its parent tables. If set to false, all columns which a table inherited from its parent tables will be ignored.
This flag is only applicable to tables. When synchronizing a view do not specify this attribute.
Allowed values: true, false

referenceFieldType

Defines how to synchronize reference field types. SnowMirror can synchronize sys_ids to the reference field or its display value or both of them.
Allowed values: SYS_IDS, DISPLAY_VALUES, BOTH

updateBeforeSynchronizationRun

Deprecated - use "autoSchemaUpdate" instead. The same as "autoSchemaUpdate".

autoSchemaUpdate

Configures how to check for schema changes in ServiceNow.

Enabled (true) - whenever a synchronization is executed, SnowMirror checks for schema changes in ServiceNow. Automatically adds, updates (data type, max. length of a column) and removes columns. If a new column is added SnowMirror clears the mirror table and downloads all records from scratch.

Enabled (no truncation) (ENABLED_WITHOUT_TRUNCATION) - the same as Enabled option. It handles new columns differently, though. If a new column is added SnowMirror does not clear the mirror table. Instead, it creates the column and populates it with a default value (which is defined in ServiceNow).

Disabled (false) - SnowMirror does not check for schema changes at all.

Allowed values: true, false, ENABLED_WITHOUT_TRUNCATION

encodedQuery

Encoded query used for filtering data in ServiceNow. See ServiceNow wiki for details

deleteStrategy

Specifies how the data will be deleted from mirror database based on deletes in ServiceNow. For details about the strategies see Delete Strategy section in User Manual.
Allowed values: AUDIT, TRUNCATE, DIFF or NONE

active

true - synchronization is active and can be scheduled to synchronize data from ServiceNow
false - synchronization is deactivated and cannot be scheduled to synchronize data from ServiceNow
Allowed values: true, false

scheduler

Specifies when the incremental load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON

fullLoadScheduler v1 api only

Specifies when the full load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON

fullLoadScheduler.executionType v1 api only

Name of an action to perform during synchronization. Allowed values: CLEAN_AND_SYNCHRONIZE, DIFFERENTIAL.

additionalSchedulers v2 api only

Specifies when the additional synchronizations will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON.

additionalSchedulers[].executionType v2 api only

Name of an action to perform during synchronization. Allowed values: INCREMENTAL_SYNCHRONIZATION, INCREMENTAL_BACKUP, DIFFERENTIAL_BACKUP, CLEAN_AND_SYNCHRONIZE, DIFFERENTIAL_SYNCHRONIZATION, SYNC_FROM

schedulerPriority

Execution priority of the job. Allowed values: HIGHEST, HIGH, NORMAL, LOW, LOWEST

retentionPeriod

How many days to keep backups

format

How to store backups. "CSV" - comma separated file. "XML" - XML files. Allowed values: CSV, XML

mirrorDbId

Specifies which database will be used to store synchronized data. Allowed values are ids of configured databases. Please see GET

tags since 5.8.0

Specifies which tags will be assigned to the given synchronization.

  • Full Request (V2 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "id": 1,
            "name": "incident",
            "table": "incident",
            "mirrorTable": "incident",
            "columns": [
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                },
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "columnsToExclude": [
                {
                    "name": "sys_created_by",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": null,
            "deleteStrategy": "TRUNCATE",
            "active": true,
            "scheduler": {
                "type": "PERIODICALLY",
                "beginDate": "2014-08-05",
                "time": "18:05",
                "days": [
                    "WEDNESDAY"
                ],
                "interval": 1000
            },
            "additionalSchedulers": [
                 {
                    "executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "PERIODICALLY",
                    "beginDate": "2014-08-05",
                    "time": "18:05",
                    "days": [
                        "WEDNESDAY"
                    ],
                    "interval": 1000
                }
            ],
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }
  • Full Request (V1 api)

    Sample Request Body (Content-Type: application/json):

    {
        "sync": {
            "id": 1,
            "name": "incident",
            "table": "incident",
            "mirrorTable": "incident",
            "columns": [
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                },
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "columnsToExclude": [
                {
                    "name": "sys_created_by",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": null,
            "deleteStrategy": "TRUNCATE",
            "active": true,
            "scheduler": {
                "type": "PERIODICALLY",
                "beginDate": "2014-08-05",
                "time": "18:05",
                "days": [
                    "WEDNESDAY"
                ],
                "interval": 1000
            },
            "fullLoadScheduler": {
            	"executionType": "CLEAN_AND_SYNCHRONIZE",
                "type": "PERIODICALLY",
                "beginDate": "2014-08-05",
                "time": "18:05",
                "days": [
                    "WEDNESDAY"
                ],
                "interval": 1000
            },
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        }
    }

Available Responses:

  • 200 - The synchronization has been successfully updated. (V2 api)

    Sample Response Body (Content-Type: application/json):

    {
        "sync": {
            "id": 1,
            "name": "incident",
            "table": "incident",
            "mirrorTable": "incident",
            "columns": [
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                },
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": null,
            "deleteStrategy": "TRUNCATE",
            "active": true,
            "scheduler": {
                "type": "PERIODICALLY",
                "beginDate": "2014-08-07",
                "time": "16:05",
                "days": [
                    "WEDNESDAY"
                ],
                "interval": 1000
            },
            "additionalSchedulers": [
                {
                    "executionType": "CLEAN_AND_SYNCHRONIZE",
                    "type": "PERIODICALLY",
                    "beginDate": "2014-08-07",
                    "time": "16:05",
                    "days": [
                        "WEDNESDAY"
                    ],
                    "interval": 1000
                }
            ],
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        },
        "syncTableCleared": false
    }
  • 200 - The synchronization has been successfully updated. (V1 api)

    Sample Response Body (Content-Type: application/json):

    {
        "sync": {
            "id": 1,
            "name": "incident",
            "table": "incident",
            "mirrorTable": "incident",
            "columns": [
                {
                    "name": "active",
                    "sysId": "8f2f4b99e1031100a24720593d95f563"
                },
                {
                    "name": "sys_id",
                    "sysId": "3a3f8b99e1031100a24720593d95f5d5"
                }
            ],
            "allowInheritedColumns": true,
            "referenceFieldType": "BOTH",
            "autoSchemaUpdate": false,
            "encodedQuery": null,
            "deleteStrategy": "TRUNCATE",
            "active": true,
            "scheduler": {
                "type": "PERIODICALLY",
                "beginDate": "2014-08-07",
                "time": "16:05",
                "days": [
                    "WEDNESDAY"
                ],
                "interval": 1000
            },
            "fullLoadScheduler": {
            	"executionType": "CLEAN_AND_SYNCHRONIZE",
                "type": "PERIODICALLY",
                "beginDate": "2014-08-07",
                "time": "16:05",
                "days": [
                    "WEDNESDAY"
                ],
                "interval": 1000
            },
            "schedulerPriority": "NORMAL",
            "mirrorDbId": 1,
            "tags": [
                {
                    "name": "Daily",
                    "color": "#123123"
                }
            ]
        },
        "syncTableCleared": false
    }
  • 400 - Could not parse a request or validations failed.

  • 404 - Could not find the synchronization.

2.5.3. DELETE

Deletes a synchronization. To be able to delete a synchronization it must not be running.

URL parameter Description

deleteTables

Decides if mirrored tables will be kept in database. Allowed values: true, false

* true - tables with mirrored data will be deleted
* false - tables with mirrored data will be kept in database

  • 200 - Synchronization has been successfully deleted.

  • 400 - Could not delete the synchronization.

  • 404 - Could not find the synchronization.

2.6. /synchronization/{id}/action

2.6.1. GET

Returns a list of all actions which can be performed on the synchronization.

Available Responses:

  • 200 - A list of actions was successfully retrieved.

    Sample Response Body (Content-Type: application/json):

    {
        "actions": [
            "SYNCHRONIZE",
            "CLEAN_AND_SYNCHRONIZE",
            "DIFFERENTIAL_SYNCHRONIZATION",
            "SYNC_FROM",
            "STOP_SYNCHRONIZATION"
        ]
    }
  • 404 - Could not find the synchronization.

2.6.2. POST

Performs an action on the given synchronization. It is expected that the synchronization is active.
Available actions are "SYNCHRONIZE", "CLEAN_AND_SYNCHRONIZE", "DIFFERENTIAL_SYNCHRONIZATION", "SYNC_FROM", STOP_SYNCHRONIZATION", "RESUME".

  • Full Request

    Sample Request Body (Content-Type: application/json):

    {
        "action": "SYNCHRONIZE"
    }
  • Full Request for SYNC_FROM

    Sample Request Body (Content-Type: application/json):

    {
        "action": "SYNC_FROM",
        "syncFrom": "2024-16-04"
    }

Available Responses:

  • 200 - An action has been successfully performed.

  • 400 - Could not parse a request or could not perform an action.

  • 404 - Could not find the synchronization.

2.7. /synchronization/{id}/history

2.7.1. GET

Returns a whole history of the synchronization.

Available Responses:

  • 200 - History was successfully retrieved.

    Sample Response Body (Content-Type: application/json):

    {
        "history": [
            {
                "id": 297,
                "result": "SUCCESSFUL",
                "start": "2014-08-07 10:20",
                "end": "2014-08-07 10:23",
                "startedBy": "snowmirror_api",
                "toInsert": 0,
                "toUpdate": 891,
                "toDelete": 0,
                "inserted": 0,
                "updated": 891,
                "deleted": 0,
                "total": 891
            },
            {
                "id": 294,
                "result": "SUCCESSFUL",
                "start": "2014-08-07 00:00",
                "end": "2014-08-07 00:00",
                "startedBy": "<SCHEDULER>",
                "toInsert": 2,
                "toUpdate": null,
                "toDelete": null,
                "inserted": 2,
                "updated": 0,
                "deleted": 0,
                "total": 2
            }
        ]
    }

2.8. /synchronization/{id}/history/{id}

2.8.1. GET

Returns information about the result of the specific synchronization run.

Available Responses:

  • 200 - History was successfully retrieved.

    Sample Response Body (Content-Type: application/json):

    {
        "history": {
            "id": 297,
            "result": "SUCCESSFUL",
            "start": "2014-08-07 10:20",
            "end": "2014-08-07 10:23",
            "startedBy": "snowmirror_api",
            "toInsert": 0,
            "toUpdate": 891,
            "toDelete": 0,
            "inserted": 0,
            "updated": 891,
            "deleted": 0,
            "total": 891
        }
    }
  • 404 - Could not find the synchronization or could not find the history.

2.9. /synchronization/{id}/history/{id}/log

2.9.1. GET

Returns a log of the given synchronization run.

Available Responses:

  • 200 - Log file was successfully retrieved.

    Sample Response Body (Content-Type: text/plain):

    INFO: 2014-08-06 22:17:57 - Synchronization has been started
    INFO: 2014-08-06 22:17:57 - No encoded query set
    INFO: 2014-08-06 22:17:57 - Loading meta-data of table sys_dictionary from ServiceNow
    INFO: 2014-08-06 22:17:59 - sys_dictionary table meta-data loaded, creating excluded columns list
    INFO: 2014-08-06 22:17:59 - No excluded columns set
    INFO: 2014-08-06 22:17:59 - Synchronizing to target table sys_dictionary
    INFO: 2014-08-06 22:17:59 - Getting count of records to insert, update and delete
    INFO: 2014-08-06 22:17:59 - Checking existing columns in the table sys_dictionary
    INFO: 2014-08-06 22:17:59 - Inserting records into table sys_dictionary
    INFO: 2014-08-06 22:17:59 - Inserting all records into table sys_dictionary
    INFO: 2014-08-06 22:17:59 - Getting next up to 2 keys of records which will be migrated
    INFO: 2014-08-06 22:17:59 - 2 keys selected.
    INFO: 2014-08-06 22:17:59 - Migrating records (1 to 2) into table sys_dictionary
    INFO: 2014-08-06 22:17:59 - Records (1 to 2) into table sys_dictionary migrated
    INFO: 2014-08-06 22:17:59 - Inserting records into table sys_dictionary finished (2 records inserted)
    INFO: 2014-08-06 22:17:59 - Updating records in table sys_dictionary
    INFO: 2014-08-06 22:17:59 - No update performed, synchronization executed for the first time
    INFO: 2014-08-06 22:17:59 - Deleting records from table sys_dictionary
    INFO: 2014-08-06 22:17:59 - No delete performed, synchronization executed for the first time
    INFO: 2014-08-06 22:17:59 - Finished executing synchronization successfully.
  • 404 - Could not find the synchronization, history or the log.

2.10. /synchronization/{id}/advancedSettings

2.10.1. GET

Returns an advanced settings of the given synchronization.

URL parameter Description

propertyKey

Returns settings value only for given key

Available Responses:

  • 200 - Advanced settings have been successfully loaded.

    Sample Response Body (Content-Type: application/json):

    {
        "advancedSettings": [
            {
                "key": "consistencyCheckAllowed",
                "value": "SYSTEM"
            },
            {
                "key": "archivePluginAllowed",
                "value": "SYSTEM"
            },
            {
                "key": "indexReplicationAllowed",
                "value": "SYSTEM"
            },
            {
                "key": "downloadAllUpdatedRecords",
                "value": "ENABLED"
            },
            {
                "key": "incrementalColumn",
                "value": "sys_updated_on"
            },
            {
                "key": "diffCheckUpdates",
                "value": "SYSTEM"
            },
            {
                "key": "databaseCheckUpdates",
                "value": "SYSTEM"
            },
            {
                "key": "startOffsetInSeconds",
                "value": null
            },
            {
                "key": "keyBatchSize",
                "value": null
            },
            {
                "key": "recordBatchSize",
                "value": null
            },
            {
                "key": "autoSchemaUpdateFillInDefaultValue",
                "value": "SYSTEM"
            },
            {
                "key": "recordsDelete",
                "value": "SYSTEM"
            },
            {
                "key": "truncationAllowed",
                "value": "SYSTEM"
            },
            {
                "key": "warningOnMissingColumnsAllowed",
                "value": "SYSTEM"
            },
            {
                "key": "countEnabled",
                "value": "ENABLED"
            },
            {
                "key": "attachmentRecordDir",
                "value": ""
            },
            {
                "key": "useTmpTables",
                "value": "SYSTEM"
            },
            {
                "key": "readReplicaState",
                "value": "SYSTEM"
            },
            {
                "key": "readReplicaName",
                "value": null
            },
            {
                "key": "logLevel",
                "value": "SYSTEM"
            }
        ]
    }
  • 500 - Response code 500 (and generally all 5xx codes) indicates that there is something wrong with SnowMirror which prevents the request to be fulfilled. If this happens SnowMirror log files will contain more details about the error.

    Sample Response Body for 500 Error (Content-Type: application/json):

    {
        "message": "Internal Server Error"
    }

2.10.2. PUT

Updates an advanced settings of the given synchronization. The request body contains fields those being modified.

Request Format:

  • Full Request

    Sample Request body (Content-Type: application/json):

    {
        "keyBatchSize": 10000,
        "recordBatchSize": 1000
    }

Available Responses:

  • 200 - An action has been successfully performed.

  • 500 - Response code 500 (and generally all 5xx codes) indicates that there is something wrong with SnowMirror which prevents the request to be fulfilled. If this happens SnowMirror log files will contain more details about the error.

    Sample Response Body for 500 Error (Content-Type: application/json):

    {
        "message": "Internal Server Error"
    }

2.11. /settings

2.11.1. GET

Returns a settings of SnowMirror.

URL parameter Description

propertyKey

Returns settings value only for given key

Available Responses:

  • 200 - settings have been successfully loaded.

    Sample Response Body (Content-Type: application/json):

    {
        "settings": [
            {
                "entityId": 294,
                "key": "hibernate.format_sql",
                "value": "false",
                "comment": "Pretty print the SQL in the log and console: true or false",
                "defaultValue": true
            },
            {
                "entityId": 292,
                "key": "hibernate.hbm2ddl.auto",
                "value": "none",
                "comment": "Database schema generation, possible values: validate | update | create | create-drop, if any other no action is taken",
                "defaultValue": true
            },
            {
                "entityId": 295,
                "key": "hibernate.populate",
                "value": "false",
                "comment": "Defines if the synchronizations in the database should be scheduled on SnowMirror startup.",
                "defaultValue": true
            },
            {
                "entityId": 293,
                "key": "hibernate.show_sql",
                "value": "false",
                "comment": "Show SQL queries in log file: true or false.",
                "defaultValue": true
            },
            ...
        ]
    }
  • 500 - Response code 500 (and generally all 5xx codes) indicates that there is something wrong with SnowMirror which prevents the request to be fulfilled. If this happens SnowMirror log files will contain more details about the error.

    Sample Response Body for 500 Error (Content-Type: application/json):

    {
        "message": "Internal Server Error"
    }

2.11.2. POST

Updates a settings of SnowMirror. The request body contains fields those being modified.

Request Format:

  • Full Request

    Sample Request body (Content-Type: application/json):

    {
        "options": {
            "hibernate.format_sql": "false",
            "hibernate.hbm2ddl.auto": "none",
            "hibernate.populate": "false",
            "hibernate.show_sql": "false"
        }
    }

Available Responses:

  • 200 - An action has been successfully performed.

  • 500 - Response code 500 (and generally all 5xx codes) indicates that there is something wrong with SnowMirror which prevents the request to be fulfilled. If this happens SnowMirror log files will contain more details about the error.

    Sample Response Body for 500 Error (Content-Type: application/json):

    {
        "message": "Internal Server Error"
    }

2.12. /mirrorDb

2.12.1. GET

Returns a list of configured databases.

Available Responses:

  • 200 - databases have been successfully loaded.

    Sample Response Body (Content-Type: application/json):

    {
        "databases": [
            {
                "id": 1,
                "name": "MSSQL",
                "defaultDatabase": true
            },
            {
                "id": 2,
                "name": "ORACLE",
                "defaultDatabase": false
            }
        ]
    }

3. Error handling

If API call ends with an error REST API will return proper HTTP Response code and explanation of what happened in response body.

Response Codes:

  • 400 - Response code 400 (and generally all 4xx codes) indicates that there is something wrong with a request (for example missing, invalid or unsupported value of a field in request body).

  • 500 - Response code 500 (and generally all 5xx codes) indicates that there is something wrong with SnowMirror which prevents the request to be fulfilled. If this happens SnowMirror log files will contain more details about the error.

    Sample Response Body for 500 Error (Content-Type: application/json):

    {
        "message": "Internal Server Error"
    }

3.1. Field value validation errors

When issuing a request with request body SnowMirror validates all the fields it that request. If a value is invalid then response body will contain description of all failed validations and HTTP Response code will be

Sample "400 - Bad Request" Response Body (Content-Type: application/json):

{
    "errors": [
        {
            "field": "sync.name",
            "message": "The name of the synchronization is already used."
        },
        {
            "field": "sync.mirrorTable",
            "message": "This table name is already used by another synchronization."
        }
    ]
}

3.2. Content-type validation

When issuing a request with a body please make sure you also send a proper Content-Type header. If you fail to do so or if you provide a type SnowMirror does not support you would end up with following error.

Sample "415 - Unsupported Media Type" Response (Content-Type: application/json):

{
    "message": "Unsupported Media Type"
}

4. Authentication and Security

To use SnowMirror REST API you have to authenticate yourself. We support basic HTTP authentication.

4.1. Basic Authentication

Basic HTTP Authentication is a mechanism where you provide your credentials through HTTP request header. The header that needs to be present is called "Authentication" and it contains a string username:password encoded by Base64 algorithm.

The "Authentication" header must be contained in all requests because REST API does not maintain any session.

  • In case the "Authentication" header is not supplied SnowMirror returns 401 - Unauthorized response. This response contains "WWW-Authenticate" header with value Basic realm="SnowMirror API". The same header will be sent if provided credentials are incorrent.

  • In case the user does not have a permission to operate on the resource SnowMirror returns 403 - Forbidden response.

    Sample 403 - Forbidden Response Body (Content-Type: application/json):

    {
        "message": "Forbidden"
    }

4.2. User

To be able to use API a user has to have Api Caller role assigned. He or she also has to have a role Synchronization Reader to be able to read data. Synchronization Administrator role is needed for modification (creates, updates and deletes).

4.2.1. Setting Up User Account

  1. Login into SnowMirror under your Administrator account

  2. Go to Settings / User Management page

  3. Click Add User button

  4. Fill in all required information:

    1. Choose credentials you will use to authenticate to SnowMirror API

    2. Choose a timezone in which API will communicate with this user account.

    3. Assign Api Caller, Synchronization Reader and Synchronization Administrator roles

  5. Click Add button. A new user will be created and you will be immediately able to use SnowMirror API.

4.2.2. Timezone

All dates and times in SnowMirror are stored in UTC (Universal Coordinated Time). Each user can choose a time zone in which the dates and times will be displayed to him or her. The time zone can be changed in SnowMirror on page Setting / Profile Settings.

All dates and times inserted using Rest API are expected to be in user’s time zone. Similarly all dates and times in responses from Rest API are formatted in user’s time zone.

SnowMirror REST API uses the time zone from user’s settings.

5. Change log

Version Date Remarks

5.5.0

September 22, 2023

  • Introduced API version 2. The API version 1 still works the same as before.

  • The new API v2 introduces "additionalSchedulers" parameter which allows you to define such additional schedulers. It deprecates "fullLoadScheduler" parameter, which is available only in v1.

  • Added new endpoints: /synchronization/{id}/advancedSettings, /settings