Integrating using Web Services

Appian can use Web Services to integrate with external systems as a service provider (other systems calling Appian) or as a client (calling other systems from Appian). Most common protocols and standards are supported by default, but you can extend the platform using Appian's plug-in framework.

• The recommended approach for Appian to access other systems is through use of the Integration Object.
• The recommended approach for other systems to access Appian is through the Web API Object.

Calling Other Systems from Appian

Anytime Appian calls another system using supported authentication and methods, it should be configured using an Integration Object, paired with a Connected System. The Connected System object allows for multiple Integrations to be configured with one system, while hosting the authentication configuration in one place.

Querying vs. Modifying Data

• Developers should always be aware of whether the integration will be querying (read-only) or modifying (read/write) data and select the appropriate checkbox for Usage when configuring an Integration object.
  • Note: Appian will restrict developers from placing Integrations that modify data in places where duplicate calls can occur.
• Unlike other Web Service smart services, Integration objects can be called in SAIL or in process.
• Queries via an Integration object can also be used as the source for a service-backed record to create a structured, navigable interface for that data in Appian.

Working with JSON

• When building the request body of an Integration object as JSON, you should create CDTs or use dictionary syntax that matches the expected structure to structure the data, and then use the function a!toJson to format the body. This will account for special characters and nulls, and always produce a well-formed structure.
• When parsing the response body of an Integration that is expected to be JSON, you should use Automatic Output Parsing (“Convert the JSON Response body to an Appian value”). This will always return your result as structured data in Appian.
  • Note: If there are any Date or Date and Time fields expected in the response body, you will need to manually convert these fields from a Text type (e.g. "2018-01-01T12:00:00Z") to a Date or Date and Time type by parsing the string.

Working with XML

• When building the request body of an Integration object as XML, you should create CDTs or use dictionary syntax that matches the expected structure to structure the data, and then use the function fn!toxml to format the body. This will account for special characters and nulls, and always produce a well-formed structure.
• When parsing the response body of an Integration that is expected to be XML, you should use the option to “Return the raw response body” and then use the function fn!torecord to convert the XML string into the structure of a matching CDT.
  • Note: The namespace of the CDT must match the namespace of the XML. If you have the WSDL URL for the XML, you can automatically create CDTs which match the XML structure in your environment by adding it to the Call Web Service Smart Service, and then saving and publishing the process model.

Unsupported Methods or Authentication Configurations

For SOAP-based Web Services that use unsupported or non-standard data structures follow the advice in the Advanced SOAP Web Service Configuration guide.

For Web Services using unsupported authentication methods you may be able to utilize the Advanced Call Web Service or Send HTTP Request plug-ins. If these do not work for your use case you can always write custom function plug-ins to perform the call.

Calling Appian from Other Systems

Other systems can use Web Services to call an Appian Web API to expose Appian expressions such as query data, modify data, or start a process. See the Best Practices for configuring an Appian Web API guide for more information.