OData

OData is a specific data protocol that allows for connection to RESTful APIs. Like the REST data source type, the OData DST is meant to allow advanced users the ability to connect to systems that do not have an existing pre-configured data source type. Most OData services could be accessed with the REST data source type, 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 data source type. 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 data sources

To begin creating a new data source, click Configure > Data Sources > New Data Source.

Inside the New Data Source popup,

  1. Select an appropriate option under Data Source Type
  2. Give your data source a unique name.
  3. Click Next Step.

Configure your data source’s connection and authentication settings

  • URL / Endpoint: This is the base URL of the data source. 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 data source connection within Skuid.
  • Authentication Method, Provider, and Credential Source: Configure the appropriate authentication settings for this particular data source. 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 Skuid would present with all requests to positively, uniquely identify the sender of the request.

Create a Remote Site Setting (Skuid on Salesforce)

Data sources that use the Apex proxy must have a remote site setting configured for the domain of the service being accessed. By selecting “OK,” Skuid will attempt to create this remote site setting for you. If you select “Cancel,” your data source 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

When loading from OData data sources, you may experience long load times. To help relieve this, you may cache your data source’s metadata. This can reduce load times of 15-20 seconds to 1-3 seconds.

Note

  • Any newly created OData data sources will automatically have their metadata cached.
  • This feature is currently exclusive to Skuid Platform.
  • You must refresh your metadata cache manually if your OData schema changes.

Enabling metadata caching

  1. Navigate to Configure > Data Sources > Data Sources.
  2. Beside any OData data sources, click Enable Metadata Cache fa-history.

With metadata caching enabled, Skuid will store the metadata for that particular data source—greatly improving load times on any pages that use it.

Note

It is important to note that Skuid will only cache the metadata that the Skuid admin has access to within the OData system. If the admin that enables caching does not have access to any objects on the system-side, then that metadata will not be cached.

It is recommended that a user with full OData permissions be the Skuid admin to enable caching.

Refreshing the metadata cache

Skuid cannot detect that a data source’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 data source’s metadata has changed recently—you’ll need to refresh the cache:

  1. Navigate to Configure > Data Sources > Data Sources.
  2. Beside any cached OData data sources, click Refresh Metadata fa-refresh.

Doing this will cause Skuid to re-download the metadata from that data source, grabbing the most recent updates in the process.

Note

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

Disabling metadata caching

To disable and delete Skuid’s metadata cache for a data source:

  1. Navigate to Configure > Data Sources > Data Sources.
  2. Beside the cached data sources, click Disable Metadata Cache fa-chain-broken.

This will clear Skuid’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
<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, Skuid 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
{
  "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 data source, and the rest of the URL is determined automatically by Skuid from the metadata provided.

Note

This contrasts with REST models.

Create a New Model

  1. Navigate to an existing Skuid page or create a new one.
  2. Click Models.
  3. Add a new model.
  4. Choose OData as the Data Source Type.
  5. Select the data source you configured for the Data Source 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 Skuid 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.