Create and configure models

Models are powerful tools that provide connections to external systems, allowing the builder to pull data into the page. However, models follow rules that govern how they can be connected to data objects or entities. It's important to follow these rules when creating models:

  • You can connect any individual model to only one object . For example, a model can be connected to the Account object in Salesforce.
  • You can create one—or more—models for each page, and each model can connect to entirely different objects.
  • You can connect to the same object using multiple models—allowing you to display different records with conditions on the same page. For example:
    • You may have one model on an account object that retrieves only some information about accounts, and displays the data in a Table at page load.
    • You may have another model pull in specific internal account information (such as the account owner ID, last time modified, modified by whom, etc.). Components in a "More about the Account" modal use this modal, which only displays when the user chooses to open it. Because this model doesn't load with the page, this streamlines the initial page load.

Jump to:

Create a model

You can create as many models as the application needs—even multiple models that point to the same external system.

  1. Click Models in the Elements panel.

  2. Click the Add a model.

  3. Fill out the model's basic properties:

    • Under Model Id, give the model a practical name, one that is distinctive enough to distinguish it from others on the page.

      Note:  This Model ID is not visible to end users. Use Model description for additional details.

Model name best practices

  • Use alphanumeric characters: SalesEntity4
  • Do not include spaces between words; use an underscore to represent a space: Opportunity_List_Data
  • When possible, use a name that indicate the model's function: ContactDetail_Record or AccountNameSource_forCustomfilter
  • If you are creating more than one model from the connection, be sure to label them accordingly: Account1 , Account2 , Account3

To connect models to an external system, you must first set up a connection to that system. This is done from the Connections screen in the Nintex Apps navigation bar.

There are a series of necessary choices to hone in on the exact content you want to pull into the model:

  1. Select the Nintex Apps connection for the desired external system. If using the model to store temporary data at runtime, select the UI-only connection.

    Note: UI-only models are unique: they do not connect to any external system. These models can store temporary values at runtime. UI-only models are commonly used for variables that power interactive elements in the user interface or for other bits of logic within a page. See UI-only Models and Fields to learn more.

  2. Next, use the dropdown next to Object or Entity to select the specific object within the system to pull the content from.
  3. Finally, if the connector supports it, select whether the model should function as a basic model—retrieving individual records—or an aggregate model —aggregating multiple records and grouping them into fewer rows.

Customize a model

Customize how the model behaves by using model properties, fields, conditions, and actions.

  • Model properties control essential model behaviors, like which object to query.
  • Fields specify which record attributes are available in the model.
  • Model conditions limit or filter the specific records that are pulled into the model.
  • Model actions trigger action flows that run automatically when model-level events occurs.

Note:  Depending upon the choices made, these options may impact page load times and performance.

Adjust the properties

Model properties —found in the Properties panel—determine the model's behaviors. Properties that are available vary by connector. To learn about the properties available for a specific connector, locate that connector's topic in the Connector section.

UI-only models are unique. They do not connect to any external system. A model using this type of connector can store temporary values at runtime, but it does not save that data to any external system. UI-only models are commonly used for variables that power interactive elements in the user interface or for other bits of logic within a page. See UI-only Models and Fields to learn more.

Model fields

Each model is connected to an external system—and specifically, to a particular object in that external system. Most external connections include fields that are accessible to the model. By selecting which of those available fields to add to the model, you specify the data or content to be included and avoid including extraneous data or content that you don't need.

There are several ways to add fields to a model.

  1. In the Elements panel, click on the desired model.
  2. Below the model name, click Data. Nintex Apps opens a list of available fields.
    • Check a field to add it to the model.
      • Uncheck a field to remove it from the model.
    • The fields selected are added to the model's fields list in the order in which they are selected. They are also listed under the Selected Fields tab.

In addition to the fields available in the external object, you may also be able to access related fields—fields that are located on another object, but have a relationship to this object. These are also known as reference fields.

  1. Click next to any field displaying that icon. A new field list opens.
  2. Check the boxes next to the fields that you would like to add to the model from the related object.

The fields selected are added to the model's fields list in the order in which they are selected. They are also listed under the Selected Fields tab. A prefix indicates the name of the associated object, for example: Owner.Address is an address field from the Owner object.

Note:  To navigate back to the field list for the main object, click the model's name in the Properties pane.

Similar to related fields, you can add fields from child relationship objects by clicking the Child Relationships tab in the Properties pane. Child relationships refer to objects that are linked in a way that is often described as a parent-child relationship. Some values in the parent object draw their data from values in the child object.

Data components, such as Table, Form, or List are used to display model fields to end users. You can add fields to these components to include fields from the model. When you add a field to a component, it’s also added to the model’s field list.

  1. Click Components in the Elements panel. This displays the components list.
  2. Drag and drop a Table, Form, or List component onto the page.
  3. In the Properties pane:
    • Model: Select the model you want to link to the component. The last modified model is selected by default.
  4. Click Add fields on the page.

    • To add an existing model field: Select a field and click OK.

      Note:  Use the Search bar to find fields quickly.

    • To add a field that has not yet been added to the model: Turn on the Display all object fields toggle. This displays all available object fields. Select a field and click OK.

  5. To reorder fields in a component, drag and drop them to change their position within the component.

  1. Click Models in the Elements panel.

  2. Select the model you want to view. The Data tab displays the list of available fields. Fields that are already added to the model appear selected.

  3. To add more fields, select the ones you want to include.

  4. Click Save.

Manage models

Click, drag, and drop models to reposition them within the Elements panel.

Note:  Model order matters: Models load in the order they are listed in the models list with models at the top loading first. If you have models that are dependent on another model for data, those models must load after their primary models.

  1. Click Models in the Elements panel. This displays the models list.
  2. Click More options > Create Form next to the model you want to use. This adds a Form below the component currently selected in the canvas and includes all fields added to the model.

For more information, see Form.

  1. Click Models in the Elements panel. This displays the models list.
  2. Click More options > Create Table next to the model you want to use. This adds a Table below the component currently selected in the canvas and includes all fields added to the model.

For more information, see Table.

Duplicating makes an exact copy of the model (including properties, fields, conditions, and actions). This is useful when you have a model that you want to duplicate and revise, without affecting the original model.

  1. Click Models in the Elements panel. This displays the models list.
  2. Click More options > Duplicate next to the model you want to duplicate.

The duplicate appears at the bottom of the models list. Duplicated models default to the name of the original model with a "1" appended. For clarity, remember to assign duplicated models a unique name to help distinguish between it and the original model.

    Important:  Deleting a model also deletes the components that are attached to that model.

  1. Click Models in the Elements panel. This displays the models list.
  2. Click More options > Delete next to the model you want to delete.
  3. Click OK. The model and associated components are removed from the page.

Dependent and principal models

Models can only go one “layer” deep within a response returned by a connection to provide rows to components. But by using another model—a dependent model—nested array data can be accessed as rows.

A dependent model is used to access data within array fields and child relationships on the object of a principal model. The principal model is the model containing the array or relationship a dependent model is made from. Dependent models appear nested in a tree-like visual beneath their principal model in the Models tab.

A dependent model may also be the principal model for a further nested dependent model. The maximum dependent model "depth," the amount of nested data that can be accessed, varies by connector.

Consider this example response detailing an account record, with contacts provided as an array field on that account:

Copy 
{
                    "name": "Example business"
                    "industry": "Technology"
                    "contacts": [
                        {
                            "name": "Alan",
                            "preferredComms": "email"
                        },
                        {
                            "name": "Alice",
                            "preferredComms": "phone"
                        },
                        ]
                    }
 

A typical model could only access the name and industry fields shown above. But by creating a dependent model on the contacts array, the additional records can be used within the page.

Dependent models can be used much like any other model—with data, condition, and model action options all available. However, these models are “dependent” on the data within the principal model, only retrieving rows from arrays within the principal. This is because dependent models rely on the network requests of the principal model, so using them does not require additional network traffic.

Because of this, dependent models cannot be queried independently of their principal models. Anytime a principal model is queried, it updates the available rows within the dependent model. In the same way, If you require only certain data from the dependent model appear, consider using conditions.

Context and dependent models

Because dependent models are used to retrieve related details about a particular record, they're often used within context containers with context conditions. This allows the mapping of a unique identifier (typically a field like Id) on the dependent model's rows to a principal model row, ensuring the proper related details are displayed.

To learn more about context containers, see Context.

Manage dependent models

To create dependent models:

  1. Click the model containing the array or child relationship.

  2. Click the Data tab.

  3. Click Fields.

  4. Click Arrays.

  5. Next to the array you wish to include, click Create dependent model.

  • If the dependent model is attached to an array of objects, then that object's keys are represented as fields.

  • If the dependent model is attached to an array of other data types (like strings), then a field named “Field” is automatically generated, with the array’s values used as the value for that field.

  • The $Parent reference field points back to the parent record in the principal model, providing a way to display information about the parent record within a component attached to the dependent model.

Once created, dependent models can be edited and deleted like any other model.

Dependent model templates

Dependent model templates are not available for all connectors.

Dependent model templates are ways to display certain fields from the associated records in a single “field” within a component. Each associated record is iterated through, and the text and fields (added as merge variables) added appear for each row.

To add a dependent template, click Add fields > Dependent model template.

Once the template is added you can adjust it in a few ways.

  • Click Insert fields to open a modal where you select specific fields.
  • Manually write the template within the Template property. You can expand this input into a larger workspace by clicking Expand , where you can also click Insert fields.

Best practices

  • When creating models, consider both the data users need to access and the experience you want to offer those users.

  • Model order matters: Models load in the order they're arranged in the models list: models at the top of the list load first. When a model is dependent on another for data, ensure that dependent model loads after the primary model. If necessary, re-order the models.

  • If much data is needed from a particular object, consider creating different copies of the model for particular components or usage on the page.

  • Set a Max # of records to a smaller number: Generally, users only really need to see around 10 records at a time; more records may present too much information to process, and in many cases they can load more records using pagination options.

  • Uncheck "Query on page load" to load models only when needed. Unchecking this property allows components and user action to determine when model data is loaded. This prevents all of the page's models from loading at the same time during the initial page load, which is especially valuable for pages with numerous models.

  • Don't specify Fields to order records by. If you need to use this feature, only specify indexed fields. Ordering by a non-indexed field will make the page run slower.

    Note:  Some databases support the creation of indexes for fields. To determine if the database you are using supports field indexing, see the database's documentation.

Properties

Important: 
  • Not all model properties listed below will be available for all connectors. If you do not see a property listed here in the Page Designer, it may not be supported by your connector. These properties are detailed in the respective connector topics. For more information, see Connectors.

  • Model Id: The unique name used by components to reference this model. Each model must have a unique name within one Nintex Apps page. If other pages are included within that page using the Page Include component or dependent pages, then the models in those pages must also have unique names.

  • Model description: Description of the model.

  • Connection: The connection that the model uses to access records.

  • Object / Entity: Determines the data object used to retrieve data. The label for this property may vary depending on the connector, but all labels refer to the same functionality.

    • External Object Name
    • Model Entity
    • Salesforce Object Name

  • Model behavior: Some connections allow builders to select a specific model behavior type. The following options are available:

    • Basic: The default Nintex Apps model.
    • Aggregate: A model that collects, groups, and summarizes multiple data records into a single end result, such as a sum or a count. For more information, see Aggregate models.
    • Read-only: (REST connections) A model that can query data but cannot create, update, or delete data.
    • Read/Write: (REST connections) A model that can use multiple connection URLs for different data operations.

  • Query on page load: To query data when a page loads, turn on the toggle. When turned off, no data rows are loaded into the model on initial page load. In this case, you can use the model to create new records or load later using an action flow such as opening it in Drawers or Modals.

  • Allow page render before query completes: (Available only if the Query on page load toggle is turned on.) Determines whether Nintex Apps must finish loading the metadata for the model before rendering the Nintex Apps page. By default, Nintex Apps loads metadata for every model before rendering a page, even those without visible UI components. If a model includes a picklist with a large number of values, it can increase page load time, especially when multiple models are used on the same page. Use this property to prioritize important models so users see key data and UI elements sooner.

    • When turned off, the model is treated as synchronous and its query must complete before the page renders.

    • When turned on, the model is treated as asynchronous and the page can render before the query finishes.

      Note: This model property is unavailable for server-side models.

  • Max # of records (limit): Determines the maximum number of records the model can retrieve when it is queried. A lower value improves page load performance but limits the amount of data available on the page.

  • Fields to order records by: Determines how records are sorted in the model using a field name and a sort command.

    To order records:

    1. Click Add fields. For more information, see Model fields.

    2. Select fields to sort by.
    3. Click Apply.
    4. Choose one of the following commands to sort each field:
      • Ascending: Records with higher alphabetical or numerical values appear at the bottom of the record list. If no sort option is specified, ascending order (ASC) is used by default.
      • Descending: Records with higher alphabetical or numerical values appear at the top of the record list. You can sort by multiple fields, and the model applies each sort condition in the order listed.

        • For example, to sort a model's rows alphabetically in descending order by the Name field, type "Name DESC".

    • Note: If used on a Salesforce connection model, this property supports the NULLS FIRST and NULLS LAST syntax.

    If a model's connection supports a limited number of sort statements, a sort limit is enforced. When the limit is reached, the oldest sort statement is rolled off to make room for each newly added sort statement.

  • Create default row if model has none: To automatically create a new record when no records exist in the model on page load, turn on the toggle. This option is useful for Create New Record pages.

  • Prevent users from leaving page if this model has unsaved changes: To display a warning dialog when users attempt to leave the page with unsaved changes in a model, turn on the toggle. When turned off, users can leave the page without a warning and may lose unsaved changes.

  • Model label: If the model’s selected object does not include a singular label, such as Account, use this property to specify one. If the connection already defines a label for the object, this property has no effect. This property corresponds to the {{Model.label}} merge variable for the model.

  • Model plural label: If the model’s selected object does not include a plural label, such as Accounts, use this property to specify one. If the connection already defines a label for the object, this property has no effect. This property corresponds to the {{Model.labelPlural}} merge variable for the model. It commonly appears in paginated components such as Table or Deck, and in page title components.

  • Defer rendering: To load specified fields asynchronously, turn on the toggle. When turned on, fields specified by the connector or in the Fields to defer property load after other fields. Other fields in the model can load and display in components as soon as they are available. Deferred fields display placeholder text while loading and do not block other fields from rendering. This option is useful for fields with longer load times, such as image fields or other binary files.

    Note: Some connectors support deferred fields, while others do not. If a connector does not support this feature, the Fields to defer property will not be available.

  • Fields to defer: (Available only when the Defer rendering toggle is turned on.) Available for some connectors, this property determines which fields load asynchronously.

  • Request data in the same transfer as other models: By default, if the connection supports it, all models are requested together and merged by the data server. To request this model separately, turn off the toggle.