OData

OData is a standardized data protocol that enables connections to RESTful APIs. Similar to the REST connector, the OData connector allows advanced users to connect to systems that do not have a preconfigured connector. However, OData provides additional metadata about objects, fields, and relationships, which helps simplify the connection setup. For more information about the OData standard and example services, see OData.

Jump to:

OData query options

The OData specification defines certain query options that services must implement. This provides functionality similar to many features in the Salesforce connector. These query options include $expand, $select, $top, $skip, $filter, and $orderby.

Metadata about objects

OData specifies that services must serve an XML document at [serviceroot]/$metadata that describes any objects and fields provided by the service.

Configure OData connection

To create a new connection, see Create a connection.

After you create the OData connection, configure the following connection-specific settings:

  • URL / Endpoint: This is the base URL of the connection. For OData, this service root is described in the OData specification.
  • Use proxy: Select to use the proxy. This option is enabled by default. For more information, see Connectors.
  • OData version: OData versions 1 through 4 are supported. You must specify which version your database uses when configuring a connection in Nintex Apps.
  • Authentication Method, Provider, and Credential Source: Configure the appropriate authentication settings for the connection. For more information, see Authentication and Nintex Apps.
  • URL Parameters to send with every request: The request URL appends the parameters for each request. This is typically used for API keys and access tokens.
  • Client Certificate: An optional certificate that Nintex Apps sends with each request to identify the client.

Metadata caching

Metadata describes the structure of your data to Nintex Apps. Because metadata is an essential part of the data model, it is unlikely to change after the initial setup. However, Nintex Apps must still query for metadata each time a page loads.

You can cache metadata, or save it for future use, instead of downloading it each time a page loads. This reduces the amount of metadata Nintex Apps needs to download and can improve page load performance.

Note: 
  • You must refresh your metadata cache manually if your OData schema changes.
  1. Go to Integrations.
  2. To display connections associated with apps, select Apps.
  3. Next to the connection for which you want to enable metadata caching, click , and click Edit.
  4. Click Enable Metadata Cache.

Nintex Apps stores the metadata for the connection, which greatly improves load times on any page that uses it.

Note: 

Nintex Apps will only cache the metadata that the Nintex Apps admin has access to in the external system. If the admin who enables caching does not have access to any objects in the external system, then that metadata will not be cached.

It is recommended that a builder with full permissions is assigned as the Nintex Apps admin.

Nintex Apps cannot detect if a connection's metadata changes. For example, if a new object or field is created, Nintex Apps does not automatically re-cache the metadata.

To ensure the cached metadata is up-to-date or if you know the connection's metadata has changed recently, refresh the cache:

  1. Go to Integrations.
  2. To display connections associated with apps, select Apps.
  3. Next to the connection for which you want to refresh metadata, click , and click Edit.
  4. Click Refresh Metadata.

Nintex Apps downloads the metadata from the connection again to retrieve the latest metadata.

Note: Ensure that a user with full permissions refreshes the cache in Nintex Apps. If the Nintex Apps admin does not have access to a previously cached metadata object, that object is deleted when the cache is refreshed.

  1. Go to Integrations.
  2. To display connections associated with apps, select Apps.
  3. Next to the connection for which you want to disable metadata caching, click , and click Edit.
  4. Click Disable Metadata Cache.

The Nintex Apps cache of any stored metadata is cleared. To re-enable metadata caching, click Enable Metadata Cache.

Entity sets

In OData, an entity set represents an object that can be queried. The following example defines six entity sets.

Copy 
<EntitySet EntityType="$news.Types.NewsContext.Category" Name="Categories"/>
<EntitySet EntityType="$news.Types.NewsContext.Article" Name="Articles"/>
<EntitySet EntityType="$news.Types.NewsContext.TagConnection" Name="TagConnections"/>
<EntitySet EntityType="$news.Types.NewsContext.Tag" Name="Tags"/>
<EntitySet EntityType="$news.Types.NewsContext.User" Name="Users"/>
<EntitySet EntityType="$news.Types.NewsContext.UserProfile" Name="UserProfiles"/>

The OData specification defines a URL that a service must respond to when a request is made for an entity set. For example, to get a list of records from the Users entity set, request the following URL:
http://www.example.com/myservice.svc/Users

Entity types

All entity sets in OData have a corresponding entity type. Entity types describe the fields that are available on an object.

The following example defines an entity type for the User object.

Copy 
<EntityType Name="User">
  <Key><PropertyRef Name="Id"/></Key>
  <Property Name="Id" Type="Edm.String"/>
  <Property Name="LoginName" Type="Edm.String"/>
  <Property Name="Email" Type="Edm.String"/>
  <NavigationProperty FromRole="User_Articles_Source" Name="Articles"   Relationship="$news.Types.NewsContext.User_Articles"ToRole="User_Articles_Target"/>
  <NavigationProperty FromRole="User_ReviewedArticles_Source" Name="ReviewedArticles"Relationship="$news.Types.NewsContext.User_ReviewedArticles" ToRole="User_ReviewedArticles_Target"/>
  <NavigationProperty FromRole="UserProfile_User_Target" Name="Profile" Relationship="$news.Types.NewsContext.UserProfile_User"ToRole="UserProfile_User_Source"/>
</EntityType>

Payload formats

OData supports payloads returned in Atom and JSON Verbose formats. With OData version 3, Nintex Apps also supports the JSON Light format.

For example, to get a list of records in JSON Verbose format:

Request

GET http://www.example.com/myservice.svc/Users?$select=Id,LoginName,Email&$top=21

Response

200 OK

Copy 
{
  "d": {
    "results": [
    {
      {
      "__metadata": {
        "type": "$news.Types.User",
        "id": "http//www.example.com/myservice.svc/Users(1)",
        "uri": "http//`www.example.com/myservice.svc/Users(1) <http://www.example.com/myservice.svc/Users(1)>`__",
      }  "Id": "1", "LoginName": "Leroy",
      "Email": "Jenkins"
    }
  ]
}

Configure OData models

For OData services, the base URL is configured in the connection, and the rest of the URL is determined automatically by Nintex Apps from the metadata provided.

Note: REST models use different URL configuration. For more information, see REST.

Create a new model

  1. Navigate to an existing Nintex Apps page or create a new page. For more information, see Access the Page Designer.
  2. In the Page Designer, in the Elements panel, click Models.
  3. Click .
  4. Type the Model Id.
  5. Type the Model description.
  6. Under Connection, select OData.
  7. Under Object, select an object.
  8. Select the External Object from the list. The available external objects are defined by your service at the [serviceroot]/$metadata URL.

Add fields

Unlike REST models, OData explicitly specifies the data type of each field as well as some additional metadata about that field. However, there are still many cases where you may want to override the metadata on these fields.

Supported OData field types

  • Edm.String
  • Edm.Boolean
  • Edm.Date
  • Edm.DateTime
  • Edm.DateTimeOffset
  • Edm.Int16
  • Edm.Int32
  • Edm.Decimal
  • Edm.Double
  • Edm.Int64
  • Edm.Guid
  • Reference fields (one-to-one or many-to-one relationships)

Reference fields

Display templates

You can access OData reference fields for a Nintex Apps page, but the reference field will only display the ID for each record—which provides limited information.

A better choice is to use a related field, such as a details or description field, as a display template to provide additional information about the record. You can also add descriptive text to provide context, or use both options.

  1. In a Table component or Field Editor component containing a reference field, click the reference field to see the field's properties.

  2. In the Properties panel, select Search.

  3. Set the following properties:

    • Option Source: Automatic

    • Display template: Select one or more fields that provide additional details about the reference field. Add text to provide additional context for the reference field.

      Note: Only fields included in the model can be selected. If the field you need is not available, add it to the model and try again. If you use both text and a display field, you can add the text before or after the display field.

  4. Click Save and click Preview.

The reference field now displays contextual information on the page.

Reference fields allow for one record to be connected to another record, which may be on a different object. Because this separate record will have its own set of details, it can be useful to link to a separate page containing that information.

Some connectors can automatically determine these links, but OData connections require that these settings be configured manually.

  1. In a Table component or Field Editor component containing a reference field, click the reference field to see the field's properties.
  2. In the Properties panel, click Link.

Configure the link options for the reference field.

  • Navigation type: Determines how a reference field directs a user.

    Note: Nintex Apps page and Route options are only available in Nintex Apps.

    • No link: The reference field does not link to a separate page.

    • Custom URL: Links to any absolute or relative URL. For more information, see What is a URL?.

      • Open URL in: Determines whether an end user opens the custom URL in the current window or in a new tab.

    • Nintex Apps page: Links to a specific Nintex Apps page, regardless of route.

    • Route: Links to a specific route.

To pass one or more URL parameters, click Add Parameter when setting the reference field's link options.

For each parameter, configure the following:

  • Key: The key or field name to pass along as a parameter. It is best practice to use the object's field name as the key. You can also type any text in this field.
  • Value: The actual value to pass along to the new page. Accepts Variables and Merge syntax, and receives Context from the row.

Typically, a parameter passes the ID of the record being referenced and sends the end user to an appropriate record detail page.

For example, you can configure the following link options for a reference field on a page within a Salesforce org:

  • Navigation type: Custom URL
    • URL: ODataAccountDetail

With only one parameter added:

  • Key: AccountID
  • Value: {{AccountID}}

This configuration directs the end user to a URL like:

https://example--c.na30.visual.force.com/apex/ODataAccountDetail?AccountID=030030AHK777