Microsoft SharePoint

📘

Licensing

Contact your sales representative if you are interested in obtaining a license for the Microsoft SharePoint Connector for your SmartIQ instance.

SharePoint is a popular enterprise content and document management platform developed by Microsoft Corporation, and provides a wide range of functions and capabilities including personal cloud, enterprise social networking, enterprise search, business intelligence, workflow management and web content management.

The Microsoft SharePoint Connector for SmartIQ has been developed to provide an integrated experience for customers looking for end to end document lifecycle management, leveraging the powerful e-forms and document creation of SmartIQ and the content management and publishing capabilities of SharePoint.

Components

Action

• Save to Document Library Action
• Save to List Action

Data Connection

• SharePoint Data Source Provider

Features

• Save documents to SharePoint, including documents generated by SmartIQ and any required attachments. This includes adding new and updating existing documents.
• Supports a wide range of metadata, including text, dates, choice and multi-choice items.
• Support for managed metadata based on a taxonomy term store
• Automatic check-out for documents being updated, if required based on the library settings.
• Ability to check-in documents with major, minor or overwrite version settings and provide a custom check-in comment.
• Save documents to existing folders, or create folders if required.
• Define global default connection information, or override per project to connect to multiple SharePoint sites.

SharePoint Service Account

Depending on the authentication method, this connector may use a service account to authenticate with the SharePoint server. This account may be any valid SharePoint user with appropriate permissions to perform the required tasks.

While not a requirement, it is recommended that this account be a dedicated account for this purpose.

Configurations

The Microsoft SharePoint Connector exposes a number of settings which provide tenant-wide values to control behavior or context. In many cases, these settings can be overridden when the action is used in a project.

Connector Settings

📘

Important

Connector Settings are applied system-wide. For specific scenarios where it is required to use different credentials, specify the credential settings in Design or in the Data Connection configuration.

1. In a web browser, navigate to the SmartIQ Manage application and log in.

2. Go to Settings > SharePoint.

3. Review and update the settings as required. The settings are described in the table below.

📘

Important

• These connector settings are optional. However, if not set within the action an error may occur.
• Default User Agent is not configurable with the action attributes and must be configured on the settings page if used.
• Taxonomy Term Store Culture is also not configurable within the action attributes and must have a valid culture identifier if using managed metadata.

4. For multiple SharePoint accounts:

   1. Click the New Set button. For example, Sandbox and Production.
   2. Click the Set as Default button to change the default connector set. If the previous Default was set in Design, SmartIQ will now use the new Default connector values.

5. Click the Save button at the top of the page.

SharePoint Data Connection

The SharePoint Connector also includes a data object type for retrieving information from a SharePoint list or folder, in a manner that can be displayed and analyzed. This feature is intended to provide form users with access to relevant SharePoint information or resources without those end users having direct access to the SharePoint environment. For example, external facing portals where users are not part of the organization’s domain.

1. In Manage, create a new Data Connection and select “SharePoint” as the Connection Type.

2. Configure the settings as per the table below:

3. Select No credentials required.

4. Click Save.

5. Click Test Connection to verify that all the settings have been configured correctly,

📘

Multiple Environments

The data connection is restricted to a single SharePoint site. If you have multiple sites, for example, <https://my.sharepoint.com/internal> and <https://my.sharepoint.com/clients>, etc, you will need to create a separate data connection for each site in Manage > Settings and select the correct account as per above.

6. Click Data Objects > New Data Object.

7. Select ‘List’ from the Object Type drop-down.

8. In the Data Object Name/Definition field, enter a few characters from the name of the list you want to access (or enter a few spaces to view the complete list).

9. Chose the list you want to access and provide an appropriate Display Name for the chosen list.

10. In Available Filter Fields, click Add All.

11. Click Save.

Using the Data Connection in Design

Typical use cases for the SharePoint data connector include allowing selection of items from SharePoint lists, displaying details of documents in SharePoint, and allowing retrieval of documents.

The process for using these data connections is overall similar to other data connections, with only a few items of note:

Document Data Convert

The Data Connector supports the use of the "Data Convert" feature to add retrieved documents to SmartIQ's generated documents at submission time. This allows the document(s) to be used as if it had been generated by SmartIQ.

Direct Document Download

The Data Connector includes the DownloadUrl of each document in the results it retrieves. This allows the designer to display a link that the user can click to open the document in their browser.

For more information, refer to Answers and Data Fields.

SharePoint Versions

This connector is primarily designed to work with SharePoint Online using either Microsoft Graph API or .NET client-side object model (CSOM) to communicate with the SharePoint server.

SharePoint 2013 & 2016 are supported but only for .NET client-side object model (CSOM) and App Only to communicate with the SharePoint server.

For SharePoint 2016+, use the 2013 version flag value.

Authentication

Graph API

SharePoint sites that are configured in SmartIQ Settings to use Graph API will use the REST based Microsoft Graph API to connect to SharePoint. Graph API does not support the creation of Managed Metadata terms from SmartIQ.

Graph API connection is only available if the "Use Graph API for SharePoint" option is checked in the SmartIQ Settings.

To use Graph API with the Sharepoint Connector:

1. Go to Manage > Settings > SharePoint and specify the Default App Id and Default App Secret. Leave the other authentication fields blank.
2. Check the Use Graph API for SharePoint box.
3. Save the changes.

See Microsoft's Documentation (https://learn.microsoft.com/en-us/graph/auth/auth-concepts) for further information on enabling Graph API authentication for SharePoint sites.

CSOM (.NET Client Side Object Model)

To use SharePoint with the CSOM libraries, sites that are configured in SmartIQ Settings must use either Azure AD Authentication or the legacy App-Only Authentication.

CSOM connection is only available if the Use Graph API for SharePoint option is not checked in the SmartIQ Settings.

Azure AD Authentication

This authentication method requires a username and password as well as the application id to be supplied.

To use Azure AD Authentication:

1. Go to Manage > Settings > SharePoint and specify the Default App Id and Default Username and Default Password. Leave the other authentication fields blank
2. Ensure the Use Graph API for SharePoint box is unchecked.
3. Save the changes.

See Microsoft's Documentation (https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azuread) for further information on enabling Azure AD authentication for SharePoint sites.

🚧

API Permissions

If API Permissions in Sharepoint are set to Application Permissions and you recieve a "List does not exist at site with URL..." error, please use Delegated Permissions instead.

App-Only Authentication (Legacy)

Basic authentication using username and password on SharePoint instances has been deprecated by Microsoft. Newer instances of SharePoint do not have this option available and Azure AD authentication should be used for CSOM communication, or switch to Graph API.

For older legacy, SharePoint sites App-Only authentication using Client Id and Client Secret is the only option now available in SmartIQ

To use App-Only Authentication:

1. Go to Manage > Settings > SharePoint and specify the Default App Id and Default App Secret. Leave the other authentication fields blank.
2. Save the changes.

See Microsoft's Documentation (https://learn.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs) for further information on enabling Client Id and Client Secret on App-Only SharePoint sites.

📘

Authentication Methods

If App Id/App Secret and Username/Password fields are populated, SmartIQ will only use App ID/App Secret. If the App-Only Authentication is unsuccessful, SmartIQ will not use the username/password as a secondary authentication option.

Save to Document Library Action

The Save to Document Library Action has been designed to save documents generated by SmartIQ or attached to the SmartIQ form, to be saved to a SharePoint document library.

Features include:

• Save documents to SharePoint, including documents generated by SmartIQ and any required attachments. This includes adding new and updating existing documents.
• Supports a wide range of metadata, including text, dates, choice and multi-choice items.
• Support for managed metadata based on a taxonomy term store.
• Automatic check-out for documents being updated, if required based on the library settings.
• Ability to check-in documents with major, minor or overwrite version settings and provide a custom check-in comment.
• Save documents to existing folders, or create folders if required.
• Define global default connection information, or override per project to connect to multiple SharePoint sites.

Using the Action in Design

Once you’ve added the Save to SharePoint Document Library Action to your project, either on the Finish page or a workflow transition, use the following table to configure any action attributes that you require.

📘

Note

There are no mandatory action attributes. Use the table below to apply any action attributes that are appropriate. Remember, default values set in the connector settings will be used if there are no overriding action attributes, and you may override some or all settings as required.

Action Attributes

Action Outputs

📘

Compatibility

For backward compatibility, the Folder attribute supports a full document path in place of using the Document Library attribute. For example:
<https://{sharepointsite}/{documentlibrary}/folder>
or
{documentlibrary}/folder

Configuring Metadata

You can configure this action to save metadata values against the documents saved in SharePoint. SmartIQ supports both standard metadata site columns, as well as managed metadata.

📘

Managed Metadata

Managed Metadata functions are not available in the Microsoft Graph API and will not function as expected if SmartIQ SharePoint connection is configured to "Use Graph API for SharePoint"

There are two ways this can be configured:

Document Metadata

In Design, click Project Properties > Document Metadata to open the metadata screen. Add any metadata elements required, and set fixed or dynamic values based on questions in the form.
Metadata configured in this way will be added for all Save to SharePoint Document Library actions used in the project.

Action Level Metadata

On the Save to SharePoint Document Library action, add a Metadata Element attribute for each metadata column to be configured following the format specified in the attributes table above.
Metadata configured in this way is only added to the action it is configured for, and will override any project level metadata configured with the same name.

Metadata columns, including managed metadata, may be configured to allow multiple selections. For example, a multiple choice field. To set multiple values where allowed, you can pass a pipe-separated string value. For example: metadata_name = value1|value2|value3

Action Documents

Use the Documents tab in Design to configure which documents should be used by this action. By default, all documents will be used, including those generated and attached.
If you’d like to configure which documents should be used by this action, select the ‘Custom’ option on the Documents tab and proceed to add the required documents and document formats.

Error Handling

The Save to Document Library Action will return an action result. For more information about action result types, refer to this page. If the result is a failure, an error message will be available in SmartIQ Manage on the Management screen.

Troubleshooting Mode

If Troubleshooting Mode is enabled for a published project, the Save to Document Library Action will record a series of information messages on the Management screen in Manage. These messages are intended to help identify problems and where they occur in the document save process, in particular with setting metadata, content type and checking in or out.
For example:

---Begin Microsoft SharePoint Connector Debug Messages---
About to save document 'MyDocument.docx' to SharePoint
Performing document check-out ready for content type and/or metadata update...
Check-out completed.
Setting content type to 'Sample'...
Content type set.
Setting metadata...
Metadata set.
Performing final check-in...
Check-in completed.
---End Microsoft SharePoint Connector Debug Messages---

Common Error Messages

All error messages generated by this action begin with the statement ‘{Action Name} failed:’ for example Save to SharePoint Document Library failed. If you renamed the action in Design, the name you chose will be used.

📘

Note

All failure messages are reported as level ‘Warning’ in Manage. SmartIQ reserves the use of ‘Error’ level messages for critical events such as document generation errors that may affect all actions.

Some common error messages that may be returned by this action are:

• List ‘{listname}’ does not exist at site with URL ‘{siteurl}’.
  The document library named in the action attributes, or the default document library named in the connector settings, does not exist. Check the settings and try again.
• The file “{fileurl}” is checked out for editing by {username}.
  The document being uploaded to SharePoint already exists, and is already checked out by a user making it unavailable for updates by this connector. Ask the owner to check the document in before trying again, or nominate an alternate folder.
• Folder not found '{foldername}'.
  The folder named in the action attributes does not exist in the SharePoint document library, and the Create Folder attribute is not set to ‘true’.

Sample Project

SharePoint Connector - Save to SharePoint Document Library

This is a SmartIQ project that generates a Word document and saves it into SharePoint online. It will also include a metadata field.

Action Configuration

Note that it will save the generated document in the ACT folder that is located within the Australia folder.

├── Documents
│      ├── Australia
└──        └── ACT

Also note that every time the form is submitted, it will modify the existing document if the name and path are the same. Versioning will be applied as defined in SharePoint General Settings.

Connector Settings (Manage)

Save to List Action

The List Action has been designed to save metadata generated by SmartIQ to be saved to a SharePoint list.

Features include:

• Save metadata as a list item to SharePoint. This includes adding new and updating existing list items.
• Supports a wide range of metadata, including text, dates, choice and multi-choice items.
• Support for managed metadata based on a taxonomy term store.
• Define global default connection information, or override per project to connect to multiple SharePoint sites.

Using the Action in Design

Once you’ve added the Save to List Action to your project, either on the Finish page or a workflow transition, use the following table to configure any action attributes that you require.

📘

Note

There are no mandatory action attributes. Use the table below to apply any action attributes that are appropriate. Remember, default values set in the connector settings will be used if there are no overriding action attributes, and you may override some or all settings as required.

Action Attributes

Configuring Metadata

You must configure this action to save metadata values against the list item saved in SharePoint. SmartIQ supports both standard metadata site columns, as well as managed metadata. Note that Graph API does not support the creation of Managed Metadata terms from SmartIQ.

There are two ways this can be configured:

Document Metadata

In Design, click Project Properties > Document Metadata to open the metadata screen. Add any metadata elements required, and set fixed or dynamic values based on questions in the form.
Metadata configured in this way will be added for all Save to SharePoint List actions used in the project.`

Action Level Metadata

On the Save to SharePoint List action, add a Metadata Element attribute for each metadata column to be configured following the format specified in the attributes table above.

Metadata configured in this way is only added to the action it is configured for, and will override any project level metadata configured with the same name.

Metadata columns, including managed metadata, may be configured to allow multiple selections – for example a multiple choice field. To set multiple values where allowed, you can pass a pipe-separated string value. For example:
metadata_name = value1|value2|value3

Error Handling

The Save to Document Library Action will return an action result. For more information about action result types, refer to this page. If the result is a failure, an error message will be available in SmartIQ Manage on the Management screen.

Troubleshooting Mode

If Troubleshooting Mode is enabled for a published projects, the Save to List Action will record a series of information messages on the Management screen in Manage. These messages are intended to help identify problems and where they occur in the document save process, in particular with setting metadata, content type and checking in or out.
For example:

---Begin Microsoft SharePoint Connector Debug Messages---	
About to insert a new item in list 'My List'.	
Setting metadata...	
--> Field name 'Title' found. Field Value='' metadata value set	
About to save standard metadata...	
Save completed.	
Metadata set.	
---End Microsoft SharePoint Connector Debug Messages---

Common Error Messages

All error messages generated by this action begin with the statement ‘{Action Name} failed:’ for example ‘Save to SharePoint List failed’. If you renamed the action in Design, the name you chose will be used.

📘

Note

All failure messages are reported as level ‘Warning’ in Manage. SmartIQ reserves the use of ‘Error’ level messages for critical events such as document generation errors that may affect all actions.

Some common error messages that may be returned by this action are:

• Save to SharePoint List Action failed: You must specify a SharePoint List name.
• List ‘{listname}’ does not exist at site with URL ‘{siteurl}’.
  The list named in the action attributes does not exist. Check the settings and try again.
• About to update item '' in list ‘{listname}’
  No List Item Id was found so the item to update is blank.
• Field name '{name}' not found and will be ignored.
  Metadata field name supplied was not present so cannot be updated.
• Save to SharePoint List Action failed: Input string was not in a correct format.
  This error can have a number of causes but will occur if the List Item Id is not valid.

Sample Project

SharePoint Connector - Save to SharePoint List

This SmartIQ project saves metadata into a SharePoint List. Please note that a Custom List named Customers needs to be configured in SharePoint with Columns: Name and DOB.

Action Configuration

Connector Settings (Manage)