Agile Product Lifecycle Management

SDK Developer Guide

January 2010

v9.3.0.2

Part No. E15928-02

ii Agile Product Lifecycle Management

Oracle Copyright

Copyright © 1995, 2010, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

This software and documentation may provide access to or information on content, products and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third party content, products and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third party content, products or services.

v9.3.0.2 iii

CONTENTS

Oracle Copyright ................................................................................................................................... ii

What's New in Release 9.3.0.2? ........................................................................................................ xx

What Was New in Release 9.3.0.1? ................................................................................................... xx

Introduction ...................................................................................................................... 1

About Agile SDK ...................................................................................................................................1

SDK Components .................................................................................................................................2

Client-Side Components..................................................................................................................................................... 2

Server-Side Components ................................................................................................................................................... 2

SDK Architecture ..................................................................................................................................3

System Requirements ..........................................................................................................................4

Java Requirements...............................................................................................................................4

Java Virtual Memory Parameters (JVM) to Avoid Out of Memory Exceptions ................................................................... 4

Agile SDK Installation Folders ..............................................................................................................5

Checking Your Agile PLM System .......................................................................................................5

Agile PLM Business Objects ................................................................................................................5

Getting Started with Agile API.......................................................................................... 7

Agile API Overview ...............................................................................................................................7

Types of Agile API Classes and Interfaces ........................................................................................................................ 7

Network Class Loading....................................................................................................................................................... 8

Single-Threaded versus Multi-Threaded Applications ........................................................................................................ 9

Packaging an Agile API Program ....................................................................................................................................... 9 Distributing Agile API Files ....................................................................................................... 9

Sample Programs ............................................................................................................................................................... 9

Starting an Agile API Program .......................................................................................................... 10

Setting the Class Path for the Agile API Library ............................................................................................................... 10

Importing Agile API Classes ............................................................................................................................................. 10

Creating a Session and Logging In .................................................................................................................................. 10

Creating a Session by Accessing a Password-Protected URL ........................................................................................ 12

Creating a Session from an Agile Web Service ................................................................................................................ 12

Loading and Creating Agile PLM Objects ......................................................................................... 13

Loading Objects................................................................................................................................................................ 13 Specifying Object Types ......................................................................................................... 14 Specifying Object Parameters ................................................................................................ 14 Loading Different Types of Objects ........................................................................................ 15

Creating Objects ............................................................................................................................................................... 18

iv Agile Product Lifecycle Management

Working with Agile PLM Classes ............................................................................................ 19 Creating Objects of User-Defined Subclasses ....................................................................... 20 Using AutoNumbers ............................................................................................................... 20 Setting the Required Fields .................................................................................................... 22 Creating Different Types of Objects ....................................................................................... 25

Checking the State of Agile PLM Objects......................................................................................................................... 29

Propagating Values to Related Objects............................................................................................................................ 29

Saving an Object to a New Object.................................................................................................................................... 30

Sharing an Object ............................................................................................................................................................. 30

Deleting and Undeleting Objects ...................................................................................................................................... 31

Closing a Session ............................................................................................................................................................. 33

Creating and Loading Queries ......................................................................................... 35

About Queries .................................................................................................................................... 35

Creating a Query ............................................................................................................................... 35

Saving a Query to a Folder ............................................................................................................... 36

Generating Ordered (sorted) or Unordered Query Results ............................................................... 37

Creating a Parameterized Query ....................................................................................................... 38

Specifying Query Attributes when Creating a Query ......................................................................... 39

Specifying Workflow Queries ............................................................................................................ 40

Specifying Search Criteria ................................................................................................................. 41

Search Conditions ............................................................................................................................................................ 41

Query Language Keywords .............................................................................................................................................. 42

Specifying Search Attributes ............................................................................................................................................ 42

Retrieving Searchable Attributes ...................................................................................................................................... 43

Using Relational Operators .............................................................................................................................................. 44 Using Unicode Escape Sequences ........................................................................................ 45 Using Between, Not Between, In, and Not In Operators ........................................................ 45 Using the Nested Criteria to Search for Values in Object Lists .............................................. 46 Using Criteria Selected from Criteria Library in SDK Queries ................................................ 47 Using Relationships and Content in SDK Queries ................................................................. 47 Searching for Words or Phrases Contained in Attachments .................................................. 48

Formatting Dates in Query Criteria ................................................................................................................................... 49

Using Logical Operators ................................................................................................................................................... 50

Using Wildcard Characters with the Like Operator ........................................................................................................... 50

Using Parentheses in Search Criteria .............................................................................................................................. 50

Using SQL Syntax for Search Criteria ............................................................................................... 51

Using SQL Wildcards ....................................................................................................................................................... 53

Sorting Query Results Using SQL Syntax ........................................................................................................................ 53

Setting Result Attributes for a Query ................................................................................................. 54

Specifying Result Attributes.............................................................................................................................................. 59

Retrieving CTO Originator Name ..................................................................................................................................... 60

v9.3.0.2 v

Duplicate Results for Site-Related Objects and AMLs ..................................................................................................... 61

Working with Query Results .............................................................................................................. 61

Sorting Query Results ...................................................................................................................................................... 61

Query Result Datatypes ................................................................................................................................................... 61

Managing Large Query Results ........................................................................................................................................ 62

Query Performance .......................................................................................................................................................... 62

Creating a Where-Used Query .......................................................................................................... 62

Loading a Query ................................................................................................................................ 63

Deleting a Query ................................................................................................................................ 64

Working with Tables ....................................................................................................... 67

About Tables ..................................................................................................................................... 67

Retrieving a Table ............................................................................................................................. 68

Accessing the New and Merged Relationships Tables ..................................................................... 69

Accessing the Relationships Table................................................................................................................................... 70

Accessing the Merged Tables .......................................................................................................................................... 70 Accessing the Merged Relationships.AffectedBy Table ......................................................... 70 Accessing the Merged Relationships.Affects table ................................................................ 70 Accessing the Merged Relationships.References Table ........................................................ 70

Working with Read-only Tables ........................................................................................................................................ 71

Retrieving the Metadata of a Table ................................................................................................... 71

Adding Table Rows ........................................................................................................................... 72

Adding an Item to the BOM Table .................................................................................................................................... 72

Adding an Attachment to the Attachments Table ............................................................................................................. 73

Adding a Manufacturer Part to the Manufacturers Table.................................................................................................. 73

Adding an Item to the Affected Items Table ..................................................................................................................... 74

Adding a Task to the Schedule Table............................................................................................................................... 74

Adding and Updating Multiple Table Rows ....................................................................................... 74

Adding Multiple Items to the BOM Table .......................................................................................................................... 75

Updating Multiple BOM Rows........................................................................................................................................... 75

Iterating Over Table Rows ................................................................................................................. 77

Updating Objects in Query Results with Multiple Page Tables ........................................................................................ 78 Updating Table Rows when Iterating Large Query Results ................................................... 78

Sorting Table Rows ........................................................................................................................... 78

Removing Table Rows ...................................................................................................................... 80

Retrieving the Referenced Object for a Row ..................................................................................... 81

Checking Status Flags of a Row ....................................................................................................... 85

Working with Page 1, Page 2, and Page 3 ....................................................................................... 85

Redlining ............................................................................................................................................ 86

Removing Redline Changes .............................................................................................................. 88

vi Agile Product Lifecycle Management

Removing Redline Changes in Bulk Mode ....................................................................................................................... 88

Identifying Redlined Rows and Redlined Cells ................................................................................. 89

Using ICell.getOldValue ................................................................................................................................................... 89

Working with Data Cells ................................................................................................. 91

About Data Cells ................................................................................................................................ 91

Data Types ........................................................................................................................................ 91

Checking User's Discovery Privilege ................................................................................................. 92

Checking Whether a Cell is Read-Only ............................................................................................. 93

Getting Values - 9.3 ........................................................................................................................... 93

Understanding SDK Date Formats and User Preferences ............................................................................................... 95

Setting Values ................................................................................................................................... 95

Catching Exceptions for Locked Objects .......................................................................................................................... 96

Getting and Setting List Values ......................................................................................................... 96

Getting and Setting Values for SingleList Cells ................................................................................................................ 97

Getting and Setting Values for MultiList Cells .................................................................................................................. 98

Getting and Setting Values for Cascading Lists ............................................................................................................... 98

Using Reference Designator Cells .................................................................................................. 100

Working with Folders .................................................................................................... 101

About Folders .................................................................................................................................. 101

Using Level Separation Characters in Folder and Object Names .................................................................................. 102

Loading a Folder .............................................................................................................................. 103

Creating a Folder ............................................................................................................................. 103

Setting the Folder Type ................................................................................................................... 104

Adding and Removing Folder Elements .......................................................................................... 104

Adding Folder Elements ................................................................................................................................................. 105

Removing Folder Elements ............................................................................................................................................ 105

Getting Folder Elements .................................................................................................................. 105

Deleting a Folder ............................................................................................................................. 108

Working with Items, BOMs, and AMLs .......................................................................... 109

About Items, BOMs, and Tables ..................................................................................................... 109

Working with Items .......................................................................................................................... 109

Getting and Setting the Revision of an Item ................................................................................................................... 109

Changing the Incorporated Status of a Revision ............................................................................................................ 112

Working with BOMs ......................................................................................................................... 112

Adding an Item to a BOM ............................................................................................................................................... 113

Expanding a BOM .......................................................................................................................................................... 113

Copying one BOM into another BOM ............................................................................................................................. 114

v9.3.0.2 vii

Creating BOM-Related Product Reports ........................................................................................................................ 115

Redlining a BOM ............................................................................................................................................................ 117 Getting a Released Assembly Item ...................................................................................... 117 Creating a Change Order ..................................................................................................... 118 Adding an Item to the Affected Items tab of a Change Order .............................................. 118 Modifying the Redline BOM Table ........................................................................................ 119

Working with AMLs .......................................................................................................................... 120

Adding an Approved Manufacturer to the Manufacturers Table ..................................................................................... 120

Redlining an AML ........................................................................................................................................................... 122

Accessing PLM Metadata with APIName Field .............................................................. 123

About APIName Field ...................................................................................................................... 123

Assigning Names to APIName Fields ............................................................................................. 124

APIName Validation Rules .............................................................................................................. 124

Accessing Metadata Using the APIName Field .............................................................................. 125

APIs that Support the APIName Field ............................................................................................................................ 125

SDK APIs to get the APIName Field .............................................................................................................................. 129

API Names of Root Administrator Nodes ....................................................................................................................... 130

API Name Examples ...................................................................................................................................................... 131

Subscribing to Agile PLM Objects ................................................................................. 137

About User Subscriptions ................................................................................................................ 137

Subscription Events ........................................................................................................................................................ 137

Subscribe Privilege ......................................................................................................................................................... 138

Subscription Notifications ............................................................................................................................................... 138 Sending Notifications with SDK ............................................................................................ 138

Deleting Subscribed Objects .......................................................................................................................................... 139

Getting Subscriptions for an Object ................................................................................................. 140

Modifying the Subscriptions for an Object ....................................................................................... 141

Making Attributes Available for Subscription ................................................................................... 142

Parent and Child Attributes............................................................................................................................................. 143

Working with Subscription Tables ................................................................................................... 144

Managing Manufacturing Sites ..................................................................................... 147

About Manufacturing Sites .............................................................................................................. 147

Controlling Access to Sites .............................................................................................................. 147

Creating a Manufacturing Site ......................................................................................................... 148

Loading a Manufacturing Site .......................................................................................................... 148

Retrieving the Sites Table for an Item ............................................................................................. 149

Adding a Manufacturing Site to the Sites Table .............................................................................. 149

Selecting the Current Manufacturing Site for an Item ..................................................................... 150

viii Agile Product Lifecycle Management

Disabling a Site ................................................................................................................................ 152

Working with Lists ........................................................................................................ 153

About Lists ....................................................................................................................................... 153

List Library ...................................................................................................................................................................... 153

SingleList Lists................................................................................................................................................................ 154

Cascading Lists .............................................................................................................................................................. 155

MultiList Lists .................................................................................................................................................................. 156

Methods that Use IAgileList ............................................................................................................................................ 156

Selecting a List Value ...................................................................................................................... 157

Working with Lifecycle Phase Cells ................................................................................................................................ 159

Working with Dynamic Lists............................................................................................................................................ 159 Enumerable and Non-Enumerable Lists .............................................................................. 160 Non-Enumerable PG&C Lists ............................................................................................... 161

Selecting a List from the List Library ............................................................................................... 161

Creating Custom Lists ..................................................................................................................... 163

Creating a Simple List .................................................................................................................................................... 163

Automatically Creating New Lists by Modifying Existing Lists ........................................................................................ 164

Creating a Cascading List .............................................................................................................................................. 165

Checking the Data Type of a List .................................................................................................... 167

Modifying a List ................................................................................................................................ 168

Adding a Value to a List.................................................................................................................................................. 168

Making List Values Obsolete .......................................................................................................................................... 169

Setting the List Name and Description ........................................................................................................................... 170

Setting Level Names for a Cascading List...................................................................................................................... 170

Enabling or Disabling a List ............................................................................................................................................ 170

Deleting a List ................................................................................................................................................................. 171

Modifying and Removing List Values ............................................................................................................................. 171

Printing Contents of IAgileList Objects ............................................................................................ 172

Working with Attachments and File Folder Objects ..................................................... 175

About Attachments and File Folders ............................................................................................... 175

Working with File Folders ................................................................................................................ 176

File Folder Classes and Subclasses .............................................................................................................................. 176

File Folder Tables and Constants................................................................................................................................... 177

Creating File Folder Objects ........................................................................................................................................... 177

Creating File Folder Objects by Adding Rows to Attachments Table ............................................................................. 180

Working with the Files Table of a File Folder ................................................................................................................. 180

Accessing Files in Agile PLM File Vault with IAttachmentFile ........................................................................................ 181

Working with Attachments Table of an Object ................................................................................ 182

v9.3.0.2 ix

Checking In and Checking Out Files with ICheckoutable ............................................................................................... 183

Specifying the Revision of the Item ................................................................................................................................ 184

Checking whether the Revision Is Incorporated ............................................................................................................. 184

Checking Out a File Folder .............................................................................................................. 185

Canceling a File Folder Checkout ................................................................................................... 185

Adding Files and URLs to the Attachments Table .......................................................................... 186

Deep Cloning Attachments and Files from One Object to Another ................................................................................ 188

Specifying the File Folder Subclass When Adding Attachments .................................................................................... 189

Retrieving Attachment Files............................................................................................................................................ 190

Deleting Attachments and File Folders........................................................................................................................... 191

Working with Thumbnails ............................................................................................................................................... 192 Accessing Thumbnails .......................................................................................................... 192 Regenerating Thumbnails .................................................................................................... 193 Setting Master Thumbnails ................................................................................................... 193 Replacing Thumbnails .......................................................................................................... 194 Sequencing Thumbnails ....................................................................................................... 195 Generating Thumbnails while Adding Files to Attachments Tab .......................................... 195

Working with Design Objects.......................................................................................................................................... 195

Adding and Loading Design Objects .............................................................................................................................. 196

Managing Version Specific Relationships between Design Objects .............................................................................. 196 Adding Relationships for Specific Versions of Design Objects ............................................ 196 Removing Relationships for Specific Versions of Design Objects ....................................... 197 Getting Relationships for Specific Versions of Design Objects ............................................ 197 Editing Relationships for Specific Versions of Design Objects ........................................... 197

Purging Specific Versions of Design Objects ................................................................................................................. 197

Searching Design Object Deployments with Where-Used Queries................................................................................ 198

Importing and Exporting Data with SDK ...................................................................... 201

About Importing and Exporting Data ............................................................................................... 201

Validating Import Data and Importing Data ..................................................................................... 201

Invoking Validation and Importing Data with SDK .......................................................................................................... 202

Exporting Data from the SDK .......................................................................................................... 204

Invoking Export from the SDK ........................................................................................................................................ 205

Managing Workflow ...................................................................................................... 207

About Workflow ............................................................................................................................... 207

The Change Control Process ......................................................................................................................................... 207

Dynamics of Workflow Functionality ............................................................................................................................... 208 How the Status of a Change Affects Workflow Functionality ............................................... 208 How User Privileges Affect Workflow Functionality .............................................................. 208

Selecting a Workflow ....................................................................................................................... 209

Adding and Removing Approvers .................................................................................................... 210

Setting the ―Signoff User Dual Identification‖ Preference ............................................................................................... 212

x Agile Product Lifecycle Management

Approving a Routable Object................................................................................................ 212 Rejecting a Routable Object ................................................................................................. 213 Adding User Groups of Approvers and Users to Approve Routable Objects ....................... 215 Approving a Routable Object by Users on behalf of ―Transferred from Users‖ ................... 216 Adding Active Escalations for the Current User to Approve a Routable Object ................... 217 Specifying a Second Signature to Approve a Routable Object ............................................ 218 Adding User ID as Second Signature to Approve a Routable Object .................................. 219

Approving or Rejecting a Change ................................................................................................... 220

Commenting a Change ................................................................................................................... 221

Auditing a Change ........................................................................................................................... 221

Changing the Workflow Status of an Object ................................................................................... 222

Sending an Agile Object to Selected Users .................................................................................... 225

Sending an Agile Object to User Groups ........................................................................................ 225

Managing and Tracking Quality .................................................................................... 227

About Quality Control ...................................................................................................................... 227

Quality-Related API Objects ........................................................................................................................................... 227

Quality-Related Roles and Privileges ............................................................................................................................. 228

Working with Customers ................................................................................................................. 228

About Customers ............................................................................................................................................................ 228

Creating a Customer ...................................................................................................................................................... 228

Loading a Customer ....................................................................................................................................................... 229

Saving a Customer as Another Customer ...................................................................................................................... 229

Working with Product Service Requests ......................................................................................... 230

About Problem Reports .................................................................................................................................................. 230

About Nonconformance Reports .................................................................................................................................... 230

Creating a Product Service Request .............................................................................................................................. 230

Assigning a Product Service Request to a Quality Analyst ............................................................................................ 231

Adding Affected Items to a Product Service Request..................................................................................................... 231

Adding Related PSRs to a Product Service Request ..................................................................................................... 232

Working with Quality Change Requests .......................................................................................... 233

Creating a Quality Change Request ............................................................................................................................... 233

Assigning a Quality Change Request to a Quality Administrator ................................................................................... 234

Saving a Quality Change Request as a Change ............................................................................................................ 234

Using Workflow Features with PSRs and QCRs ............................................................................. 235

Selecting Workflows for PSRs and QCRs ...................................................................................................................... 235

Creating and Managing Projects ................................................................................... 237

About Projects and Projects Objects ............................................................................................... 237

Differences in the Behavior of Projects Objects .............................................................................. 238

Creating Projects ............................................................................................................................. 238

Adding Rules for PPM Objects ........................................................................................................ 240

v9.3.0.2 xi

Loading Projects .............................................................................................................................. 241

Using Projects Templates ............................................................................................................... 241

Creating New Projects Using Templates ........................................................................................................................ 241

Creating Projects and Changing Ownerships................................................................................................................. 242

Saving Projects as Templates ........................................................................................................................................ 243

Scheduling Projects ......................................................................................................................... 244

Working with Projects Baselines ..................................................................................................... 247

Delegating Ownership of a Projects to Another User ...................................................................... 248

Adding Resources to a Projects‘ Team ........................................................................................... 248

Substituting Projects Resources ..................................................................................................... 251

Locking or Unlocking Projects ......................................................................................................... 252

Working with Discussions ................................................................................................................ 252

Creating a Discussion..................................................................................................................................................... 252

Replying to a Discussion ................................................................................................................................................ 254

Joining a Discussion ....................................................................................................................................................... 256

Creating an Action Item .................................................................................................................................................. 257

Working with Product Cost Management ..................................................................... 259

Overview .......................................................................................................................................... 259

Working with Price Objects ............................................................................................................. 260

Managing Pricing ............................................................................................................................. 260

Creating a Price Object .................................................................................................................................................. 261 Defaults ................................................................................................................................. 261 Specifying Item Revision ...................................................................................................... 262 Creating a Published Price ................................................................................................... 262

Loading a Price Object ................................................................................................................................................... 262

Adding Price Lines.......................................................................................................................................................... 263

Creating a Price Change Order ...................................................................................................................................... 264

Working with Suppliers .................................................................................................................... 265

Loading a Supplier.......................................................................................................................................................... 265

Modifying Supplier Data ................................................................................................................................................. 266

Working with Sourcing Projects ....................................................................................................... 267

Supported API Methods ................................................................................................................................................. 268

Loading an Existing Sourcing Project ............................................................................................................................. 268

Creating a Sourcing Project by Quantity Breaks ............................................................................................................ 269

Creating a Sourcing Project by Quantity Breaks and Price Periods ............................................................................... 269

Accessing and Modifying Objects, Tables, and Attributes.............................................................................................. 271 Setting Cover Page Values for a Sourcing Project .............................................................. 271

Understanding Nested Tables in PCM ........................................................................................................................... 272

xii Agile Product Lifecycle Management

Sourcing Project Parent Table and Nested Child Table Constants ..................................... 272 Accessing and Modifying Nested Tables in a Sourcing Project or RFQ .............................. 273 Accessing and Modifying a Sourcing Project's Status ......................................................... 273

Managing Data in Sourcing Projects .............................................................................................................................. 274 Setting Quantity for Items in a Sourcing Project ................................................................... 274 Performing Quantity Rollup in a Sourcing Project ................................................................ 275 Performing Cost Rollup in a Sourcing Project ...................................................................... 275 Performing Price Lookup in a Sourcing Project .................................................................... 276 Setting Partners in a Sourcing Project ................................................................................. 281 Modifying the Target Price for Items in a Sourcing Project .................................................. 282 Setting the Best Response for an Item in a Sourcing Project .............................................. 283

Working with RFQs......................................................................................................................................................... 284 Supported API Methods ....................................................................................................... 285 Creating RFQs for a Sourcing Project .................................................................................. 285 Loading Existing RFQs ......................................................................................................... 286 Loading RFQs from a Sourcing Project‘s RFQ Table .......................................................... 286 Accessing and Modifying RFQ Objects, Tables, Nested Tables, and Attributes ................. 287 Performing Price Lookup in RFQs ........................................................................................ 288 Working with RFQ Responses ............................................................................................. 289

Managing Product Governance & Compliance .............................................................. 291

About Agile Product Governance and Compliance ......................................................................... 291

Agile PG&C Interfaces and Classes ................................................................................................ 292

Agile PG&C Roles ........................................................................................................................... 292

Creating Declarations, Specifications, and Substances.................................................................. 293

Creating Declarations ..................................................................................................................................................... 293

Creating Specifications ................................................................................................................................................... 294

Creating Substances ...................................................................................................................................................... 295 Creating a Subpart ............................................................................................................... 295 Creating a Substance Group ................................................................................................ 296 Creating a Material ............................................................................................................... 296 Creating a Substance ........................................................................................................... 297

Adding Items, Manufacturer Parts, and Part Groups to Declarations ............................................. 297

Adding Substances to Declarations ................................................................................................ 298

Structure of Bill of Substances ....................................................................................................................................... 299

Rules for Adding Substances ......................................................................................................................................... 300

Adding Subparts and Materials that Do Not Exist .......................................................................................................... 300

Adding Examples to Substances .................................................................................................................................... 301 Adding Substances to Manufacturer Part Composition Table of Homogeneous Material Declarations .......................................................................................................................... 301 Adding Substances to Manufacturer Part Composition Table of Substance Declarations .. 303

Adding Substances to a Specification ............................................................................................. 304

Adding Specifications to a Declaration ............................................................................................ 305

Rules for Adding Specifications ...................................................................................................................................... 305

Routing Declarations ....................................................................................................................... 306

v9.3.0.2 xiii

Completing a Declaration ................................................................................................................ 307

Submitting a Declaration to the Compliance Manager .................................................................... 308

Publishing a Declaration .................................................................................................................. 308

Getting and Setting Weight Values ................................................................................................. 309

Adding Substance Compositions for a Manufacturer Part .............................................................. 310

Rolling Up Compliance Data ........................................................................................................... 312

Understanding the IPGCRollup Interface ....................................................................................................................... 313 Passing the Date Parameter ................................................................................................ 313

Using the IPGCRollup Interface ..................................................................................................................................... 313 Rolling Up Assembled Data on Items ................................................................................... 314 Rolling Up Assembled Data on MPNs .................................................................................. 314 Setting Values in the Calculated Compliance Field for Item Objects ................................... 315 Setting Values in the Calculated Compliance Field for Declaration Objects ........................ 316

Handling Exceptions ..................................................................................................... 317

About Exceptions............................................................................................................................. 317

Exception Constants........................................................................................................................ 318

Getting Error Codes......................................................................................................................... 318

Disabling and Enabling Error Codes with Bulk APIs ....................................................................... 318

Getting Error Messages .................................................................................................................. 319

Disabling and Enabling Warning Messages .................................................................................... 320

Checking if APIException is Warning and not Error ........................................................................ 321

Saving and Restoring Enabled and Disabled Warnings' State ....................................................... 321

Deleting Warnings Automatically Disabled by Agile API ................................................................. 322

Performing Administrative Tasks .................................................................................. 323

About Agile PLM Administration ...................................................................................................... 323

Privileges Required to Administer Agile PLM .................................................................................. 324

Administrative Interfaces ................................................................................................................. 324

Getting an IAdmin Instance ............................................................................................................. 325

Working with Nodes......................................................................................................................... 326

Working with the Classes Node...................................................................................................................................... 330

Managing Agile PLM Classes ......................................................................................................... 330

Concrete and Abstract Classes ...................................................................................................................................... 332

Referencing Classes ...................................................................................................................................................... 334

Identifying the Target Type of a Class ............................................................................................................................ 334

Working with Attributes .................................................................................................................... 335

Referencing Attributes .................................................................................................................................................... 335

Referencing Attributes - 9.3 ............................................................................................................................................ 336

Retrieving Attributes ....................................................................................................................................................... 337

Retrieving Individual Attributes ....................................................................................................................................... 338

xiv Agile Product Lifecycle Management

Editing the Property of an Attribute................................................................................................................................. 338

Working with User-Defined Attributes ............................................................................................................................. 339

Working with Properties of Administrative Nodes ........................................................................... 339

Managing Users .............................................................................................................................. 340

Getting All Users............................................................................................................................................................. 340

Creating a User .............................................................................................................................................................. 341

Creating a Supplier User ................................................................................................................................................ 342

Saving a User to a New User ......................................................................................................................................... 342

Checking for Expired Passwords.................................................................................................................................... 343

Configuring User Settings............................................................................................................................................... 343

Resetting User Passwords ............................................................................................................................................. 345

Deleting a User ............................................................................................................................................................... 345

Managing User Groups ................................................................................................................... 345

Getting All Users Groups ................................................................................................................................................ 346

Creating a User Group ................................................................................................................................................... 346

Adding a User Group to the User's User Group Table ................................................................................................... 348

Listing Users in a User Group ........................................................................................................................................ 348

Developing Process Extensions .................................................................................... 349

About Process Extensions .............................................................................................................. 349

Developing Custom Autonumber Sources ...................................................................................... 350

Defining a Custom Autonumber Source ......................................................................................................................... 350

Packaging and Deploying a Custom Autonumber Source ............................................................................................. 351

Configuring Custom Autonumber Sources in Java Client .............................................................................................. 352 Assigning Autonumber Sources to a Subclass .................................................................... 353

Developing Custom Actions ............................................................................................................ 353

Defining a Custom Action ............................................................................................................................................... 353 Formatting New Lines (Line Breaks) in PLM Clients ............................................................ 354

Custom Actions and User Sessions ............................................................................................................................... 354

Packaging and Deploying a Custom Action ................................................................................................................... 355

Roles and Privileges for Custom Actions ....................................................................................................................... 355 User Privileges for Configuring Process Extensions ............................................................ 356

Configuring Custom Actions in Agile Java Client ........................................................................................................... 356 Using the Process Extension Library ................................................................................... 356 Assigning Process Extensions to Classes ........................................................................... 358 Assigning Process Extensions to Workflow Statuses .......................................................... 358

Defining and Deploying URL-Based Process Extensions ............................................................... 359

Before Building a URL-Based Process Extension .......................................................................................................... 360

Defining a URL-Based Process Extension ..................................................................................................................... 360

Passing Encoded Agile PLM Information to Other Applications ..................................................................................... 361

Creating an Agile PLM Session from the Target System ............................................................................................... 361

v9.3.0.2 xv

Retrieving an Agile PLM Object from an HTTP Request ................................................................................................ 363

Identifying Attributes for Agile PLM Classes................................................................................................................... 363

Creating an External Report ............................................................................................................ 365

Deploying Process Extensions in a Clustered Environment ........................................................... 366

Best Practices for Copying third Party JAR Files ............................................................................ 366

Process Extensions FAQ ................................................................................................................ 367

Developing Web Service Extensions ............................................................................. 371

About Web Service Extensions ....................................................................................................... 371

Key Features .................................................................................................................................................................. 372

WSX Architecture ........................................................................................................................................................... 373

About Web Services ........................................................................................................................ 373

Web Services Architecture ............................................................................................................................................. 374

Security........................................................................................................................................................................... 375

Tools ............................................................................................................................................................................... 375

Finding Additional Information About Web Services ...................................................................................................... 376

Developing and Deploying a Web Service ...................................................................................... 376

About Deployment Descriptors ....................................................................................................................................... 376

Reserved Web Service Names ...................................................................................................................................... 377

Using a Web Service ....................................................................................................................... 377

Defining a Web Service Entry Point ............................................................................................................................... 378

Authenticating Users ....................................................................................................................... 378

Using Single Sign-On Cookies for Client-Server Access ................................................................ 379

Deployment Architecture ................................................................................................................................................ 379

Invoking the Web Service Client with a Single Sign-on Cookie...................................................................................... 379 Retrieve the Single Sign-On Cookie ..................................................................................... 379 Modifying the SOAP Binding Stub Code .............................................................................. 380

Preparing the Environment for MyFirstWebService Sample ........................................................... 380

Downloading Tools to Build the Sample ......................................................................................................................... 381

Installing the Java SDK .................................................................................................................................................. 381

Installing Ant .................................................................................................................................................................. 381

Building MyFirstWebService Sample .............................................................................................. 382

About Web Service Clients .............................................................................................................. 383

Client Programming Languages ..................................................................................................................................... 383

Accessing a Web Service ............................................................................................................................................... 384

Creating MyFirstClient ..................................................................................................................... 384

Generating the SOAP Request ...................................................................................................................................... 384

Submitting the SOAP Request ....................................................................................................................................... 385

Processing the SOAP Response.................................................................................................................................... 385

Running MyFirstClient .................................................................................................................................................... 386

xvi Agile Product Lifecycle Management

Creating an Agile Session inside WSX........................................................................................................................... 386

Microsoft .NET Interoperability ........................................................................................................ 386

Web Service Extensions FAQs ....................................................................................................... 387

Developing Dashboard Management Extensions ......................................................... 391

About Dashboard Management Extensions .................................................................................... 391

Roles and Privileges in Dashboard Management Extensions ........................................................................................ 392

Developing Custom Chart Dashboard Management Extensions .................................................... 392

Understanding ChartDataModel and ChartDataSet ....................................................................................................... 392

Defining a Custom Chart DX Data Source ..................................................................................................................... 392

Packaging and Deploying a Custom Chart DX Source .................................................................................................. 394

Configuring Chart DXs in Java Client ............................................................................................................................. 394 Displaying Optional Tabs in Agile Web Client ...................................................................... 395

Developing Custom Table Dashboard Management Extensions ................................................... 396

Understanding Collection and CustomTableConstants .................................................................................................. 396

Defining a Custom Table DX Data Source ..................................................................................................................... 396

Packaging and Deploying a Custom Table DX Source .................................................................................................. 399 To package and deploy a Table DX source: ........................................................................ 399

Configuring Table DXs in Java Client ............................................................................................................................. 400 To Add a Table to a Tab: ...................................................................................................... 400 To Add Data to Tables: ......................................................................................................... 401

Defining Custom (URL) Extensions ................................................................................................. 401

Agile PLM Events and Event Framework ....................................................................... 403

Understanding Agile PLM Events and Event Framework ............................................................... 403

Key Components of an Agile PLM Event ........................................................................................ 403

Event Types.................................................................................................................................................................... 404

Event Handler and Handler Types ................................................................................................................................. 405

Event Subscribers .......................................................................................................................................................... 405 Event Trigger and Trigger Types .......................................................................................... 405 Synchronous and Asynchronous Execution Modes ............................................................. 406 Event Error Handling Rule .................................................................................................... 406 Event Order .......................................................................................................................... 407

Event Generation, Processing, and Execution ................................................................................ 407

Working with Event Context Objects ............................................................................ 409

Understanding Event Context Objects ............................................................................................ 409

Persistent and Transient Data ........................................................................................................................................ 409

Event Information Objects .............................................................................................................................................. 410

Event Script Objects ....................................................................................................................................................... 412

Working with Event Information and Event Script Objects .............................................................. 413

Working with Base Event Actions ................................................................................................................................... 413

v9.3.0.2 xvii

Base Event Information Object - Java PX ............................................................................ 413 Base Event Script Objects - Script PX ................................................................................. 414

Working with General Object Actions ............................................................................................................................. 416 General Object Actions - Java PX ........................................................................................ 416 Working with General Base Event Script Objects ................................................................ 419

Working with Table and Relationship Actions ................................................................................................................ 422 Table and Relationship Actions - Java PX ........................................................................... 422 Table and Relationship Actions - Script PX .......................................................................... 424

Working with Workflow Object Actions ........................................................................................................................... 426

Workflow Object Actions - Java PX ................................................................................................................................ 426

Workflow Object Actions - Script PX .............................................................................................................................. 429

Working with Specific Object-Based Actions .................................................................................................................. 432 Specific Object-Based Actions - Java PX ............................................................................. 432 Specific Object-Based Actions - Script PX .......................................................................... 432

Working with Files and Attachments Objects Actions .................................................................................................... 433 Files and Attachments Objects Actions - Java PX ............................................................... 433 Files and Attachments Objects Actions - Script PX.............................................................. 434

Working with Product Governance and Compliance Actions ....................