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.



Default Credentials or Authentication Mode During Setup

The setup process initially configures SmartIQ for Forms Authentication (username/password access) using default credentials. You will be asked to change these credentials on initial login. It is best practice to complete the setup and test the sites using this configuration before attempting to change authentication mode. This is to make it easier to configure permissions and groups using the default administrator account that may be required for another authentication mode. For more information, refer to Run Installer.

Before Adding Manage

It is recommended that you test your application and license before and after adding the produce application to ensure that they are working as intended. For more information, refer to Adding the Manage Application.

Load Balancing

Best practice is to build your solutions within the Development environments first, before configuration of load balancing. Minimum server specifications are suggested for your initial Dev environment setup and should be scaled up depending on usage and requirements of the solution, as there are many factors that can impact these requirements. For more information, refer to Load Balancing Considerations and Max Recommendations.

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 SendGrid Settings in SMTP.

Azure PaaS

For Azure environments, refer to Best Practice for Azure App Service and Best Practice for Azure SQL Database.

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


Parameters are separated by commas and for best practice spaces should be inserted after commas to avoid issues for those using international cultures.


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


Refer to Placeholders - Best Practices

Communication Templates

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

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.


Customize the displayed columns to limit the data and show only the necessary columns. This helps to improve the user’s experience.


Use filters like date range or user group filters to decrease the amount of data fetched by SmartIQ for a faster experience.

Response Metadata Fields

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


Instead of a data grid, use a drop-down data type to trigger a postback and get the referenced field value.

Fragment Portions

SmartIQ does not recommended using Fragment portions in a dashboard.

Answer Files

SmartIQ 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 Refresh

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



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

Extension Development

  • Connection String should be configured in the Manage > Settings > Connector Settings and not in the action, unless you want to override the default connection string configured in Manage.
  • It is best practice to code Action Extensions so that they target the processing of the data provided by SmartIQ or return a User Interface but not both.
    Usually, in situations where both processing and a UI is required, separate Actions are used.
  • Action Inputs and Outputs are identified by a GUID and it is best practice to declare this GUID as a global variable.