This document contains instructions, steps, and examples for configuring and running the ExtraView Integration Daemon for Perforce to help in troubleshooting some common issues encountered during deployment or upgrades of the ExtraView software.
The version of the integration daemon software must be the same as the version of your ExtraView web application. The version of the integration daemon can be determined by looking at the lib/ directory for a file named evjNNN.jar, where NNN is the version number. This version number must match the version that is reported in the footer of your ExtraView site (e.g., “Release 7.0.1 Build 54”) or in the “Build label” line of the ExtraView Version Information utility in ExtraView Administration of your site. This is in order to maintain the same functionality of the ExtraView API that the integration daemon uses to communicate with the ExtraView application.
As with the ExtraView web application, before upgrading the integration daemon software in a production environment, the upgrade needs to be tested in a test or other non-production environment in order to validate functionality and correct operation.
The upgrade of the integration daemon involves downloading the distribution file (i.e., integrationdaemon_win.zip or integrationdaemon_unix.tar) of the version you are upgrading to, performing a backup of the old version, installing the new version in a new location, un-installing and re-installing the Windows service (if used), and copying the configuration files from the old version to the new version. The specific steps to execute are:
configuration/p4.properties data/Perforce/state.properties
The most common reason for the ExtraViewIntegrationDaemon Windows service failing to install or startup is an improperly configured installIntegrationDaemonService.bat script. This script needs to be configured with paths for your specific environment. The following lines in the installation script need to be specified:
set INTEGRATION_HOME=C:\ExtraView\integrationdaemon
set JAVA_DLL_HOME=C:\ExtraView\jdk1.5.0_22\jre\bin\server
ExtraViewService.exe -install ExtraViewIntegrationDaemon "%JAVA_DLL_HOME%\jvm.dll" "-Djava.class.path=%cp%" -start "com.extraview.sccintegration.common.IntegrationDaemon" -params -i %integration% -f %INTEGRATION_HOME%\start_commands.txt -out %INTEGRATION_HOME%\out.log -err %INTEGRATION_HOME%\err.log -current %INTEGRATION_HOME%
If the Windows service fails to start, the out.log and err.log files generated by the service can be used to determine the cause of the failure in addition to the Windows Event Viewer. If the Windows service fails to start due to mis-configuration of the install script, the service will need to be un-installed with the uninstallIntegrationDaemonService.bat script first before it is re-installed with the corrections made to the install script.
The out.log file captures text that the integration daemon writes to the standard output stream, which is normally generated when running the integration daemon manually from the command-line using the start_daemon.bat script. An example out.log file is:
Perforce Integration Daemon Started Setting event log:C:\ExtraView\PerforceDaemon\evj6501-21_integrationdaemon/logs/Perforce Attempting to Open Log File: C:\ExtraView\PerforceDaemon\evj6501-21_integrationdaemon\logs\error.log Log is:C:\ExtraView\PerforceDaemon\evj6501-21_integrationdaemon\logs\error.log Running without a queue... ERROR: P4 exited with an Error! An exception occured while running the integration daemon
The err.log file captures text that the Windows service or integration daemon writes to the standard error stream when encountering error conditions. Some example messages that are written to the err.log or Event Viewer are:
The Java Virtual Machine has exited with a code of 0, the service is being stopped. Could not create a FileOutputStream for System.err redirect.
The start_commands.txt file must contain the following lines in order for the integration daemon to poll both ExtraView and Perforce servers during operation:
e:start p:start
The following configuration settings for Perforce, the integration daemon, and ExtraView contain the minimum settings needed for the integration daemon to run successfully, and can be used to test the installation of a new or upgraded daemon. Comments have been removed to conserve documentation space.
Perforce jobspec (i.e., p4 jobspec –o):
Fields:
101 Job word 32 required
102 Status select 10 required
103 User word 32 required
104 Date date 20 always
105 Description text 0 required
110 EVid word 10 optional
111 EVurl line 50 optional
Values:
Status open/suspended/closed
Presets:
Status open
User $user
Date $now
Description "default description"
Note that the Perforce default fields (Job, Status, User, Date, Description) are not altered, and two new fields, EVid and EVurl, are added to the jobspec. The preset for Description is set to “default description” instead of the default $blank because it is a required field and must contain some text.
p4.properties (Windows example):
p4.executable=c:\\Program Files\\Perforce\\P4.EXE p4.port=perforce.yourdomain.com:1666 p4.user=my_p4_user p4.client=my_p4_client p4.password=my_p4_password p4.sysroot=c:\\WINDOWS p4.sysdrive=c: SERVER = http://extraview.yourdomain.com/evj/ExtraView/ev_api.action USER = evp4d PASSWORD = my_password p4fn.EVid=evfn.ID p4fn.Job=evfn.PERFORCE_JOB_NAME P4DESC = comment P4DESC_DIFFS = comment MJ_FIELD = Job MJ_REGEX = \\w MI_FIELD = ID MI_REGEX = \\d JOBNAME_FIELD = PERFORCE_JOB_NAME EVURL_FIELD = EVurl EVID_FIELD = EVid EVID_REPL = __EVID__ SERVER_REPL = __SERVER__ DRILLDOWN_URL = __SERVER__/evSignon?p_action=doEditDisplay&p_option=Display&p_id=__EVID__
Note that you will need to replace the default values for the p4 settings (e.g., p4.port, p4.user, etc.) pointing to your Perforce server and the SERVER, USER, and PASSWORD settings pointing to your ExtraView server with actual values that match your environment. The PERFORCE_JOB_NAME Text field will need to be created on your ExtraView site, which is covered below.
For Unix environments, you can use the same p4.properties example above (replacing the default values with ones matching your environment), but remove the lines containing the p4.sysroot and p4.sysdrive settings.
The minimal configuration file maps just two critical and required fields between the ExtraView and Perforce systems: ID to EVid, and PERFORCE_JOB_NAME to Job. These fields are used to link records from one system to the other by using their unique record identifiers (ID in ExtraView, Job in Perforce). The MJ_FIELD and MJ_REGEX settings match any job in Perforce with a Job name of any alphanumeric character including underscore (_) as denoted by the \w regular expression, and the MI_FIELD and MI_REGEX settings match any record in ExtraView with ID containing a digit as denoted by the \d regular expression. Therefore, this configuration will propagate ALL records in ExtraView to new jobs in Perforce, and any new jobs in Perforce are created as new records in ExtraView; updates to existing Perforce jobs or ExtraView records are also propagated to the other system by the integration daemon. This is the simplest integration that synchronizes all records between the two systems.
ExtraView site configuration:
The ExtraView site needs to be configured with the access permissions necessary for the integration daemon to read and write to records, and with the new Text field used to store the Perforce job identifier. Alternatively, you may use the special ADMIN account to bypass security permissions in order to perform quick validation.
Select Business Area = * Global Area * Select Project = * Master Project * Field belongs to = Issue records Fixed name = PERFORCE_JOB_NAME Title to display = Perforce Job Display type = Text Field Allow selection on reports = Yes (optional) Filter criteria = Yes (optional) Is sortable = Yes
The file diffs generated for submitted changelists in Perforce for all files contained in the changelists can be propagated to ExtraView records at the time the changelist is submitted while linked to Perforce jobs. The file diffs can be attached to the ExtraView record either as an attachment file or as text content in the COMMENTS field. This behavior is configurable in p4.properties with the P4DESC and P4DESC_DIFFS settings. For example, the following settings attach the file diffs to the COMMENTS field:
P4DESC = comment P4DESC_DIFFS = comment
While the following settings add the file diffs as an attachment to the record:
P4DESC = file P4DESC_DIFFS = file
To turn off file diffs completely, use the following settings:
P4DESC = none P4DESC_DIFFS = none
Note that the COMMENTS field is the only field supported by this functionality; other fields of Log Area type cannot be used here.
The file diffs are only included in the ExtraView record at the time the changelist is submitted IF the changelist is linked to the job; otherwise, linking a changelist to a job after the changelist is submitted will not cause the file diffs to be propagated. This works in conjunction with the P4_CHANGE setting in the state.properties file, so only changelists with a number higher than the value in this setting will be processed.
In order to troubleshoot problems that are not easily detected by reviewing the configuration of the integration daemon or the log files generated with normal logging, higher logging for debug purposes can be turned on. To turn on debugging perform the following steps:
DEFAULT_LOG_LEVEL=10
The DEFAULT_LOG_LEVEL setting increases the logging in the default error.log file. Another common log level used for debugging is 8.
P4_LOG_DIR=\\logs p4.log_level=99
The P4_LOG_DIR and p4.log_level settings turn on debug logging for the Perforce side of the integration, writing all the Perforce commands executed by the integration daemon into a file named debug.log or p4.log.
The purpose of the integration daemon is to synchronize changes between records on the Perforce and ExtraView servers. In order for the integration daemon to know how to propagate changes from one system to the other, fields on the records that are to be synchronized need to be mapped across the two systems. Not all fields on the records in either Perforce or ExtraView need to be mapped in the p4.properties configuration file; only the ones to be synchronized need to be specified. Before mapping fields, it is important to consider the types of fields the integration daemon will handle. It is recommended that only fields of similar types be mapped with the integration daemon in order for the synchronization operations to succeed.
Perforce supports the following types of fields: word, text, line, select, date
ExtraView supports the following field types: Button, Checkbox, Currency, Custom, Date, Day, Decimal, Document, HTML Area, Image, Label, List, Log Area, Number, Pop-up, Print Text, Radio Button, Tab, Text Field, Text Area, User
The most common mappings of fields by type are the following (although not all of these may have been tested or work):
P4 word—EV User, Currency, Decimal, Number, Date, Day
P4 text—EV Text Area, Print Text, HTML Area, Log Area
P4 line—EV Text Field
P4 select—EV List, Pop-up, Tab, Checkbox, Radio Button
P4 date—EV Date, Day (with custom date mask; see note below)
The following format is used to specify field mapping in the p4.properties file:
p4fn.<Perforce fieldname> = evfn.<ExtraView fieldname>
or
evfn.<ExtraView fieldname> = p4fn.<Perforce fieldname>
Note that the ExtraView fieldnames are specified as the fixed names configured in the ExtraView Data Dictionary, whereas the Perforce fieldnames are specified in the jobspec Fields section. Each field mapping is on a separate line.
For Perforce fields of select type, the set of values configured for the field must be mapped to the values of a field in ExtraView with similar type (e.g., list). The format of the value mapping specified in the p4.properties file is:
p4v.<Perforce fieldname>.<value> = evv.<ExtraView fieldname>.<value title>
or
evv.<ExtraView fieldname>.<value title> = p4v.<Perforce fieldname>.<value>
The fieldnames are the same as the ones specified above in the fieldname mappings. The Perforce fieldname values are the ones specified in the jobspec Values section; the ExtraView fieldname value titles are the “Title to display” values for the list-type fields in ExtraView. The value mapping must be unique for all values of the two fields; the same value in one ExtraView field cannot be mapped to more than one value in the Perforce field, and vice versa. If a value mapping does not exist for one or more of the values in a field, such as when adding new values to a list field while the integration daemon is running, then synchronizations for records containing the new values will most likely fail due to missing mappings in the integration daemon. The p4.properties file will need to be updated with the latest value mappings and the integration daemon restarted.
ExtraView fields of User display type have a special format of value mappings. In addition to the fieldname mapping that needs to be configured (covered above), the following setting must also be specified in the p4.properties file to identify a Perforce fieldname as a User-type field:
p4user.<Perforce fieldname>
Then, the names of the users in the two systems are mapped with the following format:
p4v.user.<username> = evv.user.<username>
or
evv.user.<username> = p4v.user.<username>
The usernames are the unique account names or user IDs that identify the users in the ExtraView and Perforce systems.
A special note about date fields in Perforce: in order to map a Perforce date field to an ExtraView Date or Day field, the following custom mask must be configured for the ExtraView account used by the integration daemon due to the strict date format used by the Perforce server: yyyy/MM/dd HH:mm:ss
When a record is updated in either Perforce or ExtraView, the integration daemon determines whether the update should be transferred or propagated to the other system by comparing the contents of the record with some settings in the integration daemon configuration file (p4.properties). The following settings are use for the comparison test:
MJ_FIELD = <Perforce fieldname> MJ_REGEX = <regular expression> MJ_POLL_TRIGGER = <boolean/arithmetic expression> MI_FIELD = <ExtraView fieldname> MI_REGEX = <regular expression> MI_POLL_TRIGGER = <boolean/arithmetic expression>
There are two sets of settings: the ones beginning with MJ_ are used to check the Perforce record for a match (MJ stands for Map Job); the ones beginning with MI_ are used to check the ExtraView record (MI stands for Map Issue).
The MJ_FIELD and MI_FIELD settings must specify a single fieldname that exists in the Perforce jobspec and the ExtraView Data Dictionary, respectively.
The REGEX settings must specify a regular expression that is used in conjunction with the corresponding FIELD setting to test whether the record matches the regular expression for the field. If the record matches the regular expression for the field configured in the REGEX and FIELD settings (which must be defined together), then the update is propagated to the other system; if no match occurs, then the updates is not propagated, unless there is a POLL_TRIGGER setting defined that matches the record (see below). The regular expressions supported in the integration daemon must be supported by the Java programming language, and are described in an Appendix of the documentation. When designing regular expressions, keep in mind that certain characters, such as backslash (\), period (.), parentheses or brackets, have special meanings or usages, and some characters may need to be “escaped” using the backslash (\) character.
Some example FIELD and REGEX settings:
MJ_FIELD = Job MJ_REGEX = \\w
MI_FIELD = ID MI_REGEX = \\d
MI_FIELD = PRIORITY MI_REGEX = [12]
MJ_FIELD = Status MJ_REGEX = closed
The POLL_TRIGGER settings are secondary means of determining whether updates are to be propagated. This setting must specify a Boolean or arithmetic expression that is compared with the update performed on the record. If the POLL_TRIGGER expression matches the record updated, then it is propagated to the other system; if the expression does not match, then the update is not propagated, unless the FIELD and REGEX settings (described above) match the record update. The Boolean or arithmetic expression may contain field names (which must be enclosed in double-underscores, e.g., “__STATUS__”), any literal values, and different operators used for comparison or operations (e.g., || for logical-OR, + for addition, == for equivalence, etc.). The documentation lists the supported format and all operators available for use in configuring the POLL_TRIGGER expression.
Some example POLL_TRIGGER settings:
MI_POLL_TRIGGER = "__STATUS__" eq "Open" || "__STATUS__" eq "Integrated"
MJ_POLL_TRIGGER = “__EVid__” ne ""
MI_POLL_TRIGGER = ("__AREA__" eq "Bugs" && “__BUG_COUNT__” gt 1) ||
("__PROJECT__" eq "Defects" && “__TYPE__” eq “Software”)
Some special notes about the FIELD, REGEX, and POLL_TRIGGER settings:
When starting the integration daemon with the start_daemon.bat script (on Windows, or the Windows service) or start_daemon.sh script (on Unix) the daemon may fail to start for several reasons.
The p4.properties configuration file does not match the ExtraView and/or Perforce systems.
Review all the contents of the p4.properties configuration file to verify that all settings are configured correctly. Make sure that the Perforce server settings, ExtraView server settings, field and value mappings, and that all the settings listed in the Minimal Configuration section in this guide are defined appropriately. For the ExtraView side, login with the credentials configured in p4.properties and verify that all the ExtraView fields specified in the p4.properties file are visible on the Detailed Report for the account’s default user role.
The ExtraView and/or Perforce servers cannot be reached
If the ExtraView server is not running or is incorrectly configured in the p4.properties file you may see one of several error messages reported in the standard output and/or the error.log file:
An exception occured while running the integration daemon
java.lang.Exception: EVRSP: HTTP response code =404
An exception occured while running the integration daemon
java.lang.Exception: EVRS: error accessing ExtraView: alert code is:1/
('com.extraview.presentation.api.EvApiException: An invalid User ID or an invalid password was entered.')
[Fatal Error] :1:1: Content is not allowed in prolog.
An exception occured while running the integration daemon
[Fatal Error] html4_loose_dtd.mht:31:3: The declaration for the entity "HTML.Version" must end with '>'.
An exception occured while running the integration daemon
If the Perforce server is not running or incorrectly configured in the p4.properties file you may see the following error reported in the standard output and the error.log file:
ERROR: P4 exited with an Error! 2011-12-16 16:11:03 [ ERROR] P4C: cannot connect to Perforce: check port/password/client, etc.:[com.perforce.api.PerforceException: No output from p4 user -o]
ExtraView server configuration does not match the p4.properties file
The most common problem with the configuration of the ExtraView site that the integration daemon point to is a field that is mapped or specified in the p4.properties file but is missing from one of the Add, Edit, or Detailed Report layouts. The following type of error messages are written to the error.log file when this occurs:
2009-10-27 09:48:00 [ ERROR] EVI: referenced field does not exist in ExtraView:dev_perforce_jobname
2011-08-10 13:27:51 [ CRITICAL] EV2Peer: Missing Fields in EV:[perforce_job_name, tn_resolution,
tn_current_est_completion_date, task_assigned, tn_change_desc, tn_add_sub_value, date_created, tn_task_summary]
2011-08-10 13:27:51 [ CRITICAL] EV2Peer: Illegal Fields in EV:{}
2011-08-10 13:27:51 [ CRITICAL] EV2Peer: Illegal Insert Values:{}
To resolve this problem:
The servers do not respond to requests made by the integration daemon in a timely manner
Connections to the servers may be affected by network congestion or other network factors, such as proxy servers, firewalls, etc. In order to determine connectivity to the ExtraView and Perforce servers, test connecting to them from the machine the integration daemon is installed on using such networking tools as ping and telnet. The recommended location for the integration daemon is either on the same machine that the ExtraView or Perforce server is running on or on a separate machine that has fast network access to both servers.
An example error message written to the error.log file when this problem occurs is:
2011-08-10 14:46:40 [ ERROR] P4C: cannot connect to Perforce: check port/password/client, etc.:[com.perforce.api.PerforceException: No output from p4 user -o]
For the Perforce side, the P4.threshold setting can be adjusted to a value higher than the default 30000 milliseconds in order to alleviate this problem.
The Perforce authentication method is not supported by the integration daemon.
For example, if the Perforce server is running at security level 3, which requires ticket-based authentication, the integration daemon will not work with its username/password credentials.
To resolve this problem:
Updates to Perforce jobs or ExtraView records may fail to be propagated to the other system due to several reasons:
Some example errors that indicate this type of problem are:
2011-08-25 13:08:44 [ ERROR] Exception = com.perforce.api.CommitException: error: Error in job specification.error: Error detected at line 2. error: Value for field 'Status' must be one of open/assigned/closed. 2011-12-16 14:33:21 [ ERROR] Exception = com.perforce.api.CommitException: error: Error in job specification.error: 'Description' field blank. You must provide it. 2011-11-04 16:48:02 [ ERROR] Exception = java.lang.Exception: EVRS: error accessing ExtraView: alert code is:1/Exception in doUpdate: com.extraview.applogic.problem.ValidationException: 10108 is not a valid Problem. 2011-09-06 08:53:24 [ ERROR] Exception = com.perforce.api.CommitException: error: Error in job specification.error: Error detected at line 22.error: Invalid date 'Sep 2, 2011'. 2011-09-02 15:43:26 [ ERROR] Exception = com.perforce.api.CommitException: error: Error in job specification.error: Error detected at line 22. error: Wrong number of words for field 'Completion-Date'.
For example, if the PROJECT field is used in the MI_POLL_TRIGGER setting to filter which records to synchronize by project, then the PROJECT field must be configured on the Detailed Report layout and the integration daemon ExtraView account must have Read access to this field.
An example error for this problem is the following:
2010-07-14 09:37:54 [ ERROR] Exception = java.lang.Exception: EVRS: error accessing ExtraView: alert code is:1/Exception in doUpdate: com.extraview.applogic.problem.ValidationException: You cannot change from status Assigned to null.
Whenever the integration daemon encounters an error condition, the specific error is written to the error.log file. Some of the errors recorded to the log are self-explanatory while other errors are less descriptive, especially if there is an unexpected error or software bug encountered. For the errors that are not easily understood, it is recommended to turn up the debugging level in the daemon in order to collect additional information about the error and submit the log file to ExtraView Support for research.
Some examples of errors seen in the error.log file follow:
The following message is written to the log due to a conversion error, in this case because a line-type field in Perforce was mapped to a UDF List field in ExtraView. This mapping of incompatible and not supported with the integration daemon.
[ ERROR] Exception = java.lang.Exception: EVRS: error accessing ExtraView: alert code is:1/ SQL Exception in doUpdate: java.sql.SQLException: Syntax error converting the nvarchar value '7.1 HF1' to a column of data type int.
The following message is written to the log due to the p4.properties file missing any field mapping or problem parsing the list of fields provided either from ExtraView or Perforce.
2011-11-09 16:07:45 [ CRITICAL] EV2Peer: validateMapping(): No Mapping Information is Available
The following message indicates a general error encountered by the integration daemon while trying to add a new record to ExtraView. To determine the cause of this error, you need to review the EVJ.log file generated by the ExtraView application for errors recorded at the same time the error was recorded in the error.log file.
2011-09-02 09:35:05 [ ERROR] Exception = java.lang.Exception: EVRS: error accessing ExtraView: alert code is:1/Exception in doInsert: java.lang.Exception: An error occurred trying to insert this record. Please contact your administrator.
The following message states that the integration daemon cannot connect to the Perforce server with the settings configured in the p4.properties file. Verify that you can connect to the Perforce server with the credentials specified in p4.properties, the authentication method is supported by the integration daemon, and the Perforce server responds within the threshold configured (may be default) in the p4.properties file.
2011-08-10 14:46:40 [ ERROR] P4C: cannot connect to Perforce: check port/password/client, etc.:[com.perforce.api.PerforceException: No output from p4 user -o]
When the integration daemon processes changelists to generate file diffs, there may be cases where the filename paths do not exist any longer or have special characters not supported by the integration daemon, resulting in the following message written to the error.log file. These types of errors do not affect the synchronization of records; they just affect the file diff propagation.
2011-01-27 17:18:35 [ ERROR] P4I: diff files exception:java.io.IOException: error: //ESG/ESG_TOOLS/PCMD/PCMD/PCMD_FORMAT/My#1 - no such file(s).
The following generic error requires high debug logging in order to determine the cause:
2011-01-25 14:10:16 [ ERROR] TP-Processor7 Exception = java.lang.NullPointerException java.lang.NullPointerException
A note about warnings or lines with the WARN log level: most of the warnings written to the error.log file are written for information purposes and do no affect the operation of the integration daemon. These warnings can be safely ignored. Some example warnings that are written to the log file are the following:
2011-11-09 16:06:50 [ WARN ] Daemon: Running without a queue... 2011-11-09 16:06:50 [ WARN ] Daemon: queue error is:Cannot get message queue: queue/B exception is:javax.naming.CommunicationException: Receive timed out [Root exception is java.net.SocketTimeoutException: Receive timed out]
Sometimes it may be necessary to re-synchronize records between ExtraView and Perforce that were modified in the past, such as when updates or changelists are missed due to a particular reason or error, or when testing and troubleshooting issues with updates not getting picked up. In order to force the integration daemon to synchronize older updates, the integration daemon must be stopped and the state.properties configuration file must be edited. The state.properties file must not be altered while the integration daemon is running because it is update automatically by the integration daemon.
The state.properties file ( in the data/Perforce/ directory) contains the following type of lines:
#Cutoff values for EVInterface and PeerInterface #Thu Nov 10 08:32:32 PST 2011 EV_TIMESTAMP=2011-11-10 08\:32\:11.294 -0800 P4_CHANGE=17 P4_TIMESTAMP=2011-11-10 08\:32\:22.000 -0800
The EV_TIMESTAMP setting specifies the timestamp of the last update that was propagated from ExtraView to Perforce, while the P4_TIMESTAMP setting specifies the timestamp of the latest update from Perforce to ExtraView. Changing either of these to a previous date (or newer date) will cause the integration daemon to obtain changes made to records since the timestamps specified and synchronize records accordingly. When this happens, the timestamp settings will be automatically updated by the integration daemon.
The P4_CHANGE setting specifies the latest changelist number that was processed by the integration daemon. Changing this value to a lower (or higher) changelist number will cause the integration daemon to process changelists from that number onward and propagate the file diffs to ExtraView records according to the p4.properties configuration. Note that the changelists must be linked to Perforce jobs in order for changelist file diffs to be propagated to ExtraView records.