Consumed OData Service Requirements

Last update: Edit

1 Introduction

This document describes the requirements for an OData service that is going to be consumed. These requirements are not further verified at runtime and expected to hold. If these requirements are not met, errors may result.

2 Requirements for a Consumed OData Service

The requirements for a consumed OData service used in a Mendix app are the following:

  • The OData service must be either an OData v3 service returning Atom XML, or an OData v4 service returning either Atom XML or JSON
  • It should support queries on the OData feed, including $filter, $orderby, $top, $skip, $expand, and $count (or $inlinecount)

3 Requirements on the Service Entities and Attributes

This section describes the features of a consumed OData service that are supported in Mendix app. These features are checked before an external entity is used in the domain model.

3.1 Entities

Vocabulary annotations can be used in a service to indicate features that are not supported. The following vocabulary annotations are recognized for entity sets:

  • Countable – marking an entity set as Countable="false" prevents the user from adding the entity to the project
  • Filterable – marking an entity set as Filterable="false" sets all properties as non-filterable
  • Sortable – marking an entity set as Sortable="false" sets all properties as non-sortable
  • Marking an entity set as Filterable="false" and Sortable="false" sets all properties as non-filterable and non-sortable; marking properties with the NonFilterableProperties annotation or the NonSortableProperties annotation sets specific attributes as non-filterable or non-sortable

An entity can only be used when it is accessible through an entity set.

Furthermore, an entity can only be used if it is uniquely identifiable with a key. The key can consist of one or more properties, as long as the following conditions are met:

  • The properties cannot be nullable (so they must have isNullable="false" specified)
  • Only the following types are allowed: Byte, SByte, Int16, Int32, Int64, Boolean, Decimal, Single, Double, and String
  • If the type is String, a MaxLength must be specified

3.2 Attributes

Attribute types have to be primitive (not complex, collections, or enumerations). The types of the attributes in your app will be based on the types of the attributes in the OData metadata, as given in the following table:

OData Type Mendix Type
Binary Binary (but see 3.4)
Boolean Boolean [1]
Byte, SByte, Int16, Int32 Integer
DateTime, DateTimeOffset, Time Date/time
Decimal, Double, Single Decimal [2]
Int64 Long
String, Guid String
(Other) (Ignored)

[1] In Mendix, Booleans cannot be null. If the service returns null, the value will be false in Mendix.
[2] Decimal values outside of the range of a Mendix decimal are currently not supported. If the service returns a value outside of the range, there will be an error.

3.3 Generalizations

The consumed OData service does not support importing generalizations and specializations. This means that the Published OData service contract from the originating app will show specializations as discrete entities which will include the attributes of the generalization along with the attributes of the specialized entity.

This means that when you are consuming a Mendix OData endpoint, it is not necessary to consume both a generalization and its specialization. The specialization will now be an entity with all the attributes and associations of the generalization.

Associations to the generalizations with other exposed entities in the published OData service will be included for the now discrete “specialized” entities.

3.4 Binary Attributes

The binary data format is supported in the form of media entities. When a media entity is dragged into the domain model, a corresponding external entity is created. The entity will have a contents attribute with the binary data.

Currently, the binary data can only be accessed by Java actions.

3.5 Associations

An OData v3 association can only be used if it has two ends.

An OData v4 navigation property can only be used as an association if it has a partner.

4 Data Hub License Limitations

Mendix Data Hub is a separately licensed product. The type of license that you have determines the total number of data objects that can be requested from a consumed OData service per day for each runtime instance of an app.

There are two types of Data Hub licenses currently available:

  • Data Hub – this is the default license with no limitation on the number of OData objects that can be consumed.

  • Freemium – this enables you to retrieve a total of 1000 OData objects per day for each runtime instance. After that limit is exceeded, an error will occur when users try to retrieve more data. The number of consumed objects per day is reset at midnight in the timezone of the Mendix Runtime scheduler (which can be defined in the app Project Settings).

Contact your Mendix Admin or Data Hub Admin to find out what type of Data Hub license your organization has.

4.1 Local development

Local development is subject to the same license as the freemium model. You have the ability to retrieve a total of 1000 OData objects, after which an error will occur. It is possible to reset this by restarting the App.