Note: Nintex Apps data centers are located in West US and Australia (AUS). In-region processing of Nintex Apps data is only available in these regions.

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.

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

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

Certain data components, such as the Table, Form, or List components, are designed to contain and display model fields, making that content accessible to the end user. Because these components rely on model fields for their content, the component itself includes an Add fields button. Adding fields directly to a component also adds them to the model's field list.

  1. Drag and drop a Table, Form, or List component into the page.
  2. In the Properties pane:
    • Model: Select the desired model to link to the component from the drop-down list. (By default, the last model modified will be pre-selected.)

To add fields to component, either:

  1. Click the Add fields button to open the Add fields dialog box, then:

    • To select a field already added to the model: Check a field from the Selected fields tab to add it to the component.

      Note:  Use the Search bar to find fields quickly.

    • To select a field that has not yet been added to a model: Check a field from the All fields tab to add it to the component. The field will also be added to the model's field list.

      • If there is no check box next to a field, click next to the field to add it to the model and make it selectable, then check the field to add it to the component.

  2. Click Apply.

Or you can drag and drop fields into the component from the model's fields listing by grabbing either:

  • a field from the model's field list (below the model's name in the Elements panel, under Fields)
  • a field from the model's field's list in the Properties pane.
Having trouble adding fields to a component?

A component can only accept fields from the model associated with it. When dragging a field into a component, if the component does not display an orange visual indicator for the area where you can drop the field, you may be trying to add a field to a component that is connected to a different model. Ensure that the component's model matches the model you are pulling your fields from.

Reorder fields in a component

Just drag and drop to change the position of fields in a component.

To see a list of the fields currently included in the model, click the model from the Elements panel, then either:

  • Below the model name, click Fields.
  • In the Properties pane, click the Selected Fields tab.

You will see check boxes next to any Fields you added to your model from the Fields list under the Models tab in the Page Designer. If you did not add any fields previous to clicking the model's Field, then no check boxes will appear.

Check the boxes next to any Fields you want to add to your component.

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.

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. In the Elements panel, click Models to open the models list.
  2. Click More options > Duplicate beside the model.

The duplicate appears at the bottom of the model 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. In the Elements panel, click Models to open the models list.
  2. Click More options > Delete beside the model.
  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. Beside 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.

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

Model 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 available for your connector.

Models for some connectors may have unique properties not documented here. These properties are detailed in the topics for those respective connectors.

  • Model ID: The unique name by which components refer to this model. Each model must have a unique name within one Nintex Apps page. If other pages are included within that page —such as through the Page Include component or dependent pages—then the models in those pages must also have unique names.

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

  • Model Object / Entity: The data object to pull data from. The label for this property can vary based on connector, but they all mean the same thing:

    • External Object Name
    • Model Entity
    • Salesforce Object Name

  • Model behavior: Some connections allow the builder to select a specific type of model behavior:

    • General: 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.
    • Read-only: ( REST connections) A model that can only query (and not update) data.
    • Read/Write: ( REST connections) A model that can use multiple connection URLs for different data operations.

  • Query on page load: If unchecked, no data rows are loaded into the model when the page initially loads. Uncheck this box to use this model to create new records, or to load this model later via an action flow (for example, opening it in a drawer or modal).

  • Allow Page Render Before Query Completes: Controls whether Nintex Apps must finish loading the metadata for the model before rendering the Nintex Apps page. (Only available if Query on page load is checked.) By default, Nintex Apps loads metadata for every model prior to rendering a page, even those without visible UI components. A model containing a picklist with hundreds or thousands of values could extend page load times, especially if there are many models on a page. Use this property to tailor which models have a higher priority, giving users access to the most meaningful data and UI elements first.

    • When unchecked, the model is considered synchronous —meaning it is given priority and its query must complete before the page renders.

    • When checked, the model is considered asynchronous, and the page will render even if its query is not yet finished.

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

  • Max # of records (limit): The maximum number of records that will be pulled in to this model when it is queried. The smaller this number is, the faster your page will load, but less data will be available within the page.

  • Fields to order records by: Determines how records are sorted within the model by a field name and a sort command, written as FieldName SORT. Two sort commands are available:

    • ASC: Ascending, meaning records of higher "value"—alphabetically or numerically—appear at the bottom of the record list. (If no sort command is specified, ASC is assumed.)

    • DESC: Descending, meaning records of higher "value"—alphabetically or numerically—appear at the top of the record list.

      Multiple sort statements can be used in this property and are applied in the order they appear.

      For example, to order a model's rows alphabetically—ascending—by the Name field and then by their Number field descending, enter: Name, Number__c DESC

      (Note that the first sort statement works because ASC is assumed.)

      Note:  If used on a Salesforce connection model, this property is also compatible with the NULLS FIRST and NULLS LAST syntax.

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

  • Create default row if model has none: When checked, a new record will automatically be created if there are no records within the model on page load. Useful for "Create New Record" pages.

  • Prevent users from leaving page if this Model has unsaved changes: When checked, a dialog box will appear to prevent users from leaving the page if there are unsaved changes in this model. If unchecked, users can leave freely but may potentially lose data changes within this model, so determine the best behavior for your use case.

  • Model label: If the model's selected object does not have a singular label —such as Account —this property can be used to specify one. However, if a label is specified for the object within the connection, this property has no effect. (Correlates with the {{Model.label}} merge variable for a model.)

  • Model plural label: If the model's selected object does not have a plural label —such as Accounts —this property can be used to specify one. However, if a label is specified for the object within the connection, this property has no effect. (Correlates with the {{Model.labelPlural}} merge variable for a model. Commonly appears at the bottom of paginated components—like Tables or Decks—and in Page Title components.)

  • Defer rendering: When checked, fields specified by the connector or marked in the Fields to Defer property will load asynchronously—meaning all other fields in the model may load and display in any components as soon as they are loaded. Deferred fields display placeholder text while they load and do not prevent other fields from rendering. Useful for fields that may incur longer load times, such as image fields or other binary files.

    Note:  While some connectors allow for deferred fields to be specified, some will not. For connectors that do not, the Fields to Defer property will not appear.

  • Fields to defer: Available for some connectors, this property sets which fields should load asynchronously. Requires Defer Rendering to be checked.