Connector for OData in applications

Set up external data access
Data types
References
Files
OData Function Imports

Set up external data access

A connection to an OData data source, that has been configured in the Integration Center using the Connector for OData, can be used in any Intrexx application. To do so, create a new external data group via the context menu of the application node.



The dialog to select the foreign data connection opens automatically.



Define the Title of the new external data group. In the Database connection drop-down list, you can select the desired connection. In the Data handler drop-down list, the correct data handler is entered automatically, when using an OData database connection. You can enter the name of the Table and / or View directly, or click on Browse to select them.



Here you can search for the table and/or view name. Enter a character string for the search to the Filter field. The * character can be used as a placeholder for arbitrary characters. A* finds all tables or views that have a name starting with A. *A* returns all tables in the result that contain the letter A in their name. Select the desired table or view at the bottom of the dialog and then click on OK.



The type of login is defined in the lower area. If the Login as current user option is selected, the authentication data from the current portal user will be requested when the page is opened on which the OData connection is integrated. The Login as static user option allows a fixed OData user to be used for authentication. click on the link Select user.



Here you can set up additional users. Next, click on Select user.



The authentication information for the static user has now been saved. The desired data fields that are provided by the OData service can now be selected on the Data fields tab and included with the elements in the Intrexx application.

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 datetime 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 what are 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 one of these 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 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 adapter 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.

1:n Relationships

Relationships of the type 1:n between OData data groups are represented in Intrexx using parent data groups (such as Flights) and subordinate child data groups (such as Bookings). 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 can be selected for the child data group. 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

To create and remove m:n relationships between two OData foreign data groups, the ODataLinksCallable Velocity callable is available.

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 for this:

• 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. This can be created in the Integration module of the portal manager. To do so, create a new storage location under File storage locations 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_DATAGROUP>', '<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.

Media Link Entries

In order to access and manipulate files, OData version 2.0 and later offers what are called Media Link Entries. These represent the recommended method to access binary data and are described in the following.

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, in which 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.

Viewing/downloading files from Media Link Entries

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 adapter 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 an element of the type Static text for programming on a view page (underneath 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_DATAGROUP>', $DC.getValueHolder('<Control name of the field with filename>').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. Filename
   A file name for the download can optionally 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="..."/>). The following screenshot shows the implementation of an image file both as a download link and as a directly embedded image:

Uploading files as Media Link Entries

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 page.
2. In the Expert settings for the control, overwrite the entry for name with the value odataMediaResource.
   
   
   
   
   
   
3. In the expert settings of the Save button on the edit page, a new attribute is required. The name of the attribute is 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 significantly more flexible and higher-performing possibility to manage files using OData is by using the upFile functions, which 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 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. The uploadFile 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. The downloadFile 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. 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 with the corresponding data group, but without data field assignment, and also create a button with 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. 5) Now switch to the expert settings of the view table and define the following settings:
6. odata.functionImport.name
   The function name (from service metadata)
7. odata.functionImport.parameter
   Mapping of the field GUIDS for the function parameters on the OData function parameter names (corresponding to the service meta data).