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.
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.
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.
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.
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.
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.
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.
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 –
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.
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.
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.
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:
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
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:
Name | Log Level | Description |
NONE | 0 | No debug messages are displayed. |
ERROR | 1 | Only error messages are displayed. |
WARNING | 2 | Error and warning messages are displayed. |
NOTICE | 3 | Error, warning, and notice messages are displayed. |
VERBOSE | 99 | Error, warning, notice, and verbose messages are displayed. |
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
p4fn.<Perforce field> = evfn.<ExtraView field>
evfn.<ExtraView field> = p4fn.<Perforce field>
For example,
p4fn.Description=evfn.DESCRIPTION
evfn.PERFORCE_JOB_NAME=p4fn.Job
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
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.
Keyword | Purpose |
DEFAULT_LOG_LEVEL | The logging level number. This specifies which log messages are sent to the log file: higher numbers denote the production of more detailed information within the log file |
LOG_DATE_FORMAT | <valid date format> The date format to use in generating log records. Default: yyyy-MM-dd |
LOG_TIME_FORMAT | <valid time format> The time format to use in generating log records: Default kk:mm:ss |
LOG_FILE_MANAGE_SCRIPT | <script name> Name of a script to run when switching log files. Default: none |
LOG_FILE_MAX_RETAINED | <number of log files> This is the maximum number of old log files retained, when switching from one log file to the next. Default is –1 (infinite). |
LOG_FILE_MAX_SIZE | Size of file in bytes This is the maximum size that the logger will permit the log file to grow (default is 10MB) before creating a new log file and archiving the old log file |
LOG_FILE_DIR | <directory pathname> The folder name to use for the log file. The default is INTEGRATION_HOME/logs |
LOG_FILE_NAME | <file name> The file name for the log file. The default is error.log |
LOG_FILE_DIR_ABSOLUTE | true or false If true, the directory name for the log file is absolute, not relative to the current log file directory |
LOG_FILE_PATH_NAME_ ABSOLUTE | true or false If true, the file path name for the log file is not relative to the current log file directory. The default is false |
LOG_TIME_AT_CREATION | true or false If true, the log file name is generated with a creation date/time |
XML_LOG_FLAG | true or false Defines log format: false (plain text) is the default |
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.
ALERT | 1 | Site level threat or problem |
CRITICAL | 2 | A configuration problem |
ERROR | 3 | A component of the system in not operational |
WARN | 4 | Example: A resource is getting low |
NOTICE | 5 | For notices to operations staff |
INFO | 6 | Normal program output like progress reporting |
DEBUG | 7 | All debug messages are at DEBUG or below |
DEBUG1 | 8 | |
DEBUG2 | 9 | |
DEBUG3 | 10 | |
DEBUG4 | 11 | |
DEBUG5 | 12 |
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"
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"
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
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
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
Identify the ID replacement variable for DRILLDOWN_URL. The default value should not be changed. For example:
EVID_REPL = __EVID__
Identify the server variable name for the DRILLDOWN_URL. The default value should not be changed. For example:
SERVER_REPL = __SERVER__
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__
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
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).
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
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>
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
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.
You can set the time interval between accesses to both Perforce and ExtraView with this setting. The wait time is expressed in milliseconds.
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.
These are special fields with the following properties:
Two pseudo-fields are implemented:
Pseudo Field | Explanation |
p4_filelist | This contains the list of file names affected by this job. The list is developed from the list of changes in the job. The file names include the depot path and are separated by semicolons |
p4_changelist | This contains the list of changes derived from the job. Each change is a number, and the changes are separated by semicolons |
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
Pseudo Field | Explanation |
LogArea fields | Fields with an ExtraView display type of LogArea, such as the ExtraView field named COMMENTS, receive special handling. The normal method of updating a comment is to append a new entry to existing comments. The integration process emulates this in the following manner, in order to avoid duplication of the existing comments in ExtraView. LogArea fields that are mapped from ExtraView to/from Perforce will be replicated in their entirety, including the all the historic comments. When modifying a LogArea field in Perforce, the user should only add new text to the end of the field; only the new text will be appended to ExtraView and the resulting LogArea field will be replicated back to the Perforce job |
User fields |
Defining a field to be a Perforce user field provides for a special kind of mapping where all mapped User ID's are shared across all Perforce user fields. To specify that a Perforce field will contain user ids (since there is not a data type in Perforce equivalent to ExtraView User-type), use the following syntax:
The Perforce field needs to be defined as a word or line type field in the Perforce jobspec. Additionally, the Perforce field needs to be mapped to an ExtraView User-type field with the field mapping syntax described above (e.g., p4fn.<Perforce field> = evfn.<ExtraView field>). For example, if you have two Perforce fields, p4user1 and p4user2, then you might want to use the user ID named FRED in either or both of these. FRED should be mapped once for all Perforce fields defined, rather than on a per-field basis, like other mappings. See the following:
Now, having a value of FRED in either the field p4user1 or the field p4user2 maps directly to the freddieEV user ID in ExtraView. This is different from other types of mappings because the mapping is not specific to the field, but to the field type, thus saving the repeated mapping of the field for each Perforce user field. |
ExtraView Repeating row fields |
If you map a field on ExtraView’s repeating row layout to the Perforce job, then the behavior of ExtraView is that it needs to know a different job number for each repeating row. The integration process creates a job number for each repeating row mapped, of the format:
where aaaaa is the ExtraView ID of the issue, and bbbbbbbbbb is the internal ID of the repeating row. This combination gives a unique mapping from each repeating row to each job. |
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.