Process-Centric Integrations

Introduction

Process-centric integrations refer to the various events and smart services that can be used to integration with another systems. This article covers those activities and relevant details about connecting it to a third party service.

  • To learn about integration objects and their configuration options, see Integration Objects.
  • To learn about setting up integrations for expressions, see the Expresison-Centric Integrations page for a list of the connector functions and the syntax for using them.

Integration Activities

The following events and smart services support integration in some way.

Activitiy Type Protocols Supported
Call Integration Connectivity Services HTTP
Call Web Service Connectivity Services SOAP
HTTP File Download Connectivity Services HTTP
HTTP File Upload Connectivity Services HTTP
Invoke SAP BAPI Connectivity Services HTTP
Start and Receive Message Event Event JMS/SMTP

Activity Details

Each node or smart service has unique capabilities and considerations when using it. Read the following sections to learn more about each activity.

Call Integration Smart Service

The call integration service smart service lets designers connect integrations to a process using an simple setup operation.

Pre-existing integrations can be called into the smart service, and will generate the necessary activity class parameters needed to use and capture data from the integration.

Conversely, integrations can be created by this smart service using existing node inputs.

Integrations that modify data in other systems require this smart service to execute.

Authentication concerns for the call integration smart service follow the authentication settings defined in the integration.

Call Web Service Smart Service

The call web service smart service lets designers connect WSDLs to process models. This smart service has the added benefit of creating a CDT to map to an incoming SOAP message.

Data transferred using web services are only encrypted when the web service is running over HTTPS. Appian recommends all sensitive or confidential data be encrypted. Application-level security is the responsibility of each customer.

The call web service node supports TransportBinding policy assertions that require HTTPS, requiring a client certificate or specific authentication schemes listed below. Web service security settings must allow username, password, and/or domain authentication.

Authentication

Web service providers that support basic auth, digest, NTLM, or WS-Security UsernameToken 1.1 or 1.0 authentication are supported. For UsernameToken authentication, username-only, username and plaintext password, and username and password digest are supported.

Transport layer authentication mechanisms (basic auth, digest, NTLM, client certificate) may be declared by the WSDL using TransportBinding WS-Policy assertions, however such a declaration is not required. Any WS-Policy assertions for these transport layer authentication mechanisms that are not declared as TransportBinding WS-Policy assertions are not supported.

In order to use WS-Security UsernameToken, it must be declared in the WSDL as a WS-Policy assertion. If the WSDL contains multiple policy alternatives in an ExactlyOne element, the first alternative supported by Appian will be selected.

  • SAML, LDAP, x509, UsernameToken derived key, SignedSupportingTokens, or other authentication schemes are not supported within the context of this smart service, but it may be possible to integrate with these systems using smart service plug-ins.
  • Client certificate/mutual SSL authentication can be enabled by uploading client certificates in the Admin Console.
  • Services that use self-signed or internal SSL certificates can be enabled by uploading trusted certificates in the Admin Console
Providing Credentials for UsernameToken Authentication

If the WSDL for the web service declares that UsernameToken is supported for authentication, a "WSDL Policy" section will be revealed on the setup tab. Credentials can be provided in one of two ways:

Using the "Custom Username Token" inputs to provide literal values or expressions for the Username and Password inputs. By checking the "Use Predefined Credentials" checkbox and then selecting the external system from the dropdown. The credentials registered to that external system in the Secure Credentials Store will be used at runtime. The attributes configured in the Secure Credentials Store for the username and password must be named username and password respectively in order for them to be detected and used by the Call Web Service smart service for UsernameToken credentials. A radio button toggle is provided to allow selection between the site-wide credentials for the external system, or the per-user credentials of the assignee that executes the smart service. If the credentials of the assignee are selected, the node must be attended or will pause by exception during execution.

Unsupported XSD & Web Services

WSDLs that utilize data types with the following XSD constructs result in CDTs that ignore the construct:

  • Enumerations
  • Simple Types with Attributes
  • Occurrence constraint lists (which are simplified to multiple or single values)

The following types of web service cannot be called using this smart service:

  • RESTful APIs without WSDL files are not supported (RESTful APIs with WSDLs that use HTTP binding are supported).
  • Attachments
  • RPC/Encoded services
  • WSDLs that utilize data types containing the following XSD constructs return an error if you attempt to to configure specific operations that use them.
    • xsd:union
    • Choice Groups
    • Substitution Groups
    • Mixed Content
  • Notification or Solicit-Response message exchange pattern operations.
  • WS-Policy elements that are not marked as optional or related to supported TransportBinding or UsernameToken policies.
  • WS-Policy ExactlyOne elements that contain any unsupported policy assertions. You can work around this by editing the WSDL to remove any unsupported elements and rehosting it.

For more information about specific XSD elements and whether or not they are supported, see the Supported XSD and JPA Annotations page.

HTTP File Download Smart Service

The HTTP file download smart service allows you to make a HTTP request to another system and store the result in Appian's document management system

This node does not pause by exception if an HTTP error occurs. You can use the Error Occurred and Error Info outputs to determine how the process handles the error, such as incorporating an escalation into a later part of the process design. This node does not automatically retry failed requests.

Authentication

HTTP file download uses a Secure Credential Store to authenticate with another system. The key values of the secure credential store is passed into the Basic Authentication node input of the smart service using the a!httpAuthenticationBasic() function.

HTTP File Upload Smart Service

The HTTP file upload smart service allows you to upload an Appian document to an external system over HTTP

This node does not pause by exception if an HTTP error occurs. You can use the Error Occurred and Error Info outputs to determine how the process handles the error, such as incorporating an escalation into a later part of the process design. This node does not automatically retry failed requests.

Authentication

HTTP file upload uses a Secure Credential Store to authenticate with another system. The key values of the secure credential store is passed into the Basic Authentication node input of the smart service using the a!httpAuthenticationBasic() function.

Invoke SAP BAPI Smart Service

The Invoke SAP BAPI Smart Service allows designers to safely invoke BAPIs with side effects in process.

The two main benefits of using this smart service are:

  1. The ability to make unattended write calls to SAP.
  2. The ability to process return values from the BAPI. Return values allow you to verify that the invocation was successful.

Authentication

Authentication for the Invoke SAP BAPI Smart Service relies on the Secure Credential Store, which is passed in as a node input.

Start and Receive Message Event

A start event can be configured with a receive message trigger to kick off a process via an incoming integration. Similarly, receive message events can be configured to handle incoming integrations after a process has been kicked off. Messages can come into the process either through a JMS bus or E-mail via Secure Message Transfer Protocol (SMTP).

JMS

JMS authentication is configured during installation setup. If JMS is properly setup, no further authentication steps are needed by the Designer. This is not an Appian username/password. Rather it is specific to the JMS provider in the application sever. For more information, see Working with the Java Messaging Service

SMTP

In order to send or receive e-mails in Appian, a mail server must be set up. This is done by the system administrator.

The Anonymous user account must be enabled to allow the receipt of email messages to start a process.

Properties

Both type of events are configured with a setup and data tab in the event properties.

JMS

The receive message event or receive trigger on a start event can obtain the following properties from an external JMS message

Select To obtain the …
Origin IP IP address of the machine from which the message was received
UserName username of the user who sent the JMS message
'msg!properties'.'' This returns the value of the JMS property with the name given as PROPERTY_NAME. Only properties that start with numbers or letters are considered valid. Invalid properties are not available.
SMTP

Data from E-mails can be obtained similar to how JMS properties are obtained. Please see the e-mail properties section of the receive message event for a full list of available properties through e-mail.

Other Notes

  • Unlike start events with a receive message trigger, intermediate receive message events only listen for messages when they are activated.
    • When messages are targeted at an active receive message event, the event only executes if all conditions configured for the event are met. Otherwise, the event does not execute and the message is lost.
  • A Start Event can use a Receive Message trigger to start a process. If you add multiple active Receive Message events, it is possible for one message to launch multiple instances of a process. Avoid this problem by creating a Receive Message condition.
  • Messages sent to a process that is paused are lost and are not available for consumption when the process resumes.
FEEDBACK