SharePoint Connected System

Overview

This article explains how to set up a SharePoint connected system to manage your documents and folders.

For instructions on how to integrate your SharePoint connected system with your Appian connected system, see Integrating SharePoint with Appian's Connected System.

For information that pertains to all connected systems, see Connected System Object.

Properties

Three forms of authentication are available for SharePoint: authorization code (per user) and client credentials (single system login) using either Azure ACS or Entra ID. Connected systems using the legacy authorization code authentication type should migrate to authorization code to ensure continued access to your SharePoint data.

Authorization Code authentication

Each Appian user will be required to sign in to their SharePoint account to authenticate. You must provide users a way to authenticate using OAuth 2.0. See SharePoint OAuth 2.0 Code Grant Flow for more details.

The SharePoint Authorization Code authentication has the following properties:

^* This value is included in an import customization file so that you can specify a different value for each environment. Sensitive values will not be exported in the import customization file and must be added manually. Required fields must have a value upon import or else import will fail. For more information on import/export behavior, see the Connected Systems Object page.

Click AUTHORIZE to use the provided configuration information to authorize the designer in a new window. See OAuth 2.0: Authorization Code Grant for more details.

Authorization Code - Legacy authentication

Each Appian user will be required to sign in to their SharePoint account to authenticate. You must provide users a way to authenticate using OAuth 2.0. See SharePoint OAuth 2.0 Code Grant Flow for more details.

The SharePoint Authorization Code Legacy authentication has the following properties:

^* This value is included in an import customization file so that you can specify a different value for each environment. Sensitive values will not be exported in the import customization file and must be added manually. Required fields must have a value upon import or else import will fail. For more information on import/export behavior, see the Connected Systems Object page.

Click AUTHORIZE to use the provided configuration information to authorize the designer in a new window. See OAuth 2.0: Authorization Code Grant for more details.

Client Credentials - Azure ACS authentication

Using Client Credentials, 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>
   

The SharePoint Client Credentials - Azure ACS authentication has the following properties:

^* This value is included in an import customization file so that you can specify a different value for each environment. Sensitive values will not be exported in the import customization file and must be added manually. Required fields must have a value upon import or else import will fail. For more information on import/export behavior, see the Connected Systems Object page.

Client Credentials - Entra ID authentication

Using Client Credentials, all integrations will use a shared SharePoint service account. Individual Appian users do not need their own SharePoint accounts. If your application is configured with delegated permissions for the site, users will only have access to the site data they would see if signed in to SharePoint directly.

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

The SharePoint Client Credentials - Entra ID authentication has the following properties:

^* This value is included in an import customization file so that you can specify a different value for each environment. Required fields must have a value upon import or else import will fail. For more information on import/export behavior, see the Connected Systems Object page.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Automating property updates

This object's properties can also be updated programmatically using the Update Connected System endpoint. This lets you change passwords, API keys, and other values without needing to sign in to Appian.

The following properties can be included in the JSON request body of the PATCH /connected-system/<UUID> call.

Operations

Add Document

Upload a document from Appian to SharePoint.

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.

Download Document

Retrieves the document from SharePoint and places into an Appian.

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.

Get Document Metadata

Retrieves metadata for a file.

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.

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.

Create Folder

Creates a new folder in SharePoint.

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.

Get Folder Metadata

Retrieves metadata for a folder.

List Folder Contents

Lists a folder's contents.

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.

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.

Execute Read Request

Execute read requests to SharePoint using a relative path.

Execute Write Request

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

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.

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.

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."

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

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.

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

Feedback