Versions Compared

Old Version 10

changes.mady.by.user user-b885f

Saved on

compared with

New Version 11

changes.mady.by.user user-1bc08

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Feature available in Helium 6.0.1 release


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

.release-box:hover {
  	cursor: hand;
    cursor: pointer;
    opacity: .9; 
}
</style>
<html>
	<div class="release-box" id="release-box">
		<a href="https://docs.perspectium.com/display/Helium" style="text-decoration: none; color: #FFFFFF; display: block;">
			Helium
		</a>
	</div>
	<br>
</html>


Attachments are stored in ServiceNow in two separate tables, sys_attachment and sys_attachment_doc. The sys_attachment record holds information about the attachment (such as the file name and file size), while the sys_attachment_doc table contains the actual byte data of the attachment separated into different chunks so as to not have one record take up too much space in a table row. Thus, sending attachment(s) to your database with the DataSync Agent will store the attachment(s) in the two tables just as they are stored in ServiceNow. 

However in this state, you're not able to view the attachments (i.e. if the attachment is a JPG, you cannot see the actual image itself) since the attachments are separated as indicated above. By including a SysAttachmentHandler in the DataSync Agent configuration, the attachment(s) will no longer be in the sys_attachment and sys_attachment_doc, but instead will be merged together and stored in a new table called attachments. This allows you to have the actual full complete attachments as if you downloaded them from your ServiceNow instance through the UI.

(info) NOTE: Storing the attachments as complete records will lead to large table rows. Ensure your database has the space to save these large records.

Prerequisites

(warning) First, you will need to set up one of the Perspectium DataSync Agents.

(warning) You should also stop running your DataSync Agent before making any Agent configuration changes.


Procedure

To set up merging of attachments, follow these steps:


UI Steps
sizesmall


UI Step

Navigate to the directory where you saved your agent.xml file when installing your DataSync Agent.


UI Step

Open your agent.xml file in a text editing application. Then, add the following directives under <share><task> : 

DirectiveDescriptionRequired?Example Value
<handler>

Name of the Java handler class. In this case, the value for this directive will be com.perspectium.replicator.sql.subscriber.edge.SysAttachmentHandler.


Code Block
<config>
	<agent>
		<share>
			<task> 
			...
<handler>com.perspectium.replicator.sql.subscriber.edge.SysAttachmentHandler</handler>
			</task>
		</share>
	</agent>
</config>


Yescom.perspectium.replicator.sql.subscriber.edge.SysAttachmentHandler
<skip_queue/>

Including skip_queue will ensure that the attachments are not posted to the Integration Mesh but inserted into the attachments table

Yes, if message_connection is not included. 

Otherwise, NOT required.


<edge_encryption>

Decrypts messages that have been published from a ServiceNow instance that is leveraging Edge Encryption.

See Edge Encryption Support for more information.

ParameterDescription
keystore

Specifies where the keystore is located (azure or local)

vault_tenant

tenant_id for the Azure Key Vault containing the keystore

vault_url

URL to the Azure Key Vault

vault_principal

principal_id for the Azure Key Vault

principal_secret

Password for the Azure Key Vault

secret_name

Name of the keystore

keystore_passwordPassword for the keystore
keystore_alias

Name of the key alias

alias_password

Password for the key


Code Block
<config>
	<agent>
		<share>
			<task> 
				...
				<edge_encryption keystore="azure"
                 vault_tenant="VAULT_TENANT_GOES_HERE" 
                 vault_url="VAULT_URL_GOES_HERE"
                 vault_principal="VAULT_PRINCIPAL_GOES_HERE" 
                 principal_secret="PRINCIPAL_SECRET_GOES_HERE" 
                 secret_name="SECRET_NAME_GOES_HERE"
                 keystore_password="KEYSTORE_PASSWORD_GOES_HERE" 
                 keystore_alias="KEYSTORE_ALIAS_GOES_HERE" 
  				 alias_password="ALIAS_PASSWORD_GOES_HERE">true</edge_encryption>

			</task>
		</share>
	</agent>
</config>


Yes, if the attachments are edge encrypted.

Otherwise, NOT required. 

true


Example of agent.xml: 

Code Block
languagexml
themeEclipse
<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
    <agent>
        <max_reads_per_connect>1</max_reads_per_connect>
        <polling_interval>5</polling_interval>
        <test_mode/>
        <subscribe>
            <task>
                <polling_interval>5</polling_interval>
                <task_name>oracle_subscriber_automated_test</task_name>
                <handler>com.perspectium.replicator.sql.SQLSubscriber</handler>
                <decryption_key>some_decryption_key_here</decryption_key>
                <message_connection user="USER" password="PASSWORD" queue="psp.out.replicator.dev1234">https://URL.perspectium.net</message_connection>
                <use_cache/>
                <instance_connection user="USER" password="PASSWORD">https://dev1234.service-now.com</instance_connection>
                <database_type>sqlserver</database_type>
                <database_port>1234</database_port>
                <database_server>SERVER_URL</database_server>
                <database_user>USER</database_user>
                <database_password>PASSWORD</database_password>
                <database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
                <database>DATABASE_NAME</database>
                <skip_columns_log_interval>200</skip_columns_log_interval>
				<plugins>
					<plugin keystore="azure"
                            vault_tenant="12345678-ab12-ab12-ab12-123456789ab"
                            vault_url="https://url.vault.azure.net/"
                            vault_principal="12345678-ab12-ab12-ab12-123456789ab"
                            principal_secret="3213156165-adasdasd_a1s5d6a5s1d6a"
                            secret_name="some_secret_name"
							keystore_password="efg123"
                            keystore_alias="128bitkey"
                            alias_password="abc123">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
        </task>
    </subscribe>
    <share>
        <task>
            <task_name>attachment_processor</task_name>
            <handler>com.perspectium.replicator.sql.subscriber.edge.SysAttachmentHandler</handler>
            <encryption_key>some_encryption_key_here</encryption_key>
            <message_connection user="USER" password="PASSWORD" queue="psp.out.replicator.dev5678">https://URL.perspectium.net</message_connection>
            <polling_interval>60</polling_interval>
            <max_writes_per_connect>1</max_writes_per_connect>
            <skip_queue/>
            <skip_report/>
            <topic>topic_here</topic>
            <type>type_here</type>
            <key>key_here</key>
            <name/>
            <database_type>sqlserver</database_type>
            <database_port>1234</database_port>
            <database_server>SERVER_URL</database_server>
            <database_user>USER</database_user>
            <database_password>PASSWORD</database_password>
            <database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
            <database>DATABASE_NAME</database>

            <edge_encryption
                    keystore="azure"
                    vault_tenant="12345678-ab12-ab12-ab12-123456789ab"
                    vault_url="https://url.vault.azure.net/"
                    vault_principal="12345678-ab12-ab12-ab12-123456789ab"
                    principal_secret="3213156165-adasdasd_a1s5d6a5s1d6a"
                    secret_name="some_secret_name"
					keystore_password="efg123"
					keystore_alias="128bitkey"
					alias_password="abc123">true</edge_encryption>
        </task>
    </share>
</agent>
</config>



UI Step

After configuring your agent.xml, start running your DataSync Agent again.