Getting started

The IBM TRIRIGA Connector for Business Applications was developed with WS-I compliance in mind, so you can use third-party web services tools as clients or to develop interfaces for other environments. This document provides an introduction to how objects, section types, field types, and associations interact and work together.

If you choose to develop by using a programming language like Java™, you do not need to marshal or unmarshal XML elements. Instead, you need to handle true Java Objects.

Data binding

To transfer objects over the IBM TRIRIGA Connector for Business Applications, Apache CXF handles the marshalling and unmarshalling of Java objects to their SOAP representations.

Apache CXF uses a built-in data binding framework that is called Aegis to marshal and unmarshal Java objects. On the server side, the object passes through the assembler class to convert objects from their domain (platform) representation to a data transport object and vice versa.

CustomBusinessConnectTask for integrations

The workflow engine contains a task that is called CustomTask that shows the Java methods that are used for the IBM TRIRIGA Connector for Business Applications.

This process allows a workflow to trigger the full scoping capabilities of the IBM TRIRIGA Connector for Business Applications by using the Java layer, eliminating SOAP marshalling and unmarshalling. This workflow enables event-triggered integrations.

Form validation

The saveRecord method validates that the submitted fields meet the default form validation.

If a user does not complete a required field when they are creating a record, the saveRecord method prevents the record from being saved and an error is returned. If the request tries to save a read-only field, an error is returned.

You can check the form validation by making a request to the getRequiredGuiFieldNames method. This method returns a ResponseHelper object that includes the name as [sectionName]::[fieldName]. The key and the value are 1 for required, 2 for read only, and 3 for required in a smart section.

The value of the ENFORCE_REQUIRED_VALIDATION property has the potential to cause previously working integrations to fail. If the value is set to Y, the ENFORCE_REQUIRED_VALIDATION property in TRIRIGAWEB.properties ensures that a record cannot be created unless all required fields are validated. A record cannot be created regardless of the tab in which the fields appear. If the value is set to N, the ENFORCE_REQUIRED_VALIDATION property in TRIRIGAWEB.properties ensures that a record cannot be created unless all required fields on the first tab are validated. All versions of the IBM TRIRIGA Application Platform before version 3.0 include this validation process.

Duration format

The duration format is used to ensure that your users see the correct value for durations in forms. Duration is stored in the IBM TRIRIGA database as a long value.

Duration formula: (100000000000000 * ((years * 12) + months)) + (weeks * 604800000) + (days * 86400000) + (hours * 3600000) + (minutes * 60000) + (seconds * 1000) + milliseconds.

MTOM enablement

Message Transmission Optimized Mechanism (MTOM) is a method to handle large amounts of binary data in your services. The IBM TRIRIGA Connector for Business Applications web services component includes support for MTOM Enablement for certain operations.

Unlike attachments, the XML infoset stays the same. MTOM optimizes any Base64 binary data that you have in your messages. When MTOM is enabled, any Base64 binary data is sent as a binary attachment to save time and space.

Enabling MTOM allows content such as documents, images, and Rich Text Format (RTF) note fields to be transferred by the IBM TRIRIGA Connector for Business Applications. When a web services client is set up, it is important to remember to configure the client to allow for MTOM.

Error handling

When methods are called for the IBM TRIRIGA Connector for Business Applications, general errors can be returned in the form of faults.

Individual methods can return errors specific to their functions. An entire batch is returned as a response object for methods that accept batch records. The most common response object that is returned is a ResponseHelperHeader object. A ResponseHelperHeader object contains a collection of the submitted data with key data to identify each individual record. The object also includes data that indicates whether a record was saved successfully or if an error occurred. This feature allows the request to track which records were affected positively or negatively.

Errors can be returned by any method request and are either returned as a fault or are embedded as the error value for the response object.

Error	Description
Authentication exception	A valid session is not established on the server and the authentication mechanism cannot find a valid set of credentials in the HTTP parameters.
Authorization exception	The authenticated user does not have permission to call the method in question.
Communications exception	An error occurred when reading the request or writing the response.
Internal server error	An error occurred and the server was unable to complete the request.
Invalid input data	At least one of the input parameters is empty, cannot be parsed, or is otherwise invalid. For example, if a method takes a record ID as a parameter and the ID contains non-numeric characters.