Integration Configuration

Configuration File

The configuration file for the JIRA integration is named jira.properties and is located in the INTEGRATION_HOME/configuration directory. The sample configuration file that is included with the integration package contains the majority of the settings supported by the JIRA integration, along with examples and brief descriptions of the different settings used. The section below lists all of the settings available for use in the configuration file.

The jira.properties file is a plain text file that can be edited with any simple text editor. Do not use Microsoft Word or other editors that may introduce special or non-plain text characters in the file. Lines that start with the # character are considered comments and are ignored by the integration. Blank lines are also ignored. After making changes to the configuration file, make sure to stop and start the integration daemon in order for the changes to take effect.

JIRA Properties

The JIRA account and server URL used by the integration daemon to communicate with the JIRA system must be specified as follows:

jira.server = <JIRA server address and port>
jira.user = <JIRA user id>
jira.password = <JIRA user password>

For example:

jira.server = http://localhost:8080
jira.user = userid
jira.password = password

ExtraView Properties

The ExtraView account and server URL that the integration daemon uses to communicate with the ExtraView system must be specified with the following configuration settings:

SERVER = <ExtraView site URL, ending in ev_api.action>
USER = <ExtraView account userid>
PASSWORD = <ExtraView account password>

For example:

SERVER = http://server.domain/evj/ExtraView/ev_api.action
USER = userid
PASSWORD = password

Integration Fields

The JIRA and ExtraView fields required for the purposes of the integration (see the JIRA Configuration and ExtraView Configuration pages) must be specified with the following configuration settings:

EVID_FIELD = <JIRA field name>
JIRA_ID_FIELD = <ExtraView field name>

The EVID_FIELD settings specifies the name of the JIRA field that stores the ExtraView record ID. The JIRA_ID_FIELD setting specifies the name of the ExtraView field that stores the JIRA record ID. In addition, the DEFAULT_JIRA_PROJECT and DEFAULT_JIRA_ISSUETYPE settings indicate the JIRA Project name and Issue Type values to use when the integration daemon creates a new JIRA record from an ExtraView record. These setting are required to be defined in the configuration file.

DEFAULT_JIRA_PROJECT = <JIRA Project name>
DEFAULT_JIRA_ISSUETYPE = <JIRA Issue Type>

For example, the following settings define the required integration fields, with the default Project name of Bugs and Issue Type value of Bug:

EVID_FIELD = EV_ID
JIRA_ID_FIELD = JIRA_ID
DEFAULT_JIRA_PROJECT = Bugs
DEFAULT_JIRA_ISSUETYPE = Bug

Field Mapping

The JIRA and ExtraView fields to be integrated must be specified in the configuration file with the following field mapping syntax:

jirafn.<JIRA field name> = evfn.<ExtraView field name>

The jirafn and evfn strings can be on either side of the equal sign, so the following syntax is equivalent:

evfn.<ExtraView field name> = jirafn.<JIRA field name>

For example, to integrate the JIRA Summary field with the ExtraView SHORT_DESCR field specify the following line:

jirafn.Summary = evfn.SHORT_DESCR
  • The field mappings for the required integration fields must be specified at a minimum. For example:
    jirafn.Key = evfn.JIRA_ID
jirafn.EV_ID = evfn.ID
  • Fields mapped should be of similar type in order for the integration to work properly. For example, a JIRA field of Select List type is mapped to an ExtraView field of List type (or Pop-up type); a JIRA field of Date Picker type is mapped to an ExtraView field of Day type; etc.
  • The following JIRA System fields are supported by the integration daemon: Assignee Affects Version/s Comment Description Due Date Fix Version/s Issue Type Key Project Priority Resolution Reporter Status Summary
  • The following JIRA Custom field types are supported by the integration daemon: Date Picker Date Time Free Text Field (unlimited text) Multi Select Number Field Select List Radio Buttons Text Field (< 255 characters)
  • The ExtraView field name specified must be the "Fixed name," not the "Title to display" attribute of the field entry in Data Dictionary.
  • Spaces in field names must be escaped with the \ character. For example:
    jirafn.Due\ Date = evfn.DUE_DATE
  • In ExtraView, the CLI_EDIT_MULTI_VALUE_FIELDS behavior setting must be turned on in order for multi-value fields to be accessible by the integration daemon.
  • In ExtraView, the LOG_AREA_TEMPLATE behavior setting must be set to the default value of "$$LA_DATE$$ $$LA_USER$$" when mapping a Log Area type ExtraView field to the JIRA Comments field; this is to ensure the correct parsing of log area entries by the integration daemon.

Value Mapping

For mapped fields that are of list or enumerated type, the values need to be mapped one-to-one using the following syntax:

jirav.<JIRA field name>.<value> = evv.<ExtraView field name>.<value>

As with the field mapping, the jirav and evv strings can be on either side of the equal sign. For example, for the JIRA list field Status that is mapped to ExtraView UDF list field JIRA_STATUS, the following lines map the values between the two fields:

jirav.Status.Open = evv.JIRA_STATUS.Open
jirav.Status.In\ Progress = evv.JIRA_STATUS.In\ Progress
  • It is important that each value for list fields be mapped to exactly one other value between the JIRA and ExtraView systems. If a JIRA field value is not mapped or is mapped to more than one ExtraView field value (and vice-versa), then errors will be generated during the synchronization process of the integration daemon and records may fail to be propagated between the systems.
  • As with field mapping, spaces in field names and/or values must be escaped with the \ character, as illustrated in the example above.

User Mapping

When mapping user fields (JIRA User Picker field type and ExtraView User field type) in the integration, and the usernames differ between the JIRA and ExtraView systems, then the mapping between users must be specified in the following format:

jirav.user.<JIRA user id> = evv.user.<ExtraView user id>

The jirav and evv strings can be on either side of the equal sign. For example:

jirav.user.adams = evv.user.asmith
The user mapping is specified only once for all user type fields mapped in the integration, which is different than the value mapping of list fields which needs to be defined for each individual field.

JIRA Version Mapping

When mapping JIRA fields of version type, such as the standard Affects Versions and Fix Versions fields or custom fields of Single Version Picker or Version Picker field type, the version values are associated to individual projects. The value mappings for all version type fields is specified in the following format:

jirav.<JIRA project key>|version.<JIRA value> = evv.version.<ExtraView value>

Note the use of the JIRA Project key concatenated with the | character and "version" word, to specify the project that the version value is associated with. For example:

jirav.BUG|version.1.0.0 = evv.version.1.0.0
Similar to the user mapping, the version mapping is specified only once for all version type fields mapped in the integration.

One-way Field Mapping

To configure specific fields to be treated as read-only in either ExtraView or JIRA, thereby performing one-way propagation, the following configuration settings are to be used:

EXTRAVIEW_READONLY_FIELDS = <ExtraView field name>, <ExtraView field name>, ...
JIRA_READONLY_FIELDS = <JIRA field name>, <JIRA field name>, ...

The EXTRAVIEW_READONLY_FIELDS setting specifies a list of ExtraView fields that are not to be updated by the integration daemon. The JIRA_READONLY_FIELDS setting specifies a list of JIRA fields that are not to be updated by the integration daemon. Note that both of these settings specify a comma-delimited list of field names. For example, to ensure that the STATUS and SHORT_DESCR fields in ExtraView are not modified by the integration daemon from the mapped fields in JIRA, use the following configuration setting:

EXTRAVIEW_READONLY_FIELDS = STATUS, SHORT_DESCR

Insert Values

The integration daemon can be configured to assign default values to ExtraView fields when inserting new records into the ExtraView system, with the following syntax:

INSERT_VALUES.<ExtraView field name> = <value>

For example, to assign a value of JIRA for the field SOURCE in a new ExtraView issue, then add the following line to the configuration file:

INSERT_VALUES.SOURCE = JIRA
Insert values for Date and Day fields must be be specified in the same format configured in the ExtraView user's personal options. Failing to following this can cause errors during the integration process.

JIRA Filtering

Records in the JIRA system can be filtered to be included in the integration based on two filtering options: field/regex and poll trigger. You may either use both filtering options or choose to configure only one of the two options. The field/regex option of filtering JIRA records is specified with the following two settings:

MJ_FIELD = <JIRA field name>
MJ_REGEX = <Regular expression>

The MJ_FIELD setting specifies the name of the JIRA field to use in checking for a match of the JIRA record. The MJ_REGEX setting specifies a regular expression that is applied to the value of the JIRA field specified by MJ_FIELD. See the Regular Expressions Appendix for more information. If the JIRA record matches the regular expression for the field, then this record passes the filtering and is included in the integration; that is, it is propagated to ExtraView using the configured mappings. If the JIRA record does not match, then the poll trigger filtering option is used to determine whether the record is included in the integration. For example, the following settings filter JIRA records with a EV_ID field value that contains one or more digits, indicated by [0-9]+:

MJ_FIELD = EV_ID
MJ_REGEX = [0-9]+

The poll trigger option of filtering JIRA records is specified with the following single setting:

MJ_POLL_TRIGGER = <boolean/arithmetic expression>

The MJ_POLL_TRIGGER setting specifies an expression containing boolean and/or arithmetic terms to be matched with JIRA records. The expression may include JIRA field names specified using the following syntax:

__<JIRA field name>__

See the Arithmetic/Boolean Expressions Appendix for more information. If the JIRA record matches the poll trigger expression, then this record passes the filtering and is included in the integration; that is, it is propagated to ExtraView using the configured mappings. If the JIRA record does not match, then the field/regex filtering option is used to determine whether the record is included in the integration. For example, the following setting filters JIRA records in the "Bugs" Project with a non-empty EV_ID field value:

MJ_POLL_TRIGGER = "__Project__" eq "Bugs" && "__EV_ID__" ne ""
  • When any of the filter settings are commented out, they automatically default to true. Thus, all records pass filtering and are included in the integration.
  • The order that the filters are applied to records is: field/regex first, poll trigger second. If the field/regex filter passes, then the poll trigger filter is not applied. Note that when the poll trigger filter is commented out, then all records automatically pass the filtering (even if they don't pass the field/regex filter).
  • When specifying an expression for the MJ_POLL_TRIGGER setting, all text or non-numeric values as well as JIRA field names should be enclosed in quotes. Numeric values should not be quoted.
  • The MJ prefix stands for Map JIRA, used for filtering JIRA records.

ExtraView Filtering

The filtering of ExtraView records is very similar to the JIRA filtering mechanism, with different configuration settings. Records in the ExtraView system can be filtered to be included in the integration based on two filtering options: field/regex and poll trigger. You may either use both filtering options or choose to configure only one of the two options. The field/regex option of filtering ExtraView records is specified with the following two settings:

MI_FIELD = <ExtraView field name>
MI_REGEX = <Regular expression>

The MI_FIELD setting specifies the name of the ExtraView field to use in checking for a match of the ExtraView record. The MI_REGEX setting specifies a regular expression that is applied to the value of the ExtraView field specified by MI_FIELD. See the Regular Expressions Appendix for more information. If the ExtraView record matches the regular expression for the field, then this record passes the filtering and is included in the integration; that is, it is propagated to JIRA using the configured mapping settings. If the ExtraView record does not match, then the poll trigger filtering option is used to determine whether the record is included in the integration. For example, the following settings filter ExtraView records with CATEGORY field value that contains character B followed by any character (including none), as indicated by .*:

MI_FIELD = CATEGORY
MI_REGEX = B.*

The poll trigger option of filtering ExtraView records is specified with the following single setting:

MI_POLL_TRIGGER = <boolean/arithmetic expression>

The MI_POLL_TRIGGER setting specifies an expression containing boolean and/or arithmetic terms to be matched with ExtraView records. The expression may include ExtraView field names specified using the following syntax:

__<ExtraView field name>__

See the Arithmetic/Boolean Expressions Appendix for more information. If the ExtraView record matches the poll trigger expression, then this record passes the filtering and is included in the integration; that is, it is propagated to JIRA using the configured mappings. If the ExtraView record does not match, then the field/regex filtering option is used to determine whether the record is included in the integration. For example, the following setting filters ExtraView records with STATUS field values of either "New" or "Open":

MI_POLL_TRIGGER = "__STATUS__" eq "New" || "__STATUS__" eq "Open"
  • When any of the filter settings are commented out, they automatically default to true. Thus, all records pass filtering and are included in the integration.
  • The order that the filters are applied to records is: field/regex first, poll trigger second. If the field/regex filter passes, then the poll trigger filter is not applied. Note that when the poll trigger filter is commented out, then all records automatically pass the filtering (even if they don't pass the field/regex filter).
  • When specifying an expression for the MI_POLL_TRIGGER setting, all text or non-numeric values as well as ExtraView field names should be enclosed in quotes. Numeric values should not be quoted.
  • The MI prefix stands for Map Issue, where Issue is the generic term for ExtraView records.

Logging

The following optional settings control how the JIRA integration records information about its operations to a log file, which can be used for debugging and troubleshooting purposes. If these settings are not defined or are commented out in the configuration file, then the default values are used by the integration.

Setting Default Value Description
DEFAULT_LOG_LEVEL 6 A number in the range of 1 to 12 that controls the amount of information written to the log file. Numbers higher than 6 are different debug levels, which write progressively detailed information as the number increases.
LOG_DATE_FORMAT yyyy-MM-dd The date format to use in generating log records.
LOG_TIME_FORMAT kk:mm:ss The time format to use in generating log records.
LOG_FILE_MANAGE_SCRIPT none Name of a script to run when switching log files.
LOG_FILE_MAX_RETAINED -1 (infinite) The maximum number of old log files retained, when switching from one log file to the next.
LOG_FILE_MAX_SIZE 10000 This is the maximum size (in bytes) that the logger will permit the log file to grow before creating a new log file and archiving the old log file.
LOG_FILE_DIR logs The directory name to use for storing the log file.
LOG_FILE_NAME error.log The file name for the log file.
LOG_FILE_DIR_ABSOLUTE false If "true", the directory name for the log file is absolute; if "false", the directory name is relative to the installation directory.
LOG_FILE_PATH_NAME_ABSOLUTE false If "true", the file path name for the log file is absolute; if "false", the file path name is relative to the installation directory.
LOG_TIME_AT_CREATION false If "true", the log file name is generated with a creation date/time string appended; if "false", the log file name is the default name.
XML_LOG_FLAG false Defines log format: "true" is for XML format; "false" is for plain text.

Polling Times

The integration daemon communicates with the JIRA and ExtraView systems on a periodic basis to query for newly updated or created records since the last time updates were processed (based on the JIRA_TIMESTAMP and EV_TIMESTAMP settings stored in the state.properties file, described in the Running the Integration Daemon page). The polling period for each of the systems can be controlled with the following configuration settings: EVPOLLWAITTIME defines the number of milliseconds between subsequent queries to the ExtraView system, that is how often to poll the ExtraView system for changes. The default value is 10000 (10 seconds). For example, to have the integration daemon check ExtraView for changes every 30 seconds, use the following setting:

EVPOLLWAITTIME = 30000

POLLWAITTIME defines the number of milliseconds between queries to the JIRA system. The default value is 10000 (10 seconds). For example, to have the integration daemon query the JIRA system for updates every minute, use the following setting:

POLLWAITTIME = 60000

Attachments

All files attached to records in JIRA and ExtraView are automatically propagated between the systems, by default. However, the ATTACHMENT_UPSERT configuration setting can be used to control this behavior.

ATTACHMENT_UPSERT = <YES|NO>

For example, to bypass attachments synchronization during record updates, use the following setting:

ATTACHMENT_UPSERT = NO