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.
2. 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.
3. 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
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.
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.
4. Files
4.1. 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:
With this method, it is possible to define the file name and content
type dynamically by detecting these values from other fields.
4.2. 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, 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.
4.3. 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
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_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:
$ProcessingContext
The current processing context object.
Record ID
The ID of the Media Link Entry data record.
Data group GUID
The GUID of the data group that contains the Media Link Entry.
Filename
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.
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="..."/>).
4.4. 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:
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.
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.
4.5. 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).
5. 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:
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.
Create a view page for the parameters of the function and a
further view page to view the results of the function call.
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.
odata.functionImport.name
The function name (from service metadata)
odata.functionImport.parameter
Mapping of the field GUIDS for the function parameters on the
OData function parameter names (corresponding to the service meta data).