tibco activematrix businessworks plug-in for odata user's ......with tibco activematrix...

TIBCO ActiveMatrix BusinessWorks™

Plug-in for ODataUser's GuideSoftware Release 6.0May 2016

Two-Second Advantage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCHEMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (ORPROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THEEMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANYOTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS ANDCONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTEDSOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THECLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOADOR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE)OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USERLICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THESOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, ANDYOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BEBOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright lawsand treaties. No part of this document may be reproduced in any form without the writtenauthorization of TIBCO Software Inc.

TIBCO, Two-Second Advantage, TIBCO ActiveMatrix BusinessWorks, TIBCO ActiveMatrixBusinessWorks Plug-in for OData, TIBCO Business Studio, and TIBCO Enterprise Administrator areeither registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or othercountries.

All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOTALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASEDAT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWAREVERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICALERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESECHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCOSOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S)AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE,INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright © 2015-2016 TIBCO Software Inc. All rights reserved.

TIBCO Software Inc. Confidential Information

2

TIBCO ActiveMatrix BusinessWorks™ Plug-in for OData User's Guide

Contents

TIBCO Documentation and Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

Product Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Creating a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Creating an OData Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Configuring a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Testing a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

Deploying an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

TIBCO Business Studio Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

OData Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

OData Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

OData Query Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

OData Modify Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Query URI Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Object Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Resource Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Query Option and Output Preview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Filters Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Columns Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Orders Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Expands Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Pagination Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Modify URI Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Working with the Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Importing the Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Running the Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Managing Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Setting Up Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Exporting Logs to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

3


TIBCO Documentation and Support Services

Documentation for this and other TIBCO products is available on the TIBCO Documentation site. Thissite is updated more frequently than any documentation that might be included with the product. Toensure that you are accessing the latest available help topics, please visit:

https://docs.tibco.com

Product-Specific Documentation

Documentation for TIBCO products is not bundled with the software. Instead, it is available on theTIBCO Documentation site at https://docs.tibco.com/products/tibco-activematrix-businessworks-plug-in-for-odata. To directly access documentation for this product from the file system, double-click thefollowing file:

TIBCO_HOME/release_notes/TIB_bwpluginodata_version_docinfo.html

where TIBCO_HOME is the top-level directory in which TIBCO products are installed. On Windows,the default TIBCO_HOME is C:\Program Files\tibco\bw6. On UNIX systems, the defaultTIBCO_HOME is /opt/tibco.

The following documents for this product can be found on the TIBCO Documentation site:

● TIBCO ActiveMatrix BusinessWorks Plug-in for OData Installation

● TIBCO ActiveMatrix BusinessWorks Plug-in for OData User's Guide

● TIBCO ActiveMatrix BusinessWorks Plug-in for OData Release Notes

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO Support:

● For an overview of TIBCO Support, and information about getting started with TIBCO Support,visit this site:

http://www.tibco.com/services/support

● If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you canrequest one.

How to Join TIBCO Community

TIBCO Community is an online destination for TIBCO customers, partners, and resident experts. It is aplace to share and access the collective experience of the TIBCO community. TIBCO Community offersforums, blogs, and access to a variety of resources. To register, go to the following web address:

https://community.tibco.com

4


https://docs.tibco.com

https://docs.tibco.com/products/tibco-activematrix-businessworks-plug-in-for-odata

https://docs.tibco.com/products/tibco-activematrix-businessworks-plug-in-for-odata

http://www.tibco.com/services/support

https://support.tibco.com

https://community.tibco.com

Product Overview

With TIBCO ActiveMatrix BusinessWorks™ Plug-in for OData, you can configure a connection to anOData server, and then use the activities to query, create, update and delete OData services.

OData (Open Data Protocol) is an OASIS standard that defines the best practice for building andconsuming RESTful APIs. You can visit the OData website http://www.odata.org/ for more information.

TIBCO ActiveMatrix BusinessWorks Plug-in for OData plugs into TIBCO ActiveMatrixBusinessWorks™. The following figure shows how the plug-in works with the TIBCO products.

● TIBCO ActiveMatrix BusinessWorks Plug-in for OData is used to communicate with an ODataServer.

● TIBCO ActiveMatrix BusinessWorks Plug-in for OData plugs into TIBCO ActiveMatrixBusinessWorks and connects to an OData server.

● TIBCO ActiveMatrix BusinessWorks is an easy-to-use integration product suite for enterpriseapplications.

● TIBCO Business Studio™ is the graphical user interface (GUI) used by TIBCO ActiveMatrixBusinessWorks and the plug-in to design business processes, and the underlying process engine isused to execute these business processes.

● TIBCO® Enterprise Administrator provides a centralized administrative interface to manage andmonitor the plug-in applications deployed in an enterprise.

The plug-in provides the following functions:

● Connect to an OData server.

● Query data from an OData server.

● Create, update, and delete data from an OData server.

5


http://www.odata.org/

Getting Started

This tutorial is designed for the beginners who want to use TIBCO ActiveMatrix BusinessWorks Plug-infor OData in TIBCO Business Studio.

All the operations are performed in TIBCO Business Studio. See TIBCO Business Studio Overview toget familiar with TIBCO Business Studio.

A basic procedure of using TIBCO ActiveMatrix BusinessWorks Plug-in for OData includes:

1. Creating a Project

2. Creating an OData Connection

3. Configuring a Process

4. Testing a Process

5. Deploying an Application

Creating a ProjectThe first task to use the plug-in is to create a project.

An Eclipse project is an application module configured for TIBCO ActiveMatrix BusinessWorks. Anapplication module is the smallest unit of resources that is named, versioned, and packaged as part ofan application.

Procedure

1. Start TIBCO Business Studio using one of the following ways:

● Microsoft Windows: click Start > All Programs > TIBCO > TIBCO_HOME > TIBCO BusinessStudio version_number > Studio for Designers.

● Mac OS and Linux: run the TIBCO Business Studio executable file located in the TIBCO_HOME/studio/version_number/eclipse directory.

2. From the menu, click File > New > BusinessWorks Resources to open the BusinessWorks Resourcewizard.

3. In the "Select a wizard" dialog, click BusinessWorks Application Module and click Next to openthe New BusinessWorks Application Module wizard.

4. In the Project dialog, configure the project that you want to create:a) In the Project name field, enter a project name.b) By default, the created project is located in the workspace current in use. If you do not want to

use the default location for the project, clear the Use default location check box and click Browseto select a new location.

c) Use the default version of the application module, or enter a new version in the Version field.d) Keep the Create empty process and Create Application check boxes selected to automatically

create an empty process and an application when creating the project.e) Select the Use Java configuration check box if you want to create a Java module.

A Java module provides the Java tooling capabilities.f) Click Finish to create the project.

Result

The project with the specified settings is displayed in the Project Explorer view.

6


Creating an OData ConnectionAfter creating a project, you add an OData Connection shared resource to create a connection betweenthe plug-in and an OData server.

Prerequisites

The OData Connection shared resource is available at the Resources level. Ensure that you have createda project, as described in Creating a Project.

Procedure

1. Expand the created project in the Project Explorer view.

2. Right-click the Resources folder and click New > OData Connection to open the OData Connectionwizard.

3. The resource folder, package name, and resource name of the OData connection are provided bydefault. If you do not want to use the default configurations, change them accordingly. Click Finishto open the OData Connection Editor.

7


4. In the Root URL field, specify the OData services root URL.

5. In the Connection Timeout (msec) field, specify the maximum response time of OData request.

If you do not provide timeout value in this field, no response time limit is set on the ODatarequest.

6. Click Load Metadata to load the metadata from the OData server.

7. In the Security panel, specify the authentication type of the OData server. See Security for moredetails.

8. If SSL is used in the server you want to connect to, you are required to configure SSL. Select theConfidentiality check box for configuration. See the TIBCO ActiveMatrix BusinessWorksdocumentation for more details.

Configuring a ProcessAfter creating a project, an empty process is created. You can add activities to the empty process tocomplete a task. For example, query data from an OData server.

Prerequisites

Ensure that you have created an empty process when Creating a Project.

Procedure

1. In the Project Explorer view, click the created project and open the empty process from theProcesses folder.

2. Select an activity from the Palette view and drop it in the Process editor.For example, select and drop the Timer activity from the General Activities palette and the ODataQuery activity from the OData palette.

8


3. Drag the icon to create a transition between the added activities.

4. Configure the added OData activities, as described in OData Palette.

An OData connection is required when configuring the OData activities. See Creating anOData Connection for more details about how to create an OData connection.

5. Click File > Save to save the project.

Testing a ProcessAfter configuring a process, you can test the process to check if the process completes your task.

Prerequisites

Ensure that you have configured a process, as described in Configuring a Process.

Procedure

1. On the toolbar, click Debug > Debug Configurations.

2. Click BusinessWorks Application > BWApplication in the left panel.By default, all the applications in the current workspace are selected in the Applications tab. Ensurethat only the application you want to debug is selected in the Applications tab in the right panel.

3. Click Debug to test the process in the selected application.TIBCO Business Studio changes to the Debug perspective. The debug information is displayed inthe Console view.

9


4. In the Debug tab, expand the running process and click an activity.

5. In the upper-right corner, click the Job Data tab, and then click the Output tab to check the activityoutput.

Deploying an ApplicationAfter testing, if the configured process works as expected, you can deploy the application that containsthe configured process into a runtime environment, and then use the bwadmin utility to manage thedeployed application.

Before deploying an application, you must generate an application archive, which is an enterprisearchive (EAR) file that is created in TIBCO Business Studio. For more information about TIBCOBusiness Studio, see TIBCO Business Studio Overview.

Deploying an application involves the following tasks:

1. Uploading an application archive

2. Deploying an application archive

3. Starting an application

See TIBCO ActiveMatrix BusinessWorks Administration for more details about how to deploy anapplication.

TIBCO Business Studio OverviewTIBCO Business Studio is an Eclipse-based integration development environment that is used todesign, develop, and test ActiveMatrix BusinessWorks applications.

TIBCO Business Studio provides a workbench in which you can create, manage, and navigate resourcesin your workspace. A workspace is the central location on your machine where all data files are stored.

10


The workbench consists of:

1. Menu: contains menu items such as File, Edit, Diagram, Navigate, Search, Project, Run, Window,and Help.

2. Toolbar: contains buttons for frequently used commands such as New , Save , Enable/

Disable Business Studio Capabilities , Create a new BusinessWorks Application Module ,

Create a new BusinessWorks Shared Module , Debug , Run , and so on.

3. Perspective: contains an initial set and layout of views that are required to perform a certain task.TIBCO Business Studio launches the Modeling perspective by default. You can change theperspective from the menu Window > Open Perspective > Perspective_Name.

4. View: displays resources. For example, the Project Explorer view displays the ActiveMatrixBusinessWorks applications, modules, and other resources in your workspace, and the Propertiesview displays the properties for the selected resource. You can open a view from the menu Window> Show View > View_Name.

5. Editor: provides a canvas to configure, edit, or browse a resource. Double-click a resource in a viewto open the appropriate editor for the selected resource. For example, double-click an ActiveMatrixBusinessWorks process (MortgageAppConsumer.bwp) in the Project Explorer view to open theprocess in the editor.

6. Palette: contains a set of widgets and a palette library. A palette groups activities that perform similartasks, and provides quick access to activities when configuring a process.

11


OData Connection

You can use the OData Connection shared resource to connect to an OData server.

General

In the General panel, you can specify the package that stores the OData Connection shared resourceand the shared resource name.

The following table lists the fields in the General panel of the OData Connection shared resource:

FieldModuleProperty? Description

Package No The name of the package where the new shared resource is added.

Name No The name to be displayed as the label for the shared resource in theprocess.

Description No A short description for this shared resource.

OData Connection Configuration

In the OData Connection Configuration panel, you can provide necessary information to connect theplug-in with an OData server.

The following table lists the fields in the OData Connection Configuration panel of the ODataConnection shared resource:

Field

ModuleProperty? Description

Root URL Yes The root URL of OData services.

For example:http://services.odata.org/V4/OData/OData.svc/

ConnectionTimeout(msecs)

Yes The maximum response time of the OData request.

Load Metadata No You can click Load Metadata to load metadata from the ODataserver.

When the metadata is loaded, the Load Metadatabutton is changed to Reload Metadata. You can click itto reload metadata from the OData server.

Security

In the Security panel, you can select the authentication type of the OData server.

The following table lists the fields in the Security panel.

12



Authentication No The authentication of the OData server. Select anauthentication type from the list:

● No Auth: without authentication.

● Basic Auth: basic authentication with user name andpassword.

● NTLM: Windows NTLM authentication.

In this release, only the OData Query activitysupports the usage of NTLM.

The following items are only displayed when Basic Auth is selected from the Authentication list.

User Name Yes The user name of basic authentication.

Password Yes The password of basic authentication.

The following items are only displayed when NTLM is selected from the Authentication list.

Domain Yes The domain of the NTLM server.

User Name Yes The user name of the NTLM server.

Password Yes The password of the NTLM server.

Workstation Yes The workstation of the NTLM server.

SSL

In the SSL panel, you can configure SSL after selecting the Confidentiality check box. See the TIBCOActiveMatrix BusinessWorks documentation for more details.

Metadata

In the Metadata tab, you can see all the metadata of the OData service after clicking Load Metadata orReload Metadata.

To update metadata dynamically after changing the URL in the Root URL field, you are required toclick Reload Metadata, and then save the OData Connection share resource.

13


OData Palette

The OData palette is added to TIBCO Business Studio after installing TIBCO ActiveMatrixBusinessWorks Plug-in for OData.

The OData palette contains the following activities to query and modify data from an OData server.

● OData Query Activity

● OData Modify Activity

OData Query ActivityYou can use the OData Query activity to query data from an OData server.

General

In the General tab, you can establish a connection to an OData server, and generate the URI to query.

The following table lists the configurations in the General tab of the OData Query activity:


Name No The name to be displayed as the label for the activity in theprocess.

ODataConnection

Yes The OData Connection shared resource that is used to create aconnection between the plug-in and an OData server. Click

to select an OData Connection shared resource.

If no matching OData Connection shared resources are found,click Create Shared Resource to create one. For more details,see Creating an OData Connection.

OData URI No The OData URI that is used to query. You can edit the ODataURI in this field. To validate the URI, you can right-click theURI and then click Validate URI in the pop-up list.

Two buttons are provided in this area:

● URI Builder: click this button to open the Build ODataURI tool. For details, see Query URI Builder.

● Clear: click this button to clear the values in the ODataURI field.

Ensure the result schema of URI matches ODataURI in the Input item.

Description

In the Description tab, you can enter a short description for the OData Query activity.

Input

In the Input tab, you can specify the required input of the activity.

14


The input items are only displayed when an OData connection is set.

The following table lists the input elements in the Input tab of the OData Query activity:

Input Item Data Type Description

Headers Complex The header of the OData request. It includes the followingitems:

● Accept: it can be used by user agents to specifyresponse media types that are acceptable.

● Content-Type: the media type of the entity body sentto the OData server.

● Content-Encoding: it is used as a modifier to themedia-type.

● Content-Language: it indicates the natural language ofthe intended audience for the enclosed message body.

● Content-Length: it indicates the size of the entity bodysent to the server.

● OData-Version: it specifies the version of the protocolused to generate the request.

The header structure is defined by the HTTPprotocol. See the HTTP protocol specification formore information about the fields and content ofthe header of an HTTP request.

DynamicHeaders Complex The dynamic header is an additional header parameterwhich is added into runtime headers of the outgoingOData request messages. The DynamicHeaders elementincludes the following items:

● Name: the name of the header

● Value: the value of the header

ODataRequest Complex This element indicates the OData related items which aredynamically generated by using the variables in the ODataURI area of the General Tab. It includes the followingitems:

● ODataURI: (Optional) you can manually type an ODataURI which is for querying in this item.

● Parameters: it shows the values of the variables in theOData URI area of the General tab.

ODataURI String This item can override the values in the OData URI area ofthe General tab.

● Ensure the URI matches the result schema ofURI.

● Parameters are not supported for this item.

15


http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398218


Parameters Complex The items under this element are the parameters in theOData URI field of the General tab.

Output

In the Output tab, you can find the output schema, which is the same as the schema in Output Previewof query builder. For more details, see Output Preview .

Fault

In the Fault tab, you can find the error code and error message of the OData Query activity.

The following table lists error schema elements in the Fault tab of this activity:

Error SchemaElement Data Type Description

msg String The error message description that is returned by the plug-in.

msgCode String The error code that is returned by the plug-in.

innerError Complex The inner error details.

message String The error message description that is returned by the OData server.

type String The error type that is returned by the OData server.

stacktrace String The error stacktrance description that is returned by the ODataserver.

OData Modify ActivityYou can use the OData Modify activity to create, update, and delete data from an OData server.

General

In the General tab, you can establish a connection to an OData server, specify the operation you want todo, and generate the URI to modify.

The following table lists the configurations in the General tab of the OData Modify activity:


Name No The name to be displayed as the label for the activity in theprocess.

16



ODataConnection

Yes The OData Connection shared resource that is used to create aconnection between the plug-in and an OData server. Click

to select an OData Connection shared resource.

If no matching OData Connection shared resources are found,click Create Shared Resource to create one. For more details,see Creating an OData Connection.

Operation No The operation that you want to perform. Select an operationfrom the list.

● Create: select it to create an entity or add reference.

● Update: select it to update an entity, property, or reference.

● Delete: select it to delete an entity or reference.

Create is selected by default.

Update Type No The update type of update operation. It is only available whenUpdate in the Operation list is selected.

● Patch: select it to only modify the field values specified inthe input items. It is selected by default.

● Replace: select it to replace all values of structuralproperties with the values specified in the input items.

OData URI No It is used to generate the URI to modify.

Two buttons are provided in the area.

● URI Builder: click this button to open the OData URIBuilder tools. For more details, see Modify URI Builder.

● Clear: click this button to clear the OData URI field value.

Description

In the Description tab, you can enter a short description for the OData Modify activity.

Input

In the Input tab, you can specify the required input of the OData Modify activity.

The following table lists the input elements in the Input tab of this activity:

17



Headers Complex The header of the OData request. It includes the followingitems:

● Accept: it is used by user agents to specify response mediatypes that are acceptable.

● Content-Type: it is the media type of the entity body sentto the OData server.

● Content-Encoding: it is used as a modifier to the media-type.

● Content-Language: it indicates the natural language of theintended audience for the enclosed message body.

● Content-Length: it indicates the size of the entity bodysent to the server.

● OData-Version: it specifies the version of the protocol usedto generate the request.

The header structure is defined by the HTTPprotocol. See the HTTP protocol specification formore information about the fields and content of theheader of an HTTP request.

DynamicHeaders Complex The dynamic header is an additional header parameter whichis added into runtime headers of the outgoing OData requestmessages. The DynamicHeaders element includes thefollowing items:

● Name: the name of the header

● Value: the value of the header

18


http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398218


ODataRequest Complex This element indicates the OData related items which aredynamically generated by using the variables in the ODataURI area of the General Tab. The input items are changedaccording to the configurations in Modify URI Builder.

● Create

— Create Entity: it shows all properties of entities, andnavigation properties.

— Create Reference: it shows the key parameter itemsand the RefLink item.

● Update

— Update Entity: it shows the entity key parameteritems and all properties.

— Update property: it shows the entity key parameteritems and property items.

— Change Reference: it shows all the key parameteritems and the RefLink item.

● Delete

— Delete Entity: it shows the key parameter items.

— Delete Reference: it shows the key parameter itemsand the RefLink item.

Output

In the Output tab, you can find the output schema.

The following table lists the output elements in the Output tab of the OData Modify activity:

Output Item Data Type Description

StatusCode String The OData response status code.

StatusMessag

e

String The OData response status message.

19


Output Item Data Type Description

Entity/

Reference

Complex The output items are changed according to your configurations inModify URI Builder.

● Create:

— Create Entity: it shows all properties of entities, andnavigation properties.

● Update:

— Update Entity: it shows all properties of entities, andnavigation properties.

— Update property: it shows updated property.

● Delete:

— This item is invisible in the delete operation mode.

Fault

In the Fault tab, you can find the error code and error message of the OData Modify activity.

The following table lists error schema elements in the Fault tab of this activity:

Error SchemaElement Data Type Description

msg String The error message description that is returned by the plug-in.

msgCode String The error code that is returned by the plug-in.

innerError Complex The inner error details.

message String The error message description that is returned by the OData server.

type String The error type that is returned by the OData server.

stacktrace String The error stacktrance description that is returned by the ODataserver.

20


Query URI Builder

The URI builder is used for building the OData query URI. You can click URI Builder in the ODataURI area of the OData Query activity to open the Build OData URI wizard.

Before using the URI builder, ensure that you have selected an OData Connection share resource.

The URI builder includes the following panels:

● Builder tabs: this panel is in the upper left of the Build OData URI wizard. It is used to manipulatethe formation of query URI displayed in the URI viewer. It contains six tabs: Object, Filters,Columns, Orders, Expands and Pagination. Each tab controls one aspect of OData query URI.

● URI viewer: this panel is at the bottom of the Build OData URI wizard. It is a read-only displayregion, in which manual changes are not allowed.

The URI builder supports the following segments, options, and operator.

● Basic resource segments: $count, $value and $ref.

● Query options: $filter, $select, $orderby, $expand, $count, $skip and $top.

● Lambda operators: any.

The URI builder does not support $all, $crossjoin, $search, $batch, $entity, $root, $id, $levelsand $format. You cannot get these options directly through the clicking or picking operations.

21


Object TabIn the Object tab, you can generate query resource path part of OData URI; and you can use the restfour tabs to provide a variety of approaches for query options combination.

The Object tab includes two parts: resource tree part is in the upper left of the tab; query options andoutput preview part are on the right of the tab. For more details, see Resource Tree and Query Optionsand Output Preview.

The right side is empty in initial state unless a resource node is selected.

As OData official documentation illustrates, a URL used by an OData service has at most threesignificant parts: the service root URL, resource path and query options.

In some sense, the object tab is an entry of URI builder, beginning of URI constructing, the tree nodeselected and query option selected. It affects the visibility and content of other tabs.

Resource Tree

Resource type represented by tree nodes can be divided into 3 classes: Entity Set , Property andNavigation Property .

When an entity set node is expanded, the node is selected automatically, and all the properties andnavigation properties belonging to corresponding entity type are represented. The entity set node isexpandable if the selected node represents a property that is a complex type or a navigation property.

22


When the entity type of an entity set has subtypes, a down arrow is displayed next to the entity type.You can click the arrow to show the subtypes, and select them.

When a subtype is chosen, all properties and navigation properties belonging to subtype itself and theinheritance from ancestor type replace original nodes accordingly. A type casting is appended to thefollowing query URI as a filter to entity set path before.

23


Query Option and Output PreviewThe Query Option area and the Output Preview area are on the right side of the Build OData URIwizard.

Query Option

In the Query Option area, you can select different options to refine the resource path generated by treenode selection.

● Query options illustrated here is different from options after the question mark (?) in query URI,and it acts on resource path only.

● Only one option can be selected in a group.

It is good practice that manually select an option before configuring.

The tree node selected on left determines what options are displayed in the query option group, whichmeans, different resource types have different query options.

You can select one of the following options in the Query Option area.

● EntitySet: select it to apply EntitySet to entity collection nodes.

● Single Entity: select it to apply Single Entity to entity collection nodes.

● Total Count: select it to apply Total Count to entity collection nodes.

● Value Only: select it to apply Value Only to property nodes.

● Value: select it to apply Value to media entity collections.

● Reference: select it to apply Reference to navigation properties.

24


Complex type property and Singleton entity have no query options.

Output Preview

Output preview is a read-only preview of output schema, which is the result of interaction betweenselected resource tree node and query option.

The output preview schema keeps consistent with activity output schema.

Filters TabIn the Filters tab, you can provide flexible query condition combinations for query URI option $filter.A meta condition is appended each time, and those meta conditions are arranged by an and relationautomatically.

The following figure is an example of the Filters tab.

Each meta condition is composed of three fields: property, operation and operand. See the followinglist for details.

● The Property field: it is the first field, and all the selection options listed in it belong to the resourceobject selected in the Object tab.

● The Operation field: it is the last second field, and the operation selected in it determines the inputdata type of parameter behind. If given an invalid value, red crosses is bound to this field. Detailmessage is displayed when moving the mouse pointer over that red crosses.

● The Operand field: it is the last field. You can input a parameter in it manually.

25


Parameters must start with the at sign (@), and when it is added, a new parameter with same nameis displayed in activity input for custom configuration.

You can also remove the at sign (@) in the Operand field,and then input values directly in this field.The URI is changed accordingly.

To rearrange these conditions for custom usage, it is good practice that manually change the relation ofconditions in the text area. Every change in the text area affects the following query URI.

26


● If the property is a collection, lambda expression $it is supported in the meta condition foriteration.

● If the property selected before is a complex type or a navigation, sub properties is representedbehind. The filter is capable of handling 3 levels expanding.

● The multiple hierarchy query is supported in the Filter tab, which means, nested properties ofnavigation type use lambda operators in meta condition.

● Any lambda operator is supported by default, and it can be changed to all manually if needed.

● Stream, Geography, Binary and Duration type properties do not support query in the Filter tab.

Columns TabIn the Columns tab, you can determine which property is queried, and navigation properties are notlisted here.

The following figure is an example of the Columns tab.

● The plus sign (+) before property name indicates that the property is a complex type.

● Property names selected are appended to $select query option in query URI at the bottom,separated by comma.

Orders TabIn the Orders tab, you can define orders of query result. The tab corresponds $orderby query option inquery URI at the bottom.

The following figure is an example of the Orders tab.

27


You can select different order combinations, and rearrange them. Order items in URI are separated bycomma.

Expands TabIn the Expands tab, selected items are displayed after the $expand query option in query URI at thebottom.

The following figure is an example of the Expands tab.

28


In this version, the Expands tab does not support nest expanding.

Pagination TabIn the Pagination tab, you can manipulate pagination of query. Every field is optional.

If no values are added in the Skip field or the Top field, client adopts pagination on server side bydefault.

If the Count Total check box is selected, $count=true is appended to query URI at the bottom. Skipand Top fields set $skip and $top options respectively.

29


If the Return All check box is selected, the Top field is disabled, and $top option is removed fromquery URI, which means, all the records must be returned even though a pagination mechanism forenforcement is on the server side.

If the Return All check box is not selected, only up to 20 records are returned.

30


Modify URI Builder

The URI builder is used to build OData URI after you select Create, Update, or Delete from theOperation list in the ODataModify activity.

Before using the URI builder, ensure that you have selected an OData Connection share resource.

The Object panel in the URI Builder wizard lists all entity sets at the first level and shows entityproperties and navigation binding properties in the second level.

When you select different options from the Operation list on the General tab, different item types aredisplayed for completing different tasks.

When selecting Create from the Operation list of the General tab, you can select an entity set or anavigation property.

● Entity set: select it to create an entity or derived entity into this entity set.

● Navigation property: select it to add a reference.

When selecting Update from the Operation list of the General tab, you can select an entity set, aproperty, or a navigation property.

● Entity set: select it to update an entity.

● Property: select it to update an property of the entity.

● Navigation property: select it to change a reference.

When selecting Delete from the Operation list of the General tab, you can select an entity set or anavigation property.

31


● Entity set: select it to delete an entity.

● Navigation property: select it to delete a reference.

OData URI is generated automatically when you select tree node from the Object panel.

32


Working with the Sample Project

The plug-in packages a sample project with the installer. The sample project shows how TIBCOActiveMatrix BusinessWorks Plug-in for OData works.

After installing the plug-in, you can find the CreateAndQuerySample.zip file in the TIBCO_HOME/bw/palettes/odata/version_number/samples directory.

This sample project contains one process.

● Process.bwp

It shows how to create and query data from an OData server.

Importing the Sample ProjectBefore running the sample project, you must import the project to TIBCO Business Studio.

Procedure

1. Start TIBCO Business Studio using one of the following ways:● Microsoft Windows: click Start > All Programs > TIBCO > TIBCO_HOME > TIBCO Business

Studio version_number > Studio for Designers.● Mac OS and Linux: run the TIBCO Business Studio executable file located in the TIBCO_HOME/

studio/version_number/eclipse directory.2. From the menu, click File > Import.3. In the Import dialog, expand the General folder and select the Existing Studio Projects into

Workspace item. Click Next.4. Click Browse next to the Select archive file field to locate the sample. Click Finish.

The sample project is located in the TIBCO_HOME/bw/palettes/odata/version_number/samplesdirectory.

Result

The sample project is imported to TIBCO Business Studio.

33


Running the Sample ProjectThis sample project contains one process that shows how to create and query data.

Prerequisites

Ensure that you have imported the sample project to TIBCO Business Studio, as described in Importingthe Sample Project.

Procedure

1. In the Project Explorer view, expand ODataSample > Module Descriptors and double-clickModule Properties to configure the module properties that are used in the sample project.

2. Expand the Module Descriptors resource, and then double-click Components.

3. In the Component Configurations area, ensure that the ComponentProcess: odatasample.Processcomponent is selected.

4. On the toolbar, click the icon to save your changes.

5. From the menu, click Run > Run Configurations to run the selected process.

6. In the left panel of the Run Configurations dialog, expand BusinessWorks Application >BWApplication.

7. In the right panel, click the Applications tab, select the check box next toODataSample.application.

8. Click Run to run the process.

9. Click the icon to stop the process.

Result

The Console is displayed after running the process.

34


Managing Logs

When an error occurs, you can check logs to trace and troubleshoot the plug-in exceptions.

By default, error logs are displayed in the Console view when you run a process. You can change thelog level of the plug-in to trace different messages and export logs to a file. Different log levelscorrespond to different messages, as described in Log Levels.

Log LevelsDifferent log levels include different information.

The plug-in supports the following log levels:

Log Level Description

Info Indicates normal plug-in operations. No action is required. A tracing messagetagged with Info indicates that a significant processing step is reached, andlogged for tracking or auditing purposes. Only info messages preceding atracking identifier are considered as significant steps.

Error Indicates that an unrecoverable error occurred. Depending on the severity ofthe error, the plug-in might continue with the next operation or might stop.

Debug Indicates a developer-defined tracing message.

Setting Up Log LevelsYou can configure a different log level for the plug-in and plug-in activities to trace different messages.

By default, the plug-in uses the log level configured for TIBCO ActiveMatrix BusinessWorks. Thedefault log level value of TIBCO ActiveMatrix BusinessWorks is ERROR.

Procedure

1. Navigate to the TIBCO_HOME/bw/version_number/config/design/logback directory and openthe logback.xml file.

2. Add the following node in the BusinessWorks Palette and Activity loggers area to specify a loglevel for the plug-in:<logger name="com.tibco.bw.palette.odata.runtime"> <level value="DEBUG"/> </logger>

The value of the level element can be ERROR, INFO, or DEBUG.

If you set the log level to Debug, the input and output for the plug-in activities are alsodisplayed in the Console view. See Log Levels for more details regarding each log level.

3. Optional: Add the following node in the BusinessWorks Palette and Activity loggers area tospecify a log level for an activity. The node varies according to the activity and the palette that itbelongs to.<logger name="com.tibco.bw.palette.odata.runtime.ActivityNameActivity"> <level value="DEBUG"/></logger>

35


For example, you can add the following node to set the log level of the OData Modify activity toDEBUG:<logger name="com.tibco.bw.palette.odata.runtime.ModifyActivity"> <level value="DEBUG"/></logger>

The activities that are not configured with specific log levels use the log level configuredfor the plug-in.

4. Save the file.

Exporting Logs to a FileYou can update the logback.xml file to export plug-in logs to a file.

Procedure

1. Navigate to the TIBCO_HOME/bw/version_number/config/design/logback directory and openthe logback.xml file.

After deploying an application in TIBCO Enterprise Administrator, navigate to theTIBCO_HOME/bw/version_number/domains/domain_name/appnodes/space_name/

node_name directory to find the logback.xml file.

2. Add the following node to specify the file where the log is exported:<appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>c:/bw6-OData.log</file> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36}-%msg%n</pattern> </encoder> </appender>

The value of the file element is the absolute path of the file that stores the exported log.

3. Add the following node to the root node at the bottom of the logback.xml file:<root level="DEBUG"> <appender-ref ref="STDOUT" /> <appender-ref ref="FILE" /></root>

4. Save the file.

36


tibco activematrix businessworks plug-in for odata user's ......with tibco activematrix...

Documents