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.

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)