HomeGuidesAPILog In

Best Practices



This page compiles and references best practice information for SmartIQ, but is not a comprehensive guide to all best practice information.

Security and Authentication

SAML 2.0

If you need to have multiple methods for authentication, use a provider that supports federated identity management. For more information, refer to SAML 2.0.


If you are using SendGrid, use the API Key method to send SMTP where the username will be apikey and the password will be the generated API Key from SendGrid. For more information, refer to SMTP.

Solution Design

Data Reuse

Where users' data needs to be stored and re-used later, SmartIQ offers a range of options for storage outside the SmartIQ server including the use of external datasources, connectors to storage platforms such as Salesforce or Dynamics, REST based platforms and Amazon and Azure storage.

For Prepare Form and Generate Form APIs best practice is to pass data either using individual values in the values object or supplied data in the data object.

Saved answer files are only useful for a user to repopulate the same version of a project when they are completing it a second time. Using saved answer files on projects that have been modified (different questions, new questions, different conditions, etc) can cause unexpected results and may cause the new project to not load.

External Service Failures

External services can occasionally become unavailable or return error messages. When connecting to third-party services such as DocuSign, SharePoint, or SMTP, it is a good idea to design workflows with retries or appropriate conditions to handle these service failures.

Form Design

FormulasParameters are separated by commas and for best practice spaces should be inserted after commas to avoid issues for those using international cultures.
FragmentsDo not use fragments just to break a project into parts, only use a fragment where the section is going to be reused either in the same project or between different projects. Unnecessary use of fragments will slow a project down and make it harder to export and import.
  • The autocomplete data question display type is only appropriate for data connections that expect a partial search term. For example retrieving all the records that contain the character ‘a’
  • When you make a selection from a result set, the [userEnteredTerm] typed is saved in the answer file. When the project is saved and resumed at a later date, a subsequent call to the data connection is made again, hopefully returning the same result. However, if for any reason the data connection returns different results, previous selections may be lost.
  • In the client app, the question is only enabled in online mode.
  • When using a Default Value, ensure that a Unique Field whose values are unique within the data is selected. For example, use an "ID" field rather than a "First Name" field. Values are matched exactly so avoid data that can change format, such as dates, or ensure that the Default Value can be formatted to match the data with, for example, leading zeros.
PlaceholdersRefer to Placeholders - Best Practices
Communication TemplatesLeave the first Communication Template translation as Default Language. This ensures that if the user’s profile language does not match any of the translations added, they will still receive a communication using the default language.
Formulas and Variables (Broadly, all questions)SmartIQ's calculation engine, which resolves the values of question references within forms, generally expects questions to only reference questions which are "earlier" in the form. For example, questions which are further up in the page/tree order. References that go in the reverse direction (where a question refers to another question which comes after this reference) may work in some cases, but can also be unreliable in terms of updating values. Questions references should look "backward" (i.e. refer only to earlier questions) wherever possible, and "forward" references are not recommended and should be avoided.
CSV data upload to repeating sectionsSmartIQ allows the dynamic upload of data from a CSV file into a repeating section. If utilizing this feature, caution is required. SmartIQ calculation engine will recalculate all questions contained in the repeating section, any dependencies on the repeating section and its questions and also any questions that depend on the repeating section. If the form is designed to use nested or side-by-side repeating sections with dependencies relating to the uploaded data these can result in a non-linear increased time to load (and serious CPU impacts on the server) up to and including full timeouts and application crashes. The load times for each additional row can increase on an exponential or even factorial basis (for nested repeats). This can mean a CSV that loads easily with 10 rows may be very slow with 25 rows and not load at all with 100 rows. If using CSV data upload, best practice is to start designing with an initial set of test data that exceeds the projected maximum row count so any performance issues are identified early in the form design process.
AccessibilitySmartIQ offers customers best practices related to Web Content Accessibility Guidelines (WCAG) through the Web Content Accessibility Guidelines (WCAG) Best Practices Guide. This guide is intended for use by SmartIQ clients who wish to follow the WCAG for business processes built in SmartIQ. The information covered includes how the capabilities of SmartIQ can help companies consider WCAG standards in their solutions and make digital form processes generated by SmartIQ more accessible to individuals who have physical limitations. The examples and features of SmartIQ included in here are intended to help form designers meet the success criteria of WCAG Level A compliance but does not in any way guarantee WCAG compliance certification. According to the Accessibility Guidelines Working Group (AG WG) (formerly the Web Content Accessibility Guidelines Working Group), ‘web content’ generally refers to the information in a web page or web application, including text, images, forms, sounds, etc. For the purposes of SmartIQ, this is the intelligent content generated and sent to the end-user of the SmartIQ interactive form process available in Produce. Web content accessibility compliance and certification is the responsibility of the client. In order to achieve or maintain WCAG compliance, Designers should ensure they are following the guidelines. Please email [email protected] for a copy of the SmartIQ WCAG Best Practices Guide.

Dashboard Design


Dashboards for completing a project process

Use dashboards to launch a project that will have no questions but can have data sources and actions. The dashboards can then display a finish page with the downloadable files ready.

ColumnsCustomize the displayed columns to limit the data and show only the necessary columns. This helps to improve the user’s experience.
FilteringUse filters like date range or user group filters to decrease the amount of data fetched by SmartIQ for a faster experience.
Response Metadata FieldsThe number of response metadata fields will have a significant impact on dashboards.

SmartIQ recommends the following:

Keep the number of response metadata fields low (less than 5).
Use Custom data objects to store additional data for the project, especially anything with personally identifiable information as Response metadata is stored unencrypted.
ReferenceInstead of a data grid, use a drop-down data type to trigger a postback and get the referenced field value.
Fragment PortionsSmartIQ does not recommended using Fragment portions in a dashboard.
Answer FilesSmartIQ recommends doing the following to ensure that workflow answer files; for example, workflows that have not been submitted, are not kept in the system too long. This is because too many answer files can slow down a dashboard when it is loading.
Use a data filter like date range or group filters to decrease the data
Terminate old and abandoned workflows:
Use an escalation on the state to terminate the workflow automatically if the workflow is abandoned after a specific period.
Use the Manage console to terminate all workflows that are no longer needed.
Live RefreshSmartIQ does not recommended using Live Refresh for forms that will be left overnight as this will cause a lot of unexpected database calls and slow down the environment.

For recommended data sizes, refer to Maximum Recommendations.