Create and Configure Models

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
• 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:

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

• Next, use the dropdown next to Object or Entity to select the specific object within the system to pull the content from.
• 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.

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. Clicking fa-arrow-circle-o-right next to any field displaying that icon. This opens a new field list.
2. Again, check the boxes beside the fields that you would like to add to the model from the related object.
3. 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 that 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/)

     • No check box next to a field? Click fa-plus-circle 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.

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.

To delete a 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.

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

• Connector: The connector <appdev/data/> to use for this model, which narrows the selectable options in the Connection property.

• Connection: The connection <appdev/data/> —a connection to a system that has been configured by the Nintex Apps builder—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 the Action Framework (for example, opening it in a drawer, popup, or tab).

• 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 the less data 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.

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