Call an Integration

Introduction

This article explains how to call integration objects from your application.

• To learn about integration objects and their configuration options, see Integration Objects.
• To learn how to use the integration designer to configure, test, and troubleshoot integrations, see Create an Integration.
• For a real-world example of how to build and use connected systems and integrations, see the Integration Tutorial.

Querying Data versus Modifying Data

Consider the following integrations involving an external payment gateway:

1. Retrieve a list of credit card transactions
2. Process a new credit card transaction

The first integration queries data, but doesn't make any changes. You could call this integration multiple times without any impact on the data in the external system.

The second integration does make a change: it processes the credit card transaction (this is also known as having side-effects). Inadvertently calling this integration more than once would cause a big problem: the customer would be charged twice for the same purchase!

Whether an integration queries data or modifies data determines where it can be called in Appian:

Call an Integration to Query Data

Integrations that query data are called like expression rules using the rule! domain and can be used in any expression (interface, process model, expression rule, record type, web API).

When calling an integration, values or variables can be passed to the rule inputs by position or by keyword.

Integrations that query data return a dictionary with the following fields:

1
2
3
4
5
6
7
8
9
10
a!localVariables(
  /* Call the integration to query the external system */
  local!externalQuery: rule!GetUnsettledTransactionList(),
  
  /* Handle the response depending on the outcome */
  local!value: if(local!externalQuery.success,
    local!externalQuery.result,
    local!externalQuery.error
  )
)

For a complete example, see the Integration Tutorial.

Call an Integration to Modify Data in an interface component or Web API

Integrations that modify data are called like smart service functions using the rule! domain and can only be used in the saveInto parameter of a component or in a Web API. This protects against duplicate updates in the external system.

When calling an integration, values or variables can be passed to the rule inputs by position or by keyword.

Integrations configured to modify data have two additional inputs:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
a!buttonWidget(
  label: "Place Your Order",

  /* Call the integration to update the external system when the button is pressed */
  saveInto: rule!AuthorizeCreditCardPayment(
    cardNumber: local!cardNumber,
    expirationDate: local!expirationDate,
    ccv: local!ccv,
    amount: local!amount,
    onSuccess: {
      /* Handle the successful response */ 
      a!save(local!result, fv!result)
    },
    onError: {
      /* Handle the error response */ 
      a!save(local!paymentErrorMessage, fv!error.message)
    }
  )
)

For a complete example, see the Integration Tutorial.

Call an Integration in a Process Model

Regardless of whether it queries or modifies data, an integration can be called in a process model using the Call Integration Smart Service. This is particularly important for integrations that modify data since they cannot be called in expressions elsewhere in a model. It can also be useful when querying data because the Call Integration node can show a custom icon to visually indicate the system or service being called.

When calling an integration, the rule inputs are displayed in the Node Inputs tab where they can be populated from process variables or expressions. The integration outputs are displayed on the Node Outputs tab where they can be saved to process variables or used in custom output expressions.

For more information, see the Call Integration Smart Service page.

Feedback