Professional Documents
Culture Documents
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).
Table of Contents
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
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
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
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.
{} Indicates a set of choices from which you must choose one. Type
only the information inside the curly braces. 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 (...).
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 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.
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
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.
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.
Note: You cannot use hooks to delete data in objects that have multi-select columns.
Delete No No Yes
Restore No No Yes
Purge No No Yes
The following diagram shows the dierent ways that hooks can be invoked.
Hook Types
You can use the hooks in OneData to invoke stored procedures, java RMIs, Java local
programs, and Integration Server.
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 .
%TABLE_NAME% Physical table name of the object associated with the hook.
Note: If the values that you pass contain only numbers, dene the parameter as long or
string.
Property Description
Hook Execution
Mode
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
Property Description
Hook Execution
Mode
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
For details on designing a process ow hook, see "Building a Process Flow" on page
63.
Property Description
Hook Execution
Mode
Property Description
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 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.
Default Parameters For stored procedures only. For information about default
parameters, see "Default Parameters in a Stored Procedure
Hook" on page 14.
4. Click Save.
The Hooks screen shows the new hook.
Note: Before you can assign a hook to an object, you must dene the hook as described in
"Dening a Hook" on page 21.
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.
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.
Note: Before you can assign a hook to an object, you must dene the hook as described in
"Dening a Hook" on page 21.
Property Description
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.
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.
Hook Properties
workowPassPhrase getWorkflowPassPhrase()
Returns the passphrase, which is a unique string used to
identify the transaction in an external workow.
hookInput. workflowPassPhrase
hookInput. getWorkflowPassPhrase()
Stored Procedures
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();
hookOutput.setInvocationNumber(hookInput.getInvocationNumber());
hookOutput.setOriginalRowset(hookInput.getOriginalRowset());
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);
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);
Function See...
Function See...
GetColumnValue Function
Returns the value of the column.
Parameters Description
Usage example
Row:= hookInput.OriginalRowset.rowset(1);
Ihook.getColumnValue(row, 'CUST_NM');
SetColumnValue Function
Sets the value of the specic column in a row.
Parameters Description
Parameters Description
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
Usage example
Row:= hookInput.OriginalRowset.rowset(1);
Ihook.getColumnOldValue(row, 'CUST_NM');
getMSColumnValue Function
Returns the values of the multi select column.
Parameters Description
setMSColumnValue Function
Sets the values of the specic multi-select column in a row.
Parameters Description
Parameters Description
getMSColumnOldValue Function
For updates, user can retrieve previous values of the multi-select column in a post-event
hook.
Parameters Description
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
Count Function
Parameters Description
Parameters
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.
Type of DML Insert, update, and delete are supported in both SP and
Java RMI. Purge and restore are supported only in Java
RMI.
Usage Example
Table with no Conceptual Object
Ars := t_actionrowset(rows,'TABLE1', 2, 'update');
Rowset Properties
The following table displays the stored procedures and Java functions.
objShowable.setTableName()
objShowable.setObjectName()
objShowable.setObjectType()
objShowable.setSelectionType()
hookOutput.setShowRowset(objShowable)
Parameter Description
Object Table name in OneData, data object name, virtual object name or
'various' if not a persistent object.
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)
Note: If there is a question, Cancel is displayed automatically. Clicking Cancel closes the
iHook window and session.
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);
None None
Usage Example
Answers := t_answers();
Parameters Description
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");
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);
Parameter Description
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
Function Description
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();
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();
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);--
hookOutput.invocationNumber := hookInput.invocationNumber;
hookOutput.originalRowset := hookInput.originalRowset;
begin-- Gets the rows that the user has clicked on.
hookInput := iHook.getHookInput (v_data_in);--
hookOutput.invocationNumber :=
hookInput.invocationNumber; hookOutput.originalRowset :=
hookInput.originalRowset;
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;
rows.extend;
rows (rows.last) := row;
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;
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;
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());
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);
}
}
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);
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;
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.
Data Object Data object is required, even if cardinality is 0 for the process
ow execution.
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.
Process Component. A process component contains the process that is being executed
in a process ow. The process component contains the individual process items,
Process Description
Property
Loop. Loop components are containers for splier (start loop) and aggregator (end
loop) process items.
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 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.
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.
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.
Property Description
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.
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.
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.
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.
Property Description
Sequence Logic or query for evaluating the next value of the sequence, for
Logic example, SELECT group_seq.NEXTVAL FROM DUAL.
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
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.
Aribute Mapping tab. List of all the objects constituting the conceptual
object selected.
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.
Property Description
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.
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.
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.
Property Description
Aribute Attribute tab. Aributes that store the result of the SQL query that
is passed to subsequent steps.
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.
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.
Property Description
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.
Data Source Form or DataGrid where rows exist for the iteration.
Item
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.
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 .
Note: Process ow changes cannot be saved until you resolve all the errors.
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.
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.
Tip: To delete the connector, click the connector. When the connector turns blue,
press the DELETE key.
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.
The following diagram displays the property denitions for each of the process items in
the process ow.
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.
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;
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>
PROJECTID Optional. Project ID if more than one project is dened for the
client in the metadata.
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>
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>
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.
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
Output Parameters
None.
Sample Input
RepositoryId = CAPITOL
UserId = admin
Password = 73ACD9A5972130B75066C82595A1FAE3
Schema Id = 2
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
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
Output Parameters
None.
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.
Job Token Required. Specify the job token returned during the execution of
the executeAsynchronousDeploymentJob service.
Output Parameters
None.
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
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
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
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.
Input Parameters
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>
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
Job Token Required. Specify the job token returned during the execution
of executeAsynchronousJob.
Output Parameters
None.
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.
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>
<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
Parameter Description
Parameter Description
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.
<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
Parameter Description
Tip: Click Save & Return to save the seings and return to the home page of OneData.
Important: If external security is enabled (Active Directory, LDAP, etc.), use the clear text
password that is passed to the external authentication provider.
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>
<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>
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>
<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.
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 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.
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.
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>
Object Name Column Name XML Element Name for the Column
State ID STATE_ID
NAME STATE_ID
CNTRY_ID 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.
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>
Tag Description
Tag Description
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.
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>
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.
Note: If the object uses Default mode, click the Advanced Definition tab.
Note: The RESTful web service link also displays in the Interchange Mapping screen. On
the Menu toolbar, click Data Interchange > Configuration > Interchange Mapping.
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.
IN conditions No Yes
Parameter Description
Parameter Description
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.
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.
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 or COL2&nullOperator=IS_NOT_NULL
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"
"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" : ""}
batchSize The batch size of the number of records that are read or
cached in each call to the database. batchSize=25
schema_id Indicates whether to retrieve data from the Work area or the
Release area. schema_id=1
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
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.
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 .
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.
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.
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>
<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>
<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=$
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
You can also lter the data returned by REST by providing appropriate lter conditions
in the request URL.
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.
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
Note: If the object mode is Default, click the Advanced Definition tab.
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.
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
For more information about the request parameters, see "REST URL Parameters" on
page 118.
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.
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
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.
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
</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.
batchSize The batch size of the number of records that are read or
cached in each call to the database. batchSize=25
schema_id Indicates whether to retrieve data from the Work area or the
Release area. schema_id=1
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.
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.
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 .
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.
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.
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 .
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>
<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>
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=$
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
You can also lter the data returned by REST by providing appropriate lter conditions
in the request URL.
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.
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
Note: If the object mode is Default, click the Advanced Definition tab.
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.
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
For more information about the request parameters, see "REST URL Parameters" on
page 118.
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.
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
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.
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
</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.
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
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.
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:
Parameter Description
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].
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.
Note: This conguration is applicable for S2P process and not for initial load or
Refresh Cache.
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.
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.
Parameter Description
Selected Objects Use the arrows to move the required objects from Available
Objects to Selected Objects.
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.
4. Click the Schedule icon corresponding to the cache refresh job to schedule the job.