User Tools

Site Tools


replicator_snc_subscribe

Subscribe

Setting up subscribe allows a SNC instance to receive data from other instances that are sharing. In order for an instance to subscribe and receive data from another instance, you will need to first create a share configuration related to this table on the sharing instance first.

The following rule applies when defining subscribe definitions.

Incoming message –> check for specific table name –> check for Global –> check for parent table definitions

For example, if you have a prod instance that will be sharing data from the ticket table and a sub-prod instance that will be subscribing to receive data from the ticket table, you will need to create a share configuration on the prod instance for the ticket table and create a subscribe configuration on the sub-prod instance for the ticket table.

Setting up a table to subscribe can be done as follows:

1. Go to the Replicator > Subscribe option under the Perspectium app:


2. The Perspectium app comes with some of the more common tables to be replicated such as incident and problem. Click on one of those tables or choose the “New” option at the top to go to the table subscribe configuration form:

3. On the table subscribe configuration form, the following options are available:


Table : The name of the table to subscribe to and receive data.

Direction : “Subscribe” - This field will not be editable as it is used for both share and subscribe configurations and indicates the type of configuration.

Subscribed : The number of records that have been subscribed to as of this time. This field can be ignored.

Run business rules : A checkbox to indicate if this table should run business rules on data it receives while subscribing.

Copy empty fields : A checkbox to indicate if fields that are empty/null should be copied over or instead disregarded. As of UpdateSet version 3.12.0 this will be selected by default and will also only overwrite fields which are contained in the incoming record.

Active : A checkbox to indicate if this table is actively subscribing.

Create : A checkbox to indicate if this table will receive new records on creation.

Delete : A checkbox to indicate if this table will receive changes on deletion.

Update : A checkbox to indicate if this table will receive changes on update.

Source table name : A field to enter the source table name if it is different on the sharing instance. If the table names are the same, this field can be left blank.

If you specify a source table name and the source table shares attachments to this subscriber, you will want to add a Before Subscribe Script in the sys_attachment subscribe configuration in order to properly link attachments to incoming records.

For example, if you have an incident table subscribe configuration where you specify the source table name as “u_custom_incident”, in the sys_attachment subscribe configuration's Before Subscribe Script, you would add the following script:

if(current.table_name == 'u_custom_incident')
{ 
    current.table_name = 'incident'; 
}

4. When setting up the table, make sure you mark at least one of the options: Create, Update, Delete.

Override system fields

A checkbox to indicate if data subscribed to should maintain the system field values from the sharing instance. This includes fields like “Created By” such that entries show the same “Created By” value as in the sharing instance versus showing a generic system account as defined in your SNC configuration. This box should generally be checked.

If you have checkmarked to “Include journal fields” and/or “Include attachments” on the share configuration related to this subscribe, you will also need to checkmark this option on the subscribe configurations for the sys_journal_field, sys_attachment and sys_attachment_doc in order for their content to be created by the same user.

Refresh history set

A checkbox to indicate if the history set for this table should be refreshed and updated when content is updated in other related tables. For example, if you are subscribing to the incident table and you want to refresh the incident record's history set in order to see the record's journal field entries and attachments.

This option should not be selected on subscribe configurations for the sys_audit, sys_journal_field, sys_attachment and sys_attachment_doc tables. These tables themselves do not have history sets to refresh. If you want to refresh to see these journal/audit/attachment records on a table such as incident, select this option on the incident table instead.

In v3.20.0 , a scheduled job will run every minute to refresh history set for subscribed records. Previously, a Run Once scheduled job was created for each record that was to be refreshed.

Field prefix

A field indicating if fields in the sharing instance have a prefix that the table on this subscribing instance does not. For example the sharing table may have fields with a prefix of “u_” whereas the subscribing table may not. This field can be left blank if the field names are the same which will apply in most cases.

Condition : To specify a set of conditions in order to subscribe to data for this table. For example, if you want to subscribe to only data related to one customer you would specify a condition here.

Condition script

Similar to Condition allowing you to specify conditions in order to subscribe to data for this table. The script will be evaluated and return a value “anded” with those specified in the “Condition”. The “current” global variable represents the incoming record de-serialized into GlideRecord.

In v3.16.0 , users can access the inbound message in the condition script represented by qcurrent. For example the following script is set up to only accept messages from a specific instance, accessed by qcurrent.key.

qcurrent.key == "instance"

Before Subscribe Script

About

This script will execute right before an insert or update allowing a chance to modify the record before persisting. Within your script you have access to the following variables:

Variable Description
current This represents the record that is being inserted or updated, the destination record
repl_gr This is the temporary inbound record, by default repl_gr will just be mapped into current
gr_before This represents the record before any update is made to it. If the record doesn't exist (you are doing an insert) then it will be assigned to current
qcurrent This represents the record within the psp_in_message table, the record pulled in from the message bus. With this you can use it's key value to determine the source
ignore v3.15.0 You can set the variable ignore to true in order to stop the execution of the Subscribe
qcurrentxml v3.25.0 This variable holds the xml object of the inbound record
xml_util v3.25.0 This variable holds an xml utility for working with qcurrentxml

With these variables you can perform a wide array of actions based on your needs.

Examples

Populating the data using the incoming key

Perhaps you are receiving data from multiple sources and you want to denote the source in some manner. You can use the qcurrent.key value when updating your record.

The following script prefixes the short description with the key

current.short_description = qcurrent.key + " - " + current.short_description;

Mapping data within a record

For example, to set the short_description field to the incoming record's number field, you would do this:

current.short_description = repl_gr.number;

Dot-walking

You can use dot-walking to display values from a referenced field.

For example, if you were subscribing to a ticket record, in the before subscribe script text box, you can reference a field by using the following script:

  current.name = repl_gr.assigned_to.name

This will display the display_value versus just the sys_id.

Using gr_before to fire an Event

For the case where you are updating a record that already exists in the system, “gr_before” is a GlideRecord object for this record before doing the update. This is useful for when you want to compare a record's values as they currently exist in the system with the values in the incoming record (repl_gr) and do any processing as a result.

For example, to fire the incident table's event when the assignment group is changed (the “incident.assigned.to.group” event as specified in the incident table's “incident events” business rule), you would do the following:

if (gr_before.assignment_group != repl_gr.assignment_group) {
  gs.eventQueue("incident.assigned.to.group", current, current.assignment_group, previous.assignment_group.getDisplayValue());
}

Using ignore

For example the following script from a ticket subscribe, will ignore a specific ticket with the number value of TKT0010001.

if (current.number == "TKT0010001") {
    ignore = true;
}

Users can also filter records from different instances by checking the key value. For example, the following script will ignore any records with the key value of “dev14945”.

if (qcurrent.key == "dev14945") {
    ignore = true;
}

Running Script Before a Delete

v3.20.0

Support has been added so you can run script before doing a delete such as inserting a record into another table. In these cases you should use “repl_gr” to access the incoming record in case the incoming record doesn't exist in the instance.

For example, say you receive a delete but you want to insert a record into another table instead, and not do an actual delete:

var tgr = new GlideRecord("incident");
tgr.short_description = repl_gr.short_description + " new";
tgr.insert();
ignore = true;

Firing Replication through Subscribe

There are some cases where you want to replicate a message right after Subscribing it in. In most cases you can select “Run Business Rules” to treat this replication as a normal record transaction and our Dynamic Share's Business Rule should fall in line. If however you cannot use this on the Subscribe than you can execute the following command.

var pspRepl = new PerspectiumReplicator();
//sys_id of desired Dynamic Share
pspRepl.shareRecord(current, "incident", "bulk", "d24f961b4f043200daa12ed18110c72d");
ignore = false;

This is essentially the code that gets executed from the Business Rule for a Dynamic Share. With this you will put in the current record, the table name, the flag “bulk”, and the sys_id of the Dynamic Share you want this to route through.

It is also important to add in the (ignore = false;) statement to the Subscribe. There are cases where the execution of the Dynamic Share's “Before Share Script” can cause the Subscribe to skip the update. Adding in this command will ensure the record gets committed to the Subscribing instance.

Maintaining a Column's Value

If you want to lock a column from being changed through the Subscribe you can put in the following line to set this column to it's “previous” value. Effectively setting it to itself so any change coming in won't take affect.

current.short_description = gr_before.short_description;

Accessing the XML Object of the Inbound Record

v3.25.0

For cases where the inbound record is different from the subscribing table (i.e. it has extra fields that the table on the subscribing instance doesn't have), you can now reference the XML object directly using the qcurrentxml variable.

The xml_util variable allows you to access values from the qcurrentxml object using getElementValueByTagName() function. This functions takes in two parameters, the XML object (qcurrentxml) and the name of the field in the XML.

For example, if you want to access the 'dv_priority' field's value in the XML and save it into the inbound record's short_description field:

if (qcurrentxml) {
    var elemValue = xml_util.getElementValueByTagName(qcurrentxml, 'dv_priority');
    current.short_description = elemValue;
}

Note: It is suggested that you check if qcurrentxml exists in case of any issues decrypting the value and getting the XML object.

After Subscribe Script

About

This script will execute right after a record has been subscribed with an insert, update or delete. This section expects server side javascript. Within your script you have access to the following variables:

Variable Description
current This represents the record that was inserted, updated or deleted, the destination record
qcurrent This represents the record within the psp_in_message table, the record pulled in from the message bus. With this you can use it's key value to determine the source
qcurrentxml This variable holds the xml object of the inbound record
xml_util This variable holds an xml utility for working with qcurrentxml
subscribe_gr This variable holds the GlideRecord object corresponding to the subscribe record configuration itself (i.e. you can use subscribe_gr.getTableName() to access the name of the table you're trying to insert)

4. Once done, click “Submit” (new table configuration) or “Update” (current configuration) to save your changes.

To quickly set up a table for subscribing, choose a table from the dropdown and then have the “Active”, “Create”, “Delete” and “Update” checkboxes all checked (the “Override system fields” checkbox will automatically be checked upon opening this form). You can choose the “Activate all” option at the bottom of the form and this will checkmark all four checkboxes (and “Deactivate all” will in the opposite case uncheck all four).

Note if any fields do not appear on your form, right-click on the “Replicator Configuration” title and choose Personalize > Form Layout and then add the missing fields to the form.

replicator_snc_subscribe.txt · Last modified: 2018/08/01 16:28 by angela.zhang