Integration Configuration

Configuration File

The configuration file for the Salesforce integration is named sf.properties and is located in the configuration directory of the INTEGRATION_HOME installation directory. The sample configuration file that is included with the integration package contains the majority of the settings supported by the Salesforce 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 sf.properties file is a plain text file that can be edited with any simple text editor. Please don't 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.

Salesforce Properties

The Salesforce account and security token used by the integration daemon to communicate with the Salesforce system must be specified as follows:

SF.user = <Salesforce account name/email address>
SF.password = <Salesforce account password>
SF.securityKey = <Salesforce account security token>

For example:

SF.user = email@domain.com
SF.password = password
SF.securityKey = aBC1DefghijklmNo2pqrs345

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

Field Mapping

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

sffn.<Salesforce object name>.<Salesforce field name> = evfn.<ExtraView field name>

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

evfn.<ExtraView field name> = sffn.<Salesforce object name>.<Salesforce field name>

For example, to integrate the Name field in the Salesforce Account object with the ExtraView field SF_ACCT_NAME specify the following line:

sffn.Account.Name = evfn.SF_ACCT_NAME
  • At least one field mapping entry has to be specified. Without the minimal field mapping, the daemon will terminate before the polling commences.
  • Date field mapping does not support custom date format on ExtraView, so make sure to use one of the standard date formats when configuring the ExtraView account used by the integration daemon.
  • Only Long and Full with Time date formats store TimeZone information, so the these date formats must be used for replication of TimeZone information.
  • For the MP_POLL_TRIGGER, MP_FIELD and MP_REGEX settings, the referenced fields must be mapped to ExtraView fields with the <SalesForce object name>.<SalesForce field name> syntax. Substituable variables using the MP_POLL_TRIGGER setting must have a single space character after each one, when encloded in quotes.

Value Mapping

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

sfv.<Salesforce object name>.<Salesforce field name>.<value> = 
      evv.<ExtraView field name>.<value>

As with the field mapping, the "sfv" and "evv" strings can be on either side of the equal sign. For example, for the Salesforce Account object with list field Status that is mapped to ExtraView field SF_STATUS, the following lines map the values between the two fields:

sfv.Account.Status.Yes = evv.SF_STATUS.Active
sfv.Account.Status.No = evv.SF_STATUS.Inactive
It is important that each value for list fields be mapped to exactly one other value between the Salesforce and ExtraView systems. If a Salesforce 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.

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 "Salesforce" in the field SOURCE in a new ExtraView issue, then add the following line to the configuration file:

INSERT_VALUES.SOURCE = Salesforce
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.

Omitting Values from the Update Process

There are occasions when you do not want to update Salesforce fields as part of the update or upsert process.  The following syntax allows you to specify fields that you do not want to update in Salesforce with an insert or update operation:

SF_READONLY_FIELDS = <Salesforce field name>, <Salesforce field name>, ...

Any number of fields may be specified in the comma-delimited list.

Salesforce Filtering

Records in the Salesforce 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 Salesforce records is specified with the following two settings:

MP_FIELD = <Salesforce object name>.<Salesforce field name>
MP_REGEX = <Regular expression>

The MP_FIELD setting specifies the name of the Salesforce field to use in checking for a match of the Salesforce record. The MP_REGEX setting specifies a regular expression that is applied to the value of the Salesforce field specified by MP_FIELD. See the Regular Expressions Appendix for more information. If the Salesforce 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 mapping settings. If the Salesforce 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 Salesforce records of Account object type with AccountName field value starting with a followed by any character(s) (including none), indicated by .*:

MP_FIELD = Account.AccountName
MP_REGEX = a.*

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

MP_POLL_TRIGGER = <boolean/arithmetic expression>

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

__<Salesforce object name>.<Salesforce field name>__
Note: there should be a single space at the end of the expression, after the two underscores.

See the Arithmetic/Boolean Expressions Appendix for more information. If the Salesforce 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 mapping settings. If the Salesforce 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 Salesforce records of Account object type either with a Type field value of "Integration" or an AccountNumber field value greater than 0:

MP_POLL_TRIGGER = "__Account.Type__ " eq "Integration" || "__Account.AccountNumber__ " gt 0
  • There should be a single space at the end of the expression, after the two underscores
  • When the filter settings are commented out, they automatically default to true. Thus, all records pass filtering and are included in the integration.
  • When specifying an expression for the MP_POLL_TRIGGER setting, all text or non-numeric values as well as Salesforce field names should be enclosed in quotes. Numeric values should not be quoted.
  • The MP prefix stands for Map Peer, where Peer is a generic term for integrations with multiple products. The Peer is Salesforce in this case.

ExtraView Filtering

The filtering of ExtraView records is very similar to the Salesforce 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 Salesforce 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 SF_STATUS field value of "Active":

MI_FIELD = SF_STATUS
MI_REGEX = Active

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>__
Note: there should be a single space at the end of the expression, after the two underscores.

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 Salesforce using the configured mapping settings. 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"
  • There should be a single space at the end of the expression, after the two underscores
  • When the filter settings are commented out, they automatically default to true. Thus, all records pass filtering and are included in the integration.
  • 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.

Integration Fields

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

EVID_FIELD = <Salesforce field name>
EVURL_FIELD = <Salesforce field name>
PEERID_FIELD = <ExtraView field name>
SFOBJTYPE_FIELD = <ExtraView field name>
PEER_URL_FIELD = <ExtraView field name>

The EVID_FIELD settings specifies the name of the Salesforce field that stores the ExtraView record ID. The EVURL_FIELD setting specifies the name of the Salesforce field that stores the URL link to the ExtraView record. The PEERID_FIELD setting specifies the name of the ExtraView field that stores the Salesforce record ID. The SFOBJTYPE_FIELD setting specifies the name of the ExtraView field that stores the Salesforce object name mapped to the ExtraView record. The PEER_URL_FIELD setting specifies the name of the ExtraView field that stores the URL link to the Salesforce record. In addition, the SFOBJTYPE_DEFAULT setting indicates the Salesforce object name to use when the integration daemon creates a new Salesforce record from a filtered ExtraView record. This setting is required to be defined in the configuration file. It works in conjunction with the SFOBJTYPE_FIELD setting to provide a default Salesforce object name to use in the integration process, especially when the object name is not provided in the ExtraView record filtered by the integration.

SFOBJTYPE_DEFAULT = <Salesforce object name>

For example, the following settings define the required integration fields, with the default Salesforce object name of Account:

EVID_FIELD = EVID__c
EVURL_FIELD = EV_URL__c
PEERID_FIELD = SFOBJID
SFOBJTYPE_FIELD = SFOBJTYPE
PEER_URL_FIELD = SFURL
SFOBJTYPE_DEFAULT = Account

Notice that the Salesforce fields in the above example have the "__c" string appended to the end of the field name to indicate that they are custom fields in Salesforce.

URL Links

In conjunction with the EVURL_FIELD described above, there are settings for controlling how the URL link to the ExtraView record is generated:

EVID_REPL =  <variable name>
SERVER_REPL = <variable name>
DRILLDOWN_URL = <URL to ExtraView record>

The EVID_REPL setting specifies the name of a variable that is used for the ExtraView record ID in the DRILLDOWN_URL setting. The SERVER_REPL setting specifies the name of a variable that is used for the ExtraView server URL in the DRILLDOWN_URL setting. The DRILLDOWN_URL setting specifies the URL link to the ExtraView record for populating the field specified by the EVURL_FIELD setting. The variables specified in the EVID_REPL and SERVER_REPL settings may be used in the URL link, and if so, they are replaced with the actual values of the record ID and ExtraView site URL, respectively. For example, the following settings define two variables, MYEVID and SERVER, that are used to compose the URL link to the ExtraView Edit screen for the record. Notice that all variable names must be surrounded with the two-underscore (__) syntax.

EVID_REPL = __MYEVID__
SERVER_REPL = __SERVER__
DRILLDOWN_URL = __SERVER__/evSignon?p_action=doEditDisplay&p_option=Display&p_id=__MYEVID__
The default values for these settings are usually left unchanged, unless the URL link for the ExtraView record is meant to perform a different function than editing the record.

Logging

The following optional settings control how the Salesforce 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.

Timing Settings

This setting controls the behavior of the integration with respect to timing operations: SFBINDTIMEOUT defines the number of milliseconds for the Salesforce binding timeout, that is how long the integration will wait to establish a connection to the Salesforce system before stopping. Note that the minimum value of this setting is 60000 (60 seconds), so if a smaller value is configured, then the minimum value will be used by default. For example:

SFBINDTIMEOUT = 60000

Polling Times

The integration daemon communicates with the Salesforce 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 SF_TIMESTAMP and EV_TIMESTAMP settings stored in the sf.properties file. 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 Salesforce system. The default value is 10000 (10 seconds). For example, to have the integration daemon query Salesforce for updates every minute, use the following setting:

POLLWAITTIME = 60000