Provide data - Connector for OData

Integration module Provide data

1. Create service

In this example, you will see how to provide appointments from the Personal calendar in Intrexx for external accesses via an OData service. The appointment data in the calendar can then be accessed from another portal by using the Connector for OData or another OData client of your choice. A new OData service can be configured in the Integration module via the OData menu / New service.



In this dialog, define the following settings:

• Name: Appointments
• Namespace: Personal-Calendar
• Service is active

In the next step, you can select the data groups for the service.

Add data group
Opens a dialog where a data group can be selected.



In this dialog, select the Personal calendar application and the Calendar data group.



In this dialog, define the following settings:

• Type name: Appointment
• Set name: Appointment
• Allowed actions: Allow all

In this dialog, the data fields, which the OData service should access, are selected:

• ID
• UserID
• Date from
• Date to
• Headline
• Body

In the next dialog, none of the settings are changed. After clicking on "Finish", the new service will be shown.

2. OData server configuration

Before the service can be used, the OData Provider must be activated via the OData menu / Settings.

OData services are connected to and provided by Intrexx to a defined TCP/IP address and port. Before you can connect to an OData service, the OData server must be accordingly configured and activated.

In this dialog, the following settings are defined:

• Link address: The server should be accessible at this address
• Port: A free port which is being used by another service and not blocked by a firewall
• Provider is active

The OData server is started automatically started and activated after clicking on "Finish". To test the service, enter the address "http://servername:port/Appointments.svc" in your browser. Replace "servername" and "port" with the hostname of the computer where the Intrexx portal server is running. The OData XML document, which is now shown, displays the "Appointment" data group.



Alternatively, you can view the OData XML document, which lists the service meta data via the OData menu / Show meta data.



In the next step, the OData service can be consumed.

3. Relationships

Relationships and references between Intrexx data groups are represented in OData as Associations and Navigation Properties. Both 1:1 and 1:n relations can be defined. Relationships with m:n cardinality can be represented with an m:n data group. Associations in OData define the relationships and their cardinality between Entity Types. Navigation Properties, on the other hand, add properties to the Entity Types, which can be used to navigate from a data record to a referenced data record without explicitly needing to add the foreign key or reference data fields to the Entity Type. The required settings for this are selected in the Relationships dialog. After the data groups that will be available to the service have been selected, the relationships between them can be defined.

4. Files

In order to enable access from an OData service to files from file fields in data groups, the service must have the corresponding file field added to it as described previously. Since Intrexx provides additional metadata fields for file fields, a field with the complex data type "IxFile" is automatically added to the Entity Type for each file field. In addition to the file, this also contains metadata, such as the file name, type, and size. Furthermore, three functions are available to access files and manage them. There are two possibilities to access files, which are described in the following.

Embedding files in OData feeds

The first possibility is to directly embed a file's contents as a base-64 encoded binary sting in an OData feed or entry. This is the simplest method to access a file, by providing it directly with the result of an OData request. The Connector for OData is able to extract the file's contents and save it locally as a file, and/or transfer it to another file field in a target file group and show the file in the browser using the Intrexx file control. It is also possible to save or update individual files using the file control. The disadvantage of this approach is that only one file can be provided for each file field. In the case of multiple file fields, this is always the first file, though a new file will always be added when saving. Also, the performance of the service will be significantly negatively impacted, since the file must first be completely loaded into the RAM in order to encode or decode it. For this reason, this method should only be used for smaller files.

OData functions for files

A significantly more flexible and resource-saving possibility to access 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
  This function returns a list of all files in a file field. The following parameters are expected:
  1. recId: The primary key of the data record with the file field.
  2. 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:
  1. recId: The primary key of the data record with the file field.
  2. fileId: The ID of the file.
  3. fieldGuid: The field GUID of the file field.
  4. 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:
  1. recId: The primary key of the data record with the file field.
  2. fileId: The ID of the file.
  3. 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:
  1. recId: The primary key of the data record with the file field.
  2. fieldGuid: The field GUID of the file field.
  3. fileName: The file name.
  4. 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:
  1. recId: The primary key of the data record with the file field.
  2. fileId: The ID of the file.
  3. fieldGuid: The field GUID of the file field.
  4. disposition (optional): The content disposition header type (either inline or attachment).

5. SSL configuration

If "Use SSL" has been activated in the OData provider settings, access to the OData services is only possible via the HTTPS protocol. To enable SSL, the server requires an X.509 certificate that is stored along with a certificate from the Certificate Authority in a keystore. In order to test SSL, it is possible to create what is known as a self-signed certificate. A certificate from a Certificate Authority should be used for a live system as otherwise warnings will appear in the browser and OData clients will decline the SSL connection. The following section describes how to generate a self-signed certificate for testing purposes and store it in a keystore. You can find additional information on this topic, including how to import trustworthy certificates, here.

Creating a keystore with SSL certificate

Open a command window in Windows or a shell in Linux, then switch to the bin directory of your Java JDK installation (such as \jre\windows\amd64\bin). Then run the following command:

$ keytool -keystore /path/to/keystore.ks -alias odata -genkey -keyalg RSA
Enter keystore password:  password
What is your first and last name?   
[Unknown]: odata.intrexx.com 
What is the name of your organizational unit?   
[Unknown]: OData 
What is the name of your organization?   
[Unknown]: United Planet GmbH 
What is the name of your City or Locality?   
[Unknown]:  
What is the name of your State or Province?   
[Unknown]: 
What is the two-letter country code for this unit?   
[Unknown]: 
Is CN=odata.intrexx.com, OU=OData, O=United Planet GmbH, 
L=Unknown, ST=Unknown, C=Unknown correct?   
[no]:  yes

Enter key password for <odata>

The program now requests a password for the keystore and information about the server certificate. When asked for the first and last name, enter the same host name of the OData server as was defined in the service endpoint URL.

6. Authentication methods

Authentication and permissions

To provide secure access to the data in a portal via OData services, user authentication takes place using the portal server login methods. The following section describes what kinds of authentication methods are supported and how they are configured. This can be done either by defining a global method for all services or by defining a specific method for each service. The data group permissions for a user are checked by the Intrexx portal server for OData requests. If a user does not possess sufficient permission to read or change data records, the OData service will either reply with an empty results set or with a permissions error.

Intrexx authentication

With Intrexx authentication, login is accomplished by using a user name and password, where the password is transferred in encrypted format using a challenge key provided by the server. This is the recommended method to use an Intrexx portal to access an OData service on another Intrexx portal.

Plain text authentication

Plain text authentication corresponds to the HTTP basic authentication method . This can be used to log in to the service directly from the browser. However, the password will be transferred in unencrypted format, meaning that this method should only be implemented when SSL encryption is active at the same time.

Combined Intrexx and Plain text authentication

Usually, a combination of Intrexx and Plain text authentication is used for OData services. The client tries to log in using Intrexx authentication first and if this is unsuccessful, a Plain text authentication is performed. If this is unsuccessful as well, the request of the client will be denied.

Windows Integrated Authentication

With Windows Integrated Authentication, the users are detected via the Active Directory / LDAP and logged on using the Kerberos protocol. This allows single sign-on to be realized in Windows environments. This method is only available with Microsoft Windows Servers and a domain environment. As soon as Windows Integrated Authentication is activated for a portal, OData users must log on with their Windows user name (domain\user) and password to an OData service. To authenticate OData requests directly with the logged on Windows user and thereby avoid an additional login, further steps are required. First, a third-party library is required that is added to the installation directory \lib. To do this, copy the file waffle-jna-1.6-with-dependencies.jar from the installation directory \adapter\odata\kerberos, Restart the portal server service afterwards. Furthermore, the login method for the OData server must be changed to Windows Integrated Authentication. To do this, open the file om.cfg in the portal directory \internal\cfg in a text editor. Within it, find the line that starts with

<binding scope="odataservice" auth-type="IntegratedAuthClient"/>

and change the value in the "auth-type" attribute to IntegratedAuth:

<binding scope="odataservice" auth-type="IntegratedAuth"/>

Repeat this step for all other OData service entries that need to be activated for Kerberos authentication. After saving the file, you must restart the portal server to make the changes active.

Trusted authentication

When using trusted authentication, a user can be logged on simply via the user's GUID. In doing so, it will be expected that the HTTP request sends the user GUID as the user name. This is the least secure method and should only be implemented in trusted environments.

Configuration of the authentication method

The global or service-specific authentication method is defined in the file om.cfg. By default, Intrexx defines the IntrexxAuth method for all OData services. To use another method or to overwrite the method for a specific service, open the file om.cfg in the portal directory \internal\cfg in a text editor.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
	<authentication anonymous="05CE8CE3035924F7D3088895F1D87DADD65CFAE4">
		<binding scope="web" auth-type="IntrexxAuth"/>
		<binding scope="client" auth-type="IntrexxAuth"/>
		...
		<binding scope="odataservice" auth-type="ODataAuth"/>
		...
	</authentication>
/configuration>

The entry scope=odataservice defines the global method for all OData services. The authentication method is saved in the auth-type attribute. The following methods are available:

• ODataAuth
• IntrexxAuth
• PlainTextAuth
• IntegratedAuth
• IntegratedAuthClient
• TrustedAuth

To override the global method for a single service, copy the entry and change the scope attribute as follows:

<binding scope="odataservice:MyService" auth-type="PlainTextAuth"/>

After the colon, specify the name of the OData services from the service configuration. After saving the configuration file and restarting the portal service, the service-specific configuration will be used.

7. More information

General
System requirements
Consume OData data
Function parameters in Groovy
Integrate OData data into applications
Export / Import
OData appendix