User Tools

Site Tools


updateset_properties

Perspectium Properties Configuration

To access the Perspectium Properties page, use the left side navigation bar to navigate to Perspectium > Control and Configuration > Properties, or simply type Control and Configuration in the navigation window and click Properties.

Perspectium Message Broker Service (MBS) Credentials

Before configuring your Perspectium properties, you will need to request the following information from support@perspectium.com:

  1. Perspectium MBS user ID
  2. Perspectium MBS password
  3. Target Perspectium MBS server (endpoint) URL

After receiving this information, enter your message bus user ID, password, and URL in the appropriate fields. A Show decrypted value link is provided so that you can see your decrypted password.

After entering your credentials, it is recommended to click the Start All module under Control and Configuration. You can also check the Logs module to make sure there are no connectivity errors. If you see logged errors for unable to connect using the “guest” user, confirm once again that you have entered the correct message bus user ID and password.

Limit Outbound Messages

v3.16.0

In v3.16.0, properties have been added to allow you to limit the number of messages placed into the outbound queue has been added. This allows you to prevent your outbound queue from growing too large and causing performance issues in your ServiceNow instance:



Once enabled, you can then enter the number of messages the outbound queue should be limited to. Once this maximum has been reached, no more messages will be placed into the queue and Perspectium Errors will be logged that you can subscribed to with error notifications. Sent messages in the outbound queue will also be deleted to help clear out the queue for the next time a job runs to place messages outbound.

In vCarbon, we have optimized how we cap the outbound messages to improve throughput into outbound queue. Previously this involved a full table count per record. Now a separate Scheduled Job, “Perspectium Check Outbound Message Limit”, will be performing and storing the table counts periodically (defaulted to 5 minutes). Each message will then check against this limit instead performing the table count itself.

Due to this optimization it is possible for there to temporarily be more messages than your limit. Since this count will be updated every 5 minutes there is that delay in what that table count represents. You can manually execute the Scheduled Job “Perspectium Check Outbound Message Limit” if you want to update the count manually.

You will see the following log message if you encounter this limit. It will will also detail the message skipped and the Share configuration which generated it in the Source.

Maximum number of messages (1000000) has been reached and no more messages will be placed into the outbound queue (skipped replicator - incident.bulk message, with sys_id: 3c59b876db8213006d8a1fc7689619f6 from bulk share b7fbcacfdb8213006d8a1fc768961992)
Note: This is checking the count set by "Perspectium Check Outbound Message Limit", which runs every 5 minutes.

Skip updating sys_domain_path

Also added was the property to skip updating the sys_domain_path field when an instance is subscribing to records from other ServiceNow instances. When selected, this option will skip updating the sys_domain_path field on a record to keep the value as it currently is or allow the system to update it appropriately if the domain changes.

In domain-separated instances with Helsinki+, if you update a record without changing the sys_domain field, the sys_domain_path will be updated to the default global value of “/” that comes in with the incoming record. Prior to Helsinki, the system would auto adjust to the proper domain path after updating the record but this is no longer the case so this option is available to allow the domain path to work properly.

The skip updating sys_domain_path option is only applicable for domain-separated instances running Helsinki and newer so it should not be selected in other cases.

Version Number

v3.16.0

In v3.16.0, the version number of the Perspectium update set currently installed can be found at the bottom of the properties page:

Zero Configuration

This feature has been deprecated as of v3.16.0. Please contact support@perspectium.com for information on how to provision your instance.

Leaving it as zero config allows the instance to be cloned over and survive the overwriting of the properties. However, the source instance must be setup as zero config as well.

v3.2.1

Zero configuration allows you to install the update set and take the defaults automatically generated by ServiceNow for the targeted message broker service, queue user and queue password. These defaults will still be required to be pre-configured by Perspectium operations team.

Leaving it as zero config allows the instance to be cloned over and survive the overwriting of the properties. However, the source instance must be setup as zero config as well.

Initial installation of the update set will be in Zero Config mode by the presence of the following key patterns in the Queue User, Queue Password, and Target server … properties in the Perspectium Properties page.

Note: Please contact support@perspectium.com for the correct target Perspectium server endpoint unless you were instructed to use the server generated target server.

2015/12/14 12:20 · Paul Nguyen

Security

Configuring Perspectium Application security ensures that your data is kept secret using encryption yet maintains high accuracy by enabling access to table schemas.

Setting up Encryption and Decryption

Next, type your encryption key and decryption key in the appropriate fields. For AES-128 encryption, your encryption/decryption key must be least 24 characters long and comprised of alphanumeric characters.

As of the Perspectium Europium release, an option for AES-256 encryption is available. For AES-256 encryption, your encryption/decryption key must be at least 32 characters long. Any encryption key entered that is 25 to 31 characters in length will default to AES-128 encryption.

Your encryption key is used to encrypt Replicator records before they are shared out of your ServiceNow instance, while your decryption key is used to decrypt records coming into ServiceNow from a subscribed source. For simplicity purposes, it is recommend to use the same key for both encryption and decryption.

The encryption and decryption key fields are saved as Password (2 Way Encrypted) field types to more securely store the encryption and decryption keys in your instance. Clicking the show decrypted value link will display your encryption/decryption key.

Establishing access by Role

The Perspectium Application installs a role called perspectium. This role (and only this role itself), when assigned to a ServiceNow user will grant access to non-ServiceNow endpoints and agents to query table schemas in order to replicate accurately and dynamically to external databases.

The perspectium role will provide access to all the necessary Perspectium tables but it is recommended that you also provide the user with the import_admin and script_include_admin roles as the Perspectium application uses import set transform maps and script includes. The application can run without these roles but it helps with configuration and troubleshooting by Support.

The schema web service is located with the following URL

https://<instance>.service-now.com/<table>.do?PSP_SCHEMA

To create a user and assign the perspectium role, navigate to the User Administration > Users module and click the button to create a new user.

We will now enter the information to create a new user, for example, a user with the user ID perspectium and select a password. Next, select the perspectium role from the related list and assign it to this user.

Remember this user ID and password as you will need it to configure for SQL Replication configuration

Encryption Modes

v3.2.3

A new property is now available to describe how data is encrypted when being shared our of your ServiceNow instance, as shown in the following screenshot.

The available modes are:

  • unencrypted - data is sent unencrypted and unencoded
  • encrypted - data is encrypted and base64 encoded
  • encrypted_multibyte - base64 encode the data before encrypting for utmost compatibility

Foreign Language Replication between ServiceNow instances

To ensure that foreign language strings are replicated properly between ServiceNow instances require at least version 3.2.3 of the Update Set to be installed and that encrypted_multibyte encryption mode is selected on the source instance.

Foreign Language Replication to SQL Replication Agents

To ensure that foreign language strings are replicated properly to your target database via a SQL Replicator Agent, you must configure your database connection string for UTF-8 character encoding. For example, agent.xml config is modified with <database_parms> for MySQL subscriber to add the parameter characterEncoding=UTF-8.

If you have selected unencrypted or encrypted_multibyte encryption modes on the source ServiceNow instance, you must first install and configure a SQL Replicator Agent version 3.2.3 or later.

        <subscribe>
            <task>
            	<task_name>multibyte_tester</task_name>
            	<handler>com.perspectium.replicator.sql.SQLSubscriber</handler>
             	<amqp_queue>psp.out.replicator.dloo_mac</amqp_queue>             
                <decryption_key>The cow jumped over the moon</decryption_key>
                
                <database_server>127.0.0.1</database_server>
                <database_user>xxx</database_user>
                <database_password>xxx</database_password>
                <database_port>3306</database_port>
                <database_type>mysql</database_type>
                <database_parms>autoReconnect=true&amp;characterEncoding=UTF-8</database_parms>
                <database>psp_repl</database>
            </task>
        </subscribe>

For additional help see the Agent Troubleshooting page for multibyte encrytion/decryption.

2015/07/06 01:58 · David Loo

Sharing Display Values

v3.1.8

There is a property under Replicator settings in the Properties page. The underlying property name is com.perspectium.replicator.add_display_values. This property is false by default.

When set to true, display value fields that are prefixed with dv_ in the field name will be added to the shared record. Display values are resolved display values of referenced records in the current record being shared. More information on display values here. Furthermore, when a Choice List field is encountered, the display value for that is is also added as a dv_ prefixed field.

This feature is useful if you are sharing few tables without needing to include referenced records, the display value may contain enough readable information for your report.

Additionally, Choice Lists and Glide Lists v3.2.3 will also generate display values.

Display values are human readable strings that do not ensure referential integrity when used to join with other tables. To ensure accurate joining between tables, always rely on the actual sys_id value in the reference field instead.

2015/03/02 00:23 · David Loo

Restrict replicated fields to only the selected table's fields

v3.5.0

You can restrict the fields that are replicated to only contain fields from the selected table for Dynamic Share or Bulk Share by setting the com.perspectium.replicator.share_current_fields to true

2016/02/07 22:02 · David Loo

Prompt before large bulk share

In v3.19.0 users can enable a prompt to appear before a large bulk share. Users can choose a minimum number of records to cause the prompt to appear.

In v3.24.0 this feature is enabled by default.

2017/03/07 15:08 · Joseph McFadden
updateset_properties.txt · Last modified: 2018/12/13 18:04 by timothy.pike