TIBCO

MDM
Web Services Guide
Software Release 8.3.1
October 2013
Two-Second Advantage

Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED
OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED
ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED
SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR
ANY OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A
LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE
AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER
LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE
SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE.PDF) OR IF THERE IS NO SUCH SOFTWARE
LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED
IN THE LICENSE FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS
AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN
AGREEMENT TO BE BOUND BY THE SAME.
This document contains confidential information that is subject to U.S. and international copyright laws and
treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO
Software Inc.
TIBCO, Two-Second Advantage, TIB, TIBCO Adapter, Predictive Business, Information Bus, TIBCO
BusinessConnect, TIBCO ActiveMatrix BusinessWorks, TIBCO Enterprise Message Service are either registered
trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.
Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition
(J2EE), and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation
in the U.S. and other countries.
All other product and company names and marks mentioned in this document are the property of their
respective owners and are mentioned for identification purposes only.
THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL
OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME
TIME. SEE THE README.TXT FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A
SPECIFIC OPERATING SYSTEM PLATFORM.
THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.
CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE
INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE
IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN
THIS DOCUMENT AT ANY TIME.
THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR
INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING
BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.
This Product is covered by U.S. Patent No. 7,472,101.
Copyright 1999-2013 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information
TIBCO MDM Web Services Guide
|
iii
Contents
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .vii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Changes from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
TIBCO MDM Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Chapter 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Working of Web Services in TIBCO MDM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Web Service Message Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Generic Schema Based Message Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Strict Schema Based Message Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Accessing Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Validation of XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Validation of XML Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Including Namespace in Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Design Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Administrator Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Data Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
DataLoad Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Content Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Event Management Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Administrator Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Data Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
DataLoad Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
TIBCO MDM Web Services Guide
iv
|
Contents
Content Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Event Management Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Password Encryption and Decryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Session Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Web Services Available in TIBCO MDM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Web Services Accepting Multiple Entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Chapter 2 Record Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
CRUD Services for Record Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Repositories with FED attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Generating WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
WSDL and XML Schema Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
CRUD Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Record Query Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Record Query Metadata Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Record Query ValidValues (Init) Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Record Validate Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Record Add or Modify Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Record Delete Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Initiate Workflow Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Transaction Atomicity for Record Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Scenario 1: Process Multiple CUD Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Scenario 2: Large Number of Modified Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Scenario 3: Same Record in Multiple Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Scenario 4: Enable Global Distributed Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Chapter 3 Work Item Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Work Item Query Parameters Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Work Item Query Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Work Item Modify Close Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Work Item Lock Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Work Item UnLock Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Get Work Item Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Work Item Reassign Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Get Custom Work Item Summary Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Get Predefined Work Item Summary Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
TIBCO MDM Web Services Guide
Contents
|
v
Chapter 4 Administration Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Login Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Logout Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Get Entitlement Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Create Enterprise Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Get Enterprise List Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Create User Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Modify User Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Change Password Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Delete User Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Get User List Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Get Role List Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Chapter 5 Data Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Text Search Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Enabling Text Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Types of Text Search Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Get DataSource List Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Get Repository List Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Get Related Repository List Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Get Repository With Dependant Artifacts Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Initiate Synchronization Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Upload Metadata Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Extract Data Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Quick Export Service Using Data Extractor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
GetClassificationSchemeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
GetClassificationSchemeAttributeList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
GetClassificationCodeHierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Chapter 6 DataLoad Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
Get DataSource Info Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Upload DataSource Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Import Records Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Load Import Records Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Chapter 7 Content Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
Get Content Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
TIBCO MDM Web Services Guide
vi
|
Contents
Chapter 8 Event Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Get Event Info Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Get Event Details Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Get Import Event Status Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
TIBCO MDM Web Services Guide
Tables
|
vii
Tables
Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Table 2 Elements in a Web Service Request or Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Table 3 Endpoint Dispatching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Table 4 SOAP Action Dispatching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Table 5 Attributes of Payload.xsd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Table 6 Authentication of Administrator Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Table 7 Authentication of Data Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 8 Authentication of DataLoad Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 9 Authentication of Content Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 10 Authentication of Event Management Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 11 Faults of Administrator Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 12 Faults of Data Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 13 Faults of DataLoad Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 14 Faults of Content Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 15 Faults of Event Management Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Table 16 UI Browser Web Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Table 17 Web Services Available in TIBCO MDM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Table 18 Web Services Accepting Multiple Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Table 19 XSD Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Table 20 Record Query - External Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Table 21 Record Query - Supported Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Table 22 Record Query - Deprecated and Equivalent Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Table 23 Record Query - Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Table 24 Relationship Type for Perspective and Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Table 25 Record Query MetaData - External Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
TIBCO MDM Web Services Guide
viii
|
Tables
TIBCO MDM Web Services Guide
|
ix
Preface
The TIBCO

MDM is a tool to manage master data of your organization by

providing a framework for governance, rules, and processes.
This ensures accuracy and efficiency both inside the enterprise as well as
throughout the value chain so that multiple processes are optimally coordinated.
TIBCO MDM delivers a multi domain horizontal platform to manage all types of
information including products, customers, vendors, reference data, trading
partners, and so on.
Topics
Changes from the Previous Release of this Guide, page x
Related Documentation, page xii
Typographical Conventions, page xiv
Connecting with TIBCO Resources, page xv
TIBCO MDM Web Services Guide
x
|
Changes from the Previous Release of this Guide
Changes from the Previous Release of this Guide
This section itemizes the major changes to web services from the previous release:
Transaaction Atomicity for Record Web Services
You can process the record web service requests as an atomic operation that
include multiple commands within the <Transaction> element. Transaction
atomicity applies to the Create, Update, and Delete operations performed on a
record. For information, refer to Transaction Atomicity for Record Web Services
on page 111.
New Web Services
The following new web services are introduced in this release:
Administration Services
Modify User Service, page 164
Change Password Service, page 170
DataLoad Services
Get DataSource Info Service, page 222
Upload DataSource Service, page 224
Import Records Service, page 226
Load Import Records Service, page 228
Event Management Services
Get Import Event Status Service, page 240
Enhanced Web Services
The following web services are enhanced in this release:
Record Services
Record Query Service, page 61
Administration Services
Create User Service, page 159
TIBCO MDM Web Services Guide
Preface
|
xi
TIBCO MDM Web Services Guide
xii
|
Related Documentation
Related Documentation
This section lists documentation resources you may find useful.
TIBCO MDM Documentation
The following documents form the TIBCO MDM documentation set:
TIBCO MDM Installation and Configuration Guide: Read this manual for
instructions on site preparation, installation, and configuration.
TIBCO MDM Users Guide: This manual explains features and benefits of
TIBCO MDM from the business users viewpoint. It describes the features and
functionality as well as all the screens.
TIBCO MDM System Administration: This manual explains features relevant to
the system administrator.
TIBCO MDM Customization: Read this manual to how the application can be
customized to your enterprise needs.
TIBCO MDM Workflow Reference: This manual is a reference for automation of
business processes.
TIBCO MDM Web Services Guide: This manual is a reference for using web
services in TIBCO MDM.
TIBCO MDM Release Notes: Read the release notes for a list of new and
changed features. This document also contains lists of known issues and
closed issues for this release.
Other TIBCO Product Documentation
You may find it useful to read the documentation for the following TIBCO
products:
TIBCO MDM Studio Installation Guide: Read this manual for instructions on
installation of TIBCO MDM Studio.
TIBCO MDM Studio Process Designer Users Guide: This guide is a reference for
designing workflows using the TIBCO MDM Process Designer graphical user
interface.
TIBCO MDM Studio Process Designer Tutorial: This guide is a tutorial for
designing workflows using the TIBCO MDM Process Designer graphical user
interface.
TIBCO MDM Web Services Guide
Preface
|
xiii
TIBCO MDM Studio Repository Designer Users Guide: This guide is a reference
for designing repositories using the TIBCO MDM Repository Designer
graphical user interface.
TIBCO MDM Studio Repository Designer Tutorial: This guide is a tutorial for
designing repositories using the TIBCO MDM Repository Designer graphical
user interface.
TIBCO MDM Studio Rulebase Designer Users Guide: This guide is a reference
for designing rulebases using the TIBCO MDM Rulebase Designer graphical
user interface.
TIBCO MDM Studio Rulebase Designer Tutorial: This guide is a tutorial for
designing rulebases using the TIBCO MDM Rulebase Designer graphical user
interface.
TIBCO Enterprise Message Service software: This software allows the
application to send and receive messages using the Java Message Service
(JMS) protocol. It also integrates with TIBCO Rendezvous and TIBCO
SmartSockets messaging products.
TIBCO BusinessWorks software: This is a scalable, extensible and easy to use
integration platform that allows you to develop and test integration projects.
It includes a graphical user interface (GUI) for defining business processes
and an engine that executes the process.
TIBCO BusinessConnect software: This software allows your company to send
and receive XML or non-XML business documents over the Internet. Based on
a mutually agreed process flow and common document format, you and your
trading partners can conduct secure and verifiable business transactions
online.
TIBCO MDM Web Services Guide
xiv
|
Typographical Conventions
Typographical Conventions
The following typographical conventions are used in this manual.
Table 1 General Typographical Conventions
Convention Use
code font Code font identifies commands, code examples, filenames, pathnames, and
output displayed in a command window. For example:
Use MyCommand to start the foo process.
bold code
font
Bold code font is used in the following ways:
In procedures, to indicate what a user types. For example: Type admin.
In large code samples, to indicate the parts of the sample that are of
particular interest.
In command syntax, to indicate the default parameter for a command. For
example, if no parameter is specified, MyCommand is enabled:
MyCommand [enable | disable]
italic font Italic font is used in the following ways:
To indicate a document title. For example: See TIBCO BusinessWorks Concepts.
To introduce new terms For example: A portal page may contain several
portlets. Portlets are mini-applications that run in a portal.
To indicate a variable in a command or code syntax that you must replace.
For example: MyCommand pathname
Key
combinations
Key name separated by a plus sign indicate keys pressed simultaneously. For
example: Ctrl+C.
Key names separated by a comma and space indicate keys pressed one after the
other. For example: Esc, Ctrl+Q.
The note icon indicates information that is of special interest or importance, for
example, an additional action required only in certain circumstances.
The tip icon indicates an idea that could be useful, for example, a way to apply
the information provided in the current section to achieve a specific result.
The warning icon indicates the potential for a damaging situation, for example,
data loss or corruption if certain steps are taken or not taken.
TIBCO MDM Web Services Guide
Preface
|
xv
Connecting with TIBCO Resources
How to Join TIBCOmmunity
TIBCOmmunity is an online destination for TIBCO customers, partners, and
resident experts. It is a place to share and access the collective experience of the
TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety
of resources. To register, go to http://www.tibcommunity.com.
How to Access TIBCO Documentation
You can access TIBCO documentation here:
http://docs.tibco.com
How to Contact TIBCO Support
For comments or problems with this manual or the software it addresses, contact
TIBCO Support as follows:
For an overview of TIBCO Support, and information about getting started
with TIBCO Support, visit this site:
http://www.tibco.com/services/support
If you already have a valid maintenance or support contract, visit this site:
https://support.tibco.com
Entry to this site requires a user name and password. If you do not have a user
name, you can request one.
TIBCO MDM Web Services Guide
xvi
|
Connecting with TIBCO Resources
TIBCO MDM Web Services Guide
|
1
Chapter 1 Overview
This chapter introduces you to the web services in TIBCO MDM.
Topics
Introduction, page 2
Web Service Message Structure, page 5
Accessing Web Services, page 10
Validation of XML, page 12
Including Namespace in Response, page 16
Design Principles, page 17
Authentication, page 18
Faults, page 26
Password Encryption and Decryption, page 33
Session Handling, page 35
Web Services Available in TIBCO MDM, page 39
Web Services Accepting Multiple Entities, page 44
TIBCO MDM Web Services Guide
2
|
Chapter 1 Overview
Introduction
Web services are self-contained modular applications that can be published,
located, and invoked across the Web. Web services perform functions, which can
be anything from simple requests to complicated business processes. Once a web
service is deployed, other applications (and also other web services) can discover
and invoke the deployed service.
Working of Web Services in TIBCO MDM
All web services in TIBCO MDM work on the request-response paradigm. Two
parties can conduct electronic business by exchanging business documents. The
sending party (Sender) packages one or more documents into a request XML
message which is then sent to the receiving party (Receiver). The Receiver
processes the message contents, generates a response XML, which is returned to
the Sender that originated the request. The Sender is informed of the status
(successful or otherwise) of the request message delivery.
Examples of the Sender's documents could be purchase order requests,
manufacturing information, and patient health care information. Examples of the
Receiver's responses include order confirmations, change control information,
and contractual acknowledgements.
Execution Mode
A web service in TIBCO MDM can be executed in the Synchronous or
Asynchronous mode. The web services that support these execution modes are
Record Add, Record Modify, Delete Record, Initiate Workflow, and Close Work
Item.
Synchronous Mode (SYNCHR)
With synchronous services, the client invokes a service and then waits for a
response to the request.
In the Synchronous mode, when a record is saved for an action, a workflow start
event is generated and the workflow event is sent for processing without sending
the workflow event into JMS. The response waits for the workflow execution to
end. Workflow execution may end when workflow completes or suspends
waiting for a user input. Only after the workflow execution is completed, the
following is returned to the web service caller:
Response
ID of workflow event
TIBCO MDM Web Services Guide
Introduction
|
3
State of workflow event
Status of workflow event
Action of the last executed workflow activity
Figure 1 SYNCHR Execution Mode
Asynchronous Mode (ASYNCHR)
With asynchronous services, the client invokes a service but does not wait for the
completion of the workflow execution.
In TIBCO MDM, when a record is saved for an action, a workflow start event is
generated and the event is sent to JMS for processing. In the Asynchronous mode,
the response does not wait for the workflow execution to end. Before the
workflow execution ends (that is, immediately after the event is sent to JMS for
processing), the following is returned to the web service caller:
Response
Workflow event ID
By default, all web services which trigger a workflow are executed in the
asynchronous mode.
This is the default execution mode.
When a Business Process Rule is set, the response is returned to the web service
caller when the workflow is suspended and a work item is created.
TIBCO MDM Web Services Guide
4
|
Chapter 1 Overview
Figure 2 ASYNCHR Execution Mode
TIBCO MDM Web Services Guide
Web Service Message Structure
|
5
Web Service Message Structure
The message structure of the web services is based on the following two types:
Generic schema based
Strict schema based
Generic Schema Based Message Structure
The generic schema based message structure is used for the following web
services:
Record Services on page 47
Work Item Services on page 115
Text Search Service on page 178
The following elements are present in a web service request or response:
Table 2 Elements in a Web Service Request or Response
Element Description
<DataService>
The DataService element defines the boundary of a web service
request. It is the outermost element in the XML. A message can
contain one or more Transactions.
<Identity>
The Identity element identifies a user or system making the web
service call. The identity establishes the roles and permissions to be
used while performing the requested operations. If the identity
cannot be established from transport level headers (example: SOAP
headers), the application uses this section to build a user profile.
In scenarios, where a session can be maintained with the server
using cookies or other means, the Identity section is not necessary
for identification. In this case the server builds the profile using
cookies.
<Context>
The Context element specifies a list of context variables that define
the context of execution for the request. Some examples of context
variables are RECORD_ACTION, WORKITEMREFERENCE, CORRELATIONID,
and so on.
TIBCO MDM Web Services Guide
6
|
Chapter 1 Overview
Common Sections
Some sections that are common across many Record and Work Item web services
are:
<Transaction>
The Transaction element denotes the boundaries of a unit of work.
All operations ('Commands') are executed under a common context.
However, database transaction semantics, in particular bulk rollback,
are not supported.
<Command type="Query">
</Command>
The type attribute of the Command element describes the type of
operation being performed on an object. The allowed types, for
example, are Query, Validate, Add and Modify. Each
Command can contain one or more Entities. All entities included
in a command have to be of the same type (example
MasterCatalogRecord).
<MasterCatalogRecord
etype="Entity"
commandqualifier="Vali
dValues">
Business objects in the application are modeled as Entities. Examples
include MasterCatalogRecord and WorkItem.
<Result
severity="Error"
code="CAT-1292">
The <Result> element describes what error occurred. It is aimed,
primarily, at the human user who has to interpret why the message
failed.
Each <Result> element contains a severity attribute and a code.
Severities indicate if this is an Error, Warning or Info message.
The code is a TIBCO MDM internal code which can be used to track
the error.
The <ResultList> element can contain one or more <Result>
entries.
The <Description> element is a human readable description of the
error.
<TransactionResult
result="Completed">
<SuccessCount>2</Succe
ssCount>
The <TransactionResult> element captures the status of a
transaction to let the caller know if the command succeeded or failed.
A Success here does not translate into the successful completion of
the Command. However, a failure here does mean the Command
was aborted. The <TransactionResult> element also captures
details such as EventID, EventState, Action, and so on.
Table 2 Elements in a Web Service Request or Response
Element Description
TIBCO MDM Web Services Guide
Web Service Message Structure
|
7
ResultList
The <ResultList> element captures the results of the web service. A ResultList
contains one or more errors, warnings or informational messages. The
<ResultList> element can contain one or more <Result> entries. For example:
<ResultList highestSeverity="Error" reference="UOM">
<Result severity="Error" code="CAT-1292">
<Description lang="en">The UOM is not a valid
value</Description>
</Result>
<Result severity="Error" code="CAT-1293">
<Description lang="en">The UOM has to be a
decimal</Description>
</Result>
</ResultList>
In the above example, the attribute UOM has 2 errors. Each Result in the
ResultList has a code, severity and description.
Code is the error code associated with the error.
Severity can be Error, Info or Warning.
Description provides the user a readable description of the error.
TransactionResult
The <TransactionResult> element captures the status of a transaction to let the
caller know if the command succeeded or failed.
SuccessCount SuccessCount indicates the number of records successfully
processed.
TotalCount TotalCount indicates the total number of records that met the
search criteria of the request. This is useful since the user gets only a subset of
the actual result set.
A Success here does not translate into the successful completion of the
command. However, a failure here does mean that the command was aborted.
The <TransactionResult> element also captures details such as EventID,
EventState, Action, and so on.
<TransactionResult result="Completed">
<SuccessCount>1</SuccessCount>
<TotalCount>1</TotalCount>
</TransactionResult>
The following is a sample of the TransactionResult when the execmode is set to
SYNCHR.
If the workflow is again suspended in another step, that is, another work item:
<TransactionResult result="Completed">
<SuccessCount>1</SuccessCount>
TIBCO MDM Web Services Guide
8
|
Chapter 1 Overview
<EventID>115018</EventID>
<EventStatus>
<Code>INPROGRESS</Code>
<Description lang="en">In Progress</Description>
</EventStatus>
<EventState>
<Code>PRODUCTADDINTERNALAPPROVAL</Code>
<Description lang="en">Internal Approval</Description>
</EventState>
<Action>InternalEditWorkItem</Action>
</TransactionResult>
If the workflow completes:
<TransactionResult result="Completed">
<SuccessCount>1</SuccessCount>
<EventID>521859</EventID>
<EventStatus>
<Code>SUCCESS</Code>
<Description lang="en">Success</Description>
</EventStatus>
<EventState>
<Code>DONE</Code>
<Description lang="en">Done</Description>
</EventState>
<Action>SetStatusToSuccess</Action>
</TransactionResult>
Comment History
The result also contains the comment history within the workflow, of which the
work item is a part. The comment history is represented as an array of comments
(marray).
Work Item Locking
For more information, refer to Work Item Lock Service, on page 128.
Strict Schema Based Message Structure
This message structure is strictly schema compliant. You can easily comprehend
it. The strict schema based message structure is used for the following web
services:
Administration Services on page 149
Data Services on page 177 except Text Search Service on page 178
Note that the Text Search web service has a specific structure suited to
searching records using search terms.
TIBCO MDM Web Services Guide
Web Service Message Structure
|
9
Get Content Service on page 232
Event Management Services on page 235
Samples
Sample request and response XML files are available in each folder specific to the
web service:
$MQ_HOME/schema/DataService/2.0/samples
TIBCO MDM Web Services Guide
10
|
Chapter 1 Overview
Accessing Web Services
The URL the web service request is sent to is called an endpoint address. It allows
the server to invoke the intended operation. The way in which a server finds the
service and the operation to be invoked is called dispatching. TIBCO MDM
supports two different ways to resolve a service and operation Endpoint
dispatching and SOAP Action dispatching. Releases prior to the current release
only supported SOAP action dispatching.
End point dispatching Append the operation name to the service URL. For
example, in the service URL
(http://<host>:<port>/eml/services/router), append the operation
name (RouteAction). The endpoint URL should be
http://<host>:<port>/eml/services/router/RouteAction.
SOAP action dispatching Use the endpoint URL of a service to address the
service. Use the SOAP Action for identifying an operation.
This release of TIBCO MDM supports SOAP actions from version 2.0 of the
schema.
Endpoint Dispatching
Table 3 Endpoint Dispatching
Service Endpoint URL Description
Data Service
http://<host>:<port>/eml/services/
router/RouteAction
For requests wrapped in a
Payload.
http://<host>:<port>/eml/services/
router/MasterCatalogRecordAction
For requests accessing master
data.
http://<host>:<port>/eml/services/
router/WorkitemAction
For requests accessing work
item functionality.
Text Search
Service
http://<host>:<port>/eml/services/
DataService/textSearchAction
For text search requests.
TIBCO MDM Web Services Guide
Accessing Web Services
|
11
SOAP Action Dispatching
SOAP Action dispatching is mainly used for schema version 1.5.
Table 4 SOAP Action Dispatching
Service Endpoint URL SOAP Action Description
Data
Service
http://<host>:<port>/
eml/services/router
RouteAction For requests wrapped in
Payload (current release).
http://<host>:<port>/
eml/services/router
http://www.tibco.com/ci
m/dataservice/2.0/wsdl/
routeaction
For requests wrapped in
Payload (releases prior to
current release).
http://<host>:<port>/
eml/services/router
MasterCatalogRecordAction For requests accessing
master data (current
release).
http://<host>:<port>/
eml/services/router
http://www.tibco.com/ci
m/dataservice/2.0/wsdl/
mastercatalogrecordacti
on
For requests accessing
master data (releases prior
to current release).
http://<host>:<port>/
eml/services/router
WorkitemAction For requests accessing work
item functionality (current
release).
http://<host>:<port>/
eml/services/router
http://www.tibco.com/ci
m/dataservice/2.0/wsdl/
workitemaction
For requests accessing work
item functionality (releases
prior to current release).
Text
Search
Service
http://<host>:<port>/
eml/services/DataServ
ice
textSearchAction For text search requests
(current release).
TIBCO MDM Web Services Guide
12
|
Chapter 1 Overview
Validation of XML
By default, an incoming request XML is not validated against any XML schema
(XSD file). However, you can enable the validation using the Configurator
(Miscellaneous > Web Service Request Validation).
When validation is enabled, TIBCO MDM validates every request XML instance
for the following:
Namespace and Schema Reference Ensures that the XML instance has used
the correct namespace and schema reference.
Inclusion of xsi:type When EntityData elements are used, TIBCO MDM
checks with the schema to see whether a specific type should be used by using
xsi:type.
After the validation, TIBCO MDM executes the request if there are no validation
errors. If validation is unsuccessful, validation errors are returned.
Validation of XML Instances
When validation is turned off (default):
The response XML instances have namespace and schema reference.
The output format of repository record attributes in the XML response of
repository record actions add, modify and validate.
When validation is turned on:
All the request XML instances contain namespace and schema reference.
All the response XML instances contain namespace and schema reference.
The responses for repository Add and Modify command types are returned
in an attribute form and not the element form.
Namespace and Schema Reference
TIBCO MDM supports validation XML instances using namespaces. The
namespaces allow for scoping of the XML elements so that name collisions do not
occur when an application uses XML instances from multiple sources.
Validation adds performance overhead and needs to be analyzed before enabling
it.
TIBCO MDM Web Services Guide
Validation of XML
|
13
Inclusion of xsi:type
The XML schema design uses inheritance with extension model via
xs:extension to add more elements or restrict the domain of values for schema
components. Following this design, the EntityData element used in request and
response XML documents must use the correct xsi:type in the XML request and
response documents. The EntityData is a base type and the XML instance will
contain specific types depending on the context. The implementation of web
services is modified to include the xsi:type whenever a specific type needs to be
present in the instance.
Service Methods
TIBCO MDM supports validation of request XML for the following service
methods:
MasterCatalogRecordAction
RouteAction
WorkItemAction
The schemas published for these web service methods use a specific namespace
for each of the service method's request and responses. The following namespaces
and corresponding schemas are used for validation of various requests and
responses.
The schema for web services is available at $MQ_HOME/schema/DataService/2.0.
For a list of other web services available, refer to Web Services Available in TIBCO
MDM, page 39.
MasterCatalogRecordAction
This service method is used to invoke catalog record related functionality such as
add, modify, validate, and so on. The request and response XML instances for this
service method must be well-formed and compliant with their corresponding
schemas:
Request MasterCatalogRecord_Action_Request.xsd
Response MasterCatalogRecord_Action_Response.xsd
RouteAction
This service method is used to invoke both catalog related functions and work
item related functions. The argument to this service method is passed as a CDATA
block under the payload element (Payload.xsd).
Payload Request Payload.xsd
TIBCO MDM Web Services Guide
14
|
Chapter 1 Overview
Payload Response Payload.xsd
Encapsulating payload in CDATA block offers slightly higher performance as the
payload is not parsed by the transport layers. The contents of the payload type
attribute indicate whether the request is for catalog record action or work item
action. The response XML instance is also encapsulated in payload element.
WorkItemAction
This service method is used to invoke the work item related functions such as
query work item, close work item, and so on. The request and response XML
instances for this service method must be well-formed and compliant with their
corresponding schemas:
Work Item Request Workitem_Action.xsd
The work item request schema supports the capturing of arbitrary user inputs.
It uses the FormResult element instead of the Accept element. Valid values are
Accept and Reject. Any other value passed is ignored and defaulted to
Accept.
When validation is turned on, the arbitrary input from the user application
must be passed within the CustomAttributes element as follows:
<FormResult etype="Attribute" type="string">Accept</FormResult
<CustomAttributes>
<raiseAlarm type="string">Alarm string</raiseAlarm>
<raiseAlarm1 type="string">Alarm string</raiseAlarm1>
<Decision etype="Attribute" type="string">val</Decision>
</CustomAttributes>
Table 5 Attributes of Payload.xsd
Attribute Description
type Determines the type of payload contents. The type can be either mastercatalog or
workitem. The default type is mastercatalog. Introducing the type attribute
makes it easier to identify a request as catalog-related or work-item related
without "looking" into the contents.
Since release 8.2.0 onwards, the FormResult parameter is deprecated, you are
recommended to use Close/Approve, Close/Reject or CloseAll/Approve, or
CloseAll/Reject.
TIBCO MDM Web Services Guide
Validation of XML
|
15
The following is the schema component that supports arbitrary user inputs.
<xs:complexType name="WorkItemCustAttrsType" mixed="true">
<xs:sequence>
<xs:any namespace="##any" processContents="skip" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
Work Item Response Workitem_Action.xsd
TIBCO MDM Web Services Guide
16
|
Chapter 1 Overview
Including Namespace in Response
You can control the addition of namespace in the response by setting the Include
of namespace property in Configurator. The default is true, that is, the namespace
is included in the response.
If the namespace is included, it can be customized by use of the Miscellaneous >
Webservice schema version property in Configurator. For example, this release of
TIBCO MDM contains the 2.0 version of the schema.
TIBCO MDM Web Services Guide
Design Principles
|
17
Design Principles
All web service calls work on the request-response paradigm. To achieve a
task, a user sends in a request XML, and the results of the request are sent
back in a response XML.
All web service calls are synchronous. A response is always sent, even if
processing of a request is delegated to the workflow.
Each web service request or call must be complete. Every time TIBCO MDM
receives a request, it expects all data necessary (for it to handle the request) to
be available in the request XML.
No state is maintained between web service calls. TIBCO MDM does not
enforce the order in which web service calls should be made. You can make
any web service call anytime.
Query and Validate messages do not change the state of the system. By
definition, Query messages are read only and do not change the state of the
system. This means, you can call the Query service on an entity any number
of times without causing the state of the system to change.
Add and Modify messages can change state of the system.
Add and Modify messages respect transactions. If a web service fails, all
activity pertaining to the request is rolled back. A web service request can
contain multiple transactions, which are independent of each other. For
example, if the first transaction is successfully executed and the second
transaction fails, there is no effect of the second transaction on the first.
TIBCO MDM Web Services Guide
18
|
Chapter 1 Overview
Authentication
Authentication for web services works as follows:
If a web service request is received from a client without specifying any
existing HTTP session the user is authenticated.
If a web service request specifies an existing session and if the session is not
already expired, the session is maintained and no authentication is done. In
this case, no password needs to be specified.
Following authentication mechanisms are supported:
Normal/Default mode: A password needs to be specified. The authentication
is done using the user ID and password. User can reside in either database or
LDAP. However, if a valid web service session ID is specified by appending
;jsessionid=<session id value> to the web service request URL,
authentication is skipped provided the specified HTTP session is valid.
If an HTTP session is present for an existing user, the user ID is also specified
in the web service request, and if the user ID does not match with the session
owner; user ID in the web service request takes precedence and the user is
re-authenticated into TIBCO MDM. The HTTP session is invalidated later on.
Single Sign-On (SSO) mode: Single sign-on is a mechanism whereby a single
initial action of user authentication and authorization allows you to access
subsequent multiple web services for which you are authorized, without the
need to specify password for all such subsequent requests. All TIBCO MDM
web services are SSO-enabled.
TIBCO MDM supports variations of single sign-on. For example, Site
Minder/Transaction Minder (SM) and SAML2.0. For the purpose of trust
verification and validating user data, TIBCO MDM relies on the information
or attributes set in the SOAP headers. This helps in establishing the trust and
confirming that request has received from a reliable or trusted source and user
is pre-authenticated. Role information for the user is also extracted from these
headers. If user does not exist in TIBCO MDM, it is created. If the user data
relevant for TIBCO MDM changes over subsequent web service requests, it
gets updated in the application. TIBCO MDM does not store user password in
this mode.
TIBCO MDM Web Services Guide
Authentication
|
19
The authentication of the user name is controlled by the User name case
sensitivity property that is specified in Configurator (InitialConfig >
Miscellaneous). By default, the value is true.
Using Secure Socket Layer (SSL) with Web Services
TIBCO MDM uses AXIS2 as a provider of web services. To serve the web service
requests over https; AXIS2 needs to be configured to receive messages on HTTPS
transport. Hence, the end point reference or URLs starting with https:// can be
served. This requires configuring transportReceiver for https in axis2.xml.
The following section needs to be uncommented and configured in axis2.xml.
This file is provided in $MQ_HOME/ECM.ear/EML.war/WEB-INF/conf directory.
<!-- the non blocking https transport based on HttpCore + SSL-NIO
extensions
<transportReceiver name="https"
class="org.apache.axis2.transport.nhttp.HttpCoreNIOSSLListener">
<parameter name="port" locked="false">9002</parameter>
<parameter name="non-blocking" locked="false">true</parameter>
<parameter name="keystore" locked="false">
<KeyStore>
<Location>identity.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
<KeyPassword>password</KeyPassword>
</KeyStore>
</parameter>
<parameter name="truststore" locked="false">
<TrustStore>
<Location>trust.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
</TrustStore>
</parameter>-->
<!--<parameter name="SSLVerifyClient">require</parameter>
supports optional|require or defaults to none -->
Tivoli Access Manager (TAM) does not support web services single sign-on.
However, it can be customized to secure web service requests, and TIBCO MDM
can work with that through the same model of establishing trust through header
information. TIBCO MDM does not support TAM based single sign-on out of the
box.
TIBCO MDM Web Services Guide
20
|
Chapter 1 Overview
<!--</transportReceiver>-->
This does not support client certification authentication, that is, it is one way SSL.
The new web services such as Administrator, Data, Content, and Event
Management web services require various types of authentication. The
subsequent sections provide the detailed information on authentication for each
of these web services.
Administrator Web Services, page 20
Data Web Services, page 22
DataLoad Web Services, page 23
Content Web Services, page 23
Event Management Web Services, page 25
Administrator Web Services
The following table lists authentication required for Administrator web services:
Table 6 Authentication of Administrator Web Services
Web Service
Name
Menu Privilege
Function
Privilege
Role Privilege
Resource Access
Permission
Login NA NA Any NA
Logout NA NA Any NA
Get
Entitlement
NA Allow view
entitlement
Administrator NA
Create
Enterprise
Administration >
All Company
Profiles
adminmenu_
company
Super User Create Company
Profile
Get Enterprise
List
Administrator > All
Company Profiles
adminmenu_
company
Super User,
Administrator,
and Work
Supervisor
Get All Company
Profiles
Create User Administration >
User Accounts
adminmenu_
member
Super User,
Administrator,
and Work
Supervisor
Create User
TIBCO MDM Web Services Guide
Authentication
|
21
Modify User Administration >
User Accounts
adminmenu_
member
Super User,
Administrator,
and Work
Supervisor
Modify user
Change
Password
Administration >
User Accounts
adminmenu_
member
Super User,
Administrator,
and Work
Supervisor
Change Password
Delete User Administration >
User Accounts
adminmenu_
member
Super User,
Administrator,
and Work
Supervisor
Delete user
Get User List Administration >
User Accounts
adminmenu_
member
Super User,
Administrator,
and Work
Supervisor
Get User
Get Role List Administration >
Roles
adminmenu_
roles
Super User,
Administrator,
and Work
Supervisor
Get Role
Table 6 Authentication of Administrator Web Services
Web Service
Name
Menu Privilege
Function
Privilege
Role Privilege
Resource Access
Permission
TIBCO MDM Web Services Guide
22
|
Chapter 1 Overview
Data Web Services
The following table lists authentication required for Data web services:
Table 7 Authentication of Data Web Services
Web Service
Name
Menu Privilege
Function
Privilege
Role Privilege
Resource Access
Permission
Text Search Browse and Search catalogmenu_c
atalog_search
Super User,
Administrator,
Work
Supervisor,
Repository
Manager,
Repository
Editor,
Repository
Approver and
Data Steward
Text Search
Get
DataSource
List
Master Data > Data
Sources
catalogmenu_
data_source
Any NA
Get Repository
List
Master Data >
Repositories
catalogmenu_
master_catalog
Super User,
Administrator,
Work
Supervisor,
Repository
Manager, and
Data Steward
List
Initiate
Synchronizatio
n
Master Data >
Syncronization
profiles
catalogmenu_c
atalog_edition
Super User,
Administrator,
Work
Supervisor,
Repository
Manager, Data
Steward
Synchronize
Records
Upload
Metadata
System Operations sysopmenu Super User and
Administrator
NA
Extract Data NA NA Super User and
Administrator
NA
TIBCO MDM Web Services Guide
Authentication
|
23
DataLoad Web Services
The following table lists authentication required for DataLoad web services:
Content Web Services
The following table lists authentication required for Content web service:
Table 8 Authentication of DataLoad Web Services
Web Service
Name
Menu Privilege
Function
Privilege
Role Privilege
Resource Access
Permission
Get
DataSource
Info
Master Data > Data
Sources
catalogmenu_
data_source
Any NA
Upload
DataSource
Master Data > Data
Sources
catalogmenu_
data_source
Any NA
ImportRecords Master Data >
Repositories >
Manage Input
Maps
catalogmenu_
master_catalog
Super User,
Administrator,
Work
Supervisor,
Repository
Manager, Data
Steward, and
Support
Engineer
Import Records
LoadImportRe
cords
Master Data >
Repositories >
Manage Input Map
catalogmenu_
master_catalog
Super User,
Administrator,
Work
Supervisor,
Repository
Manager, Data
Steward, and
Support
Engineer
Import Records
TIBCO MDM Web Services Guide
24
|
Chapter 1 Overview
Table 9 Authentication of Content Web Services
Web Service
Name
Menu Privilege
Function
Privilege
Role Privilege
Resource Access
Permission
Get Content Event Log adminmenu_
event_log
Administrator,
Super User
Event -> Resource
Access All
TIBCO MDM Web Services Guide
Authentication
|
25
Event Management Web Services
The following table lists authentication required for Event Management web
services:
Table 10 Authentication of Event Management Web Services
Web Service
Name
Menu Privilege
Function
Privilege
Role Privilege
Resource Access
Permission
Get Event Info Event Log adminmenu_
event_log
Administrator,
Super User
Event -> Resource
Access All
Get Event
Details
Event Log adminmenu_
event_log
Administrator,
Super User
Event -> Resource
Access All
Get Import
Event Status
Event Log adminmenu_
event_log
adminmenu_e
vent_log
Event -> Resource
Access All
TIBCO MDM Web Services Guide
26
|
Chapter 1 Overview
Faults
If you do not specify an adequate information in the request, the web services
return various fault messages. The following sections list the generic fault
messages that are returned in the response. However, for detailed information on
various types of error messages, refer to Appendix E - Error Codes in the TIBCO
MDM System Administrators Guide.
Administrator Web Services, page 26
Data Web Services, page 28
DataLoad Web Services, page 29
Content Web Services, page 31
Event Management Web Services, page 32
Administrator Web Services
The following table lists the faults of Administrator web services:
Table 11 Faults of Administrator Web Services
Web Service Name Faults
Login If the specified credentials are wrong, Authentication failed for user
<Parameter name='USER'> and company <Parameter
name='ENTERPRISE'> message is returned.
Logout If you get any errors while logging out, Error during logout. Invalid
or expired session message is returned.
Get Entitlement If user does not have privilege, User '<user name>' does not have
permission to view entitlement message is returned.
Create Enterprise If user does not have privilege, User <USERNAME> not authorized
to Create Enterprise message is returned.
Get Enterprise List If other than Administrator and Super User invokes this web service,
the authentication failure message is returned.
Create User If user does not have privilege, User <USERNAME> not authorized
to Create User message is returned.
TIBCO MDM Web Services Guide
Faults
|
27
Modify User If you specify wrong values for the attributes in the request.xml file,
an error message is returned. For example,
Wrong parameters specified in the <UserInfo> tag, Invalid
company <companyname> message is returned.
User credentials specified in the <UserInfo> tag other than
administrator and work supervisor, User <username> not
authorized to Modify User message is returned.
If the specified user name does not exist, User not defined
message is returned.
If wrong enterprise name is specified in the
<ModifyUserDetails> tag, the Cannot find specified company
<companyname> message is returned.
Mismatch combination in the <LocaleSettings> tag, the Locale
<languagename> is not supported message is returned.
If username is not specified, Enterprise cannot be specified if
user is not specified message is returned.
If first name is not specified, First Name mandatory. Provide
First Name message is returned.
If first name is modified more than 80 characters, Length of First
Name more than maximum allowed length 80 message is
returned.
If last name is modified more than 80 characters, Length of Last
Name more than maximum allowed length 80 message is
returned.
If middle name is modified more than 80 characters, Length of
MiddleName more than maximum allowed length 80 message
is returned.
If password is modified more than 30 characters, Length of
Password more than maximum allowed length 30 message is
returned.
Change Password If you do not specify a password in the request.xml file, the Password
should not be null or blank message is returned.
Delete User If user does not have pr i vi ledge, User <USERNAME> not
authorized to Delete User message is returned.
Table 11 Faults of Administrator Web Services
Web Service Name Faults
TIBCO MDM Web Services Guide
28
|
Chapter 1 Overview
Data Web Services
The following table lists the faults of Data web services:
Get User List If the user list is not available, No Users exist message is returned.
Get Role List If the role list is not available, No Roles exist message is returned.
Table 11 Faults of Administrator Web Services
Web Service Name Faults
Table 12 Faults of Data Web Services
Web Service Name Faults
Text Search Various validation messages are returned. For more information,
refer to the Appendix E - Error Codes in the TIBCO MDM System
Administrators Guide.
Get DataSource List If the data source does not exist, the CimFaultException error is
returned.
Get Repository List If the repository list is not available in the specified enterprise, No
Repository Found message is returned.
Initiate Synchronization If the Synchronization profile or the repository does not exist,
Repository or output map with name or ID <Parameter
name='NAME'> does not exist; may have been already deleted by
another user message is returned in the response.
Upload Metadata If user does not have privilege, User <USERNAME> not
authorized to Upload Metadata message is returned.
Extract Data If the class name is not provided, <IDataProvider/IDataProcessor>
class name is mandatory. Please provide class name message is
returned.
TIBCO MDM Web Services Guide
Faults
|
29
DataLoad Web Services
The following table lists the faults of DataLoad web services:
GetClassificationSchemeList If the repository list is not available in the specified enterprise,
Repository <name> not found for organization <ID> message is
returned.
If the start count and total count for the pagination is not available
in the specified enterprise, Invalid Return Count message is
returned.
If the classification scheme name is not available in the specified
enterprise, classification scheme <Name> could not be loaded
message is returned.
GetClassificationSchemeAttr
ibuteList
If the classification scheme name is not available in the specified
enterprise, classification scheme <Name> could not be loaded
message is returned.
GetClassificationCodeHierar
chy
If the classification code is not available in the specified enterprise,
scheme code not found message is returned.
If invalid hierarchy of code, invalid code or invalid classification
name is specified for an enterprise, Invalid code,level or hierarchy
specified in request message is returned.
If the classification scheme name is not available in the specified
enterprise, classification scheme <Name> could not be loaded
message is returned.
Table 12 Faults of Data Web Services
Web Service Name Faults
Table 13 Faults of DataLoad Web Services
Web Service Name Faults
Get DataSource Info If data source name is not specified, the Data source name is
mandatory. Provide the data source name error is returned.
If the data source does not exist or invalid, Invalid data source
name error is returned.
TIBCO MDM Web Services Guide
30
|
Chapter 1 Overview
Upload DataSource If the specified data source name is incorrect, Invalid data source
name error is returned.
If the specified enterprise name is incorrect, Invalid company
<company_name> error is returned.
If the specified password is incorrect, Cannnot authenticate
credentials with user name user_name, domain domain_name
error is returned.
If the specified user name is incorrect, User user_name does not
exist error is returned.
If you do not specify any value for the <DatasourceName>
parameter, Data source name is mandatory. Provide the data
source name error is returned.
If you do not specify any value for the <FileName> parameter, Data
source format is not SQL. Filename is mandatory error is
returned.
ImportRecords If you select DatabaseLoader as the Import approval option with
Synchronous execution mode, DBLoader doesnt support for
synch execution mode error is returned.
If you do not specify any value for the execmode attribute, Invalid
execution mode excutionmodename. Supported execution modes:
ASYNCHR or SYNCHR error is returned.
If you specify non-existing value for the InputMapName parameter,
Invalid parameter inputmapname specified error is returned.
If you specify non-existing value for the Repository parameter,
Repository or output map with name or ID repositoryname does
not exist; may have been already deleted by another user error is
returned.
If the specified enterprise name is incorrect, Invalid company
<company_name> error is returned.
If the specified user name is incorrect, User user_name does not
exist error is returned.
If the specified password is incorrect, Cannnot authenticate
credentials with user name user_name, domain domain_name
error is returned.
Table 13 Faults of DataLoad Web Services
Web Service Name Faults
TIBCO MDM Web Services Guide
Faults
|
31
Content Web Services
The following table lists the faults of Content web services:
LoadImportRecords If you do not specify any value for the Repository parameter,
Repository name is mandatory, provide repository name error is
returned.
If you do not specify any value for the InputMapName parameter,
Input map is mandatory, provide input map name error is
returned.
If you specify non-existing value for the InputMapName parameter,
Invalid parameter inputmapname specified error is returned.
If you specify non-existing value for the Repository parameter,
Repository or output map with name or ID repositoryname does
not exist; may have been already deleted by another user error is
returned.
If you upload an invalid file, the File Format not supported error is
returned.
If you do not specify any value for the <BinaryData> parameter,
Cannot upload specified file 'VALUE'; invalid file name or file
does not exist or is empty error is returned.
If you do not specify any value for the <FileName> parameter, Data
source format is not SQL. Filename is mandatory error is
returned.
If you select DatabaseLoader as the Import approval option with
the Synchronous execution mode, DBLoader doesnt support for
synch execution mode error is returned.
Table 13 Faults of DataLoad Web Services
Web Service Name Faults
Table 14 Faults of Content Web Services
Web Service
Name
Faults
Get Content If the specified DocumentId or DocumentPath for a file does
not exist or the user does not have "View Event" permissions,
Could not find document with primary key id <id> or Not
authorized to view event details message is returned.
TIBCO MDM Web Services Guide
32
|
Chapter 1 Overview
Event Management Web Services
The following table lists the faults of Event Management web services:
Table 15 Faults of Event Management Web Services
Web Service Name Menu Privilege
Get Event Info The following messages are returned in response:
Not authorized to view event details.
Event not yet started.
Event does not exist or executed in memory; no other details
available.
Get Event Details If the event ID is not found, Event does not exist or executed in
memory; no other details available message is returned.
Get Import Event Status The following messages are returned in response:
If the specified enterprise name is incorrect, Invalid company
<company_name> error is returned.
If the specified password is incorrect, Cannnot authenticate
credentials with user name <user_name>, domain
<domain_name> error is returned.
If the specified user name is incorrect, User user_name does
not exist error is returned.
If an Event ID is incorrect then Event does not exist or executed
in memory; no other details available error is returned.
TIBCO MDM Web Services Guide
Password Encryption and Decryption
|
33
Password Encryption and Decryption
The Password input is required across all web services and majorly in
Administrator web services. You can encrypt any text password using the
passwordEncryptDecryptTool.sh or passwordEncryptDecryptTool.bat tool
located in $MQ_HOME/bin.
The scripts accept a text string and return an encrypted string value or accept an
already encrypted string value and return a text value. You can generate an
encrypted string using the tool and then use it in the web service request.
Prerequisite
Ensure that all environment variables used in TIBCO MDM are set properly
before executing the script, such as MQ_HOME, MQ_COMMON_DIR, MQ_CONFIG_FILE,
NODE_ID, WAS_HOME, JBOSS_HOME, and so on.
To encrypt the password:
1. Go to the command prompt; go to the $MQ_HOME/bin folder.
2. Type passwordEncryptDecryptTool.bat "<password>"and press ENTER.
For example,
D:\work\venus_dest\bin>passwordEncryptDecryptTool.bat
"tibco123"
TIBCO MDM Web Services Guide
34
|
Chapter 1 Overview
The utility provides information about the accessed property file and loaded
properties, and then displays the encrypted password.
For example, the encrypted password for tibco123 is cfMrxokzKTm3zJJLpDW7Jg==.
3. Place the encrypted password in <ns:Password></ns:Password> tag of the
web service request. For example,
<ns:Password>cfMrxokzKTm3zJJLpDW7Jg==</ns:Password>
To decrypt the password:
Use the similar encryption procedure to decrypt the password. Place the
encrypted string in the command prompt instead of the text password. For
example, $MQ_HOME/bin>passwordEncryptDecryptTool.bat
"cfMrxokzKTm3zJJLpDW7Jg==". After entering the encrypted string as input, the
utility returns the original decrypted password. In this case, tibco123.
Encryption and decryption tool is also supported through a Java API so that it can
be embedded.
Usage is as follows:
import com.tibco.mdm.infrastructure.encryption.EncrypterDecryptorUtil;
...
...
EncrypterDecryptorUtil cipher = EncrypterDecryptorUtil.getCipher();
cipher.encrypt(<pwdStringInPlainText>);
OR
cipger.decrypt(<EncryptedPwdValue>);
You must specify double quotes for the text password or encrypted password,
else the utility does not perform encryption or decryption.
TIBCO MDM Web Services Guide
Session Handling
|
35
Session Handling
TIBCO MDM web services allow the SOAP client (web client, BW-client) to
maintain a session between web service calls, so the client need not provide the
user credentials in subsequent requests called.
The following table illustrates various scenarios involved in a web service session
management behavior in TIBCO MDM.
Table 16 UI Browser Web Client
WS
request
launched
within
running
TIBCO
MDM
URL
Writing
Cookie
enable
User
Informatio
n Provided
Session
exists
Description
Y N Y Y Y (Existing
session is
used, that is,
the one
created by
the TIBCO
MDM UI)
Username from 'userInfo' section
of the web service request is
checked with profile name. No
new session is created.
Y N Y N Y (Existing
session is
used, that is,
the one
created by
the TIBCO
MDM UI)
No new session is created. The
existing session is used.
Y Y N N Y (Existing
session is
used, that is,
the one
created by
the TIBCO
MDM UI)
No new session is created, but
the web service session ID needs
to be passed to the GI based web
service client which appends the
jsessionid=<> to the endpoint
URL.
Note: Currently, the passing of
sessionId to GI Application is not
supported.
TIBCO MDM Web Services Guide
36
|
Chapter 1 Overview
N (Launched
in a different
browser
window)
N Y N Y (Existing
session is
used, that is,
the one
created by
the TIBCO
MDM UI)
No new session is created;
existing session is used.
Note: The login service should
be invoked first.
N (Launched
in a different
browser
window)
N Y Y Y (Existing
session
created
using the
Login
service is
used)
Username from 'userInfo' section
of the web service request is
checked with profile name. No
new session is created.
N (Launched
in a different
browser
window)
Y N N Y (Existing
session
created
using the
Login
service is
used)
No new session is created, but as
cookies are not enabled
jsessionid=<> needs to be
appended to the endpoint URL.
N (Launched
in a different
browser
window)
Y N N N Throws an exception stating user
does not exists.
N (Launched
in a different
browser
window)
Y N Y N The invocation is stateless, that
is, no new session is created if
any service apart from Login
service is invoked, even if the
session does not exists.
Table 16 UI Browser Web Client
WS
request
launched
within
running
TIBCO
MDM
URL
Writing
Cookie
enable
User
Informatio
n Provided
Session
exists
Description
TIBCO MDM Web Services Guide
Session Handling
|
37
TIBCO ActiveMatrix BusinessWorks
This section describes the case of a SOAP client based on TIBCO ActiveMatrix
Businessworks.
The user wants to maintain a session (Statefull) across multiple web service calls.
In this case, the user must invoke the Login service and BusinessWorks needs to
maintain the sessionId returned from Login service in global context and append
the jsessionid=<> to the endpoint URL.
Ensure that endpoint URL contains the appropriate SOAP Action. For
example,
For Login:
http://<servername>:<port>/eml/services/AdminService/loginAction
For Add Record:
http://<servername>:<port>/eml/services/router/MasterCatalogR
ecordAction;jsessionid=T2yJKLDPzSY4CjcbzpG
For WAS, ensure URL re-writing is enabled and the jsession ID is prefixed
with 0000. For example, <0000jsessionID> is appended to the endpoint
URL. For example,
For Add Record:
http://<servername>:<port>/eml/services/router/MasterCatalogR
ecordAction;jsessionid=0000T2yJKLDPzSY4CjcbzpG
For Logout:
http://<servername>:<port>/eml/services/AdminService/logoutA
ction;jsessionid=0000T2yJKLDPzSY4CjcbzpG
Prefixing 0000 with jsession ID is required because jsession ID cookie in WAS
contains cache ID, which is prefixed to the session ID. The retrieved session ID
in the response omits this cache ID, which is 0000 in most cases. Hence, you
must explicitly prefix 0000 to the session ID while using a SOAP client.
TIBCO MDM Web Services Guide
38
|
Chapter 1 Overview
The user credentials are provided at the time of login and for every subsequent
call the jsessionid token is passed. The BW-client provides an input area for the
SOAPRequestReply activity as shown in the following figure:
If the user does not want to maintain a session (Stateless), the user need not
invoke the Login service. However, you need to provide the userInfo in every
consecutive invocation of any service. If the userInfo is not provided, an error is
displayed.
TIBCO MDM Web Services Guide
Web Services Available in TIBCO MDM
|
39
Web Services Available in TIBCO MDM
In TIBCO MDM, web services are available for the following activities:
Table 17 Web Services Available in TIBCO MDM
Web Service
Type
Service Description
Details
Available on
Page
Record Services Record Query
Service
This web service can be used to query
one or more repository records.
page 44
Record Query
MetaData Service
This web service can be used for
obtaining repository record meta-data.
page 44
Record Query
ValidValues (Init)
Service
This web service provides a list of:
initial and valid values for all
attributes as defined by the
rulebase specified for the
repository.
access privileges configured for
attributes.
valid relationship types available
for a given record.
page 88
Record Validate
Service
This web service is used to validate the
attribute values of a record against the
validation rules defined in the system.
page 94
Record Add
Modify Services
This web service is used to add or
modify a repository record. This
service works on record bundles, and
can therefore take a list of records for
processing.
page 96
TIBCO MDM Web Services Guide
40
|
Chapter 1 Overview
Delete Record
Service
This web service is used to delete:
a repository record
related target records
both the repository record and
related target records.
a record or relationship targets with
reference to a work item
page 104
Initiate Workflow
Service
This web service is used to initiate a
user-defined workflow for given
record.
page 108
Table 17 Web Services Available in TIBCO MDM
Web Service
Type
Service Description
Details
Available on
Page
TIBCO MDM Web Services Guide
Web Services Available in TIBCO MDM
|
41
Work Item
Services
Work item Query
Parameters Service
This web service can be used to get a
list of query parameters supported by
the system and also provides a list of
valid values for each of the supported
parameters.
page 116
Work item Query
Service
This web service can be used to get a
list of query work items, based on the
list of query parameters specified.
page 118
Work item Modify
Close Service
This web service can be used to close a
list of work items.
page 124
Work item Lock
Service
This web service can be used to lock or
relock a work item.
page 128
Work item UnLock
Service
This web service can be used to unlock
a work item.
page 130
Get Work item
Service
This web service can be used to get the
following details of a work item:
Work item data
Work item lock details
Comment history
Primary and associated records.
For each record, operational data is
also included.
page 132
Work item
Reassign Service
This web service can be used to
reassign a work item to another user.
page 138
Table 17 Web Services Available in TIBCO MDM
Web Service
Type
Service Description
Details
Available on
Page
TIBCO MDM Web Services Guide
42
|
Chapter 1 Overview
Administrator
Services
Login Service This web service allows you to login to
TIBCO MDM after authenticating the
specified credentials.
page 150
Logout Service This web service allows you to logout
from the user session for the
maintained session. The session is
maintained either by URL re-writing
mechanism or through cookies.
page 151
Get Entitlement
Service
This web service allows you to retrieve
entitlement information for a specified
user. Entitlement information includes
user permissions, roles assigned, and
functions assigned to the user.
page 152
Create Enterprise
Service
This web service allows you to create
an enterprise in TIBCO MDM.
page 155
Create User
Service
This web service allows you to create a
user in an existing Enterprise.
page 159
Delete User
Service
This web service allows you to delete a
user in an existing Enterprise.
page 172
Get User List
Service
This web service allows you to get a list
of the currently logged-in users for an
enterprise.
page 174
Get Role List
Service
This web service allows you to get a list
of roles of the currently logged-in users
for an enterprise
page 176
Table 17 Web Services Available in TIBCO MDM
Web Service
Type
Service Description
Details
Available on
Page
TIBCO MDM Web Services Guide
Web Services Available in TIBCO MDM
|
43
Data Services Text Search Service The Text Search web service allows you
to search for human recognizable terms
in one or more TIBCO MDM
repositories as you would do on an
Internet Search Engine.
page 178
Get Repository
List Service
This service allows you to get a list of
repositories that can be accessed by the
currently logged-in user.
page 189
Initiate
Synchronization
Service
This service allows you to synchronize
records on a Trading Partner. This
service operates in two modes, Async
and Sync.
page 195
Upload Metadata
Service
This service allows you to upload
metadata (jar or xml file) to TIBCO
MDM.
page 197
Extract Data
Service
This service allows you to extract data
from TIBCO MDM using custom
implementation.
page 199
Content Services Get Content
Service
This service allows you to download a
file for the specified context. This
service takes DocumentId or
DocumentPath as input, also the
context from where the file needs to
download is specified. If the context is
accessible for the user only then the file
is downloaded.
page 232
Event
Management
Services
Get Event Service This service allows you to get event
information for a specified event ID.
page 236
Get Event Details
Service
This service allows you to retrieve the
event details for the specified Event ID.
page 238
Table 17 Web Services Available in TIBCO MDM
Web Service
Type
Service Description
Details
Available on
Page
TIBCO MDM Web Services Guide
44
|
Chapter 1 Overview
Web Services Accepting Multiple Entities
A TIBCO MDM web service requests top-level business objects as Entities.
MasterCatalogRecord and WorkItem are the examples of an entity. These
examples represent in a web service as <MasterCatalogRecord
etype="Entity"> or <Workitem etype="Entity"> in the <Command> element.
Most of the web services can work only on one unique business object or an entity.
However, some web services can work on more than one such business object or
an entity as a part of a single web service request.
The following table lists if a web service supports multiple business objects or
entities.
Table 18 Web Services Accepting Multiple Entities
Web Service Name Does it accept multiple entities?
Record Services
Record Query Service No
Record Query MetaData Service No
Record Query ValidValues (Init) Service No
Record Validate Service Yes
Record-Add Modify Services Yes (with two transactions in one
request)
Delete Record Service Yes
Initiate Workflow Service Yes
Work Item Services
Work Item Query Parameters Service No
Work Item Query Service No
Work Item Modify Close Service Yes
Work Item Lock Service Yes
Work Item UnLock Service Yes
TIBCO MDM Web Services Guide
Web Services Accepting Multiple Entities
|
45
Work Item Get Service Yes
Work Item Reassign Service Yes (with two transactions in one
request)
Get Custom Work Item Summary Service No
Get Predefined Work Item Summary
Service
No
Administration Services
Login Service No
Logout Service No
Get Entitlement Service No
Create Enterprise Service No
Get Enterprise List Service No
Create User Service No
Delete User Service No
Get User List Service No
Get Role List Service No
Data Services
Text Search Service No
Get Repository List Service No
Initiate Synchronization Service No
Get Data Source List Service No
Upload Metadata Service No
Extract Data Service No
Content Services
Table 18 Web Services Accepting Multiple Entities
Web Service Name Does it accept multiple entities?
TIBCO MDM Web Services Guide
46
|
Chapter 1 Overview
An example of a web service accepting multiple entities is Work Item Reassign
web service. A sample request is as below:
<!-- multiple entities in one transaction is not supported for
Reassign. Specify one entity per transaction. -->
<!-- multiple transactions are supported -->
<Transaction>
<Command type="Reassign">
<Workitem etype="Entity">
<ExternalKeys>
<Key name="WORKITEMREFERENCE"
type="string">45010</Key>
<Key name="USER" type="string">del</Key>
</ExternalKeys>
</Workitem>
</Command>
</Transaction>
<Transaction>
<Command type="Reassign">
<Workitem etype="Entity">
<ExternalKeys>
<Key name="WORKITEMREFERENCE"
type="string">43010</Key>
<!-- delegation is set so that workitems will be delegated
to 2 users -->
<Key name="USER" type="string">sup</Key>
</ExternalKeys>
</Workitem>
</Command>
</Transaction>
Content Service No
Event Management Services
Get Event Info Service No
Get Event Details Service No
Table 18 Web Services Accepting Multiple Entities
Web Service Name Does it accept multiple entities?
TIBCO MDM Web Services Guide
|
47
Chapter 2 Record Services
This chapter describes the usage and customization of Record services.
Topics
CRUD Services for Record Services on page 48
Record Query Service, page 61
Record Query Metadata Service, page 84
Record Query ValidValues (Init) Service, page 88
Record Validate Service, page 94
Record Add or Modify Services, page 96
Record Delete Service, page 104
Initiate Workflow Service, page 108
Transaction Atomicity for Record Web Services, page 111
TIBCO MDM Web Services Guide
48
|
Chapter 2 Record Services
CRUD Services for Record Services
This section describes the operation and features of WSDL Generator Plug-in. The
WSDL Generator Plugin accepts a repository file as an input, and generates an
output WSDL and corresponding Java source code. The code is then compiled to
a deployable web services entity (.aar) file.
Figure 3 WSDL Generator Plugin Process
TIBCO MDM Web Services Guide
CRUD Services for Record Services
|
49
The generation is offered through Wizard, which is provided as a 'New Project'
wizard in the repository designer. The WSDL generation wizard collects the
following inputs from the user:
Source code (Java) package name
The user selected Repository
Output Project name
The WSDL should have the following properties:
Use a single namespace for request and response
Use the document literal flavor
Use a SOAP fault for conditions
The schema should have the following properties:
Define XSD types for each attribute
Use a close mapping of XML Schema base types to TIBCO MDM base types
Account for further type restrictions such as length
Support multi-value attributes
Repositories with FED attributes
The implementation for performing CRUD operations on repositories with a
timestamp type attribute mapped to the EFFECTIVEDATE attribute is as follows:
Add operation: You can add any record including future effective date records
to a repository.
Update and Delete operations: You can update and delete all records
including future effective date records.
Find operation: You can search only those records which are confirmed and
already effective. For the successful Find operation, value of the
EFFECTIVEDATE attribute should be less than the current system date.
Generating WSDL
Using the eclipse wizard, you can generate the WSDL.
TIBCO MDM Web Services Guide
50
|
Chapter 2 Record Services
1. Go to File > New > and click Other.
TIBCO MDM Web Services Guide
CRUD Services for Record Services
|
51
2. The Select a wizard screen is displayed.
3. Select MDM WSDL Generator from the WSDL Generator tree node.
4. Click Next. The Wizard displays the WSDL Generator screen.
TIBCO MDM Web Services Guide
52
|
Chapter 2 Record Services
5. Click Browse and select the path where the input file exists. All the *.rep files
are populated.
6. Select the appropriate *.rep file from the Select File drop-down list. Based on
the selected repository file, the repositories are displayed in the Select
Repository drop-down list.
7. Select a repository from the Select Repository drop-down list and click Next.
The New Project screen is displayed
.
8. Enter the appropriate project name in the Project Name field. By default, the
project name is repository name_webservice.
TIBCO MDM Web Services Guide
CRUD Services for Record Services
|
53
9. Click Next. The New Project screen is displayed.
.
10. Select the relationship depth, by default 3 levels of relationship is supported.
11. Click Next. The Generation Options screen is displayed.
.
TIBCO MDM Web Services Guide
54
|
Chapter 2 Record Services
12. Enter the appropriate package name in Package Name field. By default, a
package name is provided. The package name convention is
com.tibco.mdm.integration.webservice.<repository
name>_webservice.You can modify the package name.
13. Click Finish.
WSDL and XML Schema Generation
During the WSDL generation process, four files are created.
WSDL file
Request XSD file
Response XSD file
Generic Type file
WSDL file
The WSDL file contains the primary contract with the new service definition and
the four primary operations (add, delete, update, and find). It uses the
interoperable document literal representation.
Request XSD file
The Request contains a type definition of the entire repository and for each
attribute of the repository. This type should have the type mappings as described
in table XSD Types, page 55, including the TIBCO MDM property length which
should map for example to xsd:maxLength for a string. The three write operations
(add, modify, delete) will have an entire record as input, only the read operation
(find) will have a record id as input - and return the entire record as response.
Response XSD file
The Response file includes the request type definitions and therefore does not
need to create many dynamic types. Only for the Response itself, it will create a
type for all four operations. Furthermore, the ResultType and EventType is
contained in there which is used by the three write operations responses.
The types definition are defined in the repository model. If you want to change
the type definition it must changed at the repository model level.
TIBCO MDM Web Services Guide
CRUD Services for Record Services
|
55
Generic Type file
The generic type file contains the UserInfo type.
Table 19 XSD Types
Type Name Type Mapping Type Attributes
MDM BOOLEAN Xsd:boolean -
MDM Integer
Xsd:integer -
MDM Decimal
Xsd:decimal MDM length
xsd:fractionDigits
MDM String
Xsd:string MDM length,
xsd:maxInclusive
MDM File
Xsd:string Xsd:maxLength = 255
MDM Amount
Xsd:decimal MDM length
xsd:fractionDigits
MDM Custom Decimal
Xsd:decimal MDM Length,
Xsd:fractionDigits
MDM Date
Xsd:dateTime
TIBCO MDM Web Services Guide
56
|
Chapter 2 Record Services
CRUD Operations
The CRUD operations refer to Create, Retrieve, Update, and Delete operations.
These are the most common operations that are performed on a repository. The
following sample depicts the requests for all four operations for the Phone
repository.
1. Add/Create
Identified by ID and/or IDExt
Exception: Record already added

<ns:AddPersonRequest>
<!--Optional:-->
<ns:UserInfo>
<ns:UserName>admin</ns:UserName>
<ns:Password>admin</ns:Password>
<ns:Enterprise>rbs</ns:Enterprise>
</ns:UserInfo>
<!--Optional:-->
<ns:Context>
<!--Optional:-->
<ns:Validation>true</ns:Validation>
<!--Optional:-->
<ns:Process>true</ns:Process>
<!--Optional:-->
<ns:SystemAttributeReturn>false</ns:SystemAttributeReturn>
<!--Optional:-->
<ns:ReturnFileAsAttachment>false</ns:ReturnFileAsAttachment>
<!--Optional:-->
<ns:EffectiveDateSearchOption>E</ns:EffectiveDateSearchOption>
<!--Optional:-->
<ns:DeleteAllRelationships>false</ns:DeleteAllRelationships>
<!--Optional:-->
<ns:DeleteAllRelatedRecords>false</ns:DeleteAllRelatedRecords
</ns:Context>
<ns:Person>
<ns:ID>wt3</ns:ID>
<!--Optional:-->
<ns:IDEXT>333</ns:IDEXT>
<!--Optional:-->
<ns:CONTAINS>asdf</ns:CONTAINS>
<!--Optional:-->
<ns:firstName>user</ns:firstName>
<!--Optional:-->
<ns:lastName>wthree</ns:lastName>
<!--Optional:-->
<ns:DOB>2000-01-01</ns:DOB>
<!--Optional:-->
<ns:phoneNumber>7772121111</ns:phoneNumber>
<!--Optional:-->
<ns:PersonToAddressList>
<!--1 or more repetitions:-->
<ns:PersonToAddress>
<ns:IsPrimary>true</ns:IsPrimary>
TIBCO MDM Web Services Guide
CRUD Services for Record Services
|
57
<ns:Address>
<ns:ID>wa3</ns:ID>
<!--Optional:-->
<ns:IDEXT>333</ns:IDEXT>
<!--Optional:-->
<ns:CONTAINS>sdsd</ns:CONTAINS>
<!--Optional:-->
<ns:Name>user, wthree</ns:Name>
<!--Optional:-->
<ns:streetAddress>222, street
address</ns:streetAddress>
<!--Optional:-->
<ns:city>this city</ns:city>
<!--Optional:-->
<ns:zipCode>11111</ns:zipCode>
</ns:Address>
</ns:PersonToAddress>
</ns:PersonToAddressList>
</ns:Person>
</ns:AddPersonRequest>
2. Modify/Update
Identified by ID and/or IDExt
Exception: Record not found
<ns:UpdatePersonRequest>
<!--Optional:-->
<ns:UserInfo>
<ns:UserName>admin</ns:UserName>
<ns:Password>admin</ns:Password>
<ns:Enterprise>rbs</ns:Enterprise>
</ns:UserInfo>
<!--Optional:-->
<ns:Context>
<!--Optional:-->
<ns:Validation>true</ns:Validation>
<!--Optional:-->
<ns:Process>true</ns:Process>
<!--Optional:-->
<ns:SystemAttributeReturn>false</ns:SystemAttributeReturn>
<!--Optional:-->
<ns:ReturnFileAsAttachment>false</ns:ReturnFileAsAttachment>
<!--Optional:-->
<ns:EffectiveDateSearchOption>E</ns:EffectiveDateSearchOption>
<!--Optional:-->
<ns:DeleteAllRelationships>false</ns:DeleteAllRelationships>
<!--Optional:-->
<ns:DeleteAllRelatedRecords>false</ns:DeleteAllRelatedRecords>
</ns:Context>
<ns:Person>
<ns:ID>wt3</ns:ID>
<!--Optional:-->
<ns:IDEXT>333</ns:IDEXT>
<!--Optional:-->
TIBCO MDM Web Services Guide
58
|
Chapter 2 Record Services
<ns:CONTAINS>asdf</ns:CONTAINS>
<!--Optional:-->
<ns:firstName>user</ns:firstName>
<!--Optional:-->
<ns:lastName>w3th</ns:lastName>
<!--Optional:-->
<ns:DOB>1978-01-01</ns:DOB>
<!--Optional:-->
<ns:phoneNumber></ns:phoneNumber>
<!--Optional:-->
<ns:PersonToAddressList>
<!--1 or more repetitions:-->
<ns:PersonToAddress>
<ns:IsPrimary>true</ns:IsPrimary>
<ns:Address>
<ns:ID>aw3</ns:ID>
<!--Optional:-->
<ns:IDEXT>333</ns:IDEXT>
<!--Optional:-->
<ns:CONTAINS></ns:CONTAINS>
<!--Optional:-->
<ns:Name>user, dummy</ns:Name>
<!--Optional:-->
<ns:streetAddress>111, dummy street</ns:streetAddress>
<!--Optional:-->
<ns:city>this city</ns:city>
<!--Optional:-->
<ns:zipCode>11221</ns:zipCode>
</ns:Address>
</ns:PersonToAddress>
</ns:PersonToAddressList>
</ns:Person>
</ns:UpdatePersonRequest>
3. Delete
Identified by ID and/or IDExt
Exception: Record not found
<ns:DeletePersonRequest>
<!--Optional:-->
<ns:UserInfo>
<ns:UserName>?</ns:UserName>
<ns:Password>?</ns:Password>
<ns:Enterprise>?</ns:Enterprise>
</ns:UserInfo>
<!--Optional:-->
<ns:Context>
<!--Optional:-->
<ns:Validation>?</ns:Validation>
<!--Optional:-->
<ns:Process>?</ns:Process>
<!--Optional:-->
<ns:SystemAttributeReturn>?</ns:SystemAttributeReturn>
<!--Optional:-->
TIBCO MDM Web Services Guide
CRUD Services for Record Services
|
59
<ns:ReturnFileAsAttachment>?</ns:ReturnFileAsAttachment>
<!--Optional:-->
<ns:EffectiveDateSearchOption>?</ns:EffectiveDateSearchOption>
<!--Optional:-->
<ns:DeleteAllRelationships>?</ns:DeleteAllRelationships>
<!--Optional:-->
<ns:DeleteAllRelatedRecords>?</ns:DeleteAllRelatedRecords>
</ns:Context>
<ns:Person>
<ns:ID>?</ns:ID>
<!--Optional:-->
<ns:IDEXT>?</ns:IDEXT>
<!--Optional:-->
<ns:CONTAINS>?</ns:CONTAINS>
<!--Optional:-->
<ns:firstName>?</ns:firstName>
<!--Optional:-->
<ns:lastName>?</ns:lastName>
<!--Optional:-->
<ns:DOB>?</ns:DOB>
<!--Optional:-->
<ns:phoneNumber>?</ns:phoneNumber>
<!--Optional:-->
<ns:PersonToAddressList>
<!--1 or more repetitions:-->
<ns:PersonToAddress>
<ns:IsPrimary>?</ns:IsPrimary>
<ns:Address>
<ns:ID>?</ns:ID>
<!--Optional:-->
<ns:IDEXT>?</ns:IDEXT>
<!--Optional:-->
<ns:CONTAINS>?</ns:CONTAINS>
<!--Optional:-->
<ns:Name>?</ns:Name>
<!--Optional:-->
<ns:streetAddress>?</ns:streetAddress>
<!--Optional:-->
<ns:city>?</ns:city>
<!--Optional:-->
<ns:zipCode>?</ns:zipCode>
</ns:Address>
</ns:PersonToAddress>
</ns:PersonToAddressList>
</ns:Person>
</ns:DeletePersonRequest>
4. Find/Retrieve
Unique mode: ID and IDExt.
Specified -> Single record return
<ns:FindPersonRequest>
<!--Optional:-->
<ns:UserInfo>
TIBCO MDM Web Services Guide
60
|
Chapter 2 Record Services
<ns:UserName>admin</ns:UserName>
<ns:Password>admin</ns:Password>
<ns:Enterprise>rbs</ns:Enterprise>
</ns:UserInfo>
<!--Optional:-->
<ns:Context>
<!--Optional:-->
<ns:Validation></ns:Validation>
<!--Optional:-->
<ns:Process></ns:Process>
<!--Optional:-->
<ns:SystemAttributeReturn></ns:SystemAttributeReturn>
<!--Optional:-->
<ns:ReturnFileAsAttachment>false</ns:ReturnFileAsAttachment>
<!--Optional:-->
<ns:EffectiveDateSearchOption></ns:EffectiveDateSearchOption>
<!--Optional:-->
<ns:DeleteAllRelationships></ns:DeleteAllRelationships>
<!--Optional:-->
<ns:DeleteAllRelatedRecords></ns:DeleteAllRelatedRecords>
</ns:Context>
<!--1 or more repetitions:-->
<ns:FindPersonID>
<ns:ID>wt3</ns:ID>
<!--Optional:-->
<ns:IDEXT>333</ns:IDEXT>
</ns:FindPersonID>
</ns:FindPersonRequest>
TIBCO MDM Web Services Guide
Record Query Service
|
61
Record Query Service
Use the Record Query web service to query one or more records. You can even
query the deleted records.
The response returns attribute values and relationships to other records. The
query is based on one or more <ExternalKeys> specified in the request.
Record Query Service - Inputs
Command Type
Command type needs to be set to Query.
<Command type="Query">
<MasterCatalogRecord etype="Entity">
Query Directives
Pagination To achieve pagination of a large result, specify the following tags:
<MaxCount> : Limits the number of records returned, if more than one record
matches the query.
<StartCount> : In combination with MaxCount, the caller can control which
page of the result set needs to be returned.
<OrderByColumnList> : Defines order by Column list with sort order for the
results. This tag is Optional.
You can retrieve data in sort order based on one or more columns in an
ascending or descending order.
Example 1 Query Directives
<Command type="Query">
<StartCount>5</StartCount>
<MaxCount>50</MaxCount>
<!-- Sample OrderByColumnList syntax is -->
<!--<OrderByColumnList>AttributeName1,DESC:AttributeName2,ASC:Attr
ibuteName3</OrderByColumnList> -->
<!-- Order can be ASC or DESC, and is optional. Default being ASC
-->
<OrderByColumnList>PRODUCTID, DESC:CustName,
ASC:AmtPaid</OrderByColumnList>
<!-- Above sort order would first sort on records by
'PRODUCTID' in 'DESCENDING' order,then further sort the results
obtained by previous sort by 'CustName' in 'ASCENDING' order and
lastly further sort the results by sorting on 'AmtPaid' in default
TIBCO MDM Web Services Guide
62
|
Chapter 2 Record Services
'ASCENDING' order. Results returned would be further filtered based
on StartCount and MaxCount specified -->
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<!-- First Key is Master Catalog name -->
<Key name="MASTERCATALOGNAME">CUSTOMER</Key>
<Key name="PRODUCTID">cust_2</Key>
</ExternalKeys>
</MasterCatalogRecord>
</Command>
<FUTURE_DATED_RECORD>: Queries records by Future Effective Date key
options. Specify any one the following key options:
I (Include FED): Includes Future Effective Date records along with other
records.
O (Only FED): Includes only Future Effective Date records.
N (No FED): Does include Future Effective Date records.
Based on these key options, the records are returned. If you do specify any key
option, by default the N (No FED) option is retrieved.
Example 2 Future Dated Record Query I
<Command type="Query">
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<!-- First Key is Master Catalog name -->
<Key name="MASTERCATALOGNAME">MASTERCATALOG_WITH_EFFECTIVEDATE_RA
</Key>
<Key name="PRODUCTID">1a</Key>
<!--Key option -- I (Include FED), O (Only FED), N (No FED). If
other than I, O, N is passed then it takes the default option i.e.
N (No FED/Exclude FED)-->
<Key name="FUTURE_DATED_RECORD">I</Key>
</ExternalKeys>
</MasterCatalogRecord>
</Command>
When querying a record, specify the EFFECTIVEDATE variable in context to return
the related record according to the effective date of a relationship.
Example 3 Effective Date Related Record Query II
<Context>
<Variable name="EFFECTIVEDATE">2010-01-01
00:00:00.000</Variable>
</Context>
<Transaction>
In the Record Query request, do not use FUTURE_DATED_RECORD and
EFFECTIVEDATE tags together.
TIBCO MDM Web Services Guide
Record Query Service
|
63
<Command type="Query">
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<Key name="MASTERCATALOGNAME">SELF9</Key>
<Key name="PRODUCTID">fed1</Key>
<Key name="EFFECTIVEDATE">2013-01-01
00:00:00.000</Key>
<!--Key name="FUTURE_DATED_RECORD">I</Key-->
</ExternalKeys>
<Return>
<RelationshipData>
<Relationship>
<RelationType>CUSTOMERADDRESS</RelationType>
</Relationship>
</RelationshipData>
</Return>
</MasterCatalogRecord>
</Command>
</Transaction>
Defining query
criterion using
External Keys
The <Entity> tag specifies how to look up Records in the repository. Currently,
the only query method supported is by ExternalKeys. For different Entity types,
the ExternalKeys have different semantics. In this scenario, the Entity type is
MasterCatalogRecord which has the following semantics:
Table 20 Record Query - External Keys
Key Name Meaning Optional or Mandatory
MASTERCATALOGNAME
The name of the
repository containing
records. This is the first
key specified in the list.
All subsequent keys
make up the search
criteria for the records
in the catalog.
Mandatory
TIBCO MDM Web Services Guide
64
|
Chapter 2 Record Services
ExternalKeys The criterion the record
needs to meet to be
selected the name of
the attribute and its
value needs to be
specified.
The keys are specified
by using Key tag. It has
the following attributes:
name Name of
the attribute.
operator
Operator to use for
the search.
For example:
<Key
name="FIRSTNAME"
operator="eq">John<
/Key>
Note: All external keys
provided in the request
have to match for a
record to be selected.
At this time, AND is
the only operator
allowed for building the
search criterion. This is
implicit, and no user
inputs are required. In
other words, the query
is:
Attribute1 =
Value1 AND
Attribute2 =
Value2
Optional
Table 20 Record Query - External Keys
Key Name Meaning Optional or Mandatory
TIBCO MDM Web Services Guide
Record Query Service
|
65
Example 4 Record Query - External Keys
<ExternalKeys>
<!-- First Key is repository name -->
<Key name="MASTERCATALOGNAME">CUSTOMER</Key>
<!-- Subsequent are Record Keys -->
<Key name="FIRSTNAME" operator="eq">John</Key>
</ExternalKeys>
This example returns a list of records from CUSTOMER repository, which have
FIRSTNAME specified as John.
You can specify the multi-value attributes in the search criteria similar to the
regular attribute. For example:
<ExternalKeys>
<!-- First Key is repository name -->
<Key name="MASTERCATALOGNAME">PRODUCT</Key>
<!-- Subsequent are Record Keys -->
<Key name="TYPE" operator="eq">shirt</Key>
<Key name="SIZE" operator="eq">XL</Key>
</ExternalKeys>
This example returns those products whose TYPE is equal to shirt and one of the
value for SIZE is XL, where SIZE is a multi-value attribute.
Predefined Keys
You can specify the following predefined keys along with the repository
attributes:
RECORD_MODDATE: Identifies the modification date of the record. It can take
values as:
Date: Specify the date in any date format.
Operator: For information on the supported list of operators for the Date
data type, refer to Record Query - Supported Operators on page 69.
Example 5 RECORD_MODDATE
The following example searches a Customer record with less than the
modified date:
<ExternalKeys>
<Key name="MASTERCATALOGNAME" type="string">CUSTOMER</Key>
<!-- <Key name="PRODUCTID" type="string">c1</Key>
<Key name="PRODUCTIDEXT" type="string">c1</Key>
-->
<Key name="RECORD_MODDATE" operator="lt">05/05/2011</Key>
</ExternalKeys>
TIBCO MDM Web Services Guide
66
|
Chapter 2 Record Services
RECORD_STATE: Identifies the state of a record that is being searched. The
RECORD_STATE key supports a list of multiple values separated by a comma.
The following values are supported:
CONFIRMED: Includes the confirmed records. This is the default value.
UNCONFIRMED: Includes the unconfirmed records.
REJECTED: Includes the rejected records.
DRAFT: Includes the draft records.
LATEST: Includes the confirmed or unconfirmed records.
ALL: Includes all records with any state.
Example 6 RECORD_STATE with the CONFIRMED value
The following example searches a confirmed record with CITY as San Jose:
<ExternalKeys>
<Key name="MASTERCATALOGNAME">ADDRESS</Key>
<Key name="CITY" operator="eq">San Jose</Key>
<Key name="RECORD_STATE">CONFIRMED</Key>
</ExternalKeys>
Example 7 RECORD_STATE with multiple values
The following example searches a confirmed and unconfirmed records with
CITY as San Jose:
<ExternalKeys>
<Key name="MASTERCATALOGNAME">ADDRESS</Key>
<Key name="CITY" operator="eq">San Jose</Key>
<Key name="RECORD_STATE">CONFIRMED,UNCONFIRMED</Key>
</ExternalKeys>
The DRAFT record versions are owned by an event. The version is created during
the event. To retrieve the DRAFT version records, you must specify the work item
context.
Specify the LATEST and ALL values to include multiple states of a record.
TIBCO MDM Web Services Guide
Record Query Service
|
67
RECORD_VERSION: Identifies the version of a record that is being searched. You
can specify the following values:
<integer value>: A single record query. Indicates the record version to be
retrieved.
Example 8 RECORD_VERSION with <interger> value
The following example retrieves the data for 12345, SAVING record and for
version 5.
<ExternalKeys>
<Key name="MASTERCATALOGNAME">ACCOUNT</Key>
<Key name="PRODUCTID">12345</Key>
<Key name="PRODUCTIDEXT">SAVING</Key>
<Key name="RECORD_VERSION">5</Key>
</ExternalKeys>
ALL: Retrieves all versions of a record based on the specified criteria.
In the prior releases, if you had specified RECORD_VERSION=ALL, all
versions were retrieved in the response except for the DRAFT records.
Additionally, the deleted versions were also retrieved.
From 8.3 release onwards, if you specify RECORD_VERSION=ALL, all
CONFIRMED and ACTIVE versions are retrieved in the response. However, if
the default value of the RECORD_STATE and ACTIVE keys is used for
filtering, the retrieved versions may not be all. Therefore, to retrieve all
versions of a record, specify the following multiple combination of keys:
Example 9 RECORD_VERSION with ALL value
<ExternalKeys>
<Key name="RECORD_VERSION"operator="eq">ALL</Key>
<Key name="RECORD_STATE">ALL</Key>
<Key name="ACTIVE" type="string">ANY</Key>
</ExternalKeys>
Only the eq operator is supported for the RECORD_VERSION key.
TIBCO MDM Web Services Guide
68
|
Chapter 2 Record Services
ACTIVE: Queries whether or not the deleted records included in the response.
The valid values for this key are:
Y: Only active records are retrieved. Query does not return any deleted
record. This is the default.
N: Only data for deleted records is retrieved. Query does not return any
active record.
ANY: Indicates that both active and deleted records are retrieved, that is
both ACTIVE = Y and ACTIVE = N values are considered.
Example 10 ACTIVE
This example searches a deleted record with the specified PRODUCTID and EXT:
<Transaction>
<Command type="Query">
<StartCount>1</StartCount>
<MaxCount>10</MaxCount>
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<Key name="MASTERCATALOGNAME" type="string">DELETETEST</Key>
<Key name="PRODUCTID" operator="eq">TC1</Key>
<Key name="PRODUCTIDEXT" operator="eq">TC1</Key>
<Key name="ACTIVE" type="string">N</Key>
</ExternalKeys>
</MasterCatalogRecord>
</Command>
</Transaction>
Example 11 RECORD_STATE and ACTIVE
This example searches deleted records with the record state as CONFIRMED:
<Transaction>
<Command type="Query">
<StartCount>1</StartCount>
<MaxCount>10</MaxCount>
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<Key name="MASTERCATALOGNAME" type="string">DELETETEST</Key>
<Key name="NAME" operator="eq">TC1</Key>
<Key name="ACTIVE" operator="eq">N</Key>
<Key name="RECORD_STATE">CONFIRMED</Key>
</ExternalKeys>
</MasterCatalogRecord>
</Command>
</Transaction>
If you specify the value other than the valid values, Y is assumed.
TIBCO MDM Web Services Guide
Record Query Service
|
69
Operators
This sections provides a list of supported and deprecated operators.
Supported Operators
The following is a list of supported operators:
Table 21 Record Query - Supported Operators
Operator Description Data Types
eq Equals ALL
ne Not equals ALL
id Is Defined ALL
nd Not Defined ALL
in In
Note: Use comma as
value separator and
double quotes as text
qualifier in case the
value itself contains
comma.
ALL except Boolean
lk Like String, File
nl Not Like String, File
sw Starts With String, File
ew Ends With String, File
sl Sounds like String, File
gt Greater than Number, Date, and Timestamp
ge Greater than equals Number, Date, and Timestamp
lt Less than Number, Date, and Timestamp
le Less than equals Number, Date, and Timestamp
bw Between Number, Date, and Timestamp
TIBCO MDM Web Services Guide
70
|
Chapter 2 Record Services
For the string type attributes, additionally, you can check for case sensitivity using
caseSensitive. It specifies whether a case sensitive query is to be done. The
default is false.
Deprecated Operators
The following attributes are deprecated. Instead, use the operator attribute to
specify the required criteria:
Table 22 Record Query - Deprecated and Equivalent Operators
Deprecated
Operator
Description Equivalent Operator
lowerLimit Specifies the lower limit of
the numeric range. When
only the lower limit is
specified, all the records
with a value greater than
and equal to the lower limit
are returned.
gt
upperLimit Specifies upper limit of the
numeric range. When only
the upper limit is specified,
all the records with a value
less than or equal to the
upper limit are returned.
lt
after Specifies the lower limit of
the date range. When only
<after> is specified, all the
records with a date greater
than and equal to the
<after> date are returned.
Note: The DD-MM-YY date
format is not supported.
ge
before Specifies the upper limit of
the date range. When only
<before> is specified, all the
records with a date less than
and equal to the <before>
date are returned.
Note: The DD-MM-YY date
format is not supported.
le
TIBCO MDM Web Services Guide
Record Query Service
|
71
Relationship Search Criteria
You can search the record based on:
Relationship attributes of any relationship defined for current repository
Existence of related records
Count of related records (for example, a customer which has two associated
banks)
Attributes from target repository.
The RelationshipData tag defines how to specify the relationship criteria for
the repository. For example:
<Transaction>
<Command type="Query">
<StartCount>1</StartCount>
<MaxCount>1000</MaxCount>
<MasterCatalogRecord etype="Entity">
<!-- Base master catalog attributes -->
<ExternalKeys>
<Key name="MASTERCATALOGNAME" type="string">Customer</Key>
<Key name="PRODUCTID">a2</Key>
<Key name="PRODUCTIDEXT">a2</Key>
<Key name="FIRSTNAME">John</Key>
</ExternalKeys>
<!-- Relationship search criteria -->
<RelationshipData>
<!-- flags exists , count -->
<Relationship checkExistence ="true" count="2">
<RelationType>CustomerAccount</RelationType>
exact Specifies whether an exact
match of the string needs to
be done. When <exact> is
set to true, an exact match
of the string is returned.
By adding the * or %
character to the external
keys, a SQL LIKE
equivalent comparison can
also be performed.
Instead of exact="true", use
operator ="eq".
Instead of exact="false",
use operator="lk".
Table 22 Record Query - Deprecated and Equivalent Operators
Deprecated
Operator
Description Equivalent Operator
TIBCO MDM Web Services Guide
72
|
Chapter 2 Record Services
<!-- Relationship attributes -->
<RelationshipAttributes>
<Attribute name="type">SAVING</Attribute>
</RelationshipAttributes>
<!-- target master catalog attributes.-->
<Record>
<ExternalKeys>
<Key name="BALANCE" >39000</Key>
</ExternalKeys>
<!-- second level relationship search -->
<RelationshipData>
<Relationship checkExistence ="false">
<RelationType>AccountAddress</RelationType>
<RelationshipAttributes>
<Attribute name="preferred">Y</Attribute>
</RelationshipAttributes>
<Record>
<ExternalKeys>
<Key name="CITY">San Jose</Key>
</ExternalKeys>
</Record>
</Relationship>
</RelationshipData>
</Record>
</Relationship>
</RelationshipData>
</MasterCatalogRecord>
</Command>
</Transaction>
Table 23 Record Query - Keys
Key Name Meaning Mandatory
RelationType Relationship name Yes
checkExistence This is optional flag
which allows to search
based on existence or
non-existence of a
relationship. Valid
values are true, false
(means does not exists)
No. Default is Yes.
count Count of related records No
TIBCO MDM Web Services Guide
Record Query Service
|
73
Optimization Flags for Record Query
com.tibco.cim.optimization.recordsearch.relationship.depth
The records can be searched based on multiple or multi-level relationships.
This flag specifies maximum depth or width of the relationship for which
record search can be executed.
com.tibco.cim.optimization.recordsearch.maxjoins Maximum
number of SQL joins allowed in record search. Each inclusion of multi-value
attribute in search is counted as one join. Each inclusion of relationship
attribute in search is counted as one join.
RelationshipAttributes The criterion for
relationship attributes
can be specified using
Attribute key.
For example:
<Attribute
name="ACCOUNT_TYPE"
>SAVING</Attribute>
No
Record The criterion for target
repository attributes can
be specified using
ExternalKeys tag (the
name of the attribute
and its value needs to
be specified).
For example:
<Record>
<ExternalKeys>
<Key
name="CITY">San
Jose</Key>
</ExternalKeys>
</Record>
No
Table 23 Record Query - Keys
Key Name Meaning Mandatory
TIBCO MDM Web Services Guide
74
|
Chapter 2 Record Services
Querying Single Record
The query can be made by specifying PRODUCTID and PRODUCTIDEXT. An unique
record is returned.
<ExternalKeys>
<Key name="MASTERCATALOGNAME">CUSTOMER</Key>
<Key name="PRODUCTID">6001</Key>
<Key name="PRODUCTIDEXT">P_69_6001</Key>
</ExternalKeys>
Handling File Type Attributes
TIBCO MDM returns file type attributes either as attachments or as hyperlinks.
This is done by providing a FILE_TYPE_ATTRIBUTES context variable. It has the
following valid values:
ATTACHMENT This indicates that the client would like the server to
return the file type attributes as SOAP attachments to the web services
response.
HREF This indicates that the client would like the server to return a
hyperlink into the application, from where client can download the files
represented by the file type attributes. This is the default.
For example:
<Context>
<Variable name="FILE_TYPE_ATTRIBUTES"
type="string">HREF</Attribute>
</Context>
Return
Selecting the list of attributes The list of attribute returned in the response
can be filtered based on output map define in the repository. When the output
map is specified in the request, only those attributes from the repository that
map to the output map are returned in the response.
<Return>
<!-- CatalogOutputMap specifies which attributes to
output -->
<Entity type="OutputMap">
<ExternalKeys>
<Key name="name">ProductCatalogCase</Key>
</ExternalKeys>
</Entity>
</Return>
This <Return> section tells the system to output those attributes specified in
the Catalog Output Map called ProductCatalogCase.
TIBCO MDM Web Services Guide
Record Query Service
|
75
Selecting the list of Relationships As part of the <Return> section, you can
also specify a list of related records you are interested in. This is done by
specifying the list of relationship types.
Note: The full hierarchy for the selected relationship types is returned. For
example:
<Return>
<RelationshipData>
<Relationship>
<RelationType>Contains</RelationType>
</Relationship>
<Relationship>
<RelationType>ContainedBy</RelationType>
</Relationship>
</RelationshipData>
</Return>
Querying Records for a Specific Work Item Context
To query records for a specific work item context, specify an additional
WORKITEMREFERENCE input parameter as shown in the following example:
<DataService version="2.0">
<Identity>
<DirectoryPath>
<Directory type="Enterprise">${#Project#Enterprise}</Directory>
<Directory type="User">${#Project#User}</Directory>
</DirectoryPath>
<Authentication>${#Project#password}</Authentication>
</Identity>
<Transaction>
<Context>
<Variable name="WORKITEMREFERENCE" type="string">37130</Variable>
</Context>
<Command type="Query">
<StartCount>1</StartCount>
<MaxCount>10</MaxCount>
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<Key name="MASTERCATALOGNAME"
type="string">${#Project#MASTERCATALOGNAME}</Key>
<Key name="PRODUCTID" operator='eq'>REC1</Key>
<Key name="PRODUCTIDEXT" operator='eq'>REC1</Key>
</ExternalKeys>
</MasterCatalogRecord>
</Command>
</Transaction>
</DataService>
The Query records for workitem does not return related records of the given
record. For example, if there is a hierarchy a-contains-b-contains-c and you
have queried for record a, only the matching record for the given filter criteria is
returned in the response XML.
TIBCO MDM Web Services Guide
76
|
Chapter 2 Record Services
Querying Records Based on Classifications
You can query records based on a classification scheme or code. To do this, define
the classification scheme name and code as a context variable in the request.
ClassificationScheme Specify the classification scheme name.
ClassificationCode Specify the classification code to retrieve records
classified in that code.
To get unclassified records, specify classification scheme name.
The following is a request example:
<Transaction>
<Context>
<Variable name="CLASSIFICATIONSCHEME"
type="string">LOCATION</Variable>
<Variable name="CLASSIFICATIONCODE"
type="string">INDIA</Variable>
</Context>
<Command type="Query">
<StartCount>1</StartCount>
<MaxCount>10</MaxCount>
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<Key name="MASTERCATALOGNAME">ADDRESS</Key>
<Key name="HOUSE_NO" operator="eq">105</Key>
</ExternalKeys>
</MasterCatalogRecord>
</Command>
</Transaction>
Returning Record Classification Details
To return record classification details, you need to specify the
<ClassificationSchemes> context in the <Return> tag. You can search for
records including the record classification details.
ClassificationScheme Specify one or more classification scheme names in
the <ClassificationSchemes> context, which includes the classification and
record information.
<Return>
<ClassificationData>
<ClassificationSchemes>
<ClassificationScheme name="food"/>
</ClassificationSchemes>
Only the eq operator is supported for classification code and scheme. If you do
not specify the classification scheme, the classification code is ignored.
TIBCO MDM Web Services Guide
Record Query Service
|
77
</ClassificationData>
</Return>
ALL Specify to return all record classifications in response.
<Return>
<ClassificationData>
<ClassificationSchemes>
<All/>
</ClassificationSchemes>
</ClassificationData>
</Return>
The sample XML files are available at the following locations:
$MQ_HOME\schema\DataService\2.0\samples\repository\record-que
ry\MasterCatalogRecord-QueryData-ReturnClassificationDetails
-Request.xml
$MQ_HOME\schema\DataService\2.0\samples\repository\record-que
ry\MasterCatalogRecord-QueryData-ReturnClassificationDetails
-Response.xml
Querying Records to Filter Null Value Attributes
By default, all attributes are displayed as a part of web service reponse. However,
if you want to filter the null value attributes from the response, specify true for
the SUPPRESS_NULL_EMPTY_ATTRIBUTES context variable in the record query
request. The variable filters attributes with the null or empty values from the web
service query responses. You can use the variable for the following record
operations:
Record search
Related record search or relationship search with relationship attributes
Records with category specific attributes
Record search for deleted records
Record query based on classification data
Record query based on valid values
Record query using output map
Example 12 Record Query Request File
<ns:Context>
<ns:Variable name="SUPPRESS_NULL_EMPTY_ATTRIBUTES"
type="string">true</ns:Variable>
</ns:Context>
TIBCO MDM Web Services Guide
78
|
Chapter 2 Record Services
<ns0:Transaction>
<ns0:Command type="Query">
<ns0:MaxCount>10</ns0:MaxCount>
<ns0:MasterCatalogRecord etype="Entity">
<ns0:ExternalKeys>
<ns0:Key name="MASTERCATALOGNAME">APPLIANCES</ns0:Key>
<ns0:Key name="PRODUCTID">a</ns0:Key>
</ns0:ExternalKeys>
</ns0:MasterCatalogRecord>
</ns0:Command>
</ns0:Transaction>
Querying Records Based on Context Variables Values
You can query for records by passing custom context variable as name value pair
to Rulebase. The context variable can be used in condition to filter records, the
context variable should be declared as usage="local" in TIBCO MDM Studio.
Example 13 Filtering Records Based on Effective Date using Context Variables
Declare RUL_EFF_DATE1 and RUL_SHORTDESC variables in TIBCO MDM Studio
Rulebase Designer; specify usage="local".
Refer the Rulebase sample:
<rulebase metaversion="1.0"
xmlns="http://www.tibco.com/cim/rulebase/beans">
<name>rule</name>
<declare usage="local">
<var>RUL_EFF_DATE1</var>
<datatype type="date"/>
</declare>
<declare usage="local">
<var>RUL_SHORTDESC</var>
<datatype type="string"/>
</declare>
<constraint>
<name>con</name>
<description>con</description>

<condition>
<and>
<eq>
<var>EFFECTIVEDATE</var>
<var>RUL_EFF_DATE1</var>
</eq>
<eq>
<var>SHORTDESC</var>
<var>RUL_SHORTDESC</var>
</eq>
</and>
</condition>
<action>
<access mode="hide_record"/>
TIBCO MDM Web Services Guide
Record Query Service
|
79
</action>
</constraint>
</rulebase>
Pass the context variable in webservice request as below:
<DataService version="2.0">
<Identity>
<DirectoryPath>
<Directory type="Enterprise">Tech</Directory>
<Directory type="User">jsmith</Directory>
</DirectoryPath>
<Authentication>a</Authentication>
</Identity>
<Transaction>
<Context>
<Variable name="RUL_EFF_DATE"
type="date">07/11/2011</Variable>
<Variable name="RUL_SHORTDESC"
type="string">RECORD7</Variable>
</Context>
<Command type="Query">
<StartCount>1</StartCount>
<MaxCount>50</MaxCount>
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<Key name="MASTERCATALOGNAME"
type="string">CUSTOMER</Key>
</ExternalKeys>
</MasterCatalogRecord>
</Command>
</Transaction>
</DataService>
This hides all records with EFFECTIVEDATE=" 2011-07-11 00:00:00.000" and
SHORTDESC =Record7.
Querying Related Records
You can query for related records for a given Parent record and relationship name.
You can also specify a paging element using the <StartCount> and <MaxCount>
elements.
To query for related records:
1. Specify the user name, password, and enterprise for a user in the request
criteria.
2. Specify Command="Query" and command qualifier="RelatedRecords".
TIBCO MDM Web Services Guide
80
|
Chapter 2 Record Services
3. Specify the following mandatory input parameters in the
<ParentRecordData> element:
Repository Name
ProductID and ProductIDExt
UOM
Record version
Relationship Name
(OR)
Repository Name
ProductKeyID
Record version
Relationship Name
For example,
<ParentRecordData>
<Record>
<ExternalKeys>
<Key name="MASTERCATALOGNAME" type="string">CUSTOMER</Key>
<Key name="PRODUCTID">a1-relA</Key>
<Key name="PRODUCTIDEXT">a1-relA</Key>
<!--Key name="PRODUCTKEYID">10001</Key-->
<Key name="RECORD_VERSION">3</Key>
</ExternalKeys>
</Record>
</ParentRecordData>
4. Specify the relationship details in the <RelationshipData> element:
<RelationType>: Specify the Relationship name to return related records
for the specific relationship or specify ALL to return all the relationships
related to the record.
<RelationDepth>: Specify the relationship depth in numeric to control
the depth of the bundle heirarchy.
For example,
<Return>
<RelationshipData>
<Relationship>
<RelationType>CUSTOMERADDRESS</RelationType>
<RelationDepth>1</RelationDepth>
</Relationship>
<Relationship>
<RelationType>ALL</RelationType>
<RelationDepth>3</RelationDepth>
</Relationship>
TIBCO MDM Web Services Guide
Record Query Service
|
81
</RelationshipData>
</Return>
5. Invoke the webservice by specifying the endpoint URL as:
http://<servername>:<port>/eml/services/router/MasterCatalogAct
ion
The Response message contains a list of related records.
Querying Records Based On Perspectives
You can query for records bundled into a particular perspective. The perspective
name must be passed as one of the context attributes and depending on the type
of relationship and the depth of relationship. The following table provides the
details of relationship type:
A request example is shown below:
<DataService version="2"
<Identity>
<DirectoryPath>
<Directory type="Enterprise">Tech</Directory>
<Directory type="User">jsmith</Directory>
</ns0:DirectoryPath>
<Authentication type="Password">jsmith</Authentication>
</Identity>
<Context>
<Variable name="PERSPECTIVENAME"
type="string">personalInfoPersp</Variable>
</Context>
<Transaction>
<Command type="Query">
Table 24 Relationship Type for Perspective and Description
Relationship Type Description
ALL All the records bundled into the perspective until the
specified depth are returned.
RelationshipName which
is in the perspective
The related records pertaining to that relationship
are returned.
RelationshipName which
is not in the
perspective
Only the root record is returned.
TIBCO MDM Web Services Guide
82
|
Chapter 2 Record Services
<MaxCount>10</MaxCount>
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<Key name="MASTERCATALOGNAME">PERSON</Key>
<Key name="PRODUCTID">p1</Key>
</ExternalKeys>
<Return>
<RelationshipData>
<Relationship>
<RelationType>ALL</RelationType>
<RelationDepth>3</RelationDepth>
</Relationship>
</RelationshipData>
</Return>
</MasterCatalogRecord>
</Command>
</Transaction>
</DataService>
Record Query Service - Outputs
Record Data
Each record that matches the filter criterion given in the request is returned as a
separate MasterCatalogRecord. The relationships between the records are
captured by the RelationshipData section within each MasterCatalogRecord.
The EntityData section contains the attribute values for each record. In case a
output map was specified, the attribute list returned matches the attributes in the
output map.
Transaction Result
For more information, refer to, TransactionResult, on page 7.
Record Query Service - Access Configuration
The following access configurations can change the behavior of the Record Query
service.
TIBCO MDM Web Services Guide
Record Query Service
|
83
Rulebase Configuration
Value based security If a certain record is marked out of bounds of a profile,
these records are not returned as part of the results.
Access to attributes Certain attributes and attribute groups can be marked
hidden using rulebase configurations. If no outputmap was specified as part
of the query request, a subset of attributes to which the user has access are
returned. However, if an output map was specified in the request, a successful
response is sent only if the user has access to all repository attributes that were
mapped to the output map. If any output map attributes are marked hidden,
an authorization error is returned.
TIBCO MDM Web Services Guide
84
|
Chapter 2 Record Services
Record Query Metadata Service
Use this web service to obtain repository record metadata. The metadata contains
information, such as, the name and description of attribute groups. It also
contains information about all attributes, such as, name, description, data type,
length, and so on. The Record Query Metadata web service also shows
dependencies between attributes.
The results of this web service are independent of the data contained in a record.
Record Query MetaData - Inputs
Command type
The Command type needs to be set to Query; the entity command qualifier is set
to MetaData.
<Command type="Query">
<MasterCatalogRecord commandqualifier="MetaData" etype="Entity">
Query Directives
NONE
Support for Bundles
This service does not support record bundles.
External Keys
The external keys have the following semantics:
Entity Data
No entity data is supported in the query.
Table 25 Record Query MetaData - External Keys
Key Meaning Required?
MASTERCATALOGNAME
The name of the
repository for which
meta-data is queried.
Y
TIBCO MDM Web Services Guide
Record Query Metadata Service
|
85
Record Action Intended
You can specify the action that you want to perform on the data that is being
queried. The valid record actions are:
ADD
EDIT
COPY
VIEW
MASS_UPDATE
RECORD_SEARCH
You can specify the record action in the Context section of the request. For
example,
<Context>
<Variable name="RECORD_ACTION" type="string">ADD</Variable>
</Context>
For more details on RECORD_ACTION, refer to Appendix A Context Variables in
TIBCO MDM Studio Rulebase Designer Users Guide.
Support for Classification Context
You can retrieve a list of category specific attributes along with other attributes
while querying metadata by specifying a classification context. Specify a list
classification schemes and code hierarchy in the <ClassificationSchemes>
context.
<ClassificationSchemes>
<ClassificationScheme name="FBT-SCHEME1">
<ClassificationCode code="50201600">
<ClassificationCode code="50201700">
<ClassificationCode code="10000111"/>
<ClassificationCode code="10000115"/>
</ClassificationCode>
</ClassificationCode>
</ClassificationScheme>
</ClassificationSchemes>
By default, category specific attributes are not included. You must specify a valid
classification context to return category specific attributes in response.
TIBCO MDM Web Services Guide
86
|
Chapter 2 Record Services
Classification Scheme Each classification scheme always has one root code.
If you want to locate all category specific attributes, which apply to a
classification scheme, specify only one level root code.
ALL Specify to return all category specific attributes. For example,
<ClassificationSchemes>
<All/>
</ClassificationSchemes>
If you do not specify <ClassificationSchemes> context, the category specific
attributes are not returned.
The sample XML files are available at
$MQ_HOME\schema\DataService\2.0\samples\repository\metadata:
RecordQueryMetaDataWithClassificationContextRequest.xml
RecordQueryMetaDataWithClassificationContextResponse.xml
RecordQueryMetaDataWithClassificationContextAllRequest.xml
RecordQueryMetaDataWithClassificationContextAllResponse.xml
Record Query MetaData - Outputs
The response contains a list of all the attribute groups the user has access to. It
also contains the list of attributes belonging to the attribute groups.
AttributeGroup
The data for each attribute group that is part of the repository is returned as an
AttributeGroup entity which is related to MasterCatalogRecord entity.
RecordAttribute
The data for each record attribute is returned as a RecordAttribute entity that is
related to the MasterCatalogRecord entity.
Apart from providing record attribute details like name, description, data type
etc., the service also shows the attribute group to which the attribute belongs.
Display Dependency Between Attributes
The characteristics of an attribute or an attributes displayed value depends on
the values of another attribute and is returned as DependentRecordAttribute
relationship.
TIBCO MDM Web Services Guide
Record Query Metadata Service
|
87
Role-based Access Privileges
Users and role based privileges can be defined in the system, for access to
attribute groups. The behavior is similar to the one described in the previous
section.
TIBCO MDM Web Services Guide
88
|
Chapter 2 Record Services
Record Query ValidValues (Init) Service
Use this web service for the following:
To list of initial and valid values for all attributes as defined by the rulebase
and specified for the repository.
To provide access privileges configured for attributes.
To list the list of valid relationship types available for a given record.
The most common use case of this web service is to query the value of a
drop-down attribute, which is dependent on the value of another drop-down
attribute. This service works on attribute values supplied by the request.
Response XML Structure of Service
The Response XML structure of the Record Query ValidValues service supports
the relationships across catalogs. To switch to a backward compatible response
structure, set the Backward compatible Web Service Replies property in the
Configurator to true. Setting this property to true enables backward compatible
responses for catalogs, which do not have relationships across catalogs.
ValidValues response for catalogs having relationships across catalogs will always
have a new response structure irrespective of the value of the property. The
default value of this property is false.
ValidValuesInit versus ValidValues
ValidValuesInit This command qualifier is used when the user wants to
fetch the default initial values for a new record being added.
ValidValuesInit executes the new record initialization rulebase followed by
the validations rulebase.
ValidValues The user after obtaining the values from ValidValuesInit might
change some attributes and might want to obtain the valid values for this
changed set of attribute values. In this case the ValidValues command
qualifier needs to be used.
ValidValues executes the validations rulebase only.
TIBCO MDM Web Services Guide
Record Query ValidValues (Init) Service
|
89
Record Query/ValidValues Service - Inputs
Command type
The Command type needs to be set to Query, and the entity command qualifier
is set to ValidValues.
<Command type="Query">
<MasterCatalogRecord commandqualifier="ValidValues"
etype="Entity" type="MasterCatalogRecord">
For ValidValuesInit, the command qualifier must be ValidValuesInit.
Query Directives
None.
Support for Bundles
A Record Bundle is a list of records related to each other by defined relationships.
The relationships are defined in the <Relationship> section of the
request/response XML. The ValidValues web service works on a record bundle.
However, ValidValuesInit works only with a single repository record.
External Keys
The external keys have the following semantics:
Key Meaning Required
MASTERCATALOGNAME
The name of the repository
which contains the records.
Mandatory.
PRODUCTID
PRODUCTID of the record for
which the valid values are
sought.
Optional. When this is empty, the
system assumes that the record
doesnt exist and is being newly
created. In a record bundle, only
one record item can have its
PRODUCTID empty.
PRODUCTIDEXT
This is an optional key used
to identify a record.
Optional.
TIBCO MDM Web Services Guide
90
|
Chapter 2 Record Services
Entity Data
The Entity data section contains attribute values corresponding to a record.
However, in case of ValidValuesInit, this section can be empty when a record is
being added or values are being queried for the first time.
In case of ValidValues, the request needs to include values of the attributes.
Given attribute values are used for evaluating the valid values for each attribute.
When a record is part of a record bundle, to get valid values as dictated by the
rulebase, the request must provide the entity data of all the record items that are
part of the record bundle.
Record Action Intended
You can specify the action that you want to perform on the data that is being
queried. The valid record actions are:
ADD
EDIT
COPY
VIEW
MASS_UPDATE
RECORD_SEARCH
You can specify the record action in the Context section of the request. For
example,
<Context>
<Variable name="RECORD_ACTION" type="string">ADD</Variable>
</Context>
For more details on RECORD_ACTION, refer to Appendix A Context Variables in
TIBCO MDM Studio Rulebase Designer Users Guide.
Record Query/ValidValues Service - Outputs
RecordAttribute
The data for each record attribute is returned as a RecordAttribute entity, that is
related to the MasterCatalogRecord entity.
RelationshipAttribute
The data for each relationship attribute for specified Relationship is returned as a
'RelationshipAttribute' entity.
The following data is returned for each attribute, RecordAttribute or
RelationshipAttribute.
TIBCO MDM Web Services Guide
Record Query ValidValues (Init) Service
|
91
Initial value for an attribute
Access modifier for an attribute.
List of valid values configured for an attribute.
Selected or Initial Value for an Attribute
The Values element inside the RecordAttribute or RelationshipAttribute is
used to return the initial value, per rulebase configurations, for a new record.
The value is not returned in cases where access is denied to an attribute, that is,
when Visibility is set to HIDE.
Visibility of an Attribute
The Visibility element inside the RecordAttribute or RelationshipAttribute
denotes the kind of access the user of the service has to the attribute. The possible
values are HIDE, MODIFY and VIEW.
Valid Values of an Attribute
The ValidValues element inside the RecordAttribute or RelationshipAttribute
contains a list of valid values configured for an attribute. In most cases, this list is
used to display a drop-down list.
A sample of valid values response for relationship attribute-
<Relationship>
<RelationType>Contains</RelationType>
<RelatedEntities>
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<Key name="MASTERCATALOGNAME"
type="string">TEST_VALIDVALUES</Key>
<Key name="PRODUCTID" type="string">bchild</Key>
<Key name="PRODUCTIDEXT" type="string">bchild</Key>
</ExternalKeys>
<RelationshipData>
<Relationship>
<RelationType>RelationshipAttributeValidValues</RelationType>
<RelatedEntities>
<RecordAttribute etype="Entity">
<ExternalKeys>
<Key name="name" type="string">SIZE</Key>
</ExternalKeys>
<EntityData xsi:type="RecordAttributeEntityDataType">
<Value type="string">L</Value>
<Visibility type="string">MODIFY</Visibility>
<ValidValues type="map">
TIBCO MDM Web Services Guide
92
|
Chapter 2 Record Services
<Entry>
<Key type="string">XL</Key>
<Value type="string">XL</Value>
</Entry>
<Entry>
<Key type="string">L</Key>
<Value type="string">L</Value>
</Entry>
</ValidValues>
</EntityData>
</RecordAttribute>
<RecordAttribute etype="Entity">
<ExternalKeys>
<Key name="name" type="string">QUANTITY</Key>
</ExternalKeys>
<EntityData xsi:type="RecordAttributeEntityDataType">
<Visibility type="string">hide</Visibility>
</EntityData>
</RecordAttribute>
</RelatedEntities>
</Relationship>
</RelationshipData>
</MasterCatalogRecord>
</RelatedEntities>
</Relationship>
Multi-Value Drop Downs Values of a Record Attribute
Some of the attributes in a record might be represented as multi-value drop-down
elements. The lists of valid values for these elements are represented as
ValidValues, as described in the following format. Note the type attribute is set
to marray (different from map from a single value drop-down described in the
previous section).
The first Value element in an Entry represents the value to be saved or sent to
the server. Each of the values after the first one is a column in the multi-value
drop down.
Available List of Valid Relationship Types
The list of valid relationship types for a given record are modeled as a
RecordAttribute with external key name=RELATIONSHIP_ LIST. The Value
element in the RecordAttribute provides the default relationship type for a given
record.
The service also shows the record attribute on which the relationship list is
dependent.
TIBCO MDM Web Services Guide
Record Query ValidValues (Init) Service
|
93
Work Item Reference
When a queried record is part of a work item, the response contains the context
variable WORKITEMREFERENCE that references the work item.
<Context>
<Variable name="WORKITEMREFERENCE" type="string">10001</Variable>
</Context>
Work item reference is usually used when the Record Validate Service is called.
Configuration Parameters
The following configuration parameters can change the behavior of the Record
Query/ValidValues service.
Rulebase Configuration
Attribute Groups Hide/Show access Based on the rules defined, certain
attribute groups can be hidden from the user. The attribute values belonging
to the hidden groups are not returned as part of the response; the Visibility is
marked as HIDE.
Attribute Hide/Show access Based on the rules defined, certain attributes
can be hidden from the user. These values of hidden attributes are not
returned as part of the response; the Visibility is marked as HIDE.
Relationship Types Hide/Show access Relationships can be marked as
hidden using the rulebase. Hidden relationships are not returned as part of
the response.
Propagation When a new record is added in an existing bundle, certain
attribute values can be inherited from different record items (parent or child)
in the record bundle.
Initial value assignment Initial values can be assigned to certain attributes
when a record is being added.
Role-based Access Privileges
Users and role based privileges can be defined in the system, for access to the
attribute groups. These privileges are reflected in the Visibility attribute,
returned as part of the response.
TIBCO MDM Web Services Guide
94
|
Chapter 2 Record Services
Record Validate Service
Use this web service to validate the attribute values of a record against the
validation rules defined in the system. This service works on a record bundle, and
can take a list of related records for processing.
The service results in a response being generated with errors, warning and
information messages generated by validating the record bundle against the rules
defined.
Record Validate Service - Inputs
Command type
The Command type needs to be set to Validate and the entity command qualifier
is set to either Add or Modify depending on whether a record bundle is being
added or modified. Note that the qualifier corresponds to the state of the root
record (identified by the first MasterCatalogRecord element within a Command)
in a bundle. Therefore, if you edit an existing record and add a new record as
child to it, the qualifier will still be Modify and not Add.
<Command type="Validate">
<MasterCatalogRecord commandqualifier="Add" etype="Entity" >
Query Directives
None.
Support for Bundles
This web service can work on more than one record as part of a record bundle.
External Keys
Each record in the record bundle must have external keys. The external keys have
the following semantics:
Key Meaning Required
MASTERCATALOGNAME
The name of the repository
which contains the records.
Mandatory
TIBCO MDM Web Services Guide
Record Validate Service
|
95
Entity Data
Entity data section contains the attribute values corresponding to a record.
Work Item Reference
When a record is validated in the context of a work item, the request must contain
the context variable WORKITEMREFERENCE that references the work item.
<Context>
<Variable name="WORKITEMREFERENCE" type="string">10001</Variable>
</Context>
Work item reference is usually obtained from the Record Query/ValidValues
service.
Record Validate Service - Outputs
Records in the record bundle are validated against validation rules defined on the
server, and the results are returned in the response.
ResultList
For more information, refer to, ResultList, on page 7.
TransactionResult
For more information, refer to, TransactionResult, on page 7.
PRODUCTID
PRODUCTID of the record for
which the valid values are
sought.
Mandatory
PRODUCTIDEXT
This is an optional key used to
identify a record.
Optional
Key Meaning Required
TIBCO MDM Web Services Guide
96
|
Chapter 2 Record Services
Record Add or Modify Services
This web service allows you to add or modify a record in a repository. This service
works on record bundles, and can therefore take a list of records for processing. In
case the records have errors, the services returns a response that contains details
of the validation errors (as described in the previous section).
If the records are successfully added or modified, an informational message is
sent indicating whether the records were saved and if the workflow was initiated.
Flexible Editing of Records
Some features that provide flexibility during adding or modifying a record are:
Defining a relationship The entire set of child records is not required to
define a relationship between two records; only a related record can be
specified. To save a record with the relationship, you need not specify the
entire set of the record; specifying the relationship data is sufficient.
Specifying a reverse relationship You can also specify and process a reverse
relationship.
Adding or Modifying Records Incrementally You can add and modify
records incrementally. Incremental handling is controlled by the
<Relationship incremental="true"> flag. By default, the flag is set to
true. When the flag is set to true, only the record relationship is added to the
given existing record. If the incremental flag is set to false, all the other
relationships are deleted and the newly specified relationship is added.
For example, let us say, A-Contains-B and the Incremental flag is set to true. If
a request is sent as A-Contains-C, A will be related to B,C. If the Incremental
flag is set to false, and the request is sent A-Contains-C, the relationship
A-Contains-B is deleted and A will have a new relationship with C.
Deleting a Relationship Between Records You can delete relationships
between records by specifying the <Relationship delete="true"> flag.
For example, let us say, A-Contains-B,C.
To delete a specific relationship with the record, send a request
A-Contains-B. In the relationship element of this request, set the
TIBCO MDM Web Services Guide
Record Add or Modify Services
|
97
<Relationship delete="true">. Now "A" will be related to C.
Relationship between A and B is deleted.
To delete all relationships with records for a given relationship, send a
request to modify a record where <Relationship delete="true">,
specify the relationship type, and do not specify any record details.
To delete relationships with records for all relationships, send a request to
modify a record, specify <Relationship delete="true"
incremental="false">, and specify (*) as relationship type. (*) indicates
all relationships.
Saving a Record as DRAFT
You can save a record as DRAFT and initiate a workflow for that record. To save
the record as DRAFT, specify the record_state as DRAFT. A workflow will be
initiated.
The supported command types for saving a record as DRAFT are add and
modify.
The entity command qualifier supported is validate/process and
novalidate/process.
Flexible editing of records is supported while saving a record as DRAFT.
Modifying a Record as DRAFT
When saving a record as DRAFT in the context of a workflow, new workflow is
not triggered but the record is modified and only the event state is updated.
If a work item reference is included, the modification is a part of the
corresponding workflow and new work item is not generated.
If a work item reference is not included, DRAFT is saved and new workflow is
started.
Future Effective Date (FED) Records
For Future Effective Date records, you must define an ID, Extension, and Version.
Additionally, you can add the following
Add multiple versions of FED records.
The command qualifiers NoValidate/NoProcess and Validate/NoProcess are not
supported when saving the record as DRAFT. If any of these two qualifiers are
specified, an error is returned.
TIBCO MDM Web Services Guide
98
|
Chapter 2 Record Services
Create a new version of record, if you have made changes to the record data
and/or to the EffectiveDate.
The EffectiveDate specified at the context level applies to all records and
relationship. However, to overwrite it on individual record level, specify the new
data value for the EFFECTIVEDATE attribute.
For a relationship with EffectiveDate, specify the relationship effective date in
context so that related record is returned according to the relationship effective
date.
While modifying a FED record version, the RECORD VERSION parameter is
mandatory. For example,
<Key name="RECORD_VERSION" type="int">1</key>
Classifying Records
You can classify records into the specified classification using the
<ClassificationSchemes> context while adding or modifying a record.
The following actions are supported for the classification scheme:
Classify Classifies a record into the specified classifications. This is default
action.
Unclassify Unclassifies a record from the specified classifications.
UnclassifyAll Unclassifies a record from all existing classifications.
Replace Unclassifies a record from all existing classifications and classifies
them into specified classifications.
Specify the classifcations in the following sequence:
Name of a classification scheme
Actions for a classification scheme
Classification code: Specify the code hierarchy by nesting the
ClassificationCode tag. Ensure that you specify the classification code and
not the classification code name.
Refer to the following request example:
<ClassificationSchemes>
In the Record Add web service, if you do not specify EFFECTIVEDATE, the record
is saved as a current timestamp record and a confirmed version is created.
You can classify records only for classification schemes for which the Manual
extraction method is selected.
TIBCO MDM Web Services Guide
Record Add or Modify Services
|
99
<ClassificationScheme name = "GamesAndToys" action="Classify">
<ClassificationCode code="86010100">
<ClassificationCode code="10005133">
<ClassificationCode code="20000045"/>
</ClassificationCode></ClassificationCode>
</ClassificationScheme>
</ClassificationSchemes>
Specify the exact hierarchy of classifications in the context starting from level one.
If there is a mismatch in hierarchy, an error is returned.
Alternatively, instead of classifying record by adding it in the request you can add
it in the context variable.
<Context>
<Variable name="CLASSIFICATIONCODEPATH">
GamesAndToys/86010100/10005133/20000045</Variable>
</Context>
and have the following rulebase
<constraint>
<name>rulebase-ACTION-CATEGORIZE</name>
<action>
<categorize incremental="true">
<var>context_classificationcodepath</var>
</categorize>
</action>
</constraint>
CLASSIFICATIONCODEPATH in webservice context is a Name- Value pair. You can
use any Name-Value pair to do classification using rulebase and webservice
context. SchemeNames followed by a forward slash (/) delimter is used to define
a complete codepath. If you have multiple codepath use comma(,) separator.
You can use it with Record ADD/MODIFY, Record Query webservices. It can be
used to get List of Values, provide access based on the category.
The sample request and response XML files for all actions are available in the
following locations:
Classify Action:
$MQ_HOME/schema/DataService/2.0/samples/repository/record-add_
modify_delete/MasterCatalogRecord-Add-ManualClassify-Request
.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/record-add_
modify_delete/MasterCatalogRecord-Add-ManualClassify-Respons
e.xml
TIBCO MDM Web Services Guide
100
|
Chapter 2 Record Services
Unclassify Action:
$MQ_HOME/schema/DataService/2.0/samples/repository/record-add_
modify_delete/MasterCatalogRecord-Modify-ManualUnclassify-Re
quest.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/record-add_
modify_delete/MasterCatalogRecord-Modify-ManualUnclassify-Re
sponse.xml
Unclassify All Action:
$MQ_HOME/schema/DataService/2.0/samples/repository/record-add_
modify_delete/MasterCatalogRecord-Modify-ManualUnclassifyAll
-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/record-add_
modify_delete/MasterCatalogRecord-Modify-ManualUnclassifyAll
-Response.xml
Replace Action:
$MQ_HOME/schema/DataService/2.0/samples/repository/record-add_
modify_delete/MasterCatalogRecord-Modify-ManualReplace-Reque
st.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/record-add_
modify_delete/MasterCatalogRecord-Modify-ManualReplace-Respo
nse.xml
Record Add/Modify Services - Inputs
Command type
The valid command types are:
Add Use when the root record in a bundle is being added.
Modify Use when the root record in a bundle is being modified.
Set the entity command qualifier to any of the following:
Validate/Process Causes the records to be validated before saving. This also
initiates New Record Introduction Edit (NRIE) workflows. This is the default.
Validate/NoProcess Validates records and save them without starting the
NRIE workflows.
NoValidate/Process Does not validate the records, but saves them, and also
starts NRIE workflows.
NoValidate/NoProcess Does not validate the records or start the workflow,
but saves them.
NoValidate/ProcessOnDataChange (only for the Modify command type)
Does not validate the records if the data has not changed.
TIBCO MDM Web Services Guide
Record Add or Modify Services
|
101
Validate/ProcessOnDataChange (only for the Modify command type)
Validates the records only when the data has changed for the specified
records. If the data has not changed, an error is returned.
Execution Mode
Set the execmode to either SYNCHR or ASYNCHR. For more information, refer to
Execution Mode on page 2.
Handling File Type Attributes
TIBCO MDM can handle file type attributes either as attachments or as relative
paths into the application. To perform this, specify the FILE_TYPE_ATTRIBUTES
context variable with the following two valid values:
ATTACHMENT Indicates that the client has sent the file type attributes as SOAP
attachments.
HREF Indicates that the client had already loaded the files onto the server
(using HTTP post), and wants the server file type attributes to be processed as
relative paths into the application. This is the default.
<Context>
<Variable name="FILE_TYPE_ATTRIBUTES"
type="string">ATTACHMENT</Attribute>
</Context>
Handling System Generated Attributes
You cannot change the following system-generated attributes. If any of the
following attributes are specified in the request XML, an error is returned.
Active, creation date, moddate, version number, product keyID,
modmemberID, checksum, importtime stamp, ownerID, ownerType,
lastConfirmedVersion, processLogID, batchID, parentVersion,
catalogVersionNumber
Query Directives
None.
The CREATIONDATE and MODDATE system attributes do not provide the timezone
details. This is a limitation. For example, the value for these attributes do not
display the time zone ID along with the date and time, that is, 2013-05-08
03:19:46.0 Asia/Shanghai.
TIBCO MDM Web Services Guide
102
|
Chapter 2 Record Services
Support for Bundles
This web service can work on more than one record, as part of a record bundle.
External Keys
Each record in the record bundle must be external keys. The external keys have
the following semantics:
Entity Data
Entity data section contains the attribute values corresponding to a record.
RECORD_STATE
The request can provide the state in which the records need to be saved. The state
is accepted as an attribute in the entity data with the name RECORD_STATE. The
valid states are:
UNCONFIRMED: If the Validate/NoProcess command type is specified, by
default the UNCONFIRMED state is considered.
CONFIRMED: If the Validate/Process command type is specified, by default
the CONFIRMED state is considered.
DRAFT
If an attribute is a multi-value attribute, it is represented as follows:
<MultiValueAttribute type="string" name="COLOR">
<Value>red</Value>
<Value>green</Value>
<Value>yellow</Value>
</MultiValueAttribute
In this example, COLOR is a multi-value attribute.
If an attribute is defined as a relationship attribute, it is represented as follows:
Key Meaning Required
MASTERCATALOGNAME
The name of the repository
which contains the records.
Mandatory.
PRODUCTID
PRODUCTID of the record for
which the valid values are
sought.
Mandatory.
PRODUCTIDEXT
This is an optional key used to
identify a record.
Optional.
TIBCO MDM Web Services Guide
Record Add or Modify Services
|
103
<Relationship>
<RelationType>Contains</RelationType>
<RelatedEntities>
<MasterCatalogRecord etype="Entity">
<ExternalKeys>
<Key name="MASTERCATALOGNAME" type="string">Customer1</Key>
<Key name="PRODUCTID" type="string">a2-demo1TEST3</Key>
<Key name="PRODUCTIDEXT" type="string">a2-demo1TEST3</Key>
</ExternalKeys>
<EntityData>
<Attribute name="QUANTITY" type="integer">1</Attribute>
</EntityData>
</MasterCatalogRecord>
</RelatedEntities>
</Relationship>
In this example, QUANTITY is a relationship attribute.
For a sample of multi-value attributes and relationship attributes, refer to
$MQ_HOME/schema/DataService/2.0/samples.
WorkItem Reference
When a record is modified in the context of a work item, the request must contain
the context variable WORKITEMREFERENCE that references the work item before
the <Transaction> element.
<Context>
<Variable name="WORKITEMREFERENCE" type="string">10001</Variable>
</Context>
The work item reference is usually obtained from the Record Query/ValidValues
or Work Item Query service.
Record Add/Modify Services - Outputs
Based on the command type and the command qualifier, the system tries to
validate and save the records. Any errors found during validation (if asked to be
performed), are returned in the response.
If validation is attempted and results in errors, the records are not saved.
ResultList
For mor e information on what the ResultList element contains, refer to the
section, ResultList, on page 7.
Transaction Result
For more information, refer to , TransactionResult, on page 7.
TIBCO MDM Web Services Guide
104
|
Chapter 2 Record Services
Record Delete Service
This web service allows you to delete:
A repository record
Records related to specified record
Both the repository record and related records. That is, delete the parent
record and the records for the given relationship.
A future dated record version
When a record is deleted, a workflow is initiated unless specified otherwise in
command qualifier. Using the right command qualifier, you can skip the
workflow processing and complete the delete record operation
If the workflow is initiated its DOCSUBTYPE is set as CatEditDelete.
The eligibility criteria for deletion is:
You must have access permission to delete the record on the specified
repository.
The record must not be a part of another workflow. If the record is a part of
another workflow, the record is not deleted.
When deleting record and related records, all the records must be available for
deletion. If deletion is not allowed on one of the records then the whole
transaction is disallowed and no deletion will be carried for the remaining
records even if deletion is allowed. Deletion will be successful only if all the
records are available for deletion. The record is not available for deletion
when the record is being processed in other workflows or the user does not
have the permission for deletion.
Deleting Record
When a record is deleted, the latest version of the record must be
Active
The record is not in another workflow
The delete is performed by creating a new version with Active = N.
TIBCO MDM Web Services Guide
Record Delete Service
|
105
Future Effective Date (FED)
The web service can delete a specific future effective dated version if
Version number is specified
The specified version is future dated and active
The version is not in another workflow
Delete the previous FED versions by specifying
DELETE_PREVIOUS_FED_VERSION in the context. Alternatively, you can retain
the previous FED record version or overwrite it. Later, delete it when the
EffectiveDate is changed for a record.
The delete is performed by marking the future dated version as REJECTED.
For example:
<Command type="Delete">
<MasterCatalogRecord etype="Entity"
commandqualifier="Record">
<ExternalKeys>
<Key
name="MASTERCATALOGNAME"type="string">MASTERCATALOG_WITH_EFFECTIVE
DATE_RA</Key>
<Key name="PRODUCTID"type="string">EffectiveDate</Key>
<Key name="PRODUCTIDEXT"type="string">EffectiveDate</Key>
<Key name="RECORDVERSION"type="int">2</Key>
</ExternalKeys>
<EntityData>
<!--default RECORD_STATE is if not specified is UNCONFIRMED-->
<Attribute name="EFFECTIVEDATE"type="date">2011-06-29
00:00:00.000</Attribute>
</EntityData>
</MasterCatalogRecord>
</Command>
Delete Record - Inputs
Command Type
The valid command types are:
Delete This should be used when you need to delete a repository record or
related target records.
The entity command qualifier is set to any of the following:
Record Deletes the specified record and initiates the delete workflow.
RelationshipTargets Deletes only the related records and initiates the
delete workflow. Optionally, relationship name can be specified.
TIBCO MDM Web Services Guide
106
|
Chapter 2 Record Services
Record/NoProcess Deletes the specified record and confirms it
immediately without initiating the workflow. User must have required
privileges.
RelationshipTargets/NoProcess Deletes only the related records and
confirms it immediately without initiating the workflow. Optionally,
relationship name can be specified. User must have required privileges.
DeleteAll Deletes the specified record/related records and initiates the
workflow. Optionally, relationship name can be specified.
DeleteAll/NoProcess Deletes the specified record/related records and
confirms the record immediately. Optionally, relationship name can be
specified. User must have required privileges.
Command qualifier not specified or blank This causes both the record and
the relationship target records to be deleted and delete workflow is initiated. It
is recommended that DeleteAll be used instead of a blank command qualifier.
Execution Mode
The execmode can be set to either SYNCHR or ASYNCHR. For more information,
refer to , Execution Mode, on page 2.
Query Directives
None.
External Keys
To delete a record you must specify either of the following:
productkeyid
productid AND productidext
Key Meaning Required
PRODUCTKEYID
The PRODUCTKEYID value of the record.
Either specify productkeyid or productid and
productidext.
Either one of
these keys is
mandatory.
PRODUCTID
(and) PRODUCTIDEXT
PRODUCTID and PRODUCTIDEXT of the
record for which the valid values are sought.
Either specify productkeyid or productid and
productidext.
TIBCO MDM Web Services Guide
Record Delete Service
|
107
Delete Record - Outputs
Based on the command type and the command qualifier, the system tries to delete
records. Any errors found during validation (if asked to be performed), are
returned in the response.
ResultList
For more information, refer to, ResultList, on page 7.
TransactionResult
For more information, refer to, TransactionResult, on page 7.
TIBCO MDM Web Services Guide
108
|
Chapter 2 Record Services
Initiate Workflow Service
This web service is used to initiate workflow for a given record.
You must specify the command type as InitiateWorkflow and the entity
commandqualifier as docSubType to invoke a workflow for a record. Before
initiating a workflow for a docsubtype, make sure that the docsubtype entry is in
the Process Definition Selection business process. Triggering a workflow is an
asynchronous process, so the response is returned immediately. It does not wait
for completion of the workflow. Because of this you will always see a success
message in the response message.
Initiate Workflow Service - Inputs
Command type
A valid Command type is: InitiateWorkflow. This should be used when you
need to initiate a workflow.
Command qualifier
The entity command qualifier is set to the following:
docSubType Specify an existing docSubType. For example, FACTSHEET,
CatEditChange, CatEditDelete, CatEditImport, CatEditAdd, and
CatEditAccepted.
<Command type="InitiateWorkflow">
<MasterCatalogRecord commandqualifier="CatEditAdd" etype="Entity"
>
Execution Mode
The execmode can be set to either SYNCHR or ASYNCHR. For more information,
refer to, Execution Mode, on page 2.
Query Directives
None.
Records with RECORD_STATE as Draft cannot be used to initiate a workflow.
TIBCO MDM Web Services Guide
Initiate Workflow Service
|
109
Support for Bundles
None.
External Keys
Each web service request must have external keys. The external keys have the
following semantics:
Initiate Workflow - Outputs
ResultList
For more information, refer to, ResultList, on page 7.
Key Meaning Required
MASTERCATALOGNAME
The name of the repository
which contains the records.
Mandatory.
PRODUCTID
PRODUCTID of the record. Mandatory.
PRODUCTIDEXT
PRODUCTEXT of the record. Mandatory.
RECORD_STATE
This key identifies the state of
the record being searched. Valid
values are UNCONFIRMED
(the default) or CONFIRMED.
If the RECORD_STATE is
set to CONFIRMED, the
system looks for the latest
CONFIRMED record.
If state is set to
UNCONFIRMED, the
system looks for the latest
record including
UNCONFIRMED records,
that is, if the latest record is
an unconfirmed one, that
would be returned. This is
the default behavior, so if
unconfirmed exists select it,
otherwise return the last
confirmed version.
Optional.
TIBCO MDM Web Services Guide
110
|
Chapter 2 Record Services
Transaction Result
For more information, refer to, TransactionResult, on page 7.
TIBCO MDM Web Services Guide
Transaction Atomicity for Record Web Services
|
111
Transaction Atomicity for Record Web Services
Use Transaction Atomicity to atomize the transaction on the commands included in
the <Transaction> element. If a command specified in the <Transaction>
element fails, the transaction is not processed. Transaction atomicity applies to the
Create, Update, and Delete operations performed on a record. For more
information on these operations, refer to CRUD Operations, page 56.
To enable the Transaction Atomicity feature, specify the atomic attribute in the
<Transaction> element. You can specify any one of the following values for the
atomic attribute:
on: all commands are processed as an atomic operation. You can set the
atomic="on"for the following web services:
Record Add or Modify Services, page 96
Record Delete Service, page 104
off: each command is processed as a separate transaction.
Using these scenarios, you can process a record web service request with the
multiple commands performing CUD operations. The operations are specified as
an atomic process within the <Transaction> element.
Scenario 1: Process Multiple CUD Commands, page 112
Scenario 2: Large Number of Modified Records, page 113
Scenario 3: Same Record in Multiple Commands, page 113
Scenario 4: Enable Global Distributed Locking, page 114
The Transaction Atomicity feature does not work for the Record Query web
service. If you specify atomic="on" for the Command type="Query", the
following error message is displayed:
Only Record Add/Modify/Delete commands should be part of atomic
transaction.
The Transaction Atomicity feature currently does not support synchronous
workflows due to concerns over long running or suspended workflow logic.
TIBCO MDM Web Services Guide
112
|
Chapter 2 Record Services
Scenario 1: Process Multiple CUD Commands
In this scenario, you can add or modify records with multiple commands in a
single transaction. Specify atomic="on" in the <Transaction> element. You can
also add multiple transactions with multiple commands.
Example <Transaction atomic="on">
<Command type="Modify">
<!--The Supported CommandTypes for Save are Add and Modify-->
<MasterCatalogRecord etype="Entity"
commandqualifier="Validate/Process">
<!-- The Suppored commandqualifier for Save are
Validate/Process, Validate/NoProcess, NoValidate/Process,
NoValidate/NoProcess default is Validate/Process-->
<ExternalKeys>
<Key name="MASTERCATALOGNAME"
type="string">Customer</Key>
<Key name="PRODUCTID" type="string">1</Key>
<Key name="PRODUCTIDEXT" type="string">1-Ext</Key>
</ExternalKeys>
<EntityData>
<Attribute name="PRODUCTIDEXT"
type="string">1</Attribute>
<Attribute name="PRODUCTID"
type="string">1-Ext</Attribute>
<Attribute name="SHORTDESC" type="string">Record for
Customer repository</Attribute>
</EntityData>
</MasterCatalogRecord>
</Command>
<Command type="Modify">
<!--The Supported CommandTypes for Save are Add and Modify-->
<MasterCatalogRecord etype="Entity"
commandqualifier="Validate/Process">
<!-- The Suppored commandqualifier for Save are
Validate/Process, Validate/NoProcess, NoValidate/Process,
NoValidate/NoProcess default is Validate/Process-->
<ExternalKeys>
<Key name="MASTERCATALOGNAME"
type="string">Customer</Key>
<Key name="PRODUCTID" type="string">2</Key>
<Key name="PRODUCTIDEXT" type="string">2-Ext</Key>
</ExternalKeys>
<EntityData>
<Attribute name="PRODUCTIDEXT"
type="string">1</Attribute>
<Attribute name="PRODUCTID"
type="string">1-Ext</Attribute>
<Attribute name="SHORTDESC" type="string">Customer
repository records</Attribute>
</EntityData>
</MasterCatalogRecord>
</Command>
</Transaction>
TIBCO MDM Web Services Guide
Transaction Atomicity for Record Web Services
|
113
Result All the commands are processed as a single atomic operation. Records are
successfully modified. If any of the commands in a transaction fails, the
transaction is not processed and the records are not added or modified. The
transaction may fail because the non-supported command qualifier or an
erroneous rulebase exists in a command.
Scenario 2: Large Number of Modified Records
In this scenario, you can process multiple CUD commands with the sizeable
amount of records and relationships. The Transaction Atomicity feature enforces
consistency between a set of single data changes. Use the Transaction Atomicity
feature to load multiple unrelated records, that is, bulk load. However, the
number of records should not be large, in particular, if these are bundles. For a
single data set, do not load more than 30-50 records in one transaction.
For example, to create a large bundle with a depth of four levels, specify 4 as the
value for the Validation Record Bundle Depth property in Configurator. The
property defines the depth for validations of related records in the bundle. Add
propagation rulebases to affect numerous records. Specify atomic="on" in the
<Transaction> element.
Scenario 3: Same Record in Multiple Commands
In this scenario, you can process the same record in multiple commands within a
transaction. Specify the same record ID or EXT in two separate commands
performing the CUD operation.
Example <Transaction atomic="on">
<Command type="Add">
<!--The Supported CommandTypes for Save are Add and Modify-->
<MasterCatalogRecord etype="Entity"
commandqualifier="Validate/Process">
<!-- The Suppored commandqualifier for Save are
Validate/Process, Validate/NoProcess, NoValidate/Process,
NoValidate/NoProcess default is Validate/Process-->
<ExternalKeys>
<Key name="MASTERCATALOGNAME"
type="string">Customer</Key>
<Key name="PRODUCTID" type="string">Cust-1</Key>
<Key name="PRODUCTIDEXT" type="string">Cust-1-Ext</Key>
</ExternalKeys>
<EntityData>
<Attribute name="FIRSTNAME"
type="string">John</Attribute>
<Attribute name="LASTNAME" type="string">Doe</Attribute>
<Attribute name="DATEOFBIRTH"
type="string">19-05-1950</Attribute>
</EntityData>
</MasterCatalogRecord>
TIBCO MDM Web Services Guide
114
|
Chapter 2 Record Services
</Command>
<Command type="Add">
<!--The Supported CommandTypes for Save are Add and Modify-->
<MasterCatalogRecord etype="Entity"
commandqualifier="Validate/Process">
<!-- The Suppored commandqualifier for Save are
Validate/Process, Validate/NoProcess, NoValidate/Process,
NoValidate/NoProcess default is Validate/Process-->
<ExternalKeys>
<Key name="MASTERCATALOGNAME"
type="string">Customer</Key>
<Key name="PRODUCTID" type="string">Cust-1</Key>
<Key name="PRODUCTIDEXT" type="string">Cust-1-Ext</Key>
</ExternalKeys>
<EntityData>
<Attribute name="FIRSTNAME"
type="string">John</Attribute>
<Attribute name="LASTNAME" type="string">Doe</Attribute>
<Attribute name="DATEOFBIRTH"
type="string">25-09-1960</Attribute>
</EntityData>
</MasterCatalogRecord>
</Command>
</Transaction>
Result Both the records are saved with the respective incremental version.
Scenario 4: Enable Global Distributed Locking
In this scenario, concurrent record web service requests are sent with the multiple
commands in a single transaction. The entire transaction is locked instead of a
separate command specified in the transaction.
1. Before executing this operation, specify true for the Enable Save Lock
property in Configurator. The property enables the locking process.
2. Specify atomic="on" in the <Transaction> element to lock the entire
transaction.
TIBCO MDM Web Services Guide
|
115
Chapter 3 Work Item Services
This chapter describes the usage and customization of work item services.
Topics
Work Item Query Parameters Service, page 116
Work Item Query Service, page 118
Work Item Modify Close Service, page 124
Work Item Lock Service, page 128
Work Item UnLock Service, page 130
Get Work Item Service, page 132
Work Item Reassign Service, page 138
Get Custom Work Item Summary Service, page 140
Get Predefined Work Item Summary Service, page 146
TIBCO MDM Web Services Guide
116
|
Chapter 3 Work Item Services
Work Item Query Parameters Service
This web service can be used to get a list of query parameters supported by the
work item query service. This service also provides valid values, if any, for each of
the supported parameters.
Work Item Query Parameters Service - Inputs
Command type
Command type needs to be set to Query and the entity command qualifier needs
to be Parameters.
<Command type="Query">
<Workitem commandqualifier="Parameters" etype="Entity">
Query Directives
None.
External Keys
None.
Work Item Query/Parameters Service - Outputs
The list of query parameters for work lists supported by the system is returned by
the service.
Entity Data
FromDate The start date from which the work list is required.
ToDate The end date until which the work list is required.
RecordAttribute Value of a record attribute.
Eventreference The ID of the event for which work items need to be
searched.
ShowActionsFirst Specifies whether action items should be shown first.
PRODUCTID ID of the record.
PRODUCTIDEXT Extension of the record. Optionally used to identify a
record.
TIBCO MDM Web Services Guide
Work Item Query Parameters Service
|
117
States The state of the work items.
Datapools Name of the datapool involved in the workflow.
Partners Name of the partner involved in the workflow.
WorkitemTypes Type of work item. Valid values are "Notifications" and
"Action Items".
DocumentTypes The document type associated with the work item.
DocumentSubTypes The document sub type associated with the work
item.
Owners The username of the owner of the work item.
MasterCatalogNames The name of the repository which contains the
records.
In case the query does not have a valid value list, it is represented as an empty
attribute. For example:
<Attribute name=ToDate type="date"/>
TIBCO MDM Web Services Guide
118
|
Chapter 3 Work Item Services
Work Item Query Service
This web service can be used to query work items, based on the search criteria
specified.
Work Item Query Service - Inputs
Command type
Command type needs to be set to Query and the command qualifier must be
empty.
<Command type="Query">
<Workitem etype="Entity">
Query Directives
<MaxCount> can be specified to limit the number of work items returned, should
more than one work item match the query.
<StartCount> can be specified to achieve windowing/pagination of a large result
set. In combination with MaxCount, the caller can control which page of the
result set needs to be returned.
<Command type="Query">
<StartCount>30</StartCount>
<MaxCount>10</MaxCount>
External Keys
The external keys are used to locate list of parameters and their valid values.
Key Meaning Required
STATE
The state of the work items. Optional.
Default is OPEN.
FROMDATE
The start date from which the
work list is required.
Optional.
Default is null (no start date).
TODATE
The end date until which the
work list is required.
Optional.
Default is current date.
TIBCO MDM Web Services Guide
Work Item Query Service
|
119
WORKITEMTYPE
Type of work items being
queried.
Optional.
Valid values are:
Action Items
Notifications
All
Default ALL.
DOCUMENTSUBTYPE
The document sub type. Optional.
Default ALL.
DATAPOOL
The name of the datapool or
integration hub.
Optional
Default ALL.
PARTNER
The name of the partner or
backend system.
Optional.
Default ALL.
SHOWACTIONSFIRST
Whether action items should be
shown first.
Optional.
Default worklist is
unsorted.
OWNER
The username of the owner of
the work item. If the owner is
not the same as the user who
initiated the web service, the
owner must have permissions to
view the work items of other
users.
Optional.
Default The username of
the profile used in the service
request.
RECORDATTRIBUTE
Value of a record attribute.
NOTE: For query by this
parameter to work,
configurations are necessary as
part of the inbox customization.
Optional.
EVENTREFERENCE
Search work items for the
specified event.
Optional.
Key Meaning Required
TIBCO MDM Web Services Guide
120
|
Chapter 3 Work Item Services
CUSTOMATTRIBUTE
Search work items based on
custom attributes. For example,
<Key
name="CustomAttribute">Leg
acySystem</Key>
Optional.
Default is null
NATIVECONDITION
Search work items based on
specified search conditions. You
can specify this key along with
other conditions. The Search
condition must be specified in
the following formats:
Native SQL format valid for
configured database
Only the WHERE clause (Do
not include values to select.)
The WHERE clause must
assume a join on the
WORKITEM and
WORKITEMDETAIL tables.
Alias for the
WORKITEMDETAIL table is
workitemdetail and alias
for the WORKITEM table is
workitem.
The condition is applied as AND
with other conditions and it is
applied without any processing.
If it is invalid, an SQL error is
thrown. The application does not
display the error. For example,
<Key
name="NativeCondition">wor
kitemdetail.name =
'PRODUCTVERSION' and
workitemdetail.value =
2'</Key>
Optional.
Default is null
Key Meaning Required
TIBCO MDM Web Services Guide
Work Item Query Service
|
121
Work Item Query Service - Outputs
The list of work items fitting the given search criteria (using external keys) are
returned in the result.
Entity Data
Each work item returned in the result has the following attributes:
ActivityName Name of the work item activity.
Age Age of the work item. The format of age is D:H:M:S, which refers to
date, hour, month, and seconds.
ClosedBy Login name of the person who closed the work item. Returned
only if workitem is closed.
ClosedByUserName The first name and last name of the person who
closed the work item. Returned only if workitem is closed.
ClosedOn Date on which the work item was closed. Returned only if
workitem is closed.
CreationDate Date on which workitem was created.
Datapool Name of the marketplace involved in the workflow.
Description This is a dynamically generated description based on inbox
configuration. This contains tokens to indicate the type of hyperlinks needed
as part of the description. Please refer the Inbox configuration section for more
details.
DocumentType The document type associated with the work item.
DocumentTypeDescription The description of the document type in the
language of the user.
DocumentSubType The document sub type associated with the work item.
KEYWORD
Search work items based on the
tagged keywords. Keywords are
configured when a work item is
created in the workflow. For
example,
<Key
name="Keyword">HighPriorit
y</Key>
Optional.
Default is null
Key Meaning Required
TIBCO MDM Web Services Guide
122
|
Chapter 3 Work Item Services
DocumentSubTypeDescription The description of the document sub type
in the language of the user.
Eventreference The ID used to reference the event to which a work item
belongs.
Organization Name of the organization to which a work item belongs.
OriginalWorkitemID Only returned if applicable (for reassigned
workitems only).
OriginalOwner Login name of the original owner of the work item.
Returned only if applicable (for reassigned workitems).
OriginalOwnerName The first name and last name of the original owner
of the work item. Returned only if applicable (for reassigned workitems).
Owner The first name and last name of the owner of the work item. This is
useful when the work supervisor wants to look at work items of all users in an
organization.
OwnerName The first name and last name of the owner of the work item.
OwnerType Role/Member.
Partner Name of the trading partner involved in the workflow.
State State of the work item. OPEN/OPEN_TIMEDOUT/CLOSED and so
on.
StateDescription Description of work item state in user preferred
language.
TaskType The type of workflow. Example, CATALOGMESSAGE.
Workitemreference A unique reference for each work item.
WorkitemType Type of work item. Valid values are "Notifications" and
"Action Items".
Records in Work Item
With each work item, the list of records associated with it are also listed. This is
represented as a Relationship of type MasterCatalogRecord.
For more information, refer to Records in Work Item, on page 134 in the Get Work
Item Service.
Datapool and Partner are output only if they are associated with the work item.
TIBCO MDM Web Services Guide
Work Item Query Service
|
123
Work Item Searching
You can search the work item based on a specific criteria. For example, you can
add tags to work items using the CreateWorkitem activity, and then search for it.
Work Item Locking
For more information, refer to Work Item Lock Service, on page 128.
Transaction Result
For more information, refer to TransactionResult, on page 7.
TIBCO MDM Web Services Guide
124
|
Chapter 3 Work Item Services
Work Item Modify Close Service
This web service can be used to close a list of work items.
Work Item Modify/Close Service - Inputs
Command type
Close Work item is closed. The Command type needs to be set to Modify,
and the entity command qualifier needs to be Close.
<Command type="Modify">
<Workitem commandqualifier="Close" etype="Entity">
<Command type="Modify">
<Workitem commandqualifier="Close" etype="Entity"
execmode="SYNCHR">
<Command type="Modify">
<Workitem commandqualifier="Close" etype="Entity"
execmode="ASYNCHR">
Close/Approve Work item is approved. The approval data can be specified
using custom input parameters. If the 'result' custom parameter is specified, it
is ignored.
<Command type="Modify">
<Workitem commandqualifier="Close/Approve" etype="Entity">
Close/Reject Work item is rejected. The rejected data can be specified using
custom input parameters. If the 'result' custom parameter is specified, it is
ignored.
<Command type="Modify">
<Workitem commandqualifier="Close/Reject" etype="Entity">
The work items are closed one by one. If any of the work items cannot be closed, it
is ignored. The number of closed work items is reported in the results along with
the list of errors.
Besides, the Close command qualifier, you can also specify the following
command qualifiers:
CloseAll Closes all work items based on the specified search criteria. All
work items selected using the search criterion are considered for closing.
Similar to Close , any inputs to actionable work items can be supplied. All
closed work items receive same parameters, such as mass approval or
rejections.
<Command type="Modify">
<Workitem commandqualifier="CloseAll" etype="Entity">
TIBCO MDM Web Services Guide
Work Item Modify Close Service
|
125
CloseAll/Approve Approves all work items based on the specified search
criteria except the FormResult custom parameter. If the FormResult custom
parameter is specified, it is ignored.
<Command type="Modify">
<Workitem commandqualifier="CloseAll/Approve"
etype="Entity">
CloseAll/Reject Rejects all work items based on the specified search
criteria except the FormResult custom parameter. If the FormResult custom
parameter is specified, it is ignored.
<Command type="Modify">
<Workitem commandqualifier="CloseAll/Reject"
etype="Entity">
The <MaxCount> refers to the number of closed work items, which limits the total
number of closed work items. The default MaxCount is 20. For example,
<Command type="Modify">
<MaxCount>10</MaxCount>
<Workitem commandqualifier="CloseAll" etype="Entity">
Execution mode
The execmode can be set to either SYNCHR or ASYNCHR. For more information,
refer to Execution Mode, on page 2.
Query Directives
NONE.
External Keys
The external keys are used to locate a work item.
If Close or CloseAll command qualifier is used, the FormResult parameter is
required for actionable work items. As the FormResult parameter is deprecated,
do not use Close and CloseAll for actionable work items; instead use
Close/Approve, Close/Reject, CloseAll/Approve, or CloseAll/Reject.
Key Meaning Required
WORKITEMREFENCE
A reference ID for work item.
This is usually available as a
result of the work item query
service.
Mandatory.
TIBCO MDM Web Services Guide
126
|
Chapter 3 Work Item Services
Accept/Reject, Reason Code and Comment
While closing a work item, the user can indicate if the work item is accepted or
rejected. The user can also provide a reason, code, and comment.
These are captured under the EntityData section.
<EntityData>
<Reasoncode etype="Attribute" type="string">3000</Reasoncode>
<Comment etype="Attribute" type="string"> description</Comment>
<FormResult etype="Attribute" type="string">Reject</FormResult>
<SendForCorrections etype="Attribute"
type="string">N</SendForCorrections>
</EntityData>
A list of work items can be specified in the request, and each of them will be
closed. However, each work item needs to be in its own transaction, that is,
separated by Transaction sections. A work item can be closed even if there are
associated errors or rejections. Ensure that close is not called in such situations.
You can inquire about errors, warnings, and rejections using the GET
WORKITEM service.
Capture Custom User Inputs
While closing work items, additional custom inputs can be specified. Data
provided in this manner is added to workflow request document and can be
processed using the workflow forms.
Example 1:
A work item form can prompt the user to enter a LaunchDate for a set of records;
that can later be used in the workflow. This can be achieved by providing input as
show below.
<EntityData>
<Reasoncode etype="Attribute" type="string">3000</Reasoncode>
<Comment etype="Attribute" type="string">Reject through Web
Service MASS APPROVAL</Comment>
<FormResult etype="Attribute" type="string">Reject</FormResult>
<SendForCorrections etype="Attribute"
type="string">N</SendForCorrections>
<!-- The following are custom fields captured as part of the
work item form -->
<LaunchDate eType="Attribute" type="date">2006 10
12</LaunchDate>
</EntityData>
The above user input is made available in the work item activitys output
document.
TIBCO MDM Web Services Guide
Work Item Modify Close Service
|
127
Example 2:
The custom attributes are used to pass in additional information to the
application so that the values of these attributes can be used to update the
workflow XML document (mlXML). An XPATH expression entry is created in the
specific UI form on how to access these attributes from the request XML. These
extracted values are used to populate the work flow document.
<EntityData>
<Reasoncode etype="Attribute" type="string">3000</Reasoncode>
<Comment etype="Attribute" type="string">Reject through Web
Service MASS APPROVAL</Comment>
<FormResult etype="Attribute" type="string">Reject</FormResult>
<SendForCorrections etype="Attribute"
type="string">N</SendForCorrections>
<!-- The following are custom fields captured as part of the
work item form -->
<raiseAlarm eType="Attribute" type="string">alarm1</raiseAlarm>
</EntityData>
When FormResult is passed in a Accept, SendForCorrections is not considered.
When FormResult is passed in a Reject, SendForCorrections is considered.
All custom attributes, such as the one above, need to be specified in the
$MQ_HOME/common/standard/forms/fm26ca.xml, with the XPath as
//Field/ID[text()=CustomAttribute]/../OutputTo.
Work Item Modify/Close Service - Outputs
The service attempts to close the work item. If any errors occur (example a non
admin trying to close someone elses work item), they are returned as part of the
response.
ResultList
For more information, refer to ResultList, on page 7.
Transaction Result
For more information, refer to TransactionResult, on page 7.
Since release 8.2.0 onwards, the <FormResult etype="Attribute"
type="string">Reject</FormResult> is deprecated.
TIBCO MDM Web Services Guide
128
|
Chapter 3 Work Item Services
Work Item Lock Service
This web service allows you to lock and relock a work item to prevent other users
from opening the work item.
Locking
A "shared" work item is created when a workflow assigns work items to more
than one user in a single work item step. By locking the work item, the user can
indicate that he/she has started working on it and other users should wait for
him/her to complete or unlock the work item. This applies to scenarios when
work items are assigned to a pool of users, all of whom cannot work on the task in
parallel.
If a work item is locked by a user, other users can see the work item in the Inbox
but cannot open it. A work supervisor, however, can lock the work item for any
user. A work supervisor can see the work item in the inbox, open it, and make
changes to records within the work item even if it is locked by another user.
However, such work items cannot be submitted.
Work item locking only applies to actionable work items, and has no impact on
notification work items.
When a work item is locked through a web service, the UI shows the lock status.
Also, the work item query and get services return the details of the lock in the
response.
A locked work item can be reassigned. Reassignment of a work item, generally,
releases the lock on that work item.
Work item locking is enabled by default.
Relocking
Relocking allows you to renew an already existing lock. Expiry parameters such
as interval and so on are renewed based on the defaults specified in the
Configurator.
If the Default Work Item Lock Expiry Method is set to None in the Configurator,
a relock attempt from web services is ignored and success is returned.
The Work Item Query service returns the Lock status for a work item in response
to the state of the work item. For more details, refer to Work Item Query Service,
page 118.
TIBCO MDM Web Services Guide
Work Item Lock Service
|
129
Work Item Lock Service - Inputs
Command type
For both locking and relocking, the Command type needs to be set to Modify,
and the entity command qualifier needs to be Lock.
<Command type="Modify">
<Workitem commandqualifier="Lock" etype="Entity">
Query Directives
NONE.
External Keys
The external keys are used to locate a work item.
Work Item Lock Service - Outputs
The service attempts to lock the work item. If any errors occur (example a non
admin trying to lock someone elses work item), they are returned as part of the
response.
ResultList
For more information, refer to ResultList, on page 7.
Transaction Result
For more information, refer to TransactionResult, on page 7.
Key Meaning Required
WORKITEMREFENCE
A reference ID for each work
item. This is usually available as
a result of the work item query
service.
Mandatory.
TIBCO MDM Web Services Guide
130
|
Chapter 3 Work Item Services
Work Item UnLock Service
This web service allows you to release the lock on a work item. The work item is
unlocked and other users of the shared work item are given access to it.
A work item lock is released:
When a work item expires or times out, it is automatically unlocked. This can
be controlled by the Enable Release of Work Item Lock on Timeout property
in the Configurator.
When you close a work item, it is automatically unlocked and closed. Closing
a work item is allowed only if there is no lock or if the lock is placed by the
user who issued the close request. After the work item is closed, the lock is
released. The service does not allow a locked work item to be closed, except
by the owner of the lock or any user with the relevant permissions. If this
happens, the following response is returned to the caller of the service:
The work item is locked and cannot be closed.
When a locked work item is reassigned, even if the user doing the
reassignment does not own the work item.
Work Item UnLock Service - Inputs
Command type
The Command type needs to be set to Modify, and the entity command qualifier
needs to be UnLock.
<Command type="Modify">
<Workitem commandqualifier="UnLock" etype="Entity">
Query Directives
NONE.
TIBCO MDM Web Services Guide
Work Item UnLock Service
|
131
External Keys
The external keys are used to locate a work item.
Work Item UnLock Service - Outputs
The service attempts to close the work item. If any errors occur (example a non
admin trying to close someone elses work item), they are returned as part of the
response.
ResultList
For more information, refer to ResultList, on page 7.
Transaction Result
For more information, refer to TransactionResult, on page 7.
Key Meaning Required
WORKITEMREFENCE
A reference ID for each work
item. This is usually available as
a result of the work item query
service.
Mandatory.
TIBCO MDM Web Services Guide
132
|
Chapter 3 Work Item Services
Get Work Item Service
This web service allows you to get details of a work item. The details include the
following:
Work item data
Work item lock details
Comment history
Primary and associated records. For each record, operational data is also
included.
Miscellaneous data from the WORKITEMDETAIL table
Get Work Item Service - Inputs
Command Type
Command type needs to be set to Get. There is no command qualifier.
<Command type="Get">
<Workitem etype="Entity">
You can specify more than one entity. To retrieve multiple work items, specify
multiple transactions or multiple entities in each transaction.
Query Directives
NONE.
External Keys
Each Get request must specify exactly one external key as follows:
You can execute this web service only if you own the work item or you have the
permissions to view, reassign, and close work items assigned to other users.
Key Meaning Required
WORKITEMREFERENCE
Specifies the work item to be
retrieved.
Mandatory.
TIBCO MDM Web Services Guide
Get Work Item Service
|
133
Get Work Item Service - Outputs
Details of the specified work item are returned. The following data is returned:
Entity data
Comment history
Records in work item
Operational Data
Context Data
Work Item Locking
PREVIOUSREJECTIONS
Specifies whether the rejection
alerts generated in the previous
step (rejection) are to be
retrieved.
By default, the rejection alerts
generated in the previous step
are retrieved.
The previous alerts are obtained
based on reference step ID
specified as input to the
CreateWorkitem activity:
1. If reference step ID is not
specified, the current step is
always used irrespective of
the previous rejections
indicator.
2. If reference step ID is
specified, and previous
rejections is specified as true
or not specified (default is
true), reference step ID is
used to get rejections.
3. If reference step ID is
specified, and previous
rejections is specified as
false, current step id is used
to get rejections.
Optional.
Key Meaning Required
TIBCO MDM Web Services Guide
134
|
Chapter 3 Work Item Services
Result List
Transaction Result
Entity Data
For a list of attributes returned in the result, refer to Entity Data, on page 121.
Comment History
For more information, refer to Comment History, on page 8.
Records in Work Item
A list of primary and associated records is provided.
The primary record is identified by the <Primary>true</Primary> element.
Associated records are those records for which a product log exists for the process
log of the work item step.
The following information for each record is included:
MASTERCATALOGNAME
PRODUCTID
PRODUCTIDEXT
MODVERSION
Records are returned only if there is a primary record associated with the work
item. A work item generated for batch record processing, import, data source
import, mass update, or a work item which does not have any associated records
will not have records as output.
The record data itself is NOT returned.
Operational Data
The operational data associated with a record includes the details of the action
taken on the record and any alerts associated with the records. Possible alerts are
rejections, warnings, and errors. The data is stored in the PRODUCTLOG table.
Operational data includes the following:
Primary Identifies the primary record in the list. Records are returned only
if there is a primary record associated with the work item.
Operation Identifies the operation being performed. For example, EDIT
PRODUCT.
TIBCO MDM Web Services Guide
Get Work Item Service
|
135
OperationDescription Detailed description of the operation being
performed.
Suboperation Identifies the sub-operation being performed. For example,
INITIAL VERSION.
SuboperationDescription Detailed description of the sub-operation being
performed.
OperationDate Date and time on which the operation was performed.
Alerts Count of the different alerts generated.
RejectionCount: Count of rejection entries added by an editor or approver
as a part of the "Rejection" process.
ErrorCount: Count of errors generated when a validation rule is run. The
errors are pre-computed and stored in the attributeLog table.
WarningCount: Count of warnings generated when a validation rule is run.
The warnings are pre-computed and stored in the attributeLog table.
For example:
<OperationData>
<Primary>true</Primary>
<Operation>EDIT PRODUCT</Operation>
<OperationDescription
lang="en">Add/ModifyRecord</OperationDescription>
<Suboperation>INITIAL VERSION</Suboperation>
<SuboperationDescription lang="en">Initial
Version</SuboperationDescription>
<OperationDate>2009-02-19 09:19:13-08:00</OperationDate>
<Message></Message>
<Alerts>
<RejectionCount>0</RejectionCount>
<ErrorCount>0</ErrorCount>
<WarningCount>0</WarningCount>
</Alerts>
</OperationData>
Context Data
Data captured in WORKITEMDETAIL table is returned as name value pair here.
Data returned depends on the work item and configuration. All data is returned
as a String and all names are in upper case.
Context data includes the following attributes. However, as a workflow can be
customized to capture additional data, this is list is not exhaustive. Not all work
items will have all the attributes listed. Only those attributes which are relevant
are returned.
CATALOGEDITIONID Synchronization profile ID associated
TIBCO MDM Web Services Guide
136
|
Chapter 3 Work Item Services
CATALOGEDITIONVERSION synchronization profile version associated
Custom_* Custom information passed in to work item activity
EXPIRYTYPE Work item expiry type
INTENT Work item intent configured in the workflow
MASTERCATALOGID ID of the repository associated
MASTERCATALOGVERSION Version of the repository associated
MESSAGEID Any message ID is associated with work item. This is,
usually, the case for work items which are created using the WaitForResponse
activity.
NUMBEROFTIMEOUTS Number of timeouts for work item
RECORD_COUNT Number of records associated with the work item
when the work item was created
RESULTDECISION Decision taken on the work item
SUCCESS_COUNT Number of records considered as success. The count is
calculated when the work item is created.
SEVERITY Any severity associated
WORKITEMSTEP Step number
VALIDATIONWARNINGS Number of records which had warnings, only
applicable for batch processing activities related work items (Import
approval). The count is calculated when a work item is created.
For example:
<ContextData>
<Attribute name="NUMBEROFTIMEOUTS" type="string">1</Attribute>
<Attribute name="COMPAREKEYWOR"
type="string">PREVIOUS_CONFIRMED_VERSION</Attribute>
<Attribute name="EXPIRTYTYPE" type="string">RELATIVE</Attribute>
<Attribute name="INTENT" type="string">Edit</Attribute>
<Attribute name="RECORD_COUNT" type="string">1</Attribute>
</ContextData>
Work Item Locking
For more information, refer to Work Item Lock Service, on page 128.
ResultList
For more information, refer to ResultList, on page 7.
TIBCO MDM Web Services Guide
Get Work Item Service
|
137
Transaction Result
For more information, refer to TransactionResult, on page 7.
TIBCO MDM Web Services Guide
138
|
Chapter 3 Work Item Services
Work Item Reassign Service
This web service is used to reassign a work item to another user.
When a work item is reassigned from the user interface, you can reassign the
work item to specific users as controlled by the role delegation. However, when
using this web service, you can reassign the work item to any valid user. The
target user is not limited by role delegation setup.
Once reassigned, the work item is closed and a new work item is created for the
target user. The status of the work item is the same as the original work item. For
example, if the original work item was timed out, the new work item will also be
timed out. If the target user has delegated the work item s to other users by setting
up role delegation, more than one new work items may also be created. In this
case, the work items are created for final users in the delegation chain.
Any existing lock is released when a work item is reassigned only if the lock is
held by the owner of the work item.
Data for all newly created work items is returned in the response XML.
Work Item Reassign Service - Inputs
Command Type
Command type needs to be set to Reassign. There is no command qualifier.
<Command type="Reassign">
<Workitem etype="Entity">
Query Directives
NONE.
You can reassign a work item only if you own the work item or you have work
item permissions.
You cannot specify multiple entities in one transaction. To reassign more than one
work item, create multiple transactions.
TIBCO MDM Web Services Guide
Work Item Reassign Service
|
139
External Keys
Each web service request must have external keys. The external keys have the
following semantics:
Work Item Reassign Service - Outputs
Based on the user and WorkitemID specified in the external keys, data for all
newly created work items is returned in the response XML.
Entity Data
For a list of attributes returned in the result, refer to Entity Data, on page 121.
Records in Work Item
With each work item, the list of records associated with it are also listed.
ResultList
For more information, refer to ResultList, on page 7.
Transaction Result
For more information, refer to TransactionResult, on page 7.
Key Meaning Required
WORKITEMREFERENCE
Specifies the work item to be
retrieved.
Mandatory.
USER
Specifies the user to whom the
work item is to be reassigned.
Mandatory.
TIBCO MDM Web Services Guide
140
|
Chapter 3 Work Item Services
Get Custom Work Item Summary Service
This web service allows you to get details of work item summary for a single or
multiple summary preferences. The details include the following:
Summary Preference Name
Level details included in the specified summary preference, such as Level
name, depth, count, and its value count
True or false value to include all users.
To use this web service:
1. Specify the user details such as user name, password, and enterprise name for
the user.
2. Specify the summary preference name. For example,
<ns:PreferenceName>Pref-1</ns:PreferenceName>.
3. Specify the level name. For example,
<ns:LevelOrder>
<ns:Name>user</ns:Name>
</ns:LevelOrder>
You can specify multiple levels. Use the following list of level names:
State
Intent
Repository
ActivityName
TaskType
Result
DocType
DocSubType
Actionable (Workitem Type)
User
ClosedBy
Only the Work Supervisor role has right to specify value for
<ns:IncludeAllUsers></ns:IncludeAllUsers> tag.
TIBCO MDM Web Services Guide
Get Custom Work Item Summary Service
|
141
For more details on these levels, refer to the TIBCO MDM Users Guide.
4. Specify true or false to indicate if the preference must sum all users or not. For
example, <ns:IncludeAllUsers>true</ns:IncludeAllUsers>
5. Repeat from step 2 to step 4 to specify multiple summary preferences. For
example, Pref-2, Pref-3, and so on.
6. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/DataService/getWorkitem
SummaryAction
The custom work item summary details are returned in response.
A sample XML for a single custom work item summary is available in
$MQ_HOME/schema/DataService/2.0/samples/workitem/WorkitemSummary/
GetCustomWorkitemSummary-request.xml
$MQ_HOME/schema/DataService/2.0/samples/workitem/WorkitemSummary/
GetCustomWorkitemSummary-response.xml
TIBCO MDM Web Services Guide
142
|
Chapter 3 Work Item Services
A sample XML for multiple custom work item summary is available in
$MQ_HOME/schema/DataService/2.0/samples/workitem/WorkitemSummary/
GetMultipleCustomWorkitemSummary-request.xml
$MQ_HOME/schema/DataService/2.0/samples/workitem/WorkitemSummary/
GetMultipleCustomWorkitemSummary-response.xml
Get Custom Work Item Summary Service - Inputs
The following inputs are mandatory for this web service:
Get Custom Work Item Summary Service - Outputs
Details of the specified custom work item summary are returned such as
preference name, level depth and count, total number of work items available
with the specified criteria, and then level details for each custom work item
summary.
Example 14 Custom Work Item Summary with a single preference and level
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:WorkitemSummaryResponse
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<ns:WorkitemSummaryPreference type="CUSTOM">
<ns:Name>Pref-1</ns:Name>
<ns:DisplayName>Pref-1</ns:DisplayName>
<ns:LevelDepth>1</ns:LevelDepth>
<ns:Level count="5">
<ns:Order>0</ns:Order>
Input Description
User Name The name of the currently logged-in user.
Password Password of the currently logged-in user.
Enterprise Name Name of the enterprise for which the user is created. This is
not required if the new user is created in the same directory
as the logged-in user.
Preference Name Name of the work item summary preference.
Level Name Name of the preference level.
IncludeAllUsers Specify true or false if the work item summary is required
for all users or not.
TIBCO MDM Web Services Guide
Get Custom Work Item Summary Service
|
143
<ns:Type>REPOSITORY</ns:Type>
<ns:DisplayName>Repository</ns:DisplayName>
<ns:Values>
<ns:Value count="1">
<ns:Name>2147484058</ns:Name>
<ns:DisplayName>ACCOUNT</ns:DisplayName>
</ns:Value>
</ns:Values>
<ns:Values>
<ns:Value count="1">
<ns:Name>2147484072</ns:Name>
<ns:DisplayName>EMAIL</ns:DisplayName>
</ns:Value>
</ns:Values>
<ns:Values>
<ns:Value count="2">
<ns:Name>2147484043</ns:Name>
<ns:DisplayName>MC1</ns:DisplayName>
</ns:Value>
</ns:Values>
<ns:Values>
<ns:Value count="1">
<ns:Name>2147484050</ns:Name>
<ns:DisplayName>PERSON</ns:DisplayName>
</ns:Value>
</ns:Values>
</ns:Level>
<ns:IncludeAllUsers>true</ns:IncludeAllUsers>
</ns:WorkitemSummaryPreference>
</ns:WorkitemSummaryResponse>
</soapenv:Body>
</soapenv:Envelope>
TIBCO MDM Web Services Guide
144
|
Chapter 3 Work Item Services
Example 15 Custom Work Item Summary with multiple preferences and levels
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:WorkitemSummaryResponse
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<ns:WorkitemSummaryPreference type="CUSTOM">
<ns:Name>Pref-1</ns:Name>
<ns:DisplayName>Pref-1</ns:DisplayName>
<ns:LevelDepth>2</ns:LevelDepth>
<ns:Level count="5">
<ns:Order>0</ns:Order>
<ns:Type>STATE</ns:Type>
<ns:DisplayName>State</ns:DisplayName>
<ns:Values>
<ns:Value count="5">
<ns:Name>OPEN_TIMEDOUT</ns:Name>
<ns:DisplayName>Timed out</ns:DisplayName>
<ns:Level count="5">
<ns:Order>0</ns:Order>
<ns:Type>INTENT</ns:Type>
<ns:DisplayName>Intent</ns:DisplayName>
<ns:Values>
<ns:Value count="5">
<ns:Name>Edit</ns:Name>
<ns:DisplayName>Edit</ns:DisplayName>
</ns:Value>
</ns:Values>
</ns:Level>
</ns:Value>
</ns:Values>
</ns:Level>
<ns:IncludeAllUsers>true</ns:IncludeAllUsers>
</ns:WorkitemSummaryPreference>
<ns:WorkitemSummaryPreference type="CUSTOM">
<ns:Name>Pref-4</ns:Name>
<ns:DisplayName>Pref-4</ns:DisplayName>
<ns:LevelDepth>1</ns:LevelDepth>
<ns:Level count="3">
<ns:Order>0</ns:Order>
<ns:Type>USER</ns:Type>
TIBCO MDM Web Services Guide
Get Custom Work Item Summary Service
|
145
<ns:DisplayName>User</ns:DisplayName>
<ns:Values>
<ns:Value count="3">
<ns:Name>2147484049</ns:Name>
<ns:DisplayName>Smith,John</ns:DisplayName>
</ns:Value>
</ns:Values>
</ns:Level>
<ns:IncludeAllUsers>false</ns:IncludeAllUsers>
</ns:WorkitemSummaryPreference>
</ns:WorkitemSummaryResponse>
</soapenv:Body>
</soapenv:Envelope>
TIBCO MDM Web Services Guide
146
|
Chapter 3 Work Item Services
Get Predefined Work Item Summary Service
This web service allows you to get details of summaries for all preferences, which
are created through UI. For more details, refer to the TIBCO MDM Users Guide.
To use this web service:
1. Specify the user details such as user name, enterprise name, and password for
the user.
2. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/DataService/getWorkitem
SummaryAction
The work item summary details for all predefined summary preferences are
returned in response.
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/workitem/WorkitemSummary/
GetPredefinedWorkitemSummary-request.xml
$MQ_HOME/schema/DataService/2.0/samples/workitem/WorkitemSummary/
GetPredefinedWorkitemSummary-response.xml
Get Predefined Work Item Summary Service - Inputs
The following inputs are mandatory for this web service:
Do not specify anything in the
<ns:PredefinedSummary></ns:PredefinedSummary> tag, else an error message
is returned in response.
Input Description
User Name The name of the currently logged-in user.
Password Password of the currently logged-in user.
Enterprise
Name
Name of the enterprise for which the user is created. This is
not required if the new user is created in the same directory as
the logged-in user.
Predefined
Summary
Refers to all defined work item summary preferences.
TIBCO MDM Web Services Guide
Get Predefined Work Item Summary Service
|
147
Get Predefined Work Item Summary Service - Outputs
Details of the specified work item summary preference are returned, such as
repository name or user name and its level details. For example,
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:WorkitemSummaryResponse
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<ns:WorkitemSummaryPreference type="PREDEFINED">
<ns:Name>Pref-1</ns:Name>
<ns:DisplayName>Pref-1</ns:DisplayName>
<ns:LevelDepth>1</ns:LevelDepth>
<ns:Level count="3">
<ns:Order>0</ns:Order>
<ns:Type>REPOSITORY</ns:Type>
<ns:DisplayName>Repository</ns:DisplayName>
<ns:Values>
<ns:Value count="1">
<ns:Name>2147484058</ns:Name>
<ns:DisplayName>ACCOUNT</ns:DisplayName>
</ns:Value>
</ns:Values>
<ns:Values>
<ns:Value count="1">
<ns:Name>2147484072</ns:Name>
<ns:DisplayName>EMAIL</ns:DisplayName>
</ns:Value>
</ns:Values>
<ns:Values>
<ns:Value count="1">
<ns:Name>2147484050</ns:Name>
<ns:DisplayName>PERSON</ns:DisplayName>
</ns:Value>
</ns:Values>
</ns:Level>
<ns:IncludeAllUsers>false</ns:IncludeAllUsers>
</ns:WorkitemSummaryPreference>
</ns:WorkitemSummaryResponse>
</soapenv:Body>
</soapenv:Envelope>
TIBCO MDM Web Services Guide
148
|
Chapter 3 Work Item Services
TIBCO MDM Web Services Guide
|
149
Chapter 4 Administration Services
This chapter describes the usage and customization of administration services.
Topics
Login Service, page 150
Logout Service, page 151
Get Entitlement Service, page 152
Create Enterprise Service, page 155
Get Enterprise List Service, page 157
Create User Service, page 159
Modify User Service, page 164
Change Password Service, page 170
Delete User Service, page 172
Get User List Service, page 174
Get Role List Service, page 176
TIBCO MDM Web Services Guide
150
|
Chapter 4 Administration Services
Login Service
This service allows you to login to TIBCO MDM after authenticating the specified
credentials. This service also creates a session and returns the sessionId. The
sessionId can be used by any client such as TIBCO BusinessWorks or TIBCO
General Interface. The session is maintained by the URL rewriting mechanism.
Also, if cookies are enabled for a browser-based soap client, it is not mandatory to
send the sessionId in URL.
To use this web service:
1. Specify the user name, password, and enterprise for the user.
2. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/AdminService/loginActio
n
A new HTTP session is created.
The specified user must be able to log on to TIBCO MDM successfully and the
response returns the session ID.
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/admin/Login-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/Login-Response.xml
Many web services in TIBCO MDM are SSO enabled. For more details, refer to,
Authentication, on page 18.
Login Service - Inputs
The following inputs are mandatory for this web service:
Login Service - Outputs
A success or failure message is returned. For more information on failure
messages, refer to Table 11, Faults of Administrator Web Services, on page 26.
Input Description
User name Login ID of the user.
Password Password for the specified user name.
Enterprise Name of the enterprise.
TIBCO MDM Web Services Guide
Logout Service
|
151
Logout Service
This service allows you to logout from the user session for the maintained session.
The session is maintained either by URL re-writing mechanism or through
cookies.
To use this web service:
1. Specify the user name, password, and enterprise for the user.
2. Invoke the web service.
For a cookies-enabled browser client, specify the endpoint URL as:
http://<servername>:<port>/eml/services/AdminService/logout
Action
For a client where cookies are disabled or for a client which does not
operate with a browser (for example: TIBCO BusinessWorks), use
jsessionid as a part of the URL:
http://<servername>:<port>/eml/services/AdminService/logoutA
ction;jsessionid=T2yJKLDPzSY4CjcbzpG3gGm2qlqmGb4MzlGpSsv5Gsw
xnPZXKBKc!-1102618730!1242055503359
The specified user logs out from TIBCO MDM.
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/admin/Logout-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/Logout-Response.xml
Logout Service - Inputs
The following inputs are mandatory for this web service:
Logout Service - Outputs
If a session is not present, an "Invalid session" message is returned. For more
information on failure messages, refer to Table 11, Faults of Administrator Web
Services, on page 26.
Input Description
User name Login ID of the user.
Password Password for the specified user name.
Enterprise Name of the enterprise.
TIBCO MDM Web Services Guide
152
|
Chapter 4 Administration Services
Get Entitlement Service
This service allows you to retrieve entitlement information for a specified user.
Entitlement information includes user permissions, roles assigned, and functions
assigned to the user.
This service lists permissions at the user-level only and not at a role-level. If a
permission is denied at a role level and you run the Get Entitlement service, the
permission is displayed as allowed even though it is denied at the role-level.
You do not require any special privileges to retrieve your own entitlement
information. For information on authentication of Get Entitlement Service, refer
to Table 6, Authentication of Administrator Web Services, on page 20.
To use this web service:
1. Specify the user name, password, and enterprise for the user.
2. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/AdminService/getEntitle
mentAction
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/admin/GetEntitlement-request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/GetEntitlement-response.xml
Restricting Access to Entitlement Information
To restrict an user from getting entitlement information, run the following query
in the SQL editor:
1. Create the function in the function table:
insert into FUNCTION (NAME, DESCRIPTION, FUNCTION) values
('allow_view_entitlement', 'Allow viewing entitlement
information', ' allow_view_entitlement')
2. Identify for which role the function is to be restricted:
insert into ROLE2FUNCMAP(ID, ROLEID, FUNCID, NAME,
PRIORITY)values(select max(id)+1 from
ROLE2FUNCMAP,1234,'allow_view_entitlement', 'Catalog Approver')
3. To inactivate or disable the function allow_view_entitlement for a
particular user, restart the server after running the query. Similarly, when you
want to enable the allow_view_entitlement function for a particular user,
restart the server after running the query.
TIBCO MDM Web Services Guide
Get Entitlement Service
|
153
Get Entitlement Service - Inputs
The following inputs are required when entitlement information for other users
needs to be retrieved. If this input is not specified, entitlement information for the
currently logged in user is displayed.
Get Entitlement Service - Outputs
The response message provides information about:
All roles assigned For example, the following information is returned for
each role.
<ns:Roles>
<ns:Role id="34018">
<ns:Name>Admin</ns:Name>
<ns:Description lang="en">Default Admin Role</ns:Description>
</ns:Role>
</ns:Roles>
All accessible functions For example, the following information is
returned for each function.
<ns:Functions>
<ns:Function id="61">
<ns:Name>adminmenu_roles</ns:Name>
<ns:Description lang="en">Roles menu</ns:Description>
</ns:Function>
</ns:Functions>
Input Description
User Name Login ID of the user.
Password Password for the specified user name.
Enterprise Name of the enterprise.
User Name for
Entitlement
Name of the user for whom entitlement information
is to be retrieved.
Enterprise for
Entitlement
Name of the enterprise.
TIBCO MDM Web Services Guide
154
|
Chapter 4 Administration Services
Access permissions for all resources For example, the following
information is returned for permissions. Note that the service calculates
cumulative user permission for a resource. For example, user "A" is assigned
user level permission to allow browse for resource repository "MC1". User "A"
is also assigned two roles, "Catalog Manager" and "Catalog Edition" and both
roles are denied permission for resource "MC1". Only the permissions at the
user level are populated in the response file. Also, note that, if "Full control"
permission is assigned to a given resource, the rest of the permissions are not
populated in the response.
<ns:Resource id="34190" resourceType="Repository">
<ns:Name>MC1</ns:Name>
<ns:Accesses>
<ns:Access id="A">
<ns:Description lang="en">Full Control</ns:Description>
<ns:Allowed>Y</ns:Allowed>
</ns:Access>
</ns:Accesses>
</ns:Resource>
For information on failure messages, refer to Table 11, Faults of Administrator
Web Services, on page 26.
TIBCO MDM Web Services Guide
Create Enterprise Service
|
155
Create Enterprise Service
This service allows you to create an enterprise in TIBCO MDM.
For information on authentication of Create Enterprise Service, refer to Table 6,
Authentication of Administrator Web Services, on page 20.
To use this web service:
1. Specify the user details such as user name, password, and enterprise for the
user.
2. Specify the enterprise details such as enterprise name, enterprise internal
name, and its industry vertical.
3. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/AdminService/enterpriseA
dminAction/createEnterpriseAction
The specified enterprise is created in TIBCO MDM.
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/admin/CreateEnterprise_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/CreateEnterprise_Response.xml
Create Enterprise Service - Inputs
The following inputs are required for this web service:
Input Description
User Name Login ID of the user.
Password Password for the specified user name.
Enterprise Name of the enterprise of the Super User, Work
Supervisor, or Administrator.
Name
(Mandatory)
Name of the enterprise that is to be created.
Internal Name
(Mandatory)
Internal name of the enterprise.
TIBCO MDM Web Services Guide
156
|
Chapter 4 Administration Services
Create Enterprise Service - Outputs
If an enterprise is created, the "Enterprise Created Successfully" message is
returned.
For information on failure messages, refer to Table 11, Faults of Administrator
Web Services, on page 26.
Industry Vertical
(Optional)
Industry vertical name of the enterprise. For
example, Supplier.
Input Description
TIBCO MDM Web Services Guide
Get Enterprise List Service
|
157
Get Enterprise List Service
This service allows you to get a list of enterprises that are created in TIBCO MDM.
When deploying rulebases and workflows from TIBCO MDM Studio,
administrator needs to specify a user list of enterprises to which the rulebase and
workflow can be deployed. This service is used in the Network Deployment
wizard.
For information on authentication of Get Enterprise Service, refer to Table 6,
Authentication of Administrator Web Services, on page 20.
To use this web service:
1. Specify the user details such as user name, enterprise name, and password for
the user.
2. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/AdminService/GetEnterprise
ListAction
A list of all enterprises is returned in response. However, if the administrator
or work supervisor executes this web service, a list of a particular enterprise
that he/she belongs to is returned.
If the user does not have access to the Administration menu, an error message
is returned in response.
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/admin/GetEnterpriseList-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/GetEnterpriseList-Response.xml
Get Enterprise List Service - Inputs
The following inputs are mandatory for this web service:
Input Description
User Name The name of the currently logged-in user.
Enterprise
Name
Name of the enterprise for which the user is created.
Password Password of the currently logged-in user.
TIBCO MDM Web Services Guide
158
|
Chapter 4 Administration Services
Get Enterprise List Service - Outputs
A list of enterprises is returned. For each enterprise, the enterprise name and
industry vertical details are returned.
If other than Administrator and Super User invokes this web service, the
authentication failure message is returned. For information on failure messages,
refer to Table 11, Faults of Administrator Web Services, on page 26.
TIBCO MDM Web Services Guide
Create User Service
|
159
Create User Service
Using this web service, you can create a user in an existing Enterprise.
For information on authentication of Create User Service, refer to Table 6,
Authentication of Administrator Web Services, on page 20.
To use this web service:
, su
1. Specify user details such as, the user name, password, and enterprise for the
user.
2. Specify new user details that you want to create such as, the user name,
enterprise, security type, first name, last name, middle name, and password.
3. Specify true in the <IsEncrypted> attribute and the encrypted password in
the <Password> attribute.
4. Specify role details of a user such as, the repository editor, repository
manager, and so on.
5. Specify local information such as, the language, country, date format, time
format, timestamp format, and timezone.
6. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/AdminService/userAdminA
ction/createUserAction
The new user is created in an existing enterprise.
The Username can accept the following special characters as a part of the name:
* (asterisk)
. (period)
- (minus)
@ (at)
/ (Forward Slash)
\ (Backward Slash)
These special characters are accepted when you enter the user name while adding
permissions, roles, and users. These can be used when referring to the user name
in a dataset of a File Watcher and also while referring to the user name in a
workflow.
TIBCO MDM Web Services Guide
160
|
Chapter 4 Administration Services
The following are sample XML files:
$MQ_HOME/schema/DataService/2.0/samples/admin/CreateUser_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/CreateUser_Response.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/CreateUser_encryptedPass
word-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/CreateUser_encryptedPass
owrd-Response.xml
Create User Service - Inputs
The following inputs are required for this web service:
Input Description
UserName
(Mandatory)
Login ID of the Super User, Work Supervisor, or
Administrator.
Password
(Mandatory)
Password for the specified user name.
Enterprise
(Mandatory)
Name of the enterprise of the Super User, Work
Supervisor, or Administrator.
UserName
(Mandatory)
Unique name for the new user.
Firstname
(Mandatory)
First name of the user.
Lastname
(Mandatory)
Last name of the user.
Password
(Mandatory)
Password for the new user name.
Note: This input is not mandatory, if you select the
Security Type as LDAP.
Enterprise
(Mandatory)
Name of the enterprise for which the user is created.
Note: This input is not required if you want to create
a new user in the same enterprise where the user is
logged-in.
TIBCO MDM Web Services Guide
Create User Service
|
161
IsEncrypted Specify true if you want the password in the
encrypted format.
Specify false if you do not want the password in the
encrypted format.
Password
(Mandatory)
Specify the password that you want to update.
Note: If you have specified true for the
IsEncrypted attribute, specify the encrypted
password. While logging into TIBCO MDM from UI
as well as from the web service, specify the
decrypted form of a password.
If you have specified false for the IsEncrypted
attribute, specify the plain text password. While
logging into TIBCO MDM from UI as well as from
the web service, specify the as is password
mentioned in the request file.
Securitytype
(Mandatory)
Type of security.
Allowed Values are Password or LDAP. If you select
the LDAP security type, the user must already exist
in the LDAP directory server.
Roles
(Mandatory)
Role for the user name should be specified from the
existing roles specified for the Enterprise.
Language
(Optional)
Only a language supported by TIBCO MDM is
accepted. This input is mandatory if country is
specified. Country can be kept blank with language
value specified.
Country
(Optional)
Name of the country of the new user. Language is
mandatory if country is specified.
Input Description
TIBCO MDM Web Services Guide
162
|
Chapter 4 Administration Services
DateFormat
(Optional)
Only a date format value supported by TIBCO MDM
is accepted. By default, DD-MM-YY value is specified
in the request XML file. You can change the specified
date format. The supported date format values are:
MM/DD/YYYY
DD-MON-YYYY
MM/DD/YY
DDMMYYYY
YYYY-MM-DD
YYYY/MM/DD
DD-MM-YYYY
DD/MM/YYYY
DD-MM-YY
TimeFormat
(Optional)
Only a time format value supported by TIBCO MDM
is accepted. By default, hh:mm:ss value is specified
in the request XML file. You can change the specified
time format. The supported time format values are:
hh:mm:ss (24 hours)
hh:mm:ss AM/PM (12 hours)
Input Description
TIBCO MDM Web Services Guide
Create User Service
|
163
Create User Service - Outputs
If a user is created, the "User Created Successfully" message is returned.
For information on failure messages, refer to Table 11, Faults of Administrator
Web Services, on page 26.
TimestampFormat
(Optional)
Timezone
(Optional)
Only a timestamp format value supported by TIBCO
MDM is accepted. By default, YYYY-MM-DD
hh:mm:ss.S value is specified in the request XML
file. You can change the specified timestamp format.
The supported timestamp format values are:
YYYY-MM-DD hh:mm:ss.S -Time is displayed in
24 hours format with milliseconds. .S indicates
milliseconds.
YYYY-MM-DD hh:mm:ss.S AM/PM - Time is
displayed in 12 hours format with miliseconds.
YYYY-MM-DD hh:mm:ss.S z - Time is displayed
in 24 hours format with milliseconds and time
zone. Z indicates time zone.
YYYY-MM-DD hh:mm:ss.S AM/PM z - Time is
displayed in 12 hours format with milliseconds
and time zone.
Only time zone ID is accepted. For example,
Asia/Kolkata. By default, Asia/Tokyo value is
specified in the request XML file. You need to specify
the time zone ID from the 151 time zones supported
list. The supported time zones are listed in a text file.
The UserProfileTimeZoneList.txt and
AllTimeZoneList.txt files. The files are located at
$MQ_HOME\mdm\8.3\common\standard\samples\ti
mezone folder.
Input Description
TIBCO MDM Web Services Guide
164
|
Chapter 4 Administration Services
Modify User Service
Using this web service, you can modify the information of an existing user. As an
administrator, you can modify the following user information:
User credentials, such as, the first name, last name, middle name, and
password
The locale information, date format, time format, timestamp format, time zone
and partitioning key
The roles assigned to the user
Delegation profile including users
All fields are validated similar to the Create User web service. Only the users
list specified in the delegation profile is not validated against the delegation
setup for roles.
For information on authentication of Modify User Service, refer to Table 6,
Authentication of Administrator Web Services, on page 20.
To use this web service:
1. Specify user details such as, user name, password, and an enterprise for the
user.
2. Modify user details such as, locale settings, and role delegation information.
3. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/AdminService/userAdminA
ction/modifyUserAction
The user is modified in an enterprise.
The following are sample XML files:
$MQ_HOME/schema/DataService/2.0/samples/admin/ModifyUser_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/ModifyUser_Response.xml
Only Administrator and Work Supervisor can modify the roles.
TIBCO MDM Web Services Guide
Modify User Service
|
165
Modify User Service - Inputs
The following inputs are required for this web service:
Input Description
ModifyUserDetails
UserName
(Mandatory)
The login ID of the Super User, Work Supervisor, or
Administrator
Users can also specfy their Login ID. However, they
can only modify their user name and locale
information.
Enterprise
(Mandatory)
The name of the enterprise of the Super User, Work
Supervisor, or Administrator.
Or
The name of the enterprise to which the modifying
user belongs.
Firstname
(Mandatory)
The first name of the user.
Lastname
(Mandatory)
The last name of the user.
Middlename
(Mandatory)
The middle name of the user.
PartitionKey A parameter used only in special circumstances.
The PartiotionKey contains the partition number
for the user in case the user based partitioning is
implemented.
IsEncrypted Specify true if you want the password in the
encrypted format.
Specify false if you do not want the password in the
encrypted format.
TIBCO MDM Web Services Guide
166
|
Chapter 4 Administration Services
Password
(Mandatory)
Specify the password that you want to update.
Note: If you have specified true for the
IsEncrypted attribute, specify the encrypted
password. While logging into TIBCO MDM from UI
as well as from the web service, specify the
decrypted form of a password.
If you have specified false for the IsEncrypted
attribute, specify the plain text password. While
logging into TIBCO MDM from UI as well as from
the web service, specify the as is password
mentioned in the request file.
Roles
Roles The role for the user name. Specify an existing role
from the enterprise.
If you do not specify a role, it retrieves the role that
was previously assigned to the user.
LocaleSettings
Language
(Optional)
Only a language supported by TIBCO MDM is
accepted. This input is mandatory if the country is
specified. You can keep the Country value blank and
specify the language value.
Country
(Optional)
The name of the country of the new user.
Input Description
TIBCO MDM Web Services Guide
Modify User Service
|
167
DateFormat
(Optional)
Only a date format value supported by TIBCO MDM
is accepted. By default, DD-MM-YY value is specified
in the request XML file. You can change the specified
date format. The supported date format values are:
MM/DD/YYYY
DD-MON-YYYY
MM/DD/YY
DDMMYYYY
YYYY-MM-DD
YYYY/MM/DD
DD-MM-YYYY
DD/MM/YYYY
DD-MM-YY
TimeFormat
(Optional)
Only a time format value supported by TIBCO MDM
is accepted. By default, the hh:mm:ss value is
specified in the request XML file. You can change the
specified time format. The supported time format
values are:
hh:mm:ss (24 hours)
hh:mm:ss AM/PM (12 hours)
TimestampFormat
(Optional)
Only a timestamp format value supported by TIBCO
MDM is accepted. By default, the YYYY-MM-DD
hh:mm:ss.S value is specified in the request XML
file. You can change the specified timestamp format.
The supported timestamp format values are:
YYYY-MM-DD hh:mm:ss.S -Time is displayed in a
24 hour format with milliseconds. .S indicates
milliseconds.
YYYY-MM-DD hh:mm:ss.S AM/PM - Time is
displayed in a 12 hour forma with miliseconds.
YYYY-MM-DD hh:mm:ss.S z - Time is displayed
in a 24 hour format with milliseconds and time
zone. Z indicates time zone.
YYYY-MM-DD hh:mm:ss.S AM/PM z - Time is
displayed in a 12 hour format with milliseconds
and time zone.
Input Description
TIBCO MDM Web Services Guide
168
|
Chapter 4 Administration Services
Timezone
(Optional)
Only the time zone ID is accepted. For example,
Asia/Kolkata. By default, the Asia/Tokyo value is
specified in the request XML file.
Specify the time zone ID from the supported time
zones listed in the following files:
$MQ_HOME\mdm\8.3\common\standard\samples\t
imezone\UserProfileTimeZoneList.txt
$MQ_HOME\mdm\8.3\common\standard\samples\t
imezone\AllTimeZoneList.txt
Delegation Profile
DelegationActive Specify true to activate delegation to the specified
users. After the delegation is activated, all work
items are automatically delegated to the specified
users.
Specify false to deactivate delegation of the
specified users.
StartDate Specify the start date when the delegation is to be
activated.
EndDate Specify the end date when the delegation is to be
deactivated.
Notify Specify true to notify the users about the work items
delegated to them. After the work item is delegated
to another user, an alert message is displayed when
the user logs in to the company.
AutoRevertFlag Specify true or false.
If you specify true, the delegation remains in effect
even after the delegation end date has passed.
Users Specify name of the users to whom you want to
delegate the work items based on their role.
UserDefinedAttributes
Input Description
TIBCO MDM Web Services Guide
Modify User Service
|
169
Modify User Service - Outputs
If you modify a user, the User information modified message is returned.
For information on failure messages, refer to Table 11, Faults of Administrator
Web Services, on page 26.
AttributeHelp Specify Y to display the repository attribute Help. To
edit records, move the cursor over an attribute; this
displays a Help icon.
Specify N if you do not want to display the repository
attribute Help.
Input Description
TIBCO MDM Web Services Guide
170
|
Chapter 4 Administration Services
Change Password Service
Using this web service, you can change the password of an user without
providing any other user information for modification. If you are an
Administrator or a Work Supervisor, you can modify your own password and
also the password of other users.
For information on authentication of Modify User Service, refer to Table 6,
Authentication of Administrator Web Services, on page 20.
To use this web service:
1. Specify user details such as user name, password, and an enterprise for the
user.
2. Specify the change password details such as, a value for the <IsEncrypted>
and <Password> attributes.
3. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/AdminService/userAdminA
ction/changepasswordAction
The password of a user is changed.
The following are sample XML files:
$MQ_HOME/schema/DataService/2.0/samples/admin/ChangePassword_Request
.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/ChangePassword_Response.
xml
Change Password Service - Inputs
The following inputs are required for this web service:
Input Description
UserInfo
UserName
(Mandatory)
The login ID of the Super User, Work Supervisor, or
Administrator.
Users can also specify their login ID. However, they
can only change their own password.
Password
(Mandatory)
The password for the specified user name.
TIBCO MDM Web Services Guide
Change Password Service
|
171
Change Password Service - Outputs
The User information modified message is returned if:
the password is changed with text modification.
the password is changed with an encrypted password.
The Password updated message is returned if:
the password contains a space.
the true or false value is specified for the <IsEncrypted> attribute.
For information on failure messages, refer to Table 11, Faults of Administrator
Web Services, on page 26.
Enterprise
(Mandatory)
The name of the enterprise of the Super User, Work
Supervisor, or Administrator.
The name of the enterprise to which the user
belongs.
ChangePasswordDetails
IsEncrypted Specify true if you want the password in the
encrypted format.
Specify false if you do not want the password in the
encrypted format.
Password
(Mandatory)
Specify the password that you want to update.
Note: If you have specified true for the
IsEncrypted attribute, specify the encrypted
password. While logging into TIBCO MDM from UI
as well as from the web service, specify the
decrypted form of a password.
If you have specified false for the IsEncrypted
attribute, specify the plain text password. While
logging into TIBCO MDM from UI as well as from
the web service, specify the as is password
mentioned in the request file.
Input Description
TIBCO MDM Web Services Guide
172
|
Chapter 4 Administration Services
Delete User Service
This service allows you to delete a user in an existing Enterprise.
For information on authentication of Delete User Service, refer to Table 6,
Authentication of Administrator Web Services, on page 20.
To use this web service:
1. Specify the user details such as user name, password, and enterprise for the
user.
2. Specify the user name and its enterprise that you want to delete.
3. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/AdminService/userAdminA
ction/deleteUserAction
The specified user is deleted from an existing enterprise.
A sample XML is available in:
$MQ_HOME/schema/DataService/2.0/samples/admin/DeleteUser_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/DeleteUser_Response.xml
Delete User Service - Inputs
The following inputs are mandatory for this web service:
Input Description
User Name Login ID of the Super User, Work Supervisor, or
Administrator.
Password Password for the specified user name.
Enterprise Name of the enterprise of the Super User, Work
Supervisor, or Administrator.
User Name Name of the user to be deleted.
Note: The user should not have any open work item,
else an error is returned.
Enterprise Name of the enterprise.
Note: This input is not required if you want to delete
a user from the same enterprise where the user is
logged-in.
TIBCO MDM Web Services Guide
Delete User Service
|
173
Delete User Service - Outputs
If a user is deleted, the User Deleted Successfully message is returned.
For information on failure messages, refer to Table 11, Faults of Administrator
Web Services, on page 26.
TIBCO MDM Web Services Guide
174
|
Chapter 4 Administration Services
Get User List Service
This service allows you to get a list of all defined users for an enterprise. You can
also retrieve a list of users based on the <UserName> filter criteria. For example, if
you want to retrieve a list of users that starts with the a alphabet.
For information on authentication of Get User List Service, refer to Table 6,
Authentication of Administrator Web Services, on page 20.
To use this web service:
1. Specify the user name, password, and enterprise for the user.
2. Specify the true or false value for the Exact Search attribute.
3. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/AdminService/GetUserLis
tAction
A list of all defined users for the specified enterprise is returned in response.
A sample XML is available in:
$MQ_HOME/schema/DataService/2.0/samples/admin/GetUserList-request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/GetUserList-response.xml
Get User List Service - Inputs
The following inputs are required for this web service:
Input Description
User Name The name of the currently logged-in user.
Enterprise
Name
Name of the enterprise.
Password Password of the currently logged-in user.
Exact Search
(Optional)
Specify true or false value.
True returns the users list exactly matching with the filter
criteria.
False returns the users list that contains the specified filter
criteria.
User Name
(Optional)
Name of the user that you want to retrieve.
TIBCO MDM Web Services Guide
Get User List Service
|
175
Get User List Service - Outputs
A list of all defined users is returned for the specified enterprise. For each user, the
User ID, first name, middle name, last name, enterprise name, language, locale,
date and time format, modification member ID, modification date, modification
version, active and delegation active is returned.
For information on failure messages, refer to Table 11, Faults of Administrator
Web Services, on page 26.
First Name
(Optional)
First name of the user that you want to retrieve.
Last Name
(Optional)
Last name of the user that you want to retrieve.
Input Description
TIBCO MDM Web Services Guide
176
|
Chapter 4 Administration Services
Get Role List Service
This service allows you to get a list of roles for all defined users for the specified
enterprise. You can also retrieve a list of roles based on <RoleName> filter criteria.
For example, you may want to get a list of Repository Manager roles.
For information on authentication of Get Role List Service, refer to Table 6,
Authentication of Administrator Web Services, on page 20.
To use this web service:
1. Specify the user name, password, and enterprise for the user.
2. Specify the true or false value for the Exact Search attribute.
3. Specify the role name for filter criteria. For example, you can specify
Repository to retrieve a list of roles that start with Repository. The Role
Name is an optional parameter.
4. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/AdminService/GetRoleLis
tAction
A list of roles of all defined users for the specified enterprise is returned. If
you have specified the Repository value for the <RoleName> attribute, a list
of roles that start with Repository are returned, such as Repository Manager,
Repository Editor, and Repository Approver.
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/admin/GetRoleList-request.xml
$MQ_HOME/schema/DataService/2.0/samples/admin/GetRoleList-response.xml
Get Role List Service - Inputs
The following inputs are required for this web service:
Input Description
User Name The name of the currently logged-in user.
Password Password for the user name.
Enterprise
Name
Name of the enterprise.
TIBCO MDM Web Services Guide
Get Role List Service
|
177
Get Role List Service - Outputs
A list of roles for all defined users and for the specified enterprise is returned. For
each role, the Enterprise ID, its name, description, type, active, modification
member ID, modification date, modification version, and organization type is
returned.
For information on failure messages, refer to Table 11, Faults of Administrator
Web Services, on page 26.
Exact Search Specify true or false value.
True returns the roles list exactly matching with the filter
criteria.
False returns the roles list that contains the specified filter
criteria.
Role Name
(Optional)
Specify the role name to get a filtered list of roles.
Input Description
TIBCO MDM Web Services Guide
178
|
Chapter 4 Administration Services
TIBCO MDM Web Services Guide
|
177
Chapter 5 Data Services
This chapter describes the usage and customization of data services.
Topics
Text Search Service, page 178
Get DataSource List Service, page 187
Get Repository List Service, page 189
Initiate Synchronization Service, page 195
Upload Metadata Service, page 197
Extract Data Service, page 199
GetClassificationSchemeList, page 206
GetClassificationSchemeAttributeList, page 209
GetClassificationCodeHierarchy, page 212
TIBCO MDM Web Services Guide
178
|
Chapter 5 Data Services
Text Search Service
The Text Search web service, available as cimDataService.wsdl, allows you to
search for human recognizable terms in one or more TIBCO MDM repositories as
you would do on an Internet Search Engine. The WSDL is available at
$MQ_HOME/schema/DataService/2.0/cimDataService.wsdl. This WSDL can
be used to generate client stubs for various client languages.
The Text Search web service indexes the text in a record and stores them as key
terms in a data index. For example, if you search for records with a description
"The product is in red color", the search utility looks for the key terms, "product",
"red", and "color". Articles, prepositions, pronouns, and other such fillers are not
considered as key terms. The Text Search index contains the Record ID and the
latest version of the record.
This web service also allows you to conduct similarity searches, that is, searches
which are close to an existing indexed term (for example, due to a spelling error)
are found and returned. A Fuzzy search or similarity search is more expensive
than standard text search and should be used in a more focused way than the
'exact' text search, by limiting the repositories or attributes.
For information on authentication of Text Search Service, refer to Table 7,
Authentication of Data Web Services, on page 22.
Using this web service you can:
Search for text against the entire index (all indexed catalogs)
Search for text search against the entire index (all indexed catalogs) retrieving
only a limited client determined set (paged query)
Search for text search against a single repository
Search for text against a single repository retrieving only a limited client
determined set (paged query)
Fuzzy search against a single repository
Text search is offered as a separate service, resulting in a separate WSDL and a
different endpoint address. This is in contrast to the other services which are
multiplexed in the same WSDL and use different message parameters to
invoke a specified service.
Only the latest confirmed or unconfirmed record are searchable through the
text search service.
The search expression must not exceed 1024 bytes or 10 terms (words).
This service does not support query of deleted records.
TIBCO MDM Web Services Guide
Text Search Service
|
179
Fuzzy search against a single repository retrieving only a limited client
determined set (paged query)
Fuzzy search against a single repository with a limited set of repository
attributes
Fuzzy search against a single repository retrieving only a limited client
determined set (paged query) with a limited set of repository attributes
Enabling Text Search
To enable text search, set the following properties in Configurator (Initial Config
> Repository):
Text Indexing Enabled: Go to Initial Config > Advanced> Repository, set
this property to either OFFLINE or ONLINE. The default is NONE.
Text Indexing Receiver Pool Size: Go to Member1 > Advanced> Async Task
Management, specify the number of threads processing in parallel. Set this
property to o 1 to enable the indexing and to 0 to disable the automatic text
indexing. Do not set the property to a value greater than 1.
Additionally, you can also specify the following properties in Configurator:
Default Similarity Text Search Score: Go to Initial Config > Miscellaneous,
specify the default similarity (fuzzy) score which is needed to return a
matching record. The value must be between 0 and 1.0. The default value is
0.8.
Text Search Service - Inputs
This web service contains a single web service operation, textSearchAction.
<wsdl:portType name="DataServicePortType">
<wsdl:operation name="textSearchAction">
<wsdl:input message="tns:textSearchRequest"/>
<wsdl:output message="tns:textSearchResponse"/>
</wsdl:operation>
</wsdl:portType>
Lowering the default fuzzy score may affect performance and result in irrelevant
records.
TIBCO MDM Web Services Guide
180
|
Chapter 5 Data Services
The following inputs are mandatory for this web service:
Text Search Service - Outputs
A list of records matching the search criteria is provided as an output in the
<Records> element.
For information on failure messages, refer to Table 12, Faults of Data Web
Services, on page 28.
Types of Text Search Services
You can specify following types of text search web services:
Text Search Exact Query Service
Text Search Fuzzy Query Service
Index Entity Fuzzy Query Service
The sample XML files for each Text Search web service are available at
$MQ_HOME/schema/DataService/2.0/samples/repository/textSearch/
TextSearch-AttributeFuzzyQuery-Request(With Weight).xml
TextSearch-AttributeFuzzyQuery-Request(Without Weight).xml
TextSearch-AttributeFuzzyQuery-Response(With Weight).xml
TextSearch-AttributeFuzzyQuery-Response(Without Weight).xml
TextSearch-ExactQuery-Request.xml
TextSearch-ExactQuery-Response.xml
TextSearch-FuzzyQuery-Request.xml
TextSearch-FuzzyQuery-Response.xml
TextSearch-IndexEntityFuzzyQuery-Request(With RA).xml (RA stands
for Relationship Attributes)
TextSearch-IndexEntityFuzzyQuery-Request.xml
TextSearch-IndexEntityFuzzyQuery-Response(With RA).xml (RA
stands for Relationship Attributes)
TextSearch-IndexEntityFuzzyQuery-Response.xml
Input Description
User name Name of the user.
Password Password of the user.
Enterprise Name of the enterprise.
TIBCO MDM Web Services Guide
Text Search Service
|
181
Text Search Exact Query Service
For Text Search Exact Query web service, in addition to the mandatory inputs,
specify the following tags in the request:
Repository location indicator: This could be either the entire repository set, a
specific repository set, or a repository set whose results are limited by an
attribute set.
Entire repository set (used for an Exact Search only)
<RepositoryNames>
<RepositorySet>ALL</RepositorySet>
</RepositoryNames>
Search string: The string can be searched as follows.
Exact Search
<ExactSearchExpression>sample string</ExactSearchExpression>
You can search an entire repository set or a specific repository set.
Record Count: You can specify a number of matching records specified in a
repository that you want to display in the response.
<ns:ReturnCount>
<ns:StartCount>1</ns:StartCount>
<ns:TotalCount>1</ns:TotalCount>
</ns:ReturnCount>
Start Count represents the sequential number of matching record that you
want to display in the response. For example, if there are three matching
records in a repository and you want view the second matching record. You
can specify <ns:StartCount>2</ns:StartCount>
Total Count represents the total number of matching records that you want
to display in the response. For example, if there are five matching records
in a repository and you want to view all five records, you can specify
<ns:TotalCount>5</ns:TotalCount>
If you do not specify record count, all matching records specified in the
Exact Search criteria are displayed.
You must specify the value for both StartCount and TotalCount. If any
missing value for any one of these tag; results in failure response.
You cannot restrict an exact text search to specific attributes.
You can search in a specific repository only.
TIBCO MDM Web Services Guide
182
|
Chapter 5 Data Services
Text Search Fuzzy Query Service
For Text Search Fuzzy Query web service, in addition to the mandatory inputs,
specify the following tags in the request:
Repository location indicator: Specify the repository name and its attributes.
Specifying an attribute set (used for a Similarity Search only)
<RepositoryNames>
<RepositoryName
attributes="FirstName">Person</RepositoryName>
</RepositoryNames>
Specific repository set (used for both Exact and Similarity Search)
<RepositoryNames>
<RepositoryName>Person</RepositoryName>
</RepositoryNames>
Similarity (fuzzy) Search
<FuzzySearchExpression
similarityScore="0.95">John</FuzzySearchExpression>
You can search a specific repository. You can also limit the results based on
an attribute set.
A similarity (fuzzy) score can be specified for a Similarity (fuzzy) search.
This score is needed to return a matching record. The value must be
between 0 and 1.0. The default is 0.8.
Standard paging elements such as <StartCount> and <TotalCount> in the
<ReturnCount> element (optional). These paging elements help you achieve
windowing/pagination of a large result set.
Text Search Attribute Fuzzy Query Service
For Text Search Attribute Fuzzy Query web service, in addition to the mandatory
inputs, specify the following tags in the request:
Specifying an attribute set along with the weight
<ns:BaseExpression attribute="NAME"
weight="0.9">Michel</ns:BaseExpression>
<ns:BaseExpression attribute="CITY" weight="1.0">New
York</ns:BaseExpression>
You cannot perform a Similarity (fuzzy) Search on all repositories; a specific
repository must be specified.
Do not set ReturnCount when using FuzzySearchExpression. It could result in
a SOAP fault.
TIBCO MDM Web Services Guide
Text Search Service
|
183
Specifying an attribute set along without weight
<ns:BaseExpression attribute="NAME"
>Michel</ns:BaseExpression>
<ns:BaseExpression attribute="CITY">New
York</ns:BaseExpression>
Index Entity Fuzzy Query Service
The Index Entity Fuzzy Query web service allows you to perform search on
IndexEntity, which is specified in the IndexerConfig.xml. This file is located in
the $MQ_HOME/config folder. For more information about this file, refer to TIBCO
MDM System Administrators Guide.
To use Index Entity Fuzzy Query web service, specify the entity name, similarity
score, text search fuzzy query service details, and standard paging elements.
Example 16 IndexEntity Request
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<soapenv:Header />
<soapenv:Body>
<ns:TextSearchRequest>
<ns:UserInfo>
<ns:UserName>jsmith</ns:UserName>
<ns:Password>jsmith</ns:Password>
<ns:Enterprise>tech</ns:Enterprise>
</ns:UserInfo>
<ns:IndexEntityFuzzyQuery>
<ns:EntityName>Customer_OfficeAddress</ns:EntityName>
<ns:SimilarityScore>0.6</ns:SimilarityScore>
<ns:Repository>
<ns:Name>CUSTOMER</ns:Name>
<ns:FuzzyQuery>
<ns:BaseExpression
attribute="LASTNAME">Smith</ns:BaseExpression>
</ns:FuzzyQuery>
<ns:Relationship>
<ns:Name>OFFICEADDRESS</ns:Name>
</ns:Relationship>
</ns:Repository>
<ns:Repository>
<ns:Name>ADDRESS</ns:Name>
TIBCO MDM Web Services Guide
184
|
Chapter 5 Data Services
<ns:FuzzyQuery>
<ns:BaseExpression
attribute="CITY">Pune</ns:BaseExpression>
</ns:FuzzyQuery>
</ns:Repository>
</ns:IndexEntityFuzzyQuery>
<ns:ReturnCount>
<ns:StartCount>1</ns:StartCount>
<ns:TotalCount>1</ns:TotalCount>
</ns:ReturnCount>
</ns:TextSearchRequest>
</soapenv:Body>
</soapenv:Envelope>
Example 17 IndexEntity Response
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<ns:TextSearchResponse
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<ns:Records>
<ns:Record searchScore="1.0" searchScoreString=" ">
<ns:ExternalKeys>
<ns:Key name="MASTERCATALOGNAME"
type="string">CUSTOMER</ns:Key>
<ns:Key name="PRODUCTID" type="string">CUST102</ns:Key>
<ns:Key name="PRODUCTIDEXT" type="string">4</ns:Key>
</ns:ExternalKeys>
<ns:EntityData>
<ns:Attribute name="Gender" type="string">M</ns:Attribute>
<ns:Attribute name="OWNERID"
type="decimal">2147494649</ns:Attribute>
<ns:Attribute name="CATALOGVERSIONNUMBER"
type="decimal">1</ns:Attribute>
<ns:Attribute name="PRODUCTKEYID"
type="decimal">2147494791</ns:Attribute>
<ns:Attribute name="MODVERSION"
type="decimal">1</ns:Attribute>
<ns:Attribute name="PARENTVERSION"
type="decimal">0</ns:Attribute>
<ns:Attribute name="LastName"
type="string">Smith</ns:Attribute>
TIBCO MDM Web Services Guide
Text Search Service
|
185
<ns:Attribute name="MODMEMBERID"
type="decimal">2147485082</ns:Attribute>
<ns:Attribute name="PROCESSLOGID"
type="">2148583566</ns:Attribute>
<ns:Attribute name="LASTIMPORTTIME"
type="decimal">1.306997374356E12</ns:Attribute>
<ns:Attribute name="ACTIVE" type="string">Y</ns:Attribute>
<ns:Attribute name="MODDATE" type="date">2011-06-02
12:19:48.0</ns:Attribute>
<ns:Attribute name="Firstname"
type="string">John</ns:Attribute>
<ns:Attribute name="STATE"
type="string">CONFIRMED</ns:Attribute>
<ns:Attribute name="OWNERTYPE"
type="decimal">21</ns:Attribute>
<ns:Attribute name="LASTCONFIRMEDVERSION"
type="decimal">1</ns:Attribute>
<ns:Attribute name="Age" type="integer">23</ns:Attribute>
<ns:Attribute name="CHECKSUM"
type="decimal">-1090762682</ns:Attribute>
<ns:Attribute name="CREATIONDATE" type="date">2011-06-02
12:19:34.0</ns:Attribute>
<ns:Attribute name="DOB" type="date">1986-01-15
00:00:00.0</ns:Attribute>
</ns:EntityData>
<ns:RelationshipData>
<ns:Relationship>
<ns:RelationType>OfficeAddress</ns:RelationType>
<ns:RelatedEntities>
<ns:Record searchScore="1.0" searchScoreString=" ">
<ns:ExternalKeys>
<ns:Key name="MASTERCATALOGNAME"
type="string">ADDRESS</ns:Key>
<ns:Key name="PRODUCTID"
type="string">ADDR231</ns:Key>
<ns:Key name="PRODUCTIDEXT"
type="string">1</ns:Key>
</ns:ExternalKeys>
<ns:EntityData>
<ns:Attribute name="ADDRESS1" type="string">Gokhale
Nagar</ns:Attribute>
<ns:Attribute name="Country"
type="string">India</ns:Attribute>
<ns:Attribute name="OWNERID"
type="decimal">2147494649</ns:Attribute>
TIBCO MDM Web Services Guide
186
|
Chapter 5 Data Services
<ns:Attribute name="CATALOGVERSIONNUMBER"
type="decimal">1</ns:Attribute>
<ns:Attribute name="PRODUCTKEYID"
type="decimal">2147495316</ns:Attribute>
<ns:Attribute name="MODVERSION"
type="decimal">1</ns:Attribute>
<ns:Attribute name="PARENTVERSION"
type="decimal">0</ns:Attribute>
<ns:Attribute name="MODMEMBERID"
type="decimal">2147485082</ns:Attribute>
<ns:Attribute name="LASTIMPORTTIME"
type="decimal">1306997374356</ns:Attribute>
<ns:Attribute name="PROCESSLOGID"
type="">2148583566</ns:Attribute>
<ns:Attribute name="Zip"
type="integer">411016</ns:Attribute>
<ns:Attribute name="ACTIVE" type="string">Y</ns:Attribute>
<ns:Attribute name="MODDATE" type="date">2011-06-02
12:19:47.0</ns:Attribute>
<ns:Attribute name="STATE"
type="string">CONFIRMED</ns:Attribute>
<ns:Attribute name="OWNERTYPE"
type="decimal">21</ns:Attribute>
<ns:Attribute name="LASTCONFIRMEDVERSION"
type="decimal">1</ns:Attribute>
<ns:Attribute name="City"
type="string">Pune</ns:Attribute>
<ns:Attribute name="CHECKSUM"
type="decimal">-1088085556</ns:Attribute>
<ns:Attribute name="CREATIONDATE" type="date">2011-06-02
12:19:34.0</ns:Attribute>
</ns:EntityData>
</ns:Record>
</ns:RelatedEntities>
</ns:Relationship>
</ns:RelationshipData>
</ns:Record>
</ns:Records>
<ns:ReturnCount>
<ns:StartCount>1</ns:StartCount>
<ns:TotalCount>1</ns:TotalCount>
</ns:ReturnCount>
</ns:TextSearchResponse>
</soapenv:Body>
</soapenv:Envelope>
TIBCO MDM Web Services Guide
Get DataSource List Service
|
187
Get DataSource List Service
This service allows you to get a list of data sources of the currently logged-in
users for an enterprise. Only user authorized to access data source can get data
source details. You can also retrieve a list of data sources based on filter criteria.
For example, if you want to retrieve a data source of the specific user.
For information on authentication of Get DataSource List Service, refer to Table 7,
Authentication of Data Web Services, on page 22.
To use this web service:
1. Specify the user details such as user name, password, and enterprise for the
user.
2. Invoke the web service by specifying the following endpoint URL:
http://<servername>:<port>/eml/services/DataService/getDatasour
ceListAction
A sample XML is available in:
$MQ_HOME/schema/DataService/2.0/samples/datasource/GetDataSourceList
-request.xml
$MQ_HOME/schema/DataService/2.0/samples/datasource/GetDataSourceList
-response.xml
Get DataSource List Service - Inputs
The following inputs are required for this web service:
Input Description
User name Login ID of the user.
Password Password for the specified user name.
Enterprise Name of the enterprise.
DatasourceDetails Details of search criteria and data source name.
Exact Search Specify the true or false value.
True returns the data sources list exactly
matching with the filter criteria.
False returns the data sources list that contains
the specified filter criteria.
TIBCO MDM Web Services Guide
188
|
Chapter 5 Data Services
Get DataSource List Service - Outputs
The filtered list of all the data sources is returned for the logged in user. For each
data source, the data source ID, its name, description, file name, its format, source
table name, delimiter code, and delimiter value, date format, modification
member ID, modification date, modification version, active, and data source
column details are returned.
For an SQL type data source, the response contains the FileLastUploadedDate
element. Also, the TableLastUploadedDate element appears for a normal data
source. These are unused elements. In such cases, interpret the response as data
last uploaded.
For information on failure messages, refer to Table 12, Faults of Data Web
Services, on page 28.
DataSourceName Name of the data source.
Input Description
TIBCO MDM Web Services Guide
Get Repository List Service
|
189
Get Repository List Service
This web service allows you to get a list of repositories that can be accessed by the
currently logged-in user.
For information on authentication of Get Repository List Service, refer to Table 7,
Authentication of Data Web Services, on page 22.
To use this web service:
1. Specify the user details such as user name, password, and enterprise name.
2. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/DataService/GetReposito
ryListAction
A list of all repositories is returned in response.
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/repository/metadata/
GetRepositoryList-request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/metadata/
GetRepositoryList-response.xml
Get Repository List Service - Inputs
The following inputs are mandatory for this web service:
Get Repository List Service - Outputs
A list of repositories that can be accessed by currently logged-in user is returned.
For each repository, the name of repository, description, modification member ID,
modification date, modification version, and table name are returned. For
example:
Input Description
User name Name of the user.
Password Password of the user.
Enterprise Name of the enterprise.
TIBCO MDM Web Services Guide
190
|
Chapter 5 Data Services
<ns:Repository id="36915">
<ns:Name>C</ns:Name>
<ns:Description lang="en">C</ns:Description>
<ns:Moddate>2009-06-24 17:16:17.0</ns:Moddate>
<ns:ModMember>35289</ns:ModMember>
<ns:ModVersion>1</ns:ModVersion>
<ns:Tablename>MCT_36915</ns:Tablename>
</ns:Repository>
TotalCount indicates the total number of repositories that met the search criteria
of the request. For example:
<ns:ReturnCount>
<ns:TotalCount>2</ns:TotalCount>
</ns:ReturnCount>
For information on failure messages, refer to Table 12, Faults of Data Web
Services, on page 28.
TIBCO MDM Web Services Guide
Get Related Repository List Service
|
191
Get Related Repository List Service
This web service allows you to get a list of relationships both forward and reverse
for every repository in an enterprise. For the Export Metadata functionality, if you
select the parent repository, its related repositories need to be exported together.
Using this web service, the icon is displayed on the Export Wizard to identify
the related repository. Therefore, while exporting metadata when you click the
parent repository in the Available Repositories list, the icon is displayed next
to its related repositories. For example, consider a scenario where Customer
repository is related to Address repository. If you select the Customer repository
for export, the Address repository is also automatically selected for export
because a relationship is defined between Customer and address repositories. For
more information about selecting repositories for export, refer to Exporting and
Importing Metadata chapter in Users guide.
For information on authentication of Get Related Repository List web service,
refer to Table 7, Authentication of Data Web Services, on page 22.
To use this web service:
1. Specify the user details such as user name, password, and enterprise name.
2. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/DataService/RelatedRepo
sitoryListAction
A list of all relationships is returned in response.
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/repository/metadata/
RelatedRepositoryList_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/metadata/
RelatedRepositoryList_Response.xml
Get Related Repository List Service - Inputs
The following inputs are mandatory for this web service:
Input Description
User name Name of the user.
Password Password of the user.
Enterprise Name of the enterprise.
TIBCO MDM Web Services Guide
192
|
Chapter 5 Data Services
Get Related Repository List Service - Outputs
A list of relationships is returned.
TIBCO MDM Web Services Guide
Get Repository With Dependant Artifacts Service
|
193
Get Repository With Dependant Artifacts Service
This web service allows you to get a list of all the dependant artifacts for every
repository that you have selected during export. For the Export Metadata
functionality, if you select the repository, its dependant artifacts need to be
exported together. The dependent artifacts include the input maps and output
maps. It also includes the dependency of input maps over data sources and
dependency of output maps over synchronization formats. For example, consider
a scenario where you have selected the Customer repository and its input maps,
such InputMap1 and InputMap2. However, you have not selected the
CustDataSource data source on the Select Data Sources screen. In this case, a
warning message is displayed to inform that the dependency exist between the
input map and a data source. These dependencies are captured by the
GetRepositoryWithDependentArtifacts web service. For more information about
dependency messages, refer to Exporting and Importing Metadata chapter in Users
guide.
For information on authentication of Get Related Repository List web service,
refer to Table 7, Authentication of Data Web Services, on page 22.
To use this web service:
1. Specify the user details such as user name, password, and enterprise name.
2. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/DataService/RelatedRepo
sitoryListAction
A list of all relationships is returned in response.
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/repository/metadata/
RelatedRepositoryList_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/metadata/
RelatedRepositoryList_Response.xml
Get Repository With Dependant Artifacts Service - Inputs
The following inputs are mandatory for this web service:
Input Description
User name Name of the user.
Password Password of the user.
TIBCO MDM Web Services Guide
194
|
Chapter 5 Data Services
Get Repository With Dependant Artifacts Service - Outputs
A list of dependant artifacts is returned.
Enterprise Name of the enterprise.
Repository Name Name of the repository.
Input Description
TIBCO MDM Web Services Guide
Initiate Synchronization Service
|
195
Initiate Synchronization Service
This service allows you to synchronize records on a Trading Partner. This service
operates in two modes, Async and Sync.
This service take Synchronization profile name and repository name as
mandatory input and ValidFrom and ValidUntil date as an optional input.
For information on authentication of Initiate Synchronization Service, refer to
Table 7, Authentication of Data Web Services, on page 22.
To use this web service:
1. Specify the user name, password, and enterprise in the request criteria.
2. Specify Synchronization profile information such as Name, Repository Name,
ValidFrom, and ValidUntil.
3. Specify the execmode as "ASYNCHR" or "SYNCHR".
4. Invoke the webservice by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/DataService/synchronize
Action
You can synchronize the records in the Async or Sync mode successfully.
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/repository/record-synchronization
/Synchronization-Async-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/record-synchronization
/Synchronization-Async-Response.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/record-synchronization
/Synchronization-Sync-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/record-synchronization
/Synchronization-Sync-Response.xml
Initiate Synchronization Service - Inputs
This web service accepts the following inputs:
Input Description
User name Login ID of the user.
Password Password for the specified user name.
Enterprise Name of the enterprise.
TIBCO MDM Web Services Guide
196
|
Chapter 5 Data Services
Initiate Synchronization Service - Outputs
The response message contains EventId, EventStatus, and EventState of the event.
It also contains the DocumentId and DocumentType of the data file.
For information on failure messages, refer to Table 12, Faults of Data Web
Services, on page 28.
Name
(Mandatory)
Name of the synchronization profile.
execmode Specify ASYNCHR or SYNCHR value.
RepositoryName
(Mandatory)
Name of the repository.
ValidFrom
(Optional)
Valid from date.
ValidUntil
(Optional)
Valid until date.
Input Description
TIBCO MDM Web Services Guide
Upload Metadata Service
|
197
Upload Metadata Service
This service allows you to upload metadata to TIBCO MDM. You can upload jar,
zip, or XML file. This functionality is similar to import metadata from TIBCO
MDM user interface. You can request the Upload Metadata Service in the SYNC
and ASYNC modes.
For information on authentication of Upload Metadata Service, refer to Table 7,
Authentication of Data Web Services, on page 22.
To use this web service:
1. Specify the user details such as user name, password, and enterprise for the
user.
2. Specify the execmode as ASYNCHR or SYNCHR.
3. Specify upload metadata information such as FileName, FileType, and
BinaryData.
4. Invoke the web service by specifying the following endpoint URL:
http://<servername>:<port>/eml/services/DataService/metadataAct
ion
A sample request XML is available in:
$MQ_HOME/schema/DataService/2.0/samples/repository/metadata/Upload
Metadata_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/metadata/Upload
Metadata_Response.xml
Upload Metadata Service - Inputs
The following inputs are required for this web service:
Input Description
User name Login ID of the user.
Password Password for the specified user name.
Enterprise Name of the enterprise.
execmode Specify ASYNCHR or SYNCHR value.
TIBCO MDM Web Services Guide
198
|
Chapter 5 Data Services
Upload Metadata Service - Outputs
If the upload is successful, a success message along with event ID is returned.
For information on failure messages, refer to Table 12, Faults of Data Web
Services, on page 28.
FileName Name of the file to be uploaded. The filename must
include the file extension. For example, Metadata.jar.
This web service supports jar, zip, and XML file
extensions.
FileType Specify the file type. For example, jar, zip, and xml
file types.
BinaryData Specify the content ID. The content ID is generated,
after you upload the metadata file.
The metadata file to be uploaded must be attached to
this input.
Input Description
TIBCO MDM Web Services Guide
Extract Data Service
|
199
Extract Data Service
This service allows you to extract data from TIBCO MDM using custom
implementation. A request can be sent to extract data from database or other
sources, for example, Netrics. Specify the Data provider and Data processor to
extract and process data. Specify additional parameters such as SQL query
parameters if data is retrieved from database as key value pair.
For more details on implementing the framework, refer to the TIBCO MDM
Customization Guide.
For information on authentication of Extract Data Service, refer to Table 7,
Authentication of Data Web Services, on page 22.
To use this web service:
1. Specify the user details such as user name, password, and enterprise for the
user.
2. Specify the execmode as "ASYNCHR" or "SYNCHR".
3. Specify Extract Details information such as DataProvider, DataProcessor, and
BatchSize.
4. Specify parameter information such as key and its value. This is an optional
parameter.
5. Invoke the web service by specifying the following endpoint URL:
http://<servername>:<port>/eml/services/DataService/extractData
Action
A sample request XML is available in:
$MQ_HOME/schema/DataService/2.0/samples/repository/dataextractor/
DataExtractor_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/dataextractor/
DataExtractor_Response.xml
Extract Data Service - Inputs
The following inputs are required for this web service:
Input Description
User name Login ID of the user.
Password Password for the specified user name.
TIBCO MDM Web Services Guide
200
|
Chapter 5 Data Services
Extract Data Service - Outputs
If the spawn is successful, the event ID is returned.
For information on failure messages, refer to Table 12, Faults of Data Web
Services, on page 28.
Enterprise Name of the enterprise.
execmode Specify ASYNCHR or SYNCHR value.
DataProvider Fully qualified package name of the IDataProvider
interface. For example,
com.tibco.mdm.repository.engine.dataextract
or.test.TestDbDataProvider
DataProcessor Fully qualified package name of the IDataProvider
interface. For example,
com.tibco.mdm.repository.engine.dataextract
or.test.TestGoldencopyDataProcessor
Parameter (Optional) Key value pair for additional information such as
SQL query parameters.
Input Description
TIBCO MDM Web Services Guide
Extract Data Service
|
201
Quick Export Service Using Data Extractor
The Quick Export feature uses the data extractor framework that allows you to
trigger the export operation using the Extract Data service.
You can export records using the following Quick Export services:
Data Filter Query
Related Records
Subset Data
Quick Export Data Filter Query
You can export golden copy records by specifying catalog ID. The golden copy
records are confirmed records. You can also create an SQL query to filter records
based on the criteria described in the inputs of the search query.
Quick Export Data Filter Query - Inputs
This web service accepts the following inputs:
The Quick Export Service does not support exporting the selected records.
Input Description Expected Value
DataProvider Fully qualified package name of the
IDataProvider interface.
com.tibco.mdm.repository.
engine.dataprovider and
ProductInfoDataProvider
DataProcessor Fully qualified package name of the
IDataProcessor interface.
com.tibco.mdm.repository.
engine.dataprocessor and
RecordToCSVProcessor
CATALOGID An ID of the catalog for which quick export
needs to be triggered.
User specified
TIBCO MDM Web Services Guide
202
|
Chapter 5 Data Services
Quick Export Related Records
You can export related records by specifying parent record ID, extension, and
relationship name.
Quick Export Related Records - Inputs
This web service accepts the following inputs:
SEARCHQUERY
(Optional)
Searches records based on filter criteria and
exports all golden copy records for the
repository.
The Search Query must select
productkeyid and modversion columns.
If a table contains different column names,
ensure that columns are aliased in the SQL
query. For example, to export all confirmed
Person repository records with
PERSON_NAME attribute starting with 'A':
select gc.productkey
"productkeyid", gc.version
"modversion", p.cperson_name from
goldencopy gc, person p where
gc.productkey=p.cproductkeyid and
gc.version=p.cmodversion and
p.cperson_name like 'A%'
User specified
Input Description Expected Value
Input Description Expected Value
DataProvider Fully qualified package name
of the IDataProvider
interface.
com.tibco.mdm.reposit
ory.engine.dataprovid
er.RelatedRecordsData
Provider
DataProcessor Fully qualified package name
of the IDataProcessor
interface.
com.tibco.mdm.reposit
ory.engine.dataproces
sor.
RecordToCSVProcessor
PARENTCATALOGID Catalog ID of parent record
whose related records need to
be exported.
User specified
TIBCO MDM Web Services Guide
Extract Data Service
|
203
PARENTRECORDPRODUCTID
(Optional)
Product ID of parent record
whose related records need to
be exported. Either this
parameter or
PARENTRECORDPRODUCTKEYID
must be available.
User specified
PARENTRECORDEXTENSION
(Optional)
Product ID of parent record
whose related records need to
be exported.
User specified
PARENTRECORDMODVERSION Version of parent record
whose related records need to
be exported.
User specified
PARENTRECORDPRODUCTKEYID
(Optional)
Product key ID of parent
record whose related records
need to be exported. Either
this parameter or
PARENTRECORDPRODUCTID
must be available.
User specified
RELATIONSHIPNAME Specifies name of the
relationship for the records.
For example,
PersonToAddress
relationship related to the
Person and Address
repositories. In this case, the
records related to
PersonToAddress
relationship are exported.
User specified
EVENTID
(Optional)
Specifies parent record as
draft
User specified
Input Description Expected Value
TIBCO MDM Web Services Guide
204
|
Chapter 5 Data Services
Quick Export Subset Data
You can export subset data by specifying subset name and catalog ID.
Quick Export Subset Data - Inputs
This web service accepts the following inputs:
Quick Export Common Parameters
Quick Export data extractor web services support the following common
parameters:
Input Description Expected Value
DataProvider Fully qualified package name of
the IDataProvider interface.
com.tibco.mdm.repository.
engine.dataprovider.Subse
tDataProvider
DataProcessor Fully qualified package name of
the IDataProcessor interface.
com.tibco.mdm.repository.
engine.dataprocessor.
RecordToCSVProcessor
SUBSETNAME
(Optional)
Name of the subset. Either this
parameter or SUBSETID must be
available.
User specified
CATALOGID
(Optional)
Catalog ID for which subset is
created. If a subset name is
provided, the Catalog ID must be
available.
User specified
SUBSETID
(Optional)
An ID of the subset whose data
are exported. Either this
parameter or the subset name
must be available.
User specified
Input Description Expected Value Default Value
DELIMITER
(Optional)
Refers to the delimiter for
data in a file. The
delimiter must be a single
character.
User specified Comma (,)
TEXTQUALIFIER
(Optional)
The qualifier used to
differentiate the field data
from the delimiter.
User specified Double Quotes (")
TIBCO MDM Web Services Guide
Extract Data Service
|
205
FILEEXTENSION
(Optional)
An extension of the
exported output data
files.
User specified CSV
EMAILDELIVERY
(Optional)
Specifies whether an
email to be sent at the end
of the operation.
True or False False
EXPORTATTRIBUTES
(Optional)
Specifies whether to
export all or displayable
attributes.
All or displayable
(case sensitive)
All
EMAILTEMPLATE
(Optional)
Template used for
sending email notification
containing the File
Download link. Note that
email template must have
an anchor element with
downloadUrl ID. The
application sets the
download link for this
anchor.
Fully classified class
name of the email
template
com.tibco.mdm.ui.
workflow.engine.e
mailtemplates.Ema
ilQuickExport
Input Description Expected Value Default Value
TIBCO MDM Web Services Guide
206
|
Chapter 5 Data Services
GetClassificationSchemeList
This web service allows you to retrieve a list of classification schemes for a
particular repository.
To use this web service:
1. Specify the user name, password, and enterprise in the request criteria.
2. Specify information such as Repository Name.
3. Invoke the web service by specifying the Endpoint URL as follows:
http://<servername>:<port>/eml/services/DataService/GetClassifi
cationSchemeListAction
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/repository/classification/
GetClassificationSchemeListRequest.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/classification/
GetClassificationSchemeListResponse.xml
GetClassificationSchemeList - Inputs
This web service accepts the following inputs:
GetClassificationSchemeList - Outputs
The response message contains Classification Scheme ID, Classification Scheme
Name, Classification Scheme Type,and Classification Scheme Description.
Input Description
User name Specify the Login ID of the user.
Password Specify the password for the specified user name.
Enterprise Specify the name of the enterprise.
RepositoryName
(Mandatory)
Specify the name of the repository.
ReturnCount Specify the return count for paginated response. You
must specify the 'startCount' and 'totalCount' of the
schemes required in the request. This field is
optional.
TIBCO MDM Web Services Guide
GetClassificationSchemeList
|
207
Request:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<soapenv:Header/>
<soapenv:Body>
<ClassificationSchemeListRequest
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<UserInfo>
<UserName>a</UserName>
<Password>a</Password>
<Enterprise>a</Enterprise>
</UserInfo>
<Repository>FBT_Repository</Repository>
<!-- mandatory -->
</ClassificationSchemeListRequest >
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Header/>
<soapenv:Body>
<ClassificationSchemeListResponse
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns
="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<ClassificationScheme>
<Id>12101</Id>
<Name>FBT</Name>
<Description>FBT Desc</Description>
<Type>AttributeBased</Type>
<ModDate>12/12/12</ModDate>
<Modversion>1</Modversion>
<Active>Y</Active>
</ClassificationScheme>
<ClassificationScheme>
<Id>12105</Id>
<Name>Electronics</Name>
<Description>Electronics Desc</Description>
<Type>Rulebase</Type>
<ModDate>12/12/12</ModDate>
TIBCO MDM Web Services Guide
208
|
Chapter 5 Data Services
<Modversion>1</Modversion>
<ModMemberId>1</ModMemberId>
<Active>Y</Active>
</ClassificationScheme>
</ClassificationSchemeListResponse>
</soapenv:Body>
</soapenv:Envelope>
For information on failure messages, refer to Table 12, Faults of Data Web
Services, on page 28.
TIBCO MDM Web Services Guide
GetClassificationSchemeAttributeList
|
209
GetClassificationSchemeAttributeList
This service allows you to retrieve all details of the classification scheme
including attributes (for attribute-based scheme), and rulebase details (for
rulebase-based scheme).
This service takes the name of the Repository name, classification scheme name,
and classification scheme ID as input and returns all the details of the
classification scheme including attributes (for attribute-based scheme), and
rulebase details (for rulebase-based scheme).
To use this web service:
1. Specify the user name, password, and enterprise in the request criteria.
2. Specify information such as Repository Name, and Classification Scheme
Name.
3. Invoke the web service by specifying the Endpoint URL as follows:
http://<servername>:<port>/eml/services/DataService/GetClassifi
cationSchemeAttributeListAction
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/repository/classification/
getClassificationSchemeAttrList_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/classification/
getClassificationSchemeAttrList_Response.xml
GetClassificationSchemeAttributeList - Inputs
This web service accepts the following inputs:
Input Description
User name Specify the login ID of the user.
Password Specify the password for the specified user name.
Enterprise Specify the name of the enterprise.
RepositoryName
(Mandatory)
Specify the name of the repository.
ClassificationScheme
ID
Specify the ID of the classification scheme.
TIBCO MDM Web Services Guide
210
|
Chapter 5 Data Services
GetClassificationSchemeAttributeList - Outputs
The response message contains Classification Scheme ID, Classification Scheme
Name, Classification Scheme Type, Classification Scheme Description, and
Classification Scheme Attributes.
Request:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<soapenv:Header/>
<soapenv:Body>
<ClassificationSchemeAttributeListRequest
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<UserInfo>
<UserName>a</UserName>
<Password>a</Password>
<Enterprise>a</Enterprise>
</UserInfo>
<Repository>
<Name>FBT_Repository</Name>
<ClassificationScheme>
<Id>FBT</Id>
<Name>FBT</Name>
</ClassificationScheme>
</Repository>
</ClassificationSchemeAttributeListRequest>
</soapenv:Body>
</soapenv:Envelope>
Response:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
ClassificationScheme
Name
(Mandatory)
Specify the name of the classification scheme.
Input Description
TIBCO MDM Web Services Guide
GetClassificationSchemeAttributeList
|
211
<soapenv:Header/>
<soapenv:Body>
<ClassificationSchemeAttributeListResponse
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<ClassificationScheme>
<SchemeId>FBT</SchemeId>
<Name>FBT</Name>
<Description>FBT Desc</Description>
<ModDate>12/12/12</ModDate>
<Modversion>1</Modversion>
<Active>Y</Active>
<Type>AttributeBased</Type>
<Attributes>
<Attribute typ="String">
<Name>percentageOfAlcohol</Name>
<Position>1</Position>
<Expression>@percentageOfAlcohol</Expression>
</Attribute>
</Attributes>
</ClassificationScheme>
</ClassificationSchemeAttributeListResponse>
</soapenv:Body>
</soapenv:Envelope>
For information on failure messages, refer to Table 12, Faults of Data Web
Services, on page 28.
TIBCO MDM Web Services Guide
212
|
Chapter 5 Data Services
GetClassificationCodeHierarchy
This service allows you to retrieve the classification code hierarchy depending on
the 'context' classification codes provided in the request.
The request can contain a single classification code or a hierarchy of codes. The
request is provided in two ways:
Code Hierarchical Notation
TreePath Notation
The web service also supports pagination of response. Specify the startCount'
and 'totalCount' of the classifcation codes required in the request. The
StartCount is optional. This will determine the total count of code which is
returned in the response.
While using TreePath Notation the name of the code is not required, only the
classification Code must be specified. The response will always be in the
ClassificationCode Notation. For more information, refer the samples , Sample 1:
GetClassification Code from Level 1 using treepath Notation, on page 214
This service takes repository name, classification ID and classification name as
mandatory inputs.
To use this web service:
1. Specify the user name, password, and enterprise in the request criteria.
2. Specify information such as Repository Name, and Classification Scheme
Name.
3. Invoke the web service by specifying the Endpoint URL as follows:
http://<servername>:<port>/eml/services/DataService/.....Action
A sample XML is available in
$MQ_HOME/schema/DataService/2.0/samples/repository/classification/GetClas
sificationCode_fromRoot_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/classification/GetClas
sificationCode_fromRoot_Response.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/classification/GetClas
sificationCode_fromLevel1_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/classification/GetClas
sificationCode_fromLevel1_Response.xml
$MQ_HOME/schema/DataService/2.0/samples/repository/classification/GetClas
sificationCode_withmultipleCodes_Request.xml
$MQ_HOME/schema/DataService/2.0/samplesrepository/classification/GetClass
ificationCode_withmultipleCodes_Response.xml
TIBCO MDM Web Services Guide
GetClassificationCodeHierarchy
|
213
GetClassificationCodeHierarchy - Inputs
This web service accepts the following inputs:
Input Description
User name Specify the login ID of the user.
Password Specify the password for the specified user name.
Enterprise Specify the name of the enterprise.
RepositoryName
(Mandatory)
Specify the name of the repository.
Classification ID Specify the ID of the classification scheme.
Classification Name
(Mandatory)
Specify the name of the classification scheme.
FetchDepth Specify the depth of the response code. Default
depth is 1.
Hierarchy Notation:
Code Specify the classification code.
Name Specify the classification code name.
Level Specify the level in the hierarchy. You need to specify
the level from the root node. The root node is same as
classfication scheme name and its level is 0.
Treepath Notation
Level Specify the level in the hierarchy. You need to specify
the level from the root node. The root node is same as
classfication scheme name and its level is 0.
Path Specify the code.
ReturnCount Specify the return count for paginated response. You
must specify the 'startCount' and 'totalCount' of the
codes required in the request. This field is optional.
TIBCO MDM Web Services Guide
214
|
Chapter 5 Data Services
GetClassificationCodeHierarchy - Outputs
The response message contains Classification Code, Classification Code Name,
Classification Code Description, Classification Code Attributes(if any) and its
level.
Sample 1: GetClassification Code from Level 1 using treepath Notation
Request:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<soapenv:Header />
<soapenv:Body>
<ns:ClassificationCodeRequest>
<ns:UserInfo>
<ns:UserName>a</ns:UserName>
<ns:Password>abc</ns:Password>
<ns:Enterprise>ws</ns:Enterprise>
</ns:UserInfo>
<ns:Repository>
<ns:Name>FBT</ns:Name>
<ns:ClassificationScheme>
<ns:Id>236901</ns:Id>
<ns:Name>FBT-Scheme</ns:Name>
</ns:ClassificationScheme>
</ns:Repository>
<ns:ClassificationCodeHierarchy>
<ns:FetchDepth>1</ns:FetchDepth>
<ns:ClassificationCodeTreePath>
<ns:TreePath>
<ns:Path level="1">50180000</ns:Path>
</ns:TreePath>
</ns:ClassificationCodeTreePath >
</ns:ClassificationCodeHierarchy>
</ns:ClassificationCodeRequest>
</soapenv:Body>
</soapenv:Envelope >
TIBCO MDM Web Services Guide
GetClassificationCodeHierarchy
|
215
Response:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/
"xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0"
>
<soapenv:Body>
<ns:ClassificationCodeResponse >
<ns:ClassificationCode Level="2">
<ns:Code>50181700</ns:Code>
<ns:Name>BAKING MIXES</ns:Name>
<ns:Description>Baking Mixes</ns:Description>
</ns:ClassificationCode>
<ns:ClassificationCode Level="2">
<ns:Code>50181900</ns:Code>
<ns:Name>BREAD</ns:Name>
<ns:Description>Bread</ns:Description>
</ns:ClassificationCode>
<ns:ClassificationCode Level="2">
<ns:Code>50182000</ns:Code>
<ns:Name>SWEET BAKERY PRODUCTS</ns:Name>
<ns:Description>Sweet Bakery Products</ns:Description>
</ns:ClassificationCode>
<ns:ClassificationCode Level="2">
<ns:Code>50182100</ns:Code>
<ns:Name>BISCUITS/COOKIES</ns:Name>
<ns:Description>Biscuits/Cookies</ns:Description>
</ns:ClassificationCode>
<ns:ClassificationCode Level="2">
<ns:Code>50182200</ns:Code>
<ns:Name>SAVOURY BAKERY PRODUCTS</ns:Name>
<ns:Description>Savoury Bakery
Products</ns:Description>
</ns:ClassificationCode>
<ns:ClassificationCode Level="2">
<ns:Code>50182300</ns:Code>
<ns:Name>BREAD PRODUCTS VARIETY PACKS</ns:Name>
<ns:Description>Bread Products Variety
Packs</ns:Description>
</ns:ClassificationCode>
</ns:ClassificationCodeResponse>
</soapenv:Body>
TIBCO MDM Web Services Guide
216
|
Chapter 5 Data Services
</soapenv:Envelope>
Sample 2: GetClassifcationCode from Root using Hierarchical Notation
Request:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:ns=
"http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<soapenv:Header />
<soapenv:Body>
<ns:ClassificationCodeRequest>
<ns:UserInfo>
<ns:UserName>a</ns:UserName>
<ns:Password>abc</ns:Password>
<ns:Enterprise>ws</ns:Enterprise>
</ns:UserInfo>
<ns:Repository>
<ns:Name>FBT</ns:Name>
<ns:ClassificationScheme>
<ns:Id>236901</ns:Id>
<ns:Name>FBT-Scheme</ns:Name>
</ns:ClassificationScheme>
</ns:Repository>
<ns:ClassificationCodeHierarchy>
<ns:FetchDepth>1</ns:FetchDepth>
<!--You have a CHOICE of the next 2 items at this level. i.e
- choice of using Hierarchical Notation or TreePath Notation -->
<!-- <ns:ClassificationCodeTreePath>
<ns:TreePath>
<ns:Path level="0">FBT-SCHEME</ns:Path>
</ns:TreePath>
</ns:ClassificationCodeTreePath> -->
<ns:ClassificationCodes>
<ns:ClassificationCode Level="0">
<ns:Code>FBT-SCHEME</ns:Code>
<ns:Name>FBT-SCHEME</ns:Name>
</ns:ClassificationCode>
</ns:ClassificationCodes>
</ns:ClassificationCodeHierarchy>
<!-- The next element ReturnCount is optional. Use only if
pagination is desired -->
TIBCO MDM Web Services Guide
GetClassificationCodeHierarchy
|
217
<ns:ReturnCount>
<ns:StartCount>1</ns:StartCount>
<ns:TotalCount>5</ns:TotalCount>
</ns:ReturnCount>
</ns:ClassificationCodeRequest>
</soapenv:Body>
</soapenv:Envelope >
Response:
<soapenv:Envelope
xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<soapenv:Body>
<ns:ClassificationCodeResponse>
<ns:ClassificationCode Level="1">
<ns:Code>50200000</ns:Code>
<ns:Name>BEVERAGES</ns:Name>
<ns:Description>Beverages</ns:Description>
</ns:ClassificationCode>
<ns:ClassificationCode Level="1">
<ns:Code>50180000</ns:Code>
<ns:Name>BREAD/BAKERY PRODUCTS</ns:Name>
<ns:Description>Bread/Bakery Products</ns:Description>
</ns:ClassificationCode>
<ns:ClassificationCode Level="1">
<ns:Code>50220000</ns:Code>
<ns:Name>DAIRY PRODUCTS</ns:Name>
<ns:Description>Dairy Products</ns:Description>
</ns:ClassificationCode>
<ns:ClassificationCode Level="1">
<ns:Code>50160000</ns:Code>
<ns:Name>SUGAR SWEETENING PRODUCTS</ns:Name>
<ns:Description> Sugar Sweetening Products</ns:Description>
</ns:ClassificationCode>
<ns:ClassificationCode Level="1">
<ns:Code>50230000</ns:Code>
<ns:Name>FOOD/BEVERAGE/TOBACCO PACKS</ns:Name>
<ns:Description>Food/Beverage/Tobacco
Packs</ns:Description>
</ns:ClassificationCode>
<ns:ClassificationCode Level="1">
TIBCO MDM Web Services Guide
218
|
Chapter 5 Data Services
<ns:Code>50250000</ns:Code>
<ns:Name>FRUITS (FRESH)</ns:Name>
<ns:Description>Fruits (Fresh)</ns:Description>
</ns:ClassificationCode>
</ns:ClassificationCodeResponse>
</soapenv:Body>
</soapenv:Envelope >
Sample 3: GetClassificationCode with Multiple codes in Request
Request:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns="http://www.tibco.com/cim/services/dataservice/wsdl/2.0">
<soapenv:Header />
<soapenv:Body>
<ns:ClassificationCodeRequest>
<ns:UserInfo>
<ns:UserName>a</ns:UserName>
<ns:Password>abc</ns:Password>
<ns:Enterprise>ws</ns:Enterprise>
</ns:UserInfo>
<ns:Repository>
<ns:Name>FBT</ns:Name>
<ns:ClassificationScheme>
<ns:Id>236901</ns:Id>
<ns:Name>FBT-Scheme</ns:Name>
</ns:ClassificationScheme>
</ns:Repository>
<ns:ClassificationCodeHierarchy>
<ns:FetchDepth>1</ns:FetchDepth>
<ns:ClassificationCodes>
<ns:ClassificationCode Level="1">
<ns:Code>50180000</ns:Code>
<ns:Name>BREAD/BAKERY PRODUCTS</ns:Name>
<ns:ClassificationCode Level="2">
<ns:Code>50181700</ns:Code>
<ns:Name>BAKING/COOKING MIXES/SUPPLIES</ns:Name>
</ns:ClassificationCode></ns:ClassificationCode>
</ns:ClassificationCodes>
TIBCO MDM Web Services Guide
GetClassificationCodeHierarchy
|
219
<!-- OR - using TreePath Notation -->
<!--<ClassififcationCodeTreePath>
<TreePath>
<Path level="1">50180000</Path>
<Path level="2">50181700</Path>
</TreePath>
</ClassififcationCodeTreePath>-->
</ns:ClassificationCodeHierarchy>
</ns:ClassificationCodeRequest>
</soapenv:Body>
</soapenv:Envelope >
For information on failure messages, refer to Table 12, Faults of Data Web
Services, on page 28.
TIBCO MDM Web Services Guide
220
|
Chapter 5 Data Services
TIBCO MDM Web Services Guide
|
221
Chapter 6 DataLoad Services
This chapter describes the usage and customization of data load web services.
Topics
Get DataSource Info Service, page 222
Upload DataSource Service, page 224
Import Records Service, page 226
Load Import Records Service, page 228
TIBCO MDM Web Services Guide
222
|
Chapter 6 DataLoad Services
Get DataSource Info Service
Using this service, you can get the detailed information of a data source for the
currently logged-in users. The users who can access the data source can get the
data source information.
For information on authentication of Get DataSource Info Service, refer to Table 8,
Authentication of DataLoad Web Services, on page 23.
To use this web service:
1. Specify the user details such as user name, password, and enterprise.
2. Specify the name of a datasource.
3. Invoke the web service by specifying the following endpoint URL:
http://<servername>:<port>/eml/services/DataLoadService/getData
sourceInfoAction
A sample XML is available in:
$MQ_HOME/schema/DataService/2.0/samples/datasource/GetDataSourceInfo
-request.xml
$MQ_HOME/schema/DataService/2.0/samples/datasource/GetDataSourceInfo
-response.xml
Get DataSource Info Service - Inputs
The following inputs are required for this web service:
Get DataSource Info Service - Outputs
For each data source, the following information are returned:
Data source ID
Data source name and its description
File name and its format, source table name
Input Description
User name Login ID of the user.
Password Password for the specified user name.
Enterprise Name of the enterprise.
DataSourceName Name of the data source.
TIBCO MDM Web Services Guide
Get DataSource Info Service
|
223
Delimiter code and value
Header line count
Use titles flag
File last uploaded date
Table last uploaded date
Loaded row count
Text qualifier
Thousand separator
Date format
Modification member ID, modification date, and modification version
Active
Transport protocol
For information on failure messages, refer to Table 13, Faults of DataLoad Web
Services, on page 29.
TIBCO MDM Web Services Guide
224
|
Chapter 6 DataLoad Services
Upload DataSource Service
Using this web service, you can upload a data source. To execute this web service,
ensure that the data source exists.
To use this web service:
1. Specify user details such as, the user name, password, and enterprise.
2. Specify the data source details such as, the data source name, execution mode,
and the file name.
3. Attach the data source file.
4. Invoke the web service by specifying the following endpoint URL:
http://<servername>:<port>/eml/services/DataLoadService/Datasou
rceUploadAction
The binary data value is automatically created.
The following are sample XML files:
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadDatas
ource-Async-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadDatas
ource-Async-Response.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadDatas
ource-Sync-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadDatas
ource-Sync-Response.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadDatas
ource-DBloaderSync-Request-fail.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadDatas
ource-DBloaderSync-Response-fail.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadDatas
ource-NonexistingRepository-Request-fail.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadDatas
ource-NonexistingRepository-Response-fail.xml
Upload DataSource Service - Inputs
The following inputs are required for this web service:
Input Description
User name The login ID of the user
Password The password for the specified user name
TIBCO MDM Web Services Guide
Upload DataSource Service
|
225
Upload DataSource Service - Outputs
If you upload the data source successfully, the Datasource uploaded
successfully message is displayed. The response contains event details
depending on the specified execution mode. The event details include the event
ID, status, state, and description of the event state and status.
For information on failure messages, refer to Table 13, Faults of DataLoad Web
Services, on page 29.
Enterprise The name of the enterprise
execmode
(Mandatory)
Specify the execution mode. The valid values are
ASYNCHR or SYNCHR.
DataSourceName
(Mandatory)
The name of the data source
FileName The name of the file. The filename must contain an
extension. The extension can be .csv or .txt.
Optional for SQL data sources, otherwise mandatory.
File as attachment The data source file you can attach using SOAP UI.
The file must include the records to be imported.
Optional for SQL data sources, otherwise mandatory.
BinaryData When you create a new request using SOAP UI, the
value for the <BinaryData> parameter is
automatically created. This is a unique value for
every request, and if the request contains an
attachment, specifying the binary data parameter is
mandatory.
Input Description
TIBCO MDM Web Services Guide
226
|
Chapter 6 DataLoad Services
Import Records Service
Using this web service, you can import records into the repository. To execute this
web service, ensure that a repository and an input map exist. Based on the input
map options, you can perform the following types of import:
Database loader
Relationships only
You can import records based on the values selected in an input map. The
following features are considered while importing:
Sequencing options for concurrent jobs
Message priorities as configured
To use this web service:
1. Specify user details such as, the user name, password, and enterprise.
2. Specify import record details such as, the execution mode, repository name,
and an input map name.
3. Invoke the web service by specifying the following endpoint URL:
http://<servername>:<port>/eml/services/DataLoadService/ImportA
ction
The following are sample XML files:
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/ImportRec
ords-Async-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/ImportRec
ords-Async-Response.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/ImportRec
ords-Sync-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/ImportRec
ords-Sync-Response.xml
Import Records Service - Inputs
The following inputs are required for this web service:
Input Description
User name The login ID of the user
Password The password for the specified user name
Enterprise The name of an enterprise
TIBCO MDM Web Services Guide
Import Records Service
|
227
Import Records Service - Outputs
The response contains event details based on the specified execution mode. The
event details include the event ID, its status and state, and event status and state
description.
For the ASYNCHR execution mode, if the records are imported successfully, the
Import initiated successfully message is displayed.
For the SYNCHR execution mode, if the records are imported successfully, the
Request Completed message is displayed.
For information on failure messages, refer to Table 13, Faults of DataLoad Web
Services, on page 29.
execmode
(Mandatory)
Specify the execution mode. The valid values are
ASYNCHR or SYNCHR.
Repository
(Mandatory)
The name of the repository. Specify any existing
repository name.
InputMapName
(Mandatory)
The name of an input map for importing data.
Specify any input map that exists in the specified
repository.
Input Description
TIBCO MDM Web Services Guide
228
|
Chapter 6 DataLoad Services
Load Import Records Service
Using this web service, you can upload the data source and import records into
the repository. You must have the security permissions to import records. Use this
web service when only one data source is associated with an input map. To
execute this web service, ensure that a repository, data source, and an input map
exist.
To use this web service:
1. Specify user details such as, the user name, password, and enterprise.
2. Specify load import record details such as, the execution mode, repository
name, input map name, and a file name.
3. Invoke the web service by specifying the following endpoint URL:
http://<servername>:<port>/eml/services/DataLoadService/LoadImp
ortAction
The following are sample XML files:
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadImpor
tRecords-Sync-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadImpor
tRecords-Sync-Response.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadImpor
tRecords-Async-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/dataloadservice/LoadImpor
tRecords-Async-Response.xml
Load Import Records Service - Inputs
The following inputs are required for this web service:
Input Description
User name The login ID of the user
Password The password for the specified user name
Enterprise The name of the enterprise
execmode
(Mandatory)
Specify the execution mode. The valid values are
ASYNCHR or SYNCHR.
TIBCO MDM Web Services Guide
Load Import Records Service
|
229
Load Import Records Service - Outputs
If you upload the data source and import records successfully, the Import
initiated successfully message is displayed. The response contains the
following:
The import event details such as, the event ID, status, state, and description of
the event state and status. These details are displayed depending on the
specified execution mode.
The import activity summary.
The number of records processed during the import.
For information on failure messages, refer to Table 13, Faults of DataLoad Web
Services, on page 29.
Repository
(Mandatory)
The name of the repository. Specify any existing
repository name.
InputMapName
(Mandatory)
The name of an input map for importing data
Any existing input map within the specified
repository
FileName The name of the data source file. You can attach the
file using SOAP UI. The filename must contain the
.csv or .txt extension.
Optional for SQL data sources, otherwise mandatory.
BinaryData When you create a new request using SOAP UI, the
value for the <BinaryData> parameter is
automatically created. This is a unique value for
every request, and if the request contains an
attachment, specifying the binary data parameter is
mandatory.
Input Description
TIBCO MDM Web Services Guide
230
|
Chapter 6 DataLoad Services
TIBCO MDM Web Services Guide
|
231
Chapter 7 Content Services
This chapter describes the usage and customization of content services.
Topics
Get Content Service, page 232
TIBCO MDM Web Services Guide
232
|
Chapter 7 Content Services
Get Content Service
This service allows you to download a file for the specified context. This service
takes DocumentId or DocumentPath as an input, also the context from where the
file needs to download is specified. If the context is accessible for you, only then
you can download the file. Currently, only the Event context is supported.
For information on authentication of Get Content Service, refer to Table 9,
Authentication of Content Web Services, on page 24.
To use this web service:
1. Specify user credentials to log on to TIBCO MDM.
2. Specify the Context to which the file belongs. For example, Event. If the
context specified is Event, you must have the View Event permission.
3. Specify either the DocumentId or DocumentPath of the file that is to be
downloaded.
4. Invoke the webservice by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/ContentService/download
Action
The file is successfully downloaded.
A sample XML is available in:
$MQ_HOME/schema/DataService/2.0/samples/content/ContentService-
Download-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/content/ContentService-
Download-Response.xml
Get Content Service - Inputs
The following inputs are mandatory for this web service:
Input Description
User name Login ID of the user.
Password Password for the specified user name.
Enterprise Name of the enterprise.
DocumentId The ID of the file that is to be downloaded. Either the
ID or path must be specified.
TIBCO MDM Web Services Guide
Get Content Service
|
233
Get Content Service - Outputs
If the file is retrieved successfully, the response contains the file name, file type,
inline binary data, and the success code.
For information on failure messages, refer to Table 14, Faults of Content Web
Services, on page 31.
DocumentPath The path of the file that is to be downloaded. Either
the ID or path must be specified.
Note: You can view the document ID and path of the file on the Event Details
page.
Context Context to which the file belongs. You can download
a file only for the Event context.
Input Description
TIBCO MDM Web Services Guide
234
|
Chapter 7 Content Services
TIBCO MDM Web Services Guide
|
235
Chapter 8 Event Management Services
This chapter describes the usage and customization of event management
services.
Topics
Get Event Info Service, page 236
Get Event Details Service, page 238
Get Import Event Status Service, page 240
TIBCO MDM Web Services Guide
236
|
Chapter 8 Event Management Services
Get Event Info Service
This service allows you to get event information for a specified event ID.
For information on authentication of Get Event Info Service, refer to Table 10,
Authentication of Event Management Web Services, on page 25.
To use this web service:
1. Specify the user name, password, and enterprise in the request criteria.
2. Specify the EventId for whom the event status and event summary needs to
retrieved.
If the EventId does not exist, an error message is returned in the response.
3. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/EventMgtService/getEven
tInfoAction
A sample XML is available in:
$MQ_HOME/schema/DataService/2.0/samples/eventmgmt/Event-GetInfo-Request.xml
$MQ_HOME/schema/DataService/2.0/samples/eventmgmt/Event-GetInfo-Response.xml
Get Event Info Service - Inputs
The following inputs are mandatory for this web service:
Input Description
User name Name of the user.
Password Password of the user.
Enterprise Name of the enterprise.
EventId ID of the event for which details need to be retrieved.
TIBCO MDM Web Services Guide
Get Event Info Service
|
237
Get Event Info Service - Outputs
The response message contains the Event type, Event State, Event Status, and
Event Summary. The Event Summary is different for each event type.
The event information returned depends on the type of the event, that is, the
event summary information is returned only for the events that have summary.
Also, the number of attributes in the summary information varies based on the
event. A file attribute in the summary information path or a documentId for that
attribute is also returned so that the Content service can be used to download the
document using this information.
For information on failure messages, refer to Table 15, Faults of Event
Management Web Services, on page 32.
TIBCO MDM Web Services Guide
238
|
Chapter 8 Event Management Services
Get Event Details Service
This service allows you to retrieve the event details for the specified Event ID. The
event details as displayed in the Event Log screen are retrieved.
For information on authentication of Get Event Details Service, refer to Table 10,
Authentication of Event Management Web Services, on page 25.
To use this web service:
1. Specify the user name, password, enterprise for the user, and an event ID.
2. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/EventMgtService/GetEven
tDetailsAction
A sample XML is available in:
$MQ_HOME/schema/DataService/2.0/samples/eventmgmt/GetEventDetails_
Request.xml
$MQ_HOME/schema/DataService/2.0/samples/eventmgmt/GetEventDetails_
Response.xml
Get Event Details Service - Inputs
The following inputs are mandatory for this web service:
Input Description
User name Name of the user.
Password Password of the user.
Enterprise Name of the enterprise.
EventId ID of the event for which details need to be retrieved.
This should be a valid event ID.
TIBCO MDM Web Services Guide
Get Event Details Service
|
239
Get Event Details Service - Outputs
The event details returned depend on the type of the event. For example, the
event summary information is returned only for the events that have a summary.
If there is a file attribute in the summary information path, the document ID for
the attribute is returned. The user uses this document ID to download the
document using the contentService.
The response message contains Event Details, Process Details, Process Logs
Details, and associated events.
For information on failure messages, refer to Table 15, Faults of Event
Management Web Services, on page 32.
TIBCO MDM Web Services Guide
240
|
Chapter 8 Event Management Services
Get Import Event Status Service
This service allows you to view the status of an import event. To check the status,
specify the Event ID of an import event. Before you run this web service, execute
the Import Records web service. For information, refer to Import Records Service
on page 226.
For information on authentication of Get Import Event Status Service, refer to
Table 10, Authentication of Event Management Web Services, on page 25.
To use this web service:
1. Specify the user name, password, enterprise for the user, and an event ID.
2. Invoke the web service by specifying the endpoint URL as follows:
http://<servername>:<port>/eml/services/EventMgtService/GetImpo
rtEventStatusAction
A sample XML is available in:
$MQ_HOME/schema/DataService/2.0/samples/eventmgmt/GetImportEventSt
atus_Request.xml
$MQ_HOME/schema/DataService/2.0/samples/eventmgmt/GetImportEventSt
atus_Response.xml
Get Import Event Status Service - Inputs
The following inputs are mandatory for this web service:
Input Description
User name Name of the user.
Password Password of the user.
Enterprise Name of the enterprise.
EventId ID of the event for which details need to be retrieved.
This should be a valid event ID.
TIBCO MDM Web Services Guide
Get Import Event Status Service
|
241
Get Import Event Status Service - Outputs
The response contains the following:
Import summary with the Success status.
Summary of the each activity of Import workflow.
For a Single repository, the following parameters are displayed:
RowsProcessed, NewRecords, ModifiedRecords, RejectedRecords,
EmptyIgnoredRecords, DuplicateRecords show the appropriate values based
on the Import approval option and the number of records imported.
For cross-repository, the following parameters are displayed in the
Relationship Summary: RecordsProcessed, RelationshipCreated,
RejectedRecords, DuplicateRelationship,RelationshipFailed. They contain the
appropriate values according to the number of records imported.
For information on failure messages, refer to Table 15, Faults of Event
Management Web Services, on page 32.
TIBCO MDM Web Services Guide
242
|
Chapter 8 Event Management Services
TIBCO MDM Web Services Guide
|
243
Index
A
Administrator Web Services 149
Create Enterprise Service 155
Create User Service 159
Delete User Service 171
Get Enterprise List Service 157
Get Entitlement Service 152
Get Role List Service 175
Get User List Service 173
Login Service 150
Logout Service 151
ASYNCHR mode of web service execution 3
AXIS2 19
C
Content Web Services 231
Get Content Service 232
customer support xv, xv
D
Data Web Services 177, 221
Extract Data Service 199
Get DataSource List Service 187, 222
Get Repository List Service 189
Initiate Synchronization Service 195
Text Search Service 178
Index Entity Fuzzy Query Service 183
Text Search Exact Query Service 181
Text Search Fuzzy Query Service 182
Upload Metadata Service 197
E
Event Management Web Services
Get Event Details Service 238, 240
Get Event Service 236
execution mode
Asynchronous mode (ASYNCHR) 3
Synchronous mode (SYNCHR) 2
P
Password Encryption and Decryption 33
R
Record Web Services 47
Initiate Workflow Service 108
Record Add Modify Services 96
Record Query MetaData 84
Record Query Service 61
Record Query ValidValues (Init) Service 88
Record Validate Service 94
S
Single Sign-On 18
support, contacting xv, xv
SYNCHR mode of web service execution 2
TIBCO MDM Web Services Guide
244
|
Index
T
technical support xv, xv
W
WebServices - Message Structure 5
Work Item Web Services 115
Get Custom Work Item Summary Service 140
Get Predefined Work Item Summary Service 146
Get Work Item Service 132
Work Item Lock Service 128
Work Item Modify Close Service 124
Work Item Query Parameters Service 116
Work Item Reassign Service 138
Work Item UnLock Service 130