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
Data Connection
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.
-
In a web browser, navigate to the SmartIQ Manage application and log in.
-
Go to Settings > SharePoint.
-
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.
Setting | Description |
---|---|
Name | Name of the SharePoint site |
Default Site URL | Enter the URL of the SharePoint site to use by default. This needs to be the site root which will be something like <https://mysharepoint.com > or <https://mysharepoint.com/mysite >Note: Page or list urls are not correct for this value. |
Default Document Library | Enter the name of the Document Library to use by default for saving documents. |
Default App Id | See Authentication for details on how to use this field |
Default App Secret | See Authentication for details on how to use this field |
Default Username | See Authentication for details on how to use this field |
Default Password | See Authentication for details on how to use this field |
Default Domain | Leave this blank |
Default Version | Enter the version of Microsoft SharePoint that the default site URL refers to. Refer to SharePoint Versions for more information. |
Taxonomy Term Store Culture | If using Managed Metadata, enter the culture identifier for the Taxonomy Term Store to be used. |
Create Missing Terms | If this is set to ‘true’ and when a Managed Metadata term is specified but does not yet exist, the system will create the term and populate it. This is not supported by Graph API |
Default User Agent | If this value is not supplied, your SharePoint access may be throttled after a small number of requests. See this for information on generating an appropriate User Agent value for your server. |
Default Request Timeout | In milliseconds. Increase this if you need have a slow server/connection or are getting timeout errors connecting to the SharePoint site. |
-
For multiple SharePoint accounts:
- Click the New Set button. For example, Sandbox and Production.
- 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.
-
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.
- In Manage, create a new Data Connection and select “SharePoint” as the Connection Type.
- Configure the settings as per the table below:
Setting | Description |
---|---|
Data Connection Name | Enter the name of this data source, then this can be referenced in Design. |
Connection Type | SharePoint |
Folder | Select a folder from the list. |
Settings | Select the SharePoint account from the drop-down list. Note: This will only appear if your site has multiple SharePoint account in Settings. |
Connection Attributes | Leave this empty |
-
Select No credentials required.
-
Click Save.
-
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.
-
Click Data Objects > New Data Object.
-
Select ‘List’ from the Object Type drop-down.
-
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).
-
Chose the list you want to access and provide an appropriate Display Name for the chosen list.
-
In Available Filter Fields, click Add All.
-
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:
- Go to Manage > Settings > SharePoint and specify the
Default App Id
andDefault App Secret
. Leave the other authentication fields blank. - Check the
Use Graph API for SharePoint
box. - 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:
- Go to Manage > Settings > SharePoint and specify the
Default App Id
andDefault Username
andDefault Password
. Leave the other authentication fields blank - Ensure the
Use Graph API for SharePoint
box is unchecked. - 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:
- Go to Manage > Settings > SharePoint and specify the
Default App Id
andDefault App Secret
. Leave the other authentication fields blank. - 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
Name | Description |
---|---|
Site URL | Enter the URL of the SharePoint site to use. This needs to be the site root which will something like <https://mysharepoint.com > or <https://mysharepoint.com/mysite >Note: Page or list urls are not correct for this value. |
Document Library | Enter the name of the Document Library to use for saving documents. |
Client Id | Optional, this overrides the App Id field in the Connector Settings. See Authentication for details on how to use this input field |
Client Secret | Optional, this overrides the App Secret field in the Connector Settings. See Authentication for details on how to use this input field |
Username | Optional, this overrides the Username field in the Connector Settings. See Authentication for details on how to use this input field |
Password | Optional, this overrides the Password field in the Connector Settings. See Authentication for details on how to use this input field |
Version | Enter the version of Microsoft SharePoint that the site URL refers to. Refer to SharePoint Versions for more information. |
Metadata Element | Enter the name and value of a single metadata element to be set, including managed metadata, using the format: name = value Add as many Metadata Element attributes as you need to set all metadata values. See Configuring Metadata below for more information. |
Content Type | Enter the name of the SharePoint content type to use, if it varies from the library default. |
Create Folder | Set as ‘true’ if the connector should automatically create the folder specified if it doesn’t already exist. Note that if set, this will create nested folder structures if specified. |
Folder | Specify the folder path to which this document should be saved. Note: If the document library attribute is not set, it is assumed the folder attribute will contain the name of the document library. Path items should be separated with a ‘/’ e.g. ‘parentfolder/childfolder‘. |
Check-in | Set as ‘true’ if the connector should check the document in after uploading. If document version control is enabled in the target document library, this setting can be used to avoid leaving documents in a checked out state. |
Check-in Type | Set as ‘major’, ‘minor’ or ‘overwrite’ to indicate the version control behaviour for this check-in. |
Check-in Comment | Enter a comment if you wish to be recorded against this version check-in. |
Action Outputs
Name | Description |
---|---|
Download Document URL | Url to download the newly created or updated. |
Base Document Library URL | Base Url of the folder where the document was saved or updated. |
Preview Document URL | Url that allows previewing the document in the browser. |
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
Action Input | Value |
---|---|
Document Library | Documents |
Folder | Australia\ACT |
Metadata Element [name=value] | Location = Fyshwick |
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)
Property Name | Value |
---|---|
Default Site URL | https://YourDomain.sharepoint.com |
Default Document Library | Documents |
App Id | YourAppId |
App Secret | YourAppSecret |
Default Version | 2010 | 2013 | online |
Taxonomy Term Store Culture | en-US |
Create Missing Terms | true | false |
Default Request Timeout | 1000000 |
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
Name | Description |
---|---|
Site URL | Enter the URL of the SharePoint site to use. This needs to be the site root which will something like <https://mysharepoint.com > or <https://mysharepoint.com/mysite >Note: Page or list urls are not correct for this value. |
Client Id | Optional, this overrides the App Id field in the Connector Settings. See Authentication for details on how to use this input field |
Client Secret | Optional, this overrides the App Secret field in the Connector Settings. See Authentication for details on how to use this input field |
Username | Optional, this overrides the Username field in the Connector Settings. See Authentication for details on how to use this input field |
Password | Optional, this overrides the Password field in the Connector Settings. See Authentication for details on how to use this input field |
Version | Enter the version of Microsoft SharePoint that the site URL refers to. Refer to SharePoint Versions for more information. |
Metadata Element | Enter the name and value of a single metadata element to be set, including managed metadata, using the format: name = value Add as many Metadata Element attributes as you need to set all metadata values. See Configuring Metadata below for more information. |
Create Missing Term | If this is set to ‘true’, when a Managed Metadata term is specified but does not yet exist, the system will create the term and populate it. It will override the value in the connector settings so can be set to ‘false’ if needed. |
List | Enter the name of the List to be modified |
List Item Id | Enter the List Item Id for the item to be updated. |
Save Operation | Possible operations are ‘insert’ or ‘update’. For update the List Item Id is required. |
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
Action Input | Value |
---|---|
List | Customers |
Metadata Element [name=value] | Name = [q1] [q2] |
Metadata Element [name=value] | DOB = [q3] |
Connector Settings (Manage)
Property Name | Value |
---|---|
Default Site URL | https://YourDomain.sharepoint.com |
Default Document Library | Documents |
Default App Id | YourAppId |
Default App Secret | YourAppSecret |
Default Version | 2010 | 2013 | online |
Taxonomy Term Store Culture | en-US |
Create Missing Terms | true | false |
Default Request Timeout | 1000000 |
Updated 4 months ago