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.

OData

OData is a specific data protocol that allows for connection to RESTful APIs. Like the REST connector, the ODataconnector is meant to allow advanced builders the ability to connect to systems that do not have an existing pre-configured connector. Most OData services could be accessed with the REST connector, but OData provides additional metadata about objects, allowing more of the connection setup to be automated. The OData standard and example services can be found at http://www.odata.org.

OData Query Options

The OData spec outlines certain query options that services must implement. This allows us to achieve parity with 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.

Configuring OData connections

To begin creating a new connection, click Configure > Connections > New Connection.

Inside the New Connection popup,

1. Select an appropriate option under Connector
2. Give your connection a unique name.
3. Click Next Step.

Configure your connection's connection and authentication settings

• URL / Endpoint: This is the base URL of the connection. For OData, this "service root" is described in the OData spec.
• Use Apex Proxy: Choose whether or not to use the Apex Proxy. By default, this option is checked. See this section for more information.
• OData Version: OData versions 1 through 4 are are supported, and you must designate which version your database uses when configuring a connection connection within Nintex Apps.
• Authentication Method, Provider, and Credential Source: Configure the appropriate authentication settings for this particular connection. Click here for more information about authentication.
• URL Parameters to send with every request: The request URL will append these parameters for each request. This is typically used for API keys and access tokens.
• Client Certificate: An optional piece of data Nintex Apps would present with all requests to positively, uniquely identify the sender of the request.

Create a Remote Site Setting ( Nintex Apps for Salesforce )

Connections that use the Apex proxy must have a remote site setting configured for the domain of the service being accessed. By selecting "OK," Nintex Apps will attempt to create this remote site setting for you. If you select "Cancel," your connection will be created, but the remote site setting will not. You can create and edit remote site settings from Administer > Security Controls > Remote Site Settings in Salesforce setup.

Metadata Caching

Metadata explains the structure of your data to Nintex Apps. And because it's such an essential part of the data model, metadata is unlikely to change after initial set up. However, Nintex Apps must still query for metadata at every page load.

As an alternative, it is possible to cache, or save, metadata for future use instead of downloading it on each page load. Doing so can lead to noticeable performance improvements.

Enable metadata caching

1. Navigate to Configure > Connections > Connections.
2. Beside any the desired connections, click fa-cogs Configure Connection.
3. Within the connection's detail page, click Enable Metadata Cache fa-history.

With metadata caching enabled, Nintex Apps will store the metadata for that particular connection—greatly improving load times on any pages that use it.

Refresh the metadata cache

Nintex Apps cannot detect that a connection's metadata has changed—such as when a new object or field is created—and it will 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—you'll need to refresh the cache:

1. Navigate to Configure > Connections > Connections.
2. Beside any cached connections, click Refresh Metadata fa-refresh.

Doing this will cause Nintex Apps to re-download the metadata from that connection, grabbing the most recent updates in the process.

Note:  As with enabling metadata caching, ensure that a fully permissioned user refreshes the cache in Nintex Apps. If the Nintex Apps admin does not have access to a previously cached metadata object, that object will be deleted when the cache is refreshed.

Disable metadata caching

To disable and delete Nintex Apps's metadata cache for a connection:

1. Navigate to Configure > Connections > Connections.
2. Beside the cached connections, click Disable Metadata Cache fa-chain-broken.

This will clear Nintex Apps's cache of any stored metadata. You can re-enable caching at anytime by clicking Enable Metadata Cache fa-history.

Entity Sets

In OData, an entity set represents an object that can be queried. In the example below, six queryable entities are defined. The OData spec specifies a URL that a service must respond to for requests about that object. For example, to get a list of records from the Users Entity Set, we would request the URL http://www.example.com/myservice.svc/Users.

1
2
3
4
5
6
7
<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"/>

Entity Types

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

<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 both the ATOM and JSON verbose formats. With OData version 3, Nintex Apps also supports the JSON Light Format.

Example - Get a list of records - JSON Verbose Format

Request

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

Response

200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "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"
    }
  ]
}

Configuring 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:  This contrasts with REST models.

Create a New Model

1. Navigate to an existing Nintex Apps page or create a new one.
2. Click Models.
3. Add a new model.
4. Choose OData as the Connector.
5. Select the connection you configured for the Connection field.
6. Start typing and choose the External Object from the list. The available External Objects are defined by your service at the [serviceroot]/$metadata URL.

Adding Fields

Unlike REST models, OData explicitly specifies the datatype of each field as well as some additional metadata about that field. However, there are still many cases where you will 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

It's possible to access OData reference fields for a Nintex Apps page, but the reference field will only display the ID for each record row—which is not highly informative.

Better choice? Use a related field (for example, a "details" or "description" field) as a display template to pull in additional information about the record. Or, add explanatory text to provide context. (Or, do both.)

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 pane, select Search.

3. In Search Properties:

   • Option Source: Automatic

   • Display template: There are several options—or combinations of options:

     • Select a field (or fields) that will provide details about the reference field.

     Note:  Only fields that are included in the model are selectable. If the field you need is not offered, add it to the model and retry.

     • Add text that will add context to the reference field.

     Note:  If using both text and a display field, the text can be added either before or after the display field.

4. Click Save and then Preview.

Now the reference field column on the page contains contextual information.

Links

Reference fields allow for one record to be connected to another record—potentially 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 intuit these links, but OData connections require that these settings be input manually. To do so:

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 pane, click Link.

From here you may set the Link Options for the reference field.

Navigation type: The means by which a reference field will direct a user.

• No link: The reference field will not link to a separate page.
• Custom URL: Link to any absolute or relative URL.
  • Open URL in: Select whether an end user will be directed to this URL in the current window or in a new tab.

Note:  The following options are only available in Nintex Apps.

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

When setting a reference field's link options, you may also pass along one or more URL parameters by clicking fa-plus-circle Add Parameter.

For each parameter, you may indicate 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 a key, though you are free to enter any text in this field.
• Value: The actual value to pass along to the new page. Accepts merge syntax and receives context from the row.

Typically a parameter is used to pass the ID of the record being referenced, sending the end user to an appropriate a record detail page.

For example a reference field, on a page within a Salesforce org, using this link option configuration:

• Navigation type: Custom URL
  • URL: ODataAccountDetail

With only one parameter added:

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

Would send the end user to a URL like so:

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