Product Documentation

Create ExtraView User

Create a new ExtraView user that will be used by the Integration Daemon to access the ExtraView API to create and update issues in ExtraView. This user must be assigned a role that has access to query and update mapped fields on ExtraView screens. See the Edit Configuration File section for the list of fields that are to be mapped between Perforce jobs and ExtraView issues.

Create ExtraView Job Name Field

In the Data Dictionary administration section of ExtraView, add a new UDF Text Field that will be used to contain the Perforce job name. For example, you can call the new job name field PERFORCE_JOB_NAME. Note that if you are configuring the installation to connect to repeating rows in ExtraView, that you should create the field with the Field belongs to attribute set to Repeating row records. The job name is permitted to contain "-", "_", "$", "." and alphanumeric characters in any position.

Modify ExtraView Layouts

In ExtraView, either modify existing layouts or create new layouts for the adding, editing, and searching of ExtraView issues that will be mapped to Perforce jobs. If your ExtraView site uses role-specific layouts, modify the layout that corresponds to the role of the new ExtraView user created for Integration Daemon use.

Set Security Permissions for the Mapped Fields

In the Administration section of ExtraView, grant both add and edit field-level security permissions to read and write for the ExtraView issue fields that are mapped to Perforce job fields for the role given to the ExtraView user created above.

Set Behavior Setting for Repeating Rows

If you intend to map Perforce jobs to repeating rows within ExtraView, you must make sure that the behavior setting in the Administration System Controls section named MULTI_RELEASE_XML is set to YES.

Set Status Change Rules

If you have the behavior setting named ENABLE_STATE_CHANGE_RULES set to YES, assign the appropriate status change rules according to your designed workflow for the ExtraView user role used in the integration. This behavior setting is found in the Workflow settings section of administration. Setting the status change rules is found in the same administration section.

ExtraView – Perforce Field Mapping

Determine which ExtraView issue fields will be mapped to Perforce job fields, and vice versa. This step will define a critical piece of the ExtraView – Perforce Integration. Define a mapping between new or existing Perforce Jobspec fields and new or existing ExtraView Data Dictionary fields. For example, using the sample Jobspec from the previous section, define a mapping between the Perforce EVid field and the ExtraView ID field. Another sample mapping may be between the Perforce DESCRIPTION field and the ExtraView DESCRIPTION field.

Mapping the Status fields

Both ExtraView and Perforce have a field named STATUS that has special treatment within each software product. However, ExtraView’s treatment of the STATUS field is considerably more sophisticated than that of Perforce. This introduces some challenges in the integration process and the administrator must make some decisions about how the integration work flow should be managed. The most important point is that for ExtraView to successfully synchronize issues to their counterpart jobs in Perforce there must exist a single status value in each product that maps to each other. If you do not do this then updates between each product may be ambiguous as to their status. We suggest you use these guidelines –

• Create a new select-type field in Perforce with the same values as the STATUS field in ExtraView
• Map each value to its corresponding value in the other product (instructions follow later in this section)
• If you have configured status change rules in ExtraView, these rules are not enforced in Perforce. If your users make errors in the following of your workflow through the change in value of the STATUS field, this may have significant repercussions on your ability to synchronize issues. For example, if a user is not allowed to move a Closed issue to Fixed in ExtraView, but makes this change in Perforce, the synchronization of the issue will fail, as ExtraView will not allow the transition to take place. Such errors are reported in the log file. If you are seriously concerned about this potential for lost updates, you may want to turn off the status change rules in ExtraView

Mapping user name fields

User names are mapped between ExtraView and Perforce. If the user names are identical in both systems, they are mapped automatically, with no configuration being required in either ExtraView or Perforce. You can individually map user field names between ExtraView and Perforce. In this way, you can match unlike user names between the two systems.

Edit the Configuration File

The Perforce Integration Daemon configuration file is named p4.properties and is located in the configuration/ directory of your installation. Edit the p4.properties file and set the following settings.

Perforce Executable, server name and port

The Perforce p4 command-line interface must be installed on the same system as the integration daemon, and the absolute path to the p4 command must be specified as follows along with the address and port of the Perforce server:

p4.executable = <path to p4 command>
p4.port = <server>:<port>

For example,

p4.executable = C:\\Program Files\\Perforce\\P4.EXE  (on Windows)
p4.executable = /usr/local/bin/p4  (on Unix)
p4.port = localhost:1666

Notice the double back-slash characters (\\) that are used for escaping purposes on Windows systems.

Perforce client, user, and password

The Perforce client and the account credentials created for the integration must be specified with the following settings. For ticket-based authentication, assign the p4.password setting to the ticket value.

p4.client = <client name>
p4.user = <user name>
p4.password = <user password>

For example,

p4.client = CLIENT1
p4.user = user1
p4.password = password1

Note that two additional configuration items, p4.sysdrive and p4.sysroot, must be specified for Microsoft Windows installations. These set the system drive and system root, respectively. For example,

p4.sysroot = C:\\WINDOWS
p4.sysdrive = C:

Perforce Threshold

This optional setting provides the number of milliseconds to wait for a response from the Perforce repository before assuming it is not available. The default value for this setting when not defined is 30000 (i.e., 30 seconds). For example:

P4.threshold = 30000

Perforce Logging

The integration daemon records all the commands issued to the Perforce server and responses received to a separate log file named debug.log that can be turned on with the following settings:

p4.log_level = <p4 log level>
P4_LOG_DIR = <directory name>

For example:

p4.log_level = 99
P4_LOG_DIR = logs

Note that the Perforce log file name, debug.log, is fixed and cannot be changed. The log levels supported by the Perforce interface are listed below:

ExtraView URL, user, and password

SERVER = http://<server>/evj/ExtraView/ev_api.action
USER = <user name>
PASSWORD = <user password>
For example,
SERVER = http://server.domain.com/evj/ExtraView/ev_api.action
USER = integration_user
PASSWORD = integration_password

Field Name Mapping

p4fn.<Perforce field> = evfn.<ExtraView field>
evfn.<ExtraView field> = p4fn.<Perforce field>

For example,

p4fn.Description=evfn.DESCRIPTION
evfn.PERFORCE_JOB_NAME=p4fn.Job

Field Value Mapping

p4v.<Perforce field>.<value> = evv.<ExtraView field>.<value>
evv.<ExtraView field>.<value> = p4v.<Perforce field>.<value>

For example,

p4v.EVStatus.NEW=evv.STATUS.New
p4v.user.user1=evv.user.integration_user

Logging

The logging options set in the initial p4.properties file are likely to be sufficient for most implementations, but if you want additional controls, the following options are available to be set in the p4.properties file.

Debug Levels

The value set for the log level indicates that all log messages less than or equal to that level will be sent to the log file.

Filter Perforce Jobs

This section explains how to filter updates to Perforce jobs, such that only the changes you want are propagated to ExtraView. The configuration file entries are:

MJ_FIELD = <Perforce field>
MJ_REGEX = <regular expression>
MJ_POLL_TRIGGER = <boolean/arithmetic expression>

For each modified job or job that is part of a submitted changelist, one or two tests are executed to determine whether or not to propagate the job values to ExtraView: the MJ_FIELD test and the MJ_POLL_TRIGGER test. If either test passes, then the job values are propagated to ExtraView for creation or modification of an item associated with that job. These tests are similar to the MI_FIELD and MI_POLL_TRIGGER tests used for ExtraView issues. The MJ_FIELD test requires two property settings: MJ_FIELD and MJ_REGEX. The MJ_FIELD identifies a Perforce job field. The MJ_REGEX is a regular expression, which is applied to the job field current value, and, if there is a match in the regular expression, the test passes. See Regular Expressions Appendix for the definition of regular expressions. The MJ_POLL_TRIGGER test requires only the MJ_POLL_TRIGGER property, which is a text string containing a Boolean/arithmetic expression. If the expression evaluates to non-zero, then the test passes.

Within the expression there can be replaceable variable names: these are job field names from the Perforce job that are surrounded by “__”, for example, "__Status__". It is recommended to enclose the replaceable variable names in double quotes (e.g., "__Status__") to avoid problems when the field has no value.

As part of the expression evaluation, the replaceable variable names are replaced with the dynamic values obtained from the job under test. See Arithmetic/Boolean Expressions Appendix for the syntax of an arithmetic/Boolean expression. For example, the following settings cause Jobs with a Status value of "closed" or EVpriority values of either "Critical" or "High," to be propagated to ExtraView:

MJ_FIELD = Status
MJ_REGEX = closed
MJ_POLL_TRIGGER = "__EVpriority__" eq "Critical" || "__EVpriority__" eq "High"

Filter ExtraView Issues

This section explains how to filter updates to ExtraView records in order to transfer only the updates you want to Perforce jobs:

MI_FIELD = <ExtraView field>
MI_REGEX = <regular expression>
MI_POLL_TRIGGER = <boolean/arithmetic expression>

For each modified item in the ExtraView histories, one or two tests are executed to determine whether or not to propagate the item modifications to Perforce: the MI_FIELD test and the MI_POLL_TRIGGER test. If either test passes, then the item is propagated to Perforce for creation or modification of a job associated with that item. These tests are very flexible, making them somewhat complex; it is for this reason that we describe them here in detail. The MI_FIELD test requires two property settings: MI_FIELD and MI_REGEX. The MI_FIELD identifies an ExtraView field whose value is part of the item’s history. The MI_REGEX is a regular expression, which is applied to the field value, and, if there is a match in the regular expression, the test passes. See Regular Expressions Appendix for information on regular expressions.

The MI_POLL_TRIGGER test requires only the MI_POLL_TRIGGER property, which is a text string containing a Boolean/arithmetic expression. If the expression evaluates to non-zero, then the test passes. Contained within the expression can be replaceable variable names: these are field names from the ExtraView item that are surrounded by "__", for example, "__STATUS__". It is recommended to enclose the replaceable variable names in double quotes (e.g., "__STATUS__") to avoid problems when the field has no value.

As part of the expression evaluation, the replaceable variable names are replaced with the dynamic values obtained from the ExtraView item under test. See Arithmetic/Boolean Expressions Appendix for the syntax of an arithmetic/Boolean expression. For example, the following settings cause ExtraView records with a Priority value containing a 1 or 2, or with a Status of "Open", "Fixed", or "Closed" to be propagated to Perforce:

MI_FIELD = PRIORITY
MI_REGEX = [12]
MI_POLL_TRIGGER = "__STATUS__" eq "Open" || "__STATUS__" eq "Fixed" || "__STATUS__" eq "Closed"

JOBNAME_FIELD

This setting must be assigned to the name of the ExtraView field that corresponds to the mapped Perforce Job field.

JOBNAME_FIELD = <ExtraView Job Name field>

For example:

JOBNAME_FIELD = PERFORCE_JOB_NAME

EVID_FIELD

This field identifies the name of the Perforce field that contains the mapped ExtraView item ID field

EVID_FIELD = <Perforce field mapped to ExtraView ID value>

For example:

EVID_FIELD = EVid

EVURL_FIELD

Identify the name of the Perforce field that contains the URL for drill down to the associated ExtraView item. Note that this is a required field for the integration daemon to operate. For example:

EVURL_FIELD = EVurl

EVID_REPL

Identify the ID replacement variable for DRILLDOWN_URL. The default value should not be changed. For example:

EVID_REPL = __EVID__

SERVER_REPL

Identify the server variable name for the DRILLDOWN_URL. The default value should not be changed. For example:

SERVER_REPL = __SERVER__

DRILLDOWN_URL

Identify the URL to use to drill down into ExtraView issues from Perforce. This is used to populate the field in Perforce specified by the EVURL_FIELD setting. For example:

DRILLDOWN_URL = http://server.domain.com/evj/ExtraView/evSignon?
p_action=doEditDisplay&p_option=Display&p_id=__EVID__

FIXJOB_EVSTATUS

Perforce has the concept of “fixed jobs”. When a modification to the job moves it to the “fixed” status, and then that modification is propagated back to ExtraView, the STATUS and RELEASE_STATUS fields on the ExtraView issue are changed to the configured FIXJOB_EVSTATUS value. For example, to set the ExtraView status to FIXED when the Perforce job gets fixed use the following setting:

FIXJOB_EVSTATUS = FIXED

JOBNAME_PATTERN

The configuration property JOBNAME_PATTERN is optional. If set, it contains the pattern to be used to generate a job name in Perforce when there is no mapped job name from the issue or the mapped job name is invalid, such as all blanks. The JOBNAME_PATTERN may contain mapped issue field names for variable substitution. These are, like those in the regular expressions used elsewhere in p4.properties, surrounded by double underline characters. Note that it is important to include at least one field that makes the job names unique per issue. Otherwise, a one-to-many mapping of jobs to issues will occur, causing indeterminate replications. You can use __ID__ to guarantee uniqueness.

The substituted value will be the ID of the issue, and, if the job name field is mapped to a repeating row, it will consist of the issue ID appended with "." and the repeating row id. For example:

JOBNAME_PATTERN = evjob__ID__

This will produce job names like evjob1123, or evjob1123.123456789 (for repeating rows).

INSERT_VALUES

This setting can be used to assign default values for fields on new ExtraView records created by the integration daemon.

INSERT_VALUES.<ExtraView field name> = <ExtraView field value>

For example:

INSERT_VALUES.STATUS = New

P4_INSERT_VALUES

You may use the configuration property P4_INSERT_VALUES to set default values for fields in Perforce jobs. The syntax is the same as that for INSERT_VALUES:

P4_INSERT_VALUES.<p4fieldname>=<value> 

P4DESC and P4DESC_DIFFS settings

The P4DESC and P4DESC_DIFFS settings work together to propagate changelist information from Perforce jobs to ExtraView issues. The changelist must be linked to the job at the time of the update in order for the changelist information to be propagated. The P4DESC settings specifies the location in ExtraView where to store the description of the changelist from Perforce, and the P4DESC_DIFFS setting specifies where to store the file diffs generated from the changelist. For both settings, the valid values are: comment, file, or none. The "comment" value maps directly to the COMMENTS field; the "file" value causes the changelist information to be uploaded to the ExtraView issue as a file attachment; the "none" value means that no changelist information will be propagated to ExtraView. For example, the following configuration settings update the COMMENTS field in ExtraView with the changelist information (both description and file diffs) from the Perforce job:

P4DESC = comment
P4DESC_DIFF = comment

P4DESC_MAXSIZE

The property P4DESC_MAXSIZE = <character count> provides for an escape valve when changelist descriptions become very large, for example, 10,000 or more files in a single changelist. The <character count> is an integer that defines the threshold length of the description field, greater than which the description is added as an attachment, and not as an ExtraView issue field value. This is only relevant when P4DESC = comment or P4DESC = fieldname. If P4DESC = none, then no description is replicated to the issue, and if P4DESC = file, then the description field always goes to a file attachment to the issue. For example, if P4DESC = comment and P4DESC_MAXSIZE = 4000, then all changelist descriptions with more than 4000 characters will be replicated to the ExtraView issue as an attachment, and all changelist descriptions of 4000 characters or less will be replicated to the comments field.

POLLWAITTIME

You can set the time interval between accesses to both Perforce and ExtraView with this setting. The wait time is expressed in milliseconds.

Triggering Notification on Synchronization

Each job can specify whether or not to send email notification when the ExtraView issue is updated by the Integration Daemon. This is accomplished through an ExtraView pseudo-field called SEND_MAIL. SEND_MAIL can take on either of two values: YES or NO. When the value is YES, notification is sent, when it NO, no email notifications are sent. If the value is not present or is anything other than YES, it is treated as NO. By default, the value is always null, unless specified by the Perforce interface mapping, so no notifications will be sent. To send emails optionally based on values in the job fields, define a job field in the P4 job specification to map to the SEND_MAIL field in the ExtraView issue. This could be done as in the example p4.properties snippet as follows:

p4fn.GenerateEmail=evfn.SEND_EMAIL
p4v.GenerateEmail.Y=evv.SEND_EMAIL.YES
p4v.GenerateEmail.N=evv.SEND_EMAIL.NO

What this says is that the p4 job field "GenerateEmail" will map to the ExtraView item pseudo-field named SEND_EMAIL. For a value of "Y" in the GenerateEmail field in the P4 job, notification of email updates will occur, because this maps to the value of YES for the pseudo-field SEND_EMAIL. Otherwise, the update will not cause any notification.

Perforce Job Pseudo Fields

These are special fields with the following properties:

• These fields do not exist in any Perforce job and are not replicated there
• They have specific semantics that depend on the name of the pseudo-field
• The pseudo fields may be mapped to ExtraView fields like any “real” Perforce job field
• Pseudo fields behave as if they are a "word" or "text" type (not a user, line, or select type)

Two pseudo-fields are implemented:

Example: The p4.properties file might contain:

p4fn.p4_filelist = evfn.fred_text_field

And, fred_text_field will be populated by something similar to:

//depot/42deltas.txt;//depot/ver1.0/got blanks/cfold.txt

Fields with Special Treatment

p4user.<Perforce field>

p4user.p4user1
p4user.p4user2
evv.user.freddieEV=p4.user.fred

aaaaa.bbbbbbbbbb

SOCKET_TIMEOUT_SECONDS

This provides the number of seconds to wait before timing out on an HTTP request to ExtraView. The default value is 600 (ten minutes) if it is not specified in the properties file.