Overview

The DocuPhase Forms SharePoint Connector and Send to SharePoint document action wizard make it easy to create forms and approval workflows that validate information, route for signatures as required and save the data and documents to a secure SharePoint website. The Connector was designed to integrate with Office 365 SharePoint Online.

Open

Open

The SharePoint Connector allows you to save the form/workflow documents and metadata to a SharePoint document library and/or a list item. With point and click tools, designers can select the SharePoint destination and map form/workflow control values to the SharePoint metadata columns.

The DocuPhase Forms SharePoint wizard guides you through connecting your forms/workflows to SharePoint.

Choose your Configuration Scenario

First, choose which configuration scenario is best for you. Follow the links for detailed instructions.

Cloud Customers Connecting to SharePoint Online

This configuration has been certified by DocuPhase Forms. Follow these steps:

1. Configure DocuPhase Forms as a SharePoint Add-in

2. Configure SharePoint for your DocuPhase Forms tenant.

3. Connect your Forms/Workflows using the SharePoint wizard.

On Premise Customers connecting to SharePoint Online

This configuration has been certified by DocuPhase Forms. Follow these steps:

1. Configure DocuPhase Forms as a SharePoint Add-in

2. Download the SharePoint Connector. Rename it to sharepoint.war. Copy it to the <frevvo-home>\tomcat\webapps folder

3. Configure SharePoint for your DocuPhase Forms tenant

4. Connect your Forms/Workflows using the SharePoint wizard.

On Premise customers using SharePoint On-premise

This configuration is supported but not certified.

1. Customers using SharePoint On-premise also need an Office 365 SharePoint Online account. This is necessary to obtain an authorization token. There is no data transfer from SharePoint On-premise to SharePoint Online.

2. Customers are responsible for configuring the On-premise installation and the integration with SharePoint Online.

3. The On-premise version of SharePoint must be version 2013+.

4. Refer to this Microsoft website for information about how to use Office 365 to allow DocuPhase Forms to authenticate.

DocuPhase Forms Cloud customers connecting to SharePoint On-premise

This configuration is supported but considered unlikely as it requires your On-premise SharePoint to be exposed to the Cloud. Customers are responsible for configuring the On-premise installation and its exposure to the Cloud. 

Configuring the SharePoint Connector

Step 1 - Configure DocuPhase Forms as a SharePoint App (Add-in)

DocuPhase Forms must be added as a SharePoint provider-hosted add-in by your SharePoint Global Administrator in the Sharepoint admin center. The URL will have -admin after the domain name, e.g. https://mycompany-admin.sharepoint.com/.

Create the App

1. Navigate to https://<yourSharePointSite>-admin.sharepoint.com/_layouts/15/appregnew.aspx
   
   

2. Click Generate on Client ID and Client Secret. Copy the Client Id and client Secret and save them to a text file. You will need to add these values when configuring your tenant for SharePoint.

3. Enter a Title. The Title can be anything that can differentiate your DocuPhase Forms SharePoint application from other applications

4. Enter the App Domain. The app domain field should be the DocuPhase Forms server domain name plus the DocuPhase Forms SSL port. It should be the same <server>:<port> as the redirect URL.

   1. Cloud customers: app.frevvo.com:443

   2. On Premise customers: <server>:8443 (or your <server>:<port> if not using the default)

5. Enter the Redirect URI. The Redirect URI for DocuPhase Forms is shown below where the <server>:<port> is the same host and port in the URL used to access DocuPhase Forms.
   Redirect URI

   https://<server>:<port>/frevvo/web/sharepoint/token

   1. Cloud customers: app.frevvo.com:443

   2. On Premise customers: <server>:8443 (or your <server>:<port> if not using the default)

   3. Remember SharePoint only allows https.

6. Click Create. You will see a message such as "The app identifier has been successfully created." Copy the information on this screen and save it to a text file. You will need these values for the next step.

Grant the App Permissions

1. Navigate to https://<yourSharePointSite>-admin.sharepoint.com/_layouts/15/appinv.aspx.
   
   
   

2. In the App ID field, paste the Client ID you copied earlier. Click Lookup. 

3. The Title, App Domain, and Redirect URI fields should get filled with the information you entered in the last step.

4. Enter the Permission Request XML. Copy/paste this xml into the Permission Request XML box.

   <AppPermissionRequests AllowAppOnlyPolicy="true"> <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="Manage" /> </AppPermissionRequests>

5. Click Create. If prompted, click Trust It.
   If you see an error that you do not have permission to trust this app, please make sure you are logged in as a global admin the Sharepoint admin center. The URL will have -admin after the domain name, e.g. https://mycompany-admin.sharepoint.com/.

Copy the Realm

To determine the realm for your SharePoint site navigate to https://<yourSharePointSite>-admin.sharepoint.com/_layouts/appprincipals.aspx. Find your registered application in the list and look at the App Identifier column. The unique identifier after the @-sign in the App Identifier is the app realm and must be entered in the Realm field.

Step 2 - Configure the DocuPhase Forms Tenant for SharePoint

Cloud and On Premise customers must configure their DocuPhase Forms tenant to connect to SharePoint as a client. DocuPhase Forms expects that customers will only be integrating with one SharePoint instance for their organization. You will need the SharePoint Client Id and the Client Secret from Step 1.

Follow these steps:

1. Login to DocuPhase Forms as the tenant admin.

2. Click the Edit Tenant link.

3. Expand the SharePoint section.

   1. The Connector URL field can usually be left blank. This field is not necessary if you are using the SharePoint Connector built-in on DocuPhase Forms Cloud or you are an On Premise customer, which are the most common scenarios. This URL is only needed if you are using DocuPhase Forms Cloud but installing the connector locally. Enter the URL where your DocuPhase Forms installation that is configured for SharePoint is located. This URL must use the https protocol. The URL in the Connector URL field will override the connector URL that is specified in the configuration property in the <frevvo-home>\tomcat\conf\frevvo-config.properties file. The default value is shown below:
      frevvo.sharepoint.connector.url=http://localhost:8082/sharepoint

   2. Enter the Client Id and the Client Secret that you saved in Step 1 into the respective fields.
      
      

   3. Enter the SharePoint Domain Name e.g. <Your SharePoint domain name>.sharepoint.com. There is a dot between the SharePoint domain name and sharepoint.com. The SharePoint domain name is what you see in your SharePoint URL, i.e.:

   4. Enter the Realm (copied from SharePoint in the above steps)

4. Click Submit

5. On Premise customers can browse http://<your server:port>/sharepoint/health (replace <your server:port> with your frevvo server:port) to check the status of the connector. If the connector is up and running, you will see { "status" : "UP" }.

6. Proceed to Step 3

Step 3 - Connect Forms and Workflows with the SharePoint wizard

Login and Create Form/Workflow

Log in as a DocuPhase Forms designer user. If you are On Premise DocuPhase Forms connecting to Sharepoint in the cloud, use the URL https://<server>:<SSL port>/frevvo/web/login. Example: https://localhost:8443/frevvo/web/login. Port 8443 is the default. Create your form or workflow with controls that capture the data that you want to store in the columns configured in the Lists and Libraries on your SharePoint site.

Configure Send to SharePoint Document Action

1. Go to Settings mode in the Guided Designer navigation bar.
   

2. Click the Document Actions Tab and the Send Documents sub-tab.
   
   

3. Select the action Send to Sharepoint. If the tenant is not configured for SharePoint, the Send to SharePoint option will not display.
   
   

    

First-time SharePoint Login

You will be redirected to log in to SharePoint or Office 365 if you are logging into your account for the first time. On successful login, you will be asked to grant or deny access for your DocuPhase Forms SharePoint add-in.

Click Trust It to authenticate and grant permission to DocuPhase Forms. You will not see the trust screen on subsequent logins. The wizard will display.

Set up Route(s)

You can set up a single Document Action to write to two places (i.e. SharePoint Library and List). Route 1 will be automatically expanded. Expand Route 2 to add a second destination if desired.

1. Send Snapshot - Select a format for the Snapshot to be saved in SharePoint. The choices are: PDF, PNG or JPEG. PDF is the default. If you are sending attachments to a Sharepoint List, you must enable attachments on the List.
   
   

2. The Site URL is automatically prefilled from the SharePoint tenant configuration. This is the SharePoint site or subsite containing the destination e.g. https://frevvo.sharepoint.com. If you use a site and/or subsite, simply add it to the URL, e.g. https://frevvo.sharepoint.com/sites/Docs/docsub1. This URL must use the https protocol. 

3. Pick a Destination. SharePoint destinations can be a Library (and optionally a Folder), or List. Select Library or List from the Destination Type dropdown.

4. Pick a Library or List from the new dropdown that appears. This dropdown shows all the available Libraries or Lists in your SharePoint site.

   1. If you select a Library, you will also see the Folder field. If you want to send to a subfolder, enter the server relative path of the folder within the library. For example, for folder 'test' in library 'mylib', enter /mylib/test.
      
      

      
      
      

      The folder path may not always match exactly the visible name in the Sharepoint UI. For example, for my Library named 'Documents', the path is actually 'Shared Documents'. You can find the path in the folder's properties.

      1. Go to your Sharepoint site or subsite, and click on the folder where you plan to save your DocuPhase Forms documents.

      1. Click the Info icon (i) in the upper right side to open a properties panel.

      2. Scroll down towards the bottom to the "Path" property. Click the copy icon.

      1. Paste the copied path into a text pad. Copy everything after the domain name (in my case, /sites/Docs/docsub1/Shared%20Documents/TestFolder) and replace the encrypted character(s) as needed e.g. /sites/Docs/docsub1/Shared Documents/TestFolder

      2. Log in to DocuPhase Forms, edit your form and go to Document actions.

      3. If using a subsite, make sure the Site URL includes your subsite, e.g. 

      https://frevvo.sharepoint.com/sites/Docs/docsub1

      1. Choose Library, then pick the correct Library from the dropdown. (If you don't automatically see them, try changing "Library" to "List" and back again; this reconnects the SP connector).

      2. In the Folder field, enter the path you copied from Step 4.

5. Select a Content Type from the dropdown. The wizard automatically pulls the content type choices from your SharePoint site. The Content Type determines the available metadata column names for mapping. For example, if the destination is a List you would see Item as a choice for the Content Type. This means your submission is saved as a new item on your SharePoint list. Document Libraries show Document as the Content Type.

6. Check the types of files to be saved to the selected destination. The choices are:

   1. Snapshot - include a snapshot of your form/workflow in the format selected in the Send Snapshot field

   2. Data - include the DocuPhase Forms XML document (only available when sending to a List)

   3. Attachments - include attachments uploaded to your forms/workflows. In Workflows, when Attachments is selected you will see a list of available upload controls and can choose which to include in your Sharepoint submission. 

   4. Gen Forms(PDF) - this checkbox appears if you have mapped PDFs associated with your form/workflow e.g. W-4 and I-9 filled out by a new employee. In Workflows, when Gen Froms(PDF) is selected you will see a list of available PDFs and can choose which to include in your Sharepoint submission. 

      
      
      

      
      Workflows only:
      
      

7. Add Metadata. Map the Control Names in your form/workflow to the column names in your SharePoint destination.

   1. Click the  blue add icon to add a row.

   2. The wizard will populate the Column Name dropdown with all the columns in the destination

In the Control Name field, you can type static text (not recommended), select one or more control from your form, or a combination of control(s) and static text. To use a control from your form, type an open curly brace and the first few letters of your control name, i.e. {Fir. A list of controls in your form appears. Select the correct one.

Mapping Multi-Value Controls

You can map multi-value controls such as controls inside repeats, table columns, and checkboxes to Sharepoint columns. To map to a single value Sharepoint column, you can use any regular separator, such as a comma, in your repeat template syntax. This results in a single, comma-separated string value in the Sharepoint target column. For example, you can map the Items column in a table to a text column named with the syntax {,|Items}. This results in a single value sent to the target Sharepoint column as a comma-separated string, e.g "Widgets, Wingdings, Whatzits".

You can also map a repeat control to a multi-value (checkbox) Choice column. In this case, you must use a special syntax to send separate values that populate the Sharepoint checkboxes. For a Sharepoint list, use the repeat separator 'json'. 

List: {json|Items}

For a Sharepoint library, use the repeat separator ';#'. 

Library: {;#|Items}

These separators send the control values in an array, which populates the checkboxes in the target Choice column.

Clear Route

If you configure a second Route, clicking the Clear Route button removes the information for Route 2 only.

Save and Test

Click thesave and test icon to save the form/workflow and bring up Test mode popup.

Special Characters in Filenames

If you want to customize the name of the PDF Snapshot saved to SharePoint, make sure you have Save PDF checked. An optional field that is used to name the PDFs displays. You can use templates in this field. For example, if you have a control called EmployeeName in your form, you can type {EmployeeName} into the PDF Name field and the PDF's saved on your SharePoint site will be named {EmployeeName}.pdf.

If you leave the PDF Name property blank, DocuPhase Forms uses the Form/Workflow Name as the pdf file name.

• If the Form/Workflow Name contains special characters, the PDF will not post to SharePoint generating an HTTP 403 status error. To avoid any issues, name your form/workflows using characters that are suitable for filenames and explicitly set the PDF name in the form/workflow using the same standard. Following the POSIX filename standard (A–Z a–z 0–9 . _ - ) will ensure it works.

Special characters in filenames or folder names will cause the submission to be flagged with an error in the DocuPhase Forms submission table. We recommend POSIX naming standards as there are some special characters that are not supported by the connector. 

< (less than)
> (greater than)
: (colon - sometimes works, but is actually NTFS Alternate Data Streams)
" (double quote)
/ (forward slash)
\ (backslash)
| (vertical bar or pipe)
? (question mark)
* (asterisk)

This can happen if you do not name the PDF file, and it defaults to your form/workflow name, if that name has special characters.

Check Submissions on SharePoint

When the form is submitted or the workflow is completed, submission data, metadata, and attachments are uploaded to the specified destination in your SharePoint account. To verify your stored submissions on your SharePoint website:

1. Test your form/workflow by filling in data, adding attachments, and submitting it.

2. Login to your SharePoint account and navigate to the specified destination. The images show submissions saved to a SharePoint list and individual submission data and attachments.
   
   

   
   
   

Using the SharePoint Connector in an Azure SAML Security Manager tenant

At least one designer user that is going to be connecting forms/workflows to SharePoint with the SharePoint Connector#Step3-ConnectFormsandFlowswiththeSharePointwizard must also be a SharePoint user with the correct privileges to provide consent if your tenant is configured with the Azure SAML Security Manager.

Troubleshooting

Some common issues with solutions are listed below.

Doc Post Failure

If the submission doesn't reach your SharePoint website - if DocuPhase Forms does not receive a response back from SharePoint with a status code of 200, you can find information about the error from the DocuPhase Forms submission table.

All tenant admin(s) in your tenant or workflow admin(s) configured for specific workflows will receive a Doc Post Failure notification email to alert them that an issue has occurred. The <server-name> will be provided in the email subject. Check for some of these common issues:

• Special characters in a file name

• Incorrect login information

• Controls used in metadata changed or removed

• SharePoint folder name or metadata column changes

An error in the logs like "Value does not fall within the expected range." suggests you have not set the Content Type. See Set Up Routes for details.

An HTTP 500 error with the error "The list item was saved, but attachments could not be saved because the attachments feature is currently unavailable for this list" in the SharePoint connector logs indicates you are trying to send attachments to a List that does not have attachments enabled. Please enable attachments on the list. 

Max file size

The maximum size for all DocuPhase Forms connectors is set to unlimited. Any size file can be uploaded to DocuPhase Forms and posted to SharePoint.

Determine the version of the SharePoint Connector you are using:

To determine the version of the SharePoint connector you are using:

Browse http://<your server:port>/sharepoint/info  - the version information is returned as shown in the image.

Refresh Token Expired

If your users see an error like "org.springframework.security.oauth2.client.resource.UserRedirectRequiredException: A redirect is required to get the user's approval" when accessing or trying to submit a form, the cause is that your SharePoint Token has expired. The user who owns the SharePoint Account (usually the designer) will need to log in and provide consent to refresh the token. You can learn more in this Microsoft Documentation. Currently, DocuPhase Forms does not provide a way to generate a new refresh token automatically. This feature may be added in a future release. However, until then the SharePoint account user will have to provide consent for a fresh token every 6 months.