Connectors

Connector Properties table

The Connector Properties table (afm_connectors) stores the principle properties for the Connector.  This includes the name, description, the source and destination of the data, the connection string to access or write the data and several other properties to define the characteristics of each Connector.

Access this table from the Properties tab on the System Administration / System Administrator / Configure Connectors task.

This topic lists the properties, global parameters, and actions.

Property Name Description Value Example

Connector Code

(code)

Uniquely identifies the connector

String

 My Connector

Description - XML Template

(description)

Description of the connector’s function.  In the case of XML exports this field is used to hold a record XML template.

Memo

Generic: This is my Connector

XML: <Record> <Building/> <Floor/> <Room Area="" Division="" Department=""/> </Record>

Connector Parameters

(conn_params)

Some Connector types, such as MS Excel or Custom Connectors may have additional optional configuration parameters.  These parameters are defined in this field using JavaScript Object Notation (JSON).

String - JSON

General: see below

Text: {"CharacterEncoding":"UTF8"}

SFTP: {"clientCertificateFileName":"C:\\privatekey.ppk"}

Excel: {"rowHeaderColor":{"red":218, "green":243, "blue":236},"cellDataColor":{"red":128, "green":128, "blue":120},"showBorder":false}

LDAP: {"securityAuthentication":"simple","securityProtocol":"none"}

Connector Type

(type)

Type of foreign data system and data format the connector will integrate Archibus with such as a delimited text file, database, XML, etc.

Integer – Enumeration List

 Text File

Import

(import_export)

Data direction – import or export

Integer – Enumeration List

 "Import" or "Export"

Archibus Table

(destination_table)

The Archibus table to import/export data to/from.  This field always represents the Archibus table, whether importing or exporting.

String, validated on afm_tbls

 bl

Remote Source

(Table, XML, etc.)

(source_table)

For table, XML root element, Microsoft Excel Worksheet Name, etc., to import/export data to/from

String, non-validated

Excel: Sheet1

XML: Export: Record, Import: Records/Record

JSON: Export: records.record, Import: $.records[#].record

DB: dbo.my_table

Delimiter

(delimiter)

Delimiter character found in the source or output text file.  Typically comma, tilde, pipe or fixed length. Can be overridden by "overrideDelimiter" parameter.

Enumeration list

 COMMA

Text Qualifier

(text_qualifier)

Used to wrap string data elements in a delimited text file (CSV) for example. Can be overridden by "overrideTextQualifier" parameter.

Enumeration List

 Double Quote

Skip First Line?

(skip_first_row)

Interpreted as a number, skip N lines, where N is the number entered.

Integer

 1

Connection String

(conn_string)

Defines the connection parameters (path, jdbc, ldap, etc.) to the foreign data system for the selected connector type.

Note that for Files a URL is also supported on import if the URL is supported by URL (Java Platform SE 7 ) for the version that Java Web Central runs under, except for ftp, ftps, sftp, file and kafka which are supported specially as documented.

String

FTP: filename.txt

Text: c:\feeds\filename.txt

Excel: c:\feeds\filename.xls

XML: c:\feeds\filename.xml

JSON: c:\feeds\filename.json

DB: jdbc:sybase:Tds:localhost:2638

LDAP: LDAP://server:389/dc=domain,dc=company,dc=com

Connection Username

(conn_user)

The username required to connect to the data source defined in the Connection String.

String

 my_user

Connection Password

(conn_password)

The password required to connect to the data source defined in the Connection String.

NOTE: Password is encrypted by the server when the form is saved.  The password is stored on the database in an encrypted format. It

String

 *********

Restriction Clause

(where_clause)

Holds ‘WHERE’ keyword for database connectors – applies to import or export.  Do not include the "WHERE" keyword in the restriction clause.

Memo

DB: bl_id = 'HQ' AND fl_id='17'

LDAP: userPrincipalName=*smith*

Pre Process

(pre_process)

The method must have the qualifiers “public static void” and accept a single parameter.

The parameter should be a String which will be the connection string, or if the useConfigInPreProcess connector parameter is set to true, the method parameter should be a ConnectorConfig object.

Any method called this way must be annotated with @com.archibus.app.common.connectors.impl.method.ConnectorProcess

String: “Class|Method”

 com.example.MyClass|myMethod

Post Process

(post_process)

The method must have the qualifiers “public static void” and accept a single parameter.

The parameter should be a String which will be the connection string, or if the useConfigInPostProcess connector parameter is set to true, the method parameter should be a ConnectorConfig object.

Any method called this way must be annotated with @com.archibus.app.common.connectors.impl.method.ConnectorProcess

String: “Class|Method”

 com.example.MyClass|myMethod

Assigned Connector

(assigned_connector)

Not implemented in this release.

N/A

 N/A

Notifications

(notify_user)

Determines whether and when email notifications are sent as Connectors execute.  Valid options are None (never email), Errors Only (only email when a Connector completes with errors), Connector Execution (every execution), or Both (errors and at completion).

Enumeration List

 Errors Only

Notification Email Address

(notify_email_address)

List of email addresses to send messages to on Error and/or Completion.

String - comma separated list of email addresses

 myuser@example.com,youruser@example.com

FTP Host

(ftp_string)

Defines the connection parameters to a remote FTP site where the Connector should copy the remote file to/from depending on the type of Connector.  The Connector will load the File to/from the location in the Connection String property before/after the Connector runs.

String FTP Host address/url

 ftp.example.com

FTP Remote Folder

(ftp_folder)

Specify the folder - relative to the root location of the Host address - to where files should be accessed. If there is a folder delimiter it must be included at the end of this path.

String

 cafm

Secure FTP

(ftp_secure)

Select whether or not SFTP (SSH) protocol is used to connect and transmit files.

Yes/No

 Yes

FTP Port

(ftp_port)

Enter the network port number to which the FTP connection should be made.

Integer

 21

FTP Username

(ftp_user)

Enter the username that should be used to connect to the FTP Host

String

 myftpuser

FTP Password

(ftp_password)

Enter the password that should be used to connect to the FTP Host.

NOTE: Password is encrypted when the form is saved.  The password is stored on the database in an encrypted format.

String

 *********

Execute Flag

(exec_flag)

Status flag, set to ‘EXECUTE’ to have the connector executed.  Some systems control scheduled jobs via an external scheduler—configure the scheduler to set this flag to have connector run at prescribed interval.

Enumeration List: READY, EXECUTE, RUNNING

 READY

Listener?

(is_listener)

A background process can be defined to run a connector periodically. This is useful for running a connector continuously in the background to process incoming requests or make poll-and-wait style requests. If set to No, the background process will not start.

See Listeners.

 Yes/No No

General Connector Properties

Property Name Description Value Example

compareFields

This defaults to false. When set to true, on import each field's value will be compared to the value in the Archibus database. If the value hasn't changed, it shouldn't be updated. If no value has changed, the transaction will not be applied.

Boolean

 {compareFields: true}
foreignPKey This defaults to the primary key of the table being imported into. The array is a list of fields to use as an alternate key when correlating imported records with Archibus records. JSON array {foreignPKey:[uuid]}

supportInserts

This defaults to true. When set to false, on import the connector should not insert new records into the Archibus database. (does not prevent update)

Boolean

 {supportInserts: false}

supportUpdates

This defaults to true. When set to false, on import the connector should not update existing records in the Archibus database. (does not prevent insert)

Boolean

 {supportUpdates: false}
useConfigInPreProcess This defaults to false. When set to true, a ConnectorConfig object representing the connector configuration will be provided to the pre-process method. Boolean {useConfigInPreProcess: false}
useConfigInPostProcess This defaults to false. When set to true, a ConnectorConfig object representing the connector configuration will be provided to the post-process method. Boolean {useConfigInPostProcess: false}
useAxvwDataSouce

If specified exports from the data source identified by dataSourceName in the AXVW file indicated by viewFileName.

Object {useAxvwDataSource:
{ viewFileName:ab-out-smsbuilder-inspection.axvw,
dataSourceName:outSmsBuilderInspectionDs }
viewFileName An AXVW file with a data source to use for exporting data. String See useAxvwDataSource
dataSourceName The data source id in viewFileName. String See useAxvwDataSource
sendExceptionDetailInEmail When a connector fails, a Java exception is logged. If this is set to true, the exception and part of the stack trace will be included in emails to the Notification Email Address. Defaults to false for security reasons. Boolean {sendExceptionDetailInEmail:true}

Actions

Security Recommendations

Any secure system can be overcome with improper configuration, and even with properly configured systems it is better to implement defense-in-depth. Connectors allow for remote systems to affect Web Central and vise versa, and these interactions require consideration for security.

Connector configuration and execution should be and are by default restricted to system administrators. The below is not an exhaustive list. Consider all applicable policies and the best judgment of a security expert.