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.
| 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. |
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. |
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. |
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. |
updateBeforeSynchronizationRun |
Deprecated - use "autoSchemaUpdate" instead. The same as "autoSchemaUpdate". |
autoSchemaUpdate |
Configures how to check for schema changes in ServiceNow. |
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. |
active |
true - synchronization is active and can be scheduled to synchronize data from ServiceNow |
runImmediately |
Determines whether initial synchronization should be done |
scheduler |
Specifies when the incremental load synchronization will run. For details about the schedulers see Scheduler section in User Manual. |
fullLoadScheduler v1 api only |
Specifies when the full load synchronization will run. For details about the schedulers see Scheduler section in User Manual. |
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. |
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 |
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
|
| 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.
| 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. |
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. |
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. |
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. |
sync.updateBeforeSynchronizationRun |
Deprecated - use "sync.autoSchemaUpdate" instead. The same as "sync.autoSchemaUpdate". |
sync.autoSchemaUpdate |
Configures how to check for schema changes in ServiceNow. |
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. |
sync.active |
true - synchronization is active and can be scheduled to synchronize data from ServiceNow |
sync.scheduler |
Specifies when the incremental load synchronization will run. For details about the schedulers see Scheduler section in User Manual. |
sync.fullLoadScheduler v1 api only |
Specifies when the full load synchronization will run. For details about the schedulers see Scheduler section in User Manual. |
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. |
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:
-
Retrieve the synchronization using GET endpoint.
-
Take the JSON response from GET endpoint and change the field. Do no touch the other fields.
-
Send the JSON from the previous step to the PUT endpoint.
| 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. |
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. |
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. |
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. |
updateBeforeSynchronizationRun |
Deprecated - use "autoSchemaUpdate" instead. The same as "autoSchemaUpdate". |
autoSchemaUpdate |
Configures how to check for schema changes in ServiceNow. |
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. |
active |
true - synchronization is active and can be scheduled to synchronize data from ServiceNow |
scheduler |
Specifies when the incremental load synchronization will run. For details about the schedulers see Scheduler section in User Manual. |
fullLoadScheduler v1 api only |
Specifies when the full load synchronization will run. For details about the schedulers see Scheduler section in User Manual. |
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. |
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 |
-
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
-
Login into SnowMirror under your Administrator account
-
Go to Settings / User Management page
-
Click Add User button
-
Fill in all required information:
-
Choose credentials you will use to authenticate to SnowMirror API
-
Choose a timezone in which API will communicate with this user account.
-
Assign Api Caller, Synchronization Reader and Synchronization Administrator roles
-
-
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 |
|---|---|---|
September 22, 2023 |
|