Connectors

Connector Rules

The Connector Rules table (afm_conn_rule_cat) lists the available rules that can be applied to the data during the transfer between systems. A common example is formatting a date string from two disparate systems.

The Connectors ship with several rules. Each rule has a Rule Name (Rule Code), a description that describes the behavior of the rule, and the name of the Java Class that implements the described behavior.

Define your own rules using the System / System Administrator / Define Connector Rules task. For information, see Define Connector Rules.

Predefined Connector Rules

Rule Code	Description	Parameters
ADD	On import, adds the imported value to the value in the Archibus database. For new records the value is assumed to be zero.	None.
ASSET VALIDATION	Validates a record against Archibus data schema and stores the resulting errors in a field's value. It is used by Enterprise Assets.	None.
CONCATENATE	Appends values of multiple fields and specified text, and assigns the result to the field on which the rule is specified.	A pipe ("\|") delimited list of values to append, with field values being specified by their position in question marks ("?"). For example: "?1?\|:\|?2?" would append the value for the field in position 1, a colon, and the value in position 2. If the value in position 1 is A, and in position 2 is B, then the result would be "A:B".
CONVERT ENUMERATED PARAM VALUE	Replaces the value with a mapped value specified in parameters.	A JSON object with two attributes: `enumList`: an object whose attributes are the original values and the values of those attributes the values to replace the original values with. `preserveUnmapped`: whether to preserve values which do not appear in the enumList.
CONVERT ENUMERATION LIST VALUE	Replaces the value with the description from the enum_list column of afm_flds on export, and reverses the operation on import.	None.
CONVERT NUMBER TO TEXT	Indicates how to represent a number in text.	The format for the number as specified by java.text.DecimalFormat.
CONVERT TEXT TO NUMBER .	Converts a text containing a decimal number to a java.lang.Number. The type of number depends on the data dictionary: small int and integer will be converted to java.lang.Integer, and other data types including fields not in the data dictionary will result in a java.lang.Double. Trailing white space will be trimmed before parsing	`valueIfNull`: the value the field should have if the input is null or an empty string. If not specified value will be null. `pattern`: the format for the number in text as specified by java.text.DecimalFormat. If not specified, an attempt will still be made to convert the decimal value.
CONVERT TO DATE	Indicates how to interpret a textual date, when converting it into a date field in the database, or when writing a database date to a text field.	The format for the date as specified by java.text.SimpleDateFormat*
CONVERT UNITS	Convert units of the field's values based on a unit qualifier in a second field and a map of conversion fractions.	A JSON object with two attributes: `conversionMap`: an object whose attributes are the unit qualifiers and the values of those attributes the values to multiply by the original values. For precision, this accepts fractions. (e.g. the target field requires feet (ft), the parameter might be: {INCH: 1/12, METER: 0.3048}) `unitField`: the field whose values are unit qualifiers.
COPY INHERITED VALUE	Copies a value from the last instance of another type of record. See COBie.	The ids of the "connector\|field" where the value should be copied from.
LOOKUP VALUE	Replaces the value of the field with the description from a validating table, and attempts to reverse the operation on import (assuming the description is unique).	Validating Table** The field on the Validating Table to use in place of the foreign key field.
MAX	On import, compares the imported value to the value in the Archibus database and assigns the larger value to the field. For new records the value is assumed to be larger.	None.
MIN	On import, compares the imported value to the value in the Archibus database and assigns the smaller value to the field. For new records the value is assumed to be smaller.	None.
NONE	Performs no translation to the field's value.	None.
POPULATE TABLE	Add or update a record in a validating table when this transaction is imported if the reference is to the validating table is present. The validating table is the one specified, or if not specified, then the referenced table on afm_flds. The fields for this record are foreign key fields or those specified in parameters.	Validating Table** A pipe ("\|") delimited list of field mappings. A field mapping is either a field name or a pair of field names delimited by a semi-colon (";") where the first is the source and the second is the target. The source field name is the name of the field from the remote system, and the target field name is the name of the field on the validating table.
POPULATE TRANSACTION	Copies values from an Archibus data record into the transaction record.	Validating Table*** A JSON object with these attributes: `restrictionMap`: Archibus field names to connector field ids, for fields to be used to identify the Archibus record to copy values from. `valueMap`: Archibus field names to connector field ids, for fields to be used to be copied from the Archibus record. `customRestriction` (optional): a SQL where clause that may have parameters as they would be specified in an Archibus data source. The parameter names are Source Field names from connector fields. (e.g. "afm_conversions.date_last_update < ${parameters['Date']}" ) `failOnMissingReference` (optional): defaults to false. If the record in the validating table isn’t found and this is set to true, an error will be logged for the record. If it’s set to false it uses the defaultValueMap parameter. `defaultValueMap`: a JSON object whose keys are the keys of the valueMap and the values are values to use if the referenced record isn’t found.
SEGREGATE BY DATA	Like POPULATE TRANSACTION, except this may result in more than one transaction record per source record.	See POPULATE TRANSACTION
SET CONFIG VALUE	Sets a value from the connector field.	The '.' delimited path of configuration attributes from the ConnectorFieldConfig class. (e.g. position would get the field's position, and connector.connectorId would get the connector id)
SET CURRENT DATE	Sets the value of the field to a textual representation of the current date (web server) in the specified format. If no format is specified, passes along a database compatible date.	The format for the date as specified by SimpleDateFormat*
SET CURRENT TIME	Sets the value of the field to a textual representation of the current time (web server) in the specified format. If no format is specified, passes along a database compatible time.	The format for the time as specified by SimpleDateFormat*
SET RECORD NUMBER	Sets the value of the field to the ordinal of the current transaction. The record number begins with 1 and is incremented even if the transaction is skipped.	None.
SET USER VALUE		The '.' delimited path of configuration attributes from ContextStore.get().getUser(). (e.g. email would get the email of the user who ran the connector and employee.id would get their employee id)
SET VALUE	Sets the value of the field to the textual value specified in the parameters.	The value to assign to the field.
SET VALUE IF NULL	Same as SET VALUE, but only if the value is null or empty.	The value to assign to the field.
SKIP DELETE	On import, if a value matches a value in valueSet, delete the record and then skip it.	`valueSet`: a JSON array of values for the field this rule is set on. `deleteRestriction`: a SQL restriction with ${field_id} tokens replaced by the values for the record.
SKIP FIELD	Do not extract, and if found remove the field from the transaction.	None.
SKIP IF NOT UNIQUE	Set the field on the transaction to the value specified in parameters when no field with the IDENTITY rule assigned has changed.	The value to assign to the field.
SKIP RECORD IF NOT CONTAINS	Skips the record if the value doesn't contain one of the values in the parameter.	A pipe ("\|") delimited list of field values.
SKIP RECORD IF NOT EQUALS	Skips the record if the value doesn't exactly match one of the values in the parameter.	A pipe ("\|") delimited list of field values.
SKIP RECORD IF NULL OR EQUALS	Do not process the transaction if this field's value is one of the listed value or if it's null.	A pipe ("\|") delimited list of field values.
SPLIT DELIMITED	Splits a value into multiple field values at a delimiter.	A JSON object with up to three attributes: `delimiterPattern`: a regular expression for the value delimiter. `targetFields`: a JSON array of fields trim: optional attribute, if present indicates that white space should be removed from the delimited values.
TRIM	Removes any leading or trailing white space characters (less than or equal to \u0020).	None.
TRUNCATE	Removal trailing characters from the string representation of the value until there are at most the number of characters specified in the parameter.	The number of characters to keep.
UPLOAD DOCUMENT	Upload a document specified by the field value after the Archibus record is updated.	The path, including trailing path delimiter, where files may be found.
VALIDATE - ADD	Same as POPULATE TABLE, but only if the record does not already exist in the validating table.	See POPULATE TABLE
VALIDATE - SKIP	Removes the field from the transaction if it does not exist in the validating table. If SkipRecord is set as a parameter, skips the transaction instead of removing the field.	Validating Table** "SkipRecord"

* In some cases SimpleDateFormat features are java version dependent, based on the version of Java running the application server.

** If validating table is specified, the specified table will be used, but must be referenced by another field on the Archibus table.

*** The rule may take a parameter of the form {ruleParam:'',recordFields:['field1','field2']} where ruleParam is the rule’s normal parameter, and recordFields identifies the fields on the record that map to the validating table’s primary key.