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.

Connections

Connections are the way Nintex Apps translates the various tables and columns—or objects and fields—of a database into the declarative objects that Nintex Apps models can work with. As different databases / data services may not always provide easily digestible metadata, Nintex Apps instead relies on this set list of connections, which correlate to an object or table in a database. Additionally, connections can be configured with an array of conditions and security options on top of any security configurations in place on the database side.

Note:

Though you can regularly import connections, Nintex Apps cannot automatically keep track of changes to the database.

If a database's schema and structure change often, you'll need to update the connections to match whenever you make those changes. Consider waiting until the database reaches a more permanent state before setting up connections.

Connection Properties

There are several connection properties you may update from the connection table or the connection detail page:

Name: The name of the object, which must correlate with the object's name in the database.
Label: Typically a human-friendly identifier for an object, used in Nintex Apps pages whenever the object's label would display within a component.
Label Plural: The plural form of the above label, used whenever the object is referenced in a context that makes it plural, e.g. when working with multiple records or navigating pages of records within a component.

Creating and Configuring Connections

Creating connections is the first step in using a SQL connection, and importing connections is the recommended approach.

Note: The Nintex Apps admin who imports connections must have permission within the database to list its schema. If you are unsure if this applies to you, or if you are seeing issues, contact your database administrator.

Click fa-magic Import Connections.

A popup containing a list of the tables—or objects—within the database will appear, organized by name and schema.
For each object you wish to use within Nintex Apps, click fa-sign-in Import Object.

You can also manually create connections:

Click the down arrow beside Import Connections.
Click fa-plus-circle Manually Create Connection.
In the newly created row on the connection table, enter the Name and Schema of the object you wish to use within Nintex Apps.

Important: Creating a new connection in Nintex Apps will not create a corresponding table or object in your database. Only create objects that already exist in your database.

Adding dependent tables

If you attempt to import an object that has dependencies on other objects—i.e. other SQL tables—then you may receive an error. This is because Nintex Apps cannot parse the relationships of the object properly, and thus cannot form proper connection metadata.

Should this happen the Add Dependent Tables and Retry button will appear at the top of the import page. Clicking this will cause Nintex Apps to recursively retrieve all objects the selected object depends on, which will then allow for normal import of the selected object.

Connection details

After creating Connections, you'll need to configure them before using them within a Nintex Apps page. To do so, click fa-cogs Details beside the connection you wish to configure. Within the connection details page, you'll find several tabs where you can fine tune the details of that object.

Fields

Fields represent the columns of the object within your database. The fields of an object will be imported within the object itself, or you can also create fields manually by clicking fa-plus-circle Create Connection Field. Much like with objects themselves however, importing fields is recommended over manual creation.

Important: Creating a new field on a connection in Nintex Apps will not create a corresponding field on the table or object in your database. Only create fields that already exist within tables or objects in your database.

Each field's Name and Display Type must match the field's configuration within the database, but there are several other properties you can configure:

Label: The label that will display whenever the field is shown within a Nintex Apps page. While the Name field is often bound by the character and syntax rules of the database, the Label property allows for more human-friendly display names.
Required: When enabled, a field must have some value before Nintex Apps will allow a record on the object to be saved.
Readonly: When enabled, a field—regardless of database permissions—will not be editable within Nintex Apps
Id Field: Specifies that this field stores specially-generated identification values for each new record on the object. These read-only fields help identify each newly-created record as unique; they are also commonly used to connect an object with other objects.
Name Field: Specifies that this field contains human-readable values correlating to the ID field. Name Fields are substituted anywhere the object is referenced by its ID field, most commonly seen in reference fields on other objects.

For example, an opportunity has a contact connected to it, and that contact has an ID field with the value of 000-AAA-BBB. The ID field's correlating Name field has the value of "Contact A;" this Name field value is displayed wherever the opportunity references that contact record—allowing end users to easily parse object-to-object relationships.

Note: For many objects in most databases, it is common to have one ID field and one name field, and it is best practice to ensure these are marked within your connection. In some rare cases you may have more than one of these types of fields. If you are unsure, work with your database administrator to verify these fields and how they should be configured within Nintex Apps.

For additional field options, click fa-cogs Details beside a field:

Filterable: Designates that this field may be filtered by options within Nintex Apps components.
Groupable: Designates that this field may be used as a grouping within aggregate models.
Sortable: Designates that this field may be used for sorting within a Nintex Apps page.

Note: If you add additional fields to a connection after using it in a Nintex Apps page, you may need to click fa-refresh Refresh Fields on any models connected to that object to make those fields available.

Conditions

Connection conditions are used to either limit incoming data anytime a connection is queried or enforce field values in particular situations. While you can create a condition, it isn't actually enforced until you select one or more of the enforcement options below.

Note: Conditions can be used in conjunction with Access Control permissions to enforce different rules for different permission sets on the same connection. Since these rules supersede any page-level conditions, you can provide different user experiences across pages with minimal effort through clever connection configurations.

Condition name: A human-friendly name for the condition, typically a short description of the condition's purpose.
Field: The field whose value will be analyzed for this condition.
Value source:
- Single specified value: The field value must exactly match a particular value, which is set in the Value field.
- Nintex Apps user attribute: The field value must exactly match a user's attribute. This is a dynamic value, updating based on which Nintex Apps user is accessing the page.
- Session variable: The field value must exactly match the value of a session variable —which connects to a SAML attribute from an identity provider.
- None - blank value: The field value must be empty.
Value: The value used to limit incoming data. The options available here rely on the Value source.
Enforce on: Determines when the condition is enforced, with the following options available:
- Query: Whenever this connection is queried, it will only display data that matches the rules of this condition. Useful for filtering records.
- Insert: Whenever a new record is created, the field for that record will match the value of the condition. Particularly useful for Created By <User> fields
- Update: Whenever an end user modifies an existing record, the condition will be enforced. Meaning that, whether the user changes or removes a field's value, Nintex Apps will disregard whatever the user entered and will instead match the condition's value.
- Delete: Whenever an end user attempts to delete an existing record, the condition will be enforced. These conditions are useful for records that can only be deleted in certain conditions, preventing accidental data loss.

Access Control

Access control provides an extra degree of security beyond any database-level permissions. This security is additive; it only sits atop any measures you have already set and cannot grant permissions your end users do not already have access to. Fields, conditions, or the entirety of connection can be configured per site permission set. Permissions for objects and fields are assigned based on the following operations:

Create: The creation of a new record within the object.
Read: The querying and receiving of record data.
Update: The modification of an existing record.
Delete: The deletion of an existing record

While there is commonly overlap between each of these operations, they are exclusive from one another. For example, an end user with the Create and Update operation permissions could technically do those things, but they couldn't do anything at runtime without the Read permission because they wouldn't see any data in the first place. Consider the actual operations your users should be privy to, but also how those operations need to interact with other operations.

And by the same token, granting access to an object does not immediately grant access to all of its fields. These permissions are additive, meaning that all site permission sets—besides Admin—start with zero permissions, and you'll need to grant permissions from the bottom up.

Important: Any end user assigned a site permission set with the Configure Site permission will have full access to all connections by default —though runtime data may still be filtered based on any connection conditions enforced on the Admin site permission set.