OData Connector - Integration into Applications

Create an External Data Group

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

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. "

Enter the name of the new external data group, and then select the desired OData database connection. The appropriate data handler is then entered automatically.

You can enter the name of the desired table or view directly, or click "Search" at and search for the table or view name in the dialog box that appears.

Search Tables / Views

Filter

Enter a search string here. The * character serves as a placeholder for any character. A* finds all tables and views whose names begin with A. *A* returns all tables whose names contain the letter A.

Table / Views

Select the table or view you're looking for here.

Click "OK" once you have selected the table or view.

You can find all the information about the login settings here.

The desired data fields—which are provided by the OData service and are to be displayed in the application—can now be selected on the "Data Fields" tab and linked to application elements.

Data Types

When selecting data fields, the connector automatically converts the OData data type to the corresponding Intrexx data type. The following special considerations should be noted:

  • Unlike Intrexx, OData defines different data types for date and time. In Intrexx, all OData date/time data types are converted to the `datetime` data type. Conversely, Intrexx date values are converted to the OData data type Edm.DateTime by default. However, depending on the circumstances, the service may define a different date type. In this case, the correct OData data type can be specified in the expert settings for the respective field.

  • OData defines what are known as complex data types. This involves combining several fields of simple data types into a new, complex data type. For example, you could combine the fields "Street," "ZIP Code," and "City" into a complex data type called "Address." Since Intrexx does not support complex data types, they are converted into multiple Intrexx data fields. To ensure that the name of such a field is unique, it is formed from the components <name of the complex data type>/<field name>, for example, "Address/City."

References

One-on-One Relationships

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

In the case of a 1:1 relationship between two OData foreign data sets (OData terminology: "entity sets"), there is no need to define primary and foreign key data fields. For OData references, the relationship type is determined and selected directly from the OData service's metadata. For example, the connector for OData automatically determines the possible relationships between a seminar and a room reservation based on the service metadata and presents them as options. Then click "Next." In the next step, you can select the desired data fields on the "Data Fields" tab.

1-to-n relationships

1:n relationships between OData data sets are mapped in Intrexx using parent data sets (e.g., flights) and child data sets (e.g., bookings). When you set up the database connection in the properties of the child data group and select the corresponding OData collection (table), the available 1:n relationships will then be displayed for you to choose from. In the next step, you can select the data fields for the "Child" data group on the "Data Fields" tab. On the view and input pages of the parent data groups, you can then display dependent 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 sets.

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

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

  • Source DG GUID

    ID of the source data set.

  • Source Record ID

    ID of the source record.

  • Target Navigation Property

    Name of the OData navigation property that defines the relationship.

  • Target DG GUID

    ID of the target data group.

  • Target Record ID

    ID of the target record.

Files

Binary Data Fields

OData data fields of the type "Edm.Binary (BLOB)" are treated as the "File" data type in Intrexx. This allows binary data to be stored in Intrexx file data fields. Since OData cannot automatically determine the file type or the required file metadata from binary fields, these must be specified in the data field's expert settings.

First, you can define a file extension for general use. This is only necessary for OData services that are not made available through the Intrexx OData provider.

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

To do this, create a new file location in the "Integration" module and enter the alias "odata." You can select any directory as the path using the "${appGuid}" placeholder (e.g., "d:\temp\files\odata\${appGuid}").

Uncheck the "Export Files" option and run the functional test. If the service to be used is one provided by the Intrexx OData provider, the required file metadata is automatically provided by the service.

Another way to make the contents of binary fields available for download is to call the callable method "$ODataMediaResourceCallable.getDownloadURIForBinaryProperty()". This generates a URL that can be inserted into a download link on a view or input page:

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

This method makes it possible to dynamically define the file name and content type by deriving these values from other fields.

Starting with version 2.0, OData provides so-called media link entries for accessing and manipulating files. These are the recommended methods for accessing binary data.

An entity type can be defined as a MediaLink entry in an OData service. To do this, the entity type is marked with the "HasStream" attribute in the service metadata document. The fields of a Media Link entry then describe what is known as a 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, where each Media-Link-Entry describes exactly one file.

Unlike BLOB fields, where the entire file is provided as a binary (Base64-encoded) data structure alongside the other data fields within the XML response document, a query for a Media-Link-Entry returns only the URL to the media resource (i.e., the file).

You can then access or download the file in a browser as usual using the URL. Since the file does not need to be embedded in an XML document here, media link entries provide a much more efficient mechanism for accessing files. Since a Media Link entry describes both the file itself (metadata) and the path to it on the server, two HTTP requests are required to retrieve the metadata and download the file.

The same applies to creating a new Media Link entry, for example, when a new file is to be uploaded via the OData service or an existing one is to be updated. The following section describes the steps for displaying or downloading files from Media Link entries in Intrexx, as well as for saving files as Media Link entries on the OData server.

Since the metadata fields of a Media Link entry are standard OData data fields, they can be displayed as usual on a view or input page in Intrexx. To enable a media resource to be displayed or downloaded, a link for the resource must first be generated. This link calls an Intrexx servlet, which then requests the file via the OData service and forwards it to the browser.

To this end, the connector includes a special Velocity callable that formats the link so that it can be embedded in view or input pages. To do this, on a view page, create the "Static Text for Programming" element below an OData data group for Media Link entries. To generate a download link, 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 for downloading the media resource. The following parameters can be passed to the callable:

  1. $ProcessingContext

    The current processing context object.

  2. Record ID

    The ID of the Media Link Entry record.

  3. Data Group GUID

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

  4. File Name

    Optionally, you can enter a filename for the download here. This will appear as the default selection when saving the file in the browser. In the example above, the file name is determined from a field on the view page that is populated using the media resource's metadata. 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—that is, whether the file should be embedded directly in the browser (value "inline") or made available only as a download (value "attachment"). This value is optional and can also be set to "null."

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

Files can be saved and updated as OData media resources using an input page associated with a Media Link Entry data group. As usual, the data fields for the media resource metadata can be placed here.

The upload of the actual file is controlled via the "File Selection" element. Follow these steps:

  1. Place a new file selection control on the input page, and in the properties, on the "Data Field" tab, select the "No Link" option.

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

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

This request value automatically generates two OData requests when the record is saved. First, a media link entry is generated for the uploaded file via the OData service. A second request is then sent to save the values from the data fields on the input page as metadata for the Media Link entry.

Due to the system architecture, when uploading or downloading files between the browser and the OData server, the file must first be temporarily stored on the Intrexx portal server. With very large files, this can lead to resource bottlenecks (particularly in the portal server's main memory) and performance issues.

In this case, the URIs for the media resources should be retrieved directly from the OData feed entry and embedded in the application page, so that the file is accessed directly from the browser via the OData server. Video and audio stream resources, in particular, can only be embedded this way.

Files Using Intrexx OData Provider Services

The upFile functions, which are automatically available in every Intrexx OData service, offer a much more flexible and high-performance way to manage files via OData. This allows files to be stored and retrieved with full support for multiple file data fields. The only drawback is that Intrexx's file controls do not support this approach, which is why downloading or uploading files in Intrexx web applications must be implemented on a project-by-project basis using JavaScript or Groovy scripts. An Intrexx service for managing files offers the following OData functions:

  • 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 record containing the file field

    • fieldGuid: The field GUID of the file field

  • upFileAction

    These functions can be used to perform operations on multiple file data fields. The following parameters are expected:

    • recId: The primary key of the record containing the file field

    • fileId: The file ID

    • 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 Base64-encoded string. The following parameters are expected:

    • recId: The primary key of the record containing the file field

    • fileId: The file ID

    • fieldGuid: The field GUID of the file field

  • upFileResource – upload

    Enables a stream-based upload of a file. This is the fastest and most resource-efficient way to transfer files to the service. The following parameters are expected for the uploadFile method:

    • recId: The primary key of the record containing the file field

    • fieldGuid: The field GUID of the file field

    • fileName: The file name

    • contentType: The file's content type

  • upFileResource - download

    Enables a stream-based download of a file. This is the fastest and most resource-efficient way to access files. The following parameters are expected for the `downloadFile` method:

    • recId: The primary key of the record containing the file field

    • fileId: The file ID

    • 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 accessing entity collections (tables), OData also allows you to define so-called function imports and execute them through the service. Function imports can be compared to stored procedures in database management systems. They can accept input parameters and return a single record or a set of records as the result. Since Intrexx does not directly support stored procedures, you must follow these steps to call function imports:

  1. Use the service's metadata to 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.

  2. Create a view page for the function's parameters and another page to display the results of the function call.

  3. On the function parameters view page, place an input field for each parameter with the appropriate data type but without a link, as well as a button that navigates to the results view page.

  4. On the results page, create a view table (if there is a set of results), select the appropriate data group (depending on the function result type), and select the data fields to display.

  5. In the table properties, go to the "Expert" tab and configure the following settings:

    1. odata.functionImport.name

      Function Name (from service metadata)

    2. odata.functionImport.parameter

      Mapping the field GUIDs for the function parameters to the OData function parameter names (as specified in the service metadata).

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

More Information

General Information

System Requirements

Consume data

Provide Data

Use in Processes

Expert Settings

Appendix