Configuration

Before beginning the configuration of the task, consider whether your synchronization will map data on ExtraView's repeating rows.  If this is the case, then ensure the following behavior settings have the appropriate values:

  • MULTI_RELEASE_XML should be set to a value of YES
  • CLI_EDIT_MULTI_VALUE_FIELDS should be set to a value of YES, if you are migrating any multi-value fields between two servers
  • If you intend to map the ORIGINATOR field, then the behavior setting named ALLOW_CLI_UPDATE_ORIGINATOR should be set to a value of YES.

Go to Administration --> Operational Tasks --> Task Manager to view all the tasks.  Add a new task and choose the ExtraView Peer Daemon Task - Handles replication between ExtraView instances to begin the configuration of the task.

To describe a specific synchronization, each configured integration has the following fields:

  1. Task Name
  2. The Title of the task
  3. The Node ID where the task runs
  4. The Start Option.  Typically this will be START_NOW
  5. Poll Interval.  The default time is 30 seconds.  This timer determines the starting of the integration task and the frequency with which it runs.  Note the configuration options EVPOLLWAITTIME and EVPOLLWAITTIME2 also have an effect on timing. See below for a note on this topic
  6. The Class Name - this must be com.extraview.sccintegration.EVPeerDaemonTask
  7. The Properties - this is where the mappings and other configuration options of the daemon are configured.

You may configure more than one ExtraView Peer Daemon task.  This should be done when you want to integrate one instance with two or more other instances.  Another use of multiple tasks being configured may be to independently sychronize different business areas between two instances.  The properties and mappings of the synchronization are defined within several sections as shown in the remainder of this page.

Server Connection Information

SERVER Required This required entry specifies the URL of the first ExtraView server API
SERVER2 Required This required entry specifies the URL of the second ExtraView server API

User Sign On Information

USER Required The ExtraView User ID that accesses the SERVER
PASSWORD Required The password associated with USER
USER2 Required The ExtraView User ID that accesses the SERVER2
PASSWORD2 Required The password associated with USER2

Field Validation Information

BYPASS_EDIT_TEST Optional The fields for replication may be chosen from either server without being part of the EDIT_PROBLEM layout.  When this is set to FALSE, the fields in the replication must be in the associated layout for the authorized user / area / project
BYPASS_ADD_TEST Optional The fields for replication may be chosen from either server without being part of the ADD_PROBLEM layout.  When this is set to FALSE, the fields in the replication must be in the associated layout for the authorized user / area / project
BYPASS_DETAILED_
REPORT_TEST		 Optional The fields for replication may be chosen from either server without being part of the DETAILED_REPORT layout.  When this is set to FALSE, the fields in the replication must be in the associated layout for the authorized user / area / project

Mapping Information

Mappings may be bi-directional or uni-drectional.  This syntax is only used within the mapping section of the configuration properties and is not used elsewhere.  Consider the following:

evfn.<ExtraView field name> = evfn2.<ExtraView field name> The mapping of the field is bidirectional
evfn.<ExtraView field name> => evfn2.<ExtraView field name> This only maps from SERVER to SERVER2
evfn.<ExtraView field name> <= evfn2.<ExtraView field name> This only maps from SERVER2 to SERVER

The three classes of metadata objects which can be synchronized are: 

  • UDF enumerated field values - You may specify any subset of all the enumerated fields to be synchronized.  UDF list values are upserted based on their last date updated, which must be later than the latest date when the last UDF list update was done.  Lazy propagation is an additional way that UDF list values are propagated:

    • An issue upsert is received from the peer, containing a UDF list value reference that does not map to any existing UDF list value on the server

    • This triggers the insertion of the UDF list entry on the server, and an identity mapping to be established, thereby allowing the issue upsert to complete. This only inserts a single locale’s value and no value is set in the ENABLED or SORT_SEQ fields of the UDF list entry

    • During a later poll of the peer server, the UDF list value(s) that were inserted in the previous step are replicated by generating a metadata upsert from the UDF list values, as retrieved from the peer.  Note that this step bypasses the timestamp restriction that normally would prevent a UDF list update.

  • Allowed Values - The allowed value mapping includes only Allowed Value Types where both the parent field and the child field are mapped
     
  • Non-transactional metadata - Mappings for Relationship Groups, Attachments and Rankings are supported
Global Mapping of Field Names Required evfn.<ExtraView field name> = evfn2.<ExtraView field name>

Map the named field evfn in the first ExtraView server to the named field evfn2 in the second ExtraView server, and vice versa as this is a bi-derectional assignment.  This is a global mapping of the field.  Unlike other integration daemons, you must map all fields that you want to synchronize between databases.  This ensures that the processing involved is kept to a minimum.  You must always map the AREA and PROJECT fields, else an error occurs and no processing is performed.

Note: The CLI_EDIT_MULTI_VALUE_FIELDS behavior setting must be set to YES in order for multi-value fields to be visible and editable in ExtraView.

Examples

evfn.SHORT_DESCR = evfn2.SHORT_DESCR
evfn.DESCRIPTION = evfn2.DESCRIPTION
evfn.SHORT_DESCR = evfn2.FRED_TEXTAREA
evfn.AREA = evfn2.AREA
evfn.PROJECT = evfn2.PROJECT
evfn.OP_SYS = evfn2.OP_SYS
Field Value Mapping Optional evv.<ExtraView field name>.<ExtraView field value> = evv2.<ExtraView field name>.<ExtraView field value>

Map the field value evv in the first ExtraView server to the field value evv2 in the second ExtraView server, and vice versa.

Note: These value mappings must be defined for mapped fields with a enumerated display type,(list, popup, radio, checkbox), in order for the synchronization to work.  Note that the mappings occur by comparing the titles to the fields.  If the values do not match exactly between servers, then the field is omitted from the synchronization transaction with a warning in the log.

Note: spaces in field values must be escaped with the \ character.

Examples

evv.STATUS.In\ Progress = evv2.STATUS.Work\ In\ Progress
evv.AREA.Empty\ Area = evv2.AREA.Engineering\ Issues
evv.PROJECT.Empty\ Area\ -\ Project\ Data = evv2.PROJECT.Defects
Field Value Mapping within a Business Area / Project Optional evv.<AREA name>.<PROJECT name>.<ExtraView field name>.<ExtraView field value> = evv2.<AREA name>.<PROJECT name>.<ExtraView field name>.<ExtraView field value>

Map the field value evv in the business area and project in the first ExtraView server to the field value evv2 in the business area and project in the second ExtraView server, and vice versa.
User Mapping Optional evv.user.<ExtraView user id> = evv2.user.<ExtraView user id>

Maps the information for the <ExtraView user id> in the first ExtraView server to the user id in the second ExtraView server, and vice-versa.  Note that User IDs and all supporting information are automatically inserted into the target instance when they do not exist but are referenced within the issue data.
SERVER Item ID Mapping Required EVID_FIELD = <ExtraView Field Name>

Identify the name of the field in the first ExtraView server containing the mapped item ID in the second ExtraView server.  The field used for this purpose should have the following data dictionary attributes:

​- Display type = Text
- Select for Reports = Yes
- Filter Criteria = Yes

The EVID_FIELD does not need to be on the screen layout.

Example

EVID_FIELD = EV_ID

If you are synchronizing more than two ExtraView instances, you should use different fields to map the IDs on each server.
 
SERVER2 Item ID Mapping Required EVID_FIELD2 = <ExtraView Field Name>

Identify the name of the field in the second ExtraView server containing the mapped item ID in the first ExtraView server.  The field used for this purpose should have the following data dictionary attributes:

​- Display type = Text
- Select for Reports = Yes
- Filter Criteria = Yes

The EVID_FIELD does not need to be on the screen layout.

Example

EVID_FIELD2 = EV_ID
 
Relationship Group Mapping Optional rg.<Relationship Group Name> = rg2.<Relationship Group Name>

This mapping provides for the replication of relationship group entries between the instances.  Note that you may map between relationship groups with different names on each server.  Only those relationship group entries that have issues that are replicated by the integration task are replicated.  At this point only parent-child relationships are support for synchronization.

Example

rg.my_relationship_group = rg2.another_relationship_group
Repeating Row mapping Optional You must have a repeating row field with a text display type defined in both servers to facilitate the mapping.  These fields should not be placed on the repeating row layouts.  Ensure that you set the Field Belongs To to a value of Repeating Row Records  The fields are analogous to the EVID_FIELD and EVID_FIELD2 fields that map issues and should have the same data dictionary attributes as specified for these fields.  The fields do not need to be on the screen layouts.

As described in the Administration Guide, there is one built-in repeating row type in ExtraView, named RELEASE.  If you are mapping this repeating row type from SERVER to SERVER2, there is no need to explicitly provide a mapping for the layout type.  However, you may often want to map repeating rows with different layout types.  In these cases, you use the following syntax to identify the repeating row types being mapped:

layout_type.xxxx = layout_type2.yyyy

where xxxx and yyyy are the layout type names for the repeating row layouts being mapped on SERVER and SERVER2 respectively.  You may have multiple entries of this kind to map fields for multiple repeating row layouts within the same issue.  The statements that map the fields themselves will not be ambiguous as fields on one repeating row layout are never configured on another repeating row layout.

Example

# EVID_FIELD = <ExtraView Field Name>
#
# Identify the name of the field in the first ExtraView server containing the mapped # item ID in the second ExtraView server.
#
EVID_FIELD = EV_ID
RR_EVID_FIELD = RR_EV_ITEM_ID

# EVID_FIELD2 = <ExtraView field name>
#
# Identify the name of the field in the second ExtraView server containing the
# mapped item ID in the first ExtraView server.
#
EVID_FIELD2 = EV_ID
RR_EVID_FIELD2 = RR_EV_ITEM_ID
Deleted Issue mapping Optional Unless it is necessary to map deleted issues from one server to another, the recommendation is to set this to NO for both the source and target servers  The settings may either be:

deletes.client = NO
deletes.client2 = NO

or:

deletes.client = YES
deletes.client2 = YES

If you set these to a value of NO, then if issues are deleted on one server, they will not be deleted on the other server.  It is useful for performance to set this value to NO if you are using the integration to migrate a significant number of records from one server to another as part of an initial data migration.  Once the initial migration of records is complete, you can set this back to YES and the deletes will happen over time.
INSERT_VALUES Optional INSERT_VALUES.<ExtraView field name> = <ExtraView field value>

This property is used to provide a value to be used to set a field in all issue INSERT operations in the first ExtraView SERVER.  This is not used for updates, only inserts and its primary purpose is to ensure that you provide field values for required fields on the target instance.
INSERT_VALUES2 Optional INSERT_VALUES2.<ExtraView field name> = <ExtraView field value>

This property is used to provide a value to be used to set a field in all issue INSERT operations in SERVER2.  This is not used for updates, only inserts

Synchronization Properties

The properties that begin with the characters MI_ refer to SERVER, whilst the properties that begin with the characters MJ_ refer to the SERVER2.

Identifying the field in SERVER upon which synchronization occurs Optional MI_FIELD = <ExtraView field name>

Identify the field to be inspected for the MI_REGEX evaluation to determine if an item in the first ExtraView server maps to an item in the second ExtraView server.
The expression which evaluates MI_FIELD in SERVER Optional MI_REGEX = <regular expression>

The expression that is used with the MI_FIELD value to determine if an item in the first ExtraView server maps to an item in the second ExtraView server.  If MI_FIELD is set, then this entry is required.
Identifying the field in SERVER2 upon which synchronization occurs Optional MI_FIELD2 = <ExtraView field name>

Identify the field to be inspected for the MI_REGEX evaluation to determine if an item in the second ExtraView server maps to an item in the first ExtraView server.
The expression which evaluates MI_FIELD2 in SERVER2 Optional MI_REGEX2 = <regular expression>

The expression that is used with the MI_FIELD2 value to determine if an item in the second ExtraView server maps to an item in the first ExtraView server.  If MI_FIELD is set, then this entry is required.
The expression which determines whether an issue in SERVER maps to an issue in SERVER2 Optional In this expression, a string in the form "__NAME__" refers to a field name in the ExtraView issue; when the expression is evaluated, this string is substituted with the value of the field in the issue being tested.

Examples

MI_POLL_TRIGGER = <Boolean expression with replaceable variables>
MI_POLL_TRIGGER = "__area__" eq "Empty Area"
 
The expression which determines whether an issue in SERVER2 maps to an issue in SERVER Optional In this expression, a string in the form "__NAME__" refers to a field name in the ExtraView issue; when the expression is evaluated, this string is substituted with the value of the field in the issue being tested.

Examples

MJ_POLL_TRIGGER = <Boolean expression with replaceable variables>
MJ_POLL_TRIGGER = "__area__" eq "Empty Area"
EVPOLLWAITTIME Optional The number of milliseconds between poll times of the first server (SERVER).  The default is 10,000 milliseconds (10 seconds)
EVPOLLWAITTIME2 Optional The number of milliseconds between poll times of the second server (SERVER2).  The default is 10,000 milliseconds (10 seconds)
ATTACHMENT_UPSERT Optional This is a switch which can have the values of YES or NO.  When the value is YES, attachments are uperted along with the issues upon synchronization
SOCKET_TIMEOUT_SECONDS Optional This timeout sets the time within which the integration daemon should wait for a response from both the source and target servers.  The default value for this is 300 seconds.  If the records being synchronized are large, or there are a significant number of attachments, document fields or image fields, then this number should be increased, perhaps to 800 or 1000
PUSH_DOWN_FILTERS Optional See the following section
PUSH_DOWN_FILTERS2 Optional See the following section

Note: The Poll Interval for the task and the configuration options EVPOLLWAITTIME and EVPOLLWAITTIME2 have different purposes.  The default times for these three options should work well for most instances.  The task's Poll Interval is the frequency with which commands to the task (such as START_NOW and STOP_NOW) are processed.  The EVPOLLWAITTIME and EVPOLLWAITTIME2 are independent timers that control how often the two background threads (EVPOLLWAITTIME and EVPOLLWAITTIME2) check their work queues, once the task is running.  Note that the Poll Interval is set in seconds, while EVPOLLWAITTIME and EVPOLLWAITTIME2 are set in milliseconds.

Push Down Filters

In order to extract the issues from the SERVER to synchronize with SERVER2, ExtraView performs queries on the SERVER database.  To make these queries more efficient, thereby speeding the process, there are two properties, PUSH_DOWN_FILTERS and PUSH_DOWN_FILTERS2 that specify filters that are added to the queries that extract data from the ExtraView SERVER for replication to the peer server SERVER2.

 The syntax of the PUSH_DOWN_FILTERS parameters is the same as the syntax for MI_POLL_TRIGGER - namely, an expression including the substitutable variables __area__ and __project__ with the operators eq and ne.

 PUSH_DOWN_FILTERS is the parameter name for the SERVER filters and PUSH_DOWN_FILTERS2 is the parameter name for SERVER2.

 Example: to exclude issues from a business area titled Engineering Issues:

 PUSH_DOWN_FILTERS = __area__ ne "Engineering Issues"

 Example: to include only issues from the business area titled Engineering Issues and a project titled Contacts Project Data:

PUSH_DOWN_FILTERS = __area__ eq "Engineering Issues" || __project__ eq "Contacts - Project Data"

Notification Options

Notification is provided to administrators via email upon error conditions as follows

DAEMON_ERROR_
NOTIFICATION_INTERVAL		 Optional Notifications will be sent to the administrators no more often than the number of minutes specified in this property 
DAEMON_WARN_
NOTIFICATION_COUNT		 Optional Error email notification will not be sent until DAEMON_WARN_NOTIFICATION_COUNT error logs have occurred in DAEMON_WARN_NOTIFICATION_INTERVAL minutes
DAEMON_WARN_
NOTIFICATION_INTERVAL		 Optional Error email notification will not be sent until DAEMON_WARN_NOTIFICATION_COUNT error logs have occurred in DAEMON_WARN_NOTIFICATION_INTERVAL minutes
DAEMON_ERROR_
THRESHOLD		 Optional Errors that are sent to the log are not reported until there are DAEMON_ERROR_THRESHOLD errors

Logging Properties

LOG_FILE_PATH_NAME The EV Peer Daemon log file
LOG_FILE_PATH_
NAME_ABSOLUTE		 This setting may be used for standalone installations on Windows, or when ExtraView is running within a war file
USE_SYSTEM_LOG If this setting is Y, the daemon will use the ExtraView application server log file as opposed to the log file defined in LOG_FILE_PATH_NAME
PSP_LOG Use this statement with a value of Y if you want to write the SQL from the task to the log file
XML_LOG_FLAG Set this to a value of TRUE if you want to use XML format within the log file
LOG_FILE_MAX_SIZE The maximum size of the log file, before it rolls over to a new file, in kB
LOG_CHARSET This should be UTF-8
LOG_INCLUDE_
THREAD_NAME		 A value of YES writes the Java thread name with each entry into the log file
DEFAULT_LOG_LEVEL The default log level for the daemon.  The usual value is 6
LOG_LEVEL The log level for the daemon.  The usual value is 6
LOG_DATE_FORMAT A valid date format to use in generating log records.  The default is yyyy-MM-dd
LOG_TIME_FORMAT A valid time format to use in generating log records.  The default is kk:mm:ss
LOG_TIME_AT_CREATION This entry may be true or false.  If true, the log file name is generated with a creation date/time string appended. The default is false.
LOG_FILE_MANAGE_SCRIPT The name of a script to run when switching log files. The default is none

Cloned Issues

If an issue that is mapped is subsequently cloned, the mapping identity field should not be propagated to the cloned issue.  The reason for this is that it would establish a mapping from one peer issue to two issues (i.e. the original issue and its clone).  This is not a fatal error, but the behavior would be odd, causing updates to the peer issue for each update to either the original issue or the cloned issue.  To handle this behavior, there is a data dictionary attribute that prevents the cloning of the field value for specific fields.  This attribute is set when the field is used as a mapping field in the integration daemon.

Setting the DO_NOT_CLONE data dictionary attribute for a field means that the containing field's value will not be propagated to any clone of an issue -- its value will be null in the cloned issue.