The capabilities described on this page are included in Appian's standard capability tier. Usage limits may apply. |
Connector Functions allow developers to build integrations between Appian and other popular enterprise software platforms. The connectors are available as functions that are intended to be used with interface expressions to build rich record lists and dashboards to present a unified view of data from disparate systems.
See Connector Functions for a list of the connector functions and the syntax for using them.
Connectors require some additional setup before they can be used. All connectors require credentials to access the target system. Some connectors also require settings to be enabled on the target system or additional libraries to be deployed on the Appian application server(s).
In order to authenticate with the target system, the connectors retrieve credentials from the secure credentials store.
A system administrator user must set up credentials in the secure credentials store. See the Admin Console documentation for details on setting up sets of credentials. Most connectors require two credentials fields named "Username" and "Password." See each connector's Authentication section for details on the credentials fields that need to be present.
The credentials that the connectors use for authentication are identified based on the scsExternalSystemKey
parameter present in each connector function. Each function also takes a usePerUserCredentials
parameter, which determines whether the values of system-wide credentials should be used when authenticating with the target system (false
) or whether the individual credentials set by the current user should be used (true
). As a best practice, the system administrator should create a constant of type Text with the value set to the identifier key and developers should use that constant for the value of the scsExternalSystemKey
parameter.
As described above, the designer can choose to use the connector function with per-user or system-wide credentials. To make the choice that is right for the integration, determine whether Appian should appear as a single "integration user" when connecting to the external system, or whether it should appear to the external system that each individual user is connecting.
System-wide credentials are set in the Third-Party Credentials page of the Admin Console. Per-user credentials are set by individual users in the Third-Party Credentials settings page.
Some reasons to choose system-wide credentials:
Some reasons to choose per-user credentials:
The connectors provide functions for reading data from the target system. The functions request the data in accordance with the target system's API and return the data in the same format as returned by the target system, but transformed into an Appian dictionary. All functions that read have a common return type, which wraps the data returned from the target system while providing some additional error handling capabilities.
The connector functions that read from the target system all return the same Dictionary data structure, which contains a field that indicates whether the read was successful and fields that contain the result or error.
1
2
3
4
Return Structure
- success (Boolean)
- result (Any Type)
- error (Any Type)
If successful, the result
field will have a value and the error
field will be empty. If a failure occurs, the error
field will be populated and the result
field will be empty. The fields are as follows:
Field | Type | Description |
---|---|---|
success |
Boolean |
|
result |
Any Type |
A dictionary data structure containing the fields and data returned by the target system; specific results are described with each function below. |
error |
Any Type |
A dictionary structure containing additional information about the error that occurred. The fields are:
|
Should an error occur while retrieving data from the target system, the connector function will still return a value instead of throwing an exception that would cause the entire expression to fail to evaluate. This allows developers to gracefully handle connectivity, authentication, or other errors in a way that can still allow the user interface to render at least partial information. When the error occurs, the success
field of the return value will be set to false
. The error
field will have addition information about the error that occurred.
In order to provide the optimal user experience, developers should design the interface that is using the connector function to inspect the success
field and either display an error message in place of the content that would have been retrieved from the target system, or hide the problematic section altogether.
A common error will be an authentication failure, especially when using per-user credentials. A user that has not yet entered their credentials on the Third-Party Credentials settings page will trigger such an error when visiting a record dashboard that uses a connector to that system. By checking for an error, the designer can provide a helpful message to the user to check their credentials rather than causing the entire record dashboard to fail.
The examples in the Connector Functions documentation demonstrates using this return format for error handling.
See also: Connector Functions
Connector functions that modify data on the target system are implemented as Writers. Writers can only be used on interfaces and must be used in conjunction with the bind()
function. Connector functions that write data (create, update, delete, etc.) can be used to modify data in an external system directly from a dashboard or form. The write occurs after all local variables have been saved into. Writers do not return a response.
Connector functions are transactional within themselves, but there are no transaction boundaries that include other connector functions that may be writing data as part of the same re-evaluation. An update to one system may succeed even though an update to another system may fail. For example, if a record dashboard is designed such that an Account is updated in Salesforce, and a document is copied to SharePoint when a user clicks a button, it is possible for the Account update to Salesforce to fail and the document transfer to SharePoint to still succeed.
See also:
If an error occurs when a connector function writes data to an external system, the error will manifest as an expression failure error message in a dialog on the user interface. Connector functions that write data do not return a response, so there is no mechanism to capture the error response and modify the user interface to hide a section or show a custom error message like there is for connector functions that read data.
When designing records that use the connector functions, it may be useful to see additional information about what is being requested of the external system and what that system is returning in response. To have this information printed to the application server log file in the <APPIAN_HOME>/logs
directory, uncomment the following line in appian_log4j.properties
:
1
log4j.logger.com.appian.integration=DEBUG
Note that this configuration should be commented out or set to ERROR
level in production environments, except for when troubleshooting as the logging can have a negative impact on performance.
The CMIS connector supports integrating with systems that implement the OASIS Content Management Interoperability Services standard. The system must adhere to the CMIS 1.0 specification and expose the RESTful AtomPub binding. The CMIS connector does not support the Web Services (WSDL) binding.
The CMIS connector functions expect two credentials fields when retrieving credentials from the secure credentials store:
The target system must support HTTP basic authentication.
The user used to connect to the CMIS system can have cmis:read
, cmis:write
, or cmis:all
permission to the objects in the repository. Their allowable actions will be limited to the permission they are granted in the CMIS target system.
A folder on the CMIS target system may have many subfolders and files. The amount of data retrieved from the CMIS target system must be controlled using the pagingInfo parameter a!cmiGetFolderChildren
function.
While there is no strict limit to the size of documents that can be copied to or from the target CMIS system, be aware that the transfer of a very large file will have an impact on the user experience.
The SAP connector uses the SAP JCo 3.0 middleware library to connect to a SAP ERP systems release 3.1H or later. The connector allows Remote Function Call (RFC) communication with the SAP ABAP runtime, invoking functionality exposed as Business Application Programming Interfaces (BAPIs).
In order to use the SAP connector, the SAP JCo native library, which is not shipped with Appian, must be installed on all of the application servers running Appian. Download the SAP Jco from https://service.sap.com/connectors. A restart is not required when following these instructions.
/usr/local/appian
<APPIAN_HOME>
.sapjco3.jar
and move into ~/tmp
sapjco3.jar
into _admin/plugins
cp ~/tmp/sapjco3.jar <APPIAN_HOME>/_admin/plugins
libsapjco3.so
) and put into ~/tmp
_admin/plugins
cp ~/tmp/libsapjco3.so <APPIAN_HOME>/_admin/plugins
<APPIAN_HOME>/ae/tomcat/apache-tomcat/bin/setenv.sh
and append the following
1
2
3
4
5
6
if [ ! -z "$CLASSPATH" ] ; then
CLASSPATH="$CLASSPATH":"${AE_HOME}/_admin/plugins/sapjco3.jar:${AE_HOME}/_admin/plugins/libsapjco3.so"
else
CLASSPATH="${AE_HOME}/_admin/plugins/sapjco3.jar:${AE_HOME}/_admin/plugins/libsapjco3.so"
fi
export CLASSPATH
<APPIAN_HOME>/ae/conf/custom.properties
and append the following
1
conf.plugins.internal.EXTRA_BOOT_DELEGATION_PKGS=com.sap.*
C:\appian\
<APPIAN_HOME>
.sapjco3.jar
and move into C:\tmp
sapjco3.jar
into _admin\plugins
copy C:\tmp\sapjco3.jar <APPIAN_HOME>\_admin\plugins
sapjco3.dll
) and put into C:\tmp
_admin\plugins
copy C:\tmp\sapjco3.dll <APPIAN_HOME>\_admin\plugins
<APPIAN_HOME>\ae\tomcat\apache-tomcat\bin\setenv.bat
and append the following
1
2
3
4
5
if not "%CLASSPATH%" == "" (
set CLASSPATH=%CLASSPATH%;%AE_HOME%\_admin\plugins\sapjco3.jar;%AE_HOME%\_admin\plugins\sapjco3.dll
) else (
set CLASSPATH=%AE_HOME%\_admin\plugins\sapjco3.jar;%AE_HOME%\_admin\plugins\sapjco3.dll
)
<APPIAN_HOME>\ae\conf\custom.properties
and append the following
1
conf.plugins.internal.EXTRA_BOOT_DELEGATION_PKGS=com.sap.*
Note: For Windows, the Visual Studio C/C++ runtime libraries must be installed on the system. Please refer to the SAP Java Connector SDK release notes to determine what version to install as well as the latest Microsoft security patch required.
The SAP connector functions expect two credentials fields when retrieving credentials from the secure credentials store:
The user that is connecting must have the proper permissions set in SAP to invoke the BAPI.
Scalability considerations depend on the BAPI being invoked. Choose BAPIs that allow for specifying the number of items returned and the subset of data fields that should be returned.
The Siebel connector allows connecting to an Oracle Siebel 8.x. The connector functions allow for reading and writing data to Siebel Business Components and Business Objects. The connector also allows the invocation of arbitrary methods exposed in Siebel Business Services.
The Siebel connector functions expect two credentials fields when retrieving credentials from the secure credentials store:
The user that is connecting must have the proper permissions on the Business Components and Business Objects to read and write, as well as the proper permission for invoking a Business Service method.
Design queries using the a!sblQuery
function to return only the data fields required.
a!httpAuthenticationBasic - Creates an object that contains the information required to perform HTTP Basic authentication.
a!httpFormPart - Creates an HTTP form part which can be passed in an integration’s multipart request body.
a!httpHeader - Creates an HTTP header object which can be passed to an HTTP function.
a!httpQueryParameter - Creates an HTTP query parameter object which can be passed to an HTTP function.
a!scsField - Creates an object which contains the information required to access data in the Secure Credentials Store.
a!wsConfig - Constructs the config parameter to the webservicequery()
and webservicewrite()
functions.
a!wsHttpCredentials - Constructs a WsHttpCredentials object for use with a!wsConfig
.
a!wsHttpHeaderField - Constructs a WsHttpHeaderField object for use with a!wsConfig
.
a!wsUsernameToken - Constructs a WsUsernameToken object for use with a!wsConfig
.
a!wsUsernameTokenScs - Constructs a WsUsernameTokenScs object for use with a!wsConfig
.
Connector Functions