Connector Functions allow designers 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 Appian Administration 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 designers should use that constant for the value of the scsExternalSystemKey parameter.
System-Wide vs. Per-User Authentication
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 Appian Administration 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:
true if the read was successful, otherwise falseShould 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 designers 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, designers 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.
a!cmiCopyDocumentFromAppian - Copies an Appian document to a location in the CMIS target system, specified by the value of the objectId parameter.
a!cmiCopyDocumentToAppian - Copies a document from the CMIS target system to Appian, creating a new version of an existing Appian document.
a!cmiCopyDocumentToAppianFolder - Copies a document from the CMIS target system to an Appian folder, creating a new document.
a!cmiCreateFolder - Creates a folder in the CMIS target system.
a!cmiDelete - Deletes an object in the CMIS target system.
a!cmiGetFolderChildren - Retrieves the children of the folder given as the folderId parameter, obeying the given pagingInfo.
a!cmiGetObjectIdByPath - Retrieves the object id of a CMIS object based on the value given as the path parameter.
a!cmiGetProperties - Retrieves the properties of the CMIS object given as the objectId parameter.
a!cmiGetRepoInfo - Retrieves information about the target CMIS target system repository.
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.
Authentication and Permissions
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.
Scalability
A folder on the CMIS target system may have many sub-folders 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.
a!dynAssociate - Associates one object in Dynamics with another, using the given relationship type.
a!dynCreate - Creates a new business object in Dynamics.
a!dynDelete - Deletes a business object from Dynamics.
a!dynDisassociate - Deletes a link between business objects from Dynamics.
a!dynRetrieve - Retrieves the data for a given entity from Dynamics.
a!dynRetrieveMultiple - Retrieves a collection of entities from Dynamics that match the given query.
a!dynUpdate - Updates a business object in Dynamics.
The Dynamics connector allows integration with Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online. The connector uses the IOrganizationService web service to read from and write to the Microsoft Dynamics target system.
Authentication and Permissions
The Dynamics connector functions expect two credentials fields when retrieving credentials from the secure credentials store:
Scalability
When reading from Dynamics using the a!dynRetrieveMultiple function, use the paging capabilities of FetchXML to limit the number of results returned from Dynamics. Limit the columns that are returned by constructing the FetchXML query to return only the fields that you require. See FetchXML paging documentation for details.
a!sfcDelete - Removes a business object from Salesforce.
a!sfcDescribeGlobal - Provides introspection into the objects available in the target Salesforce instance.
a!sfcDescribeSObjects - Provides introspection into the metadata of the given Salesforce objects.
a!sfcInsert - Adds a new business object to Salesforce.
a!sfcQuery - Allows querying a Salesforce instance using the Salesforce Object Query Language.
a!sfcSearch - Allows searching a Salesforce instance using the Salesforce Object Search Language.
a!sfcUpdate - Updates data for an existing business object in Salesforce.
The Salesforce connector supports the SOAP-based Partner WSDL API version 27 and 28.
The functions that query and search Salesforce use the SOQL and SOSL Salesforce syntax, respectively. Refer to the Salesforce reference documentation for details on that syntax.
Salesforce has standard endpoint URLs that are used for authentication and selection of the version of the API to access. See Salesforce documentation for more details on the endpoint URL.
Some JVMs may not trust the certificate authority, VeriSign, which used by the Salesforce web API endpoint. If you encounter errors related to the certificate when attempting to use the Salesforce connector, add the certificate authority's root certifcate to the JVM's trust store.
Authentication and Permissions
The Salesforce connector functions expect two credentials fields when retrieving credentials from the secure credentials store:
The user that is connecting must have the "API Enabled" permission set in Salesforce. This permission is selected by default. The user permissions (Read, Create, Edit, Delete) for the authenticated user will apply to the invocation of the Salesforce API through these connector functions. Refer to Salesforce documentation for more information on data access.
Scalability
When reading data from Salesforce, use the WHERE, LIMIT and ORDER BY SOQL keywords to do processing of results on the Salesforce server instead of retrieving a large list of items and filtering or sorting within Appian.
a!sapBapiParameters - Retrieves the list of parameters required to call the given SAP BAPI.
a!sapInvoke - Invokes the given BAPI, returning the result.
a!sapInvokeWithCommit - The Invoke SAP BAPI Smart Service allows designers to safely invoke BAPIs with side effects in process.
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 http://service.sap.com/connectors. A restart is not required when following these instructions.
For Linux
/usr/local/appian<APPIAN_HOME>.META-INF/lib under temporary directory, change into ~/tmp
mkdir -p ~/tmp/META-INF/libcd ~/tmp<APPIAN_HOME>/deployment/web.war/WEB-INFappian-bundled-plugins.zip to ~/tmp (the current directory)
cp <APPIAN_HOME>/deployment/web.war/WEB-INF/appian-bundled-plugins.zip .appian-integration-sap*.jar from appian-bundled-plugins.zip into the temporary directory
unzip appian-bundled-plugins.zip "appian-integration-sap*.jar"sapjco3.jar and move into ~/tmp/META-INF/libMETA-INF folder to appian-integration-sap*.jar.
jar -uvf appian-integration-sap*.jar META-INFlibsapjco3.so) and put into ~/tmp_admin/plugins
cp libsapjco3.so <APPIAN_HOME>/_admin/pluginsappian-integration-sap*.jar into _admin/plugins
cp appian-integration-sap*.jar <APPIAN_HOME>/_admin/pluginsFor Windows
C:\appian\<APPIAN_HOME>.META-INF\lib under temporary directory, change into the temporary directory
mkdir C:\tmp\META-INF\libcd C:\tmpappian-bundled-plugins.zip
<APPIAN_HOME>\deployment\web.war\WEB-INFappian-bundled-plugins.zip to C:\tmp (the current directory)
copy <APPIAN_HOME>\deployment\web.war\WEB-INF\appian-bundled-plugins.zip .appian-integration-sap*.jar from appian-bundled-plugins.zip into the temporary directorysapjco3.jar and move into C:\tmp\META-INF\libMETA-INF folder to appian-integration-sap*.jar.
jar -uvf appian-integration-sap*.jar META-INFsapjco3.dll) and put into C:\tmpcopy sapjco3.dll <APPIAN_HOME>\_admin\pluginsappian-integration-sap*.jar into _admin\plugins
copy appian-integration-sap*.jar <APPIAN_HOME>\_admin\pluginsNote: For Windows, the Visual Studio 2005 C/C++ runtime libraries (8.0.50727.4053) must be installed on the system.
Authentication and Permissions
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
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.
a!sblCreate - Creates a new record in Siebel.
a!sblDelete - Deletes a record from Siebel.
a!sblInvoke - Invokes the method in Siebel, returning the result.
a!sblInvokeWriter - Invokes the method that will result in a modification to data in Siebel.
a!sblQuery - Retrieves records from Siebel.
a!sblUpdateFieldValue - Updates the values of the given record in Siebel.
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.
Authentication and Permissions
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.
Scalability
Design queries using the a!sblQuery function to return only the data fields required.
a!shpCopyDocumentFromAppian - Copies an Appian document to a location in SharePoint, specified by the value of the path parameter.
a!shpCopyDocumentToAppian - Copies a SharePoint document, specified by the value of the path parameter, to a folder within Appian.
a!shpInvoke - Invokes the SharePoint 2013 REST endpoint, retrieving the data based on the given path parameter.
a!shpInvokeWriter - Invokes the SharePoint 2013 REST endpoint based on the given path parameter for the purpose of writing data to SharePoint.
The SharePoint connector supports connecting to SharePoint 2013 using SharePoint's REST API. The API uses the OData web protocol standard for communication, and the connector functions adhere to the OData protocol URI conventions when passed as the value of the path parameter. The data is retrieved and converted into an Appian dictionary format for easy use in expressions.
For information on SharePoint's REST API, refer to the SharePoint 2013 REST service documentation and the REST API Reference for SharePoint 2013.
Authentication and Permissions
The SharePoint connector supports forms-based authentication using SharePoint's classic mode authentication. It supports HTTP Basic, Digest, and NTLM authentication schemes. It does not support other authentication types such as OAuth at this time.
The SharePoint connector functions expect three credentials fields when retrieving credentials from the secure credentials store:
See also: SharePoint Authentication
Scalability
Because the SharePoint connector uses the OData protocol, it supports OData operators in the path parameter that can be used to limit the data that is returned and improve performance. Use the following operators to build queries that return just the data that you need:
$select - to select just the fields you require$filter - to select just items that meet specific criteria$orderby - to sort the items on the SharePoint server instead of once the items are returned to Appian$top and $skip - to enable paging of data, reducing the set that is returned to AppianSee also: OData Query Operations in SharePoint REST Requests
a!httpAuthenticationBasic - Creates an object that contains the information required to perform HTTP Basic authentication.
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.
