You are on page 1of 155

Developing for webMethods OneData

Version 9.7

October 2014

This document applies to webMethods OneData Version 9.7 and to all subsequent releases.
Specications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.
Copyright 2011-2014 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or
its aliates and/or their licensors.
The name Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG and/or
Software AG USA Inc. and/or its subsidiaries and/or its aliates and/or their licensors. Other company and product names mentioned
herein may be trademarks of their respective owners.
Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at
hp://documentation.softwareag.com/legal/.
Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product
documentation, located at hp://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to "License
Texts, Copyright Notices and Disclaimers of Third Party Products. This document is part of the product documentation, located at
hp://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).

Document ID: ODE-DG-97-20141015


M
Table of Contents

Table of Contents

About this Guide..............................................................................................................................7


Document Conventions.............................................................................................................. 7
Documentation Installation......................................................................................................... 8
Online Information...................................................................................................................... 8

OneData Hooks................................................................................................................................ 9
Hooks in OneData.................................................................................................................... 10
Hook Invocation Modes and Triggering Events................................................................ 11
Hook Processing Actions........................................................................................... 11
Hook Types........................................................................................................................13
Stored Procedure Hooks............................................................................................13
Default Parameters in a Stored Procedure Hook............................................... 14
Java RMI and Java Local Hooks...............................................................................15
Process Flow Hooks.................................................................................................. 16
Integration Server Hooks........................................................................................... 17
IDATA Structure for Integration Server Services Called from iHooks..................18
Defining a Hook........................................................................................................................21
Assigning a Hook to an Object for Pre- or Post-Processing.................................................... 22
Creating Command Hooks and Assigning to Objects..............................................................22
Managing a Hook..................................................................................................................... 24
Removing a Hook Associated to an Object............................................................................. 24

OneDataHook Functions and Stored Procedures...................................................................... 25


iHook Properties and Functions............................................................................................... 26
HookInput Parameters and Initialization Functions (Initial Invocation).............................. 26
iHook.getHookInput (CLOB) Stored Procedure......................................................... 26
hookOutput and (Subsequent) Invocation Functions........................................................ 27
Hook Output Properties..............................................................................................28
iHook Package Functions.......................................................................................... 29
iHook Package: Rowset Functions in Stored Procedures..........................................30
iHook Package: actionRowset...........................................................................................33
iHook Package: originalRowset..................................................................................34
iHook Package: selectedRowset................................................................................35
iHook Package: showableRowset.............................................................................. 35
iHook Package: Question and Answers.....................................................................36
iHook Package: Forms Default Value........................................................................ 38
iHook Package: Forms...................................................................................................... 39
iHook Package: Column Functions in Java iHooks.......................................................... 40
iHooks Sample Code................................................................................................................41
Stored Procedure.............................................................................................................. 41
Java RMI........................................................................................................................... 45

Developing for webMethods OneData Version 9.7 3


M
Table of Contents

Working In Process Flow Designer............................................................................................. 49


Process Flow Designer.............................................................................................................50
Model Components........................................................................................................... 51
Process Items....................................................................................................................52
Interactive Process Items...........................................................................................52
Non-Interactive Process Items................................................................................... 55
Looping Process Items...............................................................................................60
Component Connectors.....................................................................................................61
Compilation and Errors in Process Flow...........................................................................61
Validation Rules for Components and Items..............................................................62
Building a Process Flow...........................................................................................................63
Process Flow Example Scenarios............................................................................................64
Process Flow Java Code Samples.......................................................................................... 73

API Functions and Web Services in OneData............................................................................ 75


API Functions Overview........................................................................................................... 76
Generic API Functions..............................................................................................................76
......................................................................................................................................
getStructure................................................................................................................ 76
getData....................................................................................................................... 77
isValidCode................................................................................................................. 79
Data Deployment Functions..................................................................................................... 80
......................................................................................................................................
executeSynchronousDeploymentJob......................................................................... 80
executeAsynchronousDeploymentJob........................................................................81
getResultForDeploymentJob...................................................................................... 82
terminateDeploymentJob............................................................................................83
Generic Job Functions..............................................................................................................84
......................................................................................................................................
executeSynchronousJob............................................................................................ 84
executeAsynchronousJob...........................................................................................85
getJobExecutionResult............................................................................................... 86
terminateJob............................................................................................................... 88
Read-Write Web Services........................................................................................................ 88
Input XML Specification.....................................................................................................89
Mandatory Tags................................................................................................................. 89
Enabling Service Layer Security in OneData...........................................................................95
Retrieving Password for Service Layer Security...................................................................... 96
Enabling and Disabling Web Services in OneData..................................................................96

SOAP Web Services...................................................................................................................... 99


SOAP Web Services.............................................................................................................. 100
Using the OneData SOAP Web Services Feature.................................................................100

REST Web Services.....................................................................................................................103

Developing for webMethods OneData Version 9.7 4


M
Table of Contents

REST Web Services in OneData........................................................................................... 104


GET and POST Services....................................................................................................... 104
GET Service Response Data.......................................................................................... 105
POST Service Response Data........................................................................................107
The Acquisition Layer and REST Services............................................................................ 108
The Exception Queue and REST Services............................................................................110
Obtaining the REST URL of a OneData Object.....................................................................110
Using Filters in REST Services..............................................................................................110
REST Object URL Syntax...............................................................................................111
Using Filter Operators in a REST URL...........................................................................113
Using JSON Strings in REST Services..................................................................................115
REST URL Parameters................................................................................................... 118
alternateKey..............................................................................................................120
baseVersion.............................................................................................................. 120
batchSize.................................................................................................................. 121
dateFormat............................................................................................................... 121
decode...................................................................................................................... 121
description................................................................................................................ 121
enableDQMode.........................................................................................................121
filter........................................................................................................................... 122
partialCommit............................................................................................................122
processingMode....................................................................................................... 122
returnColumns.......................................................................................................... 122
schema_id................................................................................................................ 124
skipEmptyColumns................................................................................................... 124
sortColumn&sortOrder..............................................................................................125
wildCardOP...............................................................................................................125
Request Parameters by HTTP Methods.................................................................. 125
Using REST Web Service URL..............................................................................................126
Accessing Data with the REST Service URL..................................................................127
REST XSDs............................................................................................................................ 127
Obtaining the XSD from OneData...................................................................................127
Configuring OneData to Skip Empty Columns................................................................128
XSD Samples by Object Type................................................................................................129
Conceptual Objects......................................................................................................... 129
Self Recursive Objects.................................................................................................... 130
Network Recursive Objects............................................................................................. 132
Supertype and Subtype Object XML...............................................................................133
REST URL Parameters.......................................................................................................... 133
alternateKey.....................................................................................................................135
baseVersion..................................................................................................................... 135
batchSize......................................................................................................................... 135
dateFormat.......................................................................................................................136
decode............................................................................................................................. 136
description........................................................................................................................136

Developing for webMethods OneData Version 9.7 5


M
Table of Contents

enableDQMode................................................................................................................136
filter.................................................................................................................................. 136
partialCommit...................................................................................................................137
processingMode...............................................................................................................137
returnColumns................................................................................................................. 137
schema_id........................................................................................................................139
skipEmptyColumns.......................................................................................................... 139
sortColumn&sortOrder..................................................................................................... 140
wildCardOP......................................................................................................................140
Request Parameters by HTTP Methods......................................................................... 140
Using REST Web Service URL..............................................................................................141
Accessing Data with the REST Service URL..................................................................142
REST XSDs............................................................................................................................ 142
Obtaining the XSD from OneData...................................................................................142
Configuring OneData to Skip Empty Columns................................................................143
XSD Samples by Object Type................................................................................................144
Conceptual Objects......................................................................................................... 144
Self Recursive Objects.................................................................................................... 145
Network Recursive Objects............................................................................................. 147
Supertype and Subtype Object XML...............................................................................148

In-Memory Database....................................................................................................................149
In-Memory Database in OneData...........................................................................................150
Caching................................................................................................................................... 150
Configuring Caching............................................................................................................... 151
Dependent Object Mapping....................................................................................................152
Creating a Cache Refresh Job...............................................................................................153
Data Cache Refresh from Work Area to Release Area.................................................. 154
Scheduling a Cache Refresh Job.......................................................................................... 154

Developing for webMethods OneData Version 9.7 6


M
Odd Header

About this Guide

This guide describes how to create and use hooks in OneData. It contains information
about API functions and web services in OneData for the developers. It also describes
how to use in-memory database in OneData.

Document Conventions

Convention Description

Bold Identies elements on a screen.

Narrowfont Identies storage locations for services on webMethods


Integration Server, using the convention folder.subfolder:service .

UPPERCASE Identies keyboard keys. Keys you must press simultaneously


are joined with a plus sign (+).

Italic Identies variables for which you must supply values specic to
your own situation or environment. Identies new terms the rst
time they occur in the text.

Monospace Identies text you must type or messages displayed by the


font system.

{} Indicates a set of choices from which you must choose one. Type
only the information inside the curly braces. Do not type the { }
symbols.

| Separates two mutually exclusive choices in a syntax line. Type


one of these choices. Do not type the | symbol.

[] Indicates one or more options. Type only the information inside


the square brackets. Do not type the [ ] symbols.

... Indicates that you can type multiple options of the same type.
Type only the information. Do not type the ellipsis (...).

Developing for webMethods OneData Version 9.7 7


M
Even Header

Documentation Installation
You can download the product documentation using the Software AG Installer. The
documentation is downloaded to a central directory named _documentation in the main
installation directory (SoftwareAG by default).

Online Information
SoftwareAG Documentation Website
You can nd documentation on the Software AG Documentation website at hp://
documentation.softwareag.com. The site requires Empower credentials. If you do not
have Empower credentials, you must use the TECHcommunity website.

Software AG Empower Product Support Website


You can nd product information on the Software AG Empower Product Support
website at hps://empower.softwareag.com.
To submit feature/enhancement requests, get information about product availability,
and download products and certied samples, go to Products.
To get information about xes and to read early warnings, technical papers, and
knowledge base articles, go to the Knowledge Center.

Software AG TECHcommunity
You can nd documentation and other technical information on the Software AG
TECHcommunity website at hp://techcommunity.softwareag.com. You can:
Access product documentation, if you have TECHcommunity credentials. If you do
not, you will need to register and specify "Documentation" as an area of interest.
Access articles, demos, and tutorials.
Use the online discussion forums, moderated by Software AG professionals, to
ask questions, discuss best practices, and learn how other customers are using
Software AG technology.
Link to external websites that discuss open standards and web technology.

Developing for webMethods OneData Version 9.7 8


M
Odd Header
OneData Hooks

1 OneData Hooks
Hooks in OneData ........................................................................................................................ 10
Defining a Hook ........................................................................................................................... 21
Assigning a Hook to an Object for Pre- or Post-Processing ....................................................... 22
Creating Command Hooks and Assigning to Objects ................................................................. 22
Managing a Hook ......................................................................................................................... 24
Removing a Hook Associated to an Object ................................................................................. 24

Developing for webMethods OneData Version 9.7 9


M
Even Header
OneData Hooks

Hooks in OneData
You can extend OneDatas functionality using commands called Hooks. Hooks invoke
external procedures. You can use the Hook interface to provide parameters that are
required to execute stored procedures at a specic data manipulation event such as:
Inserting a new record in an object.
Updating a column or an aribute in an object.
Deleting (logically) a record in an object.
Restoring a logically deleted record.
Purging (physically deleting from database) a logically deleted record.
You can use hooks in to perform an action based on a trigger, for example:
Automatically insert a record in a mapping table whenever you create a new code.
Map or auto-create a customer when a matching customer record is imported from
the source systems.
Determine whether a customer created in their system is a unique global customer or
is a duplicate of an existing global customer.
Parse a product record from the source system and decompose it into dierent
tables.
For details on iHook Packages, see " OneDataHook Functions and Stored Procedures" on
page 25.
OneData provides interactive hook support for objects in Nova mode, for interactive
user feedback from Data Manager screens. The following table lists the hook
functionality that is supported for objects in Nova mode.

Processing Action Hook Trigger

Hook Type Pre-Hook Post-Hook Standard UI Interactive


Processing? Processing? Command Command
Hook? Hook?

Java Hook Yes Yes Yes Yes

Java RMI Yes Yes Yes Yes

Stored Yes (Oracle Yes (Oracle Yes (Oracle Yes (Oracle


Procedure Repository Repository Repository Repository
Only) Only) Only) Only)

Developing for webMethods OneData Version 9.7 10


M
Odd Header
OneData Hooks

Processing Action Hook Trigger

Hook Type Pre-Hook Post-Hook Standard UI Interactive


Processing? Processing? Command Command
Hook? Hook?

Integration Yes Yes Yes Yes


Server Hook

Process Flow No No No Yes


Hook

Hook Invocation Modes and Triggering Events


There are two types of hooks: standard hooks and iHooks. Both types use a similar
framework but have dierent aributes.
Standard Hooks. You can invoke standard hooks (known simply as, hooks) during data
manipulation when no user interaction is required. You can trigger a standard hook
from on a pre-processing or post-processing event.
Event-Driven Hooks. Triggered by an event such as an insert, update, or delete
before (pre-process) or after (post-process) a data manipulation event.
Command Hooks. Triggered by an action on a record from a Data Manager or
Workow Details screen.
iHooks (Interactive Hooks). iHooks require user interaction and are triggered only after
receiving user input. iHooks provide the framework for XML interaction. You can
trigger iHooks from a pre-processing or post-processing event.

Note: If the iHook is triggered from a post-process event, the iHook interacts with
OneData, not with the user.

iHook interactivity can be directly with the user or with the system.
OneData interactive mode.OneData interacts with the data management engine to
ensure that iHook actions adhere to the same rules, auditing, and workow as
changes made through the OneData user interface.
User interactive mode.OneData uses a wizard to elicit user responses. The iHook
may interact with OneData data management engine.

Hook Processing Actions


You can invoke hooks during dierent points of data manipulation to perform necessary
processing:

Developing for webMethods OneData Version 9.7 11


M
Even Header
OneData Hooks

Pre-processing. Validate data before adding it to the repository. Pre-process hooks


call an external program to verify data consistency and to apply business rules. Data
management cannot be performed with pre-processing hooks.
Post-processing. Perform actions on the data that has been wrien to the repository.
After data is wrien to the repository, the post-processing hook calls an external
program to run subsequent event processing in a dierent repository.
User interaction trigger. Hooks that are triggered from a Data Manager or Workow
Details screen when a specic event occurs.
The following table shows the data manager actions and the type of processing
available.

Note: You cannot use hooks to delete data in objects that have multi-select columns.

Data Manager Actions Pre-process Post-Process User Interaction

Insert No Yes Yes

Update No Yes Yes

Delete No No Yes

Restore No No Yes

Purge No No Yes

The following diagram shows the dierent ways that hooks can be invoked.

Developing for webMethods OneData Version 9.7 12


M
Odd Header
OneData Hooks

Hook Types
You can use the hooks in OneData to invoke stored procedures, java RMIs, Java local
programs, and Integration Server.

Stored Procedure Hooks


You can invoke a stored procedure using either standard hooks or iHooks. OneData uses
XML to communicate with the iHook stored procedure. A stored procedure hook can
complete successfully if it does not execute a raise_application_error command.
For post-processing iHooks (OneData interactive mode), use an hookOutput message
and hookOutput.status = 'stop' to return error conditions.
To return an error from the stored procedure to OneData, the stored procedure must
invoke, Raise_application_error (-20001, 'Error description')
If an event-driven hook (pre-processing or post-processing) invokes the stored
procedure and it returns an error, the entire transaction rolls back. For example, when
you insert a new record in OneData, if the post-processing stored procedure returns an
error, OneData does not insert the new record in the repository.

Developing for webMethods OneData Version 9.7 13


M
Even Header
OneData Hooks

The properties that dene a stored procedure hook are as follows:

Property Description

Hook
Execution
Mode

Process Flow Select an existing process ow or click the Add New Process Flow
Name icon to create a new process ow.

Default Parameters used for invoking the stored procedure. For more
Parameters details about default parameters, see "Default Parameters in a
Stored Procedure Hook" on page 14 .

Is Interactive Indicates if the hook is an iHook. This property is selected by


Hook? default and cannot be changed.

Hook Execution parameter that determines when to execute the


Cardinality external program. The hook executes the program based on the
number of rows changed:
0. Hook executes when no rows are changed.
1. Hook executes when one row is changed.
n. Hook executes when more than one row is changed.

Default Parameters in a Stored Procedure Hook


In OneData, you can specify the parameters to the external program or stored procedure
when you dene the hook or assign it to an object. Parameters dened when the hook is
assigned to an object, the parameters override the parameters in the hook denition.
You can use static parameters as needed. You can also pass any other constant numeric
parameters to the procedure other than the following placeholders.

Note: The following rules apply to parameters:


Parameters are not case sensitive and must be separated by commas.
The format for dates in the XML data stream is YYYY-MM-DD HH24:MI:SS.
The XML stream publishes BLOB and CLOB as null values.

Default Parameters for Validation in Pre-Process Mode for Database Hooks

%TABLE_NAME% Physical table name of the object associated with the hook.

Developing for webMethods OneData Version 9.7 14


M
Odd Header
OneData Hooks

%TRANSACTION_ Data manager action that triggers the stored procedure.


TYPE% Valid values:
I (Insert)
U (Update)
D (Logical delete)
R (Restore)
P (Purge or physical delete)

%DATA_XML% XML format of the record being manipulated. Column


names as XML tags.

%USER_ID% User ID of the user performing the data change or


executing the hook command.

%DATA_XML_TEXT Passes XML to a hook using string data type.


%

Pre-Defined Parameters for iHooks

%IN_XML% XML format of the record being manipulated. OneData


internally stores the XML data as a BLOB.

%OUT_XML% Output XML from iHook that OneData returns as BLOB.

%MTCHG_ENGN_ XML string that the matching engine returns if matching


XML% rules are dened.

Note: If the values that you pass contain only numbers, dene the parameter as long or
string.

Java RMI and Java Local Hooks


You can congure a Java hook as an iHook only. Java local hooks exist in the same
classpath as OneData; whereas, Java RMI iHooks hosts hooks in the form of remote Java
functions through RMI. RMI hooks do not need to be in XML format because the it can
process the input and output objects directly. In Java RMI iHooks, OneData acts as the
RMI client and access the remote RMI server.

Property Description

Hook Execution
Mode

Developing for webMethods OneData Version 9.7 15


M
Even Header
OneData Hooks

Property Description

URL Applicable only to Java RMI hook. URL of the remote RMI
server. The URL format is: RMI server name :Port of RMI server .
For example, localhost:3099

Java RMI hooks. Binding name of the remote hook object in the
Program Name
RMI Server.
Java local hooks. Fully qualied class name of the hook
(packagename.classname).
For example, com.test.hook.local.TestLocalHook

Default Parameters used for invoking the stored procedure. For more
Parameters details about default parameters, see

Is Interactive Indicates if the hook is an iHook. This property is selected by


Hook default and cannot be changed.

Hook Cardinality Execution parameter that determines when to execute the


external program. The hook executes the program based on the
number of rows changed:
0. Hook executes when no rows are changed.
1. Hook executes when one row is changed.
n. Hook executes when more than one row is changed.

Process Flow Hooks


OneData's graphical process ow designer allows you to quickly build business
processes and custom wizards using a drag-and-drop graphical interface. This provides
faster process prototyping and easier plug-in change management and development.
Process ow hooks can only be executed in command hook mode. They have their own
graphical builder and do not required coding.
To create a process ow hook, set the hook type as Process Flow. The following
properties are specic to process ow hooks.

Property Description

Hook Execution
Mode

Developing for webMethods OneData Version 9.7 16


M
Odd Header
OneData Hooks

Property Description

Process Flow Select an existing process ow or click the Add New Process Flow
Name icon to create a new process ow.

Default Parameters used for invoking the stored procedure. For more
Parameters details about default parameters, see

Is Interactive Indicates if the hook is an iHook. This property is selected by


Hook? default and cannot be changed.

Hook Cardinality Execution parameter that determines when to execute the


external program. The hook executes the program based on the
number of rows changed:
0. Hook executes when no rows are changed.
1. Hook executes when one row is changed.
n. Hook executes when more than one row is changed.

For details on designing a process ow hook, see "Building a Process Flow" on page
63.

Integration Server Hooks


You can execute an Integration Server service with an Integration Server hook. The
following tables lists the Integration Server hook properties.

Note: Multi-select columns are not supported in Integration Server hooks.

Property Description

Hook Execution
Mode

Connection Select the required Integration Server connection. Congure


Integration Server connections on the Menu toolbar, Administer
> System > Connection Manager.

Service Folder Name of the package in which the service resides.

Service Name Name of the service the hook should invoke.

Is Interactive Whether the hook is an iHook. This property is selected by


Hook? default and cannot be changed.

Developing for webMethods OneData Version 9.7 17


M
Even Header
OneData Hooks

Property Description

Hook Cardinality Execution parameter that determines when to execute the


external program. The hook executes the program based on the
number of rows changed:
0. Hook executes when no rows are changed.
1. Hook executes when one row is changed.
n. Hook executes when more than one row is changed.

IDATA Structure for Integration Server Services Called from iHooks


The structure of the input and output IDATA of the service called by an Integration
Server hook must follow the format shown in the diagram below.
The following input IDATA parameters only have values for hooks used in external
workow invocation.
approverID
transactionType
updatedColumnName
oldValueRowset
workowPassPhrase
refreshTransaction

Developing for webMethods OneData Version 9.7 18


M
Odd Header
OneData Hooks

Input IDATA Structure

Developing for webMethods OneData Version 9.7 19


M
Even Header
OneData Hooks

Output IDATA Structure

Options available for:


actionType: insert, update, delete
selectionType: unselectable, single, multi

Developing for webMethods OneData Version 9.7 20


M
Odd Header
OneData Hooks

Defining a Hook
You can dene any type of hook in the OneData user interface. For more information
about hook classication, see "Hook Invocation Modes and Triggering Events" on page
11 and "Hook Types" on page 13.

To define a hook
1. On the Menu toolbar, click Define > Configuration > Hooks.
2. Click Add Hook.
3. Enter the Hook Details as follows:

Hook Detail Description

Hook Name Required. Name of hook.

Hook Description Description of hook.

Hook Execution
Mode

Hook Type Required. Type of hook. For information about the type of
hooks, see the following:
Stored procedure, see "Stored Procedure Hooks" on page
13.
Java RMI and Java Local, see "Java RMI and Java Local
Hooks" on page 15.
Process ow, see "Process Flow Hooks" on page 16.
Integration Server, see "Integration Server Hooks" on page
17.

Program Name Required. Name of the external program to be executed.

Default Parameters For stored procedures only. For information about default
parameters, see "Default Parameters in a Stored Procedure
Hook" on page 14.

Is Interactive Hook? Whether the hook is an iHook.

Hook Cardinality Execution parameter that determines when to execute the


external program:
0. Executes when no row is changed.
1. Executes when one row is changed.

Developing for webMethods OneData Version 9.7 21


M
Even Header
OneData Hooks

Hook Detail Description


n. Executes when more than one row is changed.

Note: Hook cardinality does not apply to event-driven hooks.

4. Click Save.
The Hooks screen shows the new hook.

Assigning a Hook to an Object for Pre- or Post-Processing


After creating a hook, you can assign it to the object denition so that it executes when
the triggered. In the object denition, you dene the hook invocation mode. For more
information about the hook invocation modes, see "Hook Processing Actions" on page
11.

Note: Before you can assign a hook to an object, you must dene the hook as described in
"Dening a Hook" on page 21.

To assign a hook to an object


1. On the Menu toolbar, click Define > Objects and navigate to the required object.
2. Select the Hooks tab.
3. In Invocation Mode, select the hook that you want to configure under Pre-Process or Post-
Process against the Change Type.
For stored procedure hooks, specify the default parameters in the text eld
next to the selected hook. This denion of default parameters overrides the
default parameters in the hook denion. For more informaon about the default
parameters, see "Default Parameters in a Stored Procedure Hook" on page 14
4. Click Save.

Creating Command Hooks and Assigning to Objects


You can create hook commands that link to a dened hook. These are called Command
Hooks. You can then manually trigger this command from data manager by sending
single or multiple records to the external procedure.

Note: Hook commands are associated with OneData roles. Hence only users with the
given role will be able to execute the Hook Command.

Once created, hook commands can be edited or deleted from the Manage Hook Commands
menu. Once the hook command is created, you can invoke it from the associated entity
in Data Manager using the Select Command drop-down.

Developing for webMethods OneData Version 9.7 22


M
Odd Header
OneData Hooks

Note: If there are three or fewer command hooks, OneData displays them in the
Command toolbar in Data Manager. If there are more than three hooks, OneData
displays them in the Command hook eld.

In a conceptual object command hooks:


If command hooks are set at the conceptual object level, then for all levels in the
Advanced Parent Child view, the same command hooks appear.
If command hooks are not set at the conceptual object level, then the command
hooks change based on the data object the current focus is on.

Note: Before you can assign a hook to an object, you must dene the hook as described in
"Dening a Hook" on page 21.

To create a command hook and assign it to an object


1. On the Menu toolbar, select Define > Objects and navigate to the object to which you want to
assign a command hook.
2. Click the Hooks tab.
3. Select Manage Hooks Command.
4. Click Add Hook Command and enter the details as below:

Property Description

Command Name Unique name of 100 characters or less. Can include


spaces and special characters. Must be unique within the
repository.

Command Command description. Maximum length of 4000


Description characters.

Command Display The name that displays on the Data Management screen.
Name This does not need to be unique. If this eld is blank, then
the command name is used.

Associated Hook List of hooks from which you can select one to be assigned
to an object.

Associate Roles Roles to which you can associate the hook command.
Only users with the associated role are able to execute the
command from Data Manager.

5. Click Save.

Developing for webMethods OneData Version 9.7 23


M
Even Header
OneData Hooks

Managing a Hook
After creating a hook, you can manage (edit or delete) the hook from the Hook
Denition screen.

To manage a hook
1. On the Menu toolbar, click Define > Configuration > Hooks.
2. Select the required action for the hook:
To edit a hook, click the Edit icon corresponding to the hook. Click Save after
making the changes.
To delete a hook, click the Delete icon corresponding to the hook. In the dialog
box for conrmation, click OK.

Note: You must remove a hook from all associated objects before deleting the
hook. For steps to remove a hook, see "Removing a Hook Associated to an
Object" on page 24.

Removing a Hook Associated to an Object


If you no longer want a hook in an object, you can un-assign the hook from the object.
You must un-assign a hook before deleting a hook.

To remove a hook associated to an object


1. On the Menu toolbar, click Define > Objects and select the object corresponding to the hook
you want to remove.
2. Click the Hooks tab.
3. Click the Manage Hooks screen.
4. Remove the selected hook by selecting Not selected from top of the drop-down list.

Developing for webMethods OneData Version 9.7 24


M
Odd Header
OneDataHook Functions and Stored Procedures

2 OneDataHook Functions and Stored Procedures


iHook Properties and Functions ................................................................................................... 26
iHooks Sample Code ................................................................................................................... 41

Developing for webMethods OneData Version 9.7 25


M
Even Header
OneDataHook Functions and Stored Procedures

iHook Properties and Functions


iHook is a way for an external procedure to interact with OneData.

HookInput Parameters and Initialization Functions (Initial Invocation)


HookInput is the top level class that is passed between OneData and the iHook class. For
stored procedures, iHooks one of the parameters is always, %IN_XML% .

iHook.getHookInput (CLOB) Stored Procedure


This procedure does not use a Java function. HookInput is available as the parameter of
the OnedataHook.execute().
For example, iHook.getHookInput(v_data_in)

Hook Properties

Property Java Function and Description

invocationNumber getInvocationNumber() Counter if the hook is called multiple


times. The rst value is always 0. The counter increments by
1 for all subsequent calls. For example:
hookInput.invocationNumberhookInput.getInvocationNumber()

invokedFromWorkow getInvokedFromWorkflow() Flag added to the HookInput to


indicate it was invoked from the Workow Approval Screen.
This is set to 1 when the post hook is called from Workow
Approval Screen. For example:
hookInput.invokedFromWorkflow
hookInput.getInvokedFromWorkflow()

originalRowset getOriginalRowset(). Original dataset that can have one or


more rowsets. In post-hook invocations, there is only one

Developing for webMethods OneData Version 9.7 26


M
Odd Header
OneDataHook Functions and Stored Procedures

Property Java Function and Description


rowset. In command hooks, there can be more than one. For
example:
hookInput.originalRowset
hookInput.getOriginalRowset()

selectedRowset getSelectedRowset() When user is prompted for selection,


this is the returned rowset. Depending on the selection
type (single or multi), there can be one or more rowsets in
selectedRowset . For more information, see
hookInput.selectedRowset
hookInput.getSelectedRowset()

userID getUserId() The current user.


hookInput.userId

refreshTransaction getRefreshTransaction () Returns 1 if transaction must be


refreshed by external workow engine.
hookInput.refreshTransaction
hookInput. getRefreshTransaction()

workowPassPhrase getWorkflowPassPhrase()
Returns the passphrase, which is a unique string used to
identify the transaction in an external workow.
hookInput. workflowPassPhrase
hookInput. getWorkflowPassPhrase()

hookOutput and (Subsequent) Invocation Functions


HookInput applies only to interactive hooks. HookOutput is returned to OneData to
process the next step.

Stored Procedures

Stored Procedure Java Function and Description

None HookOutput()setInvocationNumber()setOriginalRowset()
Initialization of hookOutput requires both invocationNumber and
OriginalRowset to be inherited from hookInput .

Usage Example
The following code sample is of hookOutput .
hookOutput.invocationNumber = hookInput.invocationNumber;
hookOutput.originalRowset = hookInput.originalRowset
HookOutput hookOutput = new HookOutput();

Developing for webMethods OneData Version 9.7 27


M
Even Header
OneDataHook Functions and Stored Procedures

hookOutput.setInvocationNumber(hookInput.getInvocationNumber());
hookOutput.setOriginalRowset(hookInput.getOriginalRowset());

Hook Output Properties


hookOutput Properties

Properties Description and Example

Question Question is a composite structure that has embedded question


text and answer composite structure.
hookOutput.question := question;
hookOutput.setQuestion(question);

Message If the status is completed, a message can be displayed to the


user.
hookInput.message := "This is a test".;
hookOutput.setMessage("This is a test");

ShowableRowset Set the output for the user to select from a grid. Grid can be
for an existing object or for a virtual object. If existing object,
then grid draws as per metadata. Number of selections can
be single or multi. For more information, see "iHook Package:
showableRowset" on page 35.
showRS := t_showableRowset(rows, 'TABLE1', 1, 'single');
hookOutput.showRowset := showRS;
ShowRS :=t_showableRowset(rows, 'Data Object 1', 2,
'multi');
hookOutput.showRowset := ShowRS;
ShowableRowset showable= new ShowableRowset();
showable.setRows(rowsList);
showable.setTableName("TABLE1");
showable.setObjectType(1);
showable.setSelectionType(1);
showable.setSelectionTypeDesc("Single");hookOutput.setShow
Rowset(showable);
ShowableRowset showable= new ShowableRowset();
showable.setRows(rowsList);
showable.setTableName("Data Object 1");
showable.setObjectType(2);
showable.setSelectionType(2);
showable.setSelectionTypeDesc("Multi");
hookOutput.setShowRowset(showable);

OriginalRowset Original dataset passed from OneData to the iHook class.


Required for hookOutput initialization.

Action Class to communicate to OneData on DML actions (insert/


update/delete/purge).
actn := t_actionRowset (rows, 'TABLE1', 1, 1,'Insert');
actions.extend;

Developing for webMethods OneData Version 9.7 28


M
Odd Header
OneDataHook Functions and Stored Procedures

Properties Description and Example


actions(actions.last):=actn;
hookOutput.action := actions;
Actions objActions = new Actions();
ActionRowset objAction = new ActionRowset();
objAction.setOrder(1); objAction.setObjectType(1);
objAction.setObjectName("Table 1");
objAction.setActionType(objAction.ACTION_TYPE_UPDATE);
objAction.setActionTypeDesc("Update");
objAction.addRow(objRow); objActions.addAction(objAction);
hookOutput.setActions(objActions);
1. Stop execution of the hook.
Status
2. Continue executing.

InvocationNumber Counter if the hook is called multiple times. Increments


automatically by 1 for all subsequent calls.
Required for hookOutput initialization.

AnswerID If the user is prompted with a question, answerID is returned in


the next invocation. Only one answer can be returned.

Forms Use to show a user entry form as part of the hook process.
forms := t_forms();
form1 := t_form('00_T_CUST', 1, 1);
forms.extend;
forms(forms.last) := form1;
hookOutput.forms := forms;
Forms forms = new Forms();
Form form1 = new Form();
form1.setCardinality(1);
form1.setObjectType(1);
form1.setObjectName("'00_T_CUST ");
forms.addForm(form1);
hookOutput.setForms(forms);

iHook Package Functions


The iHook Package includes the following:

Function See...

Rowset iHook Package: Rowset Functions in Stored Procedures on page 30


Functions
iHook Package: originalRowset

iHook Package: originalRowset

Developing for webMethods OneData Version 9.7 29


M
Even Header
OneDataHook Functions and Stored Procedures

Function See...

iHook Package: selectedRowset

iHook Package: selectedRowset

Questions iHook Package: Question and Answers

Forms iHook Package: Forms Default Value

iHook Package: showableRowset

Columns iHook Package: actionRowset

iHook Package: Rowset Functions in Stored Procedures


Rowset is the underlying structure for the rowset functions, such as, originalRowset ,
ShowableRowset and selectedRowset . There are basic functions that apply to all of them.

GetColumnValue Function
Returns the value of the column.

Parameters Description

Row Specic row index in the row set.

Column Name Column to be queried

Usage example
Row:= hookInput.OriginalRowset.rowset(1);
Ihook.getColumnValue(row, 'CUST_NM');

SetColumnValue Function
Sets the value of the specic column in a row.

Note: For dates, use YYYY-MM-DD HH24:MI:SS format.

Parameters Description

Row Specic row index in the row set.

Developing for webMethods OneData Version 9.7 30


M
Odd Header
OneDataHook Functions and Stored Procedures

Parameters Description

Column Name Column to be queried.

Value Actual value to set.

Usage example
Row := t_row()
Ihook.setColumnValue(row, 'CUST_NM', 'Software AG')

GetColumnOldValue Function
For updates, users can retrieve the old value in a post-event hook.

Parameters Description

Row Specic row index in the row set.

Column Name: Column to be queried.

Usage example
Row:= hookInput.OriginalRowset.rowset(1);
Ihook.getColumnOldValue(row, 'CUST_NM');

getMSColumnValue Function
Returns the values of the multi select column.

Parameters Description

Row Specic row index in the row set.

Column Name: Multi-select column name to be queried.


Row:= hookInput.OriginalRowset.rowset(1);
Ihook. getMSColumnValue (row, 'COL_MS');

setMSColumnValue Function
Sets the values of the specic multi-select column in a row.

Parameters Description

Row Specic row index in the row set.

Column Name: Multi-select column name to be queried.

Developing for webMethods OneData Version 9.7 31


M
Even Header
OneDataHook Functions and Stored Procedures

Parameters Description

MS Column Value Array of values to set.


msValues t_ms_values;
msValues := t_ms_values();
msValues.extend;
msValues(msValues.last) := '1';
msValues.extend;
msValues(msValues.last) := '2';
Row := t_row()Ihook.setMSColumnValue(row,'COL_MS', msValues);

getMSColumnOldValue Function
For updates, user can retrieve previous values of the multi-select column in a post-event
hook.

Parameters Description

Row Specic row index in the row set.

Column Name: Multi-select column name to be queried.


Row:= hookInput.OriginalRowset.rowset(1);
Ihook. getMSColumnOldValue (row, 'COL_MS');

setMSColumnOldValue Function
To update a multi-select column, set the old values in the column using this method and
by seing the new value(s) in setMSColumnValue.

Parameters Description

Row Specic row index in the row set.

Column Name: Column name to be queried.

MS Column Value Array of values to set.


msOldValues t_ms_values; msOldValues:= t_ms_values();
msOldValues := Ihook.
getMSColumnOldValue (row, 'COL_MS');
rowNew := t_row() Ihook. setMSColumnOldValue (rowNew, 'COL_MS',
msOldValues);

Developing for webMethods OneData Version 9.7 32


M
Odd Header
OneDataHook Functions and Stored Procedures

Count Function

Parameters Description

Row Rowset for which the member count needs to be


determined.
cnt= hookInput.OriginalRowset.rowset.count;

iHook Package: actionRowset


Property of hookOutput for the user to perform an action on any object in OneData.

Stored Procedure: ActionRowset initialization function: t_actionrowset


Returns an actionRowset construct to be aached to hookOutput.
Invokes Java functions:
ActionRowset() setRows() setTableName() setObjectName() setObjectType() setOrder()
setActionType() setConceptualObjectName()

Parameters

Rows Array of row n array of column/value pair.

Table Name Table name of the underlying data object in OneData. You
can specify data object name instead of Table Name, as in
syntax 3.

Object Type Type of object: 1: table; 2: data object.

Sort Order Order of action to be executed.

Type of DML Insert, update, and delete are supported in both SP and
Java RMI. Purge and restore are supported only in Java
RMI.

ConceptualObjectName Optional if the action must be combined in workow


under the context of the conceptual object.

Usage Example
Table with no Conceptual Object
Ars := t_actionrowset(rows,'TABLE1', 2, 'update');

Developing for webMethods OneData Version 9.7 33


M
Even Header
OneDataHook Functions and Stored Procedures

Table with no Conceptual Object (alternate)


Ars := t_actionrowset(rows,'TABLE1', 1, 2, 'update');

Table with Conceptual Object Context.


Ars := t_actionrowset(rows, 'TABLE1', 2, 'update', 'Person CO');

Data Object with Conceptual Object Context


Ars := t_actionrowset(rows,'Data Object', 2, 2,'update','Person CO');
ActionRowset objAction = new ActionRowset();
objAction.setObjectName("Data Object");
objAction.setObjectType(2);
objAction.setOrder(1);
objAction.setActionType(objAction.ACTION_TYPE_INSERT);
objAction.setRows(rows);
objection.setconceptualObjectName("Conceptual Object");

iHook Package: originalRowset


originalRowset is a property of hookInput . The original dataset that is passed from
OneData to the iHook.

Rowset Properties
The following table displays the stored procedures and Java functions.

Stored Procedure Java Function and Description


Function

Rowset getOriginalRowset(). Array of column/value pair Returns rowset.


For example:
hookInput.originalRowset.rowset(1)hookInput.
getOriginalRowset()

Rowset.count No java function. Returns number of rowsets in hookInput


originalrowset . For example:
hookInput.originalRowset.rowset.count

ActionType getActionType(). Returns the type of action ('insert', update' or


'delete') if initiated from command hooks, the parameter is
blank.
hookInput.originalRowset.actionType
hookInput.getOriginalRowset().getActionType()

TableName getTableName(). Returns the physical table name that caused


the action. For example:
hookInput.originalRowset.TableName
hookInput.getOriginalRowset().getTableName()

Developing for webMethods OneData Version 9.7 34


M
Odd Header
OneDataHook Functions and Stored Procedures

Stored Procedure Java Function and Description


Function

ConceptualObjectName getConceptualObjectName(). Returns the conceptual object


context with the table name. For example:
hookInput.originalRowset.conceptualObjectName
hookInput.getOriginalRowset().getConceptualObjectName()

DataObjectName getObjectName(). Returns the Data Object Name that invoked


the hook or virtual object. For example:
hookInput.originalRowset.dataObjectName
hookInput.getOriginalRowset().getObjectName()

iHook Package: selectedRowset


selectedRowset is a property of hookInput . It is a selection result where the user is
prompted to select one or more records and then the hook is invoked again.

Stored Procedure Java Function and Description


Function

Rowset getSelectedRowset(). Returns rowset, which is an array of column/


value pair. For example,
hookInput.selectedRowset.rowsethookInput.getSelectedRowset()

Rowset.count None. Returns number of rowsets in hookInput originalrowset . For


example:
hookInput.selectedRowset.rowset.count

iHook Package: showableRowset


showableRowset is a property of hookOutput where the user is prompted to select one
or more records. Records can belong to a persistent object (data object in OneData)
or a virtual object, where the grid is constructed from the captions created from
showableRowset .

Stored Procedure Initializationfunction:t_showableRowset


Returns a showable rowset that can be connected to hookOutput. Calls the java
functions:
ShowableRowset()
objShowable.setRows()

Developing for webMethods OneData Version 9.7 35


M
Even Header
OneDataHook Functions and Stored Procedures

objShowable.setTableName()
objShowable.setObjectName()
objShowable.setObjectType()
objShowable.setSelectionType()
hookOutput.setShowRowset(objShowable)

Parameter Description

Rows Array of rows. A row is an array of column/value pair.

Object Table name in OneData, data object name, virtual object name or
'various' if not a persistent object.

Object Type Type of object:


1. Table
2. Data Object
3. Virtual Object
4. Various
Single. for one selection (option buons)
Number of
selections multi. for multiple selections
none. for no selections

Usage Example
showRowset:= .t_showableRowset(rows, 'various',4, 'multi);
showRowset := t_showableRowset (rows, 'TABLE1',1,'single');
ShowableRowset objShowable = ShowableRowset();
objShowable.setRows(rows)");
objShowable.setTableName("TABLE1");objShowable.setObjectName("Data Object
1");objShowable.setObjectType(1);objShowable.setSelectionType(1);hookOutput.
setShowRowset(objShowable)

iHook Package: Question and Answers


Property of hookOutput where the user is prompted with questions and answers. The
answer is a construct to create the question structure.

Note: If there is a question, Cancel is displayed automatically. Clicking Cancel closes the
iHook window and session.

Stored Procedure: Question initialization function: t_question


Returns a question construct that can be aached to hookOutput .

Developing for webMethods OneData Version 9.7 36


M
Odd Header
OneDataHook Functions and Stored Procedures

Java Function Parameters Description

Question()setText() Question Text Text displayed to the user as the question


setAnswers() prompt.

answers Construct of an answer - ID/answer text pair.

Usage Example
Ques := t_question('Please choose option to proceed', answers)
Question ques = new Question();
ques.setText("Please choose option to proceed");ques.setAnswers(answers);

Stored Procedure: Answers initialization function: t_answers


Collection of answers. Each individual answer is a ID/answer text pair.

Java Function Description and Parameters

None None

Usage Example
Answers := t_answers();

Stored Procedure: Answer initialization function: t_answer


Returns a single answer construct that is part of the answers collection. Answers
collection is aached to the question and that in-turn to hookOutput. The property takes
no java functions.

Parameters Description

Answer ID Numeric ID of the answer that will be returned with hookInput on


the next invocation.

Sort Order : Order of the answer displayed to the user.

Answer Text : Answer text displayed to the user.

Usage Example
Answer:= t_answer(1,1,'Create new customer');
answer1 = new Answer();
answer1.setId(1);
answer1.setText("Associate Existing Customer");
answer1.setOrder(0);
answer2 = new Answer();
answer2.setId(2);
answer2.setText("Create New Customer");

Developing for webMethods OneData Version 9.7 37


M
Even Header
OneDataHook Functions and Stored Procedures

answer2.setOrder(2);List answers = new ArrayList();


answers.add(answer1);answers.add(answer2);

iHook Package: Forms Default Value


Default values can be set when a form is displayed on an iHook invocation.

Stored Procedure: Form.rowset


Sets the default values of the form that is displayed to the user.

Java Function Parameter & Description

setRowset() actionRowSetData Object Action rowset that has the default rows
embedded.
ROWS := t_rows ();ROW := t_row ();iHoo k .setColumnVal ue(row,'T EST_COL',
'U');
ROWS.EXTEND;
ROWS (ROWS.LAST) := ROW;
action : = t_actionrowset (ROWS, 'Org',2 , 0, 'update');
form1 := t_form(Org , 2, 1);
form1.Rowset := action;RowsetdefaultRowset = new Rowset();
Row thisRow = new Row();
List columns = new ArrayList();
Column column1 = new Column();
column1.setName("CUS TOMER_ID");
column1.setValue("100");
columns.add(column1);
childRow.setColumns(columns);
List rowList = new ArrayList();
rowList.add(thisRow);
defaultRowset.setRows(rowList);
Form form1 = new Form();
form1.setCardinality(1);
form1.setObjectType(2);
form1.setObjectName("Org");
form1.setRowset(defaultRowset);

Stored Procedure: Form. skipReferenceValidation


Species whether the reference validations enforced on command buon selection
should be skipped. To skip, input value as 1.

Java Function Parameters and Description

setSkipReferenceValidation skipreferencevalidation Parameter to specify whether to


enforce reference validation.
form1.skipreferencevalidation := 1;form1.setSkipReferenceValidation

Developing for webMethods OneData Version 9.7 38


M
Odd Header
OneDataHook Functions and Stored Procedures

iHook Package: Forms


Property of hookOutput where the user is prompted to ll a data entry form and entered
values returned.

Stored Procedure Java Function


Function

Form initialization Form() setCardinality(); setObjectType(); setObjectName();.


function: t_form
Returns a form rowset construct to be aached to hookOutput.

Parameter Description

Data Object Name Name of the object to display. This must


correspond to object type:
1 - Table
2 - Data Object

Number of instances Number of form instances for the data


object to display.
forms:= t_forms();
form1 := t_form('TBL_PARTY', 1, 1);
forms.extend;
forms(forms.last) := form1;
hookOutput.forms := forms;
Forms.
Forms := t_forms();Form1:= t_form('Data Object',
2,1);Forms.extend;forms(forms.last)
:= form1;hookOutput.forms
:= forms;
Forms.
Forms forms = new Forms();
Form form1 = new Form();
form1.setCardinality(1);
form1.setObjectType(2);
form1.setObjectName("Data Object");
forms.addForm(form1);
hookOutput.setForms(forms);

ihook.getColumnValue Returns a value from the rowset in a form. Get value from the
form rowset. For example,
ihook.getColumnValue(form1.rowset.rowset(1), 'CUST_NM')

Validation Rules
All validations are applied to the form when a user clicks the command buon on the
iHook screen. The following rules are enforced.
Regular expression validation

Developing for webMethods OneData Version 9.7 39


M
Even Header
OneDataHook Functions and Stored Procedures

Reference key validation


Passive constraint validation
Pending reference key validation
Temporal rule validation
Transfer date validation
Validation using data validation script
Rules engine validation

iHook Package: Column Functions in Java iHooks


Column is the structure value of a column as name/value pair.

Function Description

getValue() Returns the value of the column as String.


Parameters: None.
Example
String value = column.getValue();

setValue() Sets the value of the specic column. For date columns,
you must specify the date in the format YYYY-MM-DD
HH24:MI:SS.
Parameters: String: Actual value to set.
Example
column.setValue(value);

getOldValue() For updates, user can retrieve the old value in a post-event
hook. No parameters.
Example
String oldValue = column.getOldValue();

getMsValues() Returns the values of the multi select column as a List. No


parameters.
Example
List valueList = column.getMsValues ();

setMsValues() Sets the values of the specic multi select column.


Parameters: List: List of values to set.
Example

Developing for webMethods OneData Version 9.7 40


M
Odd Header
OneDataHook Functions and Stored Procedures

Function Description
column.setMsValues(msValues);

getOldMSValues() For updates, users can retrieve the previous values of the
multi-select column in a post-event hook. No parameters.
Example
List oldValues = column.getOldMSValues();

setOldMSValues() To update a multi-select column, set the old values in the


column using this method and by seing the new value(s) in
setMsValues.
Parameters: List: List of values to set.
Example
column.setOldMSValues(msValues);

isPrimaryKey() Indicates whether the column is a Primary Key column.


Parameters: None.

setPrimaryKey() Species whether the column is a Primary Key column.


Parameters: boolean: True if the column is a primary key;
otherwise set to false.

isMultiSelect() Indicates whether the column is a MultiSelect column. No


parameters.

setIsMultiSelect() Species whether the column is a MultiSelect column.


Parameters: boolean: True if the column is a primary key;
otherwise set to false.

iHooks Sample Code


This sections shows examples for stored procedure and Java iHooks.

Stored Procedure
iHook Required Section
hookInput t_hookInput;
hookOutput t_hookOutput := t_hookOutput();

begin-- Gets the rows that the user has clicked on.
hookInput := iHook.getHookInput (v_data_in);--

Developing for webMethods OneData Version 9.7 41


M
Even Header
OneDataHook Functions and Stored Procedures

hookOutput.invocationNumber := hookInput.invocationNumber;
hookOutput.originalRowset := hookInput.originalRowset;

Hello World in iHooks Example


CREATE OR REPLACE PROCEDURE spHelloWorldHook (v_data_in in
clob, v_data_out out clob) as
hookInput t_hookInput;
hookOutput t_hookOutput := t_hookOutput();

begin-- Gets the rows that the user has clicked on.
hookInput := iHook.getHookInput (v_data_in);--
hookOutput.invocationNumber :=
hookInput.invocationNumber; hookOutput.originalRowset :=
hookInput.originalRowset;

-- Sets the message to be displayed


hookOutput.message := 'Hello World!';

-- Displays the message at the top of the OneData screen


v_data_out := iHook.getHookOutput(hookOutput);end;/

Creating a Showable Rowset from an Existing Object


IF hookInput.invocationNumber = 0 THEN
rows := t_rows ();
FOR cur IN potentially_matching_persons LOOP
row := t_row();
iHook.setColumnValue (row,'PDS_PER_ID',cur.pds_per_id);
rows.extend;
rows (rows.last) := row;
v_found := true;
END LOOP;
IF v_found THEN
showRowset := t_showableRowset (rows,'PDS_PERSON_MASTER',1,
'single');
hookOutput.showRowset := showRowset;
END IF;
-
answers := t_answers();
answer := t_answer(1, 1, 'Associate');
answers.extend;
answers (answers.last) := answer;
answer := t_answer (2,2,'Create New');
answers.extend;
answers(answers.last) := answer;
question := t_question ('Select a row to associate and click
"Associate" or click on "Create New" to create a
new row', answers);
hookOutput.question := question;END IF;

Creating a Showable Rowset for a Custom Object


for cur in cur_find_new_accounts loop
row := t_row();
j:=j+1;
iHook.setColumnValue (row,'ACCT_CD',cur.ACCT_CD);
iHook.setColumnValue (row,'ACCT_NM',cur.ACCT_NM);
rows.extend;
rows (rows.last) := row;
end loop;
if (j>0)
then

Developing for webMethods OneData Version 9.7 42


M
Odd Header
OneDataHook Functions and Stored Procedures

showRowset := t_showableRowset (rows,'various', 4,'single');


hookOutput.showRowset := showRowset;
answers := t_answers();
answer := t_answer(1,1,'Next');
answers.extend;
answers (answers.last) := answer;
answer := t_answer (2,2,'Cancel');
answers.extend;
answers(answers.last) := answer;
question := t_question ('Select applicable accounts:', answers);
hookOutput.question := question;
end if;

Insert Action
FOR int_id IN to_be_inserted_rows LOOP
row := t_row();
iHook.setColumnValue (row,'SYS_ID', int_id.app_id);
iHook.setColumnValue (row,'SRC_VAL_ID', int_id.int_id);
iHook.setColumnValue (row,'TRGT_VAL_ID', v_to_map_item_id );
rows.extend;
rows (rows.last) := row;
end loop;

action := t_actionRowset (rows,'CODE_TRSLTN',1, 1,'insert');


actions.extend;
actions(actions.last) := action;
hookOutput.actions := actions;
hookOutput.message := 'Update/Insert Completed Successfully';

Conceptual Object DML


When a series of action queried need to be executed from the iHook and internally
within OneData needs to be linked to one conceptual transaction, a conceptual object
context needs to be given in the iHook. Highlighted in bold below.
rows := t_rows();
row := t_row();

SELECT NVL (MAX (pds_person_master_id) + 1,1)INTO v_pds_person_master_id


FROM pds_person_master;

iHook.setColumnValue (row,'PDS_PERSON_MASTER_ID', v_pds_person_master_id);


iHook.setColumnValue (row,'PERSON_LNAME',
iHook.getColumnValue (row_ori,'CLNSD_EMP_LNAME'));
iHook.setColumnValue (row,'PERSON_FNAME',
iHook.getColumnValue (row_ori,'CLNSD_EMP_FNAME'));
iHook.setColumnValue (row,'SRC_SYS_ID',
iHook.getColumnValue (row_ori,'SRC_SSY_ID'));
iHook.setColumnValue (row,'PERSON_TYP_ID',
iHook.getColumnValue (row_ori,'CLNSD_EMP_TYP'));

rows.extend;
rows (rows.last) := row;

action := t_actionRowset (rows,'PDS_PERSON_MASTER',1,1,'insert',


'Person (Gold View)');
actions.extend;actions(actions.last) := action;

rows := t_rows();row := t_row();

SELECT NVL (MAX (pds_person_address_id) + 1,1) INTO v_pds_person_address_id

Developing for webMethods OneData Version 9.7 43


M
Even Header
OneDataHook Functions and Stored Procedures

FROM pds_person_address;
/*insert into address */

iHook.setColumnValue (row,'PDS_PERSON_ADDRESS_ID',v_pds_person_address_id);
iHook.setColumnValue (row,'PERSON_ID', v_pds_person_master_id);
iHook.setColumnValue (row,'PDS_ADDR_LINE_1',
iHook.getColumnValue (row_ori,'CLNSD_ADDR_LINE_1'));
iHook.setColumnValue (row,'PDS_ADDR_LINE_2',
iHook.getColumnValue (row_ori,'CLNSD_ADDR_LINE_2'));
iHook.setColumnValue (row,'CITY_NM',
iHook.getColumnValue (row_ori,'CITY_NM'));
iHook.setColumnValue (row,'ST_NM',
iHook.getColumnValue (row_ori,'ST_NM'));
iHook.setColumnValue (row,'CNTRY_ID',
iHook.getColumnValue (row_ori,'CNTRY_ID'));

rows.extend;
rows(rows.last) := row;

action := t_actionRowset (rows,'PDS_PERSON_ADDRESS',1, 2,'insert',


'Person (Gold View)');
--
actions.extend;
actions (actions.last) := action;

Form
CREATE OR REPLACE procedure formTestHook (in_xml in clob, out_xml out clob)as

hookInput t_hookInput;
hookOutput t_hookOutput := t_hookOutput();

question t_question;
answer t_answer;
answers t_answers;
forms t_forms;
form1 t_form;
form2 t_form;

begin
hookInput := ihook.getHookInput(in_xml);
hookOutput.invocationNumber := hookInput.invocationNumber;
hookOutput.originalRowset := hookInput.originalRowset;
if hookInput.invocationNumber = 0 then
hookOutput.message := 'Form Test Hook';
answers := t_answers();
answer := t_answer(1, 1, 'OK');
answers.extend; answers(answers.last) := answer;
question := t_question('Choose action', answers);
hookOutput.question := question;
forms := t_forms();
form1 := t_form('Data Object 1', 2, 2);
forms.extend; forms(forms.last) := form1;
hookOutput.forms := forms;

else
forms := hookInput.forms;
form1 := forms(1);
hookOutput.message := ihook.getColumnValue(form1.rowset.rowset(1), 'N')
|| '<br>' || ihook.getColumnValue(form1.rowset.rowset(1), 'S')
|| '<br>' || ihook.getColumnValue(form1.rowset.rowset(1), 'D');
end if;

Developing for webMethods OneData Version 9.7 44


M
Odd Header
OneDataHook Functions and Stored Procedures

out_xml := ihook.getHookOutput(hookOutput);
end;
/

Java RMI
iHook Required Section
This is required at the beginning of any Java iHook execute() method.
HookOutput hookOutput = new
HookOutput();hookOutput.setInvocationNumber(hookInput.getInvocationNumber());
hookOutput.setOriginalRowset(hookInput.getOriginalRowset());

Hello World in iHooks


import com.datafoundations.onedata.hook.OnedataHook;
import com.datafoundations.onedata.hook.HookOutput;
import com.datafoundations.onedata.hook.HookInput;
import java.rmi.RemoteException;
import java.rmi.server.UnicastRemoteObject;

public class HelloWorldHook extends UnicastRemoteObject


implements OnedataHook{
public HelloWorldHook() throws RemoteException {
super(); }

public void init() throws RemoteException { }


public void commit() throws RemoteException { }
public void rollback() throws RemoteException { }
public void close() throws RemoteException { }
public HookOutput execute(HookInput hookInput) throws RemoteException {
HookOutput hookOutput = new HookOutput();
hookOutput.setInvocationNumber(hookInput.getInvocationNumber());
hookOutput.setOriginalRowset(hookInput.getOriginalRowset());
hookOutput.setMessage("Hello World!");
return hookOutput; }
public void setSavepoint(String string) { }
public void releaseSavepoint(String string) { }
public void rollback(String string) { }}

Creating a Showable Rowset from an Existing Object


if (hookInput.getInvocationNumber() == 0) { ActionRowset objActionRow =
hookInput.getOriginalRowset();
if (objActionRow != null) {
List list_Rows = objActionRow.getRows();
ShowableRowset objShowable = new ShowableRowset();
objShowable.setRows(hookInput.getOriginalRowset().getRows());
objShowable.setObjectName(hookInput.getOriginalRowset()
.getObjectName());
objShowable.setObjectType(hookInput.getOriginalRowset()
.getObjectType());
objShowable.setSelectionType(1);
objShowable.setSelectionTypeDesc("Single");
hookOutput.setShowRowset(objShowable);
Question question = new Question();
test_Question.setText ("Select a row to associate and click on
'Associate' or click on 'Create New' to create a new row'");
Answer answer1 = new Answer();
answer1.setId(1);

Developing for webMethods OneData Version 9.7 45


M
Even Header
OneDataHook Functions and Stored Procedures

answer1.setText("Associate");
answer1.setOrder(1);
Answer answer2 = new Answer();
answer2.setId(2);
answer2.setText("Create New");
answer2.setOrder(2);
List answers = new ArrayList();
answers.add(answer1);
answers.add(answer2 );
auestion.setAnswers(answers);
hookOutput.setQuestion(question);
}
}

Creating a Showable Rowset for a Custom Object


List rowList = new ArrayList();
Row objRow1 = new Row();
List list_col1 = new ArrayList();
Column objCOL1 = new Column();
objCOL1.setName("ACC_CD");
objCOL1.setValue("100");
list_col1.add(objCOL1);
Column objCOL2 = new Column();
objCOL2.setName("ACC_NM");
objCOL2.setValue("AC100");
list_col1.add(objCOL2);

objRow1.setColumns(list_col1);
rowList.add(objRow1);
objRow1 = new Row();
list_col1 = new ArrayList();
objCOL1 = new Column();
objCOL1.setName("ACC_CD");
objCOL1.setValue("200");
list_col1.add(objCOL1);

objCOL2 = new Column();


objCOL2.setName("ACC_NM");
objCOL2.setValue("AC200");
list_col1.add(objCOL2);
objRow1.setColumns(list_col1);
rowList.add(objRow1);

ShowableRowset objShowable = new ShowableRowset();


objShowable.setRows(rowList);
objShowable.setObjectName("TEST");
objShowable.setObjectType(4);
objShowable.setSelectionType(1);
objShowable.setSelectionTypeDesc("Single");
hookOutput.setShowRowset(objShowable);

Conceptual Object DML


The following code inserts a record to Brand object in Product->Brand->Vendor
hierarchy. The insertion is done with conceptual object context.
if(hookInput.getInvocationNumber() == 0){
Question question = new Question();
question.setText("Enter Data");
Answer answer1 = new Answer();
answer1.setId(1);
answer1.setText("Submit");

Developing for webMethods OneData Version 9.7 46


M
Odd Header
OneDataHook Functions and Stored Procedures

answer1.setOrder(0);
List answerList = new ArrayList();
answerList.add(answer1);
question.setAnswers(answerList);
hookOutput.setQuestion(question);
Forms forms = new Forms();
Form form1 = new Form();
form1.setCardinality(1);
form1.setObjectName("Brand ");
forms.addForm(form1);
hookOutput.setForms(forms);
}

else{
Forms forms = hookInput.getForms();
List list_forms = forms.getForms();
Iterator iter = list_forms.iterator();
Actions objActions = new Actions();
int order = 0;

while(iter.hasNext()){
Form form1 = (Form)iter.next();
ActionRowset objActionRowset = new ActionRowset();
objActionRowset.setActionType(
objActionRowset.ACTION_TYPE_INSERT);
objActionRowset.setRows(form1.getRowset().getRows());
objActionRowset.setObjectName(form1.getObjectName());
objActionRowset.setObjectType(2);
objActionRowset.setConceptualObjectName("Product_Catalog");
objActionRowset.setOrder(1);
objActions.addAction(objActionRowset);
}
hookOutput.setActions(objActions);
hookOutput.setMessage("Data inserted successfully.");
}

Form
import java.rmi.RemoteException;
import java.rmi.server.UnicastRemoteObject;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import com.datafoundations.onedata.hook.ActionRowset;
import com.datafoundations.onedata.hook.Actions;
import com.datafoundations.onedata.hook.Answer;
import com.datafoundations.onedata.hook.Form;
import com.datafoundations.onedata.hook.Forms;
import com.datafoundations.onedata.hook.HookInput;
import com.datafoundations.onedata.hook.HookOutput;
import com.datafoundations.onedata.hook.OnedataHook;
import com.datafoundations.onedata.hook.Question;

public class SampleFormHook extends UnicastRemoteObject


implements OnedataHook {
public SampleFormHook() throws RemoteException { super(); }

public void init() throws RemoteException { }


public void commit() throws RemoteException { }
public void rollback() throws RemoteException { }
public void close() throws RemoteException { }
public HookOutput execute(HookInput hookInput)
throws RemoteException {

Developing for webMethods OneData Version 9.7 47


M
Even Header
OneDataHook Functions and Stored Procedures

HookOutput hookOutput = new HookOutput();


hookOutput.setInvocationNumber(hookInput.getInvocationNumber());
hookOutput.setOriginalRowset(hookInput.getOriginalRowset());
if(hookInput.getInvocationNumber() == 0){
Question question = new Question();
question.setText("Enter Data");
Answer answer1 = new Answer();
answer1.setId(1);
answer1.setText("Submit");
answer1.setOrder(0);
List answerList = new ArrayList();
answerList.add(answer1);
question.setAnswers(answerList);
hookOutput.setQuestion(question);
Forms forms = new Forms();
Form form1 = new Form();
form1.setCardinality(1);
Form1.setObjectName("Data Object");
forms.addForm(form1);
hookOutput.setForms(forms);
}
else{
Forms forms = hookInput.getForms();
List formList = forms.getForms();
Actions actions = new Actions();

for (Iterator it = formList.iterator();


it.hasNext();) {
Form form = (Form) it.next();
ActionRowset insertRowSet = new ActionRowset();
insertRowSet.setObjectName(form.getObjectName());
insertRowSet.setActionType(ActionRowset.ACTION_TYPE_INSERT);
insertRowSet.setActionTypeDesc("INSERT");
insertRowSet.setObjectType(form.getObjectType());
insertRowSet.setRows(form.getRowset().getRows());
actions.addAction(insertRowSet);
}
hookOutput.setActions(actions);
hookOutput.setMessage("Data inserted successfully.");
}
return hookOutput;
}
public void setSavepoint(String string) { }
public void releaseSavepoint(String string) { }
public void rollback(String string) {
}}

Developing for webMethods OneData Version 9.7 48


M
Odd Header
Working In Process Flow Designer

3 Working In Process Flow Designer


Process Flow Designer ................................................................................................................ 50
Building a Process Flow .............................................................................................................. 63
Process Flow Example Scenarios ............................................................................................... 64
Process Flow Java Code Samples .............................................................................................. 73

Developing for webMethods OneData Version 9.7 49


M
Even Header
Working In Process Flow Designer

Process Flow Designer


Process Flow Designer is a graphical user interface for designing process ows. The
process ow denes the sequence of actions OneData performs on objects and records.
Once you have created a process ow, you can add it to a process ow hook. With
Process Flow Designer, you can create a hook without writing code.
Access Process Flow Designer from within the OneData Add a Hook screen. While you
are dening the hook, you can create the process ow and link it directly within the
hook. Process ows within hooks provide interactive triggering of process ow actions
from the user interface.
A process ow diagram links components and processes together with a starting point
and one or several end points. When the process ow diagram is associated with a
OneData hook, interaction from the user interface can trigger the process ow actions.
A process ow diagram contains model components and process items. A model component
has the pieces of the process ow diagram, including the start point, end point, and
the process containers that contain individual process items. A process item is the
action that is executed. For more information about model components, see "Model
Components" on page 51. For more information about process items, see "Process
Items" on page 52.
The following is an example of a process ow diagram.

Developing for webMethods OneData Version 9.7 50


M
Odd Header
Working In Process Flow Designer

Model Components
Model components make up the process ow diagram and include the start, stop, and
the containers for process items. Each component in the diagram is assigned a default
name, but you can dene additional properties by double clicking the component.
Process Flow Designer has the following model components:
Start. A process ow diagram must have one and only one Start component. Start
components contain the originalrowset property from iHooks and indicate where
the process starts. The component has one item implicitly embedded. Additional
process items cannot be added to the Start component.

Start Property Description

Name Name of the start component. The name must be unique; it


can contain spaces or blanks, but special characters are not
allowed.

Data Object Data object is required, even if cardinality is 0 for the process
ow execution.

Comments Comments or description to be aached to the Start


component. Informational purposes only. Optional.

Stop. A process ow diagram must have at least one, but may have many Stop
components. Stop components cannot have outbound connections and indicate
where the process ends. The component has one embedded stop item. Additional
process items cannot be added to the Stop component.

Stop Property Property

Name Name of the stop component. The name must be unique; it


can contain spaces or blanks, but special characters are not
allowed.

Message Message shown to the user when end of the process ow


branch is invoked.

Comments Comments or description to be aached to the Stop


component. Informational purposes only. Optional.

Process Component. A process component contains the process that is being executed
in a process ow. The process component contains the individual process items,

Developing for webMethods OneData Version 9.7 51


M
Even Header
Working In Process Flow Designer

which are either interactive as forms, grids, or questions, or non-interactive as


OneData actions, mappings, or sequences.

Process Description
Property

Name Name of the process component. The name must be unique;


it can contain spaces or blanks, but special characters are not
allowed.

Comments Comments or description of the process component.


Informational purposes only. Optional.

Loop. Loop components are containers for splier (start loop) and aggregator (end
loop) process items.

Loop Property Description

Name Name of the loop component. The name must be unique; it


can contain spaces or blanks, but special characters are not
allowed.

Comments Comments or description to be aached to the Loop


component. Informational purposes only. Optional.

Process Items
Process items are the basic building blocks that make up a process ow diagram. They
are broadly classied into process items and loop items.
Process items contain triggers that are interactive and non-interactive. Interactive and
non-interactive process items can only be added to process model components.
Looping items consist of splier and aggregator process items and can only be added
to a looping model component. For more information about interactive process items,
see "Interactive Process Items" on page 52. For information about non-interactive
process items, see "Non-Interactive Process Items" on page 55. For information about
looping process items, see "Looping Process Items" on page 60.

Interactive Process Items


You can congure the properties for a process item. The following table describes the
interactive process items.

Developing for webMethods OneData Version 9.7 52


M
Odd Header
Working In Process Flow Designer

Interactive Description
Process Item

Form Display a form to the user to elicit input. Form here is in the
context of an OneData data object.

Data Grid Similar to showable-rowset in iHooks, this prompts the user for a
selection from a grid display.

Decision Ability to prompt the user with options and determine execution
paths based on the selection. Successor of question-answer
construct in iHooks.

Form Process Item Properties


A Form is a process item which displays a data entry screen to the user. The aributes of
the data object selected in the General tab are populated in the Mapping tab. The aributes
displayed on the screen can be pre-populated based on the requirements in the Mapping
tab. This process item is within the process component.

Property Description

Name General tab. Name of the form item. The name must be unique;
the name can contain spaces or blanks, but cannot contain special
characters.

Data Object General tab. Data object name from which the form will inherit
aributes. Mandatory eld.

Cardinality General tab. Number of forms to display for entry/edit. Default is


1.

Comments General tab. Comments or description to be aached to the process


item. Informational purposes only. Optional.

Skip General tab. Whether to skip the reference validations in the object.
Reference
Validations

Aribute Mapping tab. Aributes of the selected data object. Populated when
the data object is selected.

Developing for webMethods OneData Version 9.7 53


M
Even Header
Working In Process Flow Designer

Property Description

Components Mapping tab. Components present in the previous steps to which


the Form aributes can be mapped to, if required.

Item Mapping tab. Items present in the selected component to which the
Form aributes can be mapped to, if required.

Values Mapping tab. Aributes present in the selected item to which the
Form aributes can be mapped to, if required.

DataGrid Process Item Properties


DataGrid process items display records from an object for user action.

Property Description

Name Name of the data grid item. The name must be unique; the
name can contain spaces or blanks, but cannot contain special
characters.

Data Object Mandatory. Data object name to populate in the data grid.

Filter Query Condition on which to lter data returned to the data grid. Filter
Query can be static (based on a xed value) or dynamic (based on
the user's selection in previous component), for example:
Static query: Name = 'CUST_NAME
Dynamic query: Name in {ComponentNameItemNameName}

Note: If multiple records may match the query results, use the
keyword in instead of = symbol in the query.

Selection User selection option for the rows in the data grid. Single
Type provides radio buon, Multi provides check boxes for multiple
rows selection, and None is used to display the data.

Comments Comments or description to be aached to the process item.


Informational purposes only.

Decision Process Item Properties


Decision process items elicit user input for action on the data of that step.

Developing for webMethods OneData Version 9.7 54


M
Odd Header
Working In Process Flow Designer

Property Description

Name Name of the decision item. The name must be unique; the
name can contain spaces or blanks, but cannot contain special
characters.

Decision Text The question or message that displays to the user to elicit a
response.

Decision Options that display to users to elicit action. Separate each option
Values by a semi- colon (;), for example, OK;Cancel.

Comments Comments or description to be aached to the process item.


Informational purposes only.

Non-Interactive Process Items


Process Flow Designer provides the following non-interactive process items:
Sequence. Fetches the value of a sequence to insert into an object.
Action. Executes an action on a data object.
CO Action. Executes an action on a conceptual object.
Mapping. Maps aributes from multiple items for an action on an object.
Custom Data. Provides users an option to execute a custom SQL query for retrieving
data.
Custom Java. Provides users an option to execute a custom Java code as part of the
process ow.
The following sections describe the properties for each of the non-interactive process
items.

Sequence Process Item Properties


Sequence process items fetch the value of a sequence to insert into an object. Only
database sequences are supported. This process item is within the process component.

Property Description

Name Name of the sequence item. The name must be unique; the
name can contain spaces or blanks, but cannot contain special
characters.

Developing for webMethods OneData Version 9.7 55


M
Even Header
Working In Process Flow Designer

Property Description

Sequence Logic or query for evaluating the next value of the sequence, for
Logic example, SELECT group_seq.NEXTVAL FROM DUAL.

Sequence Type of Sequence. Only available for an SQL sequence.


Type

Comments Comments or description to be aached to the process item.


Informational purposes only.

Action Process Item Properties


Action process items execute an action on a data object. This process item is within the
process component

Property Description

Name Name of the action item. The name must be unique; the name can
contain spaces or blanks, but cannot contain special characters.

Process Process component from which data must be retrieved for the
Component action.

Data Source Form or DataGrid from which data is received for the action.
Item

Data Object Required. Data object on which to execute the action.

Action Action to execute:


Insert: Inserts the row into the data object.
Update: Updates the corresponding row in the data object.
Delete: Deletes the corresponding row in the data object.

Comments Comments or description to be aached to the process item.


Informational purposes only.

CO Action Process Item Properties


CO Action process items execute an action on a conceptual object. The CO Action
process item is within the process component.

Developing for webMethods OneData Version 9.7 56


M
Odd Header
Working In Process Flow Designer

Property Description

Name General tab. Name of the CO action item. The name must be
unique; the name can contain spaces or blanks, but cannot
contain special characters.

Conceptual Required. General tab. The conceptual object name on which to


Object execute the action.

Comments General tab. Comments or description to be aached to the


process item. Informational purposes only.

Aribute Mapping tab. List of all the objects constituting the conceptual
object selected.

Components Mapping tab. Component(s) to which these objects need to be


mapped.

Item Mapping tab. Items present in the selected component(s) to


which these objects need to be mapped.

Mapping Process Item Properties


Mapping process items map aributes from multiple items for an action on an object.
This process item is within the process component.

Property Description

Name General tab. Name of the mapping item. The name must be
unique; the name can contain spaces or blanks, but cannot
contain special characters.

Data Object General tab. Data object from which the aributes are inherited.
Required aribute.

Comments General tab. Comments or description to be aached to the


process item. Informational purposes only.

Aribute Mapping tab. Aributes of the selected data object. Populated


when the data object is selected.

Components Mapping tab. Component to which Mapping Item aributes


need to be mapped.

Developing for webMethods OneData Version 9.7 57


M
Even Header
Working In Process Flow Designer

Property Description

Item Mapping tab. Items present in the selected component to which


Mapping Item aributes need to be mapped.

Values Mapping tab. Aributes present in the selected item to which


Mapping Item aributes need to be mapped.

Auto Populate Mapping tab. Once the component and item are selected, Auto
Populate completes where the aribute item selected on the rst
row matches the data object aribute.

CustomData Process Item Properties


CustomData process items provide users with an option to execute a custom SQL query
for retrieving data. This process item is within the process component.

Note: Process Flow Designer does not validate Java code dened in the SQL query when
saving or updating the process ow. These validations are performed during the run-
time of process ow hooks.

Property Description

Name General tab. Name of the custom data item. The name must
be unique; the name can contain spaces or blanks, but cannot
contain special characters.

Custom Data General tab. Select Display Grid to display the resulting query. To
Type use the resulting query as an input for subsequent steps, select
Custom Dataset.

Selection Type General tab. User selection option for the records displayed.
Single: Provides radio buon.
Multi: Provides check boxes for multiple rows selection.
This is only valid if Custom Data Type is Display Grid.

Comments General tab. Comments or description to be aached to the


process item. Informational purposes only. Optional.

SQL SQL tab. SQL query for fetching the data from the table. The
aributes in the SQL must be mapped to an alias that is dened
in the Attribute tab. For example, Select name as NAME from
city.

Developing for webMethods OneData Version 9.7 58


M
Odd Header
Working In Process Flow Designer

Property Description

In this SQL, you can also refer to dynamic values


acquired in previous process components.
The syntax is the same, for example, xyz =
{ProcessComponentNameProcessItemNameAttribueName}

Aribute Attribute tab. Aributes that store the result of the SQL query that
is passed to subsequent steps.

Delete Attribute tab. To delete an aribute, if required. Click Add Attribute


to add the aribute to delete.

CustomJava Process Item Properties


The CustomJava process item provides user an option to execute custom Java code as
part of the process ow.
Process Flow Designer does not validate Java code when saving or updating the process
ow. These validations are performed during the run-time of process ow hooks.

Property Description

Name General tab. Name of the custom java item. The name must be
unique; the name can contain spaces or blanks, but cannot contain
special characters.

Type General tab. Select Execution if there is no branching involved after


the Java source code is executed. Select Decision if the process ow
has to be branched after the code is executed.

Comments General tab. Comments or description to be aached to the process


item. Informational purposes only. Optional.

Java Source Java Source Code tab. Custom Java Code to be executed. For
Code examples of Java code, see "Process Flow Java Code Samples" on
page 73.

Aribute Mapping tab. Aributes used in the Java source code for inpuing
and outpuing data. For examples of Java code, see "Process Flow
Java Code Samples" on page 73.

Components Mapping tab. Components to which the custom Java item aributes
are mapped.

Developing for webMethods OneData Version 9.7 59


M
Even Header
Working In Process Flow Designer

Property Description

Item Mapping tab. Items present in the selected Component to which


custom Java item aributes are mapped.

Values Mapping tab. Aributes present in the selected item to which


custom Java item aributes are mapped.

Looping Process Items


Looping process items are process ow actions that interact with a process component
in the ow or execute a rule. Looping process items can only be added to a looping
model component. You can dene the properties for the looping process item by double
clicking the object. There are two kinds of looping process items:
Splitter. Process item indicating the start of the loop.
Aggregator. Process item indicating the end of the loop. Each splier should have one
aggregator.

Splitter Looping Process Item Properties


The following table lists the properties of splier process items.

Property Description

Name Name of the splier item. The name must be unique; the
name can contain spaces or blanks, but cannot contain special
characters.

Process Process component on which iteration needs to be based.


Component

Data Source Form or DataGrid where rows exist for the iteration.
Item

Comments Comments or description to be aached to the process item.


Informational purposes only.

Aggregator Looping Process Item Properties


The following table lists the properties of aggregator process items.

Developing for webMethods OneData Version 9.7 60


M
Odd Header
Working In Process Flow Designer

Property Description

Name Name of the aggregator item. The name must be unique; the name
can contain spaces or blanks, but cannot contain special characters.

Aggregate Indicates the output of the Loop. Select:


Rule None, if no output is required.
Consolidate, if output must be a consolidated record set.
This is relevant only if Action is part of the internal loop logic. Each
data manipulation action can be executed one by one or bundled
together and executed in bulk. You must set the Aggregate Rule to
Consolidate if laer scenario is preferred.

Comments Comments or description to be aached to the process item.


Informational purposes only.

Component Connectors
In a process ow, model components are linked with connectors. The connectors
determine the order of execution. If the execution paths depend on user interaction or
custom code, you must name the connectors to specify the order of execution during
run-time. You must enable connectors to populate subsequent components.
In addition to linking the components, connectors are also used for branching. The
process items, Decision and Custom Java, create multiple ow paths in the process. In
Decision process items, the link name must match exactly the values specied in the
property Decision Values . In Custom Java process items, the variable specied in the
Source Code must match exactly the Connector Name .

Compilation and Errors in Process Flow


Process Flow Designer checks the validity and completeness of the process ow
while saving or updating the diagram. If there are any validation errors, Process Flow
Designer displays the exception message. Components with validation errors have a red
title bar. Process items with validation errors are marked with a red error icon. To view
the error details, double click the process item or model component with the error, and
click the Error Messages tab.

Note: Process ow changes cannot be saved until you resolve all the errors.

Developing for webMethods OneData Version 9.7 61


M
Even Header
Working In Process Flow Designer

Process Flow Designer does not validate Java code dened in CustomCode or the SQL
query when CustomDataGrid item while saving or updating the process ow. These
validations are performed during the run-time of process ow hooks.

Validation Rules for Components and Items


Model components and process items in the process ow must adhere to certain rules
to avoid errors during processing. This section describes the rules that govern objects in
process ows.
Model components must adhere to the following rules:
The rst component in every process ow must be a Start component. It cannot have
an inbound connector. A process ow can have only one Start component.
You must congure each component in the process ow diagram.
Model components must have at least one inbound and one outbound connector.
Model components can have more than one outbound connector only if it contains
a Decision process item or a CustomJava process item with a property Type of
Decision.
Each process ow must have a Stop component. Stop components cannot have any
outbound connectors.
Process items must adhere to the following rules:
You must congure each process item in the process ow.
All mandatory properties of the process item must be dened.
Each Splier must have corresponding aggregator and vice versa.
For Mapping and Action process items, the Data Source dened must be from the
inbound execution ow path.

Developing for webMethods OneData Version 9.7 62


M
Odd Header
Working In Process Flow Designer

For process items with mapping, the Aributes dened in the Mapping tab must be
from the inbound execution ow path. The Aributes dened must be from the
conceptual object or data object selected.

Building a Process Flow


In Process Flow Designer, you can create a process ow diagram only within the hook
denition. For more information about the Process Flow Designer, see "Process Flow
Designer" on page 50.

To build a process flow


1. On the Menu toolbar, select Define > Configuration > Hooks.
2. Click Add Hook.
3. Select the Hook Type as Process Flow.
4. Click the Add process flow icon .
5. In the Process Flow Designer, add model components and process items to build your process
flow by dragging them onto the canvas. For information about model components, see
"Model Components" on page 51. For information on process items, see "Process
Items" on page 52.
6. Use connectors to link the components as follows:
a. Click the Enable Connector icon from the top of Designer. Hold the focus of the mouse
over the first of the two components to be connected. The pointer of the mouse changes
to a hand.
b. Click the mouse on the first component and drag the mouse to the second component and
release it. The two components are now connected.

Tip: To delete the connector, click the connector. When the connector turns blue,
press the DELETE key.

c. Double click the connector to define a name.

Important: A name is required when the connector is used for branching with
Decision process items and CustomJava process items.

7. After you create the diagram, click the Save icon on top right of Designer.
8. To edit another process flow, in the Process Flow Diagram drop-down, select the diagram and
click the Load Graph refresh button.

Important: If you switch to another process ow diagram without saving the current
diagram, you will lose the unsaved data.

Developing for webMethods OneData Version 9.7 63


M
Even Header
Working In Process Flow Designer

Process Flow Example Scenarios


This section provides sample process ow diagrams.

Scenario 1: Bulk Associate


Select a set of customers and associate to a reporting group. Optionally, create the
reporting group in the same ow.

The following diagram is an example of a process ow for this scenario.

The following diagram displays the property denitions for each of the process items in
the process ow.

Developing for webMethods OneData Version 9.7 64


M
Odd Header
Working In Process Flow Designer

Process Flow Diagram

Developing for webMethods OneData Version 9.7 65


M
Even Header
Working In Process Flow Designer

Notes on Scenario 1
D: Custom Java Code. In the Java code, we are trying to make sure which route the user
chose. If the user decides to create a new Reporting Group, then we need to use the
sequence generated. If the user decided to associate to an existing Reporting Group,
then we need to use the selected Group ID.
F: Mapping. CUST_ID and CUST_RPT_GRP_ID are the 2 key elds that need to be
lled in. CUST_ID is from the selected rows and CUST_RPT_GRP_ID is based on the
newly created group or selected group.
Internal Primary Key (CUST_RPT_GRP_REL_ID) of the combination object is a
sequence and a constant of -1 needs to be passed as part of the action.
CUST_RPT_GRP_REL_NM is a required aribute (informational only) and is
mapped to comply with the constraints.

Scenario 2: Create customer


Create a new customer and contract; option to create a parent HQ in the same process.

Developing for webMethods OneData Version 9.7 66


M
Odd Header
Working In Process Flow Designer

Developing for webMethods OneData Version 9.7 67


M
Even Header
Working In Process Flow Designer

Developing for webMethods OneData Version 9.7 68


M
Odd Header
Working In Process Flow Designer

Developing for webMethods OneData Version 9.7 69


M
Even Header
Working In Process Flow Designer

Developing for webMethods OneData Version 9.7 70


M
Odd Header
Working In Process Flow Designer

Developing for webMethods OneData Version 9.7 71


M
Even Header
Working In Process Flow Designer

Scenario 3: System Specific Override


Customer aributes can be overridden at individual system level. Prompt user for
system and show the appropriate override form. Save the results.

Scenario 4: Expire Customer


Expire selected customer and associated addresses and roles (all objects being temporal).

Developing for webMethods OneData Version 9.7 72


M
Odd Header
Working In Process Flow Designer

Process Flow Java Code Samples


All variables and data values are of type string.

Checking for null string/if statement


if (StringUtils.isEmpty(CreatID))
ResultID=AssocID;
else
ResultID=CreatID;

Assignment
ResultId=AssocID;

String comparison
if ( str1.equalsIgnoreCase(str2))
Test1=1;

Date Comparison
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Date;
import javax.swing.text.DateFormatter;
SimpleDateFormat dateFormatter = new SimpleDateFormat(dateFormat);
Date date1 = dateFormatter.parse(str1);
Date date2 = dateFormatter.parse(str2);
same = (date1.compareTo(date2) == 0);

Number Comparison
int integer1 = Integer.parseInt(str1);
int integer2 = Integer.parseInt(str2);
same = integer1 == integer2;
}catch(Exception e){
same = str1.equalsIgnoreCase(str2);
}
return same;

Developing for webMethods OneData Version 9.7 73


M
Even Header

Developing for webMethods OneData Version 9.7 74


M
Odd Header
API Functions and Web Services in OneData

4 API Functions and Web Services in OneData


API Functions Overview ............................................................................................................... 76
Generic API Functions ................................................................................................................. 76
Data Deployment Functions ......................................................................................................... 80
Generic Job Functions ................................................................................................................. 84
Read-Write Web Services ............................................................................................................ 88
Enabling Service Layer Security in OneData .............................................................................. 95
Retrieving Password for Service Layer Security ......................................................................... 96
Enabling and Disabling Web Services in OneData ..................................................................... 96

Developing for webMethods OneData Version 9.7 75


M
Even Header
API Functions and Web Services in OneData

API Functions Overview


You can use the API (Application Programming Interface) functions in OneData to
execute dened jobs in OneData through the network, without logging into the OneData
application. For example, a client may utilize a web service to execute an incremental
deployment job over the network. OneData uses the SSL authentication as dened in the
user proles to pass the functions through the application servers in the network.

Generic API Functions


The following sections describe the generic API functions provided by OneData.

getStructure
This function returns structure information about the entity or table whose name is
provided. The function accepts input as XML and returns XML string as output.
The structure of the input XML is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<ONEDATA_REQUEST>
<REPOSITORYID></REPOSITORYID>
<ENTITYNAME></ENTITYNAME>
<TABLENAME></TABLENAME>
<CLIENTID></CLIENTID>
<PROJECTID> </PROJECTID>
<SCHEMAID> </SCHEMAID>
<USERID></USERID>
<PASSWORD></PASSWORD>
</ONEDATA_REQUEST>

Input XML Tags

REPOSITORYID Optional. ID of the repository in which the entity or table resides.


If you do not provide the ID, the ID of the rst repository from
the list of available repositories is used by default. This tag is case
sensitive.

ENTITYNAME Optional. Logical name of the object in OneData. (Required if


TABLENAME is not provided).

TABLENAME Optional. Physical table name in the database. (Required if


ENTITYNAME is not provided).

Developing for webMethods OneData Version 9.7 76


M
Odd Header
API Functions and Web Services in OneData

CLIENTID Optional. Client ID if more than one client is dened in the


metadata.

PROJECTID Optional. Project ID if more than one project is dened for the
client in the metadata.

SCHEMAID Optional. Determines whether the data is retrieved from the


work area or the release area where there is a dual schema
landscape.

USERID Optional. ID and service layer security password of the user


PASSWORD calling this web service. Required if service layer security is
enabled.
For more information about the service layer security password,
see "Retrieving Password for Service Layer Security" on page
96.

getData
The structure of the input XML is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<ONEDATA_REQUEST>
<REPOSITORYID></REPOSITORYID>
<CLIENTID></ CLIENTID>
<PROJECTID></ PROJECTID>
<SCHEMAID></SCHEMAID>
<USERID></USERID>
<PASSWORD></PASSWORD>
<SELECTALLCOLUMNS></SELECTALLCOLUMNS>
<SELECTCOLUMNLIST>
<COLUMN>
<NAME></NAME>
</COLUMN>
</SELECTCOLUMNLIST>
<FILTERLIST>
<CONDITION>
<NAME></NAME>
<VALUE></VALUE>
<OPERATOR></OPERATOR>
</CONDITION>
</FILTERLIST>
</ONEDATA_REQUEST>

Input XML Parameters

REPOSITORYID Optional. ID of the repository in which the entity or the


table resides. If you do not provide the ID, the ID of the

Developing for webMethods OneData Version 9.7 77


M
Even Header
API Functions and Web Services in OneData

rst repository from the list of available repositories is


used by default. This parameter is case sensitive.

ENTITYNAME Optional. Logical name of the object in OneData.


(Required if TABLENAME is not provided.)

TABLENAME Optional. Physical table name in the database. (Required if


ENTITYNAME is not provided.)

CLIENTID Optional. Client ID if more than one client is dened in


the metadata.

PROJECTID Optional. Project ID if more than one project is dened for


the client in the metadata.

SCHEMAID Optional. Whether the data is retrieved from the work


area or the release area where there is a dual schema
landscape.

USERID Optional. ID/ service layer security password of the user


calling this web service. Required if service layer security
PASSWORD
is enabled.

SELECTALLCOLUMNS Optional. Whether to include all the columns in the


output. Seing the value to:
true. Includes all columns.
false. Includes only those columns specied inside
COLUMN tag.

SELECTCOLUMNLIST Optional. Columns to list in the output when


SELECTALLCOLUMNS is set to false. Output includes
COLUMN
only those columns specied in the COLUMN tag. Each
NAME COLUMN tag must have one NAME tag indicating the
name of the column.

FILTERLIST Optional. FILTERLIST narrows the output based on the


CONDITION. Each CONDITION must contain NAME
CONDITION
(Column Name), VALUE (Column Value), OPERATOR
NAME (IN, NOT IN, <, >, <=, >=, =). Multiple CONDITION tags
will result in ANDing between them. If IN or NOT IN is
VALUE used as OPERATOR, there can be multiple VALUE tags
OPERATOR within CONDITION tag, each one containing one value to
be used in the IN or NOT IN clause.

Developing for webMethods OneData Version 9.7 78


M
Odd Header
API Functions and Web Services in OneData

isValidCode
This function returns boolean True/False if the row in the search criteria exists.
<?xml version="1.0" encoding="UTF-8"?>
<ONEDATA_REQUEST>
<REPOSITORYID></REPOSITORYID>
<CLIENTID></ CLIENTID>
<PROJECTID></ PROJECTID>
<SCHEMAID></SCHEMAID>
<USERID></USERID>
<PASSWORD></PASSWORD>
<ENTITYNAME></ENTITYNAME>
<TABLENAME></TABLENAME>
<COLUMN>
<NAME></NAME>
<VALUE></VALUE>
</COLUMN>
</ONEDATA_REQUEST>

Input XML Parameters

REPOSITORYID Optional. ID of the repository in which the entity or


table resides. If you do not provide the ID, the ID of the
rst repository from the list of available repositories is
used by default. This parameter is case sensitive.

ENTITYNAME Optional. Logical name of the object in OneData.


(Required if TABLENAME is not provided.)

TABLENAME Optional. Physical table name of the object. (Required if


ENTITYNAME is not provided.)

CLIENTID Optional. Client ID if more than one client is dened in


the metadata.

PROJECTID Optional. Project ID if more than one project is dened


for the client in the metadata.

SCHEMAID Optional. Whether the data is retrieved from the work


area or the release area where there is a dual schema
landscape.

USERID Optional. ID/service layer security password of the user


PASSWORD calling this web service. To be provided if service layer
security is enabled.

Developing for webMethods OneData Version 9.7 79


M
Even Header
API Functions and Web Services in OneData

COLUMN NAME VALUE The COLUMN tag must contain the NAME (name
of the column) and VALUE (value of the column)
tags. Required. NAME tag is optional if the column is
primary key column.

Data Deployment Functions


OneData provides you the following functions for export jobs:

executeSynchronousDeploymentJob
This function performs the synchronous execution of a dened job and returns the job
log as an XML le. The script les are sent as aachments.

Input Parameters

Repository Optional. If you do not provide this parameter, the rst


repository from the list of available repositories is used.

User Id Optional. To be provided if service layer security is


Password enabled.

Schema Id Required. ID of the required schema. Set to:


1 for Work Area
2 for Release Area

Project Id Required. ID of the required project.

Job Name Required. Name of the job to be executed.

Incremental From Date Optional. Specify the from/to date.


Incremental
To Date

Output Parameters
None.

Sample Input
RepositoryId = CAPITOL
UserId = admin
Password = 73ACD9A5972130B75066C82595A1FAE3
Schema Id = 2

Developing for webMethods OneData Version 9.7 80


M
Odd Header
API Functions and Web Services in OneData

Project Id = 1
JobName = TestSyncDeployJob

Sample Output
<?xml version="1.0" encoding="UTF-8"?>
<DATAEXCHANGE_JOB_OUTPUT>
<DATAEXCHANGE_JOB>
<REPOSITORY>CAPITOL</REPOSITORY>
<ONEDATA_VERSION>4.3.1</ONEDATA_VERSION>
<JOB_RUN_IDENTIFIER>855</JOB_RUN_IDENTIFIER>
<ID>4516</ID>
<NAME>TestSyncDeployJob</NAME>
<EXECUTIONDATE>2007-09-12 12:47:48.0</EXECUTIONDATE>
<DURATION>1</DURATION>
<RESULT>Completed Successfully</RESULT>
<RESULT_MESSAGE>All the job steps in the job completed successfully.
</RESULT_MESSAGE>
<DATAEXCHANGE_JOBSTEP>
<ID>4523</ID>
<NAME>TestSyncDeployJobStep</NAME>
<RESULT_MESSAGE>The job step TestSyncDeployJobStep completed
successfully. 1207 records were written successfully to the file.
</RESULT_MESSAGE>
<SUCCESSFUL_RECORDCOUNT>0</SUCCESSFUL_RECORDCOUNT>
<FAILURE_RECORDCOUNT>0</FAILURE_RECORDCOUNT>
</DATAEXCHANGE_JOBSTEP>
</DATAEXCHANGE_JOB>
</DATAEXCHANGE_JOB_OUTPUT>

executeAsynchronousDeploymentJob
This web service performs asynchronous job execution so that users do not need to wait
for the job to complete execution. Function returns a job token, which is used as the
handle for geing the result for the job executed.

Input Parameters

Repository Optional. Defaults to the rst repository from the list of


available repositories if not provided.

User Id Optional. To be provided if service layer security is


Password enabled.

Schema Id Required. ID of the required schema. Set to:


1 for Work Area
2 for Release Area

Project Id Required. ID of the required project.

Job Name Required. Name of the job to be executed.

Developing for webMethods OneData Version 9.7 81


M
Even Header
API Functions and Web Services in OneData

Incremental From Date Optional. Specify the from/to date.


Incremental
To Date

Sample Input
RepositoryId = CAPITOL
UserId = admin
Password = 73ACD9A5972130B75066C82595A1FAE3
Schema Id = 2
Project Id = 1
JobName = TestAsyncDeployJob

Sample Output
861

getResultForDeploymentJob
This web service returns the job log of asynchronous jobs. We provide the job token
returned during the execution of the executeAsynchronousDeploymentJob service
to retrieve the job log. The job log is returned as an XML le. The scripts are sent as an
aachment.

Input Parameters

Repository Optional. Defaults to the rst repository from the list of


available repositories if not provided.

User Id Optional. To be provided if service layer security is


Password enabled.

Schema Id Required. ID of the required schema. Set to:


1 for Work Area
2 for Release Area

Project Id Required. ID of the required project.

Job Token Required. Job token returned by the


executeAsynchronousDeploymentJob service.

Output Parameters
None.

Developing for webMethods OneData Version 9.7 82


M
Odd Header
API Functions and Web Services in OneData

Sample Input
RepositoryId = CAPITOL
UserId = adminPassword = 73ACD9A5972130B75066C82595A1FAE3Schema Id = 2Project
Id = 1JobToken = 861

Sample Output
<?xml version="1.0" encoding="UTF-8"?>
<DATAEXCHANG E_JOB_OUTPUT>
<DATAEXCHANGE_JOB>
<REPOSITORY>CAPITOL</REPOSITORY>
<ONEDATA_VERSION>4.3.1</ONEDATA_VERSION>
<JOB_RUN_IDENTIFIER>861</JOB _RUN_IDENTIFIER>
<ID>4520</ID>
<NAME>TestAsyncD eployJob</NAME>
<EXECUTIONDATE> 2007-09-12 13:0 5:36.0</EXECUTIONDATE>
<DURATION>1</DURATION>
<RESULT>Completed Successfully</RESULT>
<RESULT_MESSAGE>All the job steps in the job completed
successfully.</RESULT_MESSAGE>
<DATAEXCHANGE_JOBSTEP>
<ID>4524</ID>
<NAME>TestAsyncDeployJobStep</NAME>
<RESULT_MESSAGE>The job step TestAsyncDeployJobStep completed
successfully. 1207 records were written successfully to the file.
</RESULT_MESSAGE>
<SUCCESSFUL_RECORDCOUNT>0</SUCCESSFUL_RECORDCOUNT>
<FAILURE_RECORDCOUNT>0</FAILURE_RECORDCOUNT>
</DATAEXCHANGE_JOBSTEP>
</DATAEXCHANGE_JOB>
</DATAEXCHANGE_JOB_OUTPUT>

terminateDeploymentJob
This web service terminates any active job executed using the asynchronous deployment
job. The job token returned during the execution of the asynchronous deployment job is
passed to terminate the job execution.

Input Parameters

Repository Optional. Defaults to the rst repository from the list of available
repositories if not provided.

User Id Optional. To be provided if service layer security is enabled.


Password

Schema Id Required. ID of the required schema. Set to:


1 for Work Area
2 for Release Area

Developing for webMethods OneData Version 9.7 83


M
Even Header
API Functions and Web Services in OneData

Project Id Required. ID of the required project.

Job Token Required. Specify the job token returned during the execution of
the executeAsynchronousDeploymentJob service.

Output Parameters
None.

Generic Job Functions


Function Description

executeSynchronousJob This web service does the synchronous execution of a


dened job.

executeAsynchronousJob This web service performs the asynchronous job


execution.

getJobExecutionResult This web service returns the job log of asynchronous


jobs.

terminateJob This web service terminates any active job executed


using the asynchronous job

executeSynchronousJob
This web service does the synchronous execution of a dened job. The execution is
synchronous because the service waits for the job to complete before it obtains the job
output. Function returns job output as an XML le that contains the log of the job that
executed. The script les are sent as aachments. The type of job is given as an input
parameter to this web service.

Input Parameters

Repository Required. Repository name.

User Id Required. User name/ password.


Password

Schema Id Required. ID of the required schema. Set to:

Developing for webMethods OneData Version 9.7 84


M
Odd Header
API Functions and Web Services in OneData

1 for Work Area


2 for Release Area

Project Id Required. ID of the required project.

Job Name Required. Name of the job to be executed.

Job Type Required. Type of job to be executed.

Incremental From Optional. From/to dates.


Date
Incremental To Date

Note: Generic job functions support Global Reports Job only that is, Job Type=43.

Output Parameters
None.

Sample Input
RepositoryId = DEV
UserId = admin
Password = 73ACD9A5972130B75066C82595A1FAE3
SchemaId = 1
ProjectId = 1
JobName = TestSyncDeployJob
JobType = 43

Sample Output
<?xml version="1.0" encoding="UTF-8" ?>
H-H <JOB_OUTPUT>
H-H <JOB>
<REPOSITORY>DEV</REPOSITORY>
<ONEDATA_VERSION>5.7rc1</ONEDATA_VERSION>
<JOB_RUN_IDENTIFIER>426156</JOB_RUN_IDENTIFIER>
<ID>95951</ID>
<NAME>Brand Report-Grouping</NAME>
<EXECUTIONDATE>1970-01-01 05:30:00.0</EXECUTIONDATE>
<DURATION>5</DURATION>
<RESULT>12 rows were retrieved for the report.</RESULT>
<RESULT_MESSAGE>The job executed successfully and the report has been
emailed to the following address(es): adminj@abc.com</RESULT_MESSAGE>
</JOB>
</JOB_OUTPUT>

executeAsynchronousJob
This web service performs the asynchronous job execution. The execution is
asynchronous because the service does not wait for the job to complete before it obtains

Developing for webMethods OneData Version 9.7 85


M
Even Header
API Functions and Web Services in OneData

the job output. The service returns a job token, which is used as the handle for geing
the result for the job that executed.

Input Parameters

Repository Required. Repository name.

User Id Required. User name/ password.


Password

Schema Id Required. ID of the required schema. Set to:


1 for Work Area
2 for Release Area

Project Id Required. ID of the required project.

Job Name Required. Name of the job to be executed.

Job Type Required. Type of job to be executed.

Incremental From Date Optional. From and to dates.


Incremental
To Date

Output Parameters
None.

Sample Input
RepositoryId = DEV
UserId = jjoseph
Password = 73ACD9A5972130B75066C82595A1FAE3
SchemaId = 1
ProjectId = 1
JobName = TestSyncDeployJob
JobType = 43

Sample Output
632

getJobExecutionResult
This web service returns the job log of asynchronous jobs. The job token is returned
during the execution of executeAsynchronousJob to retrieve the job log. Function
returns job log as an XML le. The scripts are sent as an aachment.

Developing for webMethods OneData Version 9.7 86


M
Odd Header
API Functions and Web Services in OneData

Input Parameters

Repository Required. Repository name.

User Id Required. User name/ password.


Password

Schema Id Required. ID of the required schema. Set to:


1 for Work Area
2 for Release Area

Project Id Required. ID of the required project.

Job Type Required. Type of job to be executed.

Job Token Required. Job token returned during the execution of


executeAsynchronousJob.

Output Parameters
None.

Sample Input
RepositoryId = DEV
UserId = admin
Password = 73ACD9A5972130B75066C82595A1FAE3
SchemaId=1
ProjectId=1
JobToken = 632

Sample Output
<?xml version="1.0" encoding="UTF-8" ?>
H-H
<JOB_OUTPUT>H-H
<JOB>
<REPOSITORY>DEV</REPOSITORY>
<ONEDATA_VERSION>5.7rc1</ONEDATA_VERSION><
JOB_RUN_IDENTIFIER>426156</JOB_RUN_IDENTIFIER>
<ID>95951</ID>
<NAME>Brand Report- Grouping</NAME>
<EXECUTIONDATE>1970-01-01 05:30:00.0</EXECUTIONDATE>
<DURATION>5</DURATION>
<RESULT>12 rows were retrieved for the report.</RESULT>
<RESULT_MESSAGE>The job executed successfully and the report has been
emailed to the following address(es): admin@abc.com</RESULT_MESSAGE>
</JOB>
</JOB_OUTPUT>

Developing for webMethods OneData Version 9.7 87


M
Even Header
API Functions and Web Services in OneData

terminateJob
This web service terminates any active job executed using the asynchronous job. The job
token returned during the execution of the asynchronous job is passed to terminate the
job execution.
In the event that the status of the Job is Dened, Scheduled, Completed Successfully,
Active, Completed with Errors, Pending, or Pending Termination, the output is shown
as - Job status is <STATUS>. Hence termination request cannot be submied.

Input Parameters

Repository Required. Repository name.

User Id Required. User name/ password.


Password

Schema Id Required. ID of the required schema. Set to:


1 for Work Area
2 for Release Area

Project Id Required. ID of the required project.

Job Type Required. Type of job to be executed.

Job Token Required. Specify the job token returned during the execution
of executeAsynchronousJob.

Output Parameters
None.

Read-Write Web Services


Use the read-write web services to perform operations on OneData entities from outside
OneData without any additional conguration or set up. These operations are sequential
and must be performed in the following order:
INSERT
UPDATE
DELETE
RESTORE
PURGE

Developing for webMethods OneData Version 9.7 88


M
Odd Header
API Functions and Web Services in OneData

SELECT
You can dene single or multiple operations, and you can use these services to perform
DML operations on single or multiple datasets.

Tip: You can use the SELECT operation to retrieve a maximum of 1000 rows of data. You
must use getData to fetch above 1000 rows of data. For more details about getData, see
"getData" on page 77.

Note: The web service supports operations without lter conditions only on objects that
have 1000 rows of data. If you want to specify lter, the number of rows that satisfy the
lter must ideally be less than 1000. However, the exact number of rows that the web
service supports will depend on the heap size of the server JVM.

Input XML Specification


The table below shows the reference input XML specication for writing the input XML.

Mandatory Tags
A mandatory eld indicates that the tag must exist in the correct order in the tag
hierarchy within the input XML. Failing to specify this tag may result in the service
failing. A mandatory tag may be skipped if the parent tag is optional and is omied. For
example, in the structure where the GET_STRUCTURE element is optional and the child
tag, NAME, is mandatory, if GET_STRUCTURE is omied, NAME can also be omied
because it is only required if the parent GET_STRUCTURE tag exists.
The following table shows the input tag specications for the OD_REQUEST parameter,
which is mandatory.

Input Tags
The order of the input tags is as follows:
<OD_REQUEST>
<USER_ID>
<PASSWORD>
<REPOSITORY_ID>
<GET_STRUCTURE>
<NAME>
<INSERT>
<OBJECT>
<NAME>
<ROWS>
<ROW>
<COLUMN>
<NAME>
<VALUE>
<UPDATE>
<OBJECT>
<NAME>
<ROWS>
<ROW>

Developing for webMethods OneData Version 9.7 89


M
Even Header
API Functions and Web Services in OneData

<COLUMN>
<NAME>
<VALUE>
<FILTER_LIST>
<ROW>
<CONDITION>
<NAME>
<VALUE>
<DELETE or RESTORE or PURGE>
<OBJECT>
<NAME>
<FILTER_LIST>
<ROW>
<CONDITION>
<NAME>
<VALUE>
<SELECT>
<OBJECT>
<NAME>
<ROW_START_COUNT>
<ROW_MAX_COUNT>
<FILTER_LIST>
<ROW>
<CONDITION>
<NAME>
<VALUE>

Parameter Description

OD_REQUEST Root tag.

USER_ID User ID and hashed password used for login.


PASSWORD

REPOSITORY_ID Repository in which the object resides.

GET_STRUCTURE Structure of the entities dened in the NAME sub tag. If


valid object names are not specied in the NAME tags,
no structure will be returned. You can specify multiple
NAME tags in this tag. Optional.
Includes the following sub-element.
NAME. Name of the object. Mandatory.

INSERT Action wrapper tag to perform single or multiple row


inserts. Optional. If this parameter is provided, all sub-
elements are mandatory. You can specify the following
sub-elements:
OBJECT. Object action wrapper. Mandatory.
NAME. Name of the object. Mandatory.

Developing for webMethods OneData Version 9.7 90


M
Odd Header
API Functions and Web Services in OneData

Parameter Description

ROWS. Wrapper for ROW. Can include multiple ROW


tags. Mandatory.
ROW. Row of data in an object. You can dene
multiple columns. Mandatory.
COLUMN. Represents a column of a row in an
object. Mandatory.
NAME. Column name. Mandatory.
VALUE. Column value. For the date column type,
use the format MM-DD-YYYY (for example,
12-31-2009). For the timestamp column type,
use the format MM-DD-YYYY HH:MM:SS (for
example, 12-31-2009 02:12:23). Formats follow the
Java date format conventions. Mandatory.

UPDATE Action wrapper tag to perform single or multiple column


updates. Mandatory.
OBJECT. Object action wrapper. Mandatory.
NAME. Name of the object. Mandatory.
ROWS: Wrapper for ROW. Only a single ROW tag is
allowed inside. Mandatory.
ROW. Row of data in an object. You can dene
multiple columns. Mandatory.
COLUMN. Represents a column of a row in an
object. Mandatory.
NAME. Column name. Mandatory.
VALUE. Column value. For the date column type,
use the format MM-DD-YYYY (for example,
12-31-2009). For the timestamp column type,
use the format MM-DD-YYYY HH:MM:SS (for
example, 12-31-2009 02:12:23). Formats follow the
Java date format conventions. Mandatory.
FILTER LIST. Wrapper tag for lter condition. Optional.
ROW. Only one nested CONDITION tag is currently
permied. Mandatory.
CONDITION. AND is the default operator between
conditions. The default operator between the
lter values is EQUALS. Only one element
allowed. Mandatory.

Developing for webMethods OneData Version 9.7 91


M
Even Header
API Functions and Web Services in OneData

Parameter Description

NAME. Column name. Mandatory.


VALUE. Column value. For the date column type,
use the format MM-DD-YYYY (for example,
12-31-2009). For the timestamp column type,
use the format MM-DD-YYYY HH:MM:SS (for
example, 12-31-2009 02:12:23). Formats follow the
Java date format conventions. Mandatory.

DELETE Single or multiple row delete, restore, or purge based on


RESTORE the lter condition or all rows. Optional.
PURGE
Note: All these operations use the same sub tag structure,
but they should be specied separately.

OBJECT. Object action wrapper. Mandatory.


NAME. Name of the object. Mandatory.
FILTER LIST. Wrapper tag for lter condition. Optional.
ROW. Row of data in an object. Only one
CONDITION tag is allowed. Mandatory.
CONDITION. AND is the default operator between
conditions. The default operator between the
lter values is EQUALS. Only one element
allowed. Mandatory.
NAME. Column name. Mandatory
VALUE. Column value. For the date column type,
use the format MM-DD-YYYY (for example,
12-31-2009). For the timestamp column type,
use the format MM-DD-YYYY HH:MM:SS (for
example, 12-31-2009 02:12:23). Formats follow the
Java date format conventions. Mandatory.

SELECT Single or multiple row select based on the lter condition


or all rows. Optional.
OBJECT. Object action wrapper. Mandatory.
NAME. Name of the object. Mandatory.
ROW_START_COUNT. The counter start value, for example,
if set to 101, rows starting from the 101st row to the next
'n' rows are returned as part of the result, where 'n' is
the maximum number of rows that can be returned,

Developing for webMethods OneData Version 9.7 92


M
Odd Header
API Functions and Web Services in OneData

Parameter Description
dened by the ROW_MAX_COUNT tag. Default value is
1. Accepts values > 0. Optional.
ROW_MAX_COUNT. Maximum number of rows to return
for this object. The valid value range is 1-1000. The
default upper limit value is 1000. Optional.
FILTER LIST. Wrapper tag for lter condition. Optional.
ROW. Row of data in an object. Only one
CONDITION tag is allowed. Mandatory.
CONDITION. AND is the default operator between
conditions. The default operator between the
lter values is 'EQUALS. Only one element
allowed. Mandatory.
NAME. Column name. Mandatory.
VALUE. Column value. For the date column type,
use the format MM-DD-YYYY (for example,
12-31-2009). For the timestamp column type,
use the format MM-DD-YYYY HH:MM:SS (for
example, 12-31-2009 02:12:23). Formats follow the
Java date format conventions. Mandatory.

Output XML Specification


The reference output XML structure specication for reading the output from the web
service response is listed below.
<OD_RESPONSE>
<GET_STRUCTURE>
<OBJECT>
<NAME>
<COLUMNS>
<COLUMN>
<NAME>
<TYPE>
<IS_PK>
<EDITABLE>
<READABLE>
<INSERT or UPDATE or DELETE or RESTORE or PURGE>
<OBJECT>
<NAME>
<ROWCOUNT>
<MESSAGE>
<SELECT>
<OBJECT>
<NAME>
<ROWCOUNT>
<MESSAGE>
<DATA>
<ROW>
<COLUMN>

Developing for webMethods OneData Version 9.7 93


M
Even Header
API Functions and Web Services in OneData

<NAME>
<VALUE>

In the table below, optional indicates that the tag may or may not be present in the
response XML. The presence of optional tags is controlled by the input XML request. If
the parent of a mandatory tag is present, the mandatory tag is included in the response
message. For example, if the INSERT tag was not specied in the input XML, no insert
operations occurred and the response XML does not contain INSERT or any of its child
element tags.

Parameter Description

OD_RESPONSE Root tag.

GET_STRUCTURE Wrapper for the object. Optional. Includes the following


child elements.
OBJECT. Object wrapper.
NAME. Name of the object. Mandatory.
COLUMNS. Wrapper for COLUMN. Mandatory.
COLUMN. Represents a column in the object.
Mandatory.
NAME. Name of the column. Mandatory.
TYPE. Data type of the column. Valid values
are BOOLEAN, CHAR, DATE, FILETYPE,
NUMERIC, PERCENTAGE, STRING, and
TIMESTAMP. Mandatory.
IS_PK. Whether the column is part of a primary
key constraint. Can be TRUE or FALSE.
Mandatory.
EDITABLE. Whether the column is editable. Can be
TRUE or FALSE.
READABLE. Whether the column is readable. Can
be TRUE or FALSE.

INSERT If multiple actions are performed, multiple actions tags are


DELETE generated. Each tag can have multiple OBJECT elements.
RESTORE
OBJECT. Object action wrapper. Mandatory.
PURGE
NAME. Name of the object. Mandatory.
ROWCOUNT. Number of rows inserted, updated, deleted,
restored, or purged. Mandatory.
MESSAGE. Success message. Optional.

Developing for webMethods OneData Version 9.7 94


M
Odd Header
API Functions and Web Services in OneData

Parameter Description

SELECT Single or multiple row select based on the lter condition


or all rows. Optional.
OBJECT Object action wrapper. Mandatory.
NAME. Name of the object. Mandatory.
ROWCOUNT. Number of rows selected. Mandatory.
MESSAGE. Success message. Optional.
DATA. Wrapper tag for lter condition. Optional.
The DATA element requires the following tags:
ROW. Row of data in an object. Only one CONDITION
tag is allowed. Mandatory.
COLUMN. Column corresponding to the row.
NAME. Column name. Mandatory.
VALUE. Column value. For the date column type,
use the format MM-DD-YYYY (for example,
12-31-2009). For the timestamp column type,
use the format MM-DD-YYYY HH:MM:SS (for
example, 12-31-2009 02:12:23). Formats follow the
Java date format conventions. Mandatory.

Types of Web Services


Two types of Read Write web services are currently available with OneData:
SOAP web services. For more details, see "SOAP Web Services" on page 100.
REST web services. For more details, see "REST Web Services" on page 103.

Enabling Service Layer Security in OneData


By default, OneData adds and enables service layer security. This security layer allows
you to safely enable web services in OneData. Before you use the API functionality, you
must congure the authentication in OneData for the external service layer.

To configure service layer security in OneData


1. On the menu tool bar, select Administer > System > System Properties.
By default, OneData takes you to the System Property tab.
2. In the System Property tab, locate the Authentication header.
3. Under Authentication, in the drop down for Service layer security, select Enable.

Developing for webMethods OneData Version 9.7 95


M
Even Header
API Functions and Web Services in OneData

4. Scroll down to the bottom of the page and click Save.

Tip: Click Save & Return to save the seings and return to the home page of OneData.

Retrieving Password for Service Layer Security


OneData generates a hashed password for the service layer security.

Important: If external security is enabled (Active Directory, LDAP, etc.), use the clear text
password that is passed to the external authentication provider.

To retrieve password for service layer security


1. On the Menu toolbar, click Personalize > User Profile.
2. Obtain the password given in Password for service layer security.

Enabling and Disabling Web Services in OneData


You can enable web services in OneData by adding a servlet-to-servlet mapping
declaration.

To enable or disable a web service in OneData


1. Stop OneData using any of the methods provided by your application server.

Note: Depending on your application server, you can perform a change in web.xml
le located in the exploded directory where the application was deployed or inside
onedata.war le. You must check the required parameters and redeploy onedata.war
le if you use the laer approach.

To enable web services, add the following declarations from the OneData
deployment descriptor le web.xml servlet section.
<servlet>
<servlet-name>AdminServlet</servlet-name>
<display-name>Axis Admin Servlet</display-name>
<servlet-class>org.apache.axis.transport.http.AdminServlet</servlet-
class>
</servlet>
<servlet>
<servlet-name>AxisServlet</servlet-name>
<display-name>Apache-Axis Servlet</display-name>
<servlet-class>org.apache.axis.transport.http.AxisServlet</servlet-
class>
</servlet>

Servlet mapping section:


<servlet-mapping>
<servlet-name>AdminServlet</servlet-name>
<url-pattern>/AdminServlet</url-pattern>

Developing for webMethods OneData Version 9.7 96


M
Odd Header
API Functions and Web Services in OneData

</servlet-mapping>
<servlet-mapping>
<servlet-name>AxisServlet</servlet-name>
<url-pattern>/AxisServlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>AxisServlet</servlet-name>
<url-pattern>/services/*</url-pattern>
</servlet-mapping>

To disable web services, remove servlet/servlet mapping declarations .


2. Start OneData using any of the methods provided by your Java application server.

Developing for webMethods OneData Version 9.7 97


M
Even Header

Developing for webMethods OneData Version 9.7 98


M
Odd Header
SOAP Web Services

5 SOAP Web Services


SOAP Web Services .................................................................................................................. 100
Using the OneData SOAP Web Services Feature .................................................................... 100

Developing for webMethods OneData Version 9.7 99


M
Even Header
SOAP Web Services

SOAP Web Services


SOAP is an XML-based protocol that enables applications to exchange information over
HTTP. That is, it is a protocol for accessing a web service. You can use OneData to access
specic data through SOAP web services.

Using the OneData SOAP Web Services Feature


You can use the SOAP web service to retrieve data from OneData objects by sending an
input XML request through the soapUI. Before you can send the input request, you must
dene the URL of the OneData WSDL in soapUI.
The lter criteria that you specify in the input XML request is case sensitive.

To use soap services


1. Install soapUI from the following link: hp://sourceforge.net/projects/soapui/les/
soapui/3.0.1
2. Start the soapUI.
3. Click File Name > New Soap Project.
4. In Project Name, enter the project.
5. In Initial WSDL, enter the URL of the WSDL as, http://<host>:<port>/onedata/
services/onedata?wsdl

6. Click OK.
7. Drill down to onedataSoapBinding under the created project and right click getData.
8. Select New Request.
9. Open the drop down on the top of the request window and select edit current.
10. Change the text field to http://<host>:<port>/onedata/services/onedata and
click OK.
11. Paste the following XML snippet into the left side of the request window.
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:oned="http://localhost:8080/demo/services/onedata">
<soapenv:Header/>
<soapenv:Body>
<oned:getData
soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<asInputXML xsi:type="xsd:string">
<![CDATA[
<ONEDATA_REQUEST>
<GENERATE_DATA_IN_FILE>no</GENERATE_DATA_IN_FILE>
<REPOSITORYID>repository ID</REPOSITORYID>

Developing for webMethods OneData Version 9.7 100


M
Odd Header
SOAP Web Services

<USERID>user ID</USERID>
<PASSWORD>Password for service layer security</PASSWORD>
<ENTITYNAME>data object name</ENTITYNAME>
<SELECTALLCOLUMNS>yes</SELECTALLCOLUMNS>
<ONEDATA REQUEST>]]>
</asInputXML>
</oned:getData>
</soapenv:Body>
</soapenv:Envelope>

12. Click Submit request to specified endpoint URL (green play button) in the toolbar of the
request window.
The response appears in the right pane. The data is either inline or stored in the
aachment part of web-service response.
13. To retrieve the data from the attachment, click Attachments in the bottom of the window.
Double-click the attachment to open it.

Developing for webMethods OneData Version 9.7 101


M
Even Header

Developing for webMethods OneData Version 9.7 102


M
Odd Header
REST Web Services

6 REST Web Services


REST Web Services in OneData ............................................................................................... 104
GET and POST Services ........................................................................................................... 104
The Acquisition Layer and REST Services ................................................................................ 108
The Exception Queue and REST Services ............................................................................... 110
Obtaining the REST URL of a OneData Object ........................................................................ 110
Using Filters in REST Services ................................................................................................. 110
Using JSON Strings in REST Services ..................................................................................... 115
Using REST Web Service URL ................................................................................................. 126
REST XSDs ............................................................................................................................... 127
XSD Samples by Object Type ................................................................................................... 129
REST URL Parameters .............................................................................................................. 133
Using REST Web Service URL ................................................................................................. 141
REST XSDs ............................................................................................................................... 142
XSD Samples by Object Type ................................................................................................... 144

Developing for webMethods OneData Version 9.7 103


M
Even Header
REST Web Services

REST Web Services in OneData


Representational State Transfer (REST) is an architectural style for interaction over the
Internet, built on top of the HTTP protocol. OneData REST web services provide an
easier means for third party applications to access data hosted in OneData.
Traditional web services use SOAP as the standard for serving XML data in an SOA
environment, which is often regarded to be highly complex and rigid. REST, while using
the same underlying HTTP protocol, oers a simpler request response model with easier
integration options. Currently OneData supports two REST services: GET and POST.
The RESTful web service in OneData supports all CRUD (create, read, update and
delete) actions for data objects and conceptual objects. Through the REST web service
URL, you can perform all operations (insert, update, delete, restore, and purge) on an
object. The REST web service is linked through the acquisition layer for all operations
other than data retrieval. For this reason, existing functionalities of the acquisition
layer, such as Decode, Exception Queue support, and enhanced performance are part of
RESTful web services, as well.
OneData supports data retrieval for remote objects through the RESTful web service.

Note: There may be a delay the rst time an object is accessed through a REST service.
Subsequent calls to the same object are usually faster.

You can use Apache HpClient to consume the service. You can also use web browsers
to access the server directly. If you want to dene a lter condition in the request, it must
be URL encoded to enable the use of special characters in data values or object aributes.

GET and POST Services


The following table shows the HTTP methods and their supported operations in
OneData.

Method Supported Operation

GET Data Retrieval. By default, GET retrieves data from the Release
area. To retrieve data from the Work area, use the request
parameter schema_id . For information about schema_id , see
"Using Filters in REST Services" on page 110.

POST Data modication such as INSERT, UPDATE, DELETE


(including RESTORE and PURGE).

PUT Not Supported.

Developing for webMethods OneData Version 9.7 104


M
Odd Header
REST Web Services

Method Supported Operation

DELETE Not Supported.

OneData recommends enabling SSL, but it is not mandatory. The services use the BASIC
authentication scheme, which accepts a OneData username and a hashed user password
for authentication. There is no change in the authentication mechanism used for the
dierent method type. To determine authentication and authorization for an anonymous
user, OneData uses the privileges dened in the system properties le.
To use the anonymous user account, type anonymous as the username login (no
password is required). To determine authentication and authorization for an anonymous
user, OneData uses the privileges dened in the system properties.

Note: REST web services do not support multi select and BLOB columns. The REST web
service supports the CLOB column in the POST web service but not in the GET service.

GET Service Response Data


The REST web service returns data in XML format. The service transforms data, as
needed, so that it adheres to the XML structure, including making the following
transformations:
Escapes all special characters in the response data.
Replaces spaces in object names and column captions with an underscore (_)
character.
The GET REST service returns the XML Element Name property instead of the column
name when the XML element name is dened in the column denition or foreign key
constraint denition.
You can control whether OneData wraps rows in a <datarow> tag in the response XML,
using the request parameter, baseVersion . Set baseVersion to true to generate XML output
without datarows. By default, baseVersion is set to false, which returns the response
data wrapped within datarows. Refer to the following XML examples of XML records
wrapped within datarows.
The following code sample provides an example of XML output from the EMPLOYEE
data object with datarows. In this example, EMPLOYEE is the physical object name,
The remaining aributes use the XML element name. Each record is wrapped within a
datarow tag.
<?xml version="1.0"?>
<EMPLOYEE>
<datarow>
<EMPLOYEE_ID>2012</EMPLOYEE_ID>
<EMPLOYEE_NAME>John Doe</EMPLOYEE_NAME>
<EMPLOYEE_DOB>1984-12-31 00:00:00.000000000</EMPLOYEE_DOB>
<EMPLOYEE_ADDRESS>H12,Brian Ave,California</EMPLOYEE_ADDRESS>
</datarow>
</EMPLOYEE>

Developing for webMethods OneData Version 9.7 105


M
Even Header
REST Web Services

In the next XML output sample, STATE-CITY is a conceptual object. The State and City
records are wrapped within datarows.
<?xml version="1.0"?>
<STATE>
<datarow>
<ID>6</ID>
<NAME>New Jersey</NAME>
<CITY>
<datarow>
<ID>245</ID>
<NAME>Hackensack</NAME>
<POPULATION>50667</POPULATION>
</datarow>
<datarow>
<ID>453</ID>
<NAME>Cedar Falls</NAME>
<POPULATION>27083</POPULATION>
</datarow>
</CITY>
</datarow>
</STATE>

Retrieving Columns from a Foreign Key Relationship


When you are working with related tables, you can retrieve the related columns in the
XML. The State object contains a foreign key relationship to the Country object through
the CNTRY_ID (where CNTRY_ID is the primary key, ID, in the Country object). In the
Country object, the NAME column is the description corresponding to the ID. The XML
element name for the NAME column in the Country object is COUNTRY_NAME. The
following table summarizes this information.

Object Name Column Name XML Element Name for the Column

State ID STATE_ID

NAME STATE_ID

CNTRY_ID COUNTRY_ID

Country ID (Primary Key) COUNTRY_ID

NAME COUNTRY_NAME

You can also dene an XML element name in the foreign key constraint. Therefore the
XML element name for the foreign key constraint to the NAME column in the Country
object could be Country_XML_Name.

Developing for webMethods OneData Version 9.7 106


M
Odd Header
REST Web Services

Retrieving the State Object Using a RESTful Service


The following output is returned when a REST service retrieves the State object. Note
that the XML element name used for the NAME column of the Country object is the
XML element name dened in the foreign key constraint.
<?xml version="1.0" encoding="utf-8" ?>
<State>
<datarow>
<STATE_ID>3001</STATE_ID>
<STATE_NAME>State1</STATE_NAME>
<COUNTRY_XML_NAME>Country1</COUNTRY_XML_NAME>
</datarow>
<datarow>
<STATE_ID>5001</STATE_ID>
<STATE_NAME>State2</STATE_NAME>
<COUNTRY_XML_NAME>Country2</COUNTRY_XML_NAME>
</datarow>
</State>

In the next example of the REST service output, the related description column is the ID
column in the Country object. In this case, the XML element name is the one dened for
the ID in the Country object (Country.ID), not the XML element name of the foreign key
constraint.
<?xml version="1.0" encoding="utf-8" ?>
<State>
<datarow>
<STATE_ID>3001</STATE_ID>
<STATE_NAME>State1</STATE_NAME>
<COUNTRY_ID>Country1</COUNTRY_ID>
</datarow>
<datarow>
<STATE_ID>5001</STATE_ID>
<STATE_NAME>State2</STATE_NAME>
<COUNTRY_ID>Country2</COUNTRY_ID>
</datarow>
</State>

POST Service Response Data


REST services return data in XML format. The following tables lists the tags in the
response output.

Tag Description

IDENTIFIER Unique number to retrieve values from the exception queue.


The identier tag is not included if the POST request was
executed with explicit interchange mapping. To retrieve
values from the exception queue, you must use an interchange
mapping.

MESSAGE Short description of the process execution result.

Developing for webMethods OneData Version 9.7 107


M
Even Header
REST Web Services

Tag Description

DETAILS Minimal detailed information about exceptions. Includes elapsed


time.

DATA Data values from the object that is represented by the XML
element name. This tag is shown only when the returnColumns
request parameter is specied.

STATUS Process execution status: Success or Failure.

Successful Operation Response


The following XML output sample is of a successful response from the POST operation.
<?xml version="1.0" encoding="UTF-8" ?>
<OUTPUT>
<IDENTIFIER>447426</IDENTIFIER>
<RESULT>
<MESSAGE>Process finished successfully. </MESSAGE>
<STATUS>Success</STATUS>
<DETAILS>
<![CDATA[ Total records inserted/updated: 10The process finished
successfully.Elapsed time: 1 s ]]>
</DETAILS>
</RESULT>
</OUTPUT>

Error Response
The following XML output sample is of a failed response from the POST operation.
<?xml version="1.0" encoding="UTF-8" ?>
<OUTPUT>
<IDENTIFIER>447421</IDENTIFIER>
<RESULT>
<MESSAGE>Process finished with errors. Please use the identifier to
retrieve values from exception queue.</MESSAGE>
<STATUS>Failure</STATUS>
<DETAILS><![CDATA[ ORA 12899: value too large for column
"DEV_STG"."AKJ_TEST_IMPORT_1"."COLUMN2" (actual: 22, maximum: 10)
There were errors during the import process. As partial commit was
enabled for whole process, all successful transactions have been
commited.All extracted entries that failed are posted into the
exception queue.]]>
</DETAILS>
</RESULT>
</OUTPUT>

The Acquisition Layer and REST Services


All the data manipulation operations (insert, update, delete, restore, and purge) are
connected to the acquisition layer when the RESTful web service in OneData is invoked.

Developing for webMethods OneData Version 9.7 108


M
Odd Header
REST Web Services

To invoke a DML operation on a data object, OneData provides the following explicit
and implicit interchange mapping options:
Implicit interchange mapping. This is the easiest option to perform DML operations in a
data object. To use implicit interchange mapping, do the following:
Create an XML le in accordance with the XML schema (XSD) shown at the
data object level. You can obtain this data from the External Services pane in the
Advanced Definition tab). The system internally creates an interchange mapping
and performs the DML action.
Use the same request URL as for retrieving data. You can obtain the URL from
the External Services pane in the Advanced Definition tab.
Create a simple HTTP POST request or multipart POST request with the XML
le created and the required request parameters as query string for the request.
For information about the request parameters, see "Obtaining the XSD from
OneData " on page 127.

Note: Only the XML les with an XSD-compliant structure are accepted. For
conceptual objects, ensure that the XML element tag name is unique for all
constituent objects.

Explicit interchange mapping. Even though most of the simple DML operations for an
object can be handled through implicit interchange mapping, you can create more
advanced interchange mapping and execute an existing interchange mapping for a
data object by using RESTful services, as follows:
Create an interchange mapping (or use an existing one) of any valid type
(delimited le, remote database, or XML/XSD).
Obtain the URL from the source information from the Interchange Mapping
Denition screen. Use the following format: hp://localhost:8080/onedata/rest/
QA/StandardProject/IM/Employee Interchange.
If the interchange mapping is:
Delimited or XML/XSD. Create a simple HTTP POST request/multi-part
POST request with the delimited/XML data le and the required request
parameters as a query string for the request. For information about the
request parameters for each request type, see "REST URL Parameters" on
page 118.
Remote database type. Use a simple POST request with the required parameters
as the query string to invoke the remote database interchange mapping.
There is no need to provide a data le along with the request.

Note: While creating the simple POST request, the data le content must be added to
the HTTP request body.

Developing for webMethods OneData Version 9.7 109


M
Even Header
REST Web Services

The Exception Queue and REST Services


RESTful web services are routed through the data acquisition framework. Therefore,
the exception queue is available to all of the DML operations performed using REST
services. To enable the exception queue, set the request parameter partialCommit=true
(the default seing). Once the queue is enabled, as records are extracted from the source,
any exceptions that occur are sent to the exception queue.
There are dierent methods for retrieving records from the exception queue depending
on whether the REST call was made using an implicit or explicit interchange mapping:
Implicit interchange mapping. The output XML from the response contains an identier
tag. This tag has a unique token for the RESTful session that was executed. Use the
token to retrieve exception queue records after you select RESTful Web Service for the
exception queue type.
Explicit interchange mapping. Use one of the interchange mappings to retrieve data
from the exception queue just as you would after selecting the exception queue type
as Interchange.

Obtaining the REST URL of a OneData Object


You can obtain the REST URL of an object from the OneData user interface. Alternately,
you can build the URL as described in "Using Filters in REST Services" on page 110.

To obtain the REST URL of an object


1. On the Menu toolbar, select Manage > Manage Data.
2. Select the object for which you want to obtain the REST URL.
3. In the Data Manager screen, click View > Definition.

Note: If the object uses Default mode, click the Advanced Definition tab.

4. Click the + symbol beside External Services to view the details.


The RESTful Web Service Link provides the REST URL for this object.

Note: The RESTful web service link also displays in the Interchange Mapping screen. On
the Menu toolbar, click Data Interchange > Configuration > Interchange Mapping.

Using Filters in REST Services


OneData provides multiple ways in which you can limit the data that is returned to the
user by ltering on specic columns and records.

Developing for webMethods OneData Version 9.7 110


M
Odd Header
REST Web Services

Use a RESTful web service URL. A RESTful web service link URL is encoded to avoid
issues when the object name or interchange mapping name contains special
characters that might break the HTTP request. Specify the lter conditions directly in
the REST URL. This method can be used for simple conditions, to specify the object
name and retrieve a specic record. You can also specify additional parameters, such
as the batch size and sort order of columns.
JSON string. Specify a lter in the body of the REST request. The request type should
be HTTP POST. With a JSON string, you can create complex queries with multiple
operators and value lters. You cannot add REST parameters in the body of the
service. These must be specied in the REST URL.
The following table compares the operations available in the two types of lter.

Operation Available in REST Available in JSON


URL String

and or or operator Yes Yes

Combined and and or lter No Yes

IN conditions No Yes

IS_NULL, IS_NOT_NULL, EQUAL, Yes Yes


LIKE

Parameters such as those listed in Yes No


"REST URL Parameters" on page
133.

REST Object URL Syntax


The REST URL syntax is as follows and is described in the table that follows.
hp://[hostname] :[port] /[contextRoot] /
rest/[repositoryId] /[projectName] /[type] /[objectName] ?[request_parameter]=[value]

Parameter Description

[hostname] : Name of server on which OneData is deployed.

[port] / Port on which OneData is deployed (optional based on


deployment).

[contextRoot] Context name of OneData in the application server.

Developing for webMethods OneData Version 9.7 111


M
Even Header
REST Web Services

Parameter Description

/rest/ Name of the service provider bean as congured in web.xml.


(This is a constant value.)

[repositoryId] Repository ID.

[projectName] Name of the project.

[type] [type] Type of object. The value is case sensitive.


CO. Conceptual object.
DO. Data object.
RO. Remote object.
IM. Interchange mapping.

[objectName] Name of the data object, conceptual object, remote object, or


interchange mapping.

Note: The RESTful web service URL does not support slashes (/ \)
in an object name. If these characters are part of an object name,
you will not be able to retrieve the object through an HTTP request
to the OneData server.

[parameter] Use parameters to customize the request URL for REST.


The format for the request parameter in a request URL. For
information about the REST parameters, see "REST URL
Parameters" on page 118.

Object REST URL Examples


The following are examples of REST URLs:
Data Object. Where the object name is Employee.
hp:// localhost:8080/onedata/rest/QA/StandardProject/DO/Employee
Conceptual Object. The object name is Employee CO.
hp://localhost:8080/onedata/rest/QA/StandardProject/CO/Employee CO
Remote Object. The object name is CountryID RO
hp://localhost:8080/onedata/rest/QA/StandardProject/RO/CountryID RO
Interchange Mapping. The interchange mapping name is Employee Interchange.
hp://localhost:8080/onedata/rest/QA/StandardProject/IM/Employee Interchange

Developing for webMethods OneData Version 9.7 112


M
Odd Header
REST Web Services

You can customize the REST URL with a lter and additional parameters. For more
information, see "Using Filters in REST Services" on page 110. For information about
the REST parameters, see "REST URL Parameters" on page 118.

Using Filter Operators in a REST URL


You can retrieve specic records by adding a lter to the basic REST URL, as described
in "Using Filter Operators in a REST URL" on page 113. To add a lter, append the
lter parameter to the REST URL, as ?filter.

And and Or Operators


OneData supports either and or or operators in the REST URL. To use a combined and
and or condition, you must use a JSON string. For more information about JSON strings,
see "Using JSON Strings in REST Services" on page 115.
and. The and operator returns results that satisfy all lter conditions, as in
COL1=value1 and COL2=value2. For example, the syntax for a URL would be:

http://localhost:8080/onedata/rest/QA/Standard%20Project/DO/
REST_FILTER_OBJECT?filter=ID=3 and COL1=2.

or. The or operator returns results satisfying one of the lter conditions, as in
COL1=value1 or COL2=value2. For example, the syntax for a URL would be:

http://localhost:8080/onedata/rest/QA/Standard%20Project/DO/
REST_FILTER_OBJECT?filter=ID=3 or COL1=2.

Comparison Operators
OneData supports the comparison operators IS_NULL, IS_NOT_NULL, EQUAL, and
LIKE in REST URLs. To use the IN comparison, you must use a JSON string.
You can compare values within columns.
IS_NULL. Returns results where the value the column is null, as
COL1&nullOperator=IS_NULL. The syntax would be:

http://localhost:8080/onedata/rest/QA/Standard%20Project/DO/
REST_FILTER_OBJECT?filter=ID or COL1&nullOperator=IS_NULL.

IS_NOT_NULL. Returns results where the value the column is not null, as
COL1&nullOperator=IS_NOT_NULL. The syntax would be:

COL1 and COL2&nullOperator=IS_NOT_NULL

COL1 or COL2&nullOperator=IS_NOT_NULL

Record Values and Data Type Syntax


The following table describes the syntax to use for record values based on the data type
of the column.

Developing for webMethods OneData Version 9.7 113


M
Even Header
REST Web Services

Data Type of Syntax


Column

Numeric Specify the value as is, without quotes. EMPLOYEE_ID=120. Where


Brand_ID is 1, the URL would be:
http://localhost:8080/onedata/rest/QA/StandardProject/DO/Brand
?filter=Brand_Id=1

String Wrap the value in double quotes. EMPLOYEE_NAME=John Doe


Where Brand_ID is 1 and Brand_Type is Electronics, the URL would
be:
http://localhost:8080/onedata/rest/QA/StandardProject/DO/Brand
?filter=Brand_Id=1 and Brand_Type="Electronics"

Date Wrap in double quotes, in the format YYYY-MM-DD. Treated as a


string. EMPLOYEE_DOB=1984-12-31

Timestamp Wrap the value in double quotes, in the format YYYY-


MM-DD HH:MM:SS.sssssssss. Treated as a string.
You must specify at least one digit in the milliseconds
(sssssssss).EMPLOYEE_DOJ=2007-03-01 10:30:30.0.

Special Prex with backslash characters. The standard is as specied in


Characters hp://www.w3.org/Addressing/URL/uri-spec.html.
Address H-12, O'Brian Ave, California would be,
EMPLOYEE_ADDRESS=H-12, O'Brian Ave, California

Address Manor Gate California would be,


EMPLOYEE_ADDRESS=Manor \Gate\, California

Conceptual Object Filters


To lter child records in a conceptual object, the syntax is filter=<Parent Object
Name>.<Child Object Name>.<Field Name>=VALUE

For example, the Location conceptual object consists of Country (parent object), and State
and City as child objects. To retrieve the data from the conceptual object, Location, in
which Country_Name is Country1, the URL would be:
http://localhost:8080onedata/rest/QA/StandardProject/CO/Location
?filter=Country_Name="USA"

To retrieve the data from conceptual object Location in which State_Name is Colombo, the
URL would be:
http://localhost:8080/onedata/rest/QA/StandardProject/CO/Location
?filter=Country.State.State_Name="Colombo"

Developing for webMethods OneData Version 9.7 114


M
Odd Header
REST Web Services

Using JSON Strings in REST Services


JSON strings provide more exibility to create more complex lter conditions in REST
services. The JSON string is sent in the request body of the POST method, as the content
type, set as, Content-Type=application/x-www-form-urlencoded.
The JSON lter condition is specied as a name-value parameter, using the key word,
lter in the POST method body. The lter cannot be used in the header. If there is
no lter in the HTTP POST request, specify, filter=EMPTY_FILTER. Filters are case
sensitive.
The delimiter for IN clauses can be congured in the onedata.properties le in the
onedata.webservice.rest.inclause.delimiter=; parameter. The default delimiter
is a semicolon (;), for example, IN clause => (COL1, COL2) IN ((1,2) ; (3,4) ;
(5,6)). For more information about conguring OneData properties, see Administering
webMethods OneData.
You cannot use REST parameters in the request body. To add additional parameters
to the lter, you must specify them in the URL. For more information about REST
parameters, see "REST URL Parameters" on page 118.
The following section provides examples of JSON strings.

JSON Filter with and and or Operators


To create a lter that has both and and or operators and to create nested conditions, use
a JSON string as in the following example. To retrieve (ID=1 and NAME=AAA) OR
(ID=2 and NAME=BBB), use the string:

filter = { "criterion" : [ { "criterion" : [ { "name" : "ID",


"operator" : "= ",
"value" : "1"
},
{ "name" : "NAME"
"operator" : "= ",
"value" : "AAA"
}
],
"operator" : "and"
},
{ "criterion" : [ { "name" : "ID",
"operator" : "=",
"value" : "2"
},
{ "name" : "NAME",
"operator" : "=",
"value" : "BBB"
}
],
"operator" : "and"
}
],
"operator" : "OR"
}

Developing for webMethods OneData Version 9.7 115


M
Even Header
REST Web Services

Conceptual Object JSON String Example of an and Filter


The following JSON string is an example of a conceptual object with a simple and lter.
The lter is for the parent object, GEO_COUNTRY with child objects GEO_CITY and
GEO_STATE. The lter returns records where the city name is AAA and the state name
is BBB.
(
(
GEO_COUNTRY.GEO_STATE.GEO_CITY.GEO_CITY_NM=AAA
and
GEO_COUNTRY.GEO_STATE.GEO_STATE_NM=BBB
)
)
Corresponding JSON String:
{ "criterion" :
[
{
"criterion" :
[
{
"name" : "GEO_COUNTRY.GEO_STATE.GEO_CITY.GEO_CITY_NM",
"operator" : "=",
"value" : "AAA"
},
{
"name" : "GEO_COUNTRY.GEO_STATE.GEO_STATE_NM",
"operator" : "=",
"value" : "BBB"
}
],
"operator" : "and"
}
],
"operator" : ""
}

Data Object JSON String Example of an and Filter


The following JSON string is an example of a data object with an and lter. The lter is
for the data object, GEO_COUNTRY to return records where the ID equals 1 and the
country name is AAA.
(
( GEO_COUNTRY_ID=1 and GEO_COUNTRY_NM=AAA
)
)
Corresponding JSON string:
{
"criterion" :
[
{
"criterion" :
[
{
"name" : "GEO_COUNTRY_ID" ,
"operator" : "=" ,
"value" : "1 "
} ,
{
"name" : "GEO_COUNTRY_NM" ,

Developing for webMethods OneData Version 9.7 116


M
Odd Header
REST Web Services

"operator" : "=" ,
"value" : "AAA "
}
] ,
"operator" : "and "
}
] ,
"operator" : ""}

Data Object JSON String Example of an IN Clause in a Single Column with IS_Null AND LIKE
Conditions
The following JSON string is an example of a lter in a data object with an IN clause for
IS_NULL and LIKE conditions. The lter returns records in the GEO_COUNTRY object
where the ID is 1, 2, 3, or 4, and the description is null and the country name ends with
the leer a. In this example, the delimiter to separate column values in an IN clause is a
semicolon, and is the default delimiter.
( .
{ "criterion" :
[
{
"criterion" :
[
{
"name" : "GEO_COUNTRY_ID",
"operator" : "IN",
"value" : "(1; 2; 3; 4)"
},
{
"name" : "GEO_COUNTRY_DESC",
"operator" : "IS_NULL",
"value" : ""
},
{
"name" : "GEO_COUNTRY_NM",
"operator" : "=",
"value" : "$a"
}
],
"operator" : "and"
}
],
"operator" : ""}

Data Object JSON String Example of an IN Clause in Multiple Columns


The following JSON string is an example of a lter on a data object with an IN clause in
multiple columns. The lter returns records in the GEO_COUNTRY object where the
ID is 1, the country name is AAA, and the country description is AAA, or where the ID
is 2, the country name is BBB, and the country description is BBB. In this example, the
delimiter to separate column values in the IN clause is a semicolon, and is the default
delimiter.
{ "criterion" :
[
{
"criterion" :
[
{

Developing for webMethods OneData Version 9.7 117


M
Even Header
REST Web Services

"name" : "(GEO_COUNTRY_ID, GEO_COUNTRY_NM, GEO_COUNTRY_DESC )",


"operator" : "IN",
"value" : "((1, AAA, AAA ); (2 , BBB, BBB ))"
}
],
"operator" : ""
}
],
"operator" : ""
}

Data Object JSON String Example of a Nested Condition


The following JSON string is an example of a lter on a data object with a nested lter.
The lter returns records in the GEO_COUNTRY object where the country name starts
with the leer a (required) and either the country ID is the value 1 or 2 or the country
description is null. In this example, the delimiter to separate column values in the IN
clause is a semicolon, and is the default delimiter.
{"criterion" :
[
{
"criterion" :
[
{
"name" : "GEO_COUNTRY_NM",
"operator" : "LIKE",
"value" : "A$"
}
],
"complexCriterion" :
[
{
"criterion" :
[
{
"name" : "GEO_COUNTRY_ID",
"operator" : "IN",
"value" : "(1 ; 2)"
},
{
"name" : "GEO_COUNTRY_DESC",
"operator" : "IS_NULL",
"value" : ""
}
],
"operator" : "or"
}
],
"operator" : "and"
}
],
"operator" : ""
}

REST URL Parameters


You can use parameters to customize the request URL for REST. The format for the
request parameter in a request URL is:

Developing for webMethods OneData Version 9.7 118


M
Odd Header
REST Web Services

hp://[hostname] :[port] /[contextRoot] /


rest/[repositoryId] /[projectName] /[type] /[objectName] ?[request_parameter]=[value]
The following table lists the parameters you can use in the REST web service URL. All
request parameters are case sensitive. Parameters cannot be used in a JSON string. To
add a parameter to the lter, you must append it to the REST URL.

Parameter Summary Description and Example Syntax

alternateKey Alternate key to use when data is being modied.


alternateKey=COLUMN1,COLUMN2

baseVersion Indicates whether to retrieve data using the format in an


earlier version of OneData. baseVersion=true

batchSize The batch size of the number of records that are read or
cached in each call to the database. batchSize=25

dateFormat The date format to use when modifying data.

decode Indicates whether to use decode for reference columns.


decode=true

description Indicates whether to include the column description with the


generated XSD. description=true

enableDQMode Indicates whether to perform data quality checks during


REST update or insert actions on a consolidation object.
enableDQMode=true

filter For data retrieval only.

partialCommit Indicates whether to perform a partial commit of data


changes when an error is encountered. partialCommit=true

processingMode The action to perform. processingMode=update .

returnColumns Columns to include in the response output.


returnColumns=All .

schema_id Indicates whether to retrieve data from the Work area or the
Release area. schema_id=1

Developing for webMethods OneData Version 9.7 119


M
Even Header
REST Web Services

Parameter Summary Description and Example Syntax

skipEmptyColumns Indicates whether to skip empty and missing XML tags.


skipEmptyColumns=true

sortColumn&sortOrder Order in which to sort columns retrieved, as either ascending


or descending. SortColumn=ID&sortOrder=asc

wildCardOP The character to use as a wildcard operator. wildCardOP=$

alternateKey
Alternate key to use when data is being modied. This is required if the primary key
column value does not exist in the data le. For conceptual objects, if processingMode is
delete, purge, or restore, the alternate key is only required for the root object.
Valid values are any combination of entity object names and physical column names of
data objects which are unique and non-null. There is no default value. Use the format:
Data objects. alternateKey=COLUMN1,COLUMN2
Conceptual objects.alternateKey=co_obj1=COLUMN1; co_obj2=COLUMN2,COLUMN3 ,
where co_obj1 and co_obj2 are the constituent objects and COLUMN1, COL2, COL3
are the corresponding physical column names.
Conceptual
objects.alternateKey=entity_obj1=COLUMN1,COLUMN2;entity_obj2=COLUMN3 ,
where entity_obj1 and entity_obj2 are the object names of the constituent objects
of the conceptual object, and COLUMN1, COLUMN2, COLUMN3 are the
corresponding physical column names.

Note: For conceptual objects, you must encode special characters and spaces in alternate
keys to prevent breaking the URL. If no alternate key is provided, the system assigns the
primary columns of the data object as the alternate key.

baseVersion
Indicates whether to retrieve data using the format in an earlier version of OneData. This
value overrides the default value dened at the system level in the onedata.properties
le.
baseVersion=true . Retrieve data in the previous format.
baseVersion=false . Default. Retrieve data in XML format. The default
value is set at the system level in the onedata.properties le:
onedata.webservice.rest.baseVersion=false

Developing for webMethods OneData Version 9.7 120


M
Odd Header
REST Web Services

batchSize
The batch size of the number of records that are read or cached in each call to the
database. For example, if there are 1000 records available to retrieve and batchSize =100,
the server retrieves 100 records at a time, making 10 calls.

Tip: The batch size depends on the amount of memory available for processing on the
server. Since conceptual objects use more memory, so you should decrease batchSize
for conceptual objects and increase it for data objects. For large conceptual objects, try
conguring dierent values for batchSize to nd the size that oers the best response
time without generating an OutOfMemoryException error.

Use any positive integer value, for example, batchSize=25 . There is no default value.

dateFormat
The date format to use when modifying data. The default value is YYYY-MM-DD. Valid
values are any valid date format supported in OneData, for example, dateFormat=MM-
DD-YYYY.

decode
Indicates whether to use decode for reference columns. The tag name is the XML element
name at the column denition.
decode=true . Default.
decode=false . XML output displays the original value of the base column.

description
Indicates whether to include the column description with the generated XSD. Valid
values:
description=true Includes the description.
description=false . Default. Does not include the description.

enableDQMode
Indicates whether to perform data quality checks during REST update or insert actions
on a consolidation object. To dene an object as a consolidation object, in the object
denition, add Consolidation Object in Additional Qualifiers.
enableDQMode=true or not specied. Perform data quality checks during inserts or
updates.
enableDQMode=false . Skip data quality checks on objects.

Developing for webMethods OneData Version 9.7 121


M
Even Header
REST Web Services

filter
For data retrieval only. For lter options, see "Using Filters in REST Services" on page
110.
Valid values are any valid column in the specied object, for example,
lter=COLUMN1=21 . There is no default value.

partialCommit
Indicates whether to perform a partial commit of data changes when an error is
encountered. The following are valid values.
partialCommit=true . Default. Partial commit is allowed.
partialCommit=false . Partial commit is not allowed.

processingMode
The action to perform. The default value is update. For example, processingMode=update .

Object Type Action to perform

Conceptual objects Delete hierarchy, purge hierarchy, and restore hierarchy.

Self recursive (SR) Purge root nodes. Restoring root nodes must be done as a
data object action on each object. For more information, see
"Self Recursive Objects" on page 130.

Network recursive Restore/purge root nodes. This is a two step process:


(NR) Child nodes in one XML.
ONLY root nodes in second XML.

Data objects Insert, update, update only, delete, purge, restore.

Conceptual objects Update, delete, purge, restore.

returnColumns
Columns to include in the response output. The <DATA> tag in the response contains
the data values from the object. If returnColumns is not specied, no <DATA> tags are
included in the response. Audit columns, logical columns (multi-select), and CLOB
columns cannot be returned.

Note: Applies only for insert and update actions.

Developing for webMethods OneData Version 9.7 122


M
Odd Header
REST Web Services

The syntax is objectname=columnname for each object and column to retrieve. Separate
physical column names by commas. To return all columns specify All . There is no
default value for this parameter.
Data objects. returnColumns=COL1,COL2 . To return all columns, returnColumns=All .
Conceptual objects. For example, where objects are co_obj1 and
co_obj2, and columns are COL1, COL2, COL3: Return some columns:
returnColumns=co_obj1=COL1;co_obj2=COL2,COL3 . Return all columns,
returnColumns=co_obj1=All;co_obj2=All
decode does not apply to reference columns; therefore, the XML format is the same as
when decode=false .
For a data object, the number of data object tags in the <DATA> tag varies based on the
batch size. That is, if the batch size=100 (default value) and 200 records are inserted,
there are two <State> tags for a successful execution ow. If an error occurs, then each
record retriggered from the exception queue will be in a separate data object name tag.
The following is an example of the XML returned.
<?xml version="1.0" encoding="UTF-8" ?>
<OUTPUT>
<IDENTIFIER>447426</IDENTIFIER>
<RESULT>
<DATA>
<State>
<datarow>
<STATE_ID>3001</STATE_ID>
<STATE_NAME>State_Name_1</STATE_NAME>
</datarow>
<datarow>
<STATE_ID>5001</STATE_ID>
<STATE_NAME>State_Name_2</STATE_NAME>
</datarow>
</State>
</DATA>
<MESSAGE>Process finished successfully.</MESSAGE>
<STATUS>Success</STATUS>
<DETAILS>
<![CDATA[ Total records inserted/updated: 10 The process finished
successfully. Elapsed time: 1 s ]]>
</DETAILS>
</RESULT>
</OUTPUT>

For a conceptual object, the number of data object name tags varies for each constituent
object that is inserted or updated.
<?xml version="1.0" encoding="UTF-8" ?>
<OUTPUT>
<IDENTIFIER>447426</IDENTIFIER>
<RESULT>
<DATA>
<country>
<datarow>
<COUNTRY_ID >3001</COUNTRY_ID>
<COUNTRY_NAME>Country_Name_1</COUNTRY_NAME>
</datarow>
</country>

Developing for webMethods OneData Version 9.7 123


M
Even Header
REST Web Services

<state>
<datarow>
<STATE_ID>3001</STATE _ID>
<STATE_NAME>State_Name_1</STATE_NAME>
</datarow>
</state>
<city>
<datarow>
<CITY_ID>3001</CITY_ID>
<CITY_NAME>City_Name_1</CITY _NAME>
</datarow>
</city>
</DATA>
<MESSAGE>Process finished successfully. </MESSAGE>
<STATUS>Success</STATUS>
<DETAILS>
<![CDATA[ Total records inserted/updated: 10 The process finished
successfully. Elapsed time: 1 s ]]>
</DETAILS>
</RESULT>
</OUTPUT>

schema_id
Indicates whether to retrieve data from the Work area or the Release area. Valid values:
schema_id=1 . Retrieves data directly from the database (work area), even when in-
memory is enabled.
schema_id=2 . Default. Retrieves data from the Release area. Data is also retrieved
from the Release area when the parameter is not dened.

skipEmptyColumns
Indicates whether to skip empty and missing XML tags. To use with conceptual objects,
ensure that every level in the conceptual object has at least one record.
skipEmptyColumns=true . Default.
skipEmptyColumns=false . Includes all empty and missing tags in the input XML for
insert and update actions.
To skip empty columns (shipEmptyColumns=true ) in a conceptual object that has Country
> State > City, all constituent objects must have at least one record, as in the following
examples.
<Country>
<Country_Name>Country_Name_1</Country_Name>
<State>
<St_Name>State_Name_1</St_Name>
<City>
<City_Name>City_Name_a</City_Name>
</City>
</State>
</Country>
<Country>
<Country_Name>Country_Name_1</Country_Name>
<State>
<St_Name>State_Name_2</St_Name
<City>

Developing for webMethods OneData Version 9.7 124


M
Odd Header
REST Web Services

<City_Name>City_Name_b</City_Name>
</City>
</State>
</Country>

For a conceptual object that does not have a record in every level, set the value of
skipEmptyColumns as false.
<Country>
<Country_Name>Country_Name_1</Country_Name>
<State>
<St_Name>State_Name_1</St_Name>
<City>
<City_Name>City_Name_a</City_Name>
</City>
</State>
</Country>
<Country>
<Country_Name>Country_Name_1</Country_Name>
<State>
<St_Name>State_Name_2</St_Name
<City>
<!-- City record not present for the country -->
</City>
</State>
</Country>

sortColumn&sortOrder
Order in which to sort columns retrieved, as either ascending or descending. Sorting
is done per batch. Set batchSize greater than or equal to the number of records to be
retrieved. For conceptual objects, sorting can only be applied on the root level object.
Allowable Values:
sortColumn Column name.
sortOrder Valid values are asc or desc.
For example, sortColumn=ID&sortOrder=asc

wildCardOP
The character to use as a wildcard operator. This wildcard overrides the wildcard
specied at the system level. Ensure that the character is not used in the data column.
Allowable Values $`!;@^*( )< >':|~. For example, wildCardOP=$
Default Value $. Dened at the system level in the onedata.properties le,
onedata.webservice.rest.wildcard.op=$

Request Parameters by HTTP Methods


The following table describes the available HTTP methods and which create, read,
update, and delete (CRUD) actions can be performed for the parameter. O indicates that
the action is available, X indicates that it is not available.

Developing for webMethods OneData Version 9.7 125


M
Even Header
REST Web Services

Parameter name HTTP Method CRUD Actions

GET POST Create Retrieve Update Delete

alternateKey X O O X O X

baseVersion O X X O X X

batchSize O O O O O O

dateFormat O O O O O O

decode O O O O O O

description O X X O X X

enableDQMode X O O X O X

lter O X X O X X

partialCommit X O O X O O

processingMode X O O X O O

returnColumns X O O X O X

schema_id O X X O X X

skipEmptyColumns X O O X O O

sortColumn & sortOrder O X X O X X

Using REST Web Service URL


You can use the REST web service link to manage data in OneData objects. You
can access the data either as an anonymous user or as a OneData user. When REST
fetches the data from an object, it checks for the user privileges and displays the data
accordingly. OneData returns the records in XML format. For conceptual objects,
OneData returns the child records too.

Developing for webMethods OneData Version 9.7 126


M
Odd Header
REST Web Services

You can also lter the data returned by REST by providing appropriate lter conditions
in the request URL.

Accessing Data with the REST Service URL


If an anonymous user is set up in OneData, you can access the data through the REST
web service using the anonymous user ID and no password. When you access the data
as an anonymous user, you can perform only those actions that are allowed for that
anonymous user.
For more information about how to set up an anonymous user, see Administering
webMethods OneData.

To access data through the REST web service


1. In the browser, enter the RESTful web service link, for example, http:// localhost:8080/
onedata/rest/QA/StandardProject/DO/Employee.
2. To access the data, enter the user name and password:
As an anonymous user. Username as anonymous. Leave the password blank.
As a OneData user. Username as UserOne. The password is the encrypted
password.
All the records in the object are displayed in XML format.

REST XSDs
You can use a special request to retrieve the XML Schema (XSD) associated with a
particular data object, conceptual object, or interchange mapping. You can use this
functionality to retrieve the XSD through a RESTful call.
For information about how to obtain the XSD, see "REST XSDs" on page 127.

Obtaining the XSD from OneData


You can obtain an XSD in two ways:
Append /XSD or /XMLSchema to the RESTful URL for the object or interchange
mapping and execute the HTTP GET call.

Note: When the REST URL is invoked, the interchange mapping type must be set to
type XML or XSD. Specify this by appending /XSD or /XML to the end of the URL.

For example, to obtain the XSD from the REST URL http:// localhost:8080/
onedata/rest/QA/StandardProject/DO/Employee, append /XSD to the URL as
follows:
http://localhost:8080/onedata/rest/QA/StandardProject/DO/Employee/XSD

Developing for webMethods OneData Version 9.7 127


M
Even Header
REST Web Services

Generate the XSD directly from OneData as explained below.

To obtain and download XSD from OneData


1. On the Menu toolbar, click Manage > Manage Data.
2. Select the object of which you want to generate the XSD.
3. In the Data Manager screen, click View > Definition.

Note: If the object mode is Default, click the Advanced Definition tab.

4. Click the + symbol next to External Services to expand the tab.


5. Click Generate XSD to obtain the XSD.

Note: You can also download the XSD by clicking Download XSD.

Obtain the XSD and construct XML according to this XSD. Using the HTTP client, POST
the created XML through the RESTful web service link. For examples of constructing
XML using XSD, see "REST XSDs" on page 127.

Configuring OneData to Skip Empty Columns


You can congure OneData to skip empty columns and reset the value of
any other column as empty by using REST in the onedata.properties le. The
onedata.datainterchange.nullify.keyword property denes whether to nullify an
empty eld while constructing the XML. Use this property along with the parameter
skipEmptyColumns in the REST URL.

To skip empty columns and reset other columns


1. Go to <Installation_Directory>\SoftwareAG\profiles\ODE\bin\onedata\config directory and
open the onedata.properties file.
2. Set the property, onedata.datainterchange.nullify.keyword=NULLIFY_FIELD to
automatically skip empty columns and reset fields. Save and close the file.
For example, if onedata.datainterchange.nullify.keyword=NULLIFY_FIELD,
and you want to reset a column value while constructing XML, use NULLIFY_FIELD
as follows.
<ADDRESS>
<datarow>
<ID>12</ID>
<COL1>Book</COL1>
<COL2>NULLIFY_FIELD</COL2>
<COL3></COL3>
</datarow>
</ADDRESS>

3. In the REST web service link, use the parameter skipEmptyColumns=true .


4. Using the HTTP Client, POST the created XML through the RESTful web service link.

Developing for webMethods OneData Version 9.7 128


M
Odd Header
REST Web Services

XSD Samples by Object Type


This section provides examples of how to construct XML using the XSD in dierent
scenarios.
For information about obtaining an XSD, see "REST XSDs" on page 127.

Conceptual Objects
Conceptual Object Inserts and Updates
The following scenario shows XML that inserts data into the conceptual object
REST_BRAND using REST.
You do not need to provide data for the hierarchy relation in the REST_BRAND
object. REST automatically identies the hierarchy relationship. In the below
example, the hierarchy relation is shown as <!--<RelatedBrandType>Fridge</
RelatedBrandType>--> and <!--<RelatedBrand>Kelvinator</RelatedBrand>-->.
In an input XML to insert multiple records, if the data hierarchy is not complete for
all records, OneData recommends that you provide the foreign key value so that the
records connect correctly. For example, if in a three-level hierarchy each node has
dierent number of levels, you must provide the foreign key value for each level.
<?xml version='1.0' encoding='utf-8'?>
<REST_BRAND_TYPE>
<datarow>
<BrandTypeName>Fridge</BrandTypeName>
<BrandTypeCode>F0022</BrandTypeCode>
<REST_BRAND>
<datarow>
<BrandName>Kelvinator</BrandName>
<BrandCode>KVL2</BrandCode>
<!--<RelatedBrandType>Fridge</RelatedBrandType>-->
<REST_PRODUCT>
<datarow>
<ProductName>FreshMatic</ProductName>
<ProductCode>FRS</ProductCode>
<!--<RelatedBrand>Kelvinator</RelatedBrand>-->
</datarow>
</REST_PRODUCT>
</datarow>
</REST_BRAND>
</datarow>
</REST_BRAND_TYPE>

If the primary key values are sequences, include alternateKey in the RESTful web service
link as a request parameter.
alternateKey= REST_BRAND_TYPE= BRAND_TYPE_NAME;
REST_BRAND=REST_BRAND_NAME;
REST_PRODUCT=REST_PROD_NM

Developing for webMethods OneData Version 9.7 129


M
Even Header
REST Web Services

For more information about the request parameters, see "REST URL Parameters" on
page 118.

Conceptual Object Deletes, Restores, and Purges


The scenario explained here shows XML that deletes data from the conceptual object
REST_BRAND using REST.
Construct XML for the root node alone according to the XSD. Because the delete
operation will delete the hierarchy, you do not need to provide data for the complete
hierarchy. XML is required to contain the primary key information only.
<?xml version='1.0' encoding='utf-8'?>
<REST_BRAND_TYPE>
<datarow>
<BrandTypeName>Fridge</BrandTypeName>
</datarow>
</REST_BRAND_TYPE>

If the primary key values are sequences, include alternateKey in the RESTful web service
link as a request parameter.
alternateKey =REST_BRAND_TYPE=BRAND_TYPE_NAME;
Set the processingMode parameter in the RESTful web service URL as delete. You can
set this parameter as either purge or restore. For more information about the request
parameters, see "REST URL Parameters" on page 118.

Self Recursive Objects


Self Recursive Hierarchy Inserts and Updates
The scenario explained here shows XML that inserts data into the self recursive
conceptual object MANAGER using REST.
<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR>
<datarow>
<FirstName>Manager</FirstName>
<LastName>last name</LastName>
</datarow>
<datarow>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<RelatedManager>Manager</RelatedManager>
</datarow>
</EMPLOYEE_SR>

If the primary key values are sequences, include alternateKey in the RESTful web service
URL as a request parameter. For more information about the request parameters, see
"REST URL Parameters" on page 118.
alternateKey =EMPLOYEE_SR=FNM

Developing for webMethods OneData Version 9.7 130


M
Odd Header
REST Web Services

Self Recursive Hierarchy Deletes, Restores, and Purges


The scenario explained here shows XML to delete data from the self recursive
conceptual object MANAGER using REST.
Construct XML for the root node alone according to the XSD. Because the delete
operation will delete the hierarchy, you do not need to provide data for the complete
hierarchy.# XML is required to contain the primary key information only.
<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR>
<datarow>
<FirstName>Manager</FirstName>
</datarow>
<datarow>
<FirstName>John</FirstName>
</datarow>
</EMPLOYEE_SR>

If the primary key values are sequences, include alternateKey in the RESTful web service
link as a request parameter.
alternateKey = NR_EMPLOYEE = FNM;
Set the processingMode parameter in the RESTful web service URL as delete. This deletes
all records from the MANAGER conceptual object under the specied hierarchy. You
can pass this parameter as either purge or restore. For more information about the
request parameters, see "REST URL Parameters" on page 118.

Self Recursive Conceptual Object Restore Root Nodes


To purge the root nodes (nodes without any parent) in a self recursive object, you must
purge all the child nodes rst. This is a two-step process with child nodes in one XML
and only root nodes in the second XML.
Step 1: Purge child nodes
<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR>
<datarow>
<FirstName>John</FirstName>
</datarow></EMPLOYEE_SR>

Step 2: Purge root nodes


<?xml version='1.0' encoding='utf-8'?><EMPLOYEE_SR>
<datarow>
<FirstName>Manager</FirstName>
</datarow>
</EMPLOYEE_SR>

Self Recursive Conceptual Objects Restore Root Nodes


The ability to restore a self recursive conceptual object is not currently supported, but
you can perform this operation as a two-step process. This process must be invoked on
the RESTful URL of the corresponding data objects.
Step 1: Restore root nodes

Developing for webMethods OneData Version 9.7 131


M
Even Header
REST Web Services

<?xml version='1.0' encoding='utf-8'?>


<EMPLOYEE_SR>
<datarow>
<FirstName>Manager</FirstName>
</datarow>
</EMPLOYEE_SR>

Step 2: Restore child nodes


<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR>
<datarow>
<FirstName>John</FirstName>
</datarow></EMPLOYEE_SR>

Network Recursive Objects


Network Recursive Hierarchy Inserts and Updates
The following scenario shows XML that inserts data into the network recursive
conceptual object NR_EMPLOYEE using a REST service.
<?xml version='1.0' encoding='utf-8'?>
<NR_EMPLOYEE>
<datarow>
<EMPNAME>Manager</EMPNAME>
</datarow>
<datarow>
<EMPNAME>John Doe</EMPNAME>
<NR_EMPLOYEE_REL>
<datarow>
<RelatedManager>Manager</RelatedManager>
<RelatedEmployee> John Doe </RelatedEmployee>
</datarow>
</NR_EMPLOYEE_REL>
</datarow>
</NR_EMPLOYEE>

If the primary key values are sequences, include alternateKey in the RESTful web service
link as a request parameter. For more information about the request parameters, see
"REST URL Parameters" on page 118.
alternateKey = NR_EMPLOYEE = FNM; NR_EMPLOYEE_REL=EMP_ID,MGNR_ID

Network Recursive Hierarchy Delete, Restore, and Purge


The following scenario shows XML that deletes data from the network recursive
conceptual object NR_EMPLOYEE using a REST service.
Construct XML for the root node alone according to the XSD. Because the delete
operation deletes the hierarchy, you do not need to provide data for the complete
hierarchy. XML is required to contain the primary key information only.
<?xml version='1.0' encoding='utf-8'?>
<NR_EMPLOYEE>
<datarow>
<EMPNAME>Manager</EMPNAME>
</datarow>
<datarow>
<EMPNAME>John Doe</EMPNAME>

Developing for webMethods OneData Version 9.7 132


M
Odd Header
REST Web Services

</datarow></NR_EMPLOYEE>

If the primary key values are sequences, include alternateKey in the RESTful web service
link as a request parameter. For more information about the request parameters, see
"REST URL Parameters" on page 118.
alternateKey = NR_EMPLOYEE = FNM;
Set the processingMode parameter in the REST web service as delete. This deletes all
records from the MANAGER conceptual object under the specied hierarchy.
You can set this parameter as either purge or restore to delete all records from the
NR_EMPLOYEE network recursive conceptual object under the specied hierarchy.

Network Recursive Object Restore and Purge Root Nodes


To restore/purge the root nodes (nodes without any parent) in a network recursive
object, you must restore/purge all the child nodes rst. This is a two-step process with
child nodes in one XML and ONLY root nodes in the second XML.
Step 1: Restore / Purge child nodes
<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR> <datarow> <FirstName>John</FirstName> </datarow>
</EMPLOYEE_SR>

Step 2: Restore / Purge root nodes


<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR> <datarow>
<FirstName>Manager</FirstName>
</datarow></EMPLOYEE_SR>

Supertype and Subtype Object XML


Supertype and Subtype Inserts and Updates
Constructing XML to insert or update data in a supertype or subtype object is the
same as constructing this XML from a conceptual object. For more information, see
"Conceptual Objects" on page 129.

REST URL Parameters


You can use parameters to customize the request URL for REST. The format for the
request parameter in a request URL is:
hp://[hostname] :[port] /[contextRoot] /
rest/[repositoryId] /[projectName] /[type] /[objectName] ?[request_parameter]=[value]
The following table lists the parameters you can use in the REST web service URL. All
request parameters are case sensitive. Parameters can not be used in a JSON string. To
add a parameter to the lter, you must append it to the REST URL.

Developing for webMethods OneData Version 9.7 133


M
Even Header
REST Web Services

Parameter Summary Description and Example Syntax

alternateKey Alternate key to use when data is being modied.


alternateKey=COLUMN1,COLUMN2

baseVersion Indicates whether to retrieve data using the format in an


earlier version of OneData. baseVersion=true

batchSize The batch size of the number of records that are read or
cached in each call to the database. batchSize=25

dateFormat The date format to use when modifying data.

decode Indicates whether to use decode for reference columns.


decode=true

description Indicates whether to include the column description with the


generated XSD. description=true

enableDQMode Indicates whether to perform data quality checks during


REST update or insert actions on a consolidation object.
enableDQMode=true

filter For data retrieval only.

partialCommit Indicates whether to perform a partial commit of data


changes when an error is encountered. partialCommit=true

processingMode The action to perform. processingMode=update .

returnColumns Columns to include in the response output.


returnColumns=All .

schema_id Indicates whether to retrieve data from the Work area or the
Release area. schema_id=1

skipEmptyColumns Indicates whether to skip empty and missing XML tags.


skipEmptyColumns=true

sortColumn&sortOrder Order in which to sort columns retrieved, as either ascending


or descending. SortColumn=ID&sortOrder=asc

Developing for webMethods OneData Version 9.7 134


M
Odd Header
REST Web Services

Parameter Summary Description and Example Syntax

wildCardOP The character to use as a wildcard operator. wildCardOP=$

alternateKey
Alternate key to use when data is being modied. This is required if the primary key
column value does not exist in the data le. For conceptual objects, if processingMode is
delete, purge, or restore, the alternate key is only required for the root object.
Valid values are any combination of physical column names of data objects are unique and
non-null. There is no default value. Use the format:
Data objects. alternateKey=COLUMN1,COLUMN2
Conceptual objects.alternateKey=co_obj1=COLUMN1; co_obj2=COL2,COL3 , where
co_obj1 and co_obj2 are the constituent objects and COLUMN1, COL2, COL3 are the
corresponding physical column names.

Note: For conceptual objects, you must encode special characters and spaces in alternate
keys to prevent breaking the URL. If no alternate key is provided, the system assigns the
primary columns of the data object as the alternate key.

baseVersion
Indicates whether to retrieve data using the format in an earlier version of OneData. This
value overrides the default value dened at the system level in the onedata.properties
le.
baseVersion=true . Retrieve data in the previous format.
baseVersion=false . Default. Retrieve data in XML format. The default
value is set at the system level in the onedata.properties le:
onedata.webservice.rest.baseVersion=false

batchSize
The batch size of the number of records that are read or cached in each call to the
database. For example, if there are 1000 records available to retrieve and batchSize =100,
the server retrieves 100 records at a time, making 10 calls.

Tip: The batch size depends on the amount of memory available for processing on the
server. Since conceptual objects use more memory, so you should decrease batchSize
for conceptual objects and increase it for data objects. For large conceptual objects, try
conguring dierent values for batchSize to nd the size that oers the best response
time without generating an OutOfMemoryException error.

Developing for webMethods OneData Version 9.7 135


M
Even Header
REST Web Services

Use any positive integer value, for example, batchSize=25 . There is no default value.

dateFormat
The date format to use when modifying data. The default value is YYYY-MM-DD. Valid
values are any valid date format supported in OneData, for example, dateFormat=MM-
DD-YYYY.

decode
Indicates whether to use decode for reference columns. The tag name is the XML element
name at the column denition.
decode=true . Default.
decode=false . XML output displays the original value of the base column.

description
Indicates whether to include the column description with the generated XSD. Valid
values:
description=true Includes the description.
description=false . Default. Does not include the description.

enableDQMode
Indicates whether to perform data quality checks during REST update or insert actions
on a consolidation object. To dene an object as a consolidation object, in the object
denition, add Consolidation Object in Additional Qualifiers.
enableDQMode=true or not specied. Perform data quality checks during inserts or
updates.
enableDQMode=false . Skip data quality checks on objects.

filter
For data retrieval only. For lter options, see "Using Filters in REST Services" on page
110.
Valid values are any valid column in the specied object, for example,
lter=COLUMN1=21 . There is no default value.

Developing for webMethods OneData Version 9.7 136


M
Odd Header
REST Web Services

partialCommit
Indicates whether to perform a partial commit of data changes when an error is
encountered. The following are valid values.
partialCommit=true . Default. Partial commit is allowed.
partialCommit=false . Partial commit is not allowed.

processingMode
The action to perform. The default value is update. For example, processingMode=update .

Object Type Action to perform

Conceptual objects Delete hierarchy, purge hierarchy, and restore hierarchy.

Self recursive (SR) Purge root nodes. Restoring root nodes must be done as a
data object action on each object. For more information, see
"Self Recursive Objects" on page 130.

Network recursive Restore/purge root nodes. This is a two step process:


(NR) Child nodes in one XML.
ONLY root nodes in second XML.

Data objects Insert, update, update only, delete, purge, restore.

Conceptual objects Update, delete, purge, restore.

returnColumns
Columns to include in the response output. The <DATA> tag in the response contains
the data values from the object. If returnColumns is not specied, no <DATA> tags are
included in the response. Audit columns, logical columns (multi-select), and CLOB
columns cannot be returned.

Note: Applies only for insert and update actions.

The syntax is objectname=columnname for each object and column to retrieve. Separate
physical column names by commas. To return all columns specify All . There is no
default value for this parameter.
Data objects. returnColumns=COL1,COL2 . To return all columns, returnColumns=All .

Developing for webMethods OneData Version 9.7 137


M
Even Header
REST Web Services

Conceptual objects. For example, where objects are co_obj1 and


co_obj2, and columns are COL1, COL2, COL3: Return some columns:
returnColumns=co_obj1=COL1;co_obj2=COL2,COL3 . Return all columns,
returnColumns=co_obj1=All;co_obj2=All
decode does not apply to reference columns; therefore, the XML format is the same as
when decode=false .
For a data object, the number of data object tags in the <DATA> tag varies based on the
batch size. That is, if the batch size=100 (default value) and 200 records are inserted,
there are two <State> tags for a successful execution ow. If an error occurs, then each
record retriggered from the exception queue will be in a separate data object name tag.
The following is an example of the XML returned.
<?xml version="1.0" encoding="UTF-8" ?>
<OUTPUT>
<IDENTIFIER>447426</IDENTIFIER>
<RESULT>
<DATA>
<State>
<datarow>
<STATE_ID>3001</STATE_ID>
<STATE_NAME>State_Name_1</STATE_NAME>
</datarow>
<datarow>
<STATE_ID>5001</STATE_ID>
<STATE_NAME>State_Name_2</STATE_NAME>
</datarow>
</State>
</DATA>
<MESSAGE>Process finished successfully.</MESSAGE>
<STATUS>Success</STATUS>
<DETAILS>
<![CDATA[ Total records inserted/updated: 10 The process finished
successfully. Elapsed time: 1 s ]]>
</DETAILS>
</RESULT>
</OUTPUT>

For a conceptual object, the number of data object name tags varies for each constituent
object that is inserted or updated.
<?xml version="1.0" encoding="UTF-8" ?>
<OUTPUT>
<IDENTIFIER>447426</IDENTIFIER>
<RESULT>
<DATA>
<country>
<datarow>
<COUNTRY_ID >3001</COUNTRY_ID>
<COUNTRY_NAME>Country_Name_1</COUNTRY_NAME>
</datarow>
</country>
<state>
<datarow>
<STATE_ID>3001</STATE _ID>
<STATE_NAME>State_Name_1</STATE_NAME>
</datarow>
</state>
<city>

Developing for webMethods OneData Version 9.7 138


M
Odd Header
REST Web Services

<datarow>
<CITY_ID>3001</CITY_ID>
<CITY_NAME>City_Name_1</CITY _NAME>
</datarow>
</city>
</DATA>
<MESSAGE>Process finished successfully. </MESSAGE>
<STATUS>Success</STATUS>
<DETAILS>
<![CDATA[ Total records inserted/updated: 10 The process finished
successfully. Elapsed time: 1 s ]]>
</DETAILS>
</RESULT>
</OUTPUT>

schema_id
Indicates whether to retrieve data from the Work area or the Release area. Valid values:
schema_id=1 . Retrieves data directly from the database (work area), even when in-
memory is enabled.
schema_id=2 . Default. Retrieves data from the Release area. Data is also retrieved
from the Release area when the parameter is not dened.

skipEmptyColumns
Indicates whether to skip empty and missing XML tags. To use with conceptual objects,
ensure that every level in the conceptual object has at least one record.
skipEmptyColumns=true . Default.
skipEmptyColumns=false . Includes all empty and missing tags in the input XML for
insert and update actions.
To skip empty columns (shipEmptyColumns=true ) in a conceptual object that has Country
> State > City, all constituent objects must have at least one record, as in the following
examples.
<Country>
<Country_Name>Country_Name_1</Country_Name>
<State>
<St_Name>State_Name_1</St_Name>
<City>
<City_Name>City_Name_a</City_Name>
</City>
</State>
</Country>
<Country>
<Country_Name>Country_Name_1</Country_Name>
<State>
<St_Name>State_Name_2</St_Name
<City>
<City_Name>City_Name_b</City_Name>
</City>
</State>
</Country>

Developing for webMethods OneData Version 9.7 139


M
Even Header
REST Web Services

For a conceptual object that does not have a record in every level, set the value of
skipEmptyColumns as false.
<Country>
<Country_Name>Country_Name_1</Country_Name>
<State>
<St_Name>State_Name_1</St_Name>
<City>
<City_Name>City_Name_a</City_Name>
</City>
</State>
</Country>
<Country>
<Country_Name>Country_Name_1</Country_Name>
<State>
<St_Name>State_Name_2</St_Name
<City>
<!-- City record not present for the country -->
</City>
</State>
</Country>

sortColumn&sortOrder
Order in which to sort columns retrieved, as either ascending or descending. Sorting
is done per batch. Set batchSize greater than or equal to the number of records to be
retrieved. For conceptual objects, sorting can only be applied on the root level object.
Allowable Values:
sortColumn Column name.
sortOrder Valid values are asc or desc.
For example, sortColumn=ID&sortOrder=asc

wildCardOP
The character to use as a wildcard operator. This wildcard overrides the wildcard
specied at the system level. Ensure that the character is not used in the data column.
Allowable Values $`!;@^*( )< >':|~. For example, wildCardOP=$
Default Value $. Dened at the system level in the onedata.properties le,
onedata.webservice.rest.wildcard.op=$

Request Parameters by HTTP Methods


The following table describes the available HTTP methods and which create, read,
update, and delete (CRUD) actions can be performed for the parameter. O indicates that
the action is available, X indicates that it is not available.

Developing for webMethods OneData Version 9.7 140


M
Odd Header
REST Web Services

Parameter name HTTP Method CRUD Actions

GET POST Create Retrieve Update Delete

alternateKey X O O X O X

baseVersion O X X O X X

batchSize O O O O O O

dateFormat O O O O O O

decode O O O O O O

description O X X O X X

enableDQMode X O O X O X

lter O X X O X X

partialCommit X O O X O O

processingMode X O O X O O

returnColumns X O O X O X

schema_id O X X O X X

skipEmptyColumns X O O X O O

sortColumn & sortOrder O X X O X X

Using REST Web Service URL


You can use the REST web service link to manage data in OneData objects. You
can access the data either as an anonymous user or as a OneData user. When REST
fetches the data from an object, it checks for the user privileges and displays the data
accordingly. OneData returns the records in XML format. For conceptual objects,
OneData returns the child records too.

Developing for webMethods OneData Version 9.7 141


M
Even Header
REST Web Services

You can also lter the data returned by REST by providing appropriate lter conditions
in the request URL.

Accessing Data with the REST Service URL


If an anonymous user is set up in OneData, you can access the data through the REST
web service using the anonymous user ID and no password. When you access the data
as an anonymous user, you can perform only those actions that are allowed for that
anonymous user.
For more information about how to set up an anonymous user, see Administering
webMethods OneData.

To access data through the REST web service


1. In the browser, enter the RESTful web service link, for example, http:// localhost:8080/
onedata/rest/QA/StandardProject/DO/Employee.
2. To access the data, enter the user name and password:
As an anonymous user. Username as anonymous. Leave the password blank.
As a OneData user. Username as UserOne. The password is the encrypted
password.
All the records in the object are displayed in XML format.

REST XSDs
You can use a special request to retrieve the XML Schema (XSD) associated with a
particular data object, conceptual object, or interchange mapping. You can use this
functionality to retrieve the XSD through a RESTful call.
For information about how to obtain the XSD, see "REST XSDs" on page 127.

Obtaining the XSD from OneData


You can obtain an XSD in two ways:
Append /XSD or /XMLSchema to the RESTful URL for the object or interchange
mapping and execute the HTTP GET call.

Note: When the REST URL is invoked, the interchange mapping type must be set to
type XML or XSD. Specify this by appending /XSD or /XML to the end of the URL.

For example, to obtain the XSD from the REST URL http:// localhost:8080/
onedata/rest/QA/StandardProject/DO/Employee, append /XSD to the URL as
follows:
http://localhost:8080/onedata/rest/QA/StandardProject/DO/Employee/XSD

Developing for webMethods OneData Version 9.7 142


M
Odd Header
REST Web Services

Generate the XSD directly from OneData as explained below.

To obtain and download XSD from OneData


1. On the Menu toolbar, click Manage > Manage Data.
2. Select the object of which you want to generate the XSD.
3. In the Data Manager screen, click View > Definition.

Note: If the object mode is Default, click the Advanced Definition tab.

4. Click the + symbol next to External Services to expand the tab.


5. Click Generate XSD to obtain the XSD.

Note: You can also download the XSD by clicking Download XSD.

Obtain the XSD and construct XML according to this XSD. Using the HTTP client, POST
the created XML through the RESTful web service link. For examples of constructing
XML using XSD, see "REST XSDs" on page 127.

Configuring OneData to Skip Empty Columns


You can congure OneData to skip empty columns and reset the value of
any other column as empty by using REST in the onedata.properties le. The
onedata.datainterchange.nullify.keyword property denes whether to nullify an
empty eld while constructing the XML. Use this property along with the parameter
skipEmptyColumns in the REST URL.

To skip empty columns and reset other columns


1. Go to <Installation_Directory>\SoftwareAG\profiles\ODE\bin\onedata\config directory and
open the onedata.properties file.
2. Set the property, onedata.datainterchange.nullify.keyword=NULLIFY_FIELD to
automatically skip empty columns and reset fields. Save and close the file.
For example, if onedata.datainterchange.nullify.keyword=NULLIFY_FIELD,
and you want to reset a column value while constructing XML, use NULLIFY_FIELD
as follows.
<ADDRESS>
<datarow>
<ID>12</ID>
<COL1>Book</COL1>
<COL2>NULLIFY_FIELD</COL2>
<COL3></COL3>
</datarow>
</ADDRESS>

3. In the REST web service link, use the parameter skipEmptyColumns=true .


4. Using the HTTP Client, POST the created XML through the RESTful web service link.

Developing for webMethods OneData Version 9.7 143


M
Even Header
REST Web Services

XSD Samples by Object Type


This section provides examples of how to construct XML using the XSD in dierent
scenarios.
For information about obtaining an XSD, see "REST XSDs" on page 127.

Conceptual Objects
Conceptual Object Inserts and Updates
The following scenario shows XML that inserts data into the conceptual object
REST_BRAND using REST.
You do not need to provide data for the hierarchy relation in the REST_BRAND
object. REST automatically identies the hierarchy relationship. In the below
example, the hierarchy relation is shown as <!--<RelatedBrandType>Fridge</
RelatedBrandType>--> and <!--<RelatedBrand>Kelvinator</RelatedBrand>-->.
In an input XML to insert multiple records, if the data hierarchy is not complete for
all records, OneData recommends that you provide the foreign key value so that the
records connect correctly. For example, if in a three-level hierarchy each node has
dierent number of levels, you must provide the foreign key value for each level.
<?xml version='1.0' encoding='utf-8'?>
<REST_BRAND_TYPE>
<datarow>
<BrandTypeName>Fridge</BrandTypeName>
<BrandTypeCode>F0022</BrandTypeCode>
<REST_BRAND>
<datarow>
<BrandName>Kelvinator</BrandName>
<BrandCode>KVL2</BrandCode>
<!--<RelatedBrandType>Fridge</RelatedBrandType>-->
<REST_PRODUCT>
<datarow>
<ProductName>FreshMatic</ProductName>
<ProductCode>FRS</ProductCode>
<!--<RelatedBrand>Kelvinator</RelatedBrand>-->
</datarow>
</REST_PRODUCT>
</datarow>
</REST_BRAND>
</datarow>
</REST_BRAND_TYPE>

If the primary key values are sequences, include alternateKey in the RESTful web service
link as a request parameter.
alternateKey= REST_BRAND_TYPE= BRAND_TYPE_NAME;
REST_BRAND=REST_BRAND_NAME;
REST_PRODUCT=REST_PROD_NM

Developing for webMethods OneData Version 9.7 144


M
Odd Header
REST Web Services

For more information about the request parameters, see "REST URL Parameters" on
page 118.

Conceptual Object Deletes, Restores, and Purges


The scenario explained here shows XML that deletes data from the conceptual object
REST_BRAND using REST.
Construct XML for the root node alone according to the XSD. Because the delete
operation will delete the hierarchy, you do not need to provide data for the complete
hierarchy. XML is required to contain the primary key information only.
<?xml version='1.0' encoding='utf-8'?>
<REST_BRAND_TYPE>
<datarow>
<BrandTypeName>Fridge</BrandTypeName>
</datarow>
</REST_BRAND_TYPE>

If the primary key values are sequences, include alternateKey in the RESTful web service
link as a request parameter.
alternateKey =REST_BRAND_TYPE=BRAND_TYPE_NAME;
Set the processingMode parameter in the RESTful web service URL as delete. You can
set this parameter as either purge or restore. For more information about the request
parameters, see "REST URL Parameters" on page 118.

Self Recursive Objects


Self Recursive Hierarchy Inserts and Updates
The scenario explained here shows XML that inserts data into the self recursive
conceptual object MANAGER using REST.
<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR>
<datarow>
<FirstName>Manager</FirstName>
<LastName>last name</LastName>
</datarow>
<datarow>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<RelatedManager>Manager</RelatedManager>
</datarow>
</EMPLOYEE_SR>

If the primary key values are sequences, include alternateKey in the RESTful web service
URL as a request parameter. For more information about the request parameters, see
"REST URL Parameters" on page 118.
alternateKey =EMPLOYEE_SR=FNM

Developing for webMethods OneData Version 9.7 145


M
Even Header
REST Web Services

Self Recursive Hierarchy Deletes, Restores, and Purges


The scenario explained here shows XML to delete data from the self recursive
conceptual object MANAGER using REST.
Construct XML for the root node alone according to the XSD. Because the delete
operation will delete the hierarchy, you do not need to provide data for the complete
hierarchy.# XML is required to contain the primary key information only.
<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR>
<datarow>
<FirstName>Manager</FirstName>
</datarow>
<datarow>
<FirstName>John</FirstName>
</datarow>
</EMPLOYEE_SR>

If the primary key values are sequences, include alternateKey in the RESTful web service
link as a request parameter.
alternateKey = NR_EMPLOYEE = FNM;
Set the processingMode parameter in the RESTful web service URL as delete. This deletes
all records from the MANAGER conceptual object under the specied hierarchy. You
can pass this parameter as either purge or restore. For more information about the
request parameters, see "REST URL Parameters" on page 118.

Self Recursive Conceptual Object Restore Root Nodes


To purge the root nodes (nodes without any parent) in a self recursive object, you must
purge all the child nodes rst. This is a two-step process with child nodes in one XML
and only root nodes in the second XML.
Step 1: Purge child nodes
<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR>
<datarow>
<FirstName>John</FirstName>
</datarow></EMPLOYEE_SR>

Step 2: Purge root nodes


<?xml version='1.0' encoding='utf-8'?><EMPLOYEE_SR>
<datarow>
<FirstName>Manager</FirstName>
</datarow>
</EMPLOYEE_SR>

Self Recursive Conceptual Objects Restore Root Nodes


The ability to restore a self recursive conceptual object is not currently supported, but
you can perform this operation as a two-step process. This process must be invoked on
the RESTful URL of the corresponding data objects.
Step 1: Restore root nodes

Developing for webMethods OneData Version 9.7 146


M
Odd Header
REST Web Services

<?xml version='1.0' encoding='utf-8'?>


<EMPLOYEE_SR>
<datarow>
<FirstName>Manager</FirstName>
</datarow>
</EMPLOYEE_SR>

Step 2: Restore child nodes


<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR>
<datarow>
<FirstName>John</FirstName>
</datarow></EMPLOYEE_SR>

Network Recursive Objects


Network Recursive Hierarchy Inserts and Updates
The following scenario shows XML that inserts data into the network recursive
conceptual object NR_EMPLOYEE using a REST service.
<?xml version='1.0' encoding='utf-8'?>
<NR_EMPLOYEE>
<datarow>
<EMPNAME>Manager</EMPNAME>
</datarow>
<datarow>
<EMPNAME>John Doe</EMPNAME>
<NR_EMPLOYEE_REL>
<datarow>
<RelatedManager>Manager</RelatedManager>
<RelatedEmployee> John Doe </RelatedEmployee>
</datarow>
</NR_EMPLOYEE_REL>
</datarow>
</NR_EMPLOYEE>

If the primary key values are sequences, include alternateKey in the RESTful web service
link as a request parameter. For more information about the request parameters, see
"REST URL Parameters" on page 118.
alternateKey = NR_EMPLOYEE = FNM; NR_EMPLOYEE_REL=EMP_ID,MGNR_ID

Network Recursive Hierarchy Delete, Restore, and Purge


The following scenario shows XML that deletes data from the network recursive
conceptual object NR_EMPLOYEE using a REST service.
Construct XML for the root node alone according to the XSD. Because the delete
operation deletes the hierarchy, you do not need to provide data for the complete
hierarchy. XML is required to contain the primary key information only.
<?xml version='1.0' encoding='utf-8'?>
<NR_EMPLOYEE>
<datarow>
<EMPNAME>Manager</EMPNAME>
</datarow>
<datarow>
<EMPNAME>John Doe</EMPNAME>

Developing for webMethods OneData Version 9.7 147


M
Even Header
REST Web Services

</datarow></NR_EMPLOYEE>

If the primary key values are sequences, include alternateKey in the RESTful web service
link as a request parameter. For more information about the request parameters, see
"REST URL Parameters" on page 118.
alternateKey = NR_EMPLOYEE = FNM;
Set the processingMode parameter in the REST web service as delete. This deletes all
records from the MANAGER conceptual object under the specied hierarchy.
You can set this parameter as either purge or restore to delete all records from the
NR_EMPLOYEE network recursive conceptual object under the specied hierarchy.

Network Recursive Object Restore and Purge Root Nodes


To restore/purge the root nodes (nodes without any parent) in a network recursive
object, you must restore/purge all the child nodes rst. This is a two-step process with
child nodes in one XML and ONLY root nodes in the second XML.
Step 1: Restore / Purge child nodes
<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR>
<datarow>
<FirstName>John</FirstName> </datarow>
</EMPLOYEE_SR>

Step 2: Restore / Purge root nodes


<?xml version='1.0' encoding='utf-8'?>
<EMPLOYEE_SR>
<datarow>
<FirstName>Manager</FirstName>
</datarow>
</EMPLOYEE_SR>

Supertype and Subtype Object XML


Supertype and Subtype Inserts and Updates
Constructing XML to insert or update data in a supertype or subtype object is the
same as constructing this XML from a conceptual object. For more information, see
"Conceptual Objects" on page 129.

Developing for webMethods OneData Version 9.7 148


M
Odd Header
In-Memory Database

7 In-Memory Database
In-Memory Database in OneData .............................................................................................. 150
Caching ...................................................................................................................................... 150
Configuring Caching ................................................................................................................... 151
Dependent Object Mapping ....................................................................................................... 152
Creating a Cache Refresh Job .................................................................................................. 153
Scheduling a Cache Refresh Job .............................................................................................. 154

Developing for webMethods OneData Version 9.7 149


M
Even Header
In-Memory Database

In-Memory Database in OneData


The In-Memory database feature allows you to store large amounts of data in memory,
enabling faster retrieval of data. OneData uses Terracoa as an in-memory database
solution for the REST web services.

Caching
The In-Memory Database Caching feature enables faster retrieval of data through REST
Web Services. This is implemented by utilizing the memory space of the deployment
server. The data is cached and accessed from server memory. This feature reduces time
taken for data retrieval and allows higher performance in terms of data fetches.
Using the OneData In-Memory Database Caching feature, you can congure those data
and conceptual objects for which caching is to be enabled. When caching is enabled for
the required objects, access to these objects through REST Web Services becomes faster
because the data fetch is done from server memory instead of the database.
Notes
When In-Memory caching is enabled for an object and it is accessed through REST
Web Services, the default Batch Size is set as 5000.
When In-Memory caching is enabled for a Conceptual Object, the Implicit Filter set
for this CO is ignored when this CO is accessed through REST Web Services.
Consider a data object for which more than one related description column is set for
a relation. When in-memory caching is enabled for this data object, retrieving this
through REST will aect performance.
When in-memory caching is enabled for an object that contains a column of
timestamp data, the object can be accessed using a REST web service only if the
system property Work Area-to-Release Area Mode is set as Nova in Administer >
System > System Properties.
Consider a conceptual object with the following structure.

Developing for webMethods OneData Version 9.7 150


M
Odd Header
In-Memory Database

Following are columns in State and City objects:

When in-memory caching is enabled for this conceptual object, this cannot be accessed
using a REST web service due to the multiple same-level object relation specied from
City to State.

Configuring Caching
To use the in-memory database caching feature, you must modify the OneData
properties le. For information about modifying the properties le, see Administering
webMethods OneData.
To use REST to retrieve data for a conceptual object from cache, caching must be
explicitly enabled for all the child objects of the conceptual object.

To configure caching
1. On the Menu toolbar, click Define > Objects.
2. Navigate to the required object and select the Cache tab.
3. Define the configuration parameters:

Developing for webMethods OneData Version 9.7 151


M
Even Header
In-Memory Database

Parameter Description

Enable Caching? Whether to enable metadata/data caching for the object. At


start up, OneData loads only the metadata for the objects in
which this option has been enabled.

Cache Displays Terracoa.


Implementation

Create Cache on Whether to load the data cache at start-up. When this seing
Start-up? enabled, if Enable Caching? is also enabled, the data cache is
also loaded at start-up along with the metadata cache for the
object.

Named Cache Key Whether OneData generates a unique key to identify the
cache for the selected data object (for data objects only). The
key contains [Type of Object] / [Object ID in Production] /
[Repository] / [Client ID] / [Project ID] / [Schema ID].

Note: This parameter is available for data objects only.

Maximum Maximum number that the ehcache conguration property


Records In maxEntriesLocalHeap can be set to. maxEntriesLocalHeap
Memory controls the maximum number of cache entries that can exist
in local heap memory.

Note: If you do not provide any value or set the value as 0,


OneData makes an innite number of cache entries.

4. Click Save.
5. Click Refresh Cache to refresh the data cache immediately. Confirm whether to refresh
the dependent object(s) to reload the object and the associated objects. When you click on
Cancel, only the selected object is reloaded.

Dependent Object Mapping


After enabling caching for a data object, dependent objects that need to be refreshed on
data change of this data object can be mapped to it.

Note: Dependent object mapping is not available for conceptual objects.

To map dependent objects


1. On the Menu toolbar, click Define > Objects.

Developing for webMethods OneData Version 9.7 152


M
Odd Header
In-Memory Database

2. Navigate to the required object and select the Cache tab.


3. Click the Dependent Object Mapping link and click Add new Dependent Object Mapping.

Note: This conguration is applicable for S2P process and not for initial load or
Refresh Cache.

4. Configure the following parameters:

Parameter Description

Mapping Name Name for the mapping. If you do not specify a mapping
name, OneData generates the name. This seing cannot be
changed after the mapping is saved.

Dependent Object Objects for which caching has been enabled. Select the
Name dependent object. This seing cannot be changed after the
mapping is saved.

Dependent Object Column names of the selected dependent object name.


Columns Select the required column(s) for mapping.

Selected Columns Use the navigation arrows to move required columns from
Dependent Object Columns to this eld.

Primary Key Primary key of the current object to which dependent object
Column of Current mapping is to be done.
Object

5. Click Save.
The number of columns in Selected Columns and Primary Key Column of Current Object
must be the same to successfully save the dependent object mapping.
To edit or delete the dependent object mappings, navigate to the mapping and click the
Edit or Delete icon.

Creating a Cache Refresh Job


Multiple objects can be selected and refreshed by using the Cache Refresh Job. This job
can then be scheduled to run at a specied time.

To create a new cache refresh job


1. On the menu tool bar, click Define > Configuration > Cache > Cache Refresh.
2. Click Add to create a new cache refresh job.

Developing for webMethods OneData Version 9.7 153


M
Even Header
In-Memory Database

3. Complete the job definition:

Parameter Description

Name Name for the new cache refresh job.

Description Description of the job.

Available Objects Objects for which caching has been enabled.

Selected Objects Use the arrows to move the required objects from Available
Objects to Selected Objects.

Notification User or user group to be notied. Use the search option to


select a required user or user group from the list.

Note: OneData displays 100 users or user groups per page.

4. Click Save. OneData saves the cache refresh job. After the job has successfully run, OneData
notifies the designated user or user group.

Note: When the conguration Enable Caching? and Create Cache on Start-up? is set on a
conceptual object, all the data for the constituent objects is automatically loaded to
the cache. To prevent multiple data loads, ensure that Create Cache on Start-up? is not
checked for the constituent objects of the conceptual object.

Data Cache Refresh from Work Area to Release Area


On production transfer of data, if Enable Caching? is set for the object, the data is updated
or invalidated from the data cache. To get data updated correctly on the constituent
objects for a conceptual object, the Enable Caching? option must be set for all of its
constituent objects.

Scheduling a Cache Refresh Job


After you create a Cache Refresh job, it can be run or scheduled from the job center. For
details about the job center and scheduling, see Implementing webMethods OneData.

To schedule a cache refresh job


1. On the Menu toolbar, click Administer > Job Center.
2. In Job Type, select Cache Refresh.
3. Click Next to view all cache refresh jobs.

Developing for webMethods OneData Version 9.7 154


M
Odd Header
In-Memory Database

4. Click the Schedule icon corresponding to the cache refresh job to schedule the job.

Developing for webMethods OneData Version 9.7 155