Connector for OData in applications

Create external data group

A connection to an OData data source can be used in any Intrexx application. To do so, select the application node and create a new external data group via the New menu / External data group.

Title

Define the title for the external data group here.

Database connection

The desired connection can be selected here.

Data handler

The appropriate data handler is entered automatically when you select an OData connection.

Table / View

You can enter the name of the table or view directly or click on "Search" and search for name of the table or view in the dialog that opens. Click on "OK" once you have selected your table view. Click here for more information about the settings for logging in. The data fields, which should be provided by the OData service and displays in applications, can now be selected on the Data fields tab and then linked to application elements.

Data types

When selecting the data fields, the Connector automatically converts the OData data type into the corresponding Intrexx data type. Please note the following special characteristics:

  • In contrast to Intrexx, OData defines different data types for date and time. In Intrexx, all OData date / time data types are converted into the "datetime" data type. Conversely, Intrexx date values are converted by default into the OData data type "Edm.DateTime". In certain circumstances, however, the service defines another data type. In this case, the correct OData data type can be saved in the expert settings of the corresponding field.

  • OData defines so-called complex data types. These are multiple fields of simple data types bundled into a new complex data type. As an example, you could combine the fields Street, ZIP, and City into a complex data type "Address". Since Intrexx does not recognize complex data types, they are converted into multiple Intrexx data fields. To guarantee the uniqueness of such a fields, it is created from the components <complex data type name>/<field name>, such as Address/City.

References

1:1 relationships

In Intrexx applications, references can be created from any kind of data group. If the output data group and the referenced data group contain foreign data groups from an OData connection, a 1:1 relationship can be established between them, as long as a corresponding relationship is defined in the service metadata.

For a 1:1 relationship between two OData external data groups (OData terminology: "Entity Sets"), primary and foreign key data fields do not need to be defined. For OData references, the relationship type is directly determined and selected from the metadata of the OData service. Thus, for example, the possible relationships between a seminar and a room booking are automatically detected by the OData Connector based on the service metadata and then offered for selection. Click on "Next" to continue. In the next step, you can select the desired data fields on the Data fields tab.

1:n relationships

1:n relationships between OData data groups are represented with parent data groups (e.g. Flights) and subordinate child data groups (e.g. Bookings) in Intrexx. If you set up the database connection in the properties of the child data group and select the corresponding OData collection (table), the possible 1:n relationships are then offered for selection.

In the next step, the data fields for the child data group can be selected on the Data fields tab. On view and edit pages of the parent data groups, there is then the possibility to show dependent data records from child data groups in view tables.

m:n relationships

The Velocity callable "ODataLinksCallable" can be used to create and remove m:n relationships between two OData external data groups.

Creating an m:n relationship

$ODataLinksCallable.createLink(<Configuration GUID>, <Service GUID>, <Impersonation GUID>, <Source DG GUID>, <Source_Record_ID>, <Target Navigation Property>, <Target DG GUID>, <Target_Record_ID>)

Removing an m:n relationship

$ODataLinksCallable.deleteLink(<Configuration GUID>, <Service GUID>, <Impersonation GUID>, <Source DG GUID>, <Source_Record_ID>, <Target Navigation Property>, <Target DG GUID>, <Target_Record_ID>)

The following parameters are required:

  • Configuration GUID

    GUID of the OData configuration

  • Service GUID

    GUID of the OData service.

  • Impersonation GUID

    GUID of an impersonation user, or "null" for the current user.

  • Source DG GUID

    GUID of the source data group.

  • Source Record ID

    ID of the source data record.

  • Target Navigation Property

    Name of the OData navigation property that defines the relationship.

  • Target DG GUID

    GUID of the target data group.

  • Target Record ID

    ID of the target data record.

Files

Binary data fields

OData data fields of type Edm.Binary (BLOB) are handled in Intrexx as the File data type. This allows binary data to be stored in Intrexx file fields. Since neither the file type nor the required file metadata can be automatically detected from the OData binary fields, they must be saved in the expert settings for the data field. At first, a file extension for general use can be defined. This is only necessary for OData services that are not provided via the Intrexx OData Provider.

The file type is automatically used as the file extension when the binary data is saved. Currently, only one file type can be defined per field for all data records. Furthermore, an OData-specific file storage location is required with the alias "odata", in order to temporarily store the files.

To do so, create a new file storage location in the Integration module and enter "odata" as the alias name. Under Path, a directory of your choice can be selected with the placeholder "${appGuid}". Next, deactivate the "Export files" option and run the function test. If the service to be consumed is a service prepared by the Intrexx OData Provider, the required file metadata is automatically provided for use by the service. An additional possibility to enable the contents of binary fields as a download is to use the callable method "$ODataMediaResourceCallable.getDownloadURIForBinaryProperty()". This generates an URL that can be inserted into a download link on a view or edit page:

<a target="_blank" href="$ODataMediaResourceCallable.getDownloadURIForBinaryProperty($ProcessingContext, $DC.getRecId(), '<GUID_DATENGRUPPE>', '<BINARY_PROPERTY NAME>', '<FILE_NAME>','CONTENT_TYPE', '<DISPOSITION_TYPE>')">Download File</a>

With this method, it is possible to define the file name and content type dynamically by detecting these values from other fields.

For accessing and manipulating files, OData (Version 2.0 or higher) offers Media Link Entries. These are the recommended method for accessing binary data. An entity type can be defined in an OData service as a Media Link Entry. To do this, the entity type is identified in the service metadata document with the "HasStream" attribute. The fields of a Media Link Entry then describe what is known as a Media Resource, which in turn can be any kind of file type, such as a document, image, or video or audio stream. An Entity Collection of type Media Link Entry then represents a collection of files, while a Media Link Entry by itself describes exactly one file. In contrast to BLOB fields, where the complete file is provided as a binary (base 64-encoded) data structure next to the other data fields within the XML reply document, when requesting a Media Link Entry, the requester only receives the URL to the Media Resource (i.e. the file). Via the URL, then, the file can be requested and downloaded as usual in a browser. Since the file does not need to be encoded in an XML document here, Media Link Entries provide a significantly more efficient mechanism to access files. Since a Media Link Entry describes both the file itself (metadata) and the access path to it on the server, two HTTP requests are required to request the metadata and download the file. The same applies when newly creating a Media Link Entry, such as when uploading a new file via the OData service or when updating an existing one. In the following, the steps are described how to first show/download files from Media Link Entries in Intrexx, and then how to save other files as Media Link Entries on the OData server.

Since the metadata fields of a Media Link Entry are normal OData data fields, they can be displayed as usual on a view or edit page in Intrexx. To enable the display or download of a media resource, first a link must be generated for the resource that calls up an Intrexx servlet, which then requests the file via the OData service and forwards it to the browser. To do this, the Connector contains a special Velocity callable that prepares the link in such a way that it can be embedded in view or edit pages. To do so, create a static text for programming on a view page under an OData data group for Media Link Entries. For a download link, the call for the Velocity callable is defined as follows:

<a target="_blank" href="$ODataMediaResourceCallable.getDownloadURI($ProcessingContext, $DC.getRecId(), '<GUID_DATENGRUPPE>', $DC.getValueHolder('<Kontroll-Name des Felds mit Dateiname>').getValue(), 'inline')">Download Media Resource</a>

This code generates a link on the view page to download the media resource. The following parameters can be sent along with the callable:

  1. $ProcessingContext

    The current processing context object.

  2. Record ID

    The ID of the Media Link Entry data record.

  3. Data group GUID

    The GUID of the data group that contains the Media Link Entry.

  4. File name

    Optionally, a file name for the download can be passed on here. This is shown as a preselected name when saving the file in the browser. In the example above, the file name is detected from a field on the view page, that is filled using the metadata of the media resource. If such a field is unavailable, "null" can be passed on.

  5. Content Disposition Type

    This (optional) value defines the content disposition type of the download, such as whether the file should be directly embedded in the browser (value: "inline") or is only available as a download (value: "attachment"). This value is optional and can also be defined as null.

Since the Velocity callable only returns an URI to the media resource, this can be used flexibly in various HTML controls (such as a link in <a href="..."/> or as an image in <img src="..."/>).

Saving/updating files as OData media resources can be achieved with an edit page assigned to the Media Link Entry data group. On it, the data fields can be placed for the media resource metadata as usual. Uploading the actual file is controlled via a file selection control. To do so, proceed as follows:

  1. Place a new file selection control on the edit page, then in the properties for the new control, select "No link" on the Data field tab.

  2. On the Expert tab, change the value for the expert attribute "name" to "odataMediaResource".

  3. Of the Expert tab in the properties of the Save button on the edit page, create a new attribute called "rq_odaction". Enter "upload" as the value.

Using this request value, two OData requests are automatically generated when the record is saved. First, a Media Link Entry is generated for the uploaded file through the OData service. Next, with a second request, the values from the data fields on the edit page are saved as metadata for the Media Link Entry. Depending on the system architecture, the file may need to be stored temporarily on the Intrexx Portal Server both when uploading and downloading files between the browser and the OData server. If very large files are used, this may lead to resource bottlenecks (in particular, in the portal server RAM) and performance problems. If this occurs, the URIs to the media resources should be determined directly from the OData feed entry and integrated into the application page, ensuring that access to the file occurs directly from the browser via the OData server. Video and audio stream resources in particular should only be integrated in this way.

Files with Intrexx OData provider services

A way to manage files using OData, which is significantly more flexible and provides greater performance, are the "upFile" functions that are automatically available in every Intrexx OData service. They can be used to save and request files, and they provide full support for multiple file fields in Intrexx. The single disadvantage of the functions is that the file controls in Intrexx do not support this approach, which means that uploading and downloading files in Intrexx web applications will need to be realized on a project-specific basis with JavaScript or Groovy. The Intrexx OData service offers the following functions to manage files:

  • upFileList

    This function returns a list of all files in a file field. The following parameters are expected:

    • recId: The primary key of the data record with the file field.

    • fieldGuid: The field GUID of the file field.

  • upFileAction

    This function allows operations to be performed on multiple file fields. The following parameters are expected:

    • recId: The primary key of the data record with the file field.

    • fileId: The ID of the file.

    • fieldGuid: The field GUID of the file field.

    • Operation: The file operation to be performed (either delete, moveUp, moveDown, moveTop, refreshMetadata, or refreshOrder).

  • upFileDownload

    Returns the contents of a file as a base-64 encoded string. The following parameters are expected:

    • recId: The primary key of the data record with the file field.

    • fileId: The ID of the file.

    • fieldGuid: The field GUID of the file field.

  • upFileResource upload

    Enables the stream-based upload of a file. This is the fastest and most resource-saving method to transfer files to the service. This method expects the following parameters:

    • recId: The primary key of the data record with the file field.

    • fieldGuid: The field GUID of the file field.

    • fileName: The filename.

    • contentType: The content type of the file.

  • upFileResource - download

    Enables the stream-based download of a file. This is the fastest and most resource-saving method to access files. This method expects the following parameters:

    • recId: The primary key of the data record with the file field.

    • fileId: The ID of the file.

    • fieldGuid: The field GUID of the file field.

    • disposition (optional): The content disposition header type (either inline or attachment).

OData Function Imports

In addition to access to Entity Collections (tables), OData also provides the ability to define what are known as Function Imports and to run them via the service. OData Function Imports In addition to access to Entity Collections (tables), OData also provides the ability to define what are known as Function Imports and to run them via the service. Function imports are comparable to stored procedures in database management systems, and can receive input parameters and return a single record or a set of records as the result. Since Intrexx does not offer direct support for stored procedures, the following procedure must be used to call function imports:

  1. By using the service metadata, determine the name of the function to be called(such as with "GetProductsWithRating"), the required input parameters, whether the results consist of a single record (OData entry) or a result set (OData entity set), and the entity type (table in the Intrexx data group) of the results.

  2. Create a view page for the parameters of the function and a further view page to view the results of the function call.

  3. On the view page for the function parameters, place an edit field for each parameter, but do not link these to a data field, and also create a button and set the link destination to the view page containing the results.

  4. On the results page, create a view table (in cases when there is a results set), select the corresponding data group (depending on the function results type), and the data fields to be displayed.

  5. Now switch to the Expert tab of the view table properties and define the following settings:

    1. odata.functionImport.name

      Function name (from the service metadata)

    2. odata.functionImport.parameter

      Mapping of the field GUIDs for the function parameters on the OData function parameter names (corresponding to the service metadata).

More information

General
System requirements
Provide OData data
Consume OData data
OData in processes
Export / Import
Appendix