<style>
.release-box {
	height: 30px; 
	width: 100px; 
	padding-top: 8px;
	text-align: center; 
	border-radius: 5px; 
	font-weight: bold; 
	background-color: #8efeb3;  
	border-color: #FCE28A;
}

.release-box:hover {
  	cursor: hand;
    cursor: pointer;
    opacity: .9; 
}
</style>
<meta name="robots" content="noindex">

<div class="release-box">
<a href="https://docs.perspectium.com/display/krypton" style="text-decoration: none; color: #FFFFFF; display: block;">
Krypton
</a>
</div>



Archive Data (found under DataSync) allows you to leverage the Perspectium DataSync solution to archive data from your ServiceNow instance to an external database. Whereas ServiceNow's built-in data archiving feature limits you to running archiving each table record only once, the Archive Data feature allows you to archive a record multiple times and to an external database of your choice using the Bulk Share function. 





Prerequisites

(warning) You need the following information from Perspectium Support:

  • Perspectium Integration Mesh (MBS) server URL 
  • Integration Mesh (MBS) vhost
  • Integration Mesh (MBS) username
  • Integration Mesh (MBS) password



Minimum Requirements 

Perspectium Core (ServiceNow app)Krypton 8.2.0 and newer
DataSync Agent

Krypton 8.0.3 and newer

Krypton 8.0.10 and newer for MySQL and PostgreSQL

Supported Databases


Oracle

Microsoft SQL Server

MySQL

PostgreSQL

(info) NOTE: To support Archive Data, the DataSync Agent's databases.xml configuration file has been modified to include new configurations for querying the target database for records. If you have modified the databases.xml for other configurations, acquire the updated databases.xml configuration file from Perspectium Support to update for the Archive Data changes. The databases.xml should then be placed back into the Agent's conf folder i.e. <Perspectium_Replicator_Agent_Installed_Directory>/conf 



↑ Go to top of page


Installation

You will need to install the application into your ServiceNow instance by installing update sets. You have two different options to install Archive Data:

Standalone

As of Krypton 8.3.0, Archive Data is available as a standalone update set that can be installed by itself. You do not need any other update sets but the Archive Data standalone update set.


Install Archive Data

Install the Archive Data standalone update set.




Addon

Archive Data is available as an addon to the core Perspectium application:


Install Perspectium Core Application

Install the Perspectium Core application and configure it for DataSync.


Install Archive Data

Install the Archive Data update set.


Run Finish Install

Since the Archive Data feature is built on top of the Core application as a lightweight add on, run Finish Install after installing the Archive Data update set to ensure all necessary components are installed properly.




↑ Go to top of page


Initial Setup

Before you begin, you will need set up initial configurations in Perspectium's General Settings:





Log into your ServiceNow instance and navigate to Perspectium > Control and Configuration > Properties or simply type Control and Configuration in the Filter Navigator on the upper left-hand side of the screen. and then click Properties.

Then, click General Settings.


Type your Perspectium Integration Mesh username, password, and server URL in the appropriate fields.

(info) NOTE: In the username field, you will need to prepend the username with your vhost name, i.e. vhost/user.

Then, scroll down to the bottom of the page and click Save.

Once saved, a subscribed queue will be created named psp.out.servicenow.<instance_name> to subscribe to records when restoring.







↑ Go to top of page


Overview

Once you navigate to DataSync > Archive Data, you will have the following options:

  • Archive - Choose the tables and conditions you want to archive from your ServiceNow instance.
  • Restore - Choose the previously executed archives you want to restore back into your instance.
  • Dashboard - View and monitor the data you've archived using this feature on your instance. 


Archive

Archive allows you to use the Bulk Share feature to back up tables to a queue that the DataSync Agent can then save into an external database. The Archive option provides a simplified view of the Bulk Share feature so as to allow you to specify which table to archive. Leveraging bulk share functionality, records are sent out in the standard Perspectium message format (as found in the Messages > Outbound table).

The Archive option offers the following choices after navigating Archive Data > Archive:

Create New Archive

Create a new archive configuration to specify which table you want to archive and to what target queue the records will be shared out to. This archive configuration is created as a specialized version of a bulk share.

When creating a new archive, like a standard bulk share, you specify a unique name for it along with the table you want to archive, the encryption method and a target queue to share records out to.

You can also specify conditions for which records from the table you want to archive along with sharing the table record's related attachments, journal fields and audit records. Like standard bulk shares, you can use the Share updates since then if you want to schedule this bulk share to run at certain times and share records updated since the last time the archive ran and Enable confirmation for ServiceNow to database table compare.

  • Since archives and restore share the same table as standard bulk shares, the name must be unique across bulk shares, archives and restores.
  • The table specified is the one that will be archived (i.e. not any child tables).
  • You can also choose to share out the related attachments, journal field and audit log entries related to the table you specify.
  • Since archives support table compare, the ServiceNow to database table compare UI will show both standard bulk shares and archives as selectable bulk share options.
  • Selecting a queue that has child queues will create child archives like what would happen with a standard bulk share. Executing the base archive will execute the child archives to share out records.

(info) NOTE: Because of how ServiceNow may cache UI views, you may be shown the wrong view on occasion (i.e. shown the Restore view when you are viewing an archive). To fix this, click on the menu in the top left of the form and choose the appropriate view (Share He20 Archive view for archives and Share He20 Restore view for restores):



View Archive Configurations

View previously created archive configurations. This view will only list archive configurations and not standard bulk shares.


Scheduled Archive

To schedule created archive configurations to continuously run at a time you choose. Scheduled archive is a specialized version of the scheduled bulk share feature with the main difference being you can only choose archives and not standard bulk shares. Similarly, scheduled bulk shares only allow you to choose bulk shares and not archives. 

After selecting Scheduled Archive, you have the following options:

Create New Scheduled Archive

Create a new scheduled archive to schedule when you want archive(s) to run. The options will be the same as you see on a scheduled bulk share.

(info) NOTE: You will have to save the scheduled archive first before you are able to add any archives to the scheduled archive. 


View Scheduled Archives

View previously created scheduled archives. This view will only list scheduled archives and not standard scheduled bulk shares.

From here, you can click into a scheduled archive and choose the Edit... option to add archive configurations you created to run on the scheduled archive's schedule. 

(info) NOTE: You will only be able to select archives (and not standard bulk shares) to add to your scheduled archive. Similarly, on scheduled bulk shares you can only select standard bulk shares and not archives.


↑ Go to top of page


Restore

Restore allows you to restore previously executed archives. Restore works by sending a command message to the DataSync Agent which will then query the external database where the records were previously saved to and send those records back into ServiceNow. The records are sent to the subscribed queue the ServiceNow instance consumes from, with records sent in the Perspectium message format (as found in the Messages > Inbound table) so they can be read in using the Perspectium Core application.

To restore data into your instance, you must have subscribe configured for the tables you will be restoring. When Archive Data is installed, it will create a global subscribe that will allow all table records to be restored into the instance.

(info) NOTE: If you restore task or its child records and include journal entries (sys_journal_field records) and those journal entries appear duplicated in your task record's activity log even though only a single record exists in the sys_journal_field table, you may need to rebuild the History Set for the records you are restoring. See Step 5 on this ServiceNow Knowledge Base article for more information.


The Restore option offers the following choices after navigating Archive Data > Restore:

Create New Restore

Create a new restore (bulk share) configuration to specify which archive you want to restore from. 

You can either choose an archive you previously did or manually configure the restore (you cannot do both from the same restore configuration) so as to specify your own conditions for restoring if you are trying to restore only a subset of data and know where you are restoring from (i.e. which queue your DataSync Agent is reading from). 

If you choose an archive you previously did, the manual configuration restore fields (Table name, Encryption method, Target queue, etc) will be hidden since the configurations from the archive will be used.

Otherwise you can configure restoring similar to configured creating a new archive, including if you want to restore attachments, journal fields and audit records.

Clicking Execute Now will send a command message to the queue specified (whether specifying the queue manually on the restore configuration or using the queue from the archive configuration) to tell the DataSync Agent to query and return records matching the restore conditions so the records can be read back into your ServiceNow instance.

  • Since archives and restore share the same table as standard bulk shares, the name must be unique across bulk shares, archives and restores.
  • When specifying your own conditions, verify the conditions are valid. For example, if you backed up only data from the incident table where active is true and then here configure to restore data where active is false. In this case, no data will be returned since this set of data was not archived.
  • Only archives that have a Completed status can be selected in a restore. If you created child archives, only the child archives will be selectable (and not the base archive) so you can send out restore command messages to the child queues associated with the child archives.
  • Archive configurations that are Completed will have a Restore this archive related link so you can easily create a restore off of it that you can then execute This restore configuration will be named Restore + Unix Timestamp i.e. Restore 1688533795479 to ensure uniquely named restore configurations.

(info) NOTE: Because of how ServiceNow may cache UI views, you may be shown the wrong view on occasion (i.e. shown the Restore view when you are viewing an archive). To fix this, click on the menu in the top left of the form and choose the appropriate view (Share He20 Archive view for archives and Share He20 Restore view for restores):


View Restore Configurations

View previously created restore configurations. This view will only list restore configurations and not standard bulk shares.


↑ Go to top of page


Dashboard

The Dashboard provides a view of the data you've archived using the Archive Data feature.

  • Your preferences such as the Theme you select or the Show By (Hour, Day, Month, Lifetime) option on Record Breakdown will be saved in your browser's localStorage for when you visit the Dashboard page again.



After navigation to Archive Data > Dashboard, you will see the Dashboard user interface that shows the following:

Recent Archives

This feature displays the most recent (up to 50) archives from you instance. You can click on any entry to access that specific record directly. This table will only list bulk shares created as archives and not standard bulk shares (those created under Perspectium Core > Shares > Bulk Shares).


Record Breakdown

The Record Breakdown graph is a visualization of data based on the calendar date selected. Toggle between different data representation (records per hour, day, month, or lifetime).


Total Daily/Monthly Records

Total Daily Records: Displays the total records archived for the current day. 

Total Monthly Records: Displays the total records archived for the current month. 


Changing the date/month on the calendar does not affect this count.



Average Records Sent + Calendar Select

Use this feature to get a breakdown of the number of records archived based on a selected date in the calendar. Information here is based on on bulk shares created as archives and executed in your instance.

Any time you access or reload the dashboard, the calendar date will reset to the current date.

You can change the date on the calendar using the available arrows or the dropdown settings.

The Records Sent/Day count reflects the number of records archived on the specific calendar date selected.

The Records Sent/Hour count is reflects the number of records archived in the the specific calendar date selected, divided by 24 hours. However, if the current date is selected, then this number is divided by the number of hours that have passed in that day so far. 


↑ Go to top of page


Uninstall Archive Data

Located under DataSync > -- Uninstall Archive Data, this option allows you to remove Archive Data specific Perspectium components from your instance.

Once you click on the module, you will be presented with a page to confirm you want to uninstall the Archive Data feature. Once you click Confirm, this will run a job in the background to remove Archive Data specific script includes, modules, scheduled jobs and UI pages including the Dashboard mentioned page.

This will take a few minutes to complete. You may need to log out and then log back into your ServiceNow instance to ensure that all Archive Data modules are removed from your left side list display. Also, if any Archive Data modules were marked as favorites prior to the uninstall process, you can remove the modules by selecting the - icon on to the right of the module.

(info) NOTE: If you have Archive Data installed as an addon or if you also have another standalone app installed (such as DataSync Snapshot), this will only install Archive Data functionality and not the core Perspectium application functionality.


↑ Go to top of page


Frequently Asked Questions

How should I restore related records?

If you are restoring related records and want them to appear on a record's related list, you would want to restore the record being referenced (i.e. the record specified in the referenced field) before restoring the record itself (the record that has the referenced field to the other record). 

For example if you want the Approver records to appear on a Change Request, since the sysapproval_approver record has a document_id field that references the change_request record, you would want to restore the change_request record first and then the sysapproval_approver record.

Another example, if you have Problem records that are related to Incident records and want them to show up on each record's respective related lists (i.e. the Problem shows up on the Incident's Related Records related list and the Incident shows up on the Problem record's Incident related list), you would restore the problem record first and then the incident record since the incident's problem_id field contains the reference to the problem record.

Doing this ensures that ServiceNow refreshes the links properly when the records are restored since it can find the related record being referenced and refresh related lists as a result. If you accidentally run it in the wrong order, you can always re-run the restore again as the Perspectium solution will only update fields that have changed. In this of restoring again, this shouldn't change any fields since the values are all the same but doing this a second time will cause the ServiceNow process to run and refresh the links.


↑ Go to top of page