IBM 3.3.2 TRIRIGA Application Platform Connector User Guide
The IBM TRIRIGA Application Platform Connector 3.3.2 allows you to integrate your TRIRIGA instance with other systems. This guide will help you understand the features and capabilities of this connector.
Advertisement
Advertisement
IBM TRIRIGA Application Platform
Version 3.3.2
© Copyright IBM Corp. 2011
Connector
User Guide
i
Note
This edition applies to version 3, release 3, modification 2 of IBM® TRIRIGA® Application Platform and to all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 2011, 2013. All rights reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents
CONNECTOR FOR ESRI GEOGRAPHIC INFORMATION SYSTEM ........................ 2
APPENDIX A: CLASS LOADERS AND SERVLET PROXIES ......................................... 52
About This Guide
This user guide describes the procedures for implementing IBM TRIRIGA connector products.
Conventions
This document uses the following conventions to ensure that it is as easy to read and understand as possible:
Note
– A Note provides important information that you should know in addition to the standard details. Often, notes are used to make you aware of the results of actions.
Tip
– A Tip adds insightful information that may help you use the system better.
Attention –
An attention notice indicates the possibility of damage to a program, device, system, or data.
Intended Audience
This document is intended for users who are implementing one of the IBM TRIRIGA connector products.
Prerequisites
This guide assumes that the reader has a basic understanding of the IBM TRIRIGA Application Platform and the fundamental concepts required to operate the web-based IBM TRIRIGA system.
Support
IBM Software Support provides assistance with product defects, answering FAQs, and performing rediscovery. View the IBM Software Support site at www.ibm.com/support .
© Copyright IBM Corporation 2011, 2013. 1
1. Connector for Esri Geographic
Information System
A geographic information system (GIS) is a system for capturing, storing, analyzing, and managing data and associated attributes that are spatially referenced to Earth. In the strictest sense, it is an information system capable of integrating, storing, editing, analyzing, sharing, and displaying geographically referenced information. In a more general sense, GIS is a tool that makes it possible for users to create interactive queries, analyze spatial information, edit data, integrate maps, and present the results of these tasks.
Geographic information system technology is used for resource management, asset management, environmental impact assessment, urban planning, sales, marketing, logistics, and many other activities. For example, GIS makes it possible for facility managers to easily assess impacts on facility assets in the event of a natural disaster, or GIS can be used to find a site for a new business to take advantage of a previously underserved market.
Tools and data that enable the GIS feature come from both IBM TRIRIGA and Esri. The breakdown is as follows:
Source
IBM TRIRIGA
Esri
What is provided
An initial set of building data used to query the Esri ArcGIS server.
A ClassLoader object that contains the logic to render the Esri
JavaScript viewer. For more information about class loaders, see
Custom ClassLoader in Appendix A.
Tools to configure the basemaps, layers, spatial references, widgets, and queries used in the rendered GIS Map areas within IBM TRIRIGA.
The geographical and geospatial data (Data Services). The IBM TRIRIGA system obtains this data through REST API services on Esri servers.
The actual map view. The ArcGIS server, whether the services offered online or the services hosted on a proprietary server, renders the maps and handles your geoprocessing.
Geoprocessing for drive time or distance radii. Geoprocessing is provided by the ArcGIS server.
Geocoding for gathering the latitude and longitude coordinates of addressable objects or identifiers that represent the features. This is provided by the ArcGIS server.
The Esri JavaScript API. It renders the viewer to provide data from the server and to provide basic interaction with the map data. The standard configuration is defined in the IBM TRIRIGA GIS Map object.
Esri offers a number of data services, including the Spatial Query data service. These services are used by GIS to determine the geographies the user sees within the current map view.
A GIS map can be displayed in two areas in IBM TRIRIGA applications: as a portal section or in a tab.
The same full-featured functionality is available each time a map is displayed.
© Copyright IBM Corporation 2011, 2013. 2
The versions of the IBM TRIRIGA Application Platform and the IBM TRIRIGA applications that support the
GIS features described in this chapter are defined in the IBM TRIRIGA Application Platform
Compatibility Matrix, which can be found at the following link: https://www.ibm.com/developerworks/mydeveloperworks/wikis/home?lang=en#/wiki/IBM+TRIRIGA1/ page/Support+Matrix .
GIS Portal Section
A GIS portal section points to an internal web page that contains a GIS map. The map has a default GIS
Map record associated to it that defines what to render.
The URL section names of the internal web pages are as follows:
triURL - GIS - Environmental Manager/Planner (US Govt)
triURL - GIS - Environmental Manager/Planner
When a user signs in to the application, the URL is called to load the web page that contains the map.
Based on the map defined in the URL parameter, a list of executable reports is returned. The first report in that list runs, and the results are returned to the map.
Reports can be metric queries or standard queries. The reports define what a user sees in the bubble markers for the locations or features. These queries also populate the table of data in the viewer.
There is a one-to-one correlation between the bubble markers on the map and the data in the table.
The table contains the same fields that the bubble marker contains, because the source data for both is the same report.
With map widgets, the user can pan or zoom or find locations. The user can also create and edit features on the map and assign those features to an IBM TRIRIGA object.
The pinpoints on the map show the locations that are returned from the query. Each location has a bubble marker (hover text) that displays information related to the location. If the query is a metric query, the bubble markers display the metric results. And the colors of the location pinpoint icons match the thresholds represented by the metric results. If the query is a standard query, the location pinpoint icons are colored blue. The default colors are blue, red, green, and yellow. You can use your own icons on the map to represent the location pinpoints on the screen.
The query that is associated to the map in a portal section does not affect or react to any other data on the portal. GIS is a stand-alone application inside of a portal section.
A GIS section includes a Save Preferences button. This feature saves the current map extent and view.
The next time the user signs in, the saved settings override the default in the URL parameter of the portal section URL. If the user did not save preferences, the section shows the default view as defined in the URL parameter string. The user preferences are stored per user, per map. When the user changes to a different map, the preferences for the original map are not applied to the second map.
Instead the second map is displayed with the default settings for that map, unless the user previously saved preferences for the second map.
© Copyright IBM Corporation 2011, 2013. 3
Creating a Custom GIS Portal Section
The following steps describe how to create a custom GIS portal section. For an example, you can use one of the as-delivered portal sections for reference: triURL – GIS Environmental
Manager/Planner
or triURL – GIS Environmental Manager/Planner (US Govt).
To Create a Custom GIS Portal Section
Step 1
Create a new GIS Map object. Define the initial extents, basemaps, layers, and queries to be applied to the map when it renders in the portal section. For this example, the map is named My First Map.
Step 2
Create a new portal section of type External. Enter a URL as shown in the following example: /html/en/default/rest/EsriJS?map=My First Map. The map parameter value of My First Map tells the viewer to render that record.
GIS Tab
When a user has appropriate licenses, as-delivered Location, Geography, and RE Transaction Plan records include a GIS tab. This tab contains a map that pinpoints the location of the record, and the map extent is the localized area. A default query renders the map. The query is specified in the URL as a parameter string that determines which queries to execute. The URL for the GIS tab is defined in the
Form Builder.
GIS/Esri Integration Points
To display maps, IBM TRIRIGA communicates with a mapping service provided by the Esri ArcGIS server.
IBM TRIRIGA communicates to the Esri ArcGIS server with Java, JavaScript, and HTML. Use the Esri
JavaScript API to make the service calls to the Esri ArcGIS server and to IBM TRIRIGA with its native
HTTP Service protocol. Actions that are provided on IBM TRIRIGA records (for example, the
Geocode
Address action) use a custom task that makes calls to the services.
The following fields on each of the as-delivered Location forms and business objects support this custom task:
Field Description
triGisLatitudeNU triGisLongitudeNU
Contains the latitude of the geocode point.
Contains the longitude of the geocode point.
Configuring the IBM TRIRIGA ArcGIS mapping tool
Use the IBM TRIRIGA ArcGIS mapping tool to configure your connection from IBM TRIRIGA to the Esri
ArcGIS server. The IBM TRIRIGA ArcGIS mapping tool is located in
Tools > System Setup > GIS Map.
Each record in the GIS Map object contains the metadata that defines how the map is used, including basemaps, layers, queries, and widgets.
© Copyright IBM Corporation 2011, 2013. 4
Creating a GIS Map Record
To create a GIS Map record
Step 1
Go to Tools > System Setup > GIS Map > Add.
The name you enter for the map must be different from the name of any other GIS
Map record in the system.
Step 2
Complete the Initial Extents section.
The Initial Extents section defines the initial extents and the default value for the spatial reference, the well-known ID (WKID). These values establish the boundaries of the map when it first opens in a portal section or tab. You must validate that the
WKID is appropriate for the basemaps and layers that you specify.
To save the existing extents and WKID set on the current map, go to the Preview tab.
Select the Show Details tab above the map and select the Set As Default hyperlink.
Selecting Set As Default stores the existing extents and WKID set on the current map to the Initial Extents section of the General tab.
If your basemaps are not WKID 4326 or WKID 102100, you must specify a geometry service to handle your point projection conversions. You specify a geometry service in the Options tab.
Step 3
Complete the Query List section.
Any query that is supported by the IBM TRIRIGA Report Manager can be included in the
Query List section. The query with the lowest value in the Display Order field is displayed by default. A user can select another query by clicking the Show Details tab above the map, selecting the query from a drop-down list, and running that query.
Metric queries behave differently in GIS than they do in other areas of IBM TRIRIGA.
Metric queries for other areas of IBM TRIRIGA have a Show By/Group By drop-down box and filter drop-down menus. In GIS, metric query data is filtered and grouped by the geographical data that is displayed in the current map view. For the results of a metric query to display correctly, the structure of the metric query must be tabular and the query can only include one aggregation setting.
For pinpoints to show up on the map to represent the query results, the query must include display columns that are labeled
Longitude and Latitude. The points must be stored in IBM TRIRIGA as Geographic Latitude and Longitude representing spatial reference WKID 4326.
To show an image for your results, include an image field from your object. The field must be labeled Image. The image displays in the table results for that column and at the top of the Info Window.
When a query runs, if the query filter includes the triGisLatitudeNU and triGisLongitudeNU
fields to represent the Latitude and Longitude fields used to pinpoint the item on the map, the Esri JavaScript viewer automatically adds filters to
© Copyright IBM Corporation 2011, 2013. 5
To create a GIS Map record
the query to only return results within the given extents of the map. The map can return a maximum of 1000 records. Note that the actual field names are the only way that filters can be added. If you use fields other than triGisLatitudeNU and triGisLongitudeNU
, there is no way to add a filter.
Step 4
Complete the Basemaps section.
The Basemaps section identifies the maps that are available for display. The basemap with the lowest value in the Display Order field is displayed by default. The user can select another basemap by clicking the Show Details tab above the map and selecting from the Switch Basemap drop-down list. Additional information about the map provided by the map vendor displays when the user selects the Show Details tab.
The Basemap record requires you to specify the REST URL of the Esri server that is providing the map service. If the URL is correct and valid, the basemap service description that is provided by the Esri server renders on the bottom of the GIS Base
Map form. If, instead of the basemap service description, nothing displays or you see an error, confirm that your Esri server has the Basemap service enabled with REST endpoints.
You can change the icon that shows when the basemap shows in the Switch Basemap list in the Show Details tab of the map. When the Thumbnail URL field points to a valid image, it is displayed in the Switch Basemap list. If you do not specify a value, the default image appears.
Step 5
Complete the Layers section.
The Layers section identifies the layers that are available for display on top of the basemap. When the Default check box is selected, the layer displays when the map renders. A user adds or removes a layer by clicking the Show Details tab above the map and selecting or clearing the check box next to the name of the layer.
When the user selects a layer with associated legend information, a column on the right of the map lists the legend that corresponds to the layer. When multiple layers are displayed, the legends are listed in display order. As the user modifies the extents on the map by zooming, the data in the legends updates to reflect the correct level of detail. If the map has a layer that is set as a default, the legend does not display until the user clicks either the Show Details tab or the Show Table tab. This conserves space on the map when it is viewed in smaller spaces, such as a portal. The column that displays the legends disappears after the last layer is removed.
The Layers record requires you to specify the REST URL of the Esri server that is providing the map service. If the URL is correct and valid, the basemap service description that is provided by the Esri server renders on the bottom of the GIS Base
Map form. If, instead of the basemap service description, nothing displays or you see an error, confirm that your Esri server has the Layers service enabled with REST endpoints.
Step 6
Click the Options tab.
© Copyright IBM Corporation 2011, 2013. 6
To create a GIS Map record
Icons. The color of a pin on the map can represent the data value. When the query used to determine the points to display on the map is a metric query, the colors of the pins represent where the value of each result falls within the thresholds defined in the metric query. For example, assume the threshold defined in the metric query is that a value of 1 through 3 is low and should have the color red representing a negative result. If the result is 2, the pin is displayed with the icon file contained in the Red Icon field. The Blue Icon field is used for a value that is returned by a standard query. You can change the icons that are displayed by uploading your files into the Icons section. An icon file can be in any format used to render on the web, for example, a JPG file or a PNG file. If you do not change the icon files, the asdelivered icons are used.
Widgets. You use the Widgets section to add a geoprocessor, to provide an overview map, or to add custom widgets. To define a widget, upload the JavaScript for the widget in the Code field.
The as-delivered Widgets section contains example widgets from Esri. These widgets are not tied to IBM TRIRIGA and are only included for purposes of illustration. Most widgets become available to the user by clicking the Show Details tab above the map.
With the as-delivered geocoding widget, the user can direct the map to latitude/longitude coordinates or to an address.
The as-delivered drive time widget displays radii for 1, 2, and 3 minute drive times from the point selected.
A user opens the as-delivered overview map by clicking the arrow that is in the upper right corner of the map display. The sample overview map shows a condensed version of the map and contains a pane that can be moved. The user drags that pane to navigate much larger regions of the map without having to zoom out.
With the as-delivered editor widget, a user can draw a line, polygon, or point on an Esri map. The entity is saved on the Esri map if the user associated the feature to one of the records in the query or selected the Show All Features check box. The as-delivered editor widget is named sampleEditor.js. You can use that file as an example of how to create custom editor widgets.
In the as-delivered sample editor widget, a feature can be associated with a
TRIRIGA ID by entering a value in one of the number fields or text fields in the information panel. In the sample, the Issue Id field is used. You can use this same method in another editor widget to associate a feature to a value.
A user can draw a feature and associate it to a TRIRIGA record by clicking the
Show Table tab and selecting the Associate to selected feature icon for TRIRIGA record in the table. The next time that the record is queried, the feature displays on the map. This method uses the TRIRIGA ID as the common ID between
TRIRIGA and Esri.
When enabled, the as-delivered editor widget interferes with the bubble marker information provided by the pins. At the time of this release, there is no known workaround.
With the as-delivered proximity widget, when a user clicks a point on the map, the server processes a distance radius from that map. The data displayed on the
© Copyright IBM Corporation 2011, 2013. 7
To create a GIS Map record
map changes to only show buildings that fall within that proximity boundary. The proximity boundary is determined by the server.
Custom widgets are made up of compartmentalized JavaScript code specific to Esri widget functionality. This is a low-level feature that makes it possible for you to apply a custom Esri widget based on the Esri JavaScript API version 3.3. A custom widget might be something as simple as a map overlay or as complex as polygon editing.
When you add your code to the binary field in the widget, if it is part of the GIS Map object, it appends that code to the rendered map at runtime.
Widget Group Access. Identify the security groups that are authorized to access widgets in addition to members of the Admin Group. Users in one of the listed security groups or in the Admin Group can see a widget when the Add Security check box in the Widgets section is selected.
Geometry Service. When a geometry service is specified, that service is used to process transformation of projections for the Esri JavaScript viewer. You can reference that service in widgets and use that service for point projection.
Step 7
Click the Preview tab to see the map that is configured.
A user can save the basemap and extents of their current view by clicking the Show
Details tab and then the Save Preferences button. Clicking the Clear Preferences button returns the basemap and extents to the default values in the GIS Map record.
This information is saved by an association from the GIS Map record to the GIS User
Preferences object. The user can store preferences for each map.
A user can see the data that is represented on the map in a table by clicking the Show
Table tab. When the user selects a row in the table, the map zooms to the point on the map corresponding to that record and centers there.
When viewing the table results, you can click the
Export link in the upper-right corner of the table to download the results as a tab delimited text file.
The value in the Constructed URL field on the Preview tab and the System tab is the
URL for the map that is displayed in the Preview tab. You can copy this value to paste into a Location record to tie it to the map.
Specifying whether the ArcGIS API Is Online or
Hosted
Your ArcGIS API can be from an online server or an internal hosted server. A resource file in the EsriJS
ClassLoader record specifies where your API is sourced. The resource file for an online API must be named EsriJS_arcgis.js. The resource file for a hosted API, usually behind a firewall, must be named Esri_API_3.3.zip.
© Copyright IBM Corporation 2011, 2013. 8
The first time that any user loads any map, the software looks for these two files and connects to the service defined by the file that is in the EsriJS ClassLoader record. If neither file is present, a warning message is displayed. If both files are present, the online server is used.
To navigate to the EsriJS ClassLoader record, go to
Tools > System Setup > System > Class Loader.
Specifying the Location of Your Online API
You specify the location of your external online API in the resource file in the EsriJS ClassLoader record. The resource file must be named EsriJS_arcgis.js. After you complete the steps to create your EsriJS_arcgis.js file, the next time that any user accesses any GIS map, that map and all future maps are sourced from the external online API.
To create an EsriJS_arcgis.js file
Step 1
Go to http://js.arcgis.com/3.3/ and copy that file. It defines the service to which you subscribed. Rename the downloaded file EsriJS_arcgis.js. The Esri JavaScript
API must be sourced from a CDN provided by Esri and must be version 3.3.
Step 2
Open the EsriJS ClassLoader form and add a resource file named
EsriJS_arcgis.js
. Upload your EsriJS_arcgis.js file. Save the record.
Step 3
In the Navigation Builder, search for and add the GIS Map Manager Query to your navigation. You use this query to access the configuration manager for GIS.
Step 4
Refresh your screen and navigate to the GIS Map tab that you just added. Open the
Default Map record. Under Basemaps, click Find and bring in one of the default maps provided by Esri.
Step 5
Save the record. Click the Preview tab. The Preview tab shows the basemap you added. Confirm that the map is displayed.
Step 6
To display the map in tab sections and portal sections, copy the Constructed URL field and paste it into the Custom and External URL fields in records where the map is to display. The value for the Default Map is
/html/en/default/rest/EsriJS?map=Default Map
.
Specifying the Location of Your Hosted API
You specify the location of your internal hosted API in the resource file in the EsriJS ClassLoader record. The resource file must be named EsriJS_API_3.3.zip. After you complete the steps to create your EsriJS_API_3.3.zip file, the next time that any user accesses any GIS map, that map and all future maps are sourced from your internal hosted API.
To create an Esri_API_3.3.zip file
Step 1
Go to http://www.esri.com/apps/products/download/index.cfm?fuseaction=download.all
and download the ArcGIS API for JavaScript v3.3 API (arcgis_js_v33_api.zip). Extract
© Copyright IBM Corporation 2011, 2013. 9
To create an Esri_API_3.3.zip file
the files from that compressed file.
Step 2
Navigate to arcgis_js_v33_api\library\3.3\jsapi\init.js and open it with a text editor. Search for and modify the [HOSTNAME_AND_PATH_TO_JSAPI] to refer to the BASE_URL variable. Pay attention to the location of the quotation marks.
Find [HOSTNAME_AND_PATH_TO_JSAPI] in this line from the file from Esri: location.protocol) + '//' +
"[HOSTNAME_AND_PATH_TO_JSAPI]js/dojo/dojo"
Change that line to the following: location.protocol) + '//' + BASE_URL
+"js/dojo/dojo"
Save the init.js file.
Step 3
Navigate to arcgis_js_v33_api\library\3.3\jsapi\dojo\dojo\dojo.js and open it with a text editor. Search for and modify the
[HOSTNAME_AND_PATH_TO_JSAPI]
to refer to the BASE_URL variable. Pay attention to the location of the quotation marks.
Find [HOSTNAME_AND_PATH_TO_JSAPI] in this line from the file from Esri: location.protocol) + '//' +
"[HOSTNAME_AND_PATH_TO_JSAPI]js/dojo/dojo"
Change it to the following: location.protocol) + '//' + BASE_URL
+"js/dojo/dojo"
Save the dojo.js file.
Step 4
Navigate to arcgis_js_v33_api\library and select the 3.3 folder. Create a compressed file of that folder named EsriJS_API_3.3.zip.
Step 5
Open the EsriJS ClassLoader form and add a resource file named
EsriJS_API_3.3.zip
. Upload your EsriJS_API_3.3.zip. Remove the
EsriJS_arcgis.js
file from the resource files. Save the record.
Step 6
In the Navigation Builder, search for and add the GIS Map Manager Query to your navigation. You use this query to access the configuration manager for GIS.
Step 7
Refresh your screen and navigate to the GIS Map tab that you just added. Open the
Default Map record. Under Basemaps, click Find and bring in one of the default maps provided by Esri.
Step 8
Save the record. Click the Preview tab. The Preview tab shows the basemap you added. Confirm that the map is displayed.
Step 9
To display the map in tab sections and portal sections, copy the Constructed URL field and paste it into the Custom and External URL fields in records where the map is to
© Copyright IBM Corporation 2011, 2013. 10
To create an Esri_API_3.3.zip file
display. The value for the Default Map is
/html/en/default/rest/EsriJS?map=Default Map
.
Switching from Hosted API to Online API and Vice Versa
You can change from an internal hosted ArcGIS API to an online one, and back. The Resource Files section of the EsriJS ClassLoader record identifies the ArcGIS API in use. After you change the ArcGIS
API, the next time that any user accesses any GIS map, that map and all future maps are sourced from the new API.
To change the ArcGIS API
Step 1
Open the EsriJS ClassLoader form.
Step 2
Find the new API and add it to the Resource Files section.
Step 3
Remove the old API from the Resource Files section.
Troubleshooting GIS sections
GIS Tips
The rate at which the map refreshes when the user zooms in and out depends on the speed of the user’s Internet connection. Each time a user moves the map, a call is made to respond and redraw the map. The user’s Esri JavaScript viewer handles these actions. The time it takes to redraw the map depends on the speed of the network that is used. If you use an online service such as Esri, the commands are communicating over HTTP. If you use an in-house Esri server, your intranet determines the latency.
The labels within the bubble markers and in the table are defined by IBM TRIRIGA queries.
To put a marker on the map, the data must contain fields that are labeled Latitude and Longitude.
And the query that is used to display the data must pull the Latitude and Longitude fields from the data. When both conditions are met, the point that represents the Latitude and Longitude is marked on the map.
To display a location’s image in the bubble markers, the location data must contain a field that is labeled Image. And the query that is used to display the data must pull the Image field from the data. When both conditions are met, the Image displays on the map.
If locations do not appear on your GIS map, the cause might be one of the following:
The locations are not geocoded. In order for a location to display on the map, the record must be geocoded.
Your query does not return results.
Your ArcGIS server is down or not responding.
© Copyright IBM Corporation 2011, 2013. 11
GIS Tips
Use these standards for IBM TRIRIGA data to work properly with Esri:
All queries must resolve to a list of locations or entities.
The system is designed to have an initial query and a basemap.
A standard query can bypass these requirements and display any geocoded results returned on the map. The query must return columns with the latitude and longitude in the results.
Duplicate records in the table are caused by a data issue with your hierarchy structures. GIS uses a flattened hierarchy table. You can rebuild the flattened hierarchy structure.
To rebuild the flattened hierarchy structure:
1. Go to Tools > Builder Tools > Data Modeler.
2. Select
Utilities > Hierarchy Structures. The Hierarchy Structure Manager displays all hierarchies that are defined in the flattened hierarchy table.
3. For each of the following three hierarchies, click the hyperlinked name, then click the
Generate Data link: All Geographies, Building Spaces, and Buildings and Land.
If your GIS section contains a blank white screen instead of a map, check the following conditions:
The GIS configuration pages are set up properly.
Your ArcGIS server is up.
The ArcGIS ClassLoader is not set to debug mode.
You have a license to use the GIS map.
The Resource File section of the EsriJS Class Loader instance only contains the following four files: TRIRIGAIntegration.jar, EsriJS.jar, EsriJS_Assets.zip, and
EsriJS_LanguagePack.zip
. If your set of files is not correct, click Find and associate the correct files to the Resource Files section. These four resource files come with the asdelivered software, but it is up to you to add the online or offline API provided by Esri to enable the GIS map functionality.
If a message indicates that you do not have a GIS license, make sure your IBM TRIRIGA license file or files are up to date.
You define the URLs and ports that are used for creating the GIS map. You define basemaps, layers, and widget services such as the geometry service. The only exception is the Esri JavaScript API sourced from the Esri CDN. For more information about the services that are used with that API, see http://esri.com
. The offline API is self-contained and can be used behind your firewall.
© Copyright IBM Corporation 2011, 2013. 12
2. TRIRIGA Integration Object
The TRIRIGA Integration Object is a utility business object that contains the metadata that controls integration between IBM TRIRIGA and external systems. With the TRIRIGA Integration Object, an application builder uses standard IBM TRIRIGA tools, such as workflow and queries, to create integration touch points. The TRIRIGA Integration Object has a point-and-click interface and includes options for different types of integrations. You access the TRIRIGA Integration Object from
Tools >
System Setup > Integration > Integration Object.
The fields, sections, and tabs in the Integration Object form hide and show dynamically as you enter data into the form. You are presented with only the fields, sections, and tabs that are pertinent to the integration you are defining. The general process flow is to create the Integration Object record and then run that record. After the integration process completes, the record includes a section that contains the history of what happened when you ran the integration. Also, the record includes a tab that contains the records that were affected by the response. If there are any failures, you can find a detailed description of the failure and a method you can use to manually edit the failed step and resubmit it.
Creating Integration Objects
To Create an Integration Object Record
Step 1
Go to
Tools > System Setup > Integration > Integration Object. Click the Add action.
Step 2
Specify the details to define the integration.
Step 3
Click the Create action.
An initial Integration Object form has two sections in the General tab, the General section and the
Execute History section. The fields in the General section identify how the integration you are creating functions. The following table describes these fields.
Field Name
Name
Scheme
Direction
Description
The published name. The value of this field must be unique.
Tip
– Use the object – scheme - direction format for the name. For example, an inbound integration for People from a database would be named People – database – inbound.
The payload, protocol, and transport for the data. The four scheme types are: Database, File, File to DC, and Http Post.
The direction the integration travels from the view point of IBM
TRIRIGA. The two options are Inbound and Outbound. Each option dictates the elements that are displayed in the form and that can be configured for the integration.
© Copyright IBM Corporation 2011, 2013. 13
Field Name
Debug
Description
If you select the Debug check box, debugging is enabled for the integration. Using the Debug check box avoids having to bounce the server or to enable debugging with the Administrator Console. When active, debugging logs verbose data to the server.log file.
If you are in a production environment or a performance testing environment, do not select the Debug check box.
After you create the record, use the Execute action to start the integration. This action runs the triIntegration - Execute
workflow, which is described in more detail here . The Integration
Object record becomes read only and the status changes to Processing. When the integration processing is complete, if there were no errors, the Integration Object record transitions back to the
Ready state. If an error occurred during processing, the status displays as Failed, and the object is not transitioned. You must then manually inspect the errors that occurred.
You can override the inspection and transition the record back to the Ready state by clicking the
Complete action. The Delete action is available, but hidden.
You also can take advantage of the
Copy action to duplicate the Integration Object instance.
When you use object migration to move Integration Object instances from one environment to another, before you use an Integration Object in the new environment you must open any Integration Object and run the
ReMap action. The ReMap action updates all of the IDs that have been saved in your data maps and response maps. These maps contain IDs for modules, business objects, forms, and smart record data. It is important that you run ReMap to be sure that the IDs are updated for the new environment.
The following lifecycle diagram shows the state transitions for an Integration Object record.
State Transitions for an Integration Object Record
The records in the Execute History section contain the details about each integration. Each detail record contains the status, processing counts, and duration of the run. When an integration has errors, it also includes a log of the errors and a query section that lists the individual records that failed.
© Copyright IBM Corporation 2011, 2013. 14
When the Integration Object is triggered from a workflow, the Integration Object record that contains the full overview of errors also contains a truncated message in a hidden text field that can be displayed to the user, for example in an Attention message.
Note
– The Integration Object for outbound objects can process a maximum of 1000 records at one time. If there are more than 1000 records to be exported, create your workflow logic to run the Integration Object until all records have been processed.
Data Map Tab
The Data Map tab is present in the Integration Object form when you select the inbound direction for the integration. You use the Map section on the Data Map tab to map the data from the external source to fields within the IBM TRIRIGA business object.
The Map section can have two native IBM TRIRIGA fields: Integration Map and Last Updated. The rest of the page uses the servlet proxy technology to display data during communication with the data source through the IBM TRIRIGA Connector for Business Applications.
The Integration Map field is a binary field that stores the mapping that you define for how data is to be imported. The file is stored and parsed as a JavaScript Object Notation (JSON) object that contains the information that is collected from the Data Map tab. This data is stored as application instance data.
Selecting a Form
To map data to the correct objects within IBM TRIRIGA, you must select a form in the Map section.
To Select a Form in the Map Section
Step 1
Select a module.
Step 2
Select a business object.
Step 3
Select the form.
When you select the form, a tree representation of the form is displayed.
The Default Action field is used if the record to be imported cannot be found and must be created. If the record exists, the default action is ignored and the record is updated. The actions that are in the Default Action list are the transitions from the null state that are available for the record.
The form is displayed in a tree format with icons representing the type of object of the section or field in the tree. The hierarchy of the form tree is Form -> Tab -> Section -> Field.
Icon Representation Comment
Form
Tab
15 © Copyright IBM Corporation 2011, 2013.
Icon
Strike
Red
Representation
Smart Section
Graphics Section
Query Section
Multi-tab Section
Locator Field
Regular Field
Date Field
Read Only field
Required field
Comment
Triggers a popup to define how to identify the data element. There
is more information about using smart sections here .
Cannot be mapped
Cannot be mapped
Cannot be mapped
Acts as a standard field, but the integration fails if the data cannot be located or is not unique
Text fields treated as strings
Not displayed in the tree. You use the table to the right of the form tree to define the date format for the incoming data, so that it can convert to IBM TRIRIGA date format correctly.
A field with a strikethrough cannot be mapped, but it can be used as a key field to help identify the record.
It is required to create the record. This integration record fails if it is not mapped.
In the form tree, the labels display with names in parentheses. When you click a form name, tab, or section, the element is expanded. If it is a field, it is added to the table of columns on the right of the page. If it is a field from a smart section, you use the popup window to further identify the element.
Defining the Fields
You define the fields in the Integration Object on the right side of the form.
Field
Base Parent
Description
The Base Parent field is used for hierarchy objects, such as Location,
Organization, and Geography, to identify the root of the hierarchy.
To ensure that the record is created under the correct root of the hierarchy, you must specify the path in the Base Parent field. If you do not specify the path in the Base Parent field, the record is created at the same level as the root and you cannot see or get to the record from the form.
Type
Example: \Location
The metadata definition of the system field type. All fields are treated as strings.
Example: List
© Copyright IBM Corporation 2011, 2013. 16
Field
External isKey isParent
Default
Description
The name of the external field that you want to map to IBM TRIRIGA.
Because these values can be used for database columns or for formatted files, do not use spaces, special characters, or numbers.
Example: User_Language
Note
– When this column is used in the Response Map tab ,
the External field represents either nothing, or an xpath string, or a jsonPath string.
To update records in IBM TRIRIGA, you need the record ID to identify the record. If you select isKey, the value for that row of data is used as a filter for the queried object so that exactly one record ID is returned. If no record IDs or multiple record IDs are returned, the row creates a record with all values for the row.
Select isParent to identify this record as being a parent of another object so that the hierarchy can be created. When you select isParent, you use the popup window to select the business object, form, and field.
When the record is sent to IBM TRIRIGA, if the Integration Object finds that this incoming record has a field that is defined as a parent, the value for the incoming record is used as a filter in the query that is used to capture the record ID for the parent.
For the record to be placed as a child of another record, you must submit the update or create with the record ID of the parent in the request. If you define this value in the map, this is handled automatically.
If the parent is not found or multiple parents are returned based on the value submitted, then a warning is logged and the record is created at the same level as the root.
You can use the Default field to specify constant values to be applied for all instances of the record. If the Default field is populated, the
External value is ignored and the integration assumes that the column exists only in this mapping.
Example: US English
If you specified the Database scheme, you must run the
Generate
SQL for Table section action. Default values are set at the staging table ddl and are ignored at run time. Default values are only used at run time for File or Http Post schemes.
© Copyright IBM Corporation 2011, 2013. 17
Note
– After your mappings are complete, you must click the
Save Map action. If you click either the Save form action or the Save & Close form action, your mappings are lost; they are not saved.
When you save the map, the data you specified is collected and stored in the Integration
Map field in the Map section. The format of the field is a JSON object in a text file.
Using Smart Section Fields
A smart section is a section that is used to link to another business object. The data that is displayed on the primary record reflects data in a different object. A smart section field is a field that is linked to a smart section. For more information about smart sections, see the Application Building for the IBM
TRIRIGA Application Platform 3 book.
The IBM TRIRIGA Connector for Business Applications must have the record ID of the linked smart section. To get this value, the Integration Object takes the data value submitted for the field you identify, uses the value as a filter to query for the object, and returns a single record. This value is then passed to the IBM TRIRIGA Connector for Business Applications.
Each smart section field represents a link to another business object. When you select a field, you use the popup window to select the form to use as a filter. Next choose the field to be used as a filter to retrieve the record ID.
In the smart section popup window, if you select the Should this record fail if the association cannot
be made check box and the lookup for the record ID cannot find exactly one record, the submission of the record fails. If this check box is not selected and the record ID cannot be found, a warning is written to the log, but the record is created or updated.
Query For Outbound Section
The Query For Outbound section is present in the General tab when you select the outbound direction for the integration. The fields to be exported are copied from the IBM TRIRIGA database with the query identified in this section.
Selecting a Query
Outbound integrations can be defined using either a query from the IBM TRIRIGA Report Manager or a dynamic query.
Report Manager Query
If you use a query from the Report Manager,
To select a query in the Query For Outbound section
Step 1
Select a module.
© Copyright IBM Corporation 2011, 2013. 18
To select a query in the Query For Outbound section
Step 2
Either select a business object and a query name, or select Module Query and enter the query name.
Step 3
Select the action name for the action to be performed on the record after it has been exported. For example, you can call a workflow to flag the record to not be exported again. If you leave this field blank, no action is triggered.
Step 4
Optional: Select to include the record ID. You can use the query label as an element.
For XML-defined exports, there is a binary field for use with an XSLT to do
transformations. The record ID adds the field TRIRIGA_RECORD_ID for file outputs
and adds recordId for XML and JSON exports.
Use the Report Manager to define the query. For more information about creating queries with the
Report Manager, see the IBM TRIRIGA Application Platform 3 Reporting User Guide book. The mapping of data is done in the query definition. The report labels you specify for each field must represent the external table name, XML node name, label value, or the text field header column name.
Dynamic Query
If you use a dynamic query, the Integration Object form changes. The query name elements in the
Query For Outbound section disappear and the Data Map tab is added to the form. You use the Data
Map tab to create a map to dynamically call your query. In this use of the Data Map tab, instead of
defining how inbound data is to be mapped, you are selecting the fields to be exported and the labels represent the external data source to which the fields are mapped.
You use a dynamic query to specify default data for fields. For example, if you use the Http Post scheme and need to pass a static parameter or value. For default data to work correctly with a dynamic query, you first define your data map with the default data set and then you use the
You must use a dynamic query if you are using the Database scheme and need to export blobs. You can select binary, note, or Document Manager content fields for export.
Schemes
A scheme defines the payload, protocol, and transport for the data. The following table summarizes each scheme and includes a hyperlink to more information.
Scheme
Description
Uses a database table for importing or exporting data
Imports or exports using standard files
Loads files into DataConnect staging tables
Exports data via HTTP protocol
Inbound
Yes
Yes
Yes
No
Outbound
Yes
Yes
No
Yes
© Copyright IBM Corporation 2011, 2013. 19
Database Scheme
The Database scheme uses a database table to import or export data. When you select the Database scheme, the Integration Object form expands to open the Database section, in which you add or find data sources that can connect to your database.
When you select the Database scheme to import data, you use the Database section to define the
database tables from which to import data and you use the Data Map tab to map the external database
tables to IBM TRIRIGA fields.
When you select the Database scheme to export data, you use the Query for Outbound section to
define the data to be exported.
The fields in the Database section identify the data source.
Field
Datasource Name
Table Name
Description
The Datasource Name is a locator field that represents connections to various databases. You use this field to predefine data source access with a username, password, and connection string that can be reused for multiple Integration Objects. You can connect to as many databases as needed.
Click the search icon to see the list of existing data sources. From this list, you can add new data sources as needed. The name of the data source is used as a filter to find the correct data source when the Integration Object runs.
The name of the table from which the integration pulls data
(inbound direction) or to which the integration exports data
(outbound direction).
The Database section bar actions provide useful tools.
Action
Test DB Connection
Generate SQL for Table
Description
You select the Test DB Connection action to verify that the server can communicate with the database. The table name is used to run a select 1+1 from [table name]
query to the database. The color of the Database section header changes to red if an error occurred. To view the errors, review the server logs in the IBM
TRIRIGA administrator console. For information about the administrator console, see the IBM TRIRIGA Application Platform 3
Administrator Console User Guide book.
You select the
Generate SQL for Table action to create generic SQL to define your database table. Enter the name of the new database
table and complete the mapping on the Data Map tab before clicking
this action.
Each table used for inbound transactions must have the following columns:
© Copyright IBM Corporation 2011, 2013. 20
Action Description
IMD_ID
The transaction id. Unique to each entry in the table.
IMD_STATUS
The default status of Ready is used to identify records to be processed. The other states used are
Processing, Completed, and Failed.
Generate Test Data
IMD_MESSAGE
Used if there are any errors importing the row to contain the errors. The same errors are also displayed in the Integration Object form.
TRIRIGA
_RECORD_ID
The internal record ID that IBM TRIRIGA uses to identify the record being updated or created.
This sample code was generated for a People inbound integration using the fields defined above:
-- Auto generated script for MSSQL.
CREATE TABLE example_people_in (
IMD_ID NUMERIC (18, 0) IDENTITY(1,1) NOT NULL,
IMD_STATUS VARCHAR(1000) COLLATE SQL_Latin1_General_CP1_CS_AS null DEFAULT 'Ready',
IMD_MESSAGE VARCHAR(1000) COLLATE
SQL_Latin1_General_CP1_CS_AS null,
TRIRIGA_RECORD_ID VARCHAR(1000) COLLATE
SQL_Latin1_General_CP1_CS_AS null,
TRI_ID VARCHAR(1000) COLLATE SQL_Latin1_General_CP1_CS_AS null,
FIRST_NAME VARCHAR(1000) COLLATE SQL_Latin1_General_CP1_CS_AS null,
LAST_NAME VARCHAR(1000) COLLATE SQL_Latin1_General_CP1_CS_AS null,
LANGUAGE VARCHAR(1000) COLLATE SQL_Latin1_General_CP1_CS_AS null
)
This action is only available in the inbound direction. You select the
Generate Test Data action to load your database with test data.
After you create the database table and can connect to it, you can load your database with test data. You use the test data to run simple functional testing to verify that the mappings are correct and that the integration process works correctly. Enter the number of rows to be inserted into the database table in the Test Rows field.
The data generated is created as alphanumeric values. If you specify a default value on the Data Map tab, that value is inserted for all rows. This is useful when the field might be a locator field, a number field, a date field, or a list that requires a specific value.
If an external system is populating the staging database, the external system only needs to populate the non-metadata fields. The IMD_* columns are auto-populated. After the record is updated or created, the TRIRIGA_RECORD_ID contains the record ID that identifies this record in IBM TRIRIGA internally.
Blobs are supported for both inbound and outbound transactions in the Database scheme. The types of blobs supported are binary fields, note fields, and Document Manager content. Image fields are not
© Copyright IBM Corporation 2011, 2013. 21
binary content of the document on the object. Instead, you select any base object column (for example, a text field in the General section) to use as a place holder for your content. The external name can be whatever you want, but the Default Value column must be CONTENT. This is the trigger that connects the Document Manager object to the content.
File Scheme
The File scheme imports from standardized delimited flat files or exports to formats that include standardized delimited flat files and JSON, XML, or XSLT files. You can read from or write to anywhere on the network that the server can access.
When you select the File scheme, you use the File section to define the file. This section has different elements depending on whether the direction is inbound or outbound. This table describes the elements used for both.
Element
File Name
File Path
Delimiter
Description
The name of the file to be imported or exported.
The network folder containing the file.
The delimiter used for the file. The three options are Tab \t, Pipe
|
, and Double Colon ::.
Test File Access
You select the Test File Access action to determine if the integration object can connect to the file. After the connection is established, a workflow runs that attempts to read the file. The workflow also attempts to create a file in the directory specified, write to it, and then delete it. If everything is successful, then the color of the section bar changes to green and the text on the section bar changes to File Access Successful.
File Scheme Inbound
When you select the File scheme to import data, you can manually provide a binary field that is a copy of the integration field to be imported. You can use a manual field to assist in testing, so that localized processing can be repeated without overwriting the import file.
After a file has been imported, it is renamed with the processing date and moved to a folder named processed
.
If there are multiple workflow agents running in your IBM TRIRIGA environment, you must verify that either all servers have access to the file location or be sure that there is a copy of the file on all servers. This is because the workflow that runs during the Execute process for the integration needs to have access to the file regardless of which workflow agent starts the workflow.
File Scheme Outbound
When you select the File scheme to export data, additional fields in the File section provide information to the integration.
© Copyright IBM Corporation 2011, 2013. 22
Field
Overwrite
Export Type
File Header
Description
If you select the Overwrite check box, the file to be exported is named the File Name and overwrites any existing file with the same name. If this check box is cleared, the current timestamp is appended to the name of the file.
You choose the format of the outbound file. You can select the Flat option for standard delimited files, JSON, or XML. JSON and XML
adhere to the guidelines in the Outbound Formats section of this document .
This field is only available when the value of Export Type is Flat. If you enter a value in the File Header field, the text entered into this field is written to the export file before any other data is written to the file. For example, if you need to add copyright or processing instructions, you could place it here and the data in this field will be printed before the header columns are printed.
File to DC Scheme
The File to DC scheme imports delimited files into IBM TRIRIGA DataConnect staging tables. Use the
File to DC scheme if you do not have access to, or the training required to use, an ETL tool. With this scheme you can use workflows to process and validate data, giving you additional control over error handling.
For information about DataConnect, see the DataConnect chapter in the Application Building for the
IBM TRIRIGA Application Platform: Data Management book.
When you select the File to DC scheme, the Integration Object form expands to open a Database section, a File section, and a DataConnect section, as well as adding a Data Map tab.
After you define your mapping, save the map, and run the integration object, the entries are inserted into the DataConnect staging tables with an upsert action. You must select one or more fields in the
Data Modeler as a key. DataConnect uses the keys to determine if it needs to do an insert or an update to the row.
Database Section
The fields in the Database section identify the data source.
Field
Datasource Name
Description
The Datasource Name is a locator field that represents connections to various databases. You use this field to predefine data source access with a username, password, and connection string. You can connect to as many databases as needed.
Click the search icon to see the list of existing data sources. From this list, you can add new data sources as needed. The name of the data source is used as a filter to find the correct data source when
© Copyright IBM Corporation 2011, 2013. 23
Field
Table Name
Description
the Integration Object runs.
You must select a data source object that gives you access to the IBM
TRIRIGA S_ staging tables.
The name of the table from which the integration pulls data. For testing, you must use the value DC_JOB.
The Database section action tests the database connection .
The File to DC scheme is completely separate from the TRIRIGA internal APIs and uses the Connector for Business Applications to communicate with TRIRIGA. However, the API does not allow for inspection or manipulation of the DataConnect-related information. The File to DC scheme has code that goes directly against the database to inspect, read, and write to.
The following summarizes the access that is required to the tables needed for the File to DC scheme.
The tables other than DC_JOB and the S_ tables are used to determine the columns available for the
DataConnect objects and must have Read capabilities for the user selected in the data source.
Table
IBS_SPEC_TYPE_STAGE
Read
X
Write
IBS_SPEC_TYPE
X
SYS.COLUMNS
SYS.TABLES
(MSSQL)
(MSSQL)
X
X
IBS_MODULE
ALL_TAB_COLUMNS
(ORACLE)
X
X
DC_JOB
S_
tables
X
X
X
X
File Section
You use the File section to define the path on the computer or network to the file you want to import.
Element
File Name
File Path
Delimiter
Description
The name of the file to be imported.
The network folder containing the file.
The delimiter used for the file. The three options are Tab \t, Pipe
|
, and Double Colon ::.
© Copyright IBM Corporation 2011, 2013. 24
Element
Test File Access
Description
You select the
Test File Access action to determine if the integration object can connect to the file. After the connection is established, a workflow runs that attempts to read the file. The workflow also attempts to create a file in the directory specified, write to it, and then delete it. If everything is successful, then the color of the section bar changes to green and the text on the section bar changes to File Access Successful.
You can manually provide a binary field that is a copy of the integration field to be imported. You can use a manual field to assist in testing, so that localized processing can be repeated without overwriting the import file.
After a file has been imported, it is renamed with the processing date and moved to a folder named processed
.
If there are multiple workflow agents running, you must verify that either all servers have access to the file location or be sure that the file is on all servers. This is because the workflow that runs during the
Execute process for the integration needs to have access to the file and path specified.
DataConnect Section
The DataConnect section defines elements required for DataConnect functionality.
Field
Business Object
Concurrency
DataConnect Type
Description
The business object that this integration uses to trigger the workflow that is tied to DataConnect. The business objects are in the triDataConnectJob
module.
Select whether the DataConnect job runs as a single thread transaction or as a multi-tread transaction.
1 –
Standard
Creates one job for the one business object selected.
When this integration object runs, the process flow is
2 -
Multi a. New job number created from max DC_JOB number. b. New entry inserted into DC_JOB table with new job number, business object, and a status of 1 (New). c. Staging Table is loaded with job number, form name, state of 2 (Ready) and action of 4 (Upsert). d. DC_JOB table is updated to status of 2 (Ready).
The integration loads multiple staging tables and runs them as one job. You must select a value for
IntegrationObject Dependent. The objects do not
© Copyright IBM Corporation 2011, 2013. 25
Field Description
need to be correlated, but they are all available in the workflow.
When this integration object runs, the process flow is, a. New job number created from max DC_JOB number. b. New entry inserted into DC_JOB table with new job number, business object, and a status of 1 (New). c. Staging Table is loaded with job number, form name, state of 2 (Ready) and action of 4 (Upsert). d. Query for the IntegrationObject Dependent and repeat steps a through c until an object reached no longer has an IntegrationObject Dependent defined. e. DC_JOB table is updated to status of 2 (Ready).
IntegrationObject Dependent This field is used only when the value of DataConnect Type is 2 –
Multi
. It identifies the locator field to the other Integration
Objects.
Data Map Tab
In the File to DC scheme, you use the Data Map tab to define the mappings between the delimited file uploaded and the columns in the staging table defined for the object you select.
The Integration Map field is a binary field that stores the mapping that you define for how data is to be imported. The file is stored and parsed as a JavaScript Object Notation (JSON) object that contains the information that is collected from the Data Map tab. This data is stored as application instance data.
The list of modules is limited to the modules that have business objects that have been identified as
Has Staging Table in the Data Modeler. The list of business objects is specific to those that are marked for Has Staging Table.
When a business object is selected, a query runs and displays the database columns available in the staging table associated with the business object. The name of the staging table is populated in the
Staging Table field and is read only. You must specify a value in the Form field for the process to work correctly.
The list on the left side shows the fields defined in the Data Modeler as staging table fields. The elements that are grayed out with a strikethrough are used by the automatic process and cannot be mapped. The other fields are available and when clicked add another row to the table on the right.
The External column defaults to the column name, but you can change it to match your file header.
The isKey, isParent, and Default columns are read only and are not used.
Because you are mapping your file to the staging database columns, the first row of the file must have columns that match the External column. The sequence of the columns does not matter, but the column names are case sensitive. For example, if the External columns in the map are listed as Field1,
© Copyright IBM Corporation 2011, 2013. 26
Field2, Field3, then the actual external columns can be Field2, Field1, Field3. As long as the names are identical, the fields are applied correctly.
After your map is complete, you must click the Save Map action. If you click either the Save form action or the Save & Close form action, your mappings are lost. When you save the map, the data you specified is collected and stored in the Integration Map binary field in the Map section.
Http Post Scheme
The Http Post scheme exports data to a server using HTTP protocol. When you select the Http Post scheme, the Integration Object form expands to open an Http Post section and a Query for Outbound section, as well as adding a Response Map tab.
Http Post Section
You use the Http Post section to define the server to which the data is sent.
Tokens can be added to the values of the Http URL, Http URI, and Headers fields. A token is a value that is sourced from the query results for this post. The token name must exactly match the column label in your query. For example, to add the value from the column labeled accountId in your query results to the Http URI field, enter /ws/account/{accountId}/property in the Http URI field. At runtime, it renders the value returned in the query result. If the value of accountId is 123, then the
URI sent is /ws/account/123/property. The values in the last result row provide the tokens when a batch request is made using tokens.
Field
Post Type
Description
The format of the post. If you select XML format, the Query for
Outbound adds an XSLT for further transformation.
JSON
Runs the query specified in the Query for
Outbound section, converts the results to JSON format , and applies that as the entity of the
request made to the specified HTTP URL.
To batch all records as one submission, do not specify a response type.
To make a separate request for each record returned by the query, specify a response type.
This matches up the request/response to the correct records.
PARAMETER Runs the query specified in the Query for
Outbound section, converts each row into Post parameter name and value pairs, and submits each record separately. No batch submission.
QUERY_STRING Runs the query specified in the Query for
Outbound section, converts each row in URLappended, query string parameter name and
© Copyright IBM Corporation 2011, 2013. 27
Field
Response Type
Description
XML value pairs, and submits.
Although there is no data in the body of the
HTTP request and the URL has values appended to it, the request type is Post, not Get.
Runs the query specified in the Query For
Outbound section, converts the results to XML format , and applies that as the entity of the
request made to the specified HTTP URL.
To batch all records as one submission, do not specify a response type.
To make a separate request for each record returned by the query, specify a response type.
This matches up the request and response to the correct records.
The format for the response sent for each request. When selected, the integration expects the response to match up to fields defined in the Response Map tab.
Flat
The response expects a simple response string to be mapped to a field in IBM TRIRIGA. For example, if the response prints “Success” or “Failure”, you can map that string as-is to a field that can be used as a decision point in a post-processing workflow.
JSON
The response expects a response in the form of a JSON object. You define the JSONPath as the external field in the Response Map tab. JSONPath is a standardized, dot notation syntax to traverse a JSON object to a specific value.
The Response Map used to map a field to an IBM TRIRIGA value expects only simple definitions. If the element you want to map is in an array, you must specify the index of the array you want to continue down.
For example, candidates[0].location.x returns -
12819744.7565
in the following JSON object:
{
"spatialReference" : {
"wkid" : 102100
},
"candidates" : [
{
"address" : "6720 Via Austi Pky, Las Vegas, NV,
89119",
"location" : {
"x" : -12819744.7565,
"y" : 4309920.3012000024
© Copyright IBM Corporation 2011, 2013. 28
Field
Http URL
Description
XML
},
"score" : 100,
"attributes" : {
}
},
{
"address" : "6721 Via Austi Pky, Las Vegas, NV,
89119",
"location" : {
"x" : -12819812.309700001,
"y" : 4309994.186999999
},
"score" : 79,
"attributes" : {
}
}
]
}
The response expects the response to be in the form of an
XML object. You define the XPath as the external field in the Response Map tab. XPath is a standard, slash notation syntax to traverse a XML object to a specific node or value.
For more information on XPath, see http://www.w3.org/TR/xpath/ or http://www.zvon.org/xxl/XPathTutorial/General/example s.html
Although XPath provides a way to do complex definitions, the Response Map used to map a field to an IBM TRIRIGA value expects only simple definitions. If the element you want to map is in an array, you must specify the index of the array you want to continue down.
For example, //root/candidate/location[2]/x returns 5 in the following XML object:
<root>
<candidate>
<location>
<x>1</x>
<y>2</y>
</location>
<location>
<x>5</x>
<y>6</y>
</location>
</root>
</candidate>
After the integration process completes, the records that were affected by the response are listed in the Associations tab of the integration instance record with an association string of Sourced.
The dynamic portion of the location of the server receiving the data.
For example, when there is a production server and a test server, the value of the Http URL field changes to identify the server to be
© Copyright IBM Corporation 2011, 2013. 29
Field
Http URI
Request Method
Content-Type
Omit Request Entity
Send As Batch
Headers
Description
used and the value of the Http URI field does not change.
The static portion of the location of the server receiving the data.
For example, when there is a production server and a test server, the value of the Http URI field does not change; however, the value of the Http URL field changes to identify which server is to be used.
The HTTP request method.
DELETE
GET
The origin server is to delete the resource identified by the value of the value of the Http
URI field.
The origin server is to return a copy of the data for the resource identified by the value of the
Http URI field.
POST The origin server is to add the resource enclosed in the request as a new subordinate of the resource identified by the value of the Http URI field.
PUT
The origin server is to update the entity identified by the value of the Http URI field.
The format of the request header used to specify data in the body of an entity.
The Content-Type contains a list of tested formats for the request data. To use a Content-Type that is not in the list, you can add a custom Content-Type entry to the Headers field and leave this value blank. Note: While technically you should not experience any problems with setting the Content-Type and sending the Request
Entity in the same type, IBM TRIRIGA has only validated the Content-
Types in the list.
If selected, the body of the request is excluded from the request.
If selected, the records identified in the query are sent in a group instead of one at a time.
You can add custom headers to be sent with the request in the format {name}:{value}. For example, to send userID with the value 12345 in the header, set the value of this field to userID:12345
.
Unlike the Add To Header field, which is only used to encode authentication parameters, any name:value pairs that are specified in the Headers field are always added to the request. For example, the values for the Content-Type field provide some basic, commonly used options for Content-Type. You can provide your own value for
© Copyright IBM Corporation 2011, 2013. 30
Field
Use Auth Basic
Description
Content-Type adding your own header of
Content-Type:myCustomContentType
.
You use the other fields in the Http Post section to define the security.
Field
UserName Parameter
UserName
Add To Header
Description
This option only affects the Http Post scheme when the UserName field has a value.
If your post does not require user name and password parameters, the UserName Parameter field must be blank.
If your post does not require a user name and password, the
UserName field must be blank.
This option only affects the Http Post scheme when the UserName field has a value.
If selected, the values in the UserName Parameter field and the
Password Parameter field are added to the header of the request going out. The values of each are the corresponding UserName and
Password fields.
No encoding is provided. However, this option can be used as SSO where the token must be applied to the header.
This option only affects the Http Post scheme when the UserName field has a value.
If selected, the UserName field and the Password field must have values. When selected, an Authorization Basic encoding entry is added into the header of the request going out.
Use MaxAuth
The user name and password are concatenated with a colon : and then Base64 encoded. This is a standard security protocol.
This option affects the Http Post scheme only when the UserName field has a value. If selected, the UserName field and the Password field must have values. When selected, a MAXAUTH entry is added to the header of the request that is going out. The UserName and
Password are concatenated with a colon : and then Base64 encoded.
This is the security protocol for IBM Maximo.
If the UserName field has a value and both the Use Auth Basic check box and the Add To Header check box are selected, the scheme uses Use Auth Basic.
If the UserName field has a value and the Add To Header check box, Use Auth Basic check box, and Use
MaxAuth check box are all checked, the Use MaxAuth check box takes precedence.
© Copyright IBM Corporation 2011, 2013. 31
If the UserName field has a value and neither the Use Auth Basic check box nor the Add To Header check box is selected, the values in the UserName Parameter field and the Password Parameter field are added as post variables of the request going out. The values of each are the corresponding
UserName and Password fields. No encoding is provided.
Response Map Tab
The Response Map tab maps the response parameters from the request to an existing IBM TRIRIGA
the Data Map tab, and response mapping is only allowed for simple field values.
Outbound Formats
Element
JSON
Description
You can select JSON as the Post Type for the Http Post scheme or as the Export Type for the File scheme. When you select JSON, the
Query for Outbound section displays the Include Record ID check box.
XML
The format of the JSON object has two objects: data and header.
The data object contains an array of objects containing the label name and value for the columns from the outbound query and also includes the boId and recId if specified.
The following example shows a typical default JSON structure:
{
"data": [
{
“[column_label]”:”[column_value]”,
"boId": 10002100,
"recId": 2999294
},
…
],
"header": [
"[column_label]",
…
]
}
You can select XML as the Post Type for the Http Post scheme or as the Export Type for the File scheme. When you select XML, the
Query for Outbound section contains the Include Record ID check box, the XSLT binary field to contain the XSLT for any customized export formats, and the Use Query Label As Element check box, which determines whether the export uses the label from the query as the XML node.
The default XML structure includes three nodes for each column: field, label, and value. The following example shows this default XML structure:
<query>
<continueToken/>
<results total="13">
© Copyright IBM Corporation 2011, 2013. 32
Element Description
<result recordId="11430080" associatedRecordId="null" boId="106402">
<columns>
<column>
<field>triIdTX</field>
<label>HR_ID</label>
<value>1000000</value>
</column>
...
</columns>
</result>
...
</results>
</query>
If the Use Query Label As Element check box is selected, the default
XML structure changes. The label and value nodes are merged by using the label as a node. The following example shows the default
XML structure when the Use Query Label As Element check box is selected:
<query>
<continueToken/>
<results total="13">
<result recordId="11430080" associatedRecordId="null" boId="106402">
<columns>
<column>
<field>triIdTX</field>
<HR_ID>1000000</HR_ID>
</column>
...
</columns>
</result>
...
</results>
</query>
XML query results for dates include the raw values (the value stored in database) and the display value(the formatted value displayed to the user) and function as follows:
The following example shows the XML structure when the Use Query
Label As Element check box is not selected. displayValue is added to the XML results.
<column>
<field>Date</field>
<label><![CDATA[Date]]></label>
<value><![CDATA[1359964800000]]></value>
<displayValue><![CDATA[02/04/2013]]></displayValue>
</column>
<column>
<field>DateTime</field>
<label><![CDATA[Date_Time]]></label>
<value><![CDATA[1360009800000]]></value>
<displayValue><![CDATA[02/04/2013
12:30:00]]></displayValue>
</column>
The following example shows the XML structure when the Use Query
Label As Element check box is selected. [name]_display is added to the XML results.
© Copyright IBM Corporation 2011, 2013. 33
Element Description
<column>
<field>Date</field>
<Date><![CDATA[1359964800000]]></Date>
<Date_display><![CDATA[02/04/2013]]></Date_display>
</column>
<column>
<field>DateTime</field>
<Date_Time><![CDATA[1360009800000]]></Date_Time>
<Date_Time_display><![CDATA[02/04/2013
12:30:00]]></Date_Time_display>
</column>
Schema validation is available for the XML that implements XSLT.
You can use one of the following methods to trigger schema validation:
Either - In the XSD Location field, type the URL to a public hosted schema validation.
Or - In the XSD Location field, type the path containing the full name of the XSD that is uploaded into the XSD Files field. The file in the XSD Files field must be a .zip file.
If schema errors are found during the validation, the errors are logged in the Integration instance record. If the XSD Location field is empty, no schema validation occurs.
When the Validate Only check box is selected, the records are not submitted. Instead, the information is collected, formatted, and validated against the schema. If no errors are found, the Integration
Object record returns to the Ready state and the Execute History section shows the process and that the record count is zero. If errors are found, the Integration Object record is in the Failed state and the Execute History section shows the process and a count of the errors found. The error messages are captured in the instance record.
The Http Post scheme can call out to a URL and retrieve (and process) multiple records in the response. This feature is only available when the value of Response Type is XML. No query is needed; however, if you do submit a query, it should be limited to one record only as multiple records will make multiple calls. If you do not specify a query, you must set the Request Type to empty.
In the Response Map external field column, you must represent the section of the XML that is repeatable with the token [i]. If you set a key, it will update the record based on that. In the following example, to map to the Name node in the XML, you would set
//result[i]/columns/column/Name
, and to get the recordId attribute you would set //result[i]/@recordId.
<?xml version="1.0" encoding="UTF-8"?>
<query>
<continueToken/>
<results total="6">
<result recordId="11464082" associatedRecordId="null" boId="10025526">
© Copyright IBM Corporation 2011, 2013. 34
Element
XSLT
Description
<columns>
<column>
<field>triNameTX</field>
<Name><![CDATA[Default Map]]></Name>
<Name_display><![CDATA[Default Map]]></Name_display>
</column>
<column>
<field>triIdTX</field>
<ID><![CDATA[001]]></ID>
<ID_display><![CDATA[001]]></ID_display>
</column>
</columns>
</result>
<result recordId="11464531" associatedRecordId="null" boId="10025526">
<columns>
<column>
<field>triNameTX</field>
<Name><![CDATA[SecondMap]]></Name>
<Name_display><![CDATA[SecondMap]]></Name_display>
</column>
<column>
<field>triIdTX</field>
<ID><![CDATA[002]]></ID>
<ID_display><![CDATA[002]]></ID_display>
</column>
</columns>
</result>
...
The XSLT field is a binary field that can be used to house the style sheet to convert the default XML format from the outbound query to the format that your interface requires. This field is not required and if left blank exports the values from the query with the default XML structures. If the XSLT field is populated, you can use either the default or query label as element options to pass to your XSLT to further process or transform your data. Selecting the Use Query
Label As Element check box helps to identify the columns in your
XSLT file for processing.
You can find a utility for testing XSLT in real time at the following link: http://www.w3schools.com/xml/tryxslt.asp?xmlfile=simple&xsltfile= simple
Other Ways to Trigger Integration
Integration can be triggered from the Execute action on the Integration Object form. You also can
trigger integration if you need to filter the query used for an outbound integration with data from the currently running process. Additionally, the Integration Object makes it possible for external systems to call into TRIRIGA to trigger the Execute action or to retrieve the results of a TRIRIGA query in JSON format.
Triggering Integration from an Object
The following example demonstrates how to filter a query used for an outbound integration with data from the currently running process.
© Copyright IBM Corporation 2011, 2013. 35
For example, you made changes to a subset of records, but you only want to send a record when a user clicks an action. You can use a special Custom task object built into the Integration ClassLoader that uses workflow variables to set data. By using this feature, you can build out the subset of records in the workflow using the common methods and then pass the subset by reference to the Custom task and assign the Integration Object to trigger to a workflow variable named IntegrationObject.
The workflow below demonstrates the absolute minimum to enable this functionality to work.
Example: Basic Workflow
The Class Name field for the Custom task is set to
Integration:com.tririga.custom.integration.Parameter
. You must use this class name when implementing this method. The Parameter class inside of the Integration ClassLoader is implementing the CustomParamBusinessConnectTask Java Interface class with a signature of: public CustomParamTaskResult execute(TririgaWS client, Map params, long userId, Record[] records)
The params arguments are the assigned IntegrationObject variable so that the process has the instructions it needs to continue the integration. The records argument is the Records section in the
Custom task where you assign the records to use for the workflow process.
Instead of triggering the event on one object, you are passing two sets of objects to an event.
The Parameter looks for the Integration Object from the IntegrationObject variable and processes the results in the records argument passed in by running the query specified in the Integration Object
Query for Outbound section and filtering by the record IDs of the records passed in. By doing this, you are exporting with the common utilities, but you are no longer bound by all or nothing queries or by triggering the event directly from the Integration Object Execute action.
© Copyright IBM Corporation 2011, 2013. 36
To continue with the scenario, make the workflow asynchronous and set it to run when a person record is saved.
Example: Start Task
In the Query task named Query For Integration Object in the example, you query for the Integration
Object that you want to trigger and then filter the results of that query by name. You must have only one result.
© Copyright IBM Corporation 2011, 2013. 37
Example: Query Task named Query For Integration Object
In the Variable Definition task named Define IO as Variable in the example, you define the Integration
Object as a variable. The result of the query in the previous task is now assigned to this variable.
Example: Variable Definition Task named Define IO as Variable
© Copyright IBM Corporation 2011, 2013. 38
In the Variable Definition task named IntegrationInstance in the example, you define the Integration
Instance object as a variable. This variable is used for the return value from the Custom task at the end of the example.
Example: Variable Definition Task named IntegrationInstance
In the Query task named Query for subset of people in the example, you get the filtered set of records to be processed for the integration. The task calls a query named triEmployee – Find and filters for records where the value of the triFirstNameTX field contains Rodrigo.
© Copyright IBM Corporation 2011, 2013. 39
Example: Query Task named Query for subset of people
For any business object that is used in the Query that is passed to the Integration Object, you must include the triRecordIdSY field in the business object definition. At runtime, the Integration Object uses the triRecordIdSY field to retrieve the remaining fields in the object defined in the Data Map.
In the Custom task named Custom Task in the example, you pass the results of the Query for subset of people task as the list of records. The Class Name is
Integration:com.tririga.custom.integration.Parameter
to define the ClassLoader object named “Integration” and the path to the implementation class named “Parameter” that understands how to receive and process this information.
The Parameter class expects a variable named IntegrationObject to connect to the metadata. The return variable is needed to get the Integration Instance record. The name of the return value must be
IntegrationInstance
.
© Copyright IBM Corporation 2011, 2013. 40
Example: Custom Task
Triggering Integration from a URL
An external system can call into IBM TRIRIGA by passing parameters to trigger the Execute action of an
Integration Object or to retrieve the results of a query in JSON format.
Triggering an event externally from a URL that includes the credentials can only be performed on IBM
TRIRIGA Application Platform version 3.3 and later.
Authentication can be specified in one of three ways:
You can add the credentials to the Http Request Header in the form of Basic Authorization.
You can add USERNAME and PASSWORD parameters with their values to the header of the Http
Request in plain text.
You can add the USERNAME and PASSWORD parameters with their values to the query string of the Http Request or as Post parameters, in plain text.
© Copyright IBM Corporation 2011, 2013. 41
Triggering the Execute Action
To trigger an Integration Object externally, you set the credentials and then pass the added parameter of ioName in the query string with the name of the Integration Object. For example, to trigger a
Geocode Address Integration Object, you would call the following URL: http://localhost:8001/html/en/default/rest/Integration?USERNAME=system&PASSWO
RD=admin&ioName=Geocode +Address
This returns Successful if it was able to trigger the action on that record, or it returns the error message if there was an error.
Calling the Execute action on an Integration Object is an asynchronous event, so it is not possible to get the results of a process synchronously. Should you need more immediate feedback of the results, you could tie a notification event to the completion of the Integration Object to have the IBM TRIRIGA system notify you when the processing is complete. Another option is to poll IBM TRIRIGA for that information.
Retrieving Query Results
Any query defined in the Report Manager can be executed from a web address originating outside of
IBM TRIRIGA. To specify the query, you use following parameters:
Parameter Required / Optional
action Required
Description
Must be set to query module bo
Required if no continue token used
The name of the module of the query you are calling.
Optional The business object for the query. If there is more than one, omit this parameter. query Required if no continue token used
The name of the query to execute. f ct
Optional
Required if requesting next batch
The format you want returned. Options are:
json
– (default) minimized JSON string
pjson
– JSON string in print format that makes it easier to read
xml
– minimized XML string
pxml – XML string in print format that makes it easier to read
tab – tab delimited text
A continue token is returned when the results of the query are larger than the 1000 result default. When attempting to retrieve the next batch of records, you need to pass this parameter with the token specified in the previous response.
For example, this specifies a query for all employees: http://localhost:8001/html/en/default/rest/Integration?USERNAME=system&PASSWO
RD=admin&action=query&module=triPeople&bo=triPeople&query=triEmployee+-
+Find&f=pjson
© Copyright IBM Corporation 2011, 2013. 42
Error Handling
If there are failures during an integration, the record is not saved. The integration summary displays the errors that occurred, and each record that failed is represented as a Failure record. A Failure record contains an instance record representation that you can manually edit and resubmit.
The Resubmit Record field in an Instance Failure record is a note field that contains the key value pairs that represent the business object that you were trying to create or update. You can manually edit the data in the Resubmit Record field and then click the
ReSubmit form action to resubmit the record.
When a resubmitted record completes successfully, the name of the record changes from Failure to
Successful and the text in the Error Message field and the Resubmit Record field is cleared. The
Integration Instance records counts are updated to reflect the correct values, that is, the number in the Records Successful field is increased by one and the number in the Records Failed field is decreased by one. When the Record Failed count is equal to zero, click the Complete action on the
Integration Object form.
Geocode Example
You can set up an Integration Object record that uses the Http Post scheme to export information to an
Esri server and map data from the response back to the Location records to update the geocodes.
Note that the Http URL in this example provides Esri geocoding services through their REST API. The
Esri geocoding service expects the request to contain parameters in the string to know what addresses to geocode. The response is in JSON format. The web address in this example is http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddres sCandidates
© Copyright IBM Corporation 2011, 2013. 43
Geocode Example: General Tab
You use the Data Map tab to define the fields to be extracted from IBM TRIRIGA. The values in the
External column are the names used for the parameters added to the query string. In the example, there are two additional parameters, outSR and F, that specify the WKID and format that the Esri service expects. The other fields are dynamically pulled from the Location records in IBM TRIRIGA.
Geocode Example: Data Map Tab
The Response Map tab handles the response from Esri and maps the latitude and longitude to the
Location record. Note that since the response is in JSON format, the syntax in the External columns is in JSONPath.
© Copyright IBM Corporation 2011, 2013. 44
Geocode Example: Response Map Tab
When the Execute action is triggered, the following occurs:
1. The values in the Data Map tab are used to construct a dynamic query and the query is called.
2. Because the value of the Post Type field is QUERY_STRING, each result from the query is transformed into something similar to the following URL (the actual parameters depend on the data in IBM TRIRIGA): http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/find
AddressCandidates?Address=6720+Via+Austi+Pkwy&ZIP=89119&City=Las+Vegas&
State=Nevada&outSR=102100&f=json
3. The response looks like the following JSON object:
{
"spatialReference": {
"wkid":102100,"latestWkid":3857
},
"candidates": [{
"address":"6720 Via Austi Pky, Las Vegas, NV, 89119",
"location": {
"x":-12819684.945332458,
"y":4309927.0270621451
},
"score":100,
"attributes": {
}
},
{
"address":"6720 Via Austi Pky, Las Vegas, NV, 89119",
"location": {
"x":-12819744.862808136,
"y":4309924.3334144857
},
"score":100,
"attributes": {
}
},
{
"address":"6721 Via Austi Pky, Las Vegas, NV, 89119",
© Copyright IBM Corporation 2011, 2013. 45
"location": {
"x":-12819808.664131654,
"y":4309995.0691041043
},
"score":79,
"attributes": {
}
},
{
"address":"Via Austi Pky, Las Vegas, NV, 89119",
"location": {
"x":-12819804.948472099,
"y":4309871.0261052754
},
"score":100,
"attributes": {
}
}]
}
4. The values in the Response Map tab specify that the integration needs to extract candidates[0].location.y and candidates[0].location.x from the JSON object and map them to the triGisLatitude and triGisLongitude fields in IBM TRIRIGA.
5. The Location record is updated with the new data.
6. Since no action was specified for the data being sent out of IBM TRIRIGA in the Query for
Outbound section, no actions are triggered on the Location data.
7. The final tally of the integration process is collected and an Execute History object is created with the information and any errors that may have occurred.
Additional Resources
Upgrading the TRIRIGA Integration Object
When a new installer is available for the IBM TRIRIGA Application Platform, you can specify whether the platform installer is to update the TRIRIGA Integration Object when it runs. To signal to the platform installer that it should not upgrade the TRIRIGA Integration Object, before starting the platform installer, create an Integration Object record named IGNORE_UPGRADE. Do not execute the record; the record only has to be present in the system. Then, when the platform installer runs, it does not update the Integration Object even if the platform installer build is newer than the current installed platform version.
If you do not create an Integration Object record named IGNORE_UPGRADE, when the platform installer runs, it updates the Integration Object if the platform installer build is newer than the currently installed platform version.
Object Glossary
The following objects are the elements in the Integration Object. They are delivered with this adapter and are listed here for quick reference.
© Copyright IBM Corporation 2011, 2013. 46
Object
Integration Object
(triIntegration)
Integration ClassLoader
Description
triIntegration
is the primary business object. It contains the integration metadata definition.
DataSource
(triDataSource) triIntegrationI nstance
(triIntegration
Instance
Instance Failure
(triIntegration
InstanceFailure
)
)
This object contains property settings for connecting to a database. This object is referenced in the Integration Object as a single-record smart section. This allows the reuse of datasource definitions across multiple Integration Object definitions.
This object contains the information about a specific instance of an integration run. It contains the counts, the time it took to run, a collection of error messages (if any), and a query section with details for each record that failed. The object has associations to records that were affected by the response.
This object is contained within the
Integration Object record as the Execute
History section.
This object contains details of a single record that failed for an inbound integration. It contains the error message for the failure and a simplified representation of the record that was submitted that can be manually edited and resubmitted.
The Integration Object requires the use of a TRIRIGA ClassLoader instance object named Integration. The Integration ClassLoader object is made up of three elements in the Resource Files query section. They are TRIRIGAIntegration.jar,
TRIRIGAIntegration_Assets.zip
, and jtds-1.2.5.jar.
Note
– IBM TRIRIGA is delivered with the Oracle JDBC driver, which you use when connecting to an Oracle database. IBM TRIRIGA does not include a database driver for MSSQL. If you are connecting to a MSSQL server database, you must include a MSSQL driver such as the jtds-1.2.5.jar and create a Resource File with this library included, attached to the Integration
ClassLoader object.
© Copyright IBM Corporation 2011, 2013. 47
Object Description
TRIRIGAIntegrat ion.jar
TRIRIGAIntegrat ion_Assets.zip
This Java jar file contains all of the classes used for the TRIRIGA Integration Object components. The Java classes in this jar are written to work in conjunction with the
TRIRIGA Integration Object. There are
Custom workflow task entry points as well as a communication layer used by the
TRIRIGAIntegration_Assets.zip
file elements.
This zip file contains all of the HTML,
JavaScript, CSS, and images used by the
DataMap custom tab on the Integration
Object for inbound integrations. The
JavaScript communicates with the Java API of IBM TRIRIGA Connector for Business
Applications with the use of URI-based
Servlet Proxy handles. The server side elements are contained within the
TRIRIGAIntegration.jar
.
Standard Workflows
Workflow
triIntegration -
Execute
Description
Asynchronous
This workflow is triggered when the user selects the Execute action.
This is the primary workflow. The following diagram shows the standard workflow:
© Copyright IBM Corporation 2011, 2013. 48
Workflow Description
triIntegration -
Generate Test Data
The workflow controls the status displayed to the user. The Trigger
Integration task is a Custom workflow task that calls
Integration:com.tririga.custom.integration.Integrati
on
and is the primary entry point for all Integration Objects. The information about what to do during the integration is defined in the
Integration Object and is passed by record ID to the Custom task. triIntegration -
Generate SQL for Table
Synchronous
This workflow is triggered from the Database section action to generate the SQL for use with your staging tables.
Synchronous
This workflow is triggered from the Database section action to generate randomized data that populates your staging tables to be used for testing, such as functional testing or load testing. triIntegration -
HideShow Data Sections
Synchronous
This workflow is triggered from the initial loading of a new
Integration Object as well as various elements on the form as an
OnChange workflow. This workflow shows and hides the form elements as needed for the integration you are defining.
© Copyright IBM Corporation 2011, 2013. 49
Workflow Description
Synchronous triIntegration -
PreLoad triIntegration –
Resubmit
This workflow is called when a new Integration Object is opened. It calls the triIntegration – ResetMetaData and triIntegration – HideShow
Data Section workflows. triIntegration - Reset
MetaData
Synchronous
This workflow resets the form elements that are to be blanked out.
It is called from the triIntegration – PreLoad workflow.
Asynchronous
This workflow is triggered when you resubmit a failed record from the triIntegrationInstanceFailure record. triIntegration - Test
DB Connection
Synchronous triIntegration - Test
File Access
This workflow is triggered from the Database section action to call select count(1) from {table_name}
on the database defined to validate that it can communicate and execute SQL commands on that database.
Synchronous triDataSource - Reset
Metadata
This workflow is triggered from the File section action to Create,
Read, and Delete a file to the directory or network location specified.
Asynchronous triDataSource - Test
DB Connection
This workflow resets the triDataSource record.
Synchronous
This workflow is triggered from the triDataSource record to call select count(1) from {table_name}
on the database defined to validate that it can communicate and execute SQL commands on that database
Standard Queries
Manager Default - Integration Objects
triIntegration - get Instances
triIntegration - getIntegrationObject
triDatasource - getIntegrationObject datasource
triIntegrationFailures - Get all failures
© Copyright IBM Corporation 2011, 2013. 50
Standard Lists
The lists are in the triIntegration module.
triDataConnectTypeLI
triDbDriverName
triFileExportTypeLI
triIntegrationDirection
triIntegrationFileDelimiter
triIntegrationPostTypeLI
triIntegrationType
Determining the Integration Version
To determine which version of the Integration Object you have installed, you go to the http://{localhost:8001/context}/html/en/default/rest/Integration
web address. The result displays the build date, number, and version number for the version you are currently running.
User Guides
See the following IBM TRIRIGA user guides for more information about the IBM TRIRIGA Application
Platform, such as workflows, the Data Modeler, business objects, forms, queries, state transitions, the
IBM TRIRIGA Connector for Business Applications, ClassLoaders, and Servlet Proxy.
Application Building for the IBM TRIRIGA Application Platform 3
Application Building for the IBM TRIRIGA Application Platform 3: Data Management
IBM TRIRIGA Application Platform 3 Connector User Guide (this book)
IBM TRIRIGA Connector for Business Applications 3 Technical Specification
© Copyright IBM Corporation 2011, 2013. 51
Appendix A: Class Loaders and Servlet
Proxies
The extended functionality from IBM TRIRIGA connectors uses class loaders, resource files, custom tasks, custom parameters, custom transitions, servlet proxies, the Java programming language, and the
IBM TRIRIGA Connector for Business Applications web service interface.
With IBM TRIRIGA connectors, you can write extended functionality and distribute that functionality in an object migration package. Connectors use the ClassLoader business object and resource files, and custom workflow components such as CustomTask, CustomParameters, and CustomTransitions. The servlet proxy is an extension of class loaders. The servlet proxy gives a handle to the Java IBM TRIRIGA
Connector for Business Applications (CBA) API. CBA uses Java servlet-style programming for integration into external systems with custom form components.
Before you create IBM TRIRIGA connectors, you must be familiar with the IBM TRIRIGA Application
Platform builder tools, the IBM TRIRIGA Connector for Business Applications web interface, and the
Java programming language. A connector can be implemented with the Java programming language only.
Custom Class Loaders
The IBM TRIRIGA Custom ClassLoader components work in tandem to deploy Java classes into the application server domain. Below is a diagram of how that works:
© Copyright IBM Corporation 2011, 2013. 52
Custom ClassLoader
Accessing Custom Java Classes from a Custom Task
When you create a ClassLoader instance, you can add custom Java classes to the class path of the application server in one of three ways: Parent First, Parent Last, and Isolated. These classes can be accessed via a Custom task in workflow for programmatic interaction or can be extended to work as a
Java servlet. Either method extends the form capabilities for portal sections and custom tabs in objects.
To access your classes from a Custom task that is loaded through the ClassLoader, make sure that the following elements are in place.
To Access Your Classes from a Custom Task
Step 1
Start your class packages with one of the following three structures. Any other structure is blocked.
com.tririga.ps
com.tririga.appdev
com.tririga.custom
Step 2
Specify the ClassLoader name followed by a colon in the ClassName field in the workflow Custom task.
© Copyright IBM Corporation 2011, 2013. 53
To Access Your Classes from a Custom Task
For example, if you have a ClassLoader instance named MyClassLoader and your entry class is com.tririga.custom.myclassloader.Hello, the value in your
ClassName field is:
MyClassLoader:com.tririga.custom.myclassloader.Hello
When you use this naming convention, workflow can search for your class within the context of the specified class loader.
Step 3
Implement one of the com.tririga.workflow.pub.CustomTask objects available from the as-delivered TririgaCustomTask.jar in the
<IBM_TRIRIGA_INSTALL_FOLDER>/tools/BusinessConnect
folder.
For development, you must include the TririgaBusinessConnect.jar file and the TririgaCustomTask.jar file in your IDE classpath. If you include these libraries in the ClassLoader business object, they are ignored.
To research how a Custom task is implemented and what it offers you, read the “Custom Task” section of the “Workflow” chapter in the Application Building for the IBM TRIRIGA Application Platform 3 book. The ClassLoader object only provides an easy handle to hot deploy and safely manage your
Custom task implementations. It does not add to or change the functionality of a Custom task.
The Application Building for the IBM TRIRIGA Application Platform 3 book instructs you to put your files into the application server lib directory. You can forego that step, which gets complicated when you have multiple servers. Instead, add the class loader to the database and have the container intelligently extract and use the classes.
Loading your Files into the Class Loader
You put your files into the class loader to make them available. Follow these steps to load your files into the class loader.
To load your files into the class loader
Step 1
Go to
Tools > System Setup > System > Class Loader.
Step 2
Select
Integration.
Provide a unique name and the class loader type. In the Resource Files section, add your classes and form assets, such as HTML, Flash, js, image, and property files.
In each resource file record, upload the file to be used for this class loader in the
Resource File field. A resource file can be used in more than one class loader.
A good rule of thumb is to prefix library names with an abbreviation of the class loader and the real name of the library.
If you are uploading a .jar file, only the .class files are loaded into the class path. If
© Copyright IBM Corporation 2011, 2013. 54
To load your files into the class loader
you have many assets (for example, html files, js files, and image files), you can collect them into a compressed file and upload them as a single file. You also can upload a file individually, such as a configuration file, so that you can more easily modify it.
Development Mode
In development mode, you can change files and see your changes with a refresh of the page without uploading them to the ClassLoader object.
If you have access to the <IBM_TRIRIGA_INSTALL_FOLDER>/userfiles/<ClassLoaderName> folder, you can select the Development Mode check box in the ClassLoader object. When this check box is selected, the class loader ignores the revision number and pulls from the
<IBM_TRIRIGA_INSTALL_FOLDER>/userfiles/<ClassLoaderName>
folder.
The file types that you can change include HTML, JS, flash, and images.
Attention – If you clear the Development Mode check box, the system pulls the latest files from the class loader and can overwrite your work.
© Copyright IBM Corporation 2011, 2013. 55
Servlet Proxies
The servlet proxy is an extension of the class loader. You use it to develop servlet-style classes that can render, redirect, and communicate with form assets within your ClassLoader object. The assets must be uploaded to the ClassLoader object as resource files.
The following diagram shows how the Servlet Proxy works on the server:
Servlet Proxy
Configuring a Servlet Proxy
For your servlet proxy to render correctly and pass through your code, you implement a Java Interface class that is contained in the TririgaCustomTask.jar file.
Setting up your Servlet Proxy to render correctly and pass through your code
Step 1
Create a Java class in the package com.tririga.custom and implement the com.tririga.pub.adapter.IConnect
Java Interface.
© Copyright IBM Corporation 2011, 2013. 56
Setting up your Servlet Proxy to render correctly and pass through your code
The com.tririga.custom package is the only package that you can use to create an implementation class. It must be unique.
Implement the execute method in the IConnect class.
For example, if your class is named MyFirstConnector, your code is: public class MyFirstConnector implements IConnect { public void execute(TririgaWS tws, HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException {
//your code goes here.
}
}
This example has a handle to a TririgaWS interface class. This class is the Java interface for the IBM TRIRIGA Connector for Business Applications API. The example also shows a basic request and response that you would normally have in a Java servlet.
Step 2
Continuing with the example, add the following code to the execute method where it says your code goes here.
PrintWriter out = response.getWriter(); try{ response.setContentType("text/html"); out.println("<html><head></head><body marginwidth='0' marginheight='0' style='margin:0;padding:0;border:0;'>"); out.print("Hello World"); out.println("</body></html>"); out.flush();
} finally { if(out!=null)out.close();
}
This prints an HTML page with the words, “Hello World”.
Step 3
Compile this class and add it to a .jar file named MyFirstConnector.jar.
Step 4
Go to Tools > System Setup > System > Class Loader and click Add.
The ClassLoader name and the Java class that implements IConnect must have the same name. You can have only one IConnect implementation class per ClassLoader object. In the example, this class is named MyFirstConnector, and that is what you must name your ClassLoader instance.
Step 5
Add a new Resource File record and upload your MyFirstConnector.jar file. Click
Save.
When you modify, add, or remove a resource file from a ClassLoader record, a workflow runs that increments the revision number. A change to this revision number tells the IBM TRIRIGA Application Platform to reload this ClassLoader record.
Your Servlet Proxy is now configured and ready to be accessed.
© Copyright IBM Corporation 2011, 2013. 57
Accessing a Connector
If you have configured your example MyFirstConnector Servlet Proxy correctly, it is available at the following URL: http://<yourserver>/html/en/default/rest/MyFirstConnector.
You must have a valid login to access this URL. The easiest way is to add this URL to an external link section for a portal section or within a custom tab external link within any form.
All access to your Servlet Proxy is from this base URL. When you run the base URL in this example, your screen displays the words, “Hello World.”
To access the files within your ClassLoader resource files, append the word resource to the base URL, followed by the path to the resource you want to load. For example, if you have an image as a resource file named helloWorld.jpg, you can load this image dynamically with this URL: http://<yourserver>/html/en/default/rest/MyFirstConnector/resource/helloWorld
.jpg
The server checks to see whether this resource is loaded. If not, it pulls the file from the binary
Resource File field on the Resource File record and places it into the
<IBM_TRIRIGA_INSTALL_FOLDER>/userfiles/<ClassLoaderName>
folder. When a request is made, the server checks the cache and matches it to the revision number in the class loader. If the revision numbers are different, it reloads all the files that are not part of a .jar file into this directory.
Then, it refers to this location for each subsequent request.
Your files are available on any application server and are automatically refreshed each time that a change is made. You do not need to bounce the server to refresh the class loader.
Troubleshooting Class Loaders and Servlet Proxies
The following tips describe common ways to resolve issues with the ClassLoader, the servlet proxy, and your custom connector.
Concern Remedy
How to start platform logging In the Administrator Console, in the Platform Logging managed object, turn on debugging for the Class Loader and the Servlet Proxy objects. These logs are verbose and give you a good understanding of what the server is doing. For information about how to access and use the Administrator Console, see the IBM TRIRIGA Application
Platform 3 Administrator Console User Guide book.
Simplify debugging of class loaders and servlet proxies
To add a custom category to the Platform Logging managed object in the Administrator Console, add the custom category to the
CustomLogCategories.xml
file and restart the server. The
CustomLogCategories.xml
file is in the
<IBM_TRIRIGA_INSTALL_FOLDER>/config
folder. This method is preferred because you set it up one time. If the server is restarted, you can turn DEBUG back on by selecting the check box for your custom category.
© Copyright IBM Corporation 2011, 2013. 58
Concern
.jar files do not deploy as expected
Remedy
Do not add multiple instances of the same .jar file to a Class Loader record. For example, one added directly and one contained within a compressed file. When this occurs, the instance of the .jar file that is loaded is not predictable.
© Copyright IBM Corporation 2011, 2013. 59
INDEX
Add Security ............................................ 6
Basemaps Section ..................................... 6
Blank White Screen .................................. 12
Bubble Marker .......................................... 3
Bubble Marker Label ................................. 11
Clear Preferences ..................................... 8
Complete ............................................... 14
Constructed URL ....................................... 8
Creating a Custom GIS Portal Section .............. 4
Custom ClassLoader .................................. 52
Custom Widget ......................................... 6
CustomLogCategories.xml .......................... 58
Data Map Tab ..................................... 15, 26
Database Scheme ..................................... 20
DataConnect ........................................... 23
Debug ................................................... 14
Development Mode ................................... 55
Direction ............................................... 13
Duplicate Records .................................... 12
Esri_API_3.3.zip ........................................ 8
EsriJS_arcgis.js ......................................... 8
Example Widgets ...................................... 6
Execute ................................................. 14
Execute History Section ............................. 14
Export ................................................... 8
External ................................................. 4
File Scheme ............................................ 22
File to DC Scheme .................................... 23
Flattened Hierarchy .................................. 12
Form Builder ............................................ 4
Generate SQL for Table ............................. 20
Generate Test Data .................................. 21
Geometry Service ..................................... 6
GIS ........................................................ 2
GIS Map .......................................... 3, 4, 12
GIS Portal Section ..................................... 3
GIS Tab .................................................. 4
Hosted Server .......................................... 8
Http Post Scheme .................................... 27
Icon ...................................................... 6
Initial Extents Section ................................ 5
Integration ClassLoader ............................. 47
Integration Map ....................................... 15
Integration Object .............................. 13, 47
Isolated ................................................ 53 jar files ................................................. 59
Layers Section ......................................... 6
Map Refresh Rate ..................................... 11
Map Section ........................................... 15
Metric Query ........................................... 5
Missing Location on GIS Map ........................ 11
No GIS License ........................................ 12
Online Server ........................................... 8
Options Tab ............................................ 6
Parent First ............................................ 53
Parent Last ............................................ 53
Pin Color ................................................ 6
Platform Logging ..................................... 58
Preview Tab ............................................ 8
Published Name ...................................... 13
Query For Outbound Section ....................... 18
Query List Section ..................................... 5
Query Standards ...................................... 12
Response Map Tab .................................... 32
Save Map .......................................... 18, 27
Save Preferences ................................... 3, 8
Scheme ................................................. 13
Security Group ......................................... 6
Servlet Proxy .......................................... 56
Show Details Tab ................................... 6, 8
Show Table Tab ..................................... 6, 8
Smart Section ......................................... 18
Spatial Query Data Service .......................... 2
System Tab ............................................. 8
Table .................................................... 3
Test DB Connection .................................. 20
Token ................................................... 27 triIntegration .......................................... 47
TRIRIGA ArcGIS Connector ........................... 2
Widgets Section........................................ 6
WKID ..................................................... 5
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information about the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual
Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the products and/or the programs described in this publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758
U.S.A.
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
Privacy Policy Considerations
IBM Software products, including software as service solutions, (“Software Offerings”) may use cookies or other technologies to collect product usage information, to help improve the end user experience, to tailor interactions with the end user or for other purposes. In many cases no personally identifiable information is collected by the Software Offerings. Some of our Software Offerings can help enable you to collect personally identifiable information. If this Software Offering uses cookies to collect personally identifiable information, specific information about this offering’s use of cookies is set forth below.
This Software Offering does not use cookies or other technologies to collect personally identifiable information.
If the configurations deployed for this Software Offering provide you as customer the ability to collect personally identifiable information from end users via cookies and other technologies, you should seek your own legal advice about any laws applicable to such data collection, including any requirements for notice and consent.
For more information about the use of various technologies, including cookies, for these purposes, see
IBM’s Privacy Policy at www.ibm.com/privacy and IBM's Online Privacy Statement at www.ibm.com/privacy/details in the section entitled “Cookies, Web Beacons and Other Technologies” and the "IBM Software Products and Software-as-a-Service Privacy Statement" at www.ibm.com/software/info/product-privacy/ .
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at
“ Copyright and trademark information ” at www.ibm.com/legal/copytrade.shtml
.
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
Integration with other systems
Data mapping and transformation
Outbound data transfer
Error handling
Custom class loading
Servlet proxying
Frequently asked questions
The TRIRIGA Integration Object is a utility business object that provides a framework for integrating TRIRIGA with other systems. It enables you to define integration objects, data maps, and outbound data transfer schemes.
You can configure the IBM TRIRIGA ArcGIS mapping tool by accessing Tools > System Setup > GIS Map. This tool allows you to define basemaps, layers, queries, and other GIS-related settings.
You can trigger integration from a URL by specifying the appropriate URL parameters. For example, you can use the URL /html/en/default/rest/integration/trigger?integrationObject=MyIntegrationObject&objectId=123 to trigger the integration for an object with ID 123.
