Microsoft SharePoint Connector

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 Infiniti has been developed by Intelledox to provide an integrated experience for customers looking for end to end document lifecycle management, leveraging the powerful e-forms and document creation of Infiniti and the content management and publishing capabilities of SharePoint.

Additional information on Microsoft SharePoint can be found here: https://support.office.com/en-us/article/what-is-sharepoint-97b915e6-651b-43b2-827d-fb25777f446f

Connector Components

Action

• Save to Document Library Action
• Save to List Action
• SharePoint Download Feature

Data Source

• SharePoint Data Source Provider

Features

• Save documents to SharePoint, including documents generated by Infiniti 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.

Version History

Version 3.0 (released November 2019)

• Conversion to Intelledox Platform Extension.
• Debug Mode replaced with Troubleshooting Mode for published project.

Version 2.6 (released August 2018)

• FolderPath can be a connector setting for datasource and not just filter
• Document List object type added
• SharePoint download handler added with encryption
• Handler for UserAgent added
• Error with authentication fixed
• Connector settings no longer deleted in Register

Version 2.4 (released September 2017)

• Fixed issue where auto check-out not working from a sub-folder

Version 2.3 (released April 2017)

• Ability create managed metadata terms if not found
• Datasource connectors settings bug fixed

Version 2.2 (released August 2016)

• Support for SharePoint Lists
• Fix to handle missing, hidden or sealed fields

Version 2.1 (released August 2015)

• Added SharePoint datasource
• Added Save List Action
• Added ‘Debug Mode’ connector setting to provide verbose action messages in the Management screen.
• Fixed bug where document check-in failed when mandatory metadata not set.
• Fixed bug when SharePoint library name is changed an error occurs saving a document.

Version 2.0 (released 22 May 2015)

• Renamed from ‘SharePoint Action Provider’ to ‘Microsoft SharePoint Connector’ to reflect the significant changes, and to better fit with the connector’s future roadmap.
• Rewritten to use the latest .NET object model for SharePoint (CSOM), rather than the deprecated SOAP web services.
• Added capability to set Managed Metadata for uploaded documents based on a Taxonomy Term Store. Note: Currently this feature is only available for SharePoint 2013 or SharePoint Online or later.
• Added automatic check-out for documents being updated, if required based on the library settings.

Version 1.0 (released 15 April 2013)

• Initial release

🚧

Licensing

Note that you must have a valid license key of the Microsoft SharePoint Connector for the connector to function. If you don’t have a license key, contact your Intelledox representative.

Installation Requirements

Before installing this extension you must consider the following requirements:

• You must have administrator/elevated permissions to the Infiniti web server, including the ability to copy and replace files in the Infiniti installation folder. This is usually c:\inetpub\wwwroot\infiniti however may vary from system to system.
• The Infiniti web server must have the ability to connect to the required SharePoint server, or to SharePoint Online.
• You must have an appropriate SharePoint ‘service account’ including the credentials to use for authentication with SharePoint. See SharePoint Service Account below for more details.
• You must have the following installation files:
• Microsoft.SharePoint.Client.dll
• Microsoft.SharePoint.Client.Runtime.dll
• Microsoft.SharePoint.Client.Taxonomy.dll
• MicrosoftSharePointConnector.dll
• SharePointDownloadHandler.ashx
• Ensure you have a compatible version of the connector with your current Infiniti system (Connector and Infiniti should match versions)

👍

Remember

Changes to the configuration may cause interruptions to users in forms.
Before installing this Connector in a production Infiniti environment, ensure the environment is backed up.
It is recommended that this installation is tested in a non-production environment first, and installed during scheduled downtime.

SharePoint Service Account

This connector uses 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.

Installation and Configuration

Use the instructions below to install the connector. If you are upgrading the extension from a previous version, refer to the section Upgrading the connector below.

Note that [Infiniti Produce Path] refers to the installation path on the web server running Infiniti, where the Produce site has been installed. By default this is c:\inetpub\wwwroot\infiniti\produce however may vary from environment to environment. Equally, [Infiniti Manage Path] refers to where the Manage site has been installed, and [IntelledoxScheduler Path] refers to the where the Intelledox Scheduler service has been installed.

How to install the Connector

1. If you already have a version of the SharePoint Connector installed, make sure you have a back-up of the existing connector files to make it easier to roll back if necessary.
2. On the web server hosting Infiniti, copy the connector DLL files to both Produce\bin and Manage\bin folders (e.g. c:\inetpub\wwwroot\Infiniti\Produce\bin and c:\inetpub\wwwroot\Infiniti\Manage\bin). Overwrite existing files if they already exist (see step 1 regarding back-up).
3. On the web server hosting Infiniti, copy the SharePointDownloadHandler.ashx file into the main Produce website folder (e.g. c:\inetpub\wwwroot\Infiniti\Produce).
4. On the web server, using a text editor such as Notepad add the following to the appsettings.json files for both Manage and Produce in the Extensions section. Note that if this is an upgrade, this line may already exist in the settings files, in which case please skip this step:

"Intelledox.Datasource.LegacyDatasource`1[[MicrosoftSharePointConnector.SharePointDataSource, MicrosoftSharePointConnector]], Intelledox.Datasource"

4. Also add the below into the appsettings.json files as a new section if it doesn’t already exist, otherwise just add the new datasource:

"LegacyDatasources": {
    "MicrosoftSharePointConnector.SharePointDataSource, MicrosoftSharePointConnector": {
      "name":"SharePoint"
    }
  }

5. In Produce only also add to the Extensions section of appsettings.json file the following:

"Intelledox.Action.LegacyAction`1[[MicrosoftSharePointConnector.SaveDocumentAction, MicrosoftSharePointConnector]], Intelledox.Action",    "Intelledox.Action.LegacyAction`1[[MicrosoftSharePointConnector.SaveListAction, MicrosoftSharePointConnector]], Intelledox.Action"

6. Recycle the IIS App Pool to force a reload of the Produce and Manage sites.

Using a web browser, navigate to the Infiniti Produce and Infiniti Manage applications to allow the system to register the Connector and ensure they start without error.

The Microsoft SharePoint Connector should now be installed ready for configuration and usage.

Upgrading the Connector

If your Infiniti environment is already running this connector and you are simply upgrading to a new version, follow the steps in Standard connector upgrade below. If your environment is running the older SharePoint Action Provider, refer to the Upgrading from the SharePoint Action Provider section below. Otherwise, if this is a new installation of the connector refer to Installation and Configuration above.

To determine if your existing environment is running the older SharePoint Action Provider, check the Produce appsettings.json file and see if it contains the following line in the Extensions section:

"Intelledox.Action.LegacyAction`1[[SharePointActionProvider. SharePointAction, SharePointActionProvider]], Intelledox.Action"

This line indicates your environment is running the older provider.

Standard connector upgrade

How to upgrade the connector

1. On the web server hosting Infiniti, copy the connector DLL files to both Produce\bin and Manage\bin folders, overwriting the existing files.
2. Using a web browser, navigate to the Infiniti Produce application to allow the system to register the upgraded action.

Upgrading from the SharePoint Action Provider

The new Microsoft SharePoint Connector has been designed to minimise the impact of upgrading from this older SharePoint Action Provider as possible. While some Connector Settings and Action Attributes have been renamed, and others introduced, your existing configuration in most cases should continue to work after performing this upgrade.
###How to upgrade from the SharePoint Action Provider

1. Delete the following file on the Infiniti web server from the Produce\bin folder
   SharePointActionProvider.dll
2. On the web server hosting Infiniti, copy the connector DLL files to both Produce\bin and Manage\bin folders, overwriting the existing files.
3. On the web server, using a text editor such as Notepad add the following to the appsettings.json files for both Manage and Produce in the Extensions section. Note that if this is an upgrade, this line may already exist in the settings files, in which case please skip this step:

"Intelledox.Datasource.LegacyDatasource`1[[MicrosoftSharePointConnector.SharePointDataSource, MicrosoftSharePointConnector]], Intelledox.Datasource"

Also add the below into the appsettings.json files as a new section:

"LegacyDatasources": {
    "MicrosoftSharePointConnector.SharePointDataSource, MicrosoftSharePointConnector": {
      "name":"SharePoint"
    }
  }

4. In Produce only replace the following line in the Extensions section of appsettings.json file:

"Intelledox.Action.LegacyAction`1[[SharePointActionProvider. SharePointAction, SharePointActionProvider]], Intelledox.Action"

with

"Intelledox.Action.LegacyAction`1[[MicrosoftSharePointConnector.SaveDocumentAction, MicrosoftSharePointConnector]], Intelledox.Action",    "Intelledox.Action.LegacyAction`1[[MicrosoftSharePointConnector.SaveListAction, MicrosoftSharePointConnector]], Intelledox.Action"

5. Using a web browser, navigate to the Infiniti Produce application to allow the system to register the new action.
   The older SharePoint Action Provider should now be upgraded to the Microsoft SharePoint Connector.

Installation to Intelledox Scheduler

If the target environment is using the Intelledox Scheduler, it is best practice to always install connectors and accelerators to this service at the same time as the installation in Infiniti Produce application. If this is not installed to the Intelledox Scheduler there may be errors if any projects are executed from the scheduler that refers to this connector.

To install any connector to the Intelledox Scheduler, follow the instructions in this guide as they apply to Infiniti Produce, except instead of [Infiniti Produce Path] use [IntelledoxScheduler Path], noting that there is no ‘bin’ folder in this path so all files should be copied into the root of this path. For example, consider the path:
c:\inetpub\wwwroot\infiniti\produce\bin

To install to the Intelledox Scheduler, simply use this path:

c:\inetpub\wwwroot\infiniti\intelledoxscheduler

Also, you must apply the same configuration changes as instructed for the Produce appsettings.json file.

Configuring the connector settings

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

How to view or modify connector settings

1. In a web browser, navigate to the Infiniti Manage application and log in.
2. Navigate to Settings in the Administration menu group, and then click the Connector Settings button at the top of the page.
3. Using the Connector drop-down list, select the 'SharePoint’ option.
4. Review and update the settings as required. The settings are described in the table below.
5. Click the Save button at the top of the page.

🚧

There are no mandatory connector settings, however if not set within the action an error may occur. Note that 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.

SharePoint Versions

This connector is primarily designed to work with SharePoint 2010, SharePoint 2013 & 2016 and SharePoint Online. It uses the .NET client-side object model (CSOM) to communicate with the SharePoint server.
The Default Version connector setting, and the Version action attribute helps the connector determine behaviour in the following ways:

• Authentication mode – If the version is set to ‘online’, the connector will authenticate using a special SharePoint Online credential type and will not use the Domain setting.
  If set to any other version, the connector will connect using one of the following methods:
• Anonymous authentication (if no user information provided)
• Forms authentication (username and password provided, but no domain)
• Windows authentication (username, password and domain are provided)
• Document upload technique – If the version is set to ‘online’ or ‘2013’, the connector is able to pass larger document files to SharePoint using a content stream attribute within the object model.
  For previous versions the content binary is passed in directly and will be limited in size based on the configuration of the SharePoint server’s request size limit, which by default is 2MB to avoid potential performance degradation.
• For SharePoint 2016+ use the 2013 version flag value.

📘

Note

Connector Settings are applied system-wide, for specific scenarios where it is required to use different credentials, please specify them in Design or directly in the Data Source configuration.

Save to Document Library Action

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

Features include:

• Save documents to SharePoint, including documents generated by Infiniti 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.

📘

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

📘

For backward compatibility with the old SharePoint Action Provider, 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. Infiniti supports both standard metadata site columns, as well as managed metadata.
There are two ways this can be configured:

• Project Level Metadata
  In Design, click Actions -> Set 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 a result, as described below. If the result is a failure, an error message will be available in Infiniti Manage on the Management screen.
Action results:

• Success – the action ran successfully without error.
• Fail – the action ran and returned an error.
• Not Run – if conditions set on the action prevented it from running, it will return this result.
  Action results can be used to control logic in subsequent actions. For example, an email action can be configured to execute in the event of failure.

Debug Mode

If Debug Mode is enabled in the connector settings, 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. Infiniti 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 owning user 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’.

Save to List Action

The List Action has been designed to save metadata generated by Infiniti 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.

📘

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. Infiniti supports both standard metadata site columns, as well as managed metadata.
There are two ways this can be configured:

• Project Level Metadata
  In Design, click Actions -> Set 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 List Action will return a result, as described below. If the result is a failure, an error message will be available in Infiniti Manage on the Management screen.
Action results:

• Success – the action ran successfully without error.
• Fail – the action ran and returned an error.
• Not Run – if conditions set on the action prevented it from running, it will return this result.
  Action results can be used to control logic in subsequent actions. For example, an email action can be configured to execute in the event of failure.

Debug Mode

If Debug Mode is enabled in the connector settings, 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. Infiniti 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.

SharePoint Data Source Provider

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

Usage and configuration

Configure the Connector

1. In Manage, navigate to Settings and click ‘Connector Settings’.
2. Select ‘SharePoint’ from the list of connectors.
3. Provide enough information to connect to your SharePoint environment, including Site URL and credentials. This is used by the download handler to connect, rather than the data source’s connection information. See Configuring the connector settings above.

Create a new data source

1. In Manage, create a new Data Source and select “SharePoint” as the Connection Type.
2. Configure the settings as per the table below:

🚧

The datasource is restricted to a single SharePoint site only. If you have multiple sites eg: https://my.sharepoint.com and https://my.sharepoint.com/internal https://my.sharepoint.com/clients etc, you will need to create a separate datasource for each site and specify the correct siteurl in the connection string for each site.

3. Click on ‘Save’ button.
4. Click on ‘Test Connection’ to ensure that all the data provided is ok.

Create a Data Object

1. Click Data Objects and then New Data Object.
2. Select ‘List’ from the Object Type drop-down.

3. 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).
4. Chose the list you want to access.
5. Provide an appropriate Display Name for the chosen List.
6. Click Save.
7. In Available Filter Fields, click Add All.

Add data source in Design

1. In Design, open your project and place a new Data question where you’d like to load the documents.
2. Configure the Data question to use the SharePoint connection and Data Object created in the steps above.
3. Use the data source as required to display a list, data grid, drop-down or to create a data-driven repeating section, depending on the UI requirements of your form project.
4. Save your project and test that the list is loading and you can view the information as expected.
   Note that because this uses a data source to retrieve filterable data for each list, you can set up your interface in Design using any of the valid techniques for working with data sources. This provides a great deal of flexibility, including the ability to navigate lists of documents. The download feature can then be used to access resources as needed.

SharePoint Download Feature

The SharePoint Connector now includes a new data object type for retrieving documents from a document library or sub-folder, in a manner that can be listed and made available for download.
This feature is intended to provide form designers to provide their form users with access to relevant SharePoint resources without those end users having direct access to the SharePoint environment. For example, for external facing portals where users are not part of the organization’s domain.
The Documents data object type retrieves file information for each file in a target folder, and includes a specially generated download URL that can be used to provide a link or button to download that file. The link is user-specific so that it can’t be shared to other Infiniti users, unless both share the same account (e.g. Guest users).

Usage and configuration

Add a Documents data object to your SharePoint Data Source

1. Create a SharePoint Data Source in Manage. See SharePoint Data Source Provider above
2. Click Data Objects and then New Data Object.
3. Select ‘Documents’ from the Object Type drop-down.
4. Provide an appropriate Data Object Name, and Display Name, e.g. ‘Documents’.
5. Click Save.
6. In Available Filter Fields, click Add All.

Add data source in Design

1. In Design, open your project and place a new Data question where you’d like to load the documents.
2. Configure the Data question to use the SharePoint connection and Data Object created in the steps above.
3. Configure the Data question’s filter value for FolderPath to the document library name and any sub-folders to locate the required list of files. For example, ‘Documents/example’ will retrieve documents from the ‘example’ folder within the ‘Documents’ document library.
4. Use the data source as required to display a list, data grid, drop-down or to create a data-driven repeating section, depending on the UI requirements of your form project.
5. Use the DownloadUrl field returned by the data source to construct an appropriate link for users to download desired files. For example, it could be referenced in the href part of an anchor tag:

<a href="[q1.DownloadUrl]">Download</a>