Connector for OData – Integration in applications

Create external data group

An existing connection to an OData data source can be used in any Intrexx application. You can find out how and where you can create and configure a connection here.

To integrate the connection into an application, select the application node and create a new external data group via the main menu "New / External data group".

Define the title of the new external data group and then select the desired OData database connection. A suitable data handler is then entered automatically.

You can enter the name of the desired table or view directly or click on "Search" and search for the table or view name in the following dialog.

Search tables / views

Filter

Here you can search for the table or view name. Enter a string for the search in this field. The * symbol serves as a placeholder for any character. A* finds all tables or views whose name begins with A. *A* returns all tables whose name contains the letter A.

Tables / Views

Select the required table or view here.

Click on "OK" when you have selected the table or view.

All information about the login settings can be found here.

The desired data fields that are to be provided by the OData service and displayed in the application can now be selected on the "Data fields" tab and 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 stored in the expert settings of the respective field.

  • OData defines so-called complex data types. These are multiple fields of simple data types bundled into a new complex data type. For example, you could combine the fields street, zip code 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 ensure the uniqueness of the name of such a field, it is then formed from the components <name of the complex data type>/<field name>, e.g. "address/location".

References

1:1 relationships

References to any data groups can be created in Intrexx applications. If the source data group and the referenced data group are external data groups from an OData connection, a 1:1 relationship can be established between them, provided that a corresponding relationship is defined in the service metadata.

With a 1:1 relationship between two OData foreign data groups (OData terminology: "Entity Sets"), no primary and foreign key data fields 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. Then click on "Next". In the next step, the desired data fields can be selected on the "Data fields" tab.

1:n relationships

Relationships of type 1:n between OData data groups are mapped via 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 input pages of the parent data groups, it is then possible to display dependent data records from child data groups in view tables.

m:n relationships

The velocity callable "ODataLinksCallable" is available for creating and removing 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 the type "Edm.Binary (BLOB)" are treated as a file data type in Intrexx. This allows binary data to be saved in Intrexx file data fields. As the file type and the required file metadata cannot be determined automatically from OData Binary fields, these must be stored in the Expert settings of the data field.

At first, a file extension for general use can be defined. This is only necessary for OData services that are not made available 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 per field can be defined for all data records. In addition, an OData-specific file location with the alias "odata" is required to temporarily store the files.

To do this, create a new file storage location in the "Integration" module and enter the alias name "odata". Any directory with the placeholder "${appGuid}" can be selected as the path (e.g. "d:\temp\files\odata\${appGuid}").

Deactivate the "Export files" option and carry out the function test. If the service to be consumed is a service provided by the Intrexx OData provider, the required file metadata is automatically provided by the service.

Another way to enable the content of binary fields as a download is by calling 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. For this purpose, the entity type in the service metadata document is marked with the "HasStream" attribute. The fields of a media link entry then describe a so-called media resource, which in turn can be any file type, such as a document, an image or a video or audio stream.

An entity collection of type Media-Link-Entry then forms a collection of files, whereby a Media-Link-Entry describes exactly one file.

In contrast to BLOB fields, where the complete file is supplied as a binary (Base64-encoded) data structure alongside the other data fields within the XML response document, a query for a media link entry only provides 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. As 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 query the metadata and download the file.

The same applies to the creation of a new media link entry, e.g. if a new file is to be uploaded via the OData service or an existing file is to be updated. The steps for displaying or downloading files from media link entries in Intrexx and for saving files as media link entries on the OData server are described below.

Since the metadata fields of a media link entry are standard OData data fields, they can be displayed as usual on a view or entry 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.

The connector contains a special velocity callable that prepares the link so that it can be embedded in view or input pages. To do this, create the "Static text for programming" element on a view page below 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 set.

  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 not available, 'null' can be passed.

  5. Content Disposition Type

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

Since the Velocity callable returns only one URI to the media resource, it can be used flexibly in various HTML controls.

Saving and updating files as an OData media resource can be realized via an input page assigned to the media link entry data group. On it, the data fields can be placed for the media resource metadata as usual.

The upload of the actual file is controlled via the "File selection" element. To do so, proceed as follows:

  1. Place a new file selection on the input page and select the "No link" option on the "Data field" tab in the properties.

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

  3. On the input page, create the new Expert attribute "rq_odaction" with the value "upload" in the properties of the Save button.

Using this request value, two OData requests are automatically generated when the record is saved. First, a media link entry is created for the uploaded file via the OData service. The values from the data fields on the input page are then saved as metadata for the media link entry with a second request.

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. With very large files, this can lead to resource bottlenecks (especially in the main memory of the portal server) and performance problems.

In this case, the URIs for the media resources should be determined directly from the OData feed entry and integrated into the application page so that the file can be accessed from the browser directly 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

    The upFileList 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 GUID field 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 GUID field of the file field.

    • Operation: The file operation to be executed (either delete, moveUp, moveDown, moveTop, refreshMetadata, 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 GUID field 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 GUID field of the file field

    • fileName: The file name

    • 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 GUID field 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 offers the option of defining so-called function imports and executing them via the service. Function imports can be compared with stored procedures in database management systems. You can receive input parameters and return a single data record or a set of data records as a result. Since Intrexx does not offer direct support for stored procedures, the following procedure must be used to call function imports:

  1. Determine the name of the function to be called (e.g. GetProductsWithRating), the required input parameters, whether the result consists of a data record (OData entry) or a result set (OData entity set) and the entity type (table in the Intrexx data group) of the result from the metadata of the service.

  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 input field with the corresponding data type for each parameter, but without a link, as well as a button with a jump to the view page with the results.

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

  5. Switch to the "Expert" tab in the 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).

Please note that the order of field GUIDs and parameter names in the two lists must match exactly.

More information

General

System requirements

Consume data

Provide data

Use in processes

Expert settings

Appendix