The DocuPhase Forms SharePoint Connector makes 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

Submissions from DocuPhase Forms are posted to the SharePoint Connector using the Doc Action Save to External System wizard. 

On this page

• 1 Connect a Form/Workflow to SharePoint 
  • 1.1 Add a Document Action
  • 1.2 Configure the SharePoint Doc Action
    • 1.2.1 Mapping Multi-Value Controls
  • 1.3 Test the Connector
• 2 Limitations and Troubleshooting
  • 2.1 Special Characters in Filenames

Connect a Form/Workflow to SharePoint 

Add a Document Action

1. You can add a Document Action at the end of your form/workflow or after any workflow step.

   1. Document Action: Go to your form/workflow's Settings tab in the Guided Designer Navigation bar. Click the Document Actions tab.

   2. Activity Document Action: Click the + icon after any workflow step, then click Add Document Action.

2. You will automatically be on the Send Documents sub-tab. Click ADD DOCUMENT ACTION and select Send to External System.
   
   

   Open

   

3. Select either SharePoint Library or SharePoint List from the Select Connector dropdown. The SharePoint Wizard will open.

Configure the SharePoint Doc Action

Apply the following settings.

1. Site - this is your SharePoint base URL, e.g. <company>.sharepoint.com. Setting only the base URL will display libraries/lists in your root site.

   1. To post to a particular site or subsite, use the special URL format {hostname}:/{site-server-relative-url}: e.g. idatix1.sharepoint.com:/sites/frevvo:
      To construct this, start by copying the site URL from SharePoint, e.g. https://idatix1.sharepoint.com/sites/frevvo. Then, add a colon after the ‘.com’ and after the site name. Remove the https:// protocol.

2. Libraries Only: Optionally, identify a folder with a forward slash and the folder name or a template that will resolve to the folder name at run-time, e.g. /Demo or /{Department}. The folder name is not validated at design-time.

   1. If you enter (or a template resolves to) a folder name that does not exist yet in SharePoint, the folder will be created in the library specified.

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

4. Libraries Only: Check the types of file(s) 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 submission XML document

   3. Attachments - include attachments uploaded to your forms/workflows.

   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. 

5. Add Metadata. Map data, such as 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 that are available (i.e. not hidden nor read only).

   3. 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. Use the repeat separator 'json'. Example: {json|Items}

Test the Connector

When finished, Save your form/workflow.

Here are examples of a configured Library and List.

Run your form/workflow and submit. Go to your SharePoint site to view the results.

Limitations and Troubleshooting

1. You may only post metadata (not documents) to Lists. This is a limitation of the Microsoft Graph API.

2. Doc Action Failure notifications are sent whenever the documents/data cannot be posted to SharePoint. Common causes are:

   1. Your Client Secret expired. To resolve:

      1. Follow the steps in this documentation to login as the Azure admin and generate a new Client Secret.

      2. Login as the DocuPhase Forms tenant admin, go to Manage Connectors, and edit the SharePoint Connector. Paste the new secret value and save.

      3. Resubmit any failed submissions (Note - ALL document actions will run again upon resubmission.)

   2. Your filename or folder name contains special characters that are not allowed.

      1. View the submission.xml to determine the value any templates used in file/folder names resolved to. If you note a special character, this could be the cause. Edit the form, remove the character, and resubmit.

   3. There may be other causes. On Premise customers can review the log files to see more error details. Cloud customers, please contact support@frevvo.com and include the date/time of the failed submission, the exact error shown, the form/workflow .zip file and the submission.xml for the failed submission.

3. We document that the Sites.ReadWriteAll ‘application’ api permission be provided. That permission should allow listing all sites (not just public). You can give more granular access to the application to specific sites and then use the Sites.Selected ‘application’ api permission.

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 PDF filename contains special characters (either hard-coded, from the form/workflow name, or from the resolution of any templates used), the PDF will not post to SharePoint, and will generate an HTTP 400 Bad Request error in the DocuPhase Forms submission table. 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.

< (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)