Connected Systems

Introduction

This article provides details of the various types of connected systems. Each connected system is custom for the service it connects to, and it will tailor fit integrations that use this connected system with fields specific to that third party system.

Common Properties

Each connected system has the following properties:

Field Description
Name The name of the connected system. Use a name that will uniquely identify this connection to the external system.
Description Supplemental information about the connected system that is displayed when selecting the system in the integration designer and in the application contents grid.

OpenAPI

Designers can use OpenAPI documents to generate a connected system that can inherit base URLs, authentication details, and a list of operations. Then, using that connected system, the designer can create integrations for those operations. Appian will automatically generate an expression for the URL with rule inputs for any path parameters. It will also generate required headers and query parameters.

In addition to the common properties, an OpenAPI connected system has the following properties:

Field Description
System Logo An image document used to visually represent the external system or service being connected to. The logo is displayed in the integration designer and in the process modeler on integrations that connect to this system (using the Call Integration Smart Service). If no document is selected a default logo will be used instead.
OpenAPI/Swagger Document An OpenAPI documents (formerly known as a Swagger document) defines a standard interface to a RESTful API. They can be read by a human or computer to understand the capabilities of a web service without access to source code/documentation. By uploading these to your connected system, Appian can inherit base URLs, authentication details, and a list of operations.
Base URL A consistent prefix for the URLs of this connected system's integrations. This value supports environment specific configuration for variation across environments. This value can be selected from the list of base URLs that are inherited from the attached OpenAPI document.
Authentication The type of authentication that integrations leveraging this connected system will use. For authentication options, see Connected System Authentication.

Amazon Machine Learning

NOTE: Amazon ML is no longer available to new Amazon customers

Easily connect to Amazon Web Services Machine Learning models to make predictions based on your data. Pick from available models and quickly map your data to build smarter applications for fraud detection, demand forecasting, targeted marketing, and more.

See Amazon documentation on requesting real time predictions.

In addition to the common properties, an Amazon Machine Learning connected system has the following properties:

Field Description
Access Key Id Amazon uses a custom authentication schema that requires a special signing of the request using an access key, secret access key, and region. The access key id, along with an associated secret access key and region, are used to access Amazon services. Your access key id is the first piece of a set of programmatic credentials that can be generated for Amazon Identity and Access Management (IAM) user accounts.
Secret Access Key Your secret access key is the second piece of a set of programmatic credentials that can be generated for Amazon IAM user accounts.
Region Your region is the third piece of a set of programmatic credentials that can be generated for Amazon IAM user accounts.
TEST CONNECTION Uses the provided configuration information to connect to the target system. Returns success or error with details.

Operations

Name Description Type
Run a Prediction Run a prediction on an existing Amazon Machine Learning model READ

aml_integration.png

Blue Prism

Blue Prism Robotic Process Automation (RPA) Connected System provides an easy way to integrate software robots into your business process, and eliminate repetitive and error-prone tasks that people perform. Automatic discovery of the available Blue Prism processes and their data inputs makes it quick and easy to set up.

See Blue Prism documentation on exposing and calling web services.

In addition to the common properties, an Blue Prism connected system has the following properties:

Field Description
Username Blue Prism account used to execute the Blue Prism process or object
Password Blue Prism account used to execute the Blue Prism process or object
Host URL The Host URL for your Blue Prism instance
TEST CONNECTION Uses the provided configuration information to connect to the target system. Returns success or error with details. Host URL will be validated by testing the connection. Username and Password are per process and will be validated when executing a process or object

Operations

Name Description Type
Execute Blue Prism Process Calls a Blue Prism Process that was exposed as a web service WRITE
Execute Blue Prism Business Object Calls an action defined in a Blue Prism business object WRITE

Execute Blue Prism Process

Calls a Blue Prism Process that was exposed as a web service

Note: Execute Blue Prism Process is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

bp_integration_process.png

Execute Blue Prism Business Object

Calls an action defined in a Blue Prism business object

Note: Execute Blue Prism Business Object is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

bp_integration_business_object.png

DocuSign

Quickly and easily create, manage, and send eSignatures using the new DocuSign connected system. DocuSign envelopes can contain one or more documents, the fields in the document, recipient info, delivery progress, sender information, security and more.

Two forms of authentication are available for DocuSign: Basic Authentication (single system login) and Authorization Code Grant (per user).

Basic Authentication

Uses the DocuSign Legacy Header Authentication Method, which requires a single DocuSign user’s credentials to authenticate.

Please see DocuSign documentation for more details.

In addition to the common properties, a DocuSign Legacy Header has the following properties:

Field Description
Authentication Information The following authentication information can be found in the DocuSign Admin site. From your DocuSign instance, go to the Admin site. Then click Accounts and select your account to get started.
Instance URL Instance URL will be used for authorization. This URL is used to configure your integration object and when executing your operations. For Example: https://demo.docusign.net
API Account ID To find the API Account ID, from the Account screen, under Integrations click API and Keys.
API Username The username used to sign into the provided DocuSign instance. To find the API Username, from the account screen, under Users And Groups click Users. Then select a user.
Password The password used to sign into the provided DocuSign instance
Integration Key To find the Integration Key, from the account screen, under Integrations, select API and Keys. Then select your App Name.
TEST CONNECTION Uses the provided configuration information to connect to the target system. Returns success or error with details.

docusign-basic-authentication.png

Authorization Code Grant

Uses the DocuSign OAuth 2.0 Authentication Method, where each Appian user will be required to log in to their DocuSign account to authenticate. You must provide users a way to authenticate using OAuth 2.0.

Please see DocuSign documentation for more details.

In addition to the common properties, a DocuSign Authorization Code Grant has the following properties:

Field Description
Authentication Information The following authentication information can be found in the API and Keys page for your app. From your DocuSign instance, go to the Admin site. Then click Accounts and select your account. From the account screen, under Integrations, select API and Keys. Then select your App Name.
Redirect URL Each connected system provides a callback URL that must be added to your DocuSign environment. From the API and Keys page for your app, under Additional settings, add the Redirect URI.
Instance URL Instance URL will be used for authorization. This URL is used to configure your integration object and when executing your operations. For Example: https://demo.docusign.net
API Account ID To find the API Account ID, from the Account screen, under Integrations click API and Keys.
Integration Key To find the API Username, from the account screen, under Users And Groups click Users. Then select a user.
Secret Key From the API and Keys page for your app, under Authentication, select Authorization Code Grant, and click ADD SECRET KEY.
DocuSign Environment This is either DocuSign Development (https://account-d.docusign.com) or Production (https://account.docusign.com).
AUTHORIZE Uses the provided configuration information to authorize the designer in a new window. See OAuth 2.0: Authorization Code Grant for more details.

docusign-authorization-code.png

Operations

Name Description Type
Send Document for eSignature Sends a document to a specified recipient for eSignature WRITE
Create and Send Envelope Creates and sends an envelope for eSignature or creates a draft envelope WRITE
Get Envelope Definition Gets envelope information for a specified envelope READ
List Envelopes Gets a list of envelopes that match specified search parameters READ
Update Envelope Definition Modifies envelope definitions including status WRITE
List Documents of an Envelope Gets a list of all documents associated with a specified envelope READ
Upload New Documents to an Envelope Adds or updates documents to a specified envelope WRITE
Download Document from an Envelope Gets a document from a specified envelope and saves it into Appian WRITE
List Audit Events of an Envelope Gets envelope audit events for a specified envelope READ
Generate the Recipient Signing URL Gets a pre-authenticated URL to allow a user to eSign from Appian WRITE

Send Document for eSignature

Sends a document to a specified recipient for eSignature.

Note: Send Document for eSignature is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

docusign-send-for-esign.png

Create and Send Envelope

Creates and sends an envelope for eSignature or creates a draft envelope.

See the examples below of how to set up your DocuSign envelope.

Note: Create and Send Envelope is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

docusign-create-and-send.png

Get Envelope Definition

Gets envelope information for a specified envelope.

docusign-get-envelope.png

List Envelopes

Gets a list of envelopes that match specified search parameters.

docusign-list-envelope.png

Update Envelope Definition

Modifies envelope definitions including status.

Note: Update Envelope Definition is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

docusign-update-envelope.png

List Documents of an Envelope

Gets a list of all documents associated with a specified envelope.

docusign-list-document.png

Upload New Documents to an Envelope

Adds or updates documents to a specified envelope.

Note: Upload New Documents to an Envelope is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

docusign-upload-new-doc.png

Download Document from an Envelope

Gets a document from a specified envelope and saves it into Appian.

Note: Download Document from an Envelope is a WRITE type Integration. To protect against duplicate document creation, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

docusign-download-doc.png

List Audit Events of an Envelope

Gets envelope audit events for a specified envelope.

docusign-list-audit-events.png

Generate the Recipient Signing URL

Gets a pre-authenticated URL to allow a user to eSign from Appian.

Note: Generate the Recipient Signing URL is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

docusign-generate-signing-url.png

DocuSign Envelope Examples

Request Signature on Single Document by Email

This example shows an integration configuration that includes:

  • A single PDF document to be signed
  • One tab positioned using anchor text
  • One recipient
  • For more information, see DocuSign examples

See full Envelope Definition below.

docusign_examples_single_document.png

Envelope Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
a!toJson(
  {
    "emailSubject": "Please sign the NDA",
    "recipients": {
      "signers": {
        {
          "email": "the_nda_signer@example.com",
          "name": "Darlene Petersen",
          "recipientId": "1",
          "routingOrder": "1",
          "tabs": {
            "dateSignedTabs": {
              {
                "anchorString": "signer1date",
                "anchorYOffset": "-6",
                "fontSize": "Size12",
                "name": "Date Signed",
                "recipientId": "1",
                "tabLabel": "date_signed"
              }
            },
            "fullNameTabs": {
              {
                "anchorString": "signer1name",
                "anchorYOffset": "-6",
                "fontSize": "Size12",
                "name": "Full Name",
                "recipientId": "1",
                "tabLabel": "Full Name"
              }
            },
            "signHereTabs": {
              {
                "anchorString": "signer1sig",
                "anchorUnits": "mms",
                "anchorXOffset": "0",
                "anchorYOffset": "0",
                "name": "Please sign here",
                "optional": "false",
                "recipientId": "1",
                "scaleValue": 1,
                "tabLabel": "signer1sig"
              }
            }
          }
        }
      }
    }
  }
)

Multiple Documents and Tabs, Signer and CC Recipients

This example shows an integration configuration that includes:

  • Multiple documents
  • Multiple tabs including signing, fullName, dateSigned, and text tabs
  • Tabs positioned using anchor text
  • Two recipients, a signer and a cc recipient
  • For more information, see DocuSign examples

See full expressions for Envelope Definition and Documents below.

docusign-examples-DocuSign_MultipleDocumentsTabsSignerCC.png

Envelope Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
a!toJson(
  {
    "emailSubject": "Please sign the house documentation package",
    "recipients": {
      "carbonCopies": {
        {
          "email": "cody_vigil@worldwidecorp.example.com",
          "name": "Cody Vigil",
          "recipientId": "2",
          "routingOrder": "2"
        }
      },
      "signers": {
        {
          "email": "darlene_petersen@newco.example.com",
          "name": "Darlene Petersen",
          "recipientId": "1",
          "routingOrder": "1",
          "tabs": {
            "dateSignedTabs": {
              {
                "anchorString": "signer1date",
                "anchorYOffset": "-6",
                "fontSize": "Size12",
                "name": "Date Signed",
                "recipientId": "1",
                "tabLabel": "date_signed"
              },
              {
                "documentId": "2",
                "fontSize": "Size12",
                "name": "Date Signed",
                "pageNumber": "1",
                "recipientId": "1",
                "tabLabel": "doc3_date_signed",
                "xPosition": "89",
                "yPosition": "100"
              }
            },
            "fullNameTabs": {
              {
                "anchorString": "signer1name",
                "anchorYOffset": "-6",
                "fontSize": "Size12",
                "name": "Full Name",
                "recipientId": "1",
                "tabLabel": "Full Name"
              }
            },
            "signHereTabs": {
              {
                "anchorString": "signer1sig",
                "anchorUnits": "mms",
                "anchorXOffset": "0",
                "anchorYOffset": "0",
                "name": "Please sign here",
                "optional": "false",
                "recipientId": "1",
                "scaleValue": 1,
                "tabLabel": "signer1sig"
              },
              {
                "documentId": "2",
                "name": "Please sign here",
                "optional": "false",
                "pageNumber": "1",
                "recipientId": "2",
                "scaleValue": 1,
                "tabLabel": "signer1_doc2",
                "xPosition": "89",
                "yPosition": "40"
              },
              {
                "anchorString": "Client Signature",
                "anchorUnits": "mms",
                "anchorXOffset": "0",
                "anchorYOffset": "-4",
                "name": "Please sign here",
                "optional": "false",
                "recipientId": "1",
                "scaleValue": 1,
                "tabLabel": "doc3_client_sig"
              }
            },
            "textTabs": {
              {
                "anchorString": "signer1company",
                "anchorYOffset": "-8",
                "fontSize": "Size12",
                "name": "Company",
                "recipientId": "1",
                "required": "true",
                "tabLabel": "Company"
              },
              {
                "anchorString": "Client Name",
                "anchorYOffset": "-38",
                "fontSize": "Size12",
                "name": "Company",
                "recipientId": "1",
                "required": "true",
                "tabLabel": "Company"
              },
              {
                "documentId": "3",
                "fontSize": "Size10",
                "name": "Company",
                "pageNumber": "1",
                "recipientId": "1",
                "required": "true",
                "tabLabel": "Company",
                "xPosition": "145",
                "yPosition": "195"
              }
            }
          }
        }
      }
    }
  }
)

Documents

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  documents: {
    {
      documentId: 1,
      name: "NDA",
      appianDocument: todocument(1234)
    },
    {
      documentId: 2,
      name: "House",
      appianDocument: todocument(5678)
    },
    {
      documentId: 3,
      name: "contractor_agreement",
      appianDocument: todocument(9012)
    }
  }
}

Google Cloud Natural Language

Easily connect to Google Cloud Natural Language machine learning models. Extract structure and information from text, including both sentiment and key subjects such as people, places, and events. Integrations using this connected system will allow you to provide a text value and select which types of information to analyze.

See Google documentation on text analysis.

This is part of the Appian AI offering. You can request credentials and start using this service free of charge. Please see Appian AI for more details.

In addition to the common properties, a Google Cloud Natural Language connected system has the following properties:

Field Description
Instructions The following credentials are in the Google Service Account file that is generated when the service account key is created. If you are using Appian AI, contact your Appian administrator for the file. Otherwise, to create the service account key, in the Google Cloud Console, navigate to APIs & Services > Credentials.
Project ID Found in the Google Service Account file
Private Key ID Found in the Google Service Account file
Private Key Found in the Google Service Account file
Client Email Found in the Google Service Account file
Client ID Found in the Google Service Account file
TEST CONNECTION Uses the provided configuration information to connect to the target system. Returns success or error with details.

Operation

Name Description Type
Run Analysis Run analysis on provided text READ

gcnl_integration.png

Google Cloud Translation

The new Google Cloud Translation connected system enables you to quickly and easily translate text and detect language.

This is part of the Appian AI offering. You can request credentials and start using this service free of charge. Please see Appian AI for more details.

In addition to the common properties, a Google Cloud Vision connected system has the following properties:

Field Description
Instructions The following credentials are in the Google Service Account file that is generated when the service account key is created. If you are using Appian AI, contact your Appian administrator for the file. Otherwise, to create the service account key, in the Google Cloud Console, navigate to APIs & Services > Credentials.
Project ID Found in the Google Service Account file
Private Key ID Found in the Google Service Account file
Private Key Found in the Google Service Account file
Client Email Found in the Google Service Account file
Client ID Found in the Google Service Account file
TEST CONNECTION Uses the provided configuration information to connect to the target system. Returns success or error with details.

google-cloud-translation-cs.png

Operations

Name Description Type
Translate Text Translates provided text READ
Detect Language Discovers languages from provided text READ

Translate Text

translate-translate-text.png

Detect Language

translate-detect.png

Google Cloud Vision

Easily connect to Google Cloud Vision machine learning models. Extract structure and information from images and files, including logos, landmarks, and text (Optical Character Recognition). Provide an image and select different dimensions to analyze.

See Google documentation on image detection and annotation.

This is part of the Appian AI offering. You can request credentials and start using this service free of charge. Please see Appian AI for more details.

In addition to the common properties, a Google Cloud Vision connected system has the following properties:

Field Description
Instructions The following credentials are in the Google Service Account file that is generated when the service account key is created. If you are using Appian AI, contact your Appian administrator for the file. Otherwise, to create the service account key, in the Google Cloud Console, navigate to APIs & Services > Credentials.
Project ID Found in the Google Service Account file
Private Key ID Found in the Google Service Account file
Private Key Found in the Google Service Account file
Client Email Found in the Google Service Account file
Client ID Found in the Google Service Account file
TEST CONNECTION Uses the provided configuration information to connect to the target system. Returns success or error with details.

Operations

Name Description Type
Analyze and Detect text in images Run analysis on provided image to extract structure and information from images, including logos, landmarks, and text (Optical Character Recognition). Provide an image and select different dimensions to analyze. READ
Detect text in files (PDF/TIFF) Detect and transcribe text from PDF and TIFF files. Uploads a document to Google Cloud Storage, starts OCR analysis, and returns the output. WRITE

Analyze and Detect text in images

Extract structure and information from images, including logos, landmarks, and text (Optical Character Recognition). Provide an image and select different dimensions to analyze.

See Google documentation on image detection and annotation.

gcv_integration.png

Detect text in files (PDF/TIFF)

Detect and transcribe text from PDF and TIFF files. Uploads a document to Google Cloud Storage, starts OCR analysis, and returns the output.

Note: Detect text in files (PDF/TIFF) is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

vision-detect-text.png

Google Drive

The Google Drive connected system allows you to easily manage files and folders in Google Drive using OAuth 2.0 Authorization Code (per user).

In addition to the common properties, an Google Drive connected system has the following properties:

Field Description
Instructions To generate new credentials, see How to Generate New Credentials for Google Drive. If you already have credentials, you can download them by going to the Google Cloud Console and navigating to APIs & Services > Credentials.
Client ID This value is available in the downloaded credentials
Client Secret This value is available in the downloaded credentials
AUTHORIZE Uses the provided configuration information to authorize the designer in a new window. See OAuth 2.0: Authorization Code Grant for more details.

google-drive-cs.png

Operations

Name Description Type
Upload File Upload an Appian document to Google Drive WRITE
Create Folder Create a folder in Google Drive WRITE
Create Google Doc Create a Google Doc file in Google Drive from user input text WRITE
List Folder Contents List files and folders within a Google Drive folder READ
Query Drive Search using specified query within Google Drive READ
Copy File Create a copy of the file and add it to a specified folder WRITE
Download File Retrieve a file from Google Drive and download to Appian WRITE
Manage File Location Move a file between folders within Google Drive WRITE
Find File List files and folders matching a full text search READ

Upload File

Upload an Appian document to Google Drive.

Note: Upload File is a WRITE type integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

drive-upload-file.png

Create Folder

Create a folder in Google Drive.

Note: Create Folder is a WRITE type integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

drive-create-folder.png

Create Google Doc

Create a Google Doc file in Google Drive from user input text.

Note: Create Google Doc is a WRITE type integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

drive-create-google-doc.png

List Folder Contents

List files and folders within a Google Drive folder.

Find File Metadata property names in Google documentation.

drive-list-folder-contents.png

Query Drive

Search using specified query within Google Drive.

Find File Metadata property names in Google documentation.

drive-query-drive.png

Copy File

Create a copy of the file and add it to a specified folder.

Note: Copy File is a WRITE type integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

drive-copy-file.png

Download File

Retrieve a file from Google Drive and download to Appian.

Note: Download File is a WRITE type integration. To prevent against duplicate document creation, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

drive-get-file.png

Manage File Location

Move a file between folders within Google Drive.

Note: Manage File Location is a WRITE type integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

drive-manage-file-location.png

Find File

List files and folders matching a full text search.

Find File Metadata property names in Google documentation.

drive-find-file.png

How to Generate New Credentials for Google Drive

Follow the steps below to generate credentials:

  1. Create a Google Cloud Platform Project that has Drive API services enabled

  2. Set up the OAuth Consent
    • Name: Your Name
    • Add the following scopes:
      • ../auth/drive
      • ../auth/drive.metadata
      • ../auth/drive.appdata
    • Authorized Domains: <YOUR_ENVIRONMENT>.appiancloud.com
  3. Create Credentials
    • OAuth 2.0 client IDs > Create a Client ID > Create OAuth client ID
    • Application Type: Web Application
    • Name: <NAME>
    • Authorized JavaScript origins: <leave empty>
    • Authorized redirect URIs: https://<YOUR_ENVIRONMENT>.appiancloud.com/suite/oauth/callback
  4. Download your credentials from APIs & Services > Credentials

Microsoft Azure LUIS

Easily connect to Microsoft Azure Language Understanding (LUIS) machine learning models to understand what your users want in their own words. Integrations using this connected system will allow you to provide a user's input and LUIS will extract the intent and associated entities represented by the text.

See Microsoft documentation on getting predictions from an endpoint.

In addition to the common properties, a Microsoft Azure LUIS connected system has the following properties:

Field Description
Subscription Key Subscription keys can been found in your Azure portal or in the “Publish” tab of the LUIS application. In the “Publish” tab, any key that is NOT labeled “Starter_Key” is a subscription key.
Subscription Key Region Region for LUIS Endpoint API. The region in which you publish your LUIS app corresponds to the region or location you specify in the Azure portal when you create an Azure LUIS endpoint key. When you publish an app, LUIS automatically generates an endpoint URL for the region associated with the key.
Starter Key This key can be found in the “Publish” tab of the LUIS portal for any of your LUIS apps and is called “Starter_Key”. This key is also referred to as the “Programmatic Key” in the Microsoft documentation.
Starter Key Region Region for LUIS Programmatic API. The authoring region app can only be published to a corresponding publish region.
Bing Spell Check Subscription Key Specifying this value allows you to run spell check on query text before sending it through the model. You can create a Bing Spell Check key in your Azure portal.
Use Staging? When checked, Appian will query your staging model. Use this feature to validate changes to your model. You should always uncheck this box in production using import customization.
TEST CONNECTION Uses the provided configuration information to connect to the target system. Returns success or error with details.

Operation

Name Description Type
Get Predictions from Endpoint Predict the intent and associated entities using an existing model READ

luis_integration.png

Microsoft Dynamics 365 CRM

Create, retrieve, update, and delete entity records in Dynamics Version 9 and Dynamics 365.

Two forms of authentication are available for Dynamics: Authorization Code (per user) and Client Credentials (single system login).

Authorization Code Authentication

Each Appian user will be required to log in to their Dynamics account to authenticate. You must provide users a way to authenticate using OAuth 2.0.

See Dynamics OAuth 2.0 Code Grant Flow for more details.

In addition to the common properties, the Dynamics Authorization Code authentication has the following properties:

Field Description
Redirect URL Each connected system provides a callback URL that must be added to your Dynamics environment. In the Dynamics Setup portal, navigate to App Manager, and then find your App and select Edit. Add the callback URL in the field Callback URL. See Dynamics set up documentation for more details.
Instance URL Instance URL will be used for authorization. This URL is used to configure your integration object and when executing your operations. For example https://company-name.crm.dynamics.com
Application (Client) ID In the Azure portal, navigate to Azure Active Directory, select App Registrations, and then select your application. The Application (client) ID will be listed on this page.
Directory (Tenant) ID In the Azure portal, navigate to Azure Active Directory, select App Registrations, and then select your application. The Directory (tenant) ID will be listed on this page.
Client Secret In the App registrations page, select your application from the list, select Certificates & secrets, and then navigate to Client secrets. Add a new client secret and click Add. The generated key value is the Client Secret and must be copied before leaving this page.
AUTHORIZE Uses the provided configuration information to authorize the designer in a new window. See OAuth 2.0: Authorization Code Grant for more details.

dynamics_authorization_code_cs.png

Client Credentials Authentication

Provide a single Dynamics user’s credentials to authenticate. All integrations will use a shared Dynamics service account. Individual Appian users do not need their own Dynamics accounts.

See Dynamics OAuth 2.0 Client Credentials Flow for more details. Microsoft community also provides a helpful Setup Guide.

In addition to the common properties, the Dynamics Client Credentials authentication has the following properties:

Field Description
Instance URL Instance URL will be used for authorization. This URL is used to configure your integration object and when executing your operations. For example https://company-name.crm.dynamics.com
Application (Client) ID In the Azure portal, navigate to Azure Active Directory, select App Registrations, and then select your application. The Application (client) ID will be listed on this page.
Directory (Tenant) ID In the Azure portal, navigate to Azure Active Directory, select App Registrations, and then select your application. The Directory (tenant) ID will be listed on this page.
Client Secret From your application page in Azure portal, select Certificates & secrets, and then navigate to Client secrets. Add a new client secret and click Add. The generated key value is the Client Secret and must be copied before leaving this page.
TEST CONNECTION Uses the provided configuration information to connect to the target system. Returns success or error with details.

dynamics_client_credentials_cs.png

Operations

Name Description Type
Create an Entity Record Creates a new entity record in Dynamics WRITE
Retrieve an Entity Record Retrieves the data for a given entity record from Dynamics READ
List Entity Records Retrieves a collection of entity records from Dynamics that match the given query READ
Update an Entity Record Updates an entity record in Dynamics WRITE
Delete an Entity Record Deletes an entity record from Dynamics WRITE

Create an Entity Record

Creates a new entity record in Dynamics.

Note: The Create an Entity Record operation modifies data in Dynamics. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

dynamics_create.png

Retrieve an Entity Record

Retrieves the data for a given entity record from Dynamics.

dynamics_retrieve.png

List Entity Records

Retrieves a collection of entity records from Dynamics that match the given query. See Microsoft documentation for ODATA examples.

dynamics_list.png

Update an Entity Record

Updates an entity record in Dynamics.

Note: The Update an Entity Record operation modifies data in Dynamics. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

dynamics_update.png

Delete an Entity Record

Deletes an entity record from Dynamics.

Note: The Delete an Entity Record operation modifies data in Dynamics. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

dynamics_delete.png

Salesforce

Manage your customer information and interactions. Find, update, create, or delete records within your Salesforce instance.

Two forms of authentication are available for Salesforce: Web Server OAuth (per user) and Username-Password OAuth (single system login).

Web Server OAuth Authentication

Each Appian user will be required to log in to their Salesforce account to authenticate. You must provide users a way to authenticate using OAuth 2.0.

Please see Salesforce Web Server OAuth documentation for more details.

In addition to the common properties, the Salesforce Web Server OAuth authentication has the following properties:

Field Description
Redirect URL Each connected system provides a callback URL that must be added to your Salesforce environment. In the Salesforce Setup portal, navigate to App Manager, and then find your App and select Edit. Add the callback URL in the field Callback URL. See Salesforce set up documentation for more details.
Instance URL Instance URL will be used for authorization. This URL is used to configure your integration object and when executing your operations. e.g. https://na59.salesforce.com
Client Id In the Salesforce Setup portal, navigate to App Manager, and then find your App and select View. The Client Id will be listed on this page as “Consumer Key”. See Salesforce set up documentation for more details.
Client Secret In the Salesforce Setup portal, navigate to App Manager, and then find your App and select View. The Client Secret will be listed on this page as “Consumer Secret”. See Salesforce set up documentation for more details.
Scopes In the Salesforce Setup portal, navigate to App Manager, and then find your App and select View. The scopes will be listed on this page as “Selected OAuth Scopes”. This connected system requires API and refresh token access. You must provide API access using either the api or full scope. Please see Salesforce scope documentation for more details.
AUTHORIZE Uses the provided configuration information to authorize the designer in a new window. See OAuth 2.0: Authorization Code Grant for more details.

sf_web_server_connected_system.png

Username-Password OAuth Authentication

Provide a single Salesforce user’s credentials to authenticate. All integrations will use a shared Salesforce username and password. Individual Appian users do not need their own Salesforce accounts.

Please see Salesforce Username-Password OAuth documentation for more details.

In addition to the common properties, the Salesforce Username-Password OAuth authentication has the following properties:

Field Description
Instance URL Instance URL will be used for authorization. This URL is used to configure your integration object and when executing your operations. e.g. https://na59.salesforce.com
Client Id In the Salesforce Setup portal, navigate to App Manager, and then find your App and select View. The Client Id will be listed on this page as “Consumer Key”. See Salesforce set up documentation for more details.
Client Secret In the Salesforce Setup portal, navigate to App Manager, and then find your App and select View. The Client Secret will be listed on this page as “Consumer Secret”. See Salesforce set up documentation for more details.
Username The username used to sign into the provided Salesforce instance
Password The password used to sign into the provided Salesforce instance
Security Token This is an automatically-generated user security token from Salesforce. In the Salesforce personal settings for the user, select Reset My Security Token to generate a new security token. When authorizing, this security token will be appended to the password. Please see Salesforce security token documentation for more details.
TEST CONNECTION Uses the provided configuration information to connect to the target system. Returns success or error with details.

sf_username_password_connected_system.png

Operations

Name Description Type
Create SObject Adds a new business object to Salesforce WRITE
Update SObject Updates data for an existing business object in Salesforce WRITE
Delete SObject Removes a business object from Salesforce WRITE
SOQL Query Allows querying a Salesforce instance using the Salesforce Object Query Language (SOQL) READ
SOSL Search Allows searching a Salesforce instance using the Salesforce Object Search Language (SOSL) READ
Describe SObject Provides introspection into the metadata of the given Salesforce objects READ
Describe All SObjects Provides introspection into the objects available in the target Salesforce instance READ

Create SObject

Adds a new business object to Salesforce

Note: Create SObject is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

sf_integration_create_sobject.png

Update SObject

Updates data for an existing business object in Salesforce

Note: Update SObject is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

sf_integration_update_sobject.png

Delete SObject

Removes a business object from Salesforce

Note: Delete SObject is a WRITE type Integration. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

sf_integration_delete_sobject.png

SOQL Query

Allows querying a Salesforce instance using the Salesforce Object Query Language (SOQL)

sf_integration_soql_query.png

Allows searching a Salesforce instance using the Salesforce Object Search Language (SOSL)

sf_integration_sosl_search.png

Describe SObject

Provides introspection into the metadata of the given Salesforce objects

sf_integration_describe_sobject.png

Describe All SObjects

Provides introspection into the objects available in the target Salesforce instance

sf_integration_describe_all_objects.png

SharePoint

Manage documents and folders in your SharePoint instance.

Two forms of authentication are available for SharePoint: Authorization Code (per user) and Client Credentials (single system login).

Authorization Code Authentication

Each Appian user will be required to log in to their SharePoint account to authenticate. You must provide users a way to authenticate using OAuth 2.0.

Please see SharePoint OAuth 2.0 Code Grant Flow for more details.

In addition to the common properties, the SharePoint Authorization Code authentication has the following properties:

Field Description
Redirect URL Each connected system provides a callback URL that must be added to your SharePoint environment. In the SharePoint Setup portal, navigate to App Manager, and then find your App and select Edit. Add the callback URL in the field Callback URL. See SharePoint set up documentation for more details.
Instance URL Instance URL will be used for authorization. This URL is used to configure your integration object and when executing your operations. e.g. https://yourinstance.sharepoint.com
Application (Client) ID In the Azure portal, navigate to Azure Active Directory, select App Registrations, and then select your application. The Application (client) ID will be listed on this page.
Directory (Tenant) ID In the Azure portal, navigate to Azure Active Directory, select App Registrations, and then select your application. The Directory (tenant) ID will be listed on this page.
Client Secret From your application page in Azure portal, select Certificates & secrets, and then navigate to Client secrets. Add a new client secret and click Add. The generated key value is the Client Secret and must be copied before leaving this page.
AUTHORIZE Uses the provided configuration information to authorize the designer in a new window. See OAuth 2.0: Authorization Code Grant for more details.

sharepoint_authorization_code_cs.png

Client Credentials Authentication

Provide a single SharePoint user’s credentials to authenticate. All integrations will use a shared SharePoint service account. Individual Appian users do not need their own SharePoint accounts.

To generate Client Credentials, see Granting access using SharePoint App-Only in the Microsoft docs.

A few notes on the process:

  1. If you only need access to a particular SharePoint site, go to that site’s URL to generate your Client ID and Client Secret. For example: <siteName>.sharepoint.com/sites/<subsite>/_layouts/15/appinv.aspx
  2. If you do not have tenant administrator permissions, you may need to use a different permission XML. For example:
1
2
3
<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl" />
</AppPermissionRequests>

In addition to the common properties, the SharePoint Client Credentials authentication has the following properties:

Field Description
Instance URL Instance URL will be used for authorization. This URL is used to configure your integration object and when executing your operations. e.g. https://yourinstance.sharepoint.com
Application (Client) ID To generate the Application (Client) ID, see Granting access using SharePoint App-Only in the Microsoft docs.
Client Secret To generate the Client Secret, see Granting access using SharePoint App-Only in the Microsoft docs.
Directory (Tenant) ID In the Azure portal, navigate to Azure Active Directory. Under Manage, select Properties. The tenant ID is shown in the Directory ID field.
TEST CONNECTION Uses the provided configuration information to connect to the target system. Returns success or error with details.

sharepoint_client_credentials_cs.png

Operations

Name Description Type
Add Document Upload files from Appian to SharePoint WRITE
Download Document Retrieves the document from SharePoint and places into an Appian WRITE
Get Document Metadata Retrieves metadata for a file READ
Update Document Metadata Updates metadata for the specified file WRITE
Create Folder Creates a new folder in SharePoint WRITE
Get Folder Metadata Updates metadata for the specified folder READ
List Folder Contents Lists a folder's contents READ
Update Folder Metadata Retrieves metadata for a folder READ
Execute Read Request Execute arbitrary read requests to SharePoint READ
Execute Write Request Execute arbitrary write requests to SharePoint WRITE

Add Document

Upload a document from Appian to SharePoint.

Note: The Add Document operation modifies data in SharePoint. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

sharepoint_add_document.png

Download Document

Retrieves the document from SharePoint and places into an Appian.

Note: The Download Document operation downloads a file to Appian. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

sharepoint_download_file.png

Get Document Metadata

Retrieves metadata for a file.

sharepoint_get_document_metadata.png

Update Document Metadata

Updates metadata for the specified file. See Updating Metadata for information on how to get the metadata properties from a Get Document Metadata request.

Note: The Update Document Metadata operation modifies data in SharePoint. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

sharepoint_update_document_metadata.png

Create Folder

Creates a new folder in SharePoint.

Note: The Create Folder operation modifies data in SharePoint. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

sharepoint_create_folder.png

Get Folder Metadata

Retrieves metadata for a folder.

sharepoint_get_folder_metadata.png

List Folder Contents

Lists a folder's contents.

sharepoint_list_folder_contents.png

Update Folder Metadata

Updates metadata for the specified folder. See Updating Metadata for information on how to get the metadata properties from a Get Folder Metadata request.

Note: The Update Folder Metadata operation modifies data in SharePoint. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

sharepoint_update_folder_metadata.png

Execute Read Request

Execute read requests to SharePoint using a relative path.

sharepoint_execute_read_request.png

Execute Write Request

Execute write requests to SharePoint using a relative path and body.

Note: The Execute Write Request operation modifies data in SharePoint. To prevent the integration from making the same update twice, it can only be used in the saveInto parameter of an interface component or in a Web API. See Call an Integration for more information.

sharepoint_execute_write_request.png

Updating Metadata: Identifying Metadata Properties

In order to update metadata for documents or folders, you will need to send the OData type, the name of the metadata field, and the updated value of the field. To get this information, you can send a Get Document Metadata or Get Folder Metadata request.

Getting the OData Type

The OData type is sent in the body as { "type": "<OData Type>" }

Sometimes, you can use SP.ListItem for the OData type. However, if that doesn't work, send a get metadata request. The OData type is listed under ListItemAllFields > __metadata in the response.

In our case, it is SP.Data.Shared_x0020_DocumentsItem.

sharepoint_get_document_metadata.png

Getting the Metadata Field Name

If you send a request to update data and it does not update, but the request says it was successful, send a get metadata request and look for the metadata field in the response. The name of the field might be different than its display name.

For example, in our SharePoint environment, we have a metadata field called "Description."

sharepoint_get_document_metadata.png

However, when we send a Get Document Metadata request, the name of the field is "Description0."

sharepoint_get_document_metadata.png

Creating the Request Body

When we use the information we received from the get metadata request above, our request body looks like this:

1
2
3
4
5
6
=a!toJson(
  { "__metadata":
  { "type": `"SP.Data.Shared_x0020_DocumentsItem"` },
  `"Description0"`:"Quarterly report 2019-Q4"
  }
)

Providing the ETag Value

If you need to prevent lost updates caused by multiple users making a request to update the same file, you should provide the ETag number. If you don't, when two or more requests are made at the same time, the last request to go through will overwrite the earlier requests. This could lead to one or more updates being lost because the last update won't include the information from the previous requests.

To get the ETag value, send a Get Document Metadata request. The body of the response contains the ETag number.

sharepoint_create_folder.png

The dot notation we would use to get the ETag in the above response is .result.d.ListItemAllFields.__metadata.etag.

sharepoint_create_folder.png

FEEDBACK