Agile Advantage™ Application Development Kit COM/VB Developer

Agile Advantage™

A p p l ic a t io n D e v e lo p m e n t K i t C O M /V B D e v e lo p e r G u id e – V o l 1

December 2008

v2006 SP4

Part No. E12874_Vol1-01

Agile Advantage 2006

Copyright © 1995, 2008, 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.


CONTENTSPreface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-i

TTY Access to Oracle Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-iReadme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-iAgile Training Aids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-iiAccessibility of Code Examples in Documentation . . . . . . . . . . . . . . . . . . . . . . . 1-iiAccessibility of Links to External Web Sites in Documentation . . . . . . . . . . . . . 1-ii

Chapter 1Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

What is the Agile Advantage ADK? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1What’s New for this Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Agile Advantage 2006 ADK Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

AgileAPI Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Documentation Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4LicenseKey Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Samples Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Supported Development Environments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5Sample Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Chapter 2Developing Programs with the Agile Advantage API . . . . . . . . . . . . . . . . . . . . . . 2-1

Working with Agile Advantage API Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Agile Advantage API Inheritance Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Declaring Agile Advantage Objects Using Early or Late Binding . . . . . . . . . . . . 2-3Avoiding Name Collisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3Externally Creatable Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

Structuring Your Agile Advantage API Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

Common Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Prefixes for Named Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8

5


Properties and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13Working with Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13

Referencing Attributes in Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14Tabs and Tables for Agile Advantage Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15Attribute IDs Shared Between Multiple Classes . . . . . . . . . . . . . . . . . . . . . . . . . 2-17

Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18Single-Threaded versus Multithreaded Applications . . . . . . . . . . . . . . . . . . . . . . . . 2-19VBScript Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19Creating and Modifying Agile Advantage Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20Mapping Agile Advantage Client Features to the Agile Advantage API. . . . . . . . . . 2-22

Login Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24Manufacturer Parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26Manufacturers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29Attachments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30Queries (Searches) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32Problem Reports and Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32Quality Change Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32Agile Administrator Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-33Suppliers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-34

Packaging Your Agile Advantage API Application. . . . . . . . . . . . . . . . . . . . . . . . . . . 2-35Agile Advantage ADK Files You Are Allowed to Distribute . . . . . . . . . . . . . . . 2-35Agile Advantage ADK Files You Are Not Allowed to Distribute. . . . . . . . . . . . 2-36

Chapter 3Upgrading Programs to Agile Advantage ADK 2006 . . . . . . . . . . . . . . . . . . . . . . . 3-1

Upgrading Programs from Agile 8.5 SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Changes Made to Agile Advantage 2006 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

New Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1New Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2New Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Changes Made to Agile 8.5 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

6 COM/VB Developer Guide

Contents

Agile 8.5 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Agile 8.5 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Agile 8.5 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Chapter 4Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Creating an Application Using Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Part I: Setting Up the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Part II: Using the Object Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3Part III: Creating the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4Part IV: Setting Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5Part V: Entering the Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6Part VI: Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9

Creating a Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11Part I: Setting Up the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11Part II: Creating the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12Part III: Setting Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13Part IV: Entering the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13

Displaying SmartRules Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18Part I: Setting Up the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18Part II: Creating the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19Part III: Setting Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20Part IV: Entering the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20

Synchronizing the BOMs of Two Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23Part I: Setting Up the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24Part II: Creating the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24Part III: Setting Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25Part IV: Entering the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26

Redlining a BOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33Part I: Setting Up the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33Part II: Logging In. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33Part III: Declaring Public Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-33Part IV: Adding a RedlineBOM Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34Part V: Getting a Released Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34Part VI: Creating a Change. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34Part VII: Adding the Part to the Affected Items Tab of the Change . . . . . . . . . 4-35Part VIII: Setting the Revision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35Part IX: Modifying the Redline BOM Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36Complete Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36

7


Creating an ASP Application Using Visual InterDev . . . . . . . . . . . . . . . . . . . . . . . . 4-39Part I: Setting Up the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39Part II: Designing the Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40Part III: Setting Properties of the Login Page . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-42Part IV: Adding Scripting to the Login Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-42Part V: Designing the Main Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-43Part VI: Setting Properties of the Main Page . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-44Part VII: Adding Scripting to the Main Page . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-45Part VIII: Adding a Link from the Login Page to the Main Page . . . . . . . . . . . 4-46Part IX: Running the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-46

Chapter 5Managing and Tracking Quality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

About Quality Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Quality-Related API Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Quality-Related Roles and Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Working with Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3About Customers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Creating a Customer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3Loading a Customer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4Customer Tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5Saving a Customer as Another Customer with a Different Site . . . . . . . . . . . . . 5-5

Working with Problem Reports and Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6About Problem Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6About Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7Creating a Problem Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7Creating an Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8Problem Report and Issue Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10Assigning a Problem Report or Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10Associating a Problem Report or Issue with an Item. . . . . . . . . . . . . . . . . . . . . 5-11Linked Fields for Problem Reports and Issues . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

Working with Corrective Action Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12About CARs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12Creating a CAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13Assigning a CAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14CAR Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15Saving a CAR as an ECO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15

Using Workflow Features with Problem Reports, Issues, and CARs . . . . . . . . . . . . 5-18Selecting a Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18


Contents

Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19Working with the Related PSR Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20

Chapter 6Agile Advantage API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Agile Advantage API Class Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1ActivityQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3ApprovedMfr. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12ApprovedMfrs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14Attachment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16Attachments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26Attribute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29Base. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30BOMComponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37BOMComponents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-39CCBQuery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42Change . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-53Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-58CriteriaBag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-67Customer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-71DataObject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-75Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-85Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-97Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-112ListElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-125Mfr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-127MfrPart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-131Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-135ObjectInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-138Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-139PrintOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-143Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-146Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-152RouteObject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-177Row. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-192Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-206ServiceRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-229SubClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-233Supplier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-238

9


SyncOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-241Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-243Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-244User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-250

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-261

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1


Contents

11



Preface

The Agile Advantage documentation set includes Adobe® Acrobat™ PDF files. The Oracle Technology Network (OTN) Web site (http://www.oracle.com/technology/documentation/agile.html) contains the latest versions of the Agile Advantage PDF files. You can view or download these manuals from the Web site, or you can ask your Agile administrator if there is an Agile Advantage Documentation folder available on your network from which you can access the Agile Advantage documentation (PDF) files.

Note To read the PDF files, you must use the free Adobe Acrobat Reader™ version 7.0 or later. This program can be downloaded from the Adobe Web site (http://www.adobe.com).

If you need additional assistance or information, please contact Customer Support (http://www.oracle.com/agile/support.html) for assistance.

Note Before calling Agile Support about a problem with an Oracle|Agile Advantage manual, please have the full part number, which is located on the title page.

TTY Access to Oracle Support Services

Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services within the United States of America 24 hours a day, 7 days a week. For TTY support, call 800.446.2398. Outside the United States, call +1.407.458.2479.

Readme

Any last-minute information about Agile Advantage can be found in the Readme file on the Oracle Technology Network (OTN) Web site (http://www.oracle.com/technology/documentation/agile.html).

i

http://www.oracle.com/technology/documentation/agile.html


http://www.oracle.com/agile/support.html



http://www.oracle.com/agile/support.html

http://www.adobe.com




Agile Training Aids

Go to the Oracle University Web page (http://www.oracle.com/education/chooser/selectcountry_new.html) for more information on Agile Training offerings.

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

ii

http://www.oracle.com/education/chooser/selectcountry_new.html

iii


iv

v


vi

CHAPTER 1Introduction

What is the Agile Advantage ADK?The Agile Advantage ADK is a collection of application programming interfaces (APIs), sample applications, and documentation. ADK stands for Application Development Kit. The Agile Advantage API for COM is contained within an in-process automation server, a file named AgileAPI.dll. The interfaces expose Agile Advantage objects to developers, allowing them to build custom applications that access the functions of these objects.

What’s New for this ReleaseThe Agile Advantage ADK supports these new features by allowing you to create and modify the following Product Quality items:

This chapter introduces you to the Agile API’s features. It contains the following topics:❑ What is the Agile Advantage ADK?❑ What’s New for this Release❑ Key Features❑ System Requirements❑ Agile Advantage 2006 ADK Folders❑ Licensing❑ Supported Development Environments❑ Sample Applications❑ Security

1-1

Agile Advantage 2006 ADK

❑ Customers❑ Compliance Support❑ Problem Reports❑ Issues❑ Corrective Action Requests (CARs)

For complete details about Agile Advantage API interface changes, see Chapter 3, “Upgrading Programs to Agile Advantage ADK 2006.”

Key FeaturesThe Agile Advantage ADK lets you build custom applications that access Agile Advantage eHub functionality. By using the Agile Advantage API, you can create scripts or applications that perform Agile Advantage tasks automatically.

The Agile Advantage ADK lets you do the following:

❑ Integrate the Agile Advantage system with ERP applications or other custom applications.

❑ Extend the functionality of the Agile Advantage system. For example, you could use the API to create custom reports.

❑ Develop applications to process Packages of product data.

❑ Perform batch operations against the Agile Advantage eHub.

❑ Access the Agile Advantage Windows client features from within other OLE-compatible applications, such as Microsoft Office.

❑ Use a variety of different development environments to build applications that control the Agile Advantage eHub.

1-2 Developer Guide

Chapter 1 Introduction

The Agile Advantage ADK contains the following:

❑ Agile Advantage ADK COM/VB Developer Guide (This manual)❑ Agile Advantage API server and supporting libraries❑ Runtime DLLs (such as APMsg32.dll)❑ Sample applications

System RequirementsFor Agile Advantage ADK system requirements, please see the Agile Advantage 2006 Installation and Maintenance Guide.

Agile Advantage 2006 ADK FoldersThe Agile Advantage ADK files have the following folder structure on your computer:

- <Agile Advantage Home Folder>- ADK

- COMAgileAPIDocumentationLicenseKey

+ Samples

AgileAPI Folder

The Agile Advantage ADK\COM\AgileAPI folder contains the following files:

❑ AgileAPI75.dll — the Agile 7.5 API library, which contains all Agile 7.5 API classes and interfaces.



❑ AgileAPI90.dll — the Agile Advantage 2006 API library, which contains all Agile Advantage 2006 API classes and interfaces.

❑ AgileAPI.dll — the Agile Advantage API library, which contains all Agile Advantage API classes and interfaces.

❑ APMsg32.dll — the Agile Advantage client applications error message strings.

❑ eHubMsg.dll — the Agile Advantage eHub server message strings.

1-3


❑ MFC42.dll — the Microsoft Foundation Classes (MFC) version 4.2 APIs.❑ MSVCRT.DLL — the Microsoft Visual C++ 6.0 RunTime libraries.

Documentation Folder

The Agile Advantage ADK\COM\Documentation folder is empty. It is where you would place a copy of the Agile Advantage ADK VB/COM Developer Guide manual in Adobe Acrobat format (PDF). To view this file, you need the Adobe Acrobat Reader, which can be downloaded and installed from the Adobe website.

LicenseKey Folder

The Agile Advantage ADK\COM\LicenseKey folder contains the license key text file, AgileAPI.lic.

Samples Folder

The Agile Advantage ADK\COM\Samples folder contains source code, executables, and Readme files for all sample applications created using the VB/COM APIs.

LicensingAgile Software Corporation (Agile) requires any company or individual writing code to the Agile Advantage API to legally obtain an Agile Advantage ADK license. The Agile Advantage ADK license grants the licensee the right to use the Agile Advantage API in a design environment and to freely distribute the Agile Advantage API with any application written by the licensee that makes calls to the Agile Advantage API. The Agile Advantage ADK license prohibits the distribution of the Agile Advantage API documentation, sample code, and source code to any other party that has not legally obtained an Agile Advantage ADK license. It also explicitly prohibits the development of competing applications.

Each API has a separate license key, which is located in a text file called AgileAPI.lic in the LicenseKey subfolder. The Agile API license key is the first line of text in the AgileAPI.lic file. Whenever you reference the license key in a program, make sure you specify the entire string. Otherwise, you cannot connect to an Agile Advantage eHub.

1-4 Developer Guide

Chapter 1 Introduction

If you write a program that uses the Agile Advantage API, it must call the Server.setLicenseKey() method for each Server instance your application creates. The setLicenseKey() method enables your application to have access to Agile Advantage API functionality.

Supported Development EnvironmentsAgile Software has not certified any particular development tool for use with the Agile Advantage API.

Sample ApplicationsThe Agile Advantage ADK provides several sample applications that demonstrate how to use the Agile Advantage API. When you install the Agile Advantage ADK, the sample applications are installed into the following path:

\<Agile Home Folder>\ADK\COM\Samples

Each of the Agile Advantage ADK sample applications has its own README file. Before running a sample application or working with its source files, read the README file for any setup or configuration instructions.

SecurityThe Agile Advantage API exposes its services in a secure manner. All communication between the Agile Advantage eHub and Agile Advantage API programs is encrypted using RC4 from RSA to prevent data tampering and unauthorized access. For more information about RSA, see http://www.rsasecurity.com. In addition, only authorized users can access Agile data. Requests made to the Agile Advantage eHub™ and iFS™ servers are subject to the same security restrictions as requests made using the Agile Windows client and other Agile Advantage products. For more information about Agile Advantage security, refer to the Agile Administrator 2006 User Guide.

1-5


1-6 Developer Guide

CHAPTER 2Developing Programs with

the Agile Advantage API

Working with Agile Advantage API ObjectsEach Agile Advantage object is a separate class. Before you begin programming with the Agile Advantage API, you should understand the Agile Advantage object hierarchy. The hierarchy shows the relationships that objects have with one another. It also is key to understanding the properties and methods inherited from

This chapter describes the classes and objects in the Agile API. It contains the following topics:❑ Working with Agile Advantage API Objects❑ Structuring Your Agile Advantage API Program❑ Naming Conventions❑ Properties and Methods❑ Data Types❑ Working with Attributes❑ Memory Management❑ Single-Threaded versus Multithreaded Applications❑ VBScript Support❑ Creating and Modifying Agile Advantage Users❑ Mapping Agile Advantage Client Features to the Agile Advantage API❑ Packaging Your Agile Advantage API Application

2-1


superclasses. For example, the Base class has properties that all other Agile Advantage objects inherit.

Note Before your application can work with Agile objects, you must first create an instance of the Server object.

Agile Advantage API Inheritance Model

The following list represents the inheritance model of the Agile Advantage API object hierarchy.

❑ Base❑ ActivityQuery❑ CCBQuery❑ Collection❑ CriteriaBag❑ Field❑ Folder❑ ListElement❑ Node

❑ Attribute❑ SubClass❑ Tab❑ User

❑ ObjectInfo❑ PrintOption❑ Property❑ Query❑ Row

❑ ApprovedMfr❑ Attachment❑ BOMComponent❑ DataObject

❑ Customer❑ Supplier❑ Item❑ Mfr❑ MfrPart❑ RouteObject

❑ Change

2-2 Developer Guide

Chapter 2 Developing Programs with the Agile Advantage API

❑ Package❑ ServiceRequest

❑ Server❑ SyncOption❑ Table

❑ ApprovedMfrs❑ Attachments❑ BOMComponents

Declaring Agile Advantage Objects Using Early or Late Binding

When declaring Agile Advantage object variables, you can use early or late binding. Binding refers to the way you set up object references in your program. Early binding is generally faster than late binding.

To use early binding of objects, fully declare all objects by referencing the AgileAPI library and the object name. By fully declaring the Agile Advantage API objects in Visual Basic, you enable your project to use Visual Basic’s IntelliSense features and context-sensitive help for the Agile Advantage API. With early bound object variables, Visual Basic detects the object’s properties and methods at design time.

To use late binding of objects, declare all Agile Advantage objects generically as “Object.” For example, the following declaration of an Agile Advantage Server object uses late binding:

Public currServer As ObjectSet currServer = CreateObject("AgileAPI.Server")

For late-bound objects, Visual Basic determines at run time whether the object has the properties and methods you call with the variable. It therefore always creates the most recent version of the object. However, because late binding is slower you should use it only when it is unavoidable, for example, when the object type of a variable cannot be known at design time.

Note If you are programming with a scripting environment such as VBScript, you must declare all Agile Advantage API objects using late binding.

Avoiding Name Collisions

To avoid object name collisions, make sure you fully qualify references to objects in other libraries with the following syntax:

[libraryname.]objectname

2-3


where libraryname is the class name of the control or object library and objectname is the name of the object.

For example, to declare a Node object—an item in a TreeView control—in Visual Basic, type the following declaration:

Dim node As mscomctllib.Node

Externally Creatable Objects

Server is the top-level externally creatable object in the Agile API. Before your application can work with other Agile objects, you must first create an instance of the Server object, as shown in the following sample code.

Dim server As AgileAPI.ServerSet server = CreateObject("AgileAPI.Server")server.SetLicenseKey "AgileAPILicenseKey"b = server.Connect(ehub1, 9013, scfAll)b = server.Login("username", "password", "C:\Agile85\Temp\Files",

16384)

In addition to the Server object, the Agile API also provides several other externally creatable objects. Some require initialization by an Agile eHub. Others can be created without being initialized by an Agile eHub.

The following Agile objects are externally creatable but require initialization by an Agile eHub:

❑ ActivityQuery❑ CCBQuery❑ Change❑ Customer❑ Folder❑ Item❑ Mfr❑ MfrPart❑ Package❑ Query❑ ServiceRequest❑ Supplier

For example, to create a new Item in your program, you first create the Item object and then initialize it using the Item::Create method, as shown in the following sample code.

Dim part As AgileAPI.ItemDim b As BooleanSet part = CreateObject("AgileAPI.Item")

2-4 Developer Guide


b = part.Create(server, "Part", "P1001")

If you try to access an Agile object that has not been initialized by an instance of a Server object, the Agile API returns an error that reads “Object not initialized.” To verify whether an object is initialized, use the Base::IsInit method.

The following Agile objects are externally creatable and do not require initialization by an Agile eHub. You can work with them as soon as you create them.

❑ Collection❑ ListElement❑ ObjectInfo❑ PrintOption❑ SyncOption

Structuring Your Agile Advantage API ProgramWhen you create a program using the Agile Advantage API, follow this general approach for structuring your program:

1 Create a Server object.

Dim server As AgileAPI.ServerSet server = CreateObject("AgileAPI.Server")

2 Set the Agile Advantage API license key.

server.SetLicenseKey "AgileAPILicenseKey"

3 Connect to the Agile Advantage eHub.

b = server.Connect(eHub1, 9013, scfAll)

4 Log in to the Agile Advantage eHub.

b = server.Login("jpowers", "agile", "c:\temp", 16384)

5 Complete one or more business processes. This is where most of your program code goes.

6 When finished, disconnect from the Agile Advantage eHub.

server.Disconnect

Naming ConventionsThe Agile Advantage API has straightforward names to make the function of object classes easily recognizable. Clearly named objects make browsing through the object hierarchy faster and easier, especially in development environments such as Visual Basic that have an Object Browser.

2-5


Common Terms

Several common terms have been used throughout the API class names, properties, methods, and parameters. Because these terms serve as a basic glossary for the API, you should be familiar with them before browsing the Agile Advantage API object hierarchy.

Table 2-1: Common terms

Term Description

Approved Manufacturers List

A table that lists Manufacturers and Manufacturer Parts that have been approved to produce a particular part.

Attribute An inherent characteristic of an object. When you open an object in the Agile Advantage Windows client, each field in the tabbed dialog box corresponds to an attribute. For example, one attribute of the BOM table is Find Num, which displays a find number for a BOM component.

Change Any type of Change object in Agile CM. Examples of Change objects are CARs, ECOs, ECRs, Deviations, MCOs, and Stop Ships.

Collection An ordered array of items. All items in a collection have the same type. A collection can contain objects, integers, or strings. For example, Server::GetSubclasses returns the collection of subclasses.

Corrective Action Request

A type of Change that addresses defects that surfaced from Product Service Requests (issues and problem reports).

Criteria Data that characterizes a query, which is also called a search. In the Agile Advantage Windows client, criteria are also called search conditions.

Customer A customer that purchases your company’s products and provides feedback on quality issues.

Item In the Agile Advantage Windows client, an Item is either a Part or a Document.

List A selection of values for a particular property.

List element One member in a list of values.

Manufacturer An object that contains contact information and other data related to a Manufacturer.

Manufacturer Part An object that contains information about the Part produced by a Manufacturer. The Manufacturer Part can show whether the Manufacturer is the preferred or an alternate Manufacturer and whether it’s currently an active Manufacturer of the Part. It also shows the Manufacturer’s part number.

2-6 Developer Guide


Abbreviations

In general, abbreviations have been avoided in the Agile Advantage API, except for those shown in Table 2-2.

Package An object representing a collection of product data, for example, all data on a particular assembly and its children. A Package can include BOMs, Item data, Change History, and attachments. Most operations that involve a Package (such as creating, routing, or approving a Package) require an Agile Advantage Package Server license.

Product Service Request Either a problem report, which is a part defect reported by a customer, or an issue, which is a problem that has been investigated by a Quality Analyst and has been determined to be a defect.

Property Specifies the value of a particular data member in an object. Generally provides information about the state of the object, such as its name or data type.

Query An object representing a new search in the Agile Advantage Windows client.

Subclass An object that derives from one of the Agile Advantage object types: Item, Change, Manufacturer, Manufacturer Part, or Package. All object types can have subclasses. Agile Advantage supplies 15 predefined subclasses (CAR, Customer, ECO, ECR, Deviation, Document, Issue, MCO, Package, Part, Problem Report, Stop Ship, Manufacturer, Manufacturer Part, Supplier), but you can define others (for example, Capacitor and Resistor).

Supplier An object that represents vendors who supply manufacturer parts.

Table An object representing a tabular presentation of data in the Agile Advantage Windows client. Most data in the Agile Advantage Windows client is presented in tables. For example, the BOM, Attachments, and Manufacturers tabs for a Part are all tables. Table should not be confused with a database table where the Agile Advantage Windows client stores its data.

Table 2-2: Abbreviations used in the Agile Advantage API

Abbreviation Description

AML Approved Manufacturer List

Table 2-1: Common terms

Term Description

2-7


Prefixes for Named Constants

Named constants supported by the Agile Advantage API start with a prefix that identifies the type of constant. For example, the constant ctChange is a class type constant. Table 2-3 lists constant prefixes used by the Agile Advantage API.

BOM Bill of Material

CAR Corrective Action Request

ECO Engineering Change Order

ECR Engineering Change Request

Mfr Manufacturer

MfrPart Manufacturer Part

MCO Manufacturer Change Order

PSR Product Service Request

Table 2-3: Constant prefixes

Prefix Description

aid Attribute ID

aqt ActivityQuery type

cblo CriteriaBag logical operator

cbro CriteriaBag relational operator

cqit CCBQuery interval type

cqvt CCBQuery value type

cqt CCBQuery type

ct Class type

dt Data type

fso Folder sort order

ft Folder type

nid Node ID

lic User license

nt Node type

oim ObjectInfo mask

ot Object type

pid Property ID

Table 2-2: Abbreviations used in the Agile Advantage API

Abbreviation Description

2-8 Developer Guide


Properties and MethodsMost objects in the Agile Advantage API have properties and methods. The properties and methods allow you to access and manipulate data on the Agile Advantage eHub.

Properties

A property is a member function that sets or returns information about the state of the object, such as its name or data type. Several Agile Advantage API properties have a pair of accessory functions, one to get the property value and the other to set it.

In Visual Basic, properties have only one accessory function, which is used to get and set its property value. If the property is read-only, you can get its value but not set it.

For example, to return the ErrorMessage property for the Server object, type

Server.ErrorMessage

pt Property type

qlo Query logical operator

qro Query relational operator

qt Query type

rat Row action type

ro Row operations

rst Row status type

scf Server connect flag

slf Server LoginEx flag

slt Server license type

st Status type

tt Tab or Table type

upid User privilege ID

uvt User value type

wut Where Used type

Table 2-3: Constant prefixes

Prefix Description

2-9


Table 2-4 lists all Agile Advantage API properties.

Table 2-4: Agile Advantage API Properties

Object Class Properties

ActivityQuery FromDate, ItemCount, MissingCount, States, ToDate, Type

Attachment FileCount, IsImage, IsSecure

Attachments IsImage

Attribute BaseID, DataType, FullName, IsVisible, ListElements, Name, TableName

Base ErrorCode, ErrorMessage, IsDirty, IsInit, ObjectID, ObjectType, Parent, Server, Tag

BOMComponent Children

CCBQuery Attributes, ColumnAttribute, ColumnCount, FilterQuery, FromDate, FromState, MissingCount, RowCount, States, TimeInterval, ToDate, ToState, Type

Collection Count, DataType, IsReadOnly

DataObject IsDeleted, IsUpToDate, SubClass

Field Attribute, BaseID, DataType, DiscoveryPrivilege, IsReadOnly, IsRedlined, IsRedlineShown, ListElements, Name

Folder Description, ItemCount, Owner

ListElement ID, IsObsolete, Value

MfrPart Mfr

Node ChildNodes, Name, Properties, Type

ObjectInfo ClassID, Mask, SubClassID, TargetID, TargetType

PrintOption LeftFooter, LeftHeader, MidFooter, MidHeader, RightFooter, RightHeader, ShowRedlines, Watermark

Property DisplayString, ID, IsReadOnly, ListElements, ListID, Name, Type

Query Attributes, CriteriaCount, IsCaseSensitive, Owner, ResultCacheSize, ResultCount, ResultMissingCount, ResultRange, Results, ResultStart

RouteObject StatusID

Row DiscoveryPrivilege, Fields, Referent, RowIndex

Server CurrentUser, FileServerBufferSize, FileServerCacheDir, FileServerHostname, FileServerPassword, FileServerPort, FileServerSchema, Hostname, IsConnected, IsLogin, MfrNames, Port, QueryClasses, SubClasses, Users

SubClass Attributes, AutoNumberSources, ClassID, IsAutoNumberRequired, Name, SubClassID, Tabs, TargetType

2-10 Developer Guide


Methods

A method is an action that an object can perform, such as adding, deleting, or saving an object. Methods can take several parameters, and they can be passed either by value or by reference. For the Agile Advantage API, all method parameters are required. A method may or may not return a value. Generally, when a method returns a value it is either a pointer to an object or a Boolean value to show whether the method succeeded or failed.

Note You can’t assign a value to a method, but you can assign a value to a property.

Table 2-5 lists all Agile Advantage API methods.

SyncOption CompareIDs

Tab Attributes, Type

Table Attributes, IsRedlinable, MissingCount, RowCount, RowRange, Rows, RowStart, RowType, Type

Table 2-5: Agile Advantage API Methods

Object Methods

ActivityQuery Create, Execute, GetItemInfo, GetItemNumber, GetItemRevision, GetTargetStates, GetWorkflowID, SetTargetStates, SetWorkflowID

ApprovedMfr SetMfrPart

ApprovedMfrs AddRow

Attachment AddFile, CancelCheckOut, CheckIn, CheckOut, DeleteVersion, GetCurrentVersion, GetFile, GetFileID, GetPrintOption, GetVersionInfo, GetVersions, PrintFile, SetCurrentVersion, VbsGetVersionInfo

Attachments AddRow

Base CancelBlockingCall, Compact, DisableError, EnableError, GetObjectInfo

BOMComponent Expand

BOMComponents GetEffectivePeriod, SetEffectivePeriod

CCBQuery Create, Execute, GetColumnHeader, GetItemCount, GetItemInfo, GetItemValue, GetRowHeader, GetValue, GetWorkflowID, SetWorkflowID

Table 2-4: Agile Advantage API Properties

Object Class Properties

2-11


Change Create, LoadByAttr, LoadByInfo

Collection Add, Clear, Contains, ContainsKey, Find, FindIndex, Get, Remove, SetDataType

CriteriaBag GetAttributes, GetClass, CriteriaCount, GetCriteriaData, IsCaseSensitive

Customer Create, LoadByAttr, LoadByInfo

DataObject Abort, CheckValidOperation, Delete, GetTable, Refresh, Save, SaveAs, Send, Undelete

Field GetValue, SetNull, SetValue, ShowRedline, UndoRedline

Folder AddItem, Clear, Create, Delete, FindItemIndex, GetItemInfo, GetItemName, GetName, GetSortOrder, GetType, LoadByInfo, OrderItems, Refresh, RemoveItem, SetName, SetSortOrder, SetType

Item Create, GetIncorporated, GetRevision, GetRevisions, LoadByAttr, LoadByInfo, SetIncorporated, SetRevision, SyncAML, SyncBOM, VbsGetRevision

Mfr Create, LoadByAttr, LoadByInfo

MfrPart Create, LoadByAttr, LoadByInfo

Node CreateUser, Delete

Package Create, LoadByAttr, LoadByInfo

Property GetValue, SetListElements, SetValue

Query Abort, AddCriteria, ClearCache, Create, Delete, DeleteCriteria, Execute, GetAttrValues, GetClass, GetCriteriaData, GetLogicalOperators, GetName, GetRelationalOperators, GetResultDisplay, GetType, GetWhereUsedType, LoadByInfo Refresh, Save, SaveAs, SetClass, SetCriteriaData, SetName, SetResultDisplay, SetType, SetWhereUsedType, VbsGetCriteriaData

RouteObject AddApprovers, Approve, Audit, ChangeStatus, Comment, GetApprovers, GetDefaultNextStatusID, GetDefaultNotifyList, GetNextStatusIDs, GetStatusIDs, GetWorkflowID, GetWorkflowIDs, Reject, RemoveApprovers, SetWorkflowID

Row CheckValidOperation, GetFieldDiscPriv, GetReferentInfo, GetStatus, GetValue, LogAction, SetValue


Object Methods



Data TypesThe Agile Advantage API supports Agile-specific data types in addition to standard automation data types. For a list of data type constants supported by the API, see “Data Type Constants” on page 6-333.

The data types specified for function declarations in Chapter 6, “Agile Advantage API Reference,” have C-style names. Table 2-6 lists equivalent data types Visual Basic.

Working with AttributesAn attribute is an inherent characteristic of an object. All Agile Advantage objects have attributes.

Server Connect, DiffAML, Disconnect, GetAttribute, GetFailoverServerList, GetHomeFolderInfo, GetLicenseType, GetListElement, GetListElements, GetNode, GetObject, GetVersion, Login, LoginEx, SetClientTime, SetLicenseKey, TranslateClassID

ServiceRequest Create, LoadByAttr, LoadByInfo

SubClass FindAttributes, GetNextNumber, VbsGetNextNumber

SupplierMethods Create, LoadByAttr, LoadByInfo.

Table AddRow, Refresh, RemoveRow, UnremoveRow

User ChangePassword, CheckPrivilege, GetValue, HasLicense, IsLicensed, ReleaseLicense, SetValue, vbsChangePassword

Table 2-6: Data type equivalents

C++ Data Type Visual Basic Data Type Description

BOOL Boolean Variable that is either true (nonzero) or false (zero)

BSTR String A length-prefixed string

LONG Long 32-bit signed integer

LPCTSTR String A string

LPDISPATCH Object Pointer to an object

VARIANT Variant OLE Variant data


Object Methods

2-13


Agile Advantage objects derive from main object classes, such as Change Orders and Parts. Each object class can have one or more user-defined subclasses. For example, the Parts class can have Capacitor and Resistor subclasses.

When you create or open an object in an Agile Advantage client, such as the Agile Advantage Windows client or an Agile Advantage API program, you create an instance of a subclass object. The object has fields for displaying and entering information. These fields are grouped into tabs. A tab can also contain a table, such as a BOM table. Individual fields on a tab and columns within a table correspond to attributes for the object’s subclass and its parent class.

The applications you create with the Agile Advantage API need to get and set values for attributes.

Referencing Attributes in Code

You can reference Agile Advantage attributes by attribute ID constants, ID number, or fully qualified name. By using constants in your code instead of the actual ID numbers, your code is easier to read and to maintain. Table 2-7 lists the main Agile Advantage classes and their attribute ID constants.

Table 2-7: Attribute ID constants

Class Attribute ID Constants

Change Orders ChangeOrdersAttributeIDs

Change Requests ChangeRequestsAttributeIDs

Customers CustomersAttributeIDs

Deviations DeviationsAttributeIDs

Documentation DocumentationAttributeIDs

Issues IssuesAttributeIDs

Manufacturer Orders ManufacturerOrdersAttributeIDs

Manufacturer Parts ManufacturerPartsAttributeIDs

Manufacturers ManufacturersAttributeIDs

Packages PackagesAttributeIDs

Parts PartsAttributeIDs

Problem Reports ProblemReportsAttributeIDs

Quality Change Requests QualityChangeRequestAttributeIDs

Stop Ships StopShipsAttributeIDs

Suppliers IDSuppliersAttributeIDs



Here is an example showing how to reference an attribute ID constant:

Dim attrID As LongDim vLabel As Variant

attrID = aidParts_TitleBlock_Descriptionb = Item.GetValue(attrID, vLabel)

Here is an example showing how to reference an attribute ID number:

b = Item.GetValue(1002, vLabel)

A fully qualified attribute name is a string with the following format:

TabName.AttributeName

TabName is the name of the tab on which the attribute appears in Agile Administrator. AttributeName is the current value for the Name property of an attribute. All attributes have default names, but the names can be changed. In particular, Page Two and Page Three attributes that have been made visible in your Agile Advantage system are likely to have been assigned more meaningful names than “Text01,” “List01,” and “Date01.”

“Cover Page.Reason for Change” and “Title Block.Number” are two examples of fully qualified attribute names.

In general, avoid referencing attributes by name for the following reasons:

❑ Attribute names can be modified in Agile Administrator.❑ Attribute names are localized; that is, the names are different for different

languages.

Here is an example of a reference to a fully qualified attribute name:

b = Item.GetValue("Title Block.Description", vLabel)

Note Attribute names are case-sensitive.

Tabs and Tables for Agile Advantage Classes

Each Agile Advantage class has both a Tabs node and a Tables node where its characteristics are defined. In addition, each subclass has a tabs node where its Page Three characteristics are defined. The following table shows the tab and table nodes for each Agile Advantage class and subclass. Each tab and table has a specific set of attributes.

2-15


Table 2-8: Agile classes and associated Tabs/Tables

Agile Class Agile-Supplied Subclass Class ID Subclass ID Tabs

Tables

Change Orders class ECO 6000 6141 Cover PagePage Two (for each class)Affected Items

Affected Items tableRelated Items table (for CAR)

Related QCR (for ECO)PSR and Changes (for CAR)

Related PSR tableRelated Changes table

SignoffSignoff table

AttachmentsAttachments table

HistoryHistory table

Page Three (for each subclass)

Change Requests class

ECR 7000 7141

Deviations class Deviation 8000 8141

Manufacturer Orders class

MCO 1450 1455

Quality Change Requests class

CAR 4928 4933

Stop Ships class Stop Ship 11000 11141

Parts class Part 10000 10141 Title BlockPage Two (for each class)Changes

Pending Changes tableChange History table

BOMBOM Edit tableBOM Tree table

Where UsedWhere Used table

ManufacturersManufacturers table

AttachmentsAttachments table

HistoryHistory table

QualityQuality table

Page Three (for each subclass)

Documentation class Document 9000 9141

Manufacturer Parts class

Manufacturer Part 1483 1448 General InfoPage Two (for each class)Where Used

Where Used tableAttachments

Attachments tableHistory

History tablePage Three (for each subclass)

Manufacturers class Manufacturer 1442 1447



Attribute IDs Shared Between Multiple Classes

The Agile Advantage API attribute ID constants assign unique names to the attribute IDs for each Agile Advantage class. However, the attribute ID numbers may be shared between multiple classes. For example, Attachments tab attribute IDs are the same for all classes. Keep this in mind when you reference attribute ID constants in your code. For example, when referencing Attachments tab attribute constants, you do not need to write code to handle each object class.

Package class Package 3122 3127 Cover PagePage Two (for each class)Affected ItemsSignoff

Signoff tableAttachments



Customers class Customer 4983 4988 General InfoPage Two (for each class)Related PSR

Related PSR tableAttachments



Suppliers class Broker,Component Manufacturer,Contract Manufacturer,Distributor,Manufacturer Representative

40634063

4063

40634063

40684083

4084

40854086

General InfoPage Two (for each class)Supplier Part

Supplier Part tableAttachments



Issues class Issue 4895 4900 Cover PagePage Two (for each class)Related PSR (for Issue)

Related PSR tableSignoff

Signoff tableAttachments



Problem Reports class Problem Report 4878 4883

Table 2-8: Agile classes and associated Tabs/Tables

Agile Class Agile-Supplied Subclass Class ID Subclass ID Tabs

Tables

2-17


Table 2-9 lists each Agile Advantage tab and the classes that share all attribute IDs for that tab.

Memory ManagementThe Agile Advantage API has a built-in memory management scheme that determines when an object is automatically released from memory. This frees up memory for additional Agile Advantage API objects and other applications.

As soon as an object is no longer referenced by an object variable at run time, the Agile Advantage API automatically releases it from memory. Like a chain reaction,

Table 2-9: Tabs that share attribute IDs between classes

Tab Classes that share attribute IDs

Affected Items Change Orders, Change Requests, Deviations, Manufacturer Orders, Quality Change Requests, and Stop Ships

Attachments All subclasses

BOM Documentation and Parts

Change History Documentation and Parts

Cover Page None

General Info None

History None

Manufacturers Documentation and Parts

Page Two None

Page Three All subclasses that have a Page Three

Pending Changes Documentation and Parts

PSR and Changes (Related PSR and Related Changes tables)

Change Orders, Change Requests, Deviations, Manufacturer Orders, Quality Change Requests, and Stop Ships

Related PSR Problem Reports and Issues

Related QCR None

Signoff Change Orders, Change Requests, Deviations, Manufacturer Orders, Packages, and Stop Ships

Supplier Broker, Distributor, Contract Manufacturer, Component Manufacturer and Manufacturer Representative

Title Block Documentation and Parts

Where Used Documentation and Parts



the Agile Advantage API also proceeds to release all objects that the parent object contains.

For example, when an Item object is set to nothing, the Agile Advantage API releases

❑ The Item❑ Tables of the Item❑ Rows contained within the tables❑ Properties of the individual rows

If a user still holds a child object (such as a Row) after the parent object has been unloaded, the Agile Advantage API returns Error Code 316, “Object unloaded from memory.”

To prevent users from encountering errors due to unloaded objects, you should always set an object variable in your code equal to the actual instance of the Agile Advantage API object. For example, itemObj is an object variable for an Agile Advantage Item in the following Visual Basic code snippet:

Public itemObj As AgileAPI.ItemSet itemObj = CreateObject("AgileAPI.Item")b = itemObj.LoadByAttr(Server, 0, "P00001")

When your program is finished with an object, set the object variable to nothing to release it from memory, as shown in the following Visual Basic code:

Set itemObj = Nothing

Single-Threaded versus Multithreaded ApplicationsThe Agile Advantage APIs have been certified for both single-threaded and multithreaded application development. This means that all classes have been certified for thread safety. You do not need to write complex thread synchronization code in your program to handle Agile Advantage API threads. The Agile Advantage API automatically takes care of this for you.

Because the Agile Advantage API is thread-safe, it is appropriate for use in developing both local client-side programs as well as network-based applications. Multithreading support also makes it possible for you to develop ASP (Active Server Pages) applications that run off a Web server.

VBScript SupportVBScript, a Web scripting language from Microsoft, offers a subset of Visual Basic functionality. It is commonly used to provide server-side processing in Active Server Pages (ASPs), another Microsoft technology.

2-19


The Agile Advantage API methods shown in the first column in Table 2-10 have output parameters of String and Long data type that return data from an Agile Advantage eHub. With VBScript, all variables must be declared as Variant type. Consequently, you cannot use these Agile Advantage API methods in VBScript. If you are writing VBScript, make sure you use the VBScript-supported versions of these methods. Otherwise, your script may not work.

Creating and Modifying Agile Advantage UsersThe Agile Advantage API provides a special login method, Server::LoginEx, that lets you create and modify Agile Advantage users. Server::LoginEx is equivalent to logging in to Agile Administrator. By using this special login, you have read/write access to all User node properties.

In addition to Server::LoginEx, Table 2-11 lists several Agile Advantage API methods you can use to create and modify Agile Advantage users.

Table 2-10: VBScript-supported methods

Visual Basic-Supported Method VBScript-Supported Method

Attachment::GetVersionInfo Attachment::VbsGetVersionInfo

Item::GetRevision Item::VbsGetRevision

Query::GetCriteriaData Query::VbsGetCriteriaData

SubClass::GetNextNumber SubClass::VbsGetNextNumber

User::ChangePassword User::VbsChangePassword

Table 2-11: Methods for creating and modifying Agile Advantage users

Method Description

Server::LoginEx Performs a special login to the Agile eHub, providing read/write access to the Users node. Only one user at a time can be logged in using Server::LoginEx with the slfAdministrator flag. To use Server::LoginEx, you must have Administrator privileges to the Agile Advantage system.

Server::GetNode Retrieves a Node object. To retrieve the Users node, specify nidUsers for the Node ID.

Node::CreateUser Creates a new Agile Advantage user.

Node::DeleteUser Deletes an Agile Advantage user.

Property::GetValue Retrieves a property value.

Property::SetValue Sets a property value.



User::ChangePassword Changes the user’s login and approval passwords. If you use Node::CreateUser to create a new user, the user’s initial passwords are blank until you use User::ChangePassword to change them.

Table 2-11: Methods for creating and modifying Agile Advantage users

Method Description

2-21


Mapping Agile Advantage Client Features to the Agile Advantage APIThis section provides tables that show how features in Agile Advantage clients map to equivalent APIs. The Agile Advantage API exposes functionality available in the Agile Advantage Windows and Web clients.

Login Features

Table 2-12 lists general features for logging in to the Agile Advantage eHub.

Note:1 Server::LoginEx performs a special Agile Administrator login that lets you create, modify, and delete

Agile Advantage users. Only one user at a time can log in to an Agile Advantage eHub for an Agile Administrator session using Server::LoginEx.

Items

Tables 2-13 through 2-17 list features for creating an Item and getting and changing its field values.

Table 2-12: General Agile Advantage Windows Client features

Feature Equivalent API(s)

Connect and log in to the Agile Advantage eHub

Server::Connect

Server::Login or Server::LoginEx1

Disconnect from the Agile Advantage eHub

Server::Disconnect

Connect and log in to the Agile Advantage eHub

Server::ConnectAdvExServer::LoginAdvExServer::ConnectServer::Login or Server::LoginEx1

Table 2-13: Item features


Get an Item field value Row::GetValue

Set an Item field value Row::SetValue

Get a list of Pending Changes for an Item

DataObject::GetTable(ttItemPendingChanges)

Get the Change History list for an Item

DataObject::GetTable(ttItemChangeHistory)



Get a single- or multilevel BOM by a particular revision

Item::SetRevisionDataObject::GetTable(ttItemBOM)Table::Rows::GetBOMComponent::Expand

Get a single- or multilevel BOM by a specific effectivity date

DataObject::GetTable(ttItemEffectiveBOM)BOMComponents::SetEffectivePeriod

Get the Approved Manufacturers List (AML) for an Item

DataObject::GetTable(ttItemAML)

Get the Where Used list for an Item

DataObject::GetTable(ttItemWhereUsed)

Get the History list for an Item

DataObject::GetTable(ttItemHistory)

Get attached files for an Item DataObject::GetTable(ttItemFiles)

Table 2-14: Item Manufacturer features


Add a Manufacturer Part to an Item

ApprovedMfrs::AddRow

Remove a Manufacturer Part from an Item

Table::RemoveRow

Update the Manufacturer Part for an Item

ApprovedMfr::SetMfrPart

Table 2-15: Item BOM features


Add an Item to the BOM table of a Preliminary Item

Table::AddRow

Remove an Item from the BOM table of a Preliminary Item

Table::RemoveRow

Update an Item on the BOM table of a Preliminary Item

Row::SetValue

Table 2-13: Item features


2-23


Changes

Tables 2-18 through 2-21 list features for finding, creating, and updating a Change. A Change can be a CAR, ECO, ECR, Deviation, MCO, Stop Ship, or another user-defined subclass of the Change class.

Table 2-16: Item workflow features


Send an Item DataObject::Send

Table 2-17: General Item features


Create a new Item Item::Create

Load an existing Item Item::LoadByAttr and Item::LoadByInfo

Save an Item object into another Item object

DataObject::SaveAs

Incorporate or unincorporate an Item, thereby locking or unlocking its attachments

Item::SetIncorporated

Table 2-18: Change features


Get a Change field value Row::GetValue

Set a Change field value Row::SetValue

Get Affected Items values DataObject::GetTable(ttChangeAffectedItems)

Get Redlined Manufacturers for an Affected Item

Item::SetRevisionDataObject::GetTable(ttItemRedlineBOM)

Get the History list for a Change

DataObject::GetTable(ttChangeHistory)

Get the Signoff list for a Change

DataObject::GetTable(ttChangeSignoff)

Get attached files for a Change

DataObject::GetTable(ttChangeFiles)

Get the Related PSR table for a Change

DataObject::GetTable(ttChangeRelatedPSR)

Get the Related Items table for a Quality Change Request

DataObject::GetTable(ttChangeRelatedItems)



Notes:1 Without a Product Change Server license, the user cannot specify notification and comment

parameters.

Get the Related Changes table for a Quality Change Request

DataObject::GetTable(ttChangeRelatedChanges)

Table 2-19: Affected Items features


Add an Affected Item Table::AddRow

Update an Affected Item field value

Row::SetValue

Remove an Affected Item Table::RemoveRow

Redline a BOM Item::SetRevision DataObject::GetTable(ttItemRedlineBOM) Row::SetValue

Redline a Manufacturer Item::SetRevisionDataObject::GetTable(ttItemRedlineAML)Row::SetValue

Table 2-20: Change workflow features


Audit a Change RouteObject::Audit

Change the status of a Change RouteObject::ChangeStatus1

Send a Change DataObject::Send

Approve a Change RouteObject::Approve

Reject a Change RouteObject::Reject

Comment on a Change RouteObject::Comment

Add or remove approvers for a Change

RouteObject::AddApproversRouteObject::RemoveApprovers

Table 2-21: General Change features


Create a new Change Change::Create

Table 2-18: Change features


2-25


Manufacturer Parts

Tables 2-22 through 2-24 list features for finding, creating, and updating a Manufacturer Part.

Load an existing Change Change::LoadByAttrChange::LoadByInfo

Save a Change object into another Change object

DataObject::SaveAs

Delete a Change DataObject::Delete

Undelete a Change DataObject::Undelete

Table 2-22: Manufacturer Part features


Get a Manufacturer Part field value

Row::GetValue

Set a Manufacturer Part field value

Row::SetValue

Get the Where Used list for a Manufacturer Part

DataObject::GetTable(ttMfrPartWhereUsed)

Get the History list for a Manufacturer Part

DataObject::GetTable(ttMfrPartHistory)

Get attached files for a Manufacturer Part

DataObject::GetTable(ttMfrPartFiles)

Table 2-23: Manufacturer Part workflow features


Send a Manufacturer Part DataObject::Send

Table 2-24: General Manufacturer Parts features


Create a new Manufacturer Part

MfrPart::Create

Load an existing Manufacturer Part

MfrPart::LoadByAttrMfrPart::LoadByInfo

Table 2-21: General Change features




Save a Manufacturer Part object into another Manufacturer Part object

DataObject::SaveAs

Delete a Manufacturer Part DataObject::Delete

Undelete a Manufacturer Part

DataObject::Undelete

Table 2-24: General Manufacturer Parts features


2-27


Manufacturers

Tables 2-25 through 2-27 list features for finding, creating, and updating a Manufacturer.

Table 2-25: Manufacturer features


Get a Manufacturer field value

Row::GetValue

Set a Manufacturer field value

Row::SetValue

Get the Where Used list for a Manufacturer

DataObject::GetTable(ttMfrWhereUsed)

Get the History list for a Manufacturer

DataObject::GetTable(ttMfrHistory)

Get attached files for a Manufacturer

DataObject::GetTable(ttMfrFiles)

Table 2-26: Manufacturer workflow feature


Send a Manufacturer DataObject::Send

Table 2-27: General Manufacturer features


Create a new Manufacturer Mfr::Create

Load an existing Manufacturer

Mfr::LoadByAttrMfr::LoadByInfo

Save a Manufacturer object into another Manufacturer object

DataObject::SaveAs

Delete a Manufacturer DataObject::Delete

Undelete a Manufacturer DataObject::Undelete



Packages

Tables 2-28 through 2-30 list features for finding, creating, and updating a Package.Table 2-28: Package features


Get a Package field value Row::GetValue

Set a Package field value Row::SetValue

Get the History list for a Package

DataObject::GetTable(ttPackageHistory)

Get the Signoff list for a Package

DataObject::GetTable(ttPackageSignoff)

Get attached files for a Package

DataObject::GetTable(ttPackageFiles)

Table 2-29: Package workflow features


Submit a Package RouteObject::ChangeStatus

Route a Package RouteObject::ChangeStatus

Release a Package RouteObject::ChangeStatus

Return a Package to the originator

RouteObject::ChangeStatus

Cancel a Package RouteObject::ChangeStatus

Hold a Package RouteObject::ChangeStatus

Send a Package DataObject::Send

Approve a Package RouteObject::Approve

Reject a Package RouteObject::Reject

Comment on a Package RouteObject::Comment

Add or remove approvers for a Package


Table 2-30: General Package features


Create a new Package Package::Create

Load an existing Package Package::LoadByAttrPackage::LoadByInfo

2-29


Attachments

Table 2-31 lists features for working with attachments. Attachments are files or images included with an Item, Change, Manufacturer, Manufacturer Part, or Package.

Note:1 Requires Agile Advantage Package license if the data object is a Package.

Folders

Table 2-32 lists features for working with folders.

Save a Package object into another Package object

DataObject::SaveAs

Delete a Package DataObject::Delete

Undelete a Package DataObject::Undelete

Table 2-31: Attachment features


Get a file and copy it to a specific location

Attachment::GetFile

Add a file to a multifile attachment Attachment::AddFile1

Check out a file Attachment::CheckOut1

Check in a file Attachment::CheckIn1

Cancel checkout for a file Attachment::CancelCheckOut1

Get the header/footer settings for an attachment

Attachment::GetPrintOption

Print an attachment Attachment::PrintFile

Delete an attachment Table::RemoveRow1

Table 2-32: Folder features


Create a new folder Folder::Create

Load an existing folder Folder::LoadByInfo

Add an item (such as a Query) to the folder Folder::AddItem

Table 2-30: General Package features




Queries (Searches)

Table 2-33 lists features for working with queries.

Set the type of folder (public or private) Folder::SetType

Set the folder name Folder::SetName

Set the folder sort order Folder::SetSortOrder

Remove an item from the folder Folder::RemoveItem

Clear all objects from the folder Folder::Clear

Delete a folder Folder::Delete

Table 2-33: Query features


Create a new query Query::Create

Load an existing query Query::LoadByInfo

Set the name and class of a query Query::SetNameQuery::SetClass

Set the type of a query Query::SetType

Create a Where Used query Query::SetWhereUsedType

Add, delete, get, and set criteria data for a query Query::AddCriteriaQuery::DeleteCriteriaQuery::GetCriteriaDataQuery::SetCriteriaData

Run a query Query::Execute

Make a query case-sensitive Query::IsCaseSensitive

Set the query result range (to return partial results) Query::ResultStartQuery::ResultRange

Abort a modification of a query Query::Abort

Delete a query Query::Delete

Save a query Query::SaveQuery::SaveAs

Table 2-32: Folder features


2-31


Customers

Table 2-34 lists features for working with customers.

Problem Reports and Issues

Table 2-35 lists features for working with problem reports.

Quality Change Requests

Table 2-33 lists features for working with CARS and other Quality Change Requests (QCRs).

Table 2-34: Customer features


Create a new customer Customer::Create

Load an existing customer Customer::LoadByAttrCustomer::LoadByInfo

Save a customer as a different customer or as a different customer site

DataObject::SaveAs

Table 2-35: Problem report features


Create a new problem report or issue

ServiceRequest::Create

Load an existing problem report or issue

ServiceRequest::LoadByAttrServiceRequest::LoadByInfo

Assign a problem report or issue

Row::SetValue

Change the status of a problem report or issue


Approve a problem report or issue

RouteObject::Approve

Reject a problem report or issue

RouteObject::Reject

Audit a problem report or issue

RouteObject::Audit

Table 2-36: Quality Change Request features


Create a new CAR Change::Create



Agile Administrator Features

Table 2-37 lists features for working with nodes, properties, and users in Agile Administrator.

Note The Agile Advantage API provides read-only access to most Agile Administrator properties. If you log in to the Agile Advantage system using Server::LoginEx and specify the slfAdministrator login flag, you can create and modify Agile Advantage users and classes.

Load an existing CAR Change::LoadByAttrChange::LoadByInfo

Assign a CAR Row::SetValue

Change the status of a CAR RouteObject::ChangeStatus

Approve a CAR RouteObject::Approve

Reject a CAR RouteObject::Reject

Audit a CAR RouteObject::Audit

Table 2-37: Agile Administrator features


Get an Agile Administrator node Server::GetNode

Get all subnodes (children) of a node Node::ChildNodes

Get all properties of a node Node::Properties

Get the value for an Agile Administrator property Property::GetValue

Get the possible values for a list field Property::ListElements

Get all subclasses Server::SubClasses

Get the list of subclasses for a specific object type Server::SubClasses Collection::GetSubClass::TargetType

Get the AutoNumber sources for a subclass SubClass::AutoNumberSources

Get the collection of tabs for a subclass SubClass::Tabs

Get the collection of attributes for a table Table::Attributes

Get the collection of attributes for Page One, Two, or Three of a given subclass

SubClass::FindAttributes

Get the list of Agile Advantage users Server::Users

Table 2-36: Quality Change Request features


2-33


Suppliers

Tables 2-38 through 2-40 list features for finding, creating, and updating a Supplier.

Create a user Node::CreateUser

Set a user’s properties Property::SetValue

Change user passwords User::ChangePassword

Delete a user Node::Delete

Table 2-38: Supplier features


Get a Supplier field value Row::GetValue

Set a Supplier field value Row::SetValue

Get the Price List for a Supplier

DataObject::GetTable(ttSupplierMfrParts)

Get the History list for a Supplier

DataObject::GetTable(ttSupplierHistory)

Get attached files for a Supplier

DataObject::GetTable(ttSupplierFiles)

Table 2-39: Supplier workflow feature


Send a Supplier DataObject::Send

Table 2-40: General Supplier features


Create a new Supplier Supplier::Create

Load an existing Supplier Supplier::LoadByAttrSupplier::LoadByInfo

Save a Supplier object into another Supplier object

DataObject::SaveAs

Delete a Supplier DataObject::Delete

Undelete a Supplier DataObject::Undelete

Table 2-37: Agile Administrator features




Packaging Your Agile Advantage API ApplicationAfter you develop an application that makes calls to the Agile Advantage API, you need to package its files so that users can install it or access it over the Internet. Many development environments include tools for packaging and deploying applications. For example, Microsoft Visual Studio includes a Package and Deployment Wizard.

You can also choose to package your application manually. If you choose to do this, you need to know the dependencies your project has. Again, many development environments include tools for generating dependency files. A dependency file lists the runtime components that must be distributed with your application’s project files.

Agile Advantage ADK Files You Are Allowed to Distribute

You can freely distribute any application executables or component executables that you create that make calls to the Agile Advantage ADK COM API. You also need to include the files listed in Table 2-41 when you package your application’s files. These files are located in the ADK\COM\AgileAPI folder.

Note:1 These files are also installed automatically when you install other Agile Advantage client

components, such as the Agile Advantage Windows Client. If users of your application already have the Agile Advantage Windows Client installed, you do not need to redistribute these files with your application.

Table 2-41: Agile Advantage ADK distributable files

File Description

AgileAPI.dll1 Agile API in-process server

AgileAPI75.dll1 Agile API dynamic link library for Agile Anywhere 7.5

AgileAPI80.dll1 Agile API dynamic link library for Agile 8.0

AgileAPI85.dll1 Agile API dynamic link library for Agile 8.5

AgileAPI90.dll1 Agile API dynamic link library for Agile Advantage 2006

APMsg32.dll1 Agile client error message library

eHubmsg.dll1 Agile eHub message library for Agile Advantage

MSVCRT.DLL Microsoft Visual C++ Runtime library

mfc42.dll Microsoft Foundation Class library

2-35


Your development environment might require you to distribute other runtime files with your application. For example, Visual Basic 6.0 applications require a DLL called MSVBVM60.dll. Check the documentation for your development environment to see which runtime files should be distributed with your application. In addition, your application might require other files, such as other DLLs, ActiveX controls (OCX files), or bitmaps (BMP files). Consult the manufacturer’s license agreement for each of the files you plan to distribute to determine whether you have the right to distribute the file with your application.

Agile Advantage ADK Files You Are Not Allowed to Distribute

Agile Advantage requires that any company or individual writing code to the Agile Advantage API must obtain an Agile Advantage ADK license. The Agile Advantage ADK license grants the right to use the Agile Advantage API in a design environment and to freely distribute the Agile Advantage API with any application that makes calls to the API.

The Agile Advantage ADK license explicitly prohibits distribution of the following files to any other party that has not legally obtained an Agile Advantage ADK license:

❑ Agile Advantage API documentation❑ Sample code provided with the Agile Advantage ADK❑ Source code

For more information, consult the Agile Advantage license.


CHAPTER 3Upgrading Programs to

Agile Advantage ADK 2006

Upgrading Programs from Agile 8.5 SDKPrograms created using Agile 8.5 APIs will run without modification with the Agile Advantage 2006 system without recompiling. Make sure you deploy the appropriate DLL files with your program. There are no known upgrade issues.

Changes Made to Agile Advantage 2006 APIsThis section lists interface changes to the Agile Advantage 2006 APIs since Agile 8.5.

New Classes

Agile Advantage 2006 includes the following new classes:

❑ Supplier

This chapter provides information about how to upgrade a program created with Agile 8.5 SDK so that it works with Agile Advantage 2006 ADK. It contains the following topics:❑ Upgrading Programs from Agile 8.5 SDK❑ Changes Made to Agile Advantage 2006 APIs❑ Changes Made to Agile 8.5 APIs

3-1


New Methods

Table 3-3 lists new methods for Agile Advantage 2006 APIs:

New Constants

Table 3-4 lists new constants that have been added for Agile Advantage 2006 APIs. These constants are in addition to the constants contained in the new interfaces listed above.

Constants for all Page Three attributes have also been added to the following enumerated constants:

❑ SuppliersAttributeIDConstants

Changes Made to Agile 8.5 APIsThis section lists interface changes to the Agile 8.5 APIs since Agile 8.0.

Agile 8.5 Classes

Agile API 8.5 includes the following new classes:

❑ Customer

❑ ServiceRequest

Table 3-1: New Agile Advantage API methods

Class Methods

Supplier Create, LoadByAttr, LoadByInfo

Server LoginAdv

Table 3-2: New Agile Advantage API constants

Enumerated Constants Group Constants Added

ClassTypeConstants ctSupplierSupplier

SuppliersAttributeIDConstants all

TableTypeConstants ttMfrPartSupplier

ttSupplierPage1

ttSupplierPage2

ttSupplierPage3

ttSupplierFiles

ttSupplierMfrParts

ttSupplierHistory

3-2 Developer Guide

Chapter 3 Upgrading Programs to Agile Advantage ADK 2006

Agile 8.5 Methods

Table 3-3 lists new methods for Agile API 8.5:

Agile 8.5 Constants

Table 3-4 lists new constants that have been added for Agile API 8.5. These constants are in addition to the constants contained in the new interfaces listed above.

Table 3-3: New Agile API methods

Class Methods

Customer Create, LoadByAttr, LoadByInfo

ServiceRequest Create, LoadByAttr, LoadByInfo

User VbsChangePassword

Table 3-4: New Agile API constants


ClassTypeConstants ctChangeQCR, ctCustomerCustomer, ctServiceRequest, ctServiceRequestIssue,ctServiceRequestProblemReport

CustomersAttributeIDConstants all

IssuesAttributeIDConstants all

ProblemReportsAttributeIDConstants all

QualityChangeRequestAttributeIDConstants all

TableTypeConstants ttChangeRelatedChanges, ttChangeRelatedItems, ttChangeRelatedPSR, ttChangeRelatedQCR, ttCustomerFiles, ttCustomerHistory, ttCustomerPage1, ttCustomerPage2, ttCustomerPage3, ttCustomerRelatedPSR, ttItemQuality, ttServiceRequestFiles, ttServiceRequestHistory, ttServiceRequestPage1, ttServiceRequestPage2, ttServiceRequestPage3, ttServiceRequestRelatedPSR, ttServiceRequestSignoff

3-3


Constants for all Page Three attributes have also been added to the following enumerated constants:

❑ ChangeOrdersAttributeIDConstants

❑ ChangeRequestsAttributeIDConstants❑ DeviationsAttributeIDConstants

❑ DocumentationAttributeIDConstants

❑ ManufacturerOrdersAttributeIDConstants

❑ ManufacturersAttributeIDConstants

❑ PackagesAttributeIDConstants

❑ PartsAttributeIDConstants

❑ StopShipsAttributeIDConstants

TabTypeConstants ttQuality, ttRelatedPSR, ttRelatedPSRandChanges

UserPrivIDConstants pidAddApprover, pidChangeStatus, pidCreatePDX, pidEnforceFieldLevelRead, pidFullSearchDisplay, pidModifyDelRedline, pidOverride, pidRemoveApprover, pidSSLServerMonitor, pidTransferAuthForSelf, pidTransferAuthForOthers, pidUserAdministrator

Table 3-4: New Agile API constants


3-4 Developer Guide

CHAPTER 4Tutorials

Creating an Application Using Visual BasicThis tutorial shows how to create a very simple Visual Basic application that uses the Agile API. The application displays the description of an Item based on the specified Item Number. To complete this tutorial, you need Visual Basic 6.

Finished versions of the files created in this tutorial are available in the following folder:

Program Files\Agile Advantage\ADK\COM\Samples\Tutorials\GetDesc\VB

This chapter provides tutorials on how to create applications that use the Agile API. It contains the following topics:❑ Creating an Application Using Visual Basic❑ Creating a Query❑ Displaying SmartRules Settings❑ Synchronizing the BOMs of Two Items❑ Redlining a BOM❑ Creating an ASP Application Using Visual InterDev

4-1


Part I: Setting Up the Project

This section shows how to create a new project and set a reference to the Agile API object library.

1 Start Visual Basic. The New Project dialog box appears.

2 Select Standard EXE, then click Open. A Project window with a blank form appears.

3 Choose Project | References. The References dialog box appears.

Figure 4-1: References dialog box

4 In the Available References list, make sure that Agile API is listed. If it’s not, click Browse to add it to the list. Navigate to the \Program Files\Agile Advantage 2006\ADK\COM\AgileAPI folder and select AgileAPI.dll.

5 Make sure Agile API is checked in the References dialog box, then click OK.

6 Choose File | Save Project.

• Save the form as GetDesc.frm.• Save the project as GetDesc.vbp.

4-2 Developer Guide

Chapter 4 Tutorials

Part II: Using the Object Browser

This section shows how to use the Visual Basic Object Browser, which lets you locate and manage objects in your application. It also shows how to browse the Agile object hierarchy and use the Agile API help system. For more complete information about the Object Browser, refer to the Visual Basic documentation.

1 Choose View | Object Browser. The Object Browser window appears.

2 In the Project/Library list, select AgileAPI.

Figure 4-2: Object Browser

4-3


3 The bottom pane of the Object Browser displays help on the currently selected object, showing a description of the object and its format. For more extensive help on the object, click the button. For example, click the Server object in the left pane of the Object Browser, then select the Login method in the right pane. Click the button to display online help.

Figure 4-3: Agile API Help window

4 To become familiar with the Agile object hierarchy, traverse through several Agile objects and their methods and properties.

5 Close the Object Browser and Agile API Help.

Part III: Creating the User Interface

This section shows how to add controls to the form using the Toolbox and the Object view.

1 Click the Label control in the Toolbox window, then draw a label at the top left of the form.

2 Click the TextBox control in the Toolbox window, then draw a text box below the first label you created.

3 Click the Label control in the Toolbox window, then draw another label below the first label and text box you created.

4-4 Developer Guide

Chapter 4 Tutorials

4 Click the TextBox control in the Toolbox window, then draw another text box below the second label.

5 Click the CommandButton control in the Toolbox window, then draw a command button to the right of the first label and text box.

The form should now look like Figure 4-4:

Figure 4-4: Form with initial design


Part IV: Setting Properties

Set the properties for the form as specified in Table 4-1.

Table 4-1: Form properties

Control Property Name Property Value

Command Button Name cmdDisplay

Command Button Caption &Display

Form Name frmGetDesc

Form Caption Get Description

Label #1 Name lblNumber

Label #1 Caption Item Number

Label #2 Name lblDesc

Label #2 Caption Item Description

Text Box #1 Name txtNumber

Text Box #1 Text (blank — clear the default value)

Text Box #2 Name txtDesc

Text Box #2 BackColor Menu Bar (gray)

Text Box #2 Locked True

4-5


After you set the form’s properties, it should look like the following figure:

Figure 4-5: Form with Finished Design

Part V: Entering the Code

This section shows how to write the code that implements the design you created earlier.

1 Double-click the form to enter code for the Form_Load event procedure, which runs when the form is loaded. Enter the following code:

01: Public Server As AgileAPI.Server02:03: Private Sub Form_Load()04: Set Server = CreateObject("AgileAPI.Server")05: Server.SetLicenseKey("AgileAPILicenseKey")06: b = Server.Connect("localhost", 9013, scfAll)07: b = Server.Login("username", "password", "c:\temp", 16384)08: End Sub

Analysis of the code:

• Line 1: Declares a public Server variable, which is of the type AgileAPI.Server. This is an example of an object reference that uses early binding. By fully declaring the AgileAPI.Server object, you enable the project to use Visual Basic’s IntelliSense features and context-sensitive help for the Agile API. With early bound object variables, Visual Basic detects the object’s properties and methods at design time.

Text Box #2 Text (blank — clear the default value)

Table 4-1: Form properties (continued)


4-6 Developer Guide

Chapter 4 Tutorials

Note Alternatively, you could use late binding and declare the object variable of type Object. With late binding, Visual Basic detects the object’s properties and methods at run time, which can adversely affect your application’s performance. Avoid using late binding except in those cases where it’s necessary, for example, when the object type of a variable cannot be known at design time.

• Lines 3 and 9: These are the wrapper lines for the Form_Load event procedure.

• Line 4: Creates an instance of the Agile Server object.• Line 5: Sets the license key for the Server instance, enabling the

application to use Agile API functionality. Replace AgileAPILicenseKey with a valid key. See “Server::SetLicenseKey()” on page 6-226.

• Line 6: Connects to the Agile eHub installed on the local computer using the default port.

• Line 7: Logs in to the Agile eHub. Replace username and password with a valid Agile username and password. The last four parameters specify Agile iFS (file server) information.

2 Now you need to implement the Display button. Click in the Project Explorer window to return to the Form.

3 Double-click the Display button.

4 On the second line of the Code view, declare a public variable for the Item:

Public Item As AgileAPI.Item

5 Write the following code for the cmdDisplay_Click event procedure:

01: Private Sub cmdDisplay_Click()02:03: Dim desc As Variant04: Dim b As Boolean05: Dim attrID As Long06: 07: attrID = aidParts_TitleBlock_Description08: Set Item = CreateObject("AgileAPI.Item")09: b = Item.LoadByAttr(Server, 0, txtNumber.Text)10: b = Item.GetValue(attrID, desc)11: txtDesc.Text = desc12:13: End Sub

4-7



• Lines 1 and 13: These are the wrapper lines for the cmdDisplay_Click event procedure.

• Line 3: Declares a variable desc to hold the Item Description. The variable is a Variant type.

• Line 4: Declares a variable b as a Boolean type.• Line 5: Declares a variable attrID as a Long type.• Line 7: Sets attrID equal to the constant for "Title Block.Description."• Line 8: Creates a new instance of the Item object.• Line 9: Gets the Item with the specified Item Number. The second

parameter of the LoadByAttr method is 0, which specifies the default attribute. The default attribute for Item is Item Number.

• Line 10: Gets the value of the “Title Block.Description” attribute and sets the desc variable to hold the value. The GetValue method returns a Boolean value.

• Line 11: Displays the Item Description in the txtDesc text box.

The complete code for the application looks like this:

01: Public Server As AgileAPI.Server02: Public Item As AgileAPI.Item03:

04: Private Sub cmdDisplay_Click()05:06: Dim desc As Variant07: Dim b As Boolean08: Dim attrID As Long08: 10: attrID = aidParts_TitleBlock_Description11: Set Item = CreateObject("AgileAPI.Item")12: b = Item.LoadByAttr(Server, 0, txtNumber.Text)13: b = Item.GetValue(attrID, desc)14: txtDesc.Text = desc15:16: End Sub17: 18: Private Sub Form_Load()19: Set Server = CreateObject("AgileAPI.Server")20: Server.SetLicenseKey("AgileAPILicenseKey")21: b = Server.Connect("localhost", 9013, scfAll)22: b = Server.Login("username", "password", "c:\temp", 16384)23: End Sub


4-8 Developer Guide

Chapter 4 Tutorials

7 Press F5 to run the application.

8 Type a valid number in the Item Number field, then click Display. The description of the item appears in the Item Description field.

9 Type an invalid number (such as xxxx) in the Item Number field, then click Display. A Visual Basic error appears. You can trap such errors by entering a few lines of error handling code.

Part VI: Handling Errors

This section shows how to add error handling code to the application. By adding these lines of code, the application displays an error message if an Agile API method fails.

1 If the Get Description application is still running, close it.

2 Click in the Project window to switch to the Code view.

3 Place the cursor below the following line of code:

b = Item.LoadByAttr(Server, 0, txtNumber.Text)

4 Enter the following lines of code:

If b = False Then MsgBox "Failed to get item. " + Item.ErrorMessage Exit SubEnd If


b = Item.GetValue(attrID, desc)


If b = False Then MsgBox "Failed to get value. " + Item.ErrorMessage Exit SubEnd If


b = Server.Connect("localhost", 9013, scfAll)


If b = False Then MsgBox "Failed to connect. " + Server.ErrorMessage Exit SubEnd If

9 Place the cursor below the following lines of code:

4-9


b = Server.Login("username", "password", "c:\temp", 16384)


If b = False Then MsgBox "Failed to login. " + Server.ErrorMessageEnd If


01: Public Server As AgileAPI.Server02: Public Item As AgileAPI.Item03: 04: Private Sub cmdDisplay_Click()05:06: Dim desc As Variant07: Dim b As Boolean08: Dim attrID As Long09: 10: attrID = aidParts_TitleBlock_Description11: Set Item = CreateObject("AgileAPI.Item")12: b = Item.LoadByAttr(Server, 0, txtNumber.Text)13: If b = False Then14: MsgBox "Failed to get item. " + Item.ErrorMessage15: Exit Sub16: End If17: b = Item.GetValue(attrID, desc)18: If b = False Then19: MsgBox "Failed to get value. " + Item.ErrorMessage20: Exit Sub21: End If22: txtDesc.Text = desc23:24: End Sub25: 26: Private Sub Form_Load()27: Set Server = CreateObject("AgileAPI.Server")28: Server.SetLicenseKey("AgileAPILicenseKey")29: b = Server.Connect("localhost", 9013, scfAll)30: If b = False Then31: MsgBox "Failed to connect. " + Server.ErrorMessage32: Exit Sub33: End If34: b = Server.Login(txtUsername.Text, txtPassword.Text, 35: "c:\temp", 16384)36: If b = False Then37: MsgBox "Failed to login. " + Server.ErrorMessage


Chapter 4 Tutorials

38: End If39: End Sub



13 Type an invalid number (such as xxxx) in the Item Number field, then click Display. The application displays an error message explaining that the object could not be found.

Figure 4-6: Get Description error message

Creating a QueryThis tutorial shows how to create a Visual Basic application that runs a query or Search. The application displays a list of Items with numbers that contain a specified string. To complete this tutorial, you need Visual Basic 6.


\Program Files\Agile Advantage 2006\ADK\COM\Samples\Tutorials\Query


This section shows how to create and set up a project for the Query application.




4 In the Available References list, make sure Agile API is listed. If it’s not, click Browse to add it to the list. Navigate to the \Program Files\Agile Advantage 2006\ADK\COM\AgileAPI folder and select AgileAPI.dll.

4-11



6 Choose Project | Components. The Components dialog box appears.

Figure 4-7: Components dialog box

7 On the Controls tab, make sure the following options are checked:

• Microsoft Windows Common Controls 6.0• Microsoft Windows Common Controls-2 6.0

8 Click OK to add the controls to the Visual Basic Toolbox.


• Save the form as Query.frm.• Save the project as Query.vbp.

Part II: Creating the User Interface

This section shows how to add controls to the form to display the query.


2 Click the TextBox control in the Toolbox window, then draw a text box to the right of the label.

3 Click the CommandButton control in the Toolbox window, then draw a command button to the right of the text box.

4 Click the ListView control in the Toolbox window, then draw a list view below the label and text box.


Chapter 4 Tutorials

The form should now look like Figure 4-8.

Figure 4-8: Query Form With Initial Design


Part III: Setting Properties


Part IV: Entering the Code

This section shows how to write the code that runs a query.

1 Double-click the form to enter code for the Form_Load event procedure. Enter the following code:

01: Public Server As AgileAPI.Server02:03: Private Sub Form_Load()04:

Table 4-2: Form Properties


Command Button Name cmdFind

Command Button Caption &Find

Form Name frmQuery

Form Caption Simple Query

Label Name lblItemNumber

Label Caption Item #

List View Name lvwResults

Text Box Name txtItemNumber

Text Box Text (blank — clear the default value)

4-13


05: Set Server = CreateObject("AgileAPI.Server")06: Server.SetLicenseKey("AgileAPILicenseKey")07: b = Server.Connect("localhost", 9013, scfAll)08: b = Server.Login("username", "password", 09: "c:\temp", 16384)10:11: ' Set properties of the ListView12: ch = lvwResults.ColumnHeaders.Add(1,,"Item #", 1000)13: ch = lvwResults.ColumnHeaders.Add(2,,"Item Description", 2000)14: lvwResults.View = 315:16: End Sub


• Lines 1 through 9: This code is identical to code used for the tutorial “Creating an Application Using Visual Basic” on page 4-1. For an analysis of this code, see page 4-6.

• Lines 12 through 14: Set column headers and the View property for the ListView control named lvwResults.

2 Click in the Project Explorer window to return to the Form.

3 Double-click the Find button.

4 On the second line of the Code view, declare two new public variables:

Public col As AgileAPI.CollectionPublic Query As AgileAPI.Query

5 Write the following code for the cmdFind_Click event procedure:

01: Private Sub cmdFind_Click()02: 03: Dim number As Variant04: Dim desc As Variant05: Dim attrID As Long06: Dim l As Long07: Dim b As Boolean08: Dim i As Integer09: Dim object As Object10: Dim li As ListItem11: Dim RRange As Integer12: Dim RStart As Integer13:14: ’Create an instance of the Query object 15: Set Query = CreateObject("AgileAPI.Query")16: b = Query.Create(Server)


Chapter 4 Tutorials

17:18: ’Set the query class19: Query.SetClass(ctItem)20:21: ’Add query criteria22: attrID = aidParts_TitleBlock_Number23: l = Query.AddCriteria(attrID, qroContains, txtItemNumber, _24: qloNone, 0, 0)25:26: 'Set the query range27: RRange = 2028: Query.ResultRange = RRange29:30: lvwResults.ListItems.Clear31:32: 'Run the query33: Page:34: b = Query.Execute35:36: 'Add the query results to the list view37: Set col = Query.Results38: For i = 0 To col.Count - 139: Set object = col.Get(i)40: attrID = aidParts_TitleBlock_Number41: b = object.GetValue(attrID, number)42: attrID = aidParts_TitleBlock_Description43: b = object.GetValue(attrID, desc)44: Set li = lvwResults.ListItems.Add(, , number)45: li.SubItems(1) = desc46: Next i47:48: If (col.Count = RRange) Then49: Query.ResultStart = Query.ResultStart + RRange50: GoTo Page51: End If52:53: End Sub


• Lines 1 and 53: These are the wrapper lines for the cmdFind_Click event procedure.

• Lines 3 through 12: Declare several variables.• Lines 15 and 16: Create an instance of the Query object and initialize it to

the Server instance.• Line 19: Sets the query class to Item.

4-15


• Lines 22 through 24: Add a search condition that specifies that the query find all Items with an Item Number containing the string specified in the txtItemNumber field.

• Lines 27 and 28: Set the query result range.• Line 34: Runs the query.• Lines 37 through 46: Populate the list view with the query results.• Lines 48 through 51: If the number of items in the results is equal to the

result range, reset the result start number and run the query again. This if statement ensures that the query always returns all results from the database, instead of the default maximum number of results.


01: Private Sub cmdFind_Click()02: 03: Dim number As Variant04: Dim desc As Variant05: Dim attrID As Long06: Dim l As Long07: Dim b As Boolean08: Dim i As Integer09: Dim object As Object10: Dim li As ListItem11: Dim RRange As Integer12: Dim RStart As Integer13:14: ’Create an instance of the Query object 15: Set Query = CreateObject("AgileAPI.Query")16: b = Query.Create(Server)17:18: ’Set the query class19: Query.SetClass(ctItem)20:21: ’Add query criteria22: attrID = aidParts_TitleBlock_Number23: l = Query.AddCriteria(attrID, qroContains, txtItemNumber, _24: qloNone, 0, 0)25:26: 'Set the query range27: RRange = 2028: Query.ResultRange = RRange29:30: lvwResults.ListItems.Clear31:32: 'Run the query


Chapter 4 Tutorials

33: Page:34: b = Query.Execute35:36: 'Add the query results to the list view37: Set col = Query.Results38: For i = 0 To col.Count - 139: Set object = col.Get(i)40: attrID = aidParts_TitleBlock_Number41: b = object.GetValue(attrID, number)42: attrID = aidParts_TitleBlock_Description43: b = object.GetValue(attrID, desc)44: Set li = lvwResults.ListItems.Add(, , number)45: li.SubItems(1) = desc46: Next i47:48: If (col.Count = RRange) Then49: Query.ResultStart = Query.ResultStart + RRange50: GoTo Page51: End If52:53: End Sub54: 55: Private Sub Form_Load()56:57: Set Server = CreateObject("AgileAPI.Server")58: Server.SetLicenseKey("AgileAPILicenseKey")59: b = Server.Connect("localhost", 9013, scfAll)60: b = Server.Login("username", "password", _ 61: "c:\temp", 16384)62:63: ' Set properties of the ListView64: ch = lvwResults.ColumnHeaders.Add(1,,"Item #", 1000)65: ch = lvwResults.ColumnHeaders.Add(2,,"Item Description", 2000)66: lvwResults.View = 367:68: End Sub



4-17


8 Type a portion of a valid item number, then click Find. The matching items appear in the list view.

Figure 4-9: Simple Query application

Displaying SmartRules SettingsThis tutorial shows how to create a Visual Basic application that displays SmartRules settings, a simple use of the Agile Administrator API. The Agile Administrator API lets you access all nodes and properties of Agile Administrator, including object classes and subclasses, SmartRules, roles and privileges, preferences, and users. To complete this tutorial, you need Visual Basic 6.


\Program Files\Agile Advantage 2006\ADK\COM\Samples\Tutorials\SmartRules


This section shows how to create and set up a project for the SmartRules application.







Chapter 4 Tutorials






• Save the form as SmartRules.frm.• Save the project as SmartRules.vbp.




2 Click the ListView control in the Toolbox window, then draw a list view below the label.

3 Click the CommandButton control in the Toolbox window, then draw a command button below the ListView.The form should now look like Figure 4-10.

Figure 4-10: SmartRules Form With Initial Design


4-19





This section shows how to write the code that displays the SmartRules settings for an Agile eHub.


01: Public Server As AgileAPI.Server02:03: Private Sub Form_Load()04:05: Set Server = CreateObject("AgileAPI.Server")06: Server.SetLicenseKey("AgileAPILicenseKey")07: b = Server.Connect("localhost", 9013, scfAll)08: b = Server.Login("username", "password", _ 09: "c:\temp", 16384)10:11: 'Set properties of the ListView12: Set ch = lvwSmartRules.ColumnHeaders.Add(1, , _13: "SmartRule", 3000)14: Set ch = lvwSmartRules.ColumnHeaders.Add(2, , _15: "Current Setting", 3000)16: lvwSmartRules.View = 317:18: End Sub

Table 4-3: Form Properties


Command Button Name cmdOK

Command Button Caption OK

Form Name frmSmartRules

Form Caption Agile SmartRules

Label Name lblSmartRules

Label Caption SmartRules Properties

List View Name lvwSmartRules


Chapter 4 Tutorials


• Lines 1 through 9: This code is identical to code used for the tutorial “Creating an Application Using Visual Basic” on page 4-1. For an analysis of this code, see page 4-6.

• Lines 12 through 16: Set column headers and the View property for the ListView control named lvwSmartRules.

2 Click in the Project Explorer window to return to the Form.

3 Double-click the OK button on the form.

4 Write the following code for the cmdOK_Click event procedure:

01: Private Sub cmdOK_Click()02: End03: End Sub


• Lines 1 and 3: These are the wrapper lines for the cmdOK_Click event procedure.

• Line 2: Exits the application.

5 Go to the top of the Form_Load() procedure and declare the following variables:

Dim srNode As AgileAPI.NodeDim colNodeProps As AgileAPI.CollectionDim nodeProp As AgileAPI.PropertyDim b As BooleanDim ch As ObjectDim i As LongDim li As Object

6 At the bottom of the Form_Load() procedure add the following code:

01: lvwSmartRules.ListItems.Clear02: Set srNode = server.GetNode(nidSmartRules)03: If srNode Is Nothing Then04: MsgBox server.ErrorMessage05: End If06: 07: Set colNodeProps = srNode.Properties08: For i = 0 To colNodeProps.Count - 109: Set nodeProp = colNodeProps.Get(i)10: Set li = lvwSmartRules.ListItems.Add(, , nodeProp.Name)11: li.SubItems(1) = nodeProp.DisplayString12: Next i

4-21



• Line 1: Clears items from the list view.• Lines 2 through 5: Get the SmartRules node.• Line 7: Gets the collection of properties for the SmartRules node.• Lines 8 through 12: For each SmartRule, add the property name and

display string to the list view.


01: Public server As AgileAPI.Server02: 03: Private Sub cmdOK_Click()04: End05: End Sub06: 07: Private Sub Form_Load()08: 09: Dim srNode As AgileAPI.Node10: Dim colNodeProps As AgileAPI.Collection11: Dim nodeProp As AgileAPI.Property12: Dim b As Boolean13: Dim ch As Object14: Dim i As Long15: Dim li As Object16: 17: Set Server = CreateObject("AgileAPI.Server")18: Server.SetLicenseKey("AgileAPILicenseKey")19: b = Server.Connect("localhost", 9013, scfAll)20: b = Server.Login("username", "password",_ 21: "c:\temp", 16384)22:23: 'Set properties of the ListView24: Set ch = lvwSmartRules.ColumnHeaders.Add(1, , _25: "SmartRule", 3000)26: Set ch = lvwSmartRules.ColumnHeaders.Add(2, , _27: "Current Setting", 3000)28: lvwSmartRules.View = 329: 30: lvwSmartRules.ListItems.Clear31: Set srNode = server.GetNode(nidSmartRules)32: If srNode Is Nothing Then33: MsgBox server.ErrorMessage34: End If35: 36: Set colNodeProps = srNode.Properties


Chapter 4 Tutorials

37: For i = 0 To colNodeProps.Count - 138: Set nodeProp = colNodeProps.Get(i)39: Set li = lvwSmartRules.ListItems.Add(, , nodeProp.Name)40: li.SubItems(1) = nodeProp.DisplayString41: Next i42: 43: End Sub


8 Press F5 to run the application. The list of SmartRules and their properties appear in the list view.

Figure 4-11: SmartRules application

Synchronizing the BOMs of Two ItemsThis tutorial shows how to create a Visual Basic application that synchronizes the BOMs of two Parts. To complete this tutorial, you need Visual Basic 6.


\Program Files\Agile Advantage 2006\ADK\COM\Samples\Tutorials\SyncBOM

4-23



This section shows how to create and set up a project for the SyncBOM application.











• Save the form as SyncBOM.frm.• Save the project as SyncBOM.vbp.



1 Use the Label control and the TextBox control to create three labels and three text boxes on the left side of the form.

2 Click the CommandButton control in the Toolbox window, then draw a command button below the labels and text boxes.

3 Click the ListView control in the Toolbox window, then draw a list view on the right side of the form.

4 Use the Label control to add a label above the list view.


Chapter 4 Tutorials

The form should now look like Figure 4-12.

Figure 4-12: SyncBOM form with initial design




Table 4-4: Form properties


Command Button Name cmdSync

Command Button Caption &Synchronize

Form Name frmSyncBOM

Form Caption Synchronize BOMs

Label 1 Name lblSource

Label 1 Caption Source Item

Label 2 Name lblTarget

Label 2 Caption Target Item

Label 3 Name lblNumber

Label 3 Caption Change Number

Label 4 Name lblBOM

Label 4 Caption Target Item BOM

List View Name lvwBOM

Text Box 1 Name txtSource

Text Box 1 Text (blank -- clear the default value)

Text Box 2 Name txtTarget

Text Box 2 Text (blank -- clear the default value)

4-25



This section shows how to write the code that synchronizes the BOMs of two Items. When you use the SyncBOM method to synchronize the BOMs of two Items, you effectively create a new revision of the target Item. After synchronizing BOMs, your application should set a new revision for the Item and then release the Change to the target Item using the RouteObject::ChangeStatus method.


01: Public Server As AgileAPI.Server02: Public Item As AgileAPI.Item03: Public Table As AgileAPI.Table04: 05: Private Sub Form_Load()06: 07: 'Connect to the Agile eHub and log in08: Set Server = CreateObject("AgileAPI.Server")09: Server.SetLicenseKey("AgileAPILicenseKey")10: b = Server.Connect("localhost", 9013, scfAll)11: b = Server.Login("username", "password",_12: "c:\temp", 16384)13: 14: ' Set up list view15: lvwBOM.View = lvwReport16: lvwBOM.ColumnHeaders.Clear17: ch = lvwBOM.ColumnHeaders.Add(1, , "Item Number", 1200)18: ch = lvwBOM.ColumnHeaders.Add(2, , "Part Description", 2000)19: ch = lvwBOM.ColumnHeaders.Add(3, , "Rev", 800)20: ch = lvwBOM.ColumnHeaders.Add(4, , "Find Num", 900)21: ch = lvwBOM.ColumnHeaders.Add(5, , "Qty", 800)22: ch = lvwBOM.ColumnHeaders.Add(6, , "Ref Des", 900)23: ch = lvwBOM.ColumnHeaders.Add(7, , "BOM Notes", 900)24: 25: End Sub

Text Box 3 Name txtNumber

Text Box 3 Text (blank — clear the default value)

Table 4-4: Form properties (continued)



Chapter 4 Tutorials


• Lines 1 through 12: This code is similar to code used for the tutorial “Creating an Application Using Visual Basic” on page 4-1. For an analyis of this code, see page 4-6. The only new lines of code not in the previous tutorial are lines 2 and 3, where the Item and Table objects are declared.

• Lines 15 through 23: Set the View property and column headers for the list view control named lvwBOM.

2 Click in the Project window to switch to the Code view.

3 Double-click the Synchronize button.

4 Write the following code for the cmdSync_Click event procedure:

01: Private Sub cmdSync_Click()02: 03: Dim rlCols As AgileAPI.SyncOption04: Dim b As Boolean05:06: If txtSource.Text = "" Then07: If txtTarget.Text = "" Then08: If txtNumber.Text = "" Then09: MsgBox "Source Item, Target Item, and Change Number " & _10: "fields cannot be empty."11: Exit Sub12: End If13: End If14: End If15: 16: ' Get the specified target item17: Set Item = CreateObject(“AgileAPI.Item”)18: b = Item.LoadByAttr(Server, 0, txtTarget.Text)19: 20: If b = False Then21: MsgBox "Failed to get target Item. " + Item.ErrorMessage22: Exit Sub23: End If24: 25: ' Get the BOM table for the target Item26: Set Table = Item.GetTable(ttItemBOM)27:28: ' Create a new instance of the SyncOption object29: Set rlCols = CreateObject("AgileAPI.SyncOption")30:31: If Item.SyncBOM(txtSource.Text, txtNumber.Text, rlCols) Then32: Item.SetRevision txtNumber.Text

4-27


33: Call DisplayBOM(Item, Table)34: Else35: MsgBox "Failed to synchronize BOMs. " + Item.ErrorMessage36: End If37: 38: End Sub


• Lines 1 and 38: These are the wrapper lines for the cmdSync_Click event procedure.

• Line 3: Declares the rlCols variable.• Line 4: Declares the b Boolean variable.• Lines 6 through 14: If any of the fields in the dialog box are empty, exit the

procedure.• Lines 17 and 18: Get the Item specified in the Target Item field.• Lines 20 through 23: If b is False (0), display an error message and exit the

procedure.• Line 26: Gets the BOM table for the Item.• Line 29: Sets rlCols equal to a new SyncOption object.• Lines 31 through 36: Synchronize the BOM of the Target Item with the

BOM of the Source Item. If the SyncBOM method is successful, line 32 sets the revision of the Item to the one corresponding to the Change Number. Line 33 calls the DisplayBOM procedure, which fills the list view with the updated BOM.

5 Write the following code for the DisplayBOM procedure:

01: Public Sub DisplayBOM(Item As Object, Table As Object)02: 03: Dim li As ListItem04: Dim Value As Variant05: Dim row As AgileAPI.Row06: Dim attrID As Long07: 08: Table.Refresh09: 10: lvwBOM.ListItems.Clear11: 12: For i = 0 To Table.RowCount - 113:14: Set row = Table.Rows.Get(i)15: 16: 'Get the "BOM.Item Number" value17: attrID = aidParts_BOM_ItemNumber


Chapter 4 Tutorials

18: b = row.GetValue(attrID, Value)19: Set li = lvwBOM.ListItems.Add(i + 1, , Value)20: 21: 'Get the "BOM.Part Description" value22: attrID = aidParts_BOM_PartDescription23: b = row.GetValue(attrID, Value)24: li.SubItems(1) = Value25:26: 'Get the "BOM.Item Rev" value27: attrID = aidParts_BOM_ItemRev28: b = row.GetValue(attrID, Value)29: li.SubItems(2) = Value30: 31: 'Get the "BOM.Find Num" value32: attrID = aidParts_BOM_FindNum33: b = row.GetValue(attrID, Value)34: li.SubItems(3) = Value35: 36: 'Get the "BOM.Qty" value37: attrID = aidParts_BOM_Qty38: b = row.GetValue(attrID, Value)39: li.SubItems(4) = Value40: 41: 'Get the "BOM.Ref Des" value42: attrID = aidParts_BOM_RefDes43: b = row.GetValue(attrID, Value)44: li.SubItems(5) = Value45: 46: 'Get the "BOM.BOM Notes" value47: attrID = aidParts_BOM_BOMNotes48: b = row.GetValue(attrID, Value)49: li.SubItems(6) = Value50:51: Next i52: 53: End Sub


• Lines 1 and 53: These are the wrapper lines for the DisplayBOM procedure.• Lines 3 through 6: Declare local variables for the procedure.• Line 8: Refreshes the BOM table.• Lines 10 through 51: Populate the list view with data from the Target Item

BOM table.

4-29



001: Public Server As AgileAPI.Server002: Public Item As AgileAPI.Item003: Public Table As AgileAPI.Table004: 005: Private Sub Form_Load()006: 007: 'Connect to the Agile eHub and log in008: Set Server = CreateObject("AgileAPI.Server")009: Server.SetLicenseKey("AgileAPILicenseKey")010: b = Server.Connect("localhost", 9013, scfAll)011: b = Server.Login("username", "password", _012: "c:\temp", 16384)013: 014: ' Set up list view015: lvwBOM.View = lvwReport016: lvwBOM.ColumnHeaders.Clear017: ch = lvwBOM.ColumnHeaders.Add(1, , "Item Number", 1200)018: ch = lvwBOM.ColumnHeaders.Add(2, , "Part Description", 2000)019: ch = lvwBOM.ColumnHeaders.Add(3, , "Rev", 800)020: ch = lvwBOM.ColumnHeaders.Add(4, , "Find Num", 900)021: ch = lvwBOM.ColumnHeaders.Add(5, , "Qty", 800)022: ch = lvwBOM.ColumnHeaders.Add(6, , "Ref Des", 900)023: ch = lvwBOM.ColumnHeaders.Add(7, , "BOM Notes", 900)024: 025: End Sub026: 027: Private Sub cmdSync_Click()028: 029: Dim rlCols As AgileAPI.SyncOption030: Dim b As Boolean031:032: If txtSource.Text = "" Then033: If txtTarget.Text = "" Then034: If txtNumber.Text = "" Then035: MsgBox "Source Item, Target Item, and Change Number " & _036: "fields cannot be empty."037: Exit Sub038: End If039: End If040: End If041: 042: ' Get the specified target item043: Set Item = CreateObject("AgileAPI.Item")044: b = Item.LoadByAttr(Server, 0, txtTarget.Text)


Chapter 4 Tutorials

045: 046: If b = False Then047: MsgBox "Failed to get target Item. " + Item.ErrorMessage048: Exit Sub049: End If050: 051: ' Get the BOM table for the target Item052: Set Table = Item.GetTable(ttItemBOM)053:054: ' Create a new instance of the SyncOption object055: Set rlCols = CreateObject("AgileAPI.SyncOption")056:057: If Item.SyncBOM(txtSource.Text, txtNumber.Text, rlCols) Then058: Item.SetRevision txtNumber.Text059: Call DisplayBOM(Item, Table)060: Else061: MsgBox "Failed to synchronize BOMs. " + Item.ErrorMessage062: End If063: 064: End Sub065: 066: Public Sub DisplayBOM(Item As Object, Table As Object)067: 068: Dim li As ListItem069: Dim Value As Variant070: Dim row As AgileAPI.Row071: Dim attrID As Long072 073: Table.Refresh074: 075: lvwBOM.ListItems.Clear076: 077: For i = 0 To Table.RowCount - 1078:079: Set row = Table.Rows.Get(i)080: 081: 'Get the "BOM.Item Number" value082: attrID = aidParts_BOM_ItemNumber083: b = row.GetValue(attrID, Value)084: Set li = lvwBOM.ListItems.Add(i + 1, , Value)085: 086: 'Get the "BOM.Part Description" value087: attrID = aidParts_BOM_PartDescription088: b = row.GetValue(attrID, Value)089: li.SubItems(1) = Value

4-31


090:091: 'Get the "BOM.Item Rev" value092: attrID = aidParts_BOM_ItemRev093: b = row.GetValue(attrID, Value)094: li.SubItems(2) = Value095: 096: 'Get the "BOM.Find Num" value097: attrID = aidParts_BOM_FindNum098: b = row.GetValue(attrID, Value)099: li.SubItems(3) = Value100: 101: 'Get the "BOM.Qty" value102: attrID = aidParts_BOM_Qty103: b = row.GetValue(attrID, Value)104: li.SubItems(4) = Value105: 106: 'Get the "BOM.Ref Des" value107: attrID = aidParts_BOM_RefDes108: b = row.GetValue(attrID, Value)109: li.SubItems(5) = Value110: 111: 'Get the "BOM.BOM Notes" value112: attrID = aidParts_BOM_BOMNotes113: b = row.GetValue(attrID, Value)114: li.SubItems(6) = Value115:116: Next i117: 118: End Sub



8 Type values in the three fields, then click Synchronize. The newly synchronized BOM table appears in the list view.


Chapter 4 Tutorials

Figure 4-13: SyncBOM application

Redlining a BOMThis tutorial shows how to write the Visual Basic code needed to redline the BOM of a released Part. Unlike the other tutorials in this chapter, there is no user interface to create. It is purely a code tutorial. To complete this tutorial, you need Visual Basic 6.


\Program Files\Agile Advantage 2006\ADK\COM\Samples\Tutorials\RedlineBOM


Set up the Visual Basic project as you have in the other Visual Basic tutorials in this chapter. For more information, see “Part I: Setting Up the Project” on page 4-11.

Part II: Logging In

Write the code that creates an instance of the Agile API Server, sets the Agile API license key, connects to the server, and logs in. For more information, see “Part IV: Entering the Code” on page 4-13.

Part III: Declaring Public Variables

In the public declarations section of the form, make sure the following variables have been declared:

Public Server As AgileAPI.ServerPublic Item As AgileAPI.ItemPublic Change As AgileAPI.ChangePublic Table As AgileAPI.TablePublic Row As AgileAPI.Row

4-33


Part IV: Adding a RedlineBOM Procedure

Add the wrapper lines for a procedure called RedlineBOM:

Private Sub RedlineBOM(Server As AgileAPI.Server)

End Sub

Part V: Getting a Released Part

Within the RedlineBOM procedure, add the following code to get a Part numbered P00003. Substitute a valid Part number for your Agile server. Make sure the Part is released and has a BOM.

Dim partNum As StringDim b As BooleanDim attrID As Long

’Replace "P00003" with a valid part number.’The part must be released and it must have a BOM.partNum = "P00003"

'Get Part P00003attrID = aidParts_TitleBlock_NumberSet Item = CreateObject("AgileAPI.Item")b = Item.LoadByAttr(Server, attrID, partNum)If b = False Then MsgBox "Failed to get item." + Item.ErrorMessage Exit SubEnd If

Part VI: Creating a Change

Add the following code to create an ECO numbered C10001.

Dim changeNum As String

’You can replace "C10001" with a different number.changeNum = "C10001"

'Create an ECOSet Change = CreateObject("AgileAPI.Change")b = Change.Create(Server, "ECO", changeNum)If Not b Then MsgBox "Failed to create change. " + Change.ErrorMessage Exit SubEnd If


Chapter 4 Tutorials

Part VII: Adding the Part to the Affected Items Tab of the Change

Add the following code to add the Part to the Affected Items tab.

'Get the Affected Items table of the changeSet Table = Change.GetTable(ttChangeAffectedItems)

'Add a new row to the Affected Items tableSet Row = Table.AddRow

'Set the Item Number fieldattrID = aidChangeOrders_AffectedItems_ItemNumberb = Row.SetValue(attrID, partNum)If Not b Then MsgBox "Failed to set Item Number field." + Row.ErrorMessage Exit SubEnd If

Part VIII: Setting the Revision

Add the following code to specify the new revision for the Change, save it, then set the revision for the Part to the one associated with the Change.

'Set the New Rev fieldattrID = aidChangeOrders_AffectedItems_NewRevb = Row.SetValue(attrID, "B")If Not b Then MsgBox "Failed to set the new revision. " + Row.ErrorMessage Exit SubEnd If

'Save the Changeb = Change.SaveIf Not b Then MsgBox "Failed to save the Change. " + Change.ErrorMessage Exit SubEnd If

'Set the revision for the Item to the one associated with the Changeb = Item.SetRevision(changeNum)If Not b Then MsgBox "Failed to set revision. " + Item.ErrorMessage Exit SubEnd If

4-35


Part IX: Modifying the Redline BOM Table

Add the following code to get the Redline BOM table, add a new row to it, set some new redline values, and then save the Part.

'Get the RedlineBOM table for the ItemSet Table = Item.GetTable(ttItemRedlineBOM)If Table Is Nothing Then MsgBox "Failed to get the Redline BOM table. " + Item.ErrorMessage Exit SubEnd If

'Add a row to the BOM tableSet Row = Table.AddRowIf Row Is Nothing Then MsgBox "Failed to add a row. " + Table.ErrorMessage Exit SubEnd If

'Start making redline changes'Set the "BOM.Part Description" valueattrID = aidParts_BOM_PartDescriptionb = Row.SetValue(attrID, "New Widget")'Set the "BOM.BOM Notes" valueattrID = aidParts_BOM_BOMNotesb = Row.SetValue(attrID, "This is a redline change.")If Not b Then MsgBox "Failed to set value. " + Row.ErrorMessage Exit SubEnd If

'Save the Partb = Item.SaveIf Not b Then MsgBox "Failed to save the Part. " + Item.ErrorMessageEnd If

Complete Code

The complete code for the procedure looks like this:

Private Sub RedlineBOM(Server As AgileAPI.Server)

Dim partNum As StringDim b As BooleanDim attrID As Long


Chapter 4 Tutorials

’Replace "P00003" with a valid part number.’The part must be released and it must have a BOM.partNum = "P00003"

'Get Part P00003attrID = aidParts_TitleBlock_NumberSet Item = CreateObject("AgileAPI.Item")b = Item.LoadByAttr(Server, attrID, partNum)If b = False Then MsgBox "Failed to get item." + Item.ErrorMessage Exit SubEnd If

Dim changeNum As String

'You can replace "C10001" with a different number.changeNum = "C10001"

'Create an ECOSet Change = CreateObject("AgileAPI.Change")b = Change.Create(Server, "ECO", changeNum)If Not b Then MsgBox "Failed to create change. " + Change.ErrorMessage Exit SubEnd If

'Get the Affected Items table of the changeSet Table = Change.GetTable(ttChangeAffectedItems)

'Add a new row to the Affected Items tableSet Row = Table.AddRow

'Set the Item Number fieldattrID = aidChangeOrders_AffectedItems_ItemNumberb = Row.SetValue(attrID, partNum)If Not b Then MsgBox "Failed to set Item Number field." + Row.ErrorMessage Exit SubEnd If

'Set the New Rev fieldattrID = aidChangeOrders_AffectedItems_NewRevb = Row.SetValue(attrID, "B")If Not b Then MsgBox "Failed to set the new revision. " + Row.ErrorMessage

4-37


Exit SubEnd If

'Save the Changeb = Change.SaveIf Not b Then MsgBox "Failed to save the Change. " + Change.ErrorMessage Exit SubEnd If

'Set the revision for the Item to the one associated with the Changeb = Item.SetRevision(changeNum)If Not b Then MsgBox "Failed to set revision. " + Item.ErrorMessage Exit SubEnd If

'Get the RedlineBOM table for the ItemSet Table = Item.GetTable(ttItemRedlineBOM)If Table Is Nothing Then MsgBox "Failed to get the Redline BOM table. " + Item.ErrorMessage Exit SubEnd If

'Add a row to the BOM tableSet Row = Table.AddRowIf Row Is Nothing Then MsgBox "Failed to add a row. " + Table.ErrorMessage Exit SubEnd If

'Start making redline changes'Set the "BOM.Part Description" valueattrID = aidParts_BOM_PartDescriptionb = Row.SetValue(attrID, "New Widget")'Set the "BOM.BOM Notes" valueattrID = aidParts_BOM_BOMNotesb = Row.SetValue(attrID, "This is a redline change.")If Not b Then MsgBox "Failed to set value. " + Row.ErrorMessage Exit SubEnd If

'Save the Partb = Item.Save


Chapter 4 Tutorials

If Not b Then MsgBox "Failed to save the Part. " + Item.ErrorMessageEnd If

Creating an ASP Application Using Visual InterDevThis tutorial shows how to create a very simple Active Server Pages (ASP) application that uses the Agile API. The application displays the description of an Item based on the specified Item Number. To complete this tutorial, you need Microsoft Visual InterDev 6.0.


\Program Files\Agile Advantage 2006\ADK\COM\Samples\Tutorials\GetDesc\ASP


This section shows how to create a new project and set a reference to the Agile API object library.

1 Start Visual InterDev. The New Project dialog box appears.

2 Specify a name and location for the project, then double-click the New Web Project icon.

Figure 4-14: New Project dialog box

3 In Step 1 of the Web Project Wizard, specify the name of your Web server, then click Next.

4-39


Note For Visual InterDev to recognize your Web server, you may need to install FrontPage 98 Server Extensions.

4 In Steps 2, 3, and 4 of the Web Project Wizard, use the default settings. In the Step 4 dialog, click Finish to create the new project. It may take several seconds for Visual InterDev to set up the scripts for your project.

5 Choose Project | Project References.

6 In the Available References list, make sure that Agile API is listed. If it’s not, click Browse to add it to the list. Navigate to the \Program Files\Agile Advantage 2006\ADK\COM\AgileAPI directory and select the Agile API library file (AgileAPI.dll).


Part II: Designing the Login Page

This section shows how to add a login page to the project.

1 From the menu, choose Project | Add Item.

2 In the Name field, type login.asp, then double-click the ASP Page icon.

Figure 4-15: Add Item dialog box

A new ASP page appears in the designer. The login.asp file also is listed in the Project Explorer window.

3 Click the Design tab of login.asp.

4 Type Username at the top left of the page.

5 In the Toolbox, select Design-Time Controls. These controls support server-side scripting.


Chapter 4 Tutorials

6 Double-click the Textbox control.

7 A message box asks if you would like to enable the Scripting Object Model for the page. Click Yes.

8 Place the cursor to the right of the text box, then press Enter.

9 Type Password.

10 Double-click the Textbox control to add another text box.

11 Place the cursor to the right of the text box, then press Enter.

12 Place the cursor to the right of the text box, then double-click the Button control.

13 Place the cursor to the right of the button, then press Enter.

14 Type Login Status:, then double-click the Label control.

15 Place the cursor to the right of the label, then press Enter.

16 Type After login, click here to continue.

The page should look like Figure 4-16.

Figure 4-16: Login page design

17 From the menu, choose File | Save.

4-41


Part III: Setting Properties of the Login Page

Set properties for the login page as specified in Table 4-5.

There is one more property you need to set for the Password text box. Right-click the text box and choose Properties from the shortcut menu. Click the Style drop-down list, select Password, then click OK. The Password style makes the text box show an asterisk (*) for each letter that a user types.

Part IV: Adding Scripting to the Login Page

This section describes how to add VBScript to the page to make it log into the Agile eHub server.

1 Click the Source tab of the login page.

2 In the Toolbox, select the Script Outline.

3 Open the Server Objects & Events folder, then open the cmdLogin object.

4 Double-click the onclick event. On the Source tab of the login page, the following wrapper lines are added for the cmdLogin_onclick() event procedure:

Sub cmdLogin_onclick()

End Sub

5 Complete the code for the cmdLogin_onclick() procedure. The code should look like this:

01: Sub cmdLogin_onclick()02: 03: set Svr = Server.CreateObject("AgileAPI.Server")04: Svr.SetLicenseKey("AgileAPILicenseKey")05: Svr.Connect("localhost", 9013, scfAll)

Table 4-5: Login Page properties


Command 1 Button Caption Login

Command Button ID cmdLogin

Textbox1 ID txtUsername

Textbox2 ID txtPassword

Label 1 DataField Not connected

Label 1 ID lblStatus


Chapter 4 Tutorials

06: b = Svr.Login(cstr(txtUsername.value), _07: cstr(txtPassword.value), "c:\temp", _08: 16384)09: if b then10: lblStatus.setCaption("Login successful")11: set Session("Svr") = Svr12: else13: lblStatus.setCaption(Svr.ErrorMessage)14: end if15: 16: End Sub


• Lines 1 and 14: The wrapper lines for the cmdLogin_onclick() event procedure.

• Line 3: Creates an instance of the AgileAPI.Server object and sets it equal to Svr.

• Line 4: Sets the license key for the Server instance, enabling the application to use Agile API functionality. Replace AgileAPILicenseKey with a valid key. For more information, see “Server::SetLicenseKey()” on page 6-226.

• Line 5: Connects to the Agile eHub server.• Lines 6 through 8: Log into the server using the text in the Username and

Password fields.• Lines 9 through 14: If login is successful, line 10 changes the lblStatus

caption to “Login successful.” Line 11 saves the Svr instance to the session; if you did not save the Svr instance to the session, you would need to create a new Svr instance each time a script needed to reference it. If login is not successful, line 13 changes the lblStatus caption to the server error message.

6 Choose File | Save.

Part V: Designing the Main Page

This section describes how to add a second page to the project, which is the main page for the application.

1 From the menu, choose Project | Add Item again.

2 In the Name field, type main.asp, then double-click the ASP Page icon.

A new ASP page appears in the designer. The main.asp file also is listed in the Project Explorer window.

4-43


3 Click the Design tab of main.asp.

4 Type Item Number at the top left of the page.

5 In the Toolbox, select Design-Time Controls.

6 Double-click the Textbox control.

7 A message box asks if you would like to enable the Scripting Object Model for the page. Click Yes.

8 Place the cursor to the right of the text box, then double-click the Button control.

9 Place the cursor to the right of the button, then press Enter.

10 Type Item Description.

11 Double-click the Textbox control to add another text box.

The page should look like Figure 4-17.

Figure 4-17: Main page design


Part VI: Setting Properties of the Main Page

Set properties for the main page as specified in Table 4-6.

Table 4-6: Main Page properties


Command 1 Button Caption Get Description

Command Button ID cmdGetDesc

Textbox1 ID txtNumber

Textbox2 ID txtDesc


Chapter 4 Tutorials

Part VII: Adding Scripting to the Main Page

This section describes how to add VBScript to the main page to make it get the description for a specified Item.

1 Click the Source tab of the login page.

2 In the Toolbox, select Script Outline.

3 Open the Server Objects & Events folder, then open the cmdGetDesc object.

4 Double-click the onclick event. On the Source tab of the login page, the following wrapper lines are added for the cmdLogin_onclick() event procedure:

Sub cmdGetDesc_onclick()

End Sub

5 Complete the code for the cmdGetDesc_onclick() procedure. The code should look like this:

01: Sub cmdGetDesc_onclick()02: 03: set Svr = Session("Svr")04: set Item = CreateObject("AgileAPI.Item")05: b = Item.LoadByAttr(Svr, 0, txtNumber.value)06: b = Item.GetValue(aidParts_TitleBlock_Description, value)07: txtDesc.value = value08: 09: End Sub


• Lines 1 and 8: The wrapper lines for the cmdGetDesc_onclick() event procedure.

• Line 3: Sets Svr equal to the Svr instance saved to the session.• Line 4: Creates a new Item object.• Line 5: Retrieves the Item specified by the Item Number field.• Line 6: Retrieves the description of the Item.• Line 7: Sets the Item Description value to the description retrieved on Line

6.


4-45


Part VIII: Adding a Link from the Login Page to the Main Page

Currently, there isn’t a link from the login page to the main page. This section describes how to add the link so that a user can login and then go to the main page.

1 In the Project Explorer window, double-click login.asp to open the page.

2 Click the Design tab of the page.

3 Select the word “here” in the text, “After login, click here to continue.”

4 Choose HTML | Link.

5 In the URL field, type main.asp, then click OK.

6 From the menu, choose File | Save All.

Part IX: Running the Application

This section describes how to run the aspGetDesc application.

1 Right-click the login.asp page in the Project Explorer and choose View in Browser from the pop-up menu.

2 Type a valid username and password, then click Login. The Login Status text should change to “Login successful.”

Figure 4-18: Login page in Internet Explorer

3 Click the “here” link to go to the main.asp page.


Chapter 4 Tutorials

4 Type a valid Agile Item Number, then click Get Description. The description should appear in the Item Description field.

Figure 4-19: Main page in Internet Explorer

4-47



CHAPTER 5Managing and

Tracking QualityThis chapter shows how to manage quality tracking processes using the Agile API. It contains the following topics:❑ About Quality Control❑ Working with Customers❑ Working with Problem Reports and Issues❑ Working with Corrective Action Requests❑ Using Workflow Features with Problem Reports, Issues, and CARs❑ Working with the Related PSR Table

5-1


About Quality ControlThe Agile system provides tools that allow companies to track and manage the following product quality items:

❑ customer complaints❑ product and manufacturing quality issues❑ enhancement and Corrective Action Requests

The corrective action process in the Agile system is flexible and can be implemented in many different ways. For example, one way to customize the Agile system is to use the Agile ADK to integrate the system with a Customer Relationship Management (CRM) system.

Quality-Related API Objects

The Agile system includes the following new API objects:

❑ Customer — a customer that uses the company’s product(s). In some Agile implementations, customers and problem reports will be imported directly from Customer Relationship Management (CRM) systems.

❑ ServiceRequest — similar to the RouteObject class, this class lets you create two types of ServiceRequest objects, problem reports and issues.

In addition to Customer and ServiceRequest, the Agile API supports a new type of Change object, Quality Change Requests. The default type of Quality Change Request is a Corrective Action Request, or CAR. A CAR is a request to correct a quality issue that has been identified with a product.

Quality-Related Roles and Privileges

To create, view, and modify problem reports, issues, and CARs, you must have the appropriate privileges. The Agile system has two default user roles that provide users with privileges to work with Problem Reports, Issues, and CARs:

❑ Quality Analyst — role for users who manage problem reports and issues❑ Quality Administrator — role for users who manage CARs and other

Quality Change Requests (QCRs)

For more information about roles and privileges, see the Agile Administrator User’s Guide.

5-2 Developer Guide

Chapter 5 Managing and Tracking Quality

Working with CustomersThis section describes how to create, load, and save Customer objects.

About Customers

The Customer object stores contact information about a customer. What role does a customer have in the Agile system? Customers provide feedback on your company’s products, alerting you to quality issues or problems they encounter.

The Customer object can originate in another system, such as a CRM system. You can use the Agile ADK to import customer data and problem reports from CRM systems into the Agile system.

Creating a Customer

To create a customer, create a new Customer object, then use the Customer::Create method to initialize the object.

Example 5-1 shows how to create a customer by specifying the Customer subclass ID.

Example 5-1: Creating A Customer Using The Customer Subclass ID

Public Sub CreateCustomer() 'Declare variables Dim b As Boolean Dim vSubClassID As Variant Dim strCustNum As String Dim strCustName As String Dim strSiteNum As String Dim strSiteName As String Dim cust1 As AgileAPI.Customer 'Initialize variables vSubClassID = 4988 ’subclass ID for Customer Set cust1 = new AgileAPI.Customer strCustNum = "CUST00001" strCustName = "Western Widgets" strSiteNum = "SITE00025" strSiteName = "San Jose"

b = cust1.Create(server, vSubClassID, strCustNum, strCustName, _ strSiteNum, strSiteName)

5-3


If Not b Then MsgBox "Failed to create customer. " + cust1.ErrorMessage End If End Sub

Example 5-2 shows how to create a customer by specifying the Customer subclass name.

Example 5-2: Creating a customer using the Customer subclass name

Public Sub CreateCustomer() 'Declare variables Dim b As Boolean Dim strCustNum As String Dim strCustName As String Dim strSiteNum As String Dim strSiteName As String Dim vSubClassName As Variant Dim cust1 As AgileAPI.Customer 'Initialize variables Set cust1 = new AgileAPI.Customer strCustNum = "CUST00001" strCustName = "Western Widgets" strSiteNum = "SITE00025" strSiteName = "San Jose" vSubClassName = "Customer"

b = cust1.Create(server, vSubClassName, strCustNum, strCustName, _ strSiteNum, strSiteName) If Not b Then MsgBox "Failed to create customer. " + cust1.ErrorMessage End IfEnd Sub

Loading a Customer

To load a customer, create a new Customer object, then use either the LoadByAttr() or LoadByInfo() method to initialize the object.

Example 5-3: Loading A Customer By Attribute

Public Sub LoadCustomer()

'Declare variables Dim b As Boolean

5-4 Developer Guide


Dim cust1 As AgileAPI.Customer

'Create a new Customer object Set cust1 = new AgileAPI.Customer

'Load a customer using the default attribute 0, 'which is equal to 5110 (General Info | Customer number). 'For the value parameter, specify a CustomerNumber::SiteID pair. b = cust1.LoadByAttr(server, 0, "CUST00001::SITE00025")

'Load a customer using attribute 5110 '(General Info | Customer number) b = cust1.LoadByAttr(server, 5110, "CUST00001::SITE00025")

'Load a customer using attribute 5111, '(General Info | Customer Name). For the value parameter, 'specify a CustomerName::SiteName pair. b = cust1.LoadByAttr(server, 5111, "Western Widgets::San Jose")

End Sub

Customer Tabs

Table 5-1 lists the tabs that each Customer can have:

Note General Info, Page Two, and Page Three tabs are single-row tables whose fields can be accessed directly without using DataObject::GetTable.

Saving a Customer as Another Customer with a Different Site

To save a customer as another customer, use the DataObject::SaveAs method, which has the following syntax:

Table 5-1: Customer tabs

Tab Related table type constant Read/Write mode

General Info ttCustomerPage1 Read/Write

Page Two ttCustomerPage2 Read/Write

Page Three ttCustomerPage3 Read/Write

Related PSR ttCustomerRelatedPSR Read-only

Attachments ttCustomerFiles Read/Write

History ttCustomerHistory Read-only

5-5


BOOL SaveAs(LPDISPATCH subClass, LPCTSTR number)

For the number parameter, use one of the following formats for customers:

❑ customerNumber::customerName::siteID::siteName❑ customerNumber::customerName::siteID❑ customerNumber::customerName

Example 5-4: Saving a customer to another customer with a different site

Dim b As Boolean

'Create an empty customer objectDim customer As AgileAPI.CustomerSet customer = new AgileAPI.Customer

'Load an existing customer from the serverb = customer.LoadByAttr(server, 0, "CUST00001::SJ")

'Save the customer with a new site ID and site nameb = customer.SaveAs(customer.SubClass, _ "CUST0001::Western Widgets::AU::Austin")

Working with Problem Reports and IssuesThis section describes how to work with the two different ServiceRequest objects, problem reports and issues.

About Problem Reports

A problem report describes a problem or an incident that occurred with a product from the customer’s perspective. A problem report can be submitted by a customer, sales representative, or customer service representative.

Because a problem report usually originates with a customer, it may not accurately describe the actual cause of the problem. To understand the root cause of a problem, a Quality Analyst must investigate the problem.

You can associate a problem report with a customer and customer site. You can also associate a problem report with an item. Neither the Cover Page | Customer Name, Cover Page | Site Name, nor Cover Page | Item Number fields is required.

5-6 Developer Guide


Problem reports can be routed for investigation. The investigating team, consisting of Quality Analysts, determines the root cause of the problem and decides whether to escalate the problem into an issue.

About Issues

An issue is a problem that has been investigated by a Quality Analyst and has been determined to need corrective action. Issues and problem reports can be related; it may be helpful to think of an issue as the next step in a Quality Control process after a problem report. An issue describes a problem from an engineering perspective, correctly identifying the root cause of a problem that has been deemed important enough to fix.

An issue can be related to one or more problem reports. For example, you may consolidate five similar problem reports into one issue that identifies the root cause for all five reported problems.

An issue can also be created without an associated problem report. For example, a product issue may have surfaced within your company instead of at a customer site. If the root cause of the problem is known, you can skip the problem report step and create an issue.

You can associate an issue with a customer and customer site. Unless an issue consolidates multiple problem reports, you can also associate an issue with an item. Neither the Cover Page | Customer Name, Cover Page | Site Name, nor Cover Page | Item Number fields is required.

Issues can be routed for review. Typically, the review is used for additional information gathering rather than approval and rejection.

Creating a Problem Report

To create a problem report, create a new ServiceRequest object, then use the ServiceRequest::Create method to initialize the object.

Example 5-5 shows how to create a problem report by specifying the Problem Report subclass ID.

Example 5-5: Creating a problem report by specifying the subclass ID

Public Sub CreateProblemReport() 'Declare variables Dim b As Boolean

5-7


Dim vSubClassID As Variant Dim pr1 As AgileAPI.ServiceRequest Dim strPRNum As String

'Initialize variables Set pr1 = new AgileAPI.ServiceRequest vSubClassID = 4883 'subclass ID for Problem Reports strPRNum = "PR00001"

'Create a Problem Report b = pr1.Create(server, vSubClassID, strPRNum) If Not b Then MsgBox "Failed to create Problem Report. " + pr1.ErrorMessage End IfEnd Sub

Example 5-6 shows how to create a problem report by specifying the Problem Report subclass name.

Example 5-6: Creating A Problem Report By Specifying The Subclass Name

Public Sub CreateProblemReport() 'Declare variables Dim b As Boolean Dim pr1 As AgileAPI.ServiceRequest Dim vSubClassName As Variant Dim strPRNum As String

'Initialize variables Set pr1 = new AgileAPI.ServiceRequest vSubClassName = "Problem Report" strPRNum = "PR00001"

b = pr1.Create(server, vSubClassName, strPRNum) If Not b Then MsgBox "Failed to create Problem Report. " + pr1.ErrorMessage End IfEnd Sub

Creating an Issue

An issue, like a problem report, is a type of ServiceRequest. To create an issue, create a new ServiceRequest object, then use the ServiceRequest::Create method to initialize the object.

Example 5-7 shows how to create an issue by specifying the Issue subclass ID.

5-8 Developer Guide


Example 5-7: Creating An Issue By Specifying The Subclass ID

Public Sub CreateIssue() 'Declare variables Dim b As Boolean Dim vSubClassID As Variant Dim issue1 As AgileAPI.ServiceRequest Dim strIssueNum As String

'Initialize variables Set issue1 = new AgileAPI.ServiceRequest vSubClassID = 4900 ’subclass ID for Issues strIssueNum = "ISSUE00001"

'Create an Issue b = issue1.Create(server, vSubClassID, strIssueNum) If Not b Then MsgBox "Failed to create Issue. " + issue1.ErrorMessage End IfEnd Sub

Example 5-8 shows how to create an issue by specifying the Issue subclass name.

Example 5-8: Creating An Issue By Specifying The Subclass Name

Public Sub CreateIssue() 'Declare variables Dim b As Boolean Dim pr1 As AgileAPI.ServiceRequest Dim vSubClassName As Variant Dim strPRNum As String

'Initialize variables Set pr1 = new AgileAPI.ServiceRequest vSubClassName = "Issue" strPRNum = "ISSUE00001"

b = issue1.Create(server, vSubClassName, strIssueNum) If Not b Then MsgBox "Failed to create Issue. " + issue1.ErrorMessage End IfEnd Sub

5-9


Problem Report and Issue Tabs

Table 5-2 lists the tabs that each problem report and issue can have:

Note Cover Page, Page Two, and Page Three tabs are single-row tables whose fields can be accessed directly without using DataObject::GetTable.

Assigning a Problem Report or Issue

To assign a problem report or issue to a Quality Analyst, you set the value for the Cover Page | Quality Analyst field, which is a list field. The value for a list field must be a Collection object containing one ListElement or String. Example 5-9 shows how to set the value for the Cover Page | Quality Analyst field for a problem report or issue.

Example 5-9: Assigning a problem report or issue

Public Sub AssignServiceRequest(sr As AgileAPI.ServiceRequest)

'Declare variables Dim b As Boolean Dim l As Long Dim attr As AgileAPI.Attribute Dim col As AgileAPI.Collection Dim listVal As ListElement Dim nClassID As Integer Dim vCol As Variant Dim vAttrID As Variant

'Initialize variables nClassID = sr.SubClass.ClassID

If nClassID = ctServiceRequestProblemReport Then

Table 5-2: Problem Report And Issue Tabs


Cover Page ttServiceRequestPage1 Read/Write

Page Two ttServiceRequestPage2 Read/Write

Page Three ttServiceRequestPage3 Read/Write

Related PSR (for issue only) ttServiceRequestRelatedPSR Read/Write

Signoff ttServiceRequestSignoff Read/Write

Attachments ttServiceRequestFiles Read/Write

History ttServiceRequestHistory Read-only



vAttrID = aidProblemReports_CoverPage_QualityAnalyst Else vAttrID = aidIssues_CoverPage_QualityAnalyst EndIf

'Get the first user in the list for the Quality Analyst field Set attr = server.GetAttribute(nClassID, vAttrID) Set col = attr.ListElements Set listVal = col.Get(0)

'Get the current value of the Quality Analyst field b = sr.GetValue(vAttrID, vCol) 'Clear the collection b = vCol.Clear 'Add the list element to vListVal l = vCol.Add(listVal, -1)

'Set the value of the Quality Analyst field b = sr.SetValue(vAttrID, vCol) If Not b Then MsgBox "Failed to set value. " + sr.ErrorMessage End IfEnd Sub

Associating a Problem Report or Issue with an Item

To associate a Problem Report with an Item, you set the value for the Cover Page | Item Number field. This is fairly straightforward, but there are some restrictions that apply. For example, if an issue consolidates multiple problem reports, you can’t associate it with an item.

Example 5-10: Setting The Item Number Field For A Problem Report Or Issue

'Sets the Item Number associated with a Problem Report'or an Issue. The boolIsPR parameter identifies whether'the object is a Problem Report or not.Public Sub SetItemNumber(sr As AgileAPI.ServiceRequest, _ vItemNum As Variant, boolIsPR As Boolean)

Dim vAttrID As Variant

If boolIsPR Then vAttrID = aidProblemReports_CoverPage_ItemNumber Else vAttrID = aidIssues_CoverPage_ItemNumber

5-11


EndIf

'Set the value of the Item Number field b = sr.SetValue(vAttrID, vItemNum) If Not b Then MsgBox "Failed to set value. " + sr.ErrorMessage End IfEnd Sub

Linked Fields for Problem Reports and Issues

The following fields of a problem report or issue are linked to the Cover Page | Item Number field:

❑ Cover Page | Failure Mode ❑ Cover Page | Rev Fixed ❑ Cover Page | Rev Found

When you specify a value for the Cover Page | Item Number field, the list of available values (a Collection containing ListElement objects) for each of these linked fields is updated automatically. If the Cover Page | Item Number field is empty, you cannot select a value for a linked field.

Working with Corrective Action RequestsThis section describes how to work with Corrective Action Requests (CAR).

About CARs

A CAR is type of change that addresses defects that (generally) surfaced from issues and problem reports. CARs are in the new Quality Change Requests (QCR) class, which is part of the Change category, or superclass.

A CAR is a type of change that addresses product quality defects. Typically, the defects addressed by CARs surfaced from problem reports and issues.

By the time a problem reaches the CAR stage, the team has figured out which specific items must be fixed (the affected items).



Creating a CAR

To create a CAR, create a new Change object, then use the Change::Create method to initialize the object.

Example 5-11 shows how to create a CAR by specifying the CAR subclass ID.

Example 5-11: Creating A CAR By Specifying The Subclass ID

Public Sub CreateCAR() { 'Declare variables Dim b As Boolean Dim vSubClassID As Variant Dim car1 As AgileAPI.Change Dim strCARNum As String

'Initialize variables Set car1 = new AgileAPI.Change vSubClassID = 4933 'subclass ID for CARs strCARNum = "QCR00001"

'Create a CAR b = car1.Create(server, vSubClassID, strCARNum) If Not b Then MsgBox "Failed to create CAR. " + car1.ErrorMessage End IfEnd Sub

Example 5-12 shows how to create a CAR by specifying the CAR subclass name.

Example 5-12: Creating A CAR By Specifying The Subclass Name

Public Sub CreateCAR() { 'Declare variables Dim b As Boolean Dim vSubClassName As Variant Dim car1 As AgileAPI.Change Dim strSubClassName As String Dim strCARNum As String

'Initialize variables Set car1 = new AgileAPI.Change vSubClassName = "CAR" strCARNum = "QCR00001"

b = car1.Create(server, vSubClassName, strCARNum) If Not b Then

5-13


MsgBox "Failed to create CAR. " + car1.ErrorMessage End IfEnd Sub

Assigning a CAR

To assign a CAR to a Quality Administrator, you set the value for the Cover Page | Quality Administrator field. This is similar to the way you assign a problem report or issue. The only distinction is that CARs are assigned to a Quality Administrator and problem reports and issues are assigned to a Quality Analyst. The value for the Quality Administrator field must be a Collection object containing one ListElement or String, as shown in Example 5-13.

Example 5-13: Assigning A CAR

Public Sub AssignCAR(car As AgileAPI.Change) 'Declare variables Dim b As Boolean Dim l As Long Dim attr As AgileAPI.Attribute Dim col As AgileAPI.Collection Dim listVal As AgileAPI.ListElement Dim nClassID As Integer Dim vCol As Variant Dim vAttrID As Variant

'Initialize variables nClassID = car.SubClass.ClassID vAttrID = aidQualityChangeRequests_CoverPage_QualityAdministrator

'Get the first user in the list for the Quality Administrator field Set attr = server.GetAttribute(nClassID, vAttrID) Set col = attr.ListElements Set listVal = col.Get(0)

'Get the current value of the Quality Administrator field b = car.GetValue(vAttrID, vCol) 'Clear the collection b = vCol.Clear 'Add the list element to vCol l = vCol.Add(listVal, -1) 'Set the value of the Quality Administrator field b = car.SetValue(vAttrID, vCol)



If Not b Then MsgBox "Failed to set value. " + car.ErrorMessage End IfEnd Sub

CAR Tabs

Table 5-3 lists the tabs that each CAR can have:

Note Cover Page, Page Two, and Page Three tabs are single-row tables whose fields can be accessed directly without using DataObject::GetTable.

Saving a CAR as an ECO

You can use the DataObject::SaveAs method to save a CAR as another CAR or as an ECO. When you save a CAR as an ECO, the items affected by the CAR are not automatically transferred to the Affected Items tab of the ECO. If you want to transfer affected items from the CAR to the ECO, you must write the code in your program to provide that functionality.

Note If you try to save a CAR to a subclass other than CAR or ECO, the method fails.

Example 5-14: Saving A CAR As An ECO

Public Sub SaveCARAsECO(server As AgileAPI.server)

Table 5-3: CAR Tabs


Cover Page ttChangePage1 Read/Write

Page Two ttChangePage2 Read/Write

Page Three ttChangePage3 Read/Write

Affected Items ttChangeAffectedItems Read/Write

ttChangeRelatedItems Read-only

PSR And Changes ttChangeRelatedPSR Read/Write

ttChangeRelatedChanges Read/Write

Signoff ttChangeSignoff Read/Write

Attachments ttChangeFiles Read/Write

History ttChangeHistory Read-only

5-15


'Declare variablesDim b As BooleanDim vItemNum As VariantDim vCARNum As VariantDim vECONum As VariantDim car As AgileAPI.ChangeDim eco As AgileAPI.ChangeDim carItemRow As AgileAPI.rowDim ecoItemRow As AgileAPI.rowDim carItems As AgileAPI.TableDim ecoItems As AgileAPI.Table

'Initialize variablesvCARNum = "QCR00001"vECONum = "C00006"Set car = New AgileAPI.ChangeSet eco = New AgileAPI.Change

'Load an exiting CAR from the serverb = car.LoadByAttr(server, 0, vCARNum)

'Save the CAR as an ECOb = car.SaveAs(server.SubClasses.Find("ECO"), CStr(vECONum))If Not b Then MsgBox "Unable to save. " + car.ErrorMessage Exit SubEnd If

'Load the new ECOb = eco.LoadByAttr(server, 0, vECONum)If Not b Then MsgBox "Unable to load ECO. " + eco.ErrorMessage Exit SubEnd If

'Retrieve the Affected Items table for the ECOSet ecoItems = eco.GetTable(ttChangeAffectedItems)

'Copy the affected items from the CAR to'the Affected Items tab of the ECOSet carItems = car.GetTable(ttChangeAffectedItems)If carItems.RowCount <> 0 Then For i = 0 To carItems.RowCount - 1 'Get an affected item from the CAR



Set carItemRow = carItems.Rows.Get(i) b = carItemRow.GetValue(aidQualityChangeRequests_AffectedItems_ ItemNumber, vItemNum) 'Add a row to the Affected Items table of the ECO Set ecoItemRow = ecoItems.AddRow 'Set the Item Number field for the row b = ecoItemRow.SetValue(aidChangeOrders_AffectedItems_ ItemNumber, vItemNum) Next iEnd If

'Copy the related items from the CAR to'the Affected Items tab of the ECOSet carItems = car.GetTable(ttChangeRelatedItems)If carItems.RowCount <> 0 Then For i = 0 To carItems.RowCount - 1 'Get a related item from the CAR Set carItemRow = carItems.Rows.Get(i) b = carItemRow.GetValue(aidQualityChangeRequests_RelatedItems_ItemNumber, vItemNum) 'Add a row to the Affected Items table of the ECO Set ecoItemRow = ecoItems.AddRow 'Set the Item Number field for the row b = ecoItemRow.SetValue(aidChangeOrders_AffectedItems_ ItemNumber, vItemNum) Next iEnd If

'Save the ECOb = eco.SaveIf Not b Then MsgBox "Unable to save ECO. " + eco.ErrorMessageEnd If

End Sub

5-17


Using Workflow Features with Problem Reports, Issues, and CARsProblem Reports, Issues, and CARs derive all workflow functionality from the RouteObject class, which is a superclass of both Change and ServiceRequest. Table 5-4 lists the workflow commands you can use for Agile objects.

Selecting a Workflow

When you create a new ServiceRequest or Change (including a CAR), you must select a workflow. Your Agile system can have multiple workflows defined for each type of Product Service Request. To retrieve the valid workflow IDs for an object, use RouteObject::GetWorkflowIDs. If a ServiceRequest or Change has not been assigned a workflow ID yet, you can use RouteObject::SetWorkflowID to select a workflow, as shown in Example 5-15.

Example 5-15: Selecting A Workflow

Private Sub cmdCreatePR_Click() 'Declare variables Dim b As Boolean Dim pr As AgileAPI.ServiceRequest Dim colWFIDs As AgileAPI.Collection

'Initialize variables Set pr = new AgileAPI.ServiceRequest Set colWFIDs = new AgileAPI.Collection

Table 5-4: Product Quality Workflow Features


Audit a Problem Report, Issue, or CAR RouteObject::Audit

Change the status of a Problem Report, Issue, or CAR


Send a Problem Report, Issue, or CAR DataObject::Send

Approve a Problem Report, Issue, or CAR RouteObject::Approve

Reject a Problem Report, Issue, or CAR RouteObject::Reject

Comment on a Problem Report, Issue, or CAR

RouteObject::Comment

Add or remove approvers for a Problem Report, Issue, or CAR




'Create a Problem Report b = pr.Create(server, "ProblemReport", txtNumber.Text)

'Get the Collection of possible workflow IDs b = pr.GetWorkflowIDs(True, colWFIDs)

'Set the workflow ID b = pr.SetWorkflowID(colWFIDs.Get(0)) If Not b Then MsgBox "Unable to set workflow ID. " + pr.ErrorMessage End IfEnd Sub

Auditing

Example 5-16 shows how to audit a ServiceRequest object (either a Problem Report or Issue) and display the audit results in the text area of a dialog box:

Example 5-16: Auditing A ServiceRequest

'Audit the present status of the ServiceRequestPrivate Sub cmdAudit_Click(sr As AgileAPI.ServiceRequest) 'Declare variables Dim col As AgileAPI.Collection Dim nStatusID As Integer

'Initialize variables Set col = new AgileAPI.Collection nStatusID = sr.StatusID

'Audit the present status b = sr.Audit(nStatusID, False, col) If b Then ShowAuditResults(col) Else MsgBox "Failed to audit. " + sr.ErrorMessage End IfEnd Sub

'Audit the release of the Service RequestPrivate Sub AuditRelease(sr As AgileAPI.ServiceRequest) 'Declare variables Dim col As AgileAPI.Collection Dim nStatusID As Integer

5-19


'Initialize variables Set col = new AgileAPI.Collection nStatusID = sr.StatusID

'Audit the release b = sr.Audit(nStatusID, true, col) If b Then ShowAuditResults(col) Else MsgBox "Failed to audit. " + sr.ErrorMessage End IfEnd Sub

Public showAuditResults(col As AgileAPI.Collection) Dim strResult As String 'Clear Audit Results list frmAuditResults.lvwAuditResults.ListItems.Clear 'Populate the Audit Results list For i = 0 To col.Count - 1 strResult = col.Get(i) Set li = lvwAuditResults.ListItems.Add(, , strResult) Next i 'Show the Audit Results dialog frmAuditResults.ShowEnd Sub

Working with the Related PSR TableThe Related PSR tab displays a table of related objects. Each row in the table represents a related ServiceRequest object. Customers, Issues, and CARs all have a Related PSR table. For Customers, the Related PSR table is read-only. For Issues and CARS, you can modify the Related PSR by adding and removing rows.

Example 5-17: Creating A CAR And Adding A Row To The Related PSR Table

Public Sub CreateCAR() 'Declare variables Dim b As Boolean Dim vSubClassName As Variant Dim strCARNum As String Dim vIssueNum As Variant Dim car1 As AgileAPI.Change Dim psrTable As AgileAPI.Table Dim psrRow As AgileAPI.Row



'Initialize variables Set car1 = new AgileAPI.Change vSubClassName = "CAR" strCARNum = "QCR00012" vIssueNum = "ISSUE00002"

'Create a CAR b = car1.Create(server, vSubClassName, strCARNum) If Not b Then MsgBox "Unable to create CAR. " + car1.ErrorMessage Exit Sub End If

'Retrieve the Related PSRs table Set psrTable = car1.GetTable(ttChangeRelatedPSR)

'Add a new empty row to the table Set psrRow = psrTable.AddRow

'Set the PSR Number field for the row b = psrRow.SetValue(aidQualityChangeRequests_RelatedPSR_PSRNumber, vIssueNum) If Not b Then MsgBox "Unable to set value. " + psrRow.ErrorMessage Exit Sub End If

'Save the CAR b = car1.Save If Not b Then MsgBox "Unable to save CAR. " + car1.ErrorMessage End IfEnd Sub

5-21



CHAPTER 6Agile Advantage API

Reference

Agile Advantage API Class LibraryThe Agile Advantage API class library offers the object classes listed in Table 6-1.

This chapter provides developer documentation for the Agile Advantage API. It contains the following topics:❑ Agile Advantage API Class Library❑

Table 6-1: Agile Advantage API Class Library

Class Object Description

ActivityQuery A query used to generate an activity report

ApprovedMfr A row in the Manufacturers table

ApprovedMfrs Manufacturers table

Attachment Attached file or image listed on the Attachments table

Attachments Attachments table

Attribute Provides detailed information about a particular data member in an object

Base Base class of all Agile API objects

BOMComponent A row in a Bill of Material (BOM) table

BOMComponents Bill of Material (BOM) table

CCBQuery A query used to generate CCB reports

6-1


Change A Change in the product change control process

Collection An ordered array of items

CriteriaBag A Reusable Criteria object that is used with Agile workflows

Customer A customer that purchases your company's products and provides feedback on quality issues.

DataObject Any object in the Agile system that holds tables of data

Field Value of a data member, which is equivalent to a single data cell in a tabbed window in Agile CM or Agile wCM

Folder A folder in Agile CM and Agile wCM

Item An Item in the product change control process

ListElement An element in a List field

Mfr Manufacturer

MfrPart Manufacturer Part

Node A node in the Agile Administrator tree

ObjectInfo Provides a record that uniquely identifies an Agile API object

Package A collection of data describing a proposed product

PrintOption Report header and footer options

Property A row in the Agile Administrator property view

Query A query object, or Search

RouteObject An object that can be routed to other users

Row A row in an Agile table

Server Agile eHub and Agile iFS servers

ServiceRequest A product service request (PSR), which is a reported problem, defect, or issue for a particular part.

SubClass Class definition used to identify the category to which an object belongs

Supplier Vendor that supplies manufacturer parts

SyncOption Specifies the attributes that you want redlined when using other Agile API functions, such as Item::SyncBOM

Tab A special kind of node in Agile Administrator that holds a collection of attributes

Table Table containing an array of rows

User Agile user

Table 6-1: Agile Advantage API Class Library

Class Object Description

6-2 Developer Guide

Chapter 6 Agile Advantage API Reference – ActivityQuery

ActivityQueryOverview

A query used to generate an activity report in the Agile Advantage Windows client. The two activity reports included with the Agile Advantage Windows client are Item Activity and Change Activity.

ActivityQuery is an externally creatable object. However, when you use the constructor to create an ActivityQuery in your program, it is an empty object that is not associated with an Agile Advantage eHub. Use ActivityQuery::Create to initialize the object to a specific Agile Advantage eHub.

An ActivityQuery is a temporary query used to generate a report. Unlike a Query object, you cannot save an ActivityQuery.

Hierarchy

❑ Base ❑ ActivityQuery

Properties

Table 6-2: ActivityQuery Properties

Name Type Mode Description

FromDate DATE Read/Write Sets or gets the start date and time used for the activity report.

ItemCount LONG Read-only Gets the number of items returned by the activity report.

MissingCount LONG Read-only Returns the number of items missing from the activity report due to the user’s lack of Discovery privilege for those rows.

States LPDISPATCH Read-only Returns the Collection of available state changes to select from for the report.

Note: For Change Activity reports, use SetWorkflowID to select a workflow before retrieving states.

ToDate DATE Read/Write Sets or gets the end date and time used for the activity report.

Type LONG Read-only Returns the type of activity report, either aqtItem or aqtChange.

6-3


Methods

Create

Execute

GetItemInfo

GetItemNumber

GetItemRevision

GetTargetStates

GetWorkflowID

SetTargetStates

SetWorkflowID

ActivityQuery::Create()

Syntax

BOOL Create(LPDISPATCH server,long type)

Description

Creates a new activity query, which is equivalent to one of the Activity Reports in Agile CM.

Parameters

server

a pointer to a Server object used to initialize the new ActivityQuery

type

type of ActivityQuery to create; valid types are aqtItem and aqtChange; see “ActivityQuery Type Constants” on page 6-261

Returns

Nonzero if the method was successful; 0 otherwise.

Example

Public server As AgileAPI.ServerPublic aquery As AgileAPI.ActivityQuery

Private Sub createActQuery(server As Object)

Dim b As Boolean

6-4 Developer Guide


Set aquery = CreateObject("AgileAPI.ActivityQuery") b = aquery.Create(server, aqtItem) If Not b Then MsgBox “Unable to create Activity Query. “ + aquery.ErrorMessage End If

End Sub

ActivityQuery::Execute()

Syntax

BOOL Execute()

Description

Runs the query and generates the activity report. Execute does not create a collection of query results. To get the ActivityQuery report data, follow these steps:

1 After running ActivityQuery::Execute, use ActivityQuery::ItemCount to determine how many items are in the report.

2 Use ActivityQuery::GetItemInfo or ActivityQuery::GetItemNumber to get information about each report item.

3 Load each report item. For Items, you can use Item::LoadByInfo or Item::LoadByAttr. For Changes, you can use Change::LoadByInfo or Change::LoadByAttr. You can also use Server::GetObject.

4 Use Row::GetValue to get the field values for each Item or Change.

Returns

Nonzero if the query executes successfully; 0 otherwise.

Example

Public aquery As AgileAPI.ActivityQuery

Public Sub RunQuery()

Dim b As Boolean

' SetFromDate - call a subroutine to set the From date ' SetToDate - call a subroutine to set the To date

' Run the query b = aquery.Execute If Not b Then

6-5


MsgBox aquery.ErrorMessage Exit Sub End If

If aquery.ItemCount = 0 Then MsgBox "The query returns no results. “ + _ “Change the query and run it again." Else PopulateResults End If

End Sub

ActivityQuery::GetItemInfo()

Syntax

BOOL GetItemInfo(long index,LPDISPATCH info)

Description

Retrieves information that uniquely identifies an item in the activity query. The information is stored in an ObjectInfo object, and it includes the class ID, subclass ID, target ID, and target type.

Parameters

index

index of the item

info

an output parameter that returns the ObjectInfo for the specified item. info must point to an existing ObjectInfo object; it cannot be Null.

Returns


Example


Public Sub PopulateResults()

Dim info As AgileAPI.ObjectInfo Dim i As Long Dim obj As Object

6-6 Developer Guide


Dim b As Boolean

Set info = CreateObject("AgileAPI.ObjectInfo") For i = 0 To aquery.ItemCount - 1 b = aquery.GetItemInfo(i, info) If Not b Then MsgBox aquery.ErrorMessage frmResults.lvwResults.ListItems.Clear Exit Sub Else Set obj = server.GetObject(info) If obj Is Nothing Then MsgBox "Unable to load object. " + server.ErrorMessage frmResults.lvwResults.ListItems.Clear Exit Sub End If End If

'Code for getting values for each object goes here.

Next i

End Sub

ActivityQuery::GetItemNumber()

Syntax

BSTR GetItemNumber(long index)

Description

Returns a string with the unique number for a specified item in the activity report.

Parameters

index

index number of the item in the activity report

Returns

The number of the item; depending on the type of activity report, this could be an Item number or a Change number.

6-7


Example



Dim i As Long Dim obj As Object Dim b As Boolean Dim num As String

frmResults.lvwResults.ListItems.Clear For i = 0 To aquery.ItemCount - 1 If aquery.Type = aqtItem Then num = aquery.GetItemNumber(i) Set obj = CreateObject("AgileAPI.Item") b = obj.LoadByAttr(server, 0, num) 'Code for getting values for each object goes here. Else num = aquery.GetItemNumber(i) Set obj = CreateObject("AgileAPI.Change") b = obj.LoadByAttr(server, 0, num) 'Code for getting values for each object goes here. End If Next i

End Sub

ActivityQuery::GetItemRevision()

Syntax

BSTR GetItemRevision(long index)

Description

Returns the revision of a specified item in an Item Activity report.

Parameters

index

index number of the item to check

Returns

A string containing the item revision.

6-8 Developer Guide


Example


Public GetRevs(aquery As Object)

Dim i As Long Dim strRev As String

For i = 0 To aquery.ItemCount - 1 strRev = aquery.GetItemRevision(i) MsgBox "Revision of item " + CStr(i) ": " + strRev Next i

End Sub

ActivityQuery::GetTargetStates()

Syntax

BOOL GetTargetStates(LPDISPATCH states)

Description

Retrieves the target state changes used for the activity report.

Parameters

states

a Collection containing target state changes for the report

Returns


Example

Public aquery As AgileAPi.ActivityQueryPublic colStates AgileAPI.CollectionPublic colTargetStates As AgileAPI.Collection

Public Sub SetStates()

Dim b As Boolean Dim i As Long

Set colStates = aquery.States

b = aquery.GetTargetStates(colTargetStates)

6-9


If b Then b = colTargetStates.Clear For i = 0 To lstSelections.ListCount - 1 colTargetStates.Add colStates.Find(lstSelections.List(i)), -1 Next i b = aquery.SetTargetStates(colTargetStates) If Not b Then MsgBox aquery.ErrorMessage End If End If

End Sub

ActivityQuery::GetWorkflowID()

Syntax

long GetWorkflowID()

Description

Retrieves the current workflow ID for a Change Activity report. The ActivityQuery object must be of type aqtChange to get the workflow ID.

Returns

The workflow ID number.

ActivityQuery::SetTargetStates()

Syntax

BOOL SetTargetStates(LPDISPATCH states)

Description

Sets the target state changes to use to generate the activity report.

Parameters

states

a Collection containing target state changes for the report

Returns


Example

See “ActivityQuery::GetTargetStates()” on page 6-9.



ActivityQuery::SetWorkflowID()

Syntax

BOOL SetWorkflowID(long newWorkflowID)

Description

Specifies the workflow ID for a Change Activity report. The ActivityQuery object must be of type aqtChange to set the workflow ID.

Parameters

newWorkflowID

workflow ID number. To select all workflows, type 0. You can use the Agile Administrator API to retrieve the list of valid workflow IDs. For more information, see “RouteObject::SetWorkflowID()” on page 6-190.

Returns


6-11


ApprovedMfrOverview

A row in a Manufacturers table (the ApprovedMfrs object) for an Item. You can use ApprovedMfr to change the Manufacturer Part.

Hierarchy

❑ Base❑ Row

❑ ApprovedMfr

Methods

SetMfrPart

ApprovedMfr::SetMfrPart()

Syntax

BOOL SetMfrPart( LPDISPATCH mfrPart)

Description

Sets the Manufacturer Part for a Manufacturer that appears on an Approved Manufacturers List.

To set the Manufacturer Part:

1 Create a new MfrPart object in your program.

2 Use MfrPart::LoadByAttr or MfrPart::LoadByInfo to load the MfrPart object you want to set.

3 Use ApprovedMfr::SetMfrPart to set a MfrPart object for the Approved Manufacturers List.

Parameters

mfrPart

object representing a Manufacturer Part

Returns



Chapter 6 Agile Advantage API Reference – ApprovedMfr

Example

Public server As AgileAPI.ServerPublic mfrPart As AgileAPI.MfrPart

Sub SetMfrPart(approvedMfr As Object)

Dim b As Boolean

b = mfrPart.LoadByAttr(server, 0, txtMfrName + "::" + txtPartNumber) If Not b Then MsgBox "Failed to get MfrPart. " + mfrPart.ErrorMessage Exit Sub Else If Not approvedMfr.SetMfrPart(mfrPart) Then MsgBox "Failed to get MfrPart. " + approvedMfr.ErrorMessage End If End If

End Sub

6-13


ApprovedMfrsOverview

The Manufacturers table, also called the Approved Manufacturers List (AML), for an Item. Each row of the table is an ApprovedMfr object. You can use the AML to find which manufacturers are producing a particular Part, their identification information for that Part, where that Part is used, and contact information for the Manufacturer.

Hierarchy

❑ Base❑ Table

❑ ApprovedMfrs

Methods

AddRow

ApprovedMfrs::AddRow()

Syntax

LPDISPATCH AddRow( LPDISPATCH mfrPart)

Description

Adds a Manufacturer Part to an Approved Manufacturers List.

Parameters

mfrPart

object representing a Manufacturer Part

Returns

A pointer to the ApprovedMfr object if the method was successful; Null otherwise.

Example

Private Sub AddAML(aml As Object)

Dim approvedMfr As AgileAPI.ApprovedMfr Dim mfrPart As AgileAPI.MfrPart Dim b As Boolean

Set mfrPart = CreateObject("AgileAPI.MfrPart") b = mfrPart.LoadByAttr(server, 0, txtMfrName + "::" + txtPartNumber)


Chapter 6 Agile Advantage API Reference – ApprovedMfrs

If Not b Then MsgBox "Failed to load MfrPart. " + mfrPart.ErrorMessage Exit Sub Else Set approvedMfr = aml.AddRow(mfrPart) Call AddItem(approvedMfr, Tree.SelectedItem) End If

End Sub

6-15


AttachmentOverview

An attached file listed on the Attachments table. Provides read/write access to attachment properties, allowing you to add a file, check in and check out a file, get a file, and cancel a checkout.

An attachment can be any type of file, including a drawing, scanned image, document, or a compressed file. Each attachment can consist of multiple files.

Hierarchy

❑ Base ❑ Row

❑ Attachment

Properties

Table 6-3: Attachment properties


FileCount LONG Read-only Returns the total number of files contained within an attachment.

IsImage BOOL Read-only Returns nonzero if the attachment is an image; otherwise, it returns 0. The Agile Advantage API treats all attachments as images. This does not imply anything about the file format of attachments. An attachment can be any type of file.

IsSecure BOOL Read-only Returns nonzero if the attachment has been uploaded to the Agile Advantage iFS; otherwise, it returns 0. An attachment that is not stored on the Agile Advantage iFS is just a reference to its actual location.

Note: Agile Advantage iFS does not validate URLs for unsecured attachments.


Chapter 6 Agile Advantage API Reference – Attachment

Methods

AddFile

CancelCheckOut

CheckIn

CheckOut

DeleteVersion

GetCurrentVersion

GetFile

GetFileID

GetPrintOption

GetVersionInfo

GetVersions

PrintFile

SetCurrentVersion

VbsGetVersionInfo

Attachment::AddFile()

Syntax

BOOL AddFile( LPCTSTR file)

Description

Adds another file to the selected attachment, allowing you to create a multifile attachment.

Note To add a new attachment to the Attachments table, use Attachments::AddRow.

Parameters

file

path and filename of the file to add (256 characters maximum)

Returns

Nonzero if the method is successful; 0 otherwise.

6-17


Example

Private Sub AddImageFile(Attachment As AgileAPI.Attachment)

‘Display the File dialog frmFile.Show 1, Me If frmFile.OK Then

If Not Attachment.AddFile(frmFile.txtFilename.Text) Then MsgBox "Failed to add file. " + Attachment.ErrorMessage End If End If

End Sub

Attachment::CancelCheckOut()

Syntax

BOOL CancelCheckOut()

Description

Cancels checkout for the selected file without checking in changes. This allows other users to check out and modify the file.

Returns


Example

Private Sub CancelCheckout(Attachment As Object)

If Not Attachment.CancelCheckOut Then MsgBox "Failed to cancel checkout. " + Attachment.ErrorMessage End If

End Sub

Attachment::CheckIn()

Syntax

BOOL CheckIn()

Description

Checks in all checked out files contained in the Attachment object.



Returns


Example

Private Sub CheckInAttachment(Attachment As Object)

If Not Attachment.CheckIn Then MsgBox "Failed to check in attachment. " + Attachment.ErrorMessage End If End Sub

Attachment::CheckOut()

Syntax

BOOL CheckOut( LPCTSTR folder)

Description

Checks out all files contained in the Attachment object and makes a copy of the files in the specified folder.

Parameters

folder

full path of the folder to copy the file (256 characters maximum); the folder must exist or checkout fails

Note If the selected file is not secured in the Agile iFS vault, CheckOut returns an “Invalid Operation” error.

Returns


Example

Private Sub CheckOutAttachment(Attachment As Object)

' Display the File dialog frmFile.Show 1, Me

If frmFile.OK Then If Not Attachment.CheckOut(frmFile.txtFolder.Text) Then MsgBox "Failed to check out. " + Attachment.ErrorMessage End If

6-19


End If

End Sub

Attachment::DeleteVersion()

Syntax

BOOL DeleteVersion()

Description

Deletes the latest file version. If the current file version isn’t the latest, DeleteVersion fails.

Returns


Attachment::GetCurrentVersion()

Syntax

long GetCurrentVersion()

Description

Retrieves the attachment’s current version number.

Returns

The attachment’s current version number.

Attachment::GetFile()

Syntax

BOOL GetFile( LONG index,LPCTSTR file)

Description

Makes a copy of the selected file contained in the Attachment object.

Parameters

index

index number for a file contained in a multifile attachment. For single-file attachments, specify 0. For multifile attachments, specify the index number of the file to copy. GetFile can copy only one file at a time.



file

the path and filename to copy the selected file (260 characters maximum); the folder you specify must already exist. Otherwise, GetFile fails.

Note If the selected file is not secured in the Agile Advantage iFS vault, GetFile returns an “Invalid Operation” error.

Returns


Example

Sub GetAttachment(Attachment As Object)

' Display the File dialog frmFile.Show 1, Me

If frmFile.OK Then If Not Attachment.GetFile(0, frmFile.txtFilename.Text) Then MsgBox "Failed to get the file. " + Attachment.ErrorMessage End If End If

End Sub

Attachment::GetFileID()

Syntax

long GetFileID(long index)

Description

Returns the ID number of the selected file.

Note This Agile Advantage API method was designed to be used internally by other Agile Advantage products. Currently, the Agile Advantage API does not provide public methods that require the file ID as one of its parameters. For example, there is not a public method that lets you get a file from the Agile Advantage iFS by specifying the file ID.

Parameters

index

index number for a multifile attachment. For singe-file attachments, specify 0.

6-21


Returns

The ID number of a file; 0 if there is an error.

Attachment::GetPrintOption()

Syntax

BOOL GetPrintOption(int index,LPDISPATCH option)

Description

Retrieves the PrintOption settings for the specified file. The PrintOption object has properties that set the strings used for headers and footers in printed output.

Parameters

index

the specified file to print. The index can be from 0 to Attachment::FileCount - 1. If the specified index is out of range, GetPrintOption fails.

option

a PrintOption object that you created; GetPrintOption fills the specified PrintOption object with header and footer settings

Returns


Example

Dim po As AgileAPI.PrintOption

'Create the PrintOption object Set po = CreateObject("AgileAPI.PrintOption")

'Get the PrintOption settings from the Agile eHub If Not obj.GetPrintOption(txtIndex.Text, po) Then MsgBox "Unable to get PrintOption. " + obj.ErrorMessage End if

Attachment::GetVersionInfo()

Syntax

BOOL GetVersionInfo(LPDISPATCH fileSizes, BSTR FAR* lastViewDate, BSTR FAR* createDate)



Description

Returns several output parameters with information about the attachment’s versions.

Parameters

fileSizes

an output parameter that returns a Collection containing the file sizes for all versions of the attachment. fileSizes must reference an existing Collection object

lastViewDate

an output parameter that returns a string representing the date the attachment version was last viewed

createDate

an output parameter that returns a string representing the date the attachment version was created

Returns


Attachment::GetVersions()

Syntax

BOOL GetVersions(LPDISPATCH versionNumbers)

Description

Retrieves the Collection of version numbers for the attachment.

Parameters

versionNumbers

an output parameter that returns a Collection containing the attachment’s version numbers. versionNumbers must reference an existing Collection object.

Returns


6-23


Attachment::PrintFile()

Syntax

BOOL PrintFile(int index,LPDISPATCH option)

Description

Prints an attachment using the specified PrintOption settings for headers and footers.

To support printing attachments from an Agile Advantage API program, the Agile Advantage Windows client must be installed on the client computer. Also, the Path System Variable for Windows must include the path for the Agile Advantage Windows client.

Parameters

index

the specified file to print. The index can be from 0 to Attachment::FileCount - 1. If the specified index is out of range, PrintFile fails.

option

the PrintOption object for header and footer settings. If you specify a Null PrintOption object, the default settings are used.

Returns


Example

Private Sub Attachment_PrintFile_Click()

Set obj = Tree.SelectedItem.Tag frmIndex.Show 1, Me

Dim po As AgileAPI.PrintOption

Set po = CreateObject("AgileAPI.PrintOption") b = obj.GetPrintOption(frmIndex.Index, po) po.RightFooter = "Confidential" If Not obj.PrintFile(frmIndex.Index, po) Then MsgBox "Failed to print file. " + obj.ErrorMessage End If

End Sub



Attachment::SetCurrentVersion()

Syntax

BOOL SetCurrentVersion(long version)

Description

Sets the attachment’s current version number. To retrieve all version numbers for the attachment, use Attachment::GetVersions.

Returns


Attachment::VbsGetVersionInfo()

Syntax

BOOL VbsGetVersionInfo(LPDISPATCH fileSizes,VARIANT FAR* lastViewDate,VARIANT FAR* createDate)

Description

A VBScript-supported version of GetVersionInfo that returns several output parameters with information about the attachment's versions.

Parameters

fileSizes

an output parameter that returns a Collection containing the file sizes for all versions of the attachment. fileSizes must reference an existing Collection object

lastViewDate

an output parameter that returns a Variant string representing the date the attachment version was last viewed

createDate

an output parameter that returns a Variant string representing the date the attachment version was created

Returns


6-25


AttachmentsOverview

The Attachments table. Provides a method for adding attachments to the table.

Hierarchy

❑ Base ❑ Table

❑ Attachments

Properties

Methods

AddRow

Attachments::AddRow()

Syntax

LPDISPATCH AddRow( LPCTSTR file,BOOL secure)

Description

Adds a new row to the Attachments table. You can specify the path of a file or a URL for the new attachment. Files referenced in URLs are not uploaded to the Agile iFS.

When the secure parameter equals 0:

❑ The Agile eHub does not verify the specified file name. Instead, it adds the full path or URL to the Agile iFS.

❑ The object added to the Attachments table does not support the following Attachment class member functions: CheckOut and GetFile.

If an Item is incorporated, the Attachments table is read-only. No attachments can be added. To find if an Item is incorporated, use Item::GetIncorporated.

Table 6-4: Attachments properties


IsImage BOOL Read-only Returns whether the Attachments object is an images table or a files table. The Agile API treats all attachments as images. This does not imply anything about the file format of attachments. An attachment can be any type of file.


Chapter 6 Agile Advantage API Reference – Attachments

Attachments::AddRow can be used with any of the following table types (see “Table Type Constants” on page 6-545):

❑ ttCustomerFiles❑ ttItemFiles ❑ ttItemImages ❑ ttChangeFiles ❑ ttChangeImages ❑ ttMfrFiles ❑ ttMfrImages ❑ ttMfrPartFiles ❑ ttMfrPartImages ❑ ttPackageFiles ❑ ttPackageImages ❑ ttServiceRequestFiles ❑ ttSupplierFiles

Note Make sure your program saves the object after adding an attachment. If Attachments::AddRow fails when adding an attachment, all attachments added since the object was last saved are lost.

Parameters

file

path or URL of the file to add (256 characters maximum)

secure

nonzero to secure the content of the file by adding it to the file server; 0 to not upload the file. If file is a URL, secure should be 0.

Returns

A pointer to the Attachment object if the method was successful; Null otherwise.

6-27


Example

Private Sub AddAttachment(obj As Object)

Dim Attachment As AgileAPI.Attachment

Set Attachment = obj.AddRow(frmFile.txtFilename, frmFile.chkSecure) If Attachment Is Nothing Then MsgBox "Failed to add attachment. " + obj.ErrorMessage Exit Sub Else b = obj.Save Call AddToList(Attachment) End If

End Sub


Chapter 6 Agile Advantage API Reference – Attribute

Attribute Overview

An inherent characteristic of an object. An attribute provides detailed information about a particular data member. Each of the main Agile object classes and subclasses that you define in Agile Administrator has several tables containing attributes. When you open an object in Agile CM, a tabbed window appears with fields for recording information. These fields correspond directly to Agile attributes. For lists of attributes for each Agile class, see “” on page 6-261.

Hierarchy

❑ Base ❑ Node

❑ Attribute

Properties

Table 6-5: Attribute properties


DataType DataTypeConstants Read-only Returns the attribute’s data type. See “Data Type Constants” on page 6-333.

BaseID LONG Read-only Returns the attribute’s base ID.

FullName BSTR Read-only Returns the attribute’s fully qualified name. A fully qualified name is a string that includes the tab name and the attribute name separated by a period, for example, “Title Block.Description.”

IsVisible BOOL Read-only Returns a nonzero value if the attribute is visible; otherwise, it returns 0.

ListElements LPDISPATCH Read-only Returns the collection of all possible values for a list field.

Name BSTR Read-only Returns the attribute’s name.

TableName BSTR Read-only Returns the attribute’s table name.

6-29


BaseOverview

Base class of all Agile Advantage API objects. To begin using Agile objects in your application, you must first create an instance of the Server object; see “Server” on page 6-206.

Properties

Table 6-6: Base properties


ErrorCode LONG Read-only Returns the error number for the object’s last failed operation. If a function call fails, ErrorCode is updated with the current error number. If a function call succeeds, ErrorCode clears to 0. For more information, see Chapter 7, “Error Messages.”

ErrorMessage BSTR Read-only Returns the error message for the object’s last failed operation. If a function call fails, ErrorMessage is updated with the current error message. If a function call succeeds, ErrorMessage clears to an empty string. For more information, see Chapter 7, “Error Messages.”

IsDirty BOOL Read/Write Sets or gets whether the object has been modified. A nonzero value indicates that the object has been modified.


Chapter 6 Agile Advantage API Reference – Base

IsInit BOOL Read-only Returns nonzero if the object is initialized by an Agile Advantage API Server object. Otherwise, it returns 0. If you try to access an Agile Advantage object that has not been initialized by an instance of a Server object, the Agile Advantage API returns an error that reads “Object not initialized.”

ObjectID LONG Read-only Returns the object ID for the object on the server.

ObjectType ObjectTypeConstants Read-only Returns the object’s type. For more information, see “Object Type Constants” on page 6-432.

Parent LPDISPATCH Read-only Returns the object’s parent object.

Server LPDISPATCH Read-only Returns the Server object. You can use the Server property to access properties and methods of Server from another object.

Note: You cannot return the Server object from a User object. User::Server always returns Nothing.

Tag VARIANT Read/Write Sets or gets arbitrary values. Use the Tag property to store any arbitrary value you might use in your program. Tag is a Variant type, which means you can use it to store a value or an object.

Table 6-6: Base properties


6-31


Methods

CancelBlockingCall

Compact

DisableError

EnableError

GetObjectInfo

Base::CancelBlockingCall()

Syntax

BOOL CancelBlockingCall()

Description

Cancels an RPC call that is currently being made to the Agile eHub. You can use CancelBlockingCall to stop a query from processing if it is taking too long to return results.

While a query is running, your program is blocked from doing anything else. By using CancelBlockingCall to abort a query in progress, you return control to your program.

Returns


Example

Public Sub CancelQueryCall(Query As Object)

Dim b As Boolean

b = Query.CancelBlockingCall If Not b Then MsgBox "Unable to cancel the query. " + Query.ErrorMessage End If

End Sub



Base::Compact()

Syntax

void Compact()

Description

Compacts the object, freeing up additional memory. Use Compact in your program in situations where memory is critical.

Example

Dim currPart As AgileAPI.Item

'Create a new PartSet currPart = CreateObject("AgileAPI.Item")b = currPart.Create(server, ctItemPart, "P0001")

'Compact the new Part to reduce memory usagecurrPart.Compact

Base::DisableError()

Syntax

BOOL DisableError(LONG code)

Description

Temporarily disables the specified error code. Generally, warning error codes associated with database objects, such as Change, Item, Mfr, MfrPart, Package, Row, SubClass, and Table, can be disabled. By disabling a warning error code, you prevent it from interfering with any Agile Advantage API methods that would trigger the warning.

When you use DisableError to disable a specific warning error code, it remains disabled for the Server instance until you call Base::EnableError to enable it. You can use DisableError(0) to disable all Agile warning error codes. If all warning error codes are disabled, you can call EnableError(0) to enable them again, or use EnableError(code) to enable a particular warning error code.

Parameters

code

number of the warning error code to disable; 0 to disable all warning errors that can be disabled. For a list of error codes, see Chapter 7, “Error Messages.”

6-33


Returns


Example

Sub CancelChange(Change As Object, lCancelID As Long)

b = Change.ChangeStatus(lCancelID, 0, txtComment.Text, _ chkNotifyOrig.Value, chkNotififyCA.Value, chkNotifyCCB.Value, _ txtNotifyList.Text, txtApprovers.Text, txtObservers.Text, 0)If Not b Then If Change.ErrorCode = 208 intResponse = MsgBox("Do you really want to cancel this Change?", _ vbYesNo) If intResponse = vbYes Then b = Change.DisableError(208) b = Change.ChangeStatus(lCancelID, 0, txtComment.Text, _ chkNotifyOrig.Value, chkNotifyCCB.Value, txtNotifyList.Text, _ txtApprovers.Text, txtObservers.Text, 0) b = Change.EnableError(0) Else Exit Sub End If Else MsgBox "Unable to cancel Change. " + Change.ErrorMessage End IfEnd If

End Sub

Base::EnableError()

Syntax

BOOL EnableError(LONG code)

Description

Enables the specified warning error code. By default, all Agile error codes are enabled. If you used DisableError(0) to disable all warning error codes, you can call EnableError(0) to enable them again, or use EnableError(code) to enable a particular warning error code.



Parameters

code

number of the warning error code to enable; 0 to enable all warning errors. For a list of error codes, see Chapter 7, “Error Messages.”

Returns


Example

See “DataObject::Delete()” on page 6-78.

Base::GetObjectInfo()

Syntax

BOOL GetObjectInfo(LPDISPATCH info)

Description

Retrieves information that uniquely identifies the Agile Advantage object, including the class ID, subclass ID, target ID, and target type.

After getting the object information, you can use the returned ObjectInfo object to retrieve the object again.

Parameters

info

an output parameter that returns a pointer to the ObjectInfo for the object. info must point to an existing ObjectInfo object; it cannot be Null.

Returns


Example

Public item As AgileAPI.ItemPublic server As AgileAPI.Server

Private Sub cmdLoadItem_Click()

Dim info As AgileAPI.ObjectInfo Dim vValue As Variant Dim attrID As Long Dim b As Boolean

6-35


Set info = CreateObject("AgileAPI.ObjectInfo") Set item = CreateObject("AgileAPI.Item")

attrID = aidParts_TitleBlock_Number b = item.LoadByAttr(server, attrID, txtNumber.Text) If Not b Then MsgBox item.ErrorMessage, vbExclamation Else item.IsDirty = False attrID = aidParts_TitleBlock_Description item.GetValue(attrID, vValue) item.GetObjectInfo(info) AddToHistoryList(vValue, info) frmMain.Show End If

End Sub


Chapter 6 Agile Advantage API Reference – BOMComponent

BOMComponentOverview

A row in a Bill of Material (BOM) table.

Hierarchy

❑ Base ❑ Row

❑ BOMComponent

Properties

Methods

Expand

BOMComponent::Expand()

Syntax

BOOL Expand(long level,BOOL unique)

Description

Expands subitems of the BOMComponent to the specified level. This is equivalent to double-clicking an assembly in the BOM in the Agile Advantage Windows client. A BOMComponent cannot be expanded if it is identical to the parent Item.

Note After using BOMComponent::Expand, use the Children property to return the updated collection of BOM subitems.

Table 6-7: BOMComponent properties


Children LPDISPATCH Read-only For a multi-level BOM, returns a Collection of subitems contained within the BOM component. If the BOM is not expanded to multiple levels, Children returns an empty Collection.

6-37


Parameters

level

specifies how many levels to expand; type -1 to expand all levels, 0 to collapse the assembly, 1 to expand to the first level, 2 to expand to the second level, and so on.

unique

nonzero to not expand the BOMComponent if it is in the BOM tree; 0 otherwise. Set unique to nonzero to avoid infinite expansion loops for BOMs with circular references.

Returns


Example

Public Sub ExpandBomItem(bomtable As Object, bomitem As Object)

Dim b As Boolean

b = bomitem.Expand(-1, 1) If Not b Then MsgBox "Unable to expand the BOM component. " + bomitem.ErrorMessage End If

bomtable.Refresh UpdateBOMView

End Sub

Public Sub CollapseBomItem(bomtable As Object, bomitem As Object)

Dim b As Boolean

b = bomitem.Expand(0, 1) If Not b Then MsgBox "Unable to collapse the BOM component. " + bomitem.ErrorMessage End If

bomtable.Refresh UpdateBOMView

End Sub


Chapter 6 Agile Advantage API Reference – BOMComponents

BOMComponentsOverview

A Bill of Material (BOM) table, which contains one or more BOMComponent objects. To add a row to the BOM table, use Table::AddRow.

Hierarchy

❑ Base ❑ Table

❑ BOMComponents

Methods

GetEffectivePeriod

SetEffectivePeriod

BOMComponents::GetEffectivePeriod()

Syntax

BOOL GetEffectivePeriod(DATE FAR* startDate,DATE FAR* endDate)

Description

This method is available only for the Effective BOM table for an Item (TableType = ttItemEffectiveBOM); for other types of BOM tables the method fails. It gets the effective period for the Effective BOM table, which shows the list of components that were available during the specified period. You can use GetEffectivePeriod to retrieve the effective period that you set earlier using BOMComponents::SetEffectivePeriod.

Parameters

startDate

an output parameter that returns the start date of the effective period

endDate

an output parameter that returns the end date of the effective period; cannot be earlier than startDate

Returns


6-39


Example

Sub ListEffectiveBOMItems(BOMComponents As Object)

Dim dateStart As Date, dateEnd As Date If BOMComponents.GetEffectivePeriod(dateStart, dateEnd) Then li.SubItems(2) = "(" + CStr(dateStart) + "," + CStr(dateEnd) + ")" Else li.SubItems(2) = "<error>" End IfEnd Sub

BOMComponents::SetEffectivePeriod()

Syntax

BOOL SetEffectivePeriod(DATE startDate,DATE endDate)

Description

This method is available only for the Effective BOM table for an Item (TableType = ttItemEffectiveBOM); for other types of BOM tables the method fails. It sets the effective period for the Effective BOM table, which shows the list of components that were available during the specified period.

Parameters

startDate

start date of the effective period

endDate

end date of the effective period; cannot be earlier than startDate

Note If you change the effective period, use Table::Refresh to refresh the Effective BOM table.

Returns


Example

Sub SetEffectiveBOMPeriod(BOMComponents As Object)

'Set the effective period to the StartDate and EndDate fields If Not BOMComponents.SetEffectivePeriod(frmDateRange.StartDate, _ frmDateRange.EndDate) Then MsgBox "Failed to set effective period. " + BOMComponents.ErrorMessage


Chapter 6 Agile Advantage API Reference – BOMComponents

End If

End Sub

6-41


CCBQueryOverview

A query used to generate CCB reports in the Agile Advantage Windows client. The three CCB reports included with the Agile Advantage Windows client are Change Metrics, Change Cycle Time, and Backlog.

CCBQuery is an externally creatable object. However, when you use the constructor to create a CCBQuery in your program, it is an empty object that is not associated with an Agile Advantage eHub. Use CCBQuery::Create to initialize the object to a specific Agile Advantage eHub.

A CCBQuery is a temporary query used to generate a report. Unlike a Query object, you cannot save a CCBQuery to the Agile Advantage eHub.

Hierarchy

❑ Base❑ CCBQuery

Properties

Table 6-8: CCBQuery properties


Attributes LPDISPATCH Read-only Gets a pointer to a Collection containing Attribute objects (the available output attributes for the report).

ColumnAttribute LONG Read/Write Sets or gets the base ID number for the output attribute. The specified output attribute must be one contained within the Attributes collection.

ColumnCount LONG Read-only Returns the number of columns in the CCB report.

FilterQuery LPDISPATCH Read/Write Sets or gets the ObjectInfo for a query used to filter the CCB report.

FromDate DATE Read/Write Sets or gets the start date and time used for the CCB report.Note: FromDate must be earlier than ToDate.

FromState LONG Read/Write Sets or gets the status ID for the start state of the CCB report.


Chapter 6 Agile Advantage API Reference – CCBQuery

MissingCount LONG Read-only Returns the number of items missing from the CCB report due to the user’s lack of Discovery privilege for those items.

RowCount LONG Read-only Returns the number of rows returned in the CCB report.

States LPDISPATCH Read-only Returns the Collection of available workflow statuses for the report.

Note: Use SetWorkflowID to select a workflow before retrieving workflow statuses.

TimeInterval LONG Read/Write Returns the interval type used for the CCB report. See “CCBQuery Interval Type Constants” on page 6-261.

ToDate DATE Read/Write Sets or gets the end date and time used for the CCB report. Note: ToDate must be later than FromDate.

ToState LONG Read/Write Sets or gets the status ID for the end state of the CCB report.

Type LONG Read-only Returns the type of CCBQuery Type constant, either cqtChangeMetrics, cqtChangeBacklog, or cqtChangeCycleTime. You set the CCBQuery type when you create it. See “CCBQuery Type Constants” on page 6-262.

Table 6-8: CCBQuery properties


6-43


Methods

Create

Execute

GetColumnHeader

GetItemCount

GetItemInfo

GetItemValue

GetRowHeader

GetValue

GetWorkflowID

SetWorkflowID

CCBQuery::Create()

Syntax

BOOL Create(LPDISPATCH server,long type)

Description

Creates a new CCB query, which is equivalent to one of the CCB Reports in the Agile Advantage Windows client.

Parameters

server

a pointer to a Server object used to initialize the new CCBQuery

type

type of CCBQuery to create; valid types are cqtChangeMetrics, cqtChangeBacklog, and cqtChangeCycleTime; see “CCBQuery Type Constants” on page 6-262

Returns


Example

Public Sub CreateCCBQuery()

Dim b As Boolean



If Not ccbquery Is Nothing Then Set ccbquery = Nothing End If

' Create an instance of the CCBQuery object Set ccbquery = CreateObject("AgileAPI.CCBQuery") Select Case frmQueryType.cboType.Text Case "Change Metrics" b = ccbquery.Create(server, cqtChangeMetrics) Case "Change Cycle Time" b = ccbquery.Create(server, cqtChangeCycleTime) Case "Backlog" b = ccbquery.Create(server, cqtChangeBacklog) End Select If Not b Then MsgBox "Unable to create CCBQuery. " + ccbquery.ErrorMessage End If

End Sub

CCBQuery::Execute()

Syntax

BOOL Execute()

Description

Runs the query and generates the CCB report.

Returns

Nonzero if the query executes successfully, 0 otherwise.

Example

Public Sub RunQuery()

Dim b As Boolean SetFromDate SetToDate SetTimeUnit SetFromAndToStates SetOutput SetQuery

' Run the CCB query

6-45


b = ccbquery.Execute If Not b Then MsgBox ccbquery.ErrorMessage Exit Sub End If

If ccbquery.RowCount = 0 Then MsgBox "The query returns no results. " _ + "Change the query and run it again." Else frmMain.Hide frmResults.Show PopulateResults End If

End Sub

CCBQuery::GetColumnHeader()

Syntax

BSTR GetColumnHeader(long column)

Description

Returns the header for the specified column.

Parameters

column

zero-based column number; the first column is 0, the second is 1, and so on

Returns

Column header.

Example

See “CCBQuery::GetValue()” on page 6-50.



CCBQuery::GetItemCount()

Syntax

long GetItemCount(long row,long column)

Description

Returns the number of items referenced in the specified column and row.

Parameters

row

zero-based row number; the first row is 0, the second is 1, and so on

column


Returns

Number of items.

Example

Public info As AgileAPI.ObjectInfoPublic item As AgileAPI.Item

Public Sub GetItems(lRow As Long, lColumn As Long)

Dim itemCount as Long Dim i As Long Dim b As Boolean

Set info = CreateObject("AgileAPI.ObjectInfo") Set item = CreateObject("AgileAPI.Item")

itemCount = ccbQuery.GetItemCount(lRow, lColumn) If itemCount <> 0 Then For i = 0 to itemCount - 1 b = ccbQuery.GetItemInfo(lRow, lColumn, i, info) b = item.LoadByInfo(server, info) GetItemValues(item, lRow, lColumn, i) Next i End If

End Sub

6-47


CCBQuery::GetItemInfo()

Syntax

BOOL GetItemInfo(long row,long column,long index,LPDISPATCH info)

Description

Retrieves information that uniquely identifies an item, such as an ECO, in the CCB query. The information is stored in an ObjectInfo object, and it includes the class ID, subclass ID, target ID, and target type.

Parameters

row


column


index

index number of the item for the number of items in the row; to find the number of items referenced in a cell, use GetItemCount

info

an output parameter that returns the ObjectInfo for the specified item. info must point to an existing ObjectInfo object; it cannot be Null.

Returns


Example

See “CCBQuery::GetItemCount()” on page 6-47.

CCBQuery::GetItemValue()

Syntax

long GetItemValue(long row,long column,



long index,long vt)

Description

Returns the number of days for a specified CCBQuery value type. You can use GetItemValue to return report values that are not equivalent to Agile fields. For example, you can show how many days a Change remained at the current state by specifying the value type cqvtDaysAtCurrentState.

Parameters

row


column


index

index number of the item for the number of items in the row; to find the number of items referenced in a cell, use GetItemCount

vt

CCBQuery Value Type constant (see page 6-262) that identifies the type of value to return

Returns

Number of days for the specified value type.

Example

Public Sub GetValues(item As Object, lRow As Long, _ lColumn As Long, i As Long)

Dim lDays As Long

Select Case ccbquery.Type Case cqtChangeCycleTime lDays = item.GetItemValue(lRow, lColumn, i, cqvtDaysBetweenStates) AddValToReport(lRow, lColumn, lDays) Case cqtChangeBacklog lDays = item.GetItemValue(lRow, lColumn, i, _ cqvtDaysSinceInitialState) AddValToReport(lRow, lColumn, lDays) lDays = item.GetItemValue(lRow, lColumn, i, _

6-49


cqvtDaysAtCurrentState) AddValToReport(lRow, lColumn, lDays) Case cqtChangeMetrics 'Do nothing for ChangeMetrics Exit Sub

End Select

End Sub

CCBQuery::GetRowHeader()

Syntax

BSTR GetRowHeader(long row)

Description

Returns the header for the specified row.

Parameters

row


Returns

Row header.

Example

See “CCBQuery::GetValue()” below.

CCBQuery::GetValue()

Syntax

long GetValue(long row,long column)

Description

Returns the cell value for the specified column and row.

Parameters

row




column


Returns

Value of the cell.

Example

Public ccbquery As AgileAPI.CCBQuery


Dim i As Long Dim colnum As Long Dim rownum As Long

'Clear the grid frmResults.grdResults.Clear frmResults.grdResults.Cols = ccbquery.ColumnCount + 1 frmResults.grdResults.Rows = ccbquery.RowCount + 1

'Add column headers to grid For i = 1 To cquery.ColumnCount frmResults.grdResults.row = 0 frmResults.grdResults.col = i frmResults.grdResults.Text = ccbquery.GetColumnHeader(i - 1) Next i

'Add row headers to grid For i = 1 To cquery.RowCount frmResults.grdResults.row = i frmResults.grdResults.col = 0 frmResults.grdResults.Text = Format(ccbquery.GetRowHeader(i - 1), _ "ddddd") Next i

'Add values to the grid For colnum = 1 To ccbquery.ColumnCount For rownum = 1 To ccbquery.RowCount frmResults.grdResults.row = rownum frmResults.grdResults.col = colnum frmResults.grdResults.Text = ccbquery.GetValue(rownum - 1, colnum - 1) Next rownum Next colnum frmResults.grdResults.Refresh

6-51


End Sub

CCBQuery::GetWorkflowID()

Syntax


Description

Retrieves the current workflow ID for a CCB report.

Returns


CCBQuery::SetWorkflowID()

Syntax


Description

Specifies the workflow ID for a CCB report.

Parameters

newWorkflowID

workflow ID number. To select all workflows, type 0. You can use the Agile Administrator API to retrieve the list of valid workflow IDs. For more information, see “RouteObject::SetWorkflowID()” on page 6-190.

Returns



Chapter 6 Agile Advantage API Reference – Change

ChangeOverview

A Change in the product change control process. To work with a Change object, use methods and properties of DataObject and RouteObject.

Change is an externally creatable object. However, when you use the constructor to create a Change in your program, it is an empty object that is not associated with an Agile Advantage eHub. To work with an existing Change (such as an ECO), you need to use Change::LoadByAttr or Change::LoadByInfo to load a Change from an Agile Advantage eHub. To create a new Change on an Agile Advantage eHub, use Change::Create.

Hierarchy

❑ Base❑ Row

❑ DataObject❑ RouteObject

❑ Change

Methods

Create

LoadByAttr

LoadByInfo

Change::Create()

Syntax

BOOL Create(LPDISPATCH server,const VARIANT FAR& subClass,LPCTSTR number)

Description

Creates a new Change of the specified subclass.

Parameters

server

a pointer to a Server object used to initialize the new Change

6-53


subClass

a SubClass ID or name

number

number of the new Change

Returns


Example

Public server As AgileAPI.ServerPublic currECO As AgileAPI.Change

Private Sub cmdCreateECO_Click()

Dim b As Boolean

Set currECO = CreateObject("AgileAPI.Change") b = currECO.Create(server, "ECO", txtNumber.Text) If Not b Then MsgBox "Failed to create object. " + currECO.ErrorMessage End If

End Sub

Change::LoadByAttr()

Syntax

BOOL LoadByAttr(LPDISPATCH server,const VARIANT FAR& attr,const VARIANT FAR& value)

Description

Loads an existing Change into the object by specifying an attribute (by name or ID) and its value.

Parameters

server

a pointer to a Server object used to initialize the Change



attr

a fully qualified attribute, such as “Cover Page.Description of Change,” or a base ID. You can also type 0 to use the default attribute, “Cover Page.Change Number.” For lists of attributes for each Agile class, see “” on page 6-261.

value

a value for the specified attribute

Returns


Example


Private Sub GetChange_Click()

Dim b As Boolean

Set currECO = CreateObject("AgileAPI.Change") b = currECO.LoadByAttr(server, 0, txtNumber.Text) If Not b Then MsgBox "Failed to get object. " + currECO.ErrorMessage End If

End Sub

Change::LoadByInfo()

Syntax

BOOL LoadByInfo(LPDISPATCH server,LPDISPATCH info)

Description

Loads an existing Change into the object by specifying an ObjectInfo object that uniquely identifies it. The specified ObjectInfo object must have TargetID and TargetType members.

Parameters

server

a pointer to a Server object used to initialize the Change

6-55


info

a pointer to an ObjectInfo object that uniquely identifies the Change

Returns


Example

Public history(1 to 10, 1 to 10) As VariantPublic server As AgileAPI.ServerPublic obj As Object

Private Sub GetObjFromHistory(index As Long)

Dim info As AgileAPI.ObjectInfo Dim b As Boolean

'Get an ObjectInfo object from the history array Set info = history(index, 2)

'Based on the object type, create an object Select Case info.TargetType

Case otChange Set obj = CreateObject("AgileAPI.Change")

Case otItem Set obj = CreateObject("AgileAPI.Item")

Case otMfr Set obj = CreateObject("AgileAPI.Mfr")

Case otMfrPart Set obj = CreateObject("AgileAPI.MfrPart")

Case otPackage Set obj = CreateObject("AgileAPI.Package")

Case otCustomer Set obj = CreateObject("AgileAPI.Customer")

Case otServiceRequest Set obj = CreateObject("AgileAPI.ServiceRequest")

Case otSupplier Set obj = CreateObject("AgileAPI.Supplier")



End Select

'Load the object from the Agile eHub b = obj.LoadByInfo(server, info)

End Sub

6-57


CollectionOverview

An ordered array of items. The Collection can be one of the three types specified in its DataType member. All items in a Collection have the same type. A Collection can contain objects (dtObject) derived from the Base class, integers (dtLong), or strings (dtString).

Collection is an externally creatable object. You can create a new Collection object and add elements to it.

Creating an Instance of the Collection Object

In Visual Basic you can create an instance of the Collection object using the CreateObject function.

' Declare an object variable for the collectionDim SizeValues As Object

' Create a new instance of the collectionSet SizeValues = CreateObject("AgileAPI.Collection")

You can also assign a reference to the Collection object using the New keyword:

' Declare an object variable for the collectionDim SizeValues As Object

' Create a new instance of the collectionSet SizeValues = New AgileAPI.Collection

Setting the Data Type of a Collection

When you create a new Collection, it has no specified data type. You cannot add objects, integers, or strings to a Collection whose data type has not been set. To set the data type of a Collection, use Collection::SetDataType.

If an Agile Advantage API method creates a Collection object for one of its output parameters, the method also internally sets the data type of the Collection; you do not need to use Collection::SetDataType to set its data type.

Hierarchy

❑ Base❑ Collection


Chapter 6 Agile Advantage API Reference – Collection

Properties

Methods

Collection::Add()

Syntax

LONG Add( const VARIANT FAR& value,LONG index)

Description

Adds a new value to the Collection at the specified index number.

Before you can add objects to a Collection, the Collection must have a specified data type. Otherwise, the Add method fails.

Parameters

value

value to add to the collection

index

index number where the new value is added; -1 adds a value to the end of the collection.

Table 6-9: Collection properties


Count LONG Read-only Returns the total number of items in the collection.

DataType DataTypeConstants Read-only Returns the type of items stored in the collection. For a list of data types, see “Data Type Constants” on page 6-333.

IsReadOnly BOOL Read-only Returns a nonzero value if the collection is read-only and cannot be modified. Otherwise, it returns 0.

Add FindIndex

Clear Get

Contains Remove

ContainsKey SetDataType

Find

6-59


Returns

The index number of the new value if the method is successful; -1 otherwise.

Example

Sub AddLifecyclePhase(Query As Object)

Dim colIDs As AgileAPI.Collection, colWidths As AgileAPI.Collection Dim index As Long

If Query.GetResultDisplay(colIDs, colWidths) Then

'Add the Lifecycle Phase column ID colIDs.Add aidParts_TitleBlock_LifecyclePhase, -1

'Set the column width for Lifecycle Phase to 2 inches colWidths.Add 2, -1

'Set the query result display If Not Query.SetResultDisplay(colIDs, colWidths) Then MsgBox "Failed to set the result display. " + Query.ErrorMessage Exit Sub End If

Else MsgBox "Failed to get the result display. " + Query.ErrorMessage End If

End Sub

Collection::Clear()

Syntax

BOOL Clear()

Description

Removes all items from the Collection.

Returns


Example

See “Query::SetResultDisplay()” on page 6-172.



Collection::Contains()

Syntax

BOOL Contains(const VARIANT FAR& value)

Description

Indicates whether a Collection contains the specified object or value.

Parameters

value

an object or value

Returns

Nonzero if the Collection contains the specified object or value; 0 otherwise.

Example

Public Sub CheckIfUserExists(server As Object, strName As String)

'Find whether the specified name is a valid Agile user b = server.Users.Contains(strName) If Not b Then MsgBox "The specified user does not exist." End If

End Sub

Collection::ContainsKey()

Syntax

BOOL ContainsKey(const VARIANT FAR& key)

Description

Indicates whether a Collection contains an item with a particular key. Each Agile object has two keys, a number and a string.

Parameters

key

a key that identifies an Agile Advantage object. Each Agile Advantage object has two keys, a number and a string.

6-61


Returns

Nonzero if the Collection contains the key; 0 otherwise.

Example

Public Sub CheckIfItemOnBOM(BOMComponent As Object, strNumber As String)

'Find whether the specified Item is on the BOM b = BOMComponent.Children.ContainsKey(strNumber) If Not b Then MsgBox "The specified Item is not on the BOM." End If

End Sub

Collection::Find()

Syntax

LPDISPATCH Find(const VARIANT FAR& key)

Description

Searches the Collection for an object using the given key, which could be a number or a string.

Parameters

key

the key to search for. Each Agile Advantage object has two keys, a number and a string. For example, you can find an Attribute or Field by specifying a fully qualified name, such as “Title Block.Description,” or the base ID number. For lists of attributes for each Agile class, see “” on page 6-261.

Returns

A pointer to the object if it is found in the Collection; Null otherwise.

Example

Public Sub CreateNewPart(server As Object, strNumber As String)

Dim subclass As AgileAPI.SubClass Dim part As AgileAPI.Item

'Find the Part subclass Set subclass = server.SubClasses.Find("Part")



'Create a new part Set part = CreateObject("AgileAPI.Item") b = part.Create(server, subclass, strNumber) If Not b Then MsgBox "Unable to create the part. " + part.ErrorMessage End If

End Sub

Collection::FindIndex()

Syntax

LONG FindIndex(const VARIANT FAR& value)

Description

Finds the index of a value contained in the Collection. This method can be used to find object, string, or number values. Use the DataType property to verify that the data type of the Collection.

Parameters

value

value to find in the Collection; the value must correspond to the DataType of the Collection; for example, if DataType equals dtObject, value must be an object reference.

Returns

The index number of the found value; -1 if not found

Example

Sub RemoveLifecyclePhase(Query As Object)

Dim colIDs As AgileAPI.Collection, colWidths As AgileAPI.Collection Dim index As Long

If Query.GetResultDisplay(colIDs, colWidths) Then

'Find the Lifecycle Phase column ID index = colIDs.FindIndex(aidParts_TitleBlock_LifecyclePhase)

'Remove Lifecycle Phase from the collection colIDs.Remove(index) colWidths.Remove(index)

6-63


'Set the query result display If Not Query.SetResultDisplay(colIDs, colWidths) Then MsgBox "Failed to set the result display. " + Query.ErrorMessage Exit Sub End If

Else MsgBox "Failed to get the result display. " + Query.ErrorMessage End IfEnd Sub

Collection::Get()

Syntax

VARIANT Get(LONG index)

Description

Gets a value in the Collection.

Parameters

index

index number for the value to get

Returns

The value at the specified index.

Example

Private Function GetAttribute(ID As Long) As Object

Dim col As AgileAPI.Collection Set col = Query.Attributes

Set GetAttribute = Nothing

For i = 0 To col.count - 1 If ID = col.Get(i).ID Then Set GetAttribute = col.Get(i) Exit For End If Next i

End Function



Collection::Remove()

Syntax

BOOL Remove(LONG index)

Description

Removes the value at the specified position, then decrements the Collection::Count property by 1. The remaining values in the collection are reindexed.

Parameters

index

index number for the value to remove

Returns


Example

See “Collection::FindIndex()” on page 6-63.

Collection::SetDataType()

Syntax

BOOL SetDataType(DataTypeConstants dt)

Description

Sets the data type of a Collection object that you create.

Parameters

dt

data type. For a list of valid data type constants, see “Data type constants” on page 6-333.

Returns


Example

Dim SizeValues As AgileAPI.Collection

‘Create a new collectionSet SizeValues = CreateObject("AgileAPI.Collection")If SizeValues Is Nothing Then

6-65


MsgBox "Unable to create collection. " + server.ErrorMessage Exit SubEnd If

‘Set the data type of the SizeValues collectionSizeValues.SetDataType dtString

‘Add values to the collectionSizeValues.Add "Small", -1SizeValues.Add "Medium", -1SizeValues.Add "Large", -1


Chapter 6 Agile Advantage API Reference – CriteriaBag

e-

CriteriaBag Overview

A Reusable Criteria object that is used with Agile workflows. The CriteriaBag object is equivalent to the criteria specified for each of the Reusable Criteria that appear in the Criteria Library node in Agile Administrator. By specifying a list of Reusable Criteria, you limit which Changes or Packages can use a specific workflow.

The CriteriaBag object is similar to a Query. It uses many of the same Query attributes, relational operators, and logical operators to define the criteria.

To work with a CriteriaBag object, use Property::GetValue to return the value for a Reusable Criteria node.

The CriteriaBag object is currently read-only. You cannot use the Agile API to define new Reusable Criteria for workflows.

Hierarchy

❑ Base❑ CriteriaBag

Properties

Table 6-10: CriteriaBag properties


CriteriaCount long Read-only Returns the total number of search conditions in the CriteriaBag object.

IsCaseSensitive BOOL Read-only Returns whether the Reusable Criteria iscase-sensitive. A case-sensitive search looks for text that is an exact match (uppercase and lowercase letters). Case-sensitive searches can run faster than casinsensitive searches.

6-67


Methods

GetAttributes

GetClass

GetCriteriaData

CriteriaBag::GetAttributes()

Syntax

BOOL GetAttributes(LPDISPATCH ids,LPDISPATCH names)

Description

Returns separate Collection objects containing the available attribute ID numbers and attribute names for the CriteriaBag object.

Parameters

ids

an output parameter that returns a Collection object containing attribute ID numbers. ids must reference an existing Collection object.

names

an output parameter that returns a Collection object containing attribute names. names must reference an existing Collection object

Returns


CriteriaBag::GetClass()

Syntax

long GetClass()

Description

Retrieves the class ID number for the current Reusable Criteria.

Returns

The class ID number for the current Reusable Criteria.


Chapter 6 Agile Advantage API Reference – CriteriaBag

CriteriaBag::GetCriteriaData()

Syntax

BOOL GetCriteriaData(long index,long FAR* attrID,CriteriaBagRelationalOperatorConstants FAR* relOp,BSTR FAR* value,CriteriaBagLogicalOperatorConstants FAR* logicOp,long FAR* leftParen,long FAR* rightParen)

Description

Retrieves the search condition at the specified position.

Parameters

index

index number of the search condition to retrieve. For example, type 0 to retrieve the first search condition.

attrID

an output parameter that returns the base ID of an attribute. For lists of attributes for each Agile class, see “” on page 6-261.

relOp

an output parameter that returns the CriteriaBag relational operator constant used for the search condition

value

an output parameter that returns the value to search for

logicOp

an output parameter that returns the CriteriaBag logical operator constant used for the search condition

leftParen

an output parameter that returns the number of left parentheses before the search condition

rightParen

an output parameter that returns the number of right parentheses before the search condition

6-69


Returns



Chapter 6 Agile Advantage API Reference – Customer

CustomerOverview

A customer that purchases your company's products and provides feedback on quality issues. The Customer object can originate in another system, such as a Customer Relationship Management (CRM) system, and subsequently be imported to the Agile system. If customers experience a problem with a product, they can report the problem by creating a problem report, a type of ServiceRequest.

Customer is an externally creatable object. However, when you use the constructor to create a Customer object in your program, it is an empty object that is not associated with an Agile eHub. To load an existing Customer from an Agile Advantage eHub, use Customer::LoadByAttr or Customer::LoadByInfo. To create a new Customer on an Agile Advantage eHub, use Customer::Create.

Hierarchy

❑ Base❑ Row

❑ DataObject ❑ Customer

Methods

Create

LoadByAttr

LoadByInfo

Customer::Create()

Syntax

BOOL Create(LPDISPATCH server,const VARIANT FAR& subClass,LPCTSTR number,LPCTSTR name,LPCTSTR siteNumber,LPCTSTR siteName)

Description

Creates a new customer using the specified subclass.

The number::siteNumber combination uniquely defines a customer. There is a one-to-one correspondence between customer name and number and between siteName

6-71


and siteNumber. Once you assign a customer name to a customer number, you cannot reuse the name with a different customer number. Similarly, you cannot reuse the same site name with a different site number. The number, name, siteNumber, and siteName fields are case-sensitive. Therefore, “cust0001” is a different customer than “CUST0001”.

Parameters

server

a pointer to a Server object used to initialize the new customer

subClass

a subclass ID or name

number

number of the new customer

name

name of the new customer

siteNumber

site number for the new customer. If the customer does not have a site, enter a null String.

siteName

site name for the new customer. If the customer does not have a site, enter a null String.

Returns



Chapter 6 Agile Advantage API Reference – Customer

Example

Private Sub CreateCustomer(server As AgileAPI.Server)

Dim b As Boolean Dim cust As AgileAPI.Customer

Set cust = CreateObject("AgileAPI.Customer") b = cust.Create(server, "Customer", "CUST00001", "Western Widgets", _ "", "") If Not b Then MsgBox "Failed to create customer. " + cust.ErrorMessage End If

End Sub

Customer::LoadByAttr()

Syntax


Description

Loads an existing customer into the object by specifying an attribute and its value.

Parameters

server

a pointer to a Server object used to initialize the customer

attr

a fully qualified attribute, such as “General Info.Customer Number,” or a base ID. You can also type 0 to use the default attribute, “General Info.Customer Number,” or type an attribute ID constant.

value

a value for the specified attribute. If attr is 0 or “General Info.Customer Number,” the value must consist of a CustomerNumber::SiteID pair. Similarly, if attr is “General Info.Customer Name,” the value must consist of a CustomerName::SiteName pair. If the customer does not have a site specified, the “::SiteID” or “::SiteName” suffix can be omitted.

6-73


Returns


Example

Private Sub LoadCustomer(server As AgileAPI.Server)

Dim b As Boolean Dim cust As AgileAPI.Customer

Set cust = CreateObject("AgileAPI.Customer") b = cust.LoadByAttr(server, 0, "CUST00001") If Not b Then MsgBox "Failed to load customer. " + cust.ErrorMessage End If

End Sub

Customer::LoadByInfo()

Syntax


Description

Loads an existing customer into the object by specifying an ObjectInfo object that uniquely identifies it. The specified ObjectInfo object must have TargetID and TargetType members.

Parameters

server

a pointer to a Server object used to initialize the customer

info

a reference to an ObjectInfo object that uniquely identifies the customer

Returns


Example

See “Change::LoadByInfo()” on page 6-55.


Chapter 6 Agile Advantage API Reference – DataObject

DataObjectOverview

Any Agile Advantage object that holds tables of data. Once you get an object—for example, an Item—from the Server, you can use DataObject::GetTable to fetch a particular table. Item, Mfr, MfrPart, and RouteObject all derive from DataObject.

Hierarchy

❑ Base❑ Row

❑ DataObject

Properties

Methods

DataObject:Abort()

Syntax

BOOL Abort()

Description

Cancels all changes made to the object since it was last saved.

Table 6-11: DataObject properties


IsDeleted BOOL Read-only Returns a nonzero value if the object has been deleted. Otherwise, it returns 0.

IsUpToDate BOOL Read-only Returns a nonzero value if the object has latest data from the Agile Advantage eHub. Otherwise, it returns 0 when the object needs to be refreshed.

SubClass LPDISPATCH Read-only Returns a pointer to the SubClass for the selected object.

Abort Save

CheckValidOperation SaveAs

Delete Send

GetTable Undelete

Refresh

6-75


Returns


Example

Sub AbortDataObject(obj As Object)

'Cancel all changes If Not obj.Abort Then MsgBox "Failed to abort." + obj.ErrorMessage End If

End Sub

DataObject::CheckValidOperation()

Syntax

BOOL CheckValidOperation(long op)

Description

Checks whether the specified row operation is valid. If the operation is invalid, CheckValidOperation returns 0.

Parameters

op

one of the Row operation constants (see page 6-518)

Returns

Nonzero if the operation is valid; 0 otherwise.

Example

Public Sub CheckValidOps(change As Object)

Dim b As Boolean

' Check whether the Submit button should be enabled b = change.CheckValidOperation(roStatusSubmit) If Not b Then cmdSubmit.Enabled = False Else cmdSubmit.Enabled = True End If



' Check whether the Route button should be enabled b = change.CheckValidOperation(roStatusRoute) If Not b Then cmdRoute.Enabled = False Else cmdRoute.Enabled = True End If

' Check whether the Release button should be enabled b = change.CheckValidOperation(roStatusRelease) If Not b Then cmdRelease.Enabled = False Else cmdRelease.Enabled = True End If

' Check whether the Unrelease button should be enabled b = change.CheckValidOperation(roStatusUnrelease) If Not b Then cmdUnrelease.Enabled = False Else cmdUnrelease.Enabled = True End If

' Check whether the Expire button should be enabled b = change.CheckValidOperation(roStatusExpire) If Not b Then cmdExpire.Enabled = False Else cmdExpire.Enabled = True End If

' Check whether the Resume button should be enabled b = change.CheckValidOperation(roStatusResume) If Not b Then cmdResume.Enabled = False Else cmdResume.Enabled = True End If

' Check whether the Implement button should be enabled b = change.CheckValidOperation(roStatusImplement) If Not b Then cmdImplement.Enabled = False Else

6-77


cmdImplement.Enabled = True End If

' Check whether the Close button should be enabled b = change.CheckValidOperation(roStatusClose) If Not b Then cmdClose.Enabled = False Else cmdClose.Enabled = True End If

' Check whether the Return to Originator button should be enabled b = change.CheckValidOperation(roStatusReturnToOriginator) If Not b Then cmdReturn.Enabled = False Else cmdReturn.Enabled = True End If

' Check whether the Hold button should be enabled b = change.CheckValidOperation(roStatusHold) If Not b Then cmdHold.Enabled = False Else cmdHold.Enabled = True End If

' Check whether the Cancel button should be enabled b = change.CheckValidOperation(roStatusCancel) If Not b Then cmdCancel.Enabled = False Else cmdCancel.Enabled = True End If

End Sub

DataObject::Delete()

Syntax

BOOL Delete()

Description

Deletes the object. The Agile API supports “soft” and “hard” deletes.



If you delete an object that has not already been deleted, this is a soft delete. When an object is soft-deleted,

❑ It still exists in the Agile Advantage database.❑ The object’s DataObject::IsDeleted property returns nonzero.❑ The object’s number is still reserved, and you cannot create another object

of that type with the deleted object’s number unless you hard-delete the object first.

❑ You can still get the object (for example, using the Item::LoadByAttr method).

❑ If you have the necessary privileges, you can undelete the object using DataObject::Undelete.

❑ If you have the necessary privileges, you can permanently delete the object using DataObject::Delete again.

If you delete an object that has already been soft-deleted, you remove it from the database permanently, or hard-delete it. You must have the necessary privileges to hard-delete an object.

Caution! Once you hard-delete an object, it is gone and cannot be restored.

The warning messages listed in Table 6-12 cause Delete to fail if they are enabled. Before using Delete, make sure these error codes are disabled using Base::DisableError.

For the complete list of error and warning messages, see Chapter 7, “Error Messages.”

Returns


Example

Sub DeleteDataObject(obj As Object)

'Disable warnings about deleting objects b = obj.DisableError(165)

Table 6-12: Delete error messages

Error Code Message Description

165 Are you sure that you want to delete this object?

Soft-delete warning

166 Are you sure that you want to permanently delete this object?

Hard-delete warning

6-79


b = obj.DisableError(166)

If Not obj.Delete Then MsgBox "Failed to delete object. " + obj.ErrorMessage Else 'Enable all error messages b = obj.EnableError(0) End If

End Sub

DataObject::GetTable()

Syntax

LPDISPATCH GetTable(LONG type)

Description

Gets a table of the specified type. Use GetTable to get different tables of an Item, Change, Manufacturer, Manufacturer Part, or Package. For example, you can use it to get the History list of an Item.

You cannot use GetTable to get a Table object for the Page 1, 2, and 3 table types (for example, ttItemPage1, ttItemPage2, and ttItemPage3) because they are not in tabular format. To retrieve attributes for Page 1, 2, and 3, use SubClass::GetAttributes.

Parameters

type

one of the Table type constants (see page 6-545)

Returns

A pointer to the Table object if the method is successful; Null otherwise.

Example

Public server As AgileAPI.ServerPublic item As AgileAPI.ItemPublic table As AgileAPI.Table

Private Sub cmdGetBOM_Click()

Dim b As Boolean

' Get the specified target Item Set item = CreateObject("AgileAPI.Item")



b = item.LoadByAttr(server, 0, txtTargetItem.Text) If Not b Then MsgBox "Failed to load Item. " + item.ErrorMessage Exit Sub End If ' Get the BOM table for the Item Set table = item.GetTable(ttItemBOM)

If table Is Nothing Then MsgBox "Failed to get BOM table. " + item.ErrorMessage End If

End Sub

DataObject::Refresh()

Syntax

BOOL Refresh()

Description

Refreshes the object’s data, making it current with the latest data from the server.

Returns


Example

Sub RefreshDataObject(obj As Object)

If Not obj.Refresh Then MsgBox "Failed to refresh. " + obj.ErrorMessage Exit Sub End If

End Sub

DataObject::Save()

Syntax

BOOL Save()

Description

Saves the object in the database.

6-81


Returns


Example

Sub SaveDataObject(obj As Object)

If Not obj.Save Then MsgBox "Failed to save. " + obj.ErrorMessage End If

End Sub

DataObject::SaveAs()

Syntax

BOOL SaveAs(LPDISPATCH subClass,LPCTSTR number)

Description

Saves the object as the specified subclass and number. You can save an object to another subclass, but it must be a subclass contained within the object’s parent class. For example, you can save a Part as a Document since both are contained within the Item class. However, you cannot save a Part as an ECO or an ECR.

Parameters

subClass

class definition

number

a string value used to uniquely identify the object you are saving. For an Item, Change, or Package, enter the Item Number, Change Number, or Package Number, respectively. For a Mfr, enter the Manufacturer name. For a MfrPart, there are two formats:

• mfrName::partNumber — saves the MfrPart as a different Mfr and MfrPart number.

• partNumber — saves the MfrPart with a different MfrPart number.

Returns




Example

Sub SaveAsDataObject(obj As Object, subClass As Object)

Dim nextNum As String

'Get the next AutoNumber for the SubClass subClass.GetNextNumber(subClass.AutoNumberSources.Get(0), nextNum)

'Save the DataObject If Not obj.SaveAs(subClass, nextNum) Then MsgBox "Failed to save. " + obj.ErrorMessage End If

End Sub

DataObject::Send()

Syntax

BOOL Send(LPCTSTR users,LPCTSTR comment)

Description

Sends the object to a list of users.

Parameters

users

semicolon-delimited list of users to receive the object (2000 characters maximum)

comment

comment describing the object (2000 characters maximum)

Returns

Nonzero if the method is successful; 0 otherwise. If any users on the users list are invalid, the method returns 0 and does not send the object to any users.

6-83


Example

Sub SendDataObject(obj As Object)

If Not obj.Send(txtToUsers.Text, txtComment.Text) Then MsgBox "Failed to send. " + obj.ErrorMessage End If

End Sub

DataObject::Undelete()

Syntax

BOOL Undelete()

Description

Restores the soft-deleted object where DataObject::IsDeleted is nonzero. You must have the necessary privileges to undelete an object.

Note You can undelete a Change only if it has no entries on the Affected Items table (TableType = ttChangeAffectedItems).

Returns


Example

Sub UndeleteDataObject(obj As Object) If Not obj.Undelete Then MsgBox "Failed to undelete the object. " + obj.ErrorMessage End IfEnd Sub


Chapter 6 Agile Advantage API Reference – Field

FieldOverview

Specifies the value of a particular data member in an object, which is equivalent to a single data cell in a tabbed window in the Agile Advantage Windows or Web client. A Field is associated with an Attribute object and defines the particular state of the corresponding data member. This object is a union of different types of properties. Use DataType to determine the type of the particular Field.

Hierarchy

❑ Base ❑ Field

Properties

Table 6-13: Field properties


Attribute LPDISPATCH Read-only Returns the Attribute object. For lists of attributes for each Agile Advantage class, see “” on page 6-261.

DataType LONG Read-only Returns the type of data stored. For more information about data types, see “Data Type Constants” on page 6-333.

BaseID LONG Read-only Returns the attribute’s base ID.

DiscoveryPrivilege BOOL Read-only Returns whether the user has the Discovery privilege for a particular cell, which permits the user to see its value. If the user does not have the Discovery privilege, the GetValue method returns “No Privilege.”

Note: If the Discovery feature is disabled in the Agile Database node in Agile Administrator, users with the Read privilege are able to discover all objects.

6-85


Methods

GetValue

SetNull

SetValue

ShowRedline

UndoRedline

Field::GetValue()

Syntax

BOOL GetValue(VARIANT FAR* value)

Description

Retrieves the field value. To set the field value, use Field::SetValue.

IsReadOnly BOOL Read-only Returns a nonzero value if the field is read-only. Otherwise, it returns 0.

IsRedlined BOOL Read-only Returns a nonzero value when the field value is redlined. Otherwise, it returns 0.

To check if a row of a table has been redlined, use Row::GetStatus. For example, use Row::GetStatus(stIsRedlineAdded, status) to check whether a row has been redline added.

IsRedlineShown BOOL Read-only Returns a nonzero value when the redlined value is being shown. Otherwise, it returns 0.

ListElements LPDISPATCH Read-only Returns the collection of all possible values for a list field.

Name BSTR Read-only Returns the name used to identify the object.





The data type of value depends on the data type of the Field object (Field::DataType), as shown in Table 6-14.

The field may not have a value. For a Text field with no value, GetValue returns an empty string. For a SingleList or MultiList field with no value, GetValue returns an empty Collection object.

For list and MultiList fields, the selected value could be obsolete if it was removed from the list in Agile Administrator after the value was last set. You can check if a value is obsolete using the ListElement::IsObsolete property.

Parameters

value

an output parameter that returns the property value

Returns


Example: Getting a String Value

The following Visual Basic code shows how to use Field::GetValue to get the value for “Title Block.Description,” a string value.

Public Item As AgileAPI.ItemPublic vDesc As Variant

Public Sub GetDescription()

Dim field As AgileAPI.Field

'Get the "Title Block.Description" field Set field = Item.Fields.Find(aidParts_TitleBlock_Description)

'Get the "Title Block.Description" value b = field.GetValue(vDesc)

Table 6-14: Date types of Field values

Field::DataType value Variant Data Type

dtString VT_BSTR (a string)

dtLong VT_I4 (an integer)

dtDate VT_DATE (a date)

dtSingleList VT_DISPATCH (a Collection of one ListElement)

dtMultiList VT_DISPATCH (a Collection of ListElements)

6-87


If Not b Then MsgBox field.ErrorMessage, vbInformation, "Error Getting Value" Exit Sub End If

'Populate the Description field with the value frmMain.txtDesc.Text = vDesc

End Sub

Example: Getting a Numeric Value

The following Visual Basic code shows how to use Field::GetValue to get the value for “Page Two.Standard Cost,” a custom text field whose format has been set to Numeric.

Public Item As AgileAPI.ItemPublic vStdCost As Variant

Public Sub GetStdCost()


'Get the "Page Two.Standard Cost" (Text01) field Set field = Item.Fields.Find(aidParts_PageTwo_Text01)

'Get the "Page Two.Standard Cost" value b = field.GetValue(vStdCost) If Not b Then MsgBox field.ErrorMessage, vbInformation, "Error Getting Value" Exit Sub End If

'Populate the Standard Cost field with the value frmMain.txtStdCost.Text = vStdCost

End Sub

Example: Getting a Date Value

The following Visual Basic code shows how to use Field::GetValue to get the value for a custom date field, “Page Two.Target Draft Date.”

Public Item As AgileAPI.ItemPublic vTargetDraftDate As Variant

Public Sub GetTargetDraftDate()




'Get the "Page Two.Target Draft Date" (Date01) field Set field = Item.Fields.Find(aidParts_PageTwo_Date01)

'Get the "Page Two.Target Draft Date" value b = field.GetValue(vTargetDraftDate) If Not b Then MsgBox field.ErrorMessage, vbInformation, "Error Getting Value" Exit Sub End If

'Populate the Draft Date field with the value If CStr(vTargetDraftDate) <> "" Then frmMain.txtDraftDate.Text = FormatDateTime(vTargetDraftDate, _ vbShortDate) Else frmMain.txtTargetDraftDate.Text = "" End If

End Sub

Example: Getting a List Value

The following Visual Basic code shows how to use Field::GetValue to get the value for “Title Block.Part Category,” a list value.

Public Item As AgileAPI.ItemPublic vPartCat As Variant

Public Sub GetPartCat()


'Get the "Title Block.Part Category" field Set field = Item.Fields.Find(aidParts_TitleBlock_PartCategory)

'Get the "Title Block.Part Category" value b = field.GetValue(vPartCat) If Not b Then MsgBox field.ErrorMessage, vbInformation, "Error Getting Value" Exit Sub End If

'Select the "Title Block.Part Category" value in the list

6-89


If vPartCat.Count = 0 Then frmMain.cmbPartCat.ListIndex = -1 Else If vPartCat.Get(0).IsObsolete = True Then frmMain.cmbPartCat.ListIndex = -1 Else frmMain.cmbPartCat.Text = vPartCat.Get(0).Value End If End If

End Sub

Example: Getting a MultiList Value

The following Visual Basic code shows how to use Field::GetValue to get the value for “Title Block.Product Line(s),” a MultiList value.

Public Item As AgileAPI.ItemPublic vProdLines As Variant

Public Sub GetProdLines()


'Get the "Title Block.Product Line(s)" field Set field = Item.Fields.Find(aidParts_TitleBlock_ProductLines)

'Get the "Title Block.Product Line(s)" value b = field.GetValue(vProdLines) If Not b Then MsgBox field.ErrorMessage, vbInformation, "Error Getting Value" Exit Sub End If

'Populate the Product Lines field with the value If vProdLines.Count = 0 Then frmMain.txtProdLines.Text = "" Else frmMain.txtProdLines.Text = ListElementsToString(vProdLines) End If

End Sub

Public Function ListElementsToString(col As Variant) As String

Dim ListElements As String



For I = 0 To col.Count - 1 If col.Get(I).IsObsolete = False Then ListElementsToString = ListElementsToString + col.Get(I).Value If Not I = col.Count - 1 Then ListElementsToString = ListElementsToString + "," End If End If Next IEnd Function

Field::SetNull()

Syntax

BOOL SetNull()

Description

Sets the field value to Null. For a Date, Long, or SingleList field, you can use SetNull to select no value.

Returns


Example


'Get the Part Category fieldSet field = Item.Fields.Find(aidParts_TitleBlock_PartCategory)

'If no Part Category is selected, set its value to NullIf frmMain.cmbPartCat.ListIndex = -1 Then b = field.SetNull()End If

Field::SetValue()

Syntax

BOOL SetValue( const VARIANT FAR& value)

Description

Sets the field value. The field is not saved to the database until you use DataObject::Save.

6-91


The data type of value depends on the data type of the Field object (Field::DataType). For more information, see “Field::GetValue()” on page 6-86.

When you set a value for a field, the Agile Advantage API automatically sets Base::IsDirty equal to 1. This locks the object and prevents other users from modifying it. The object remains locked until you either save or abort your changes.

Parameters

value

the new value of the field

Returns


Example: Setting a String Value

The following Visual Basic code shows how to use Field::SetValue to set the value for “Title Block.Description,” a string value.


Public Sub SetDesc()


'Get the "Title Block.Description" field Set field = Item.Fields.Find(aidParts_TitleBlock_Description)

'Set the "Title Block.Description" value b = field.SetValue(frmMain.txtDesc.Text) If Not b Then MsgBox field.ErrorMessage, vbInformation, "Error Setting Value" Call GetDescription End If

End Sub

Example: Setting a Numeric Value

The following Visual Basic code shows how to use Field::SetValue to set the value for “Page Two.Standard Cost,” a custom text field whose format has been set to Numeric.


Public Sub SetStdCost()




'Get the "Page Two.Standard Cost" (Text01) field Set field = Item.Fields.Find(aidParts_PageTwo_Text01)

'Set the "Page Two.Standard Cost" value b = field.SetValue(frmMain.txtStdCost.Text) If Not b Then MsgBox field.ErrorMessage, vbInformation, "Error Setting Value" Call GetStdCost End If

End Sub

Example: Setting a Date Value

The following Visual Basic code shows how to use Field::SetValue to set the value for a custom date field, “Page Two.Target Draft Date.”


Public Sub SetTargetDraftDate()


'Get the "Page Two.Target Draft Date" (Date01) field Set field = Item.Fields.Find(aidParts_PageTwo_Date01)

'Get the "Page Two.Target Draft Date" value b = field.SetValue(dtTargetDraftDate.Value)

If Not b Then MsgBox field.ErrorMessage, vbInformation, "Error Setting Value" Call GetTargetDraftDate End If

End Sub

Example: Setting a List Value

The following Visual Basic code shows how to use Field::SetValue to set the value for “Title Block.Part Category,” a list value.

Public Item As AgileAPI.ItemPublic vPartCat As VariantPublic PartsClass As AgileAPI.SubClassPublic attr As AgileAPI.Attribute

6-93


Public Sub SetPartCat()

Dim field As AgileAPI.Field Dim col As AgileAPI.Collection Dim li As AgileAPI.ListElement

'Get the Part Category field Set field = Item.Fields.Find(aidParts_TitleBlock_PartCategory)

'Get the collection of Part Category values Set col = field.ListElements

'Clear the Part Category collection retrieved 'earlier using GetValue vPartCat.Clear 'Set the "Title Block.Part Category" value If frmMain.cmbPartCat.ListIndex = -1 Then b = field.SetValue(vPartCat) Else Set li = col.Get(frmMain.cmbPartCat.ListIndex) vPartCat.Add li, -1 b = field.SetValue(vPartCat) End If If Not b Then MsgBox field.ErrorMessage, vbInformation, "Error Setting Value" Call GetPartCat End If

End Sub

Example: Setting a MultiList Value

The following Visual Basic code shows how to use Field::SetValue to set the value for “Title Block.Product Line(s),” a MultiList value.


Public Sub UpdateProductLines()

Dim field As AgileAPI.Field Dim col As AgileAPI.Collection Dim listElement As AgileAPI.ListElement Dim li As ListItem

'Get the Product Lines property



Set field = Item.Fields.Find(aidParts_TitleBlock_ProductLines)

'Get the collection of Product Lines values Set col = field.ListElements

'Clear the Product Lines collection retrieved 'earlier using GetValue vProdLines.Clear

'Compare the selected Product Lines values with 'each of the possible values for the field. 'For each matching value, add the list element to 'the vProdLines collection. For I = 0 To frmMultiList.lvwSelections.ListItems.Count - 1 Set li = frmMultiList.lvwSelections.ListItems(I + 1) For x = 0 To col.Count - 1 If li.Text = col.Get(x).Value Then Set listElement = col.Get(x) vProdLines.Add listElement, -1 End If Next x Next I

'Populate the Product Lines field with the value If vProdLines.Count = 0 Then frmMain.txtProdLines.Text = "" Else frmMain.txtProdLines.Text = ListElementsToString(vProdLines) End If frmMultiList.Hide

'Get the "Title Block.Product Line(s)" field Set field = Item.Fields.Find(aidParts_TitleBlock_ProductLines)

'Set the "Title Block.Product Line(s)" value b = field.SetValue(vProdLines) If Not b Then MsgBox field.ErrorMessage, vbInformation, "Error Setting Value" GetProdLines End If

End Sub

6-95


Field::ShowRedline()

Syntax

BOOL ShowRedline(BOOL show)

Description

Toggles between the redline value and the original value.

Parameters

show

a nonzero value to show the redline value; 0 to show the original value

Returns


Example

Sub ShowRedline(obj As Object)

If Not obj.ShowRedline Then MsgBox "Failed to show redline. " + obj.ErrorMessage Else DisplayRedlineValues End If

End Sub

Field::UndoRedline()

Syntax

BOOL UndoRedline()

Description

Removes the redline value.

Returns


Example

Sub UndoRedline(obj As Object) If Not obj.UndoRedline Then MsgBox "Failed to undo redline. " + obj.ErrorMessage End IfEnd Sub


Chapter 6 Agile Advantage API Reference – Folder

FolderOverview

A folder used to hold other objects, such as other Folder or Query objects.

Folders can also contain Change, Item, Mfr, MfrPart, and Package objects, even though these objects are not visible in the Agile Advantage Windows client folders. To retrieve one of these objects from a folder, use Folder::GetItemInfo to retrieve the ObjectInfo for the object, then use Server::GetObject to get the object.

Folders can be Public, Private, or System. A Public folder is accessible to all users. A Private folder is accessible only to the folder owner. A System folder, which is accessible to users with appropriate privileges, is a predefined folder included with the Agile system.

Folder is an externally creatable object. However, when you use the constructor to create a folder in your program, it is an empty object that is not associated with an Agile eHub. To load an existing folder, use Folder::LoadByInfo. To create a new folder on an Agile Advantage eHub, use Folder::Create.

The Agile Advantage API automatically saves any changes that you make to a folder. If you add or remove items, change the sort order, or rename the folder, it is automatically saved.

Note You cannot modify items in the Agile Advantage Home Folder. You also cannot modify most predefined system queries.

Hierarchy

❑ Base❑ Folder

Properties



Description BSTR Read-only Sets and gets the description of the folder.

Note: The folder description is not a visible property in the Agile Advantage Windows or Web client.

ItemCount LONG Read-only Returns the number of items in the folder.

6-97


Methods

Folder::AddItem()

Syntax

long AddItem(LPDISPATCH info,long index)

Description

Adds an item (such as a Folder or Query object) to the folder at the specified index.

Note You cannot add items to the Agile Advantage Home Folder.

Parameters

info

a pointer to an ObjectInfo object

index

index number at which to insert the new item; -1 to add the item at the end

Returns

Index number of the new item.

Owner BSTR Read-only Returns the owner of the folder.

AddItem GetType

Clear LoadByInfo

Create OrderItems

Delete Refresh

FindItemIndex RemoveItem

GetItemInfo SetName

GetItemName SetSortOrder

GetName SetType

GetSortOrder





Example

Public Sub AddAllItemsQuery(folder As Object, server As Object)

Dim query As AgileAPI.Query Dim info As AgileAPI.ObjectInfo Dim b As Boolean Dim l As Long Dim attrID As Long

'Create a Query object Set query = CreateObject("AgileAPI.Query") b = query.Create(server)

'Create an ObjectInfo object Set info = CreateObject("AgileAPI.ObjectInfo")

'Define the All Items query attrID = aidParts_TitleBlock_Number b = query.SetClass(ctItem) l = query.AddCriteria(attrID, qroLike, "%", qloNone, 0, 0)

'Set the query name b = query.SetName("All Items")

'Save the query b = query.Save

'Get the query ObjectInfo b = query.GetObjectInfo(info)

'Add the All Items query to the folder b = folder.AddItem(info, -1)

End Sub

Folder::Clear()

Syntax

BOOL Clear()

Description

Clears the folder of all objects. You can clear the contents of folders that you created, but you cannot clear the contents of any predefined Agile Advantage system folders (such as the Global Searches and My Inbox folders).

6-99


Returns


Example

Public Sub ClearFolder(folder As Object)

Dim b As Boolean

'Clear the folder b = folder.Clear If Not b Then MsgBox "Unable to clear items from the folder. " + folder.ErrorMessage Exit Sub End If

'Refresh the folder contents b = folder.Refresh

End Sub

Folder::Create()

Syntax

BOOL Create(LPDISPATCH server)

Description

Creates a new Folder, which can be used as a container for Folder or Query objects.

Parameters

server

a pointer to a Server object used to initialize the Folder object

Returns


Example

Public folder As AgileAPI.FolderPublic currFolderInfo As AgileAPI.ObjectInfo

Public Sub CreateFolder(server As Object)

Dim b As Boolean



frmCreateFolder.Show vbModal

'Create a folder object Set folder = CreateObject("AgileAPI.folder")

'Initialize the new folder object b = folder.Create(server)

'Set the folder type b = folder.SetType(ftPrivate)

'Name the folder b = folder.SetName(frmCreateFolder.txtName.Text)

End Sub

Folder::Delete()

Syntax

BOOL Delete()

Description

Permanently deletes the folder. You cannot delete folders that are not empty or contain subfolders. You also cannot delete any predefined Agile Advantage system folders (such as the Global Searches and My Inbox folders).

Note Once you delete a folder, you cannot undelete it.

Returns


Example

Public Sub DeleteFolder(folder as Object)

Dim intResponse As Long Dim b As Boolean

intResponse = MsgBox("Delete the folder?", vbYesNo) If intResponse = vbYes Then b = folder.Delete If Not b Then MsgBox "Unable to delete folder." + folder.ErrorMessage End If End If

6-101


End Sub

Folder::FindItemIndex()

Syntax

long FindItemIndex(LPDISPATCH info)

Description

Finds the index position of an item (such as a Folder or Query object) with matching object information.

Parameters

info

a pointer to an ObjectInfo object that specifies the object to find

Returns

The index position of the matching item.

Example

See “Folder::RemoveItem()” on page 6-109.

Folder::GetItemInfo()

Syntax

BOOL GetItemInfo(long index,LPDISPATCH info)

Description

Retrieves information that uniquely identifies the Agile object (such as a Query object) at the specified index position.

Parameters

index

index position of an item contained in the folder

info

output parameter that returns a pointer to an ObjectInfo object for the specified folder item. info must point to an existing ObjectInfo object; it cannot be Null.



Returns


Example

Public server As AgileAPI.Server

Public Sub GetGlobalSearches(homefolder As Object)

Dim qfolder As AgileAPI.Folder Dim info As AgileAPI.ObjectInfo

'Create a folder object Set qfolder = CreateObject("AgileAPI.folder")


'Get the Global Searches folder For i = 0 To homefolder.ItemCount - 1 If homefolder.GetItemName(i) = "Global Searches" Then b = homefolder.GetItemInfo(i, info) If b Then b = qfolder.LoadByInfo(server, info) End If End If Next i

End Sub

Folder::GetItemName()

Syntax

BSTR GetItemName(long index)

Description

Retrieves the name of the item (such as a Query object) at the specified index position.

Parameters

index

index position of an item contained in the folder

6-103


Returns

Name of the item at the specified index position.

Example

See “Folder::GetItemInfo()” on page 6-102.

Folder::GetName()

Syntax

BSTR GetName()

Description

Retrieves the name of the folder.

Returns

The folder name.

Example

Public folder As AgileAPI.Folder

'Code for Folder Name formPrivate Sub Form_Activate() 'Get the current folder name and fill the Name field with it txtName.Text = folder.GetName

End Sub

Private Sub cmdOK_Click()

If Not folder.SetName(txtName.Text) Then MsgBox "Failed to set the folder name." + folder.ErrorMessage End If

End Sub

Folder::GetSortOrder()

Syntax

long GetSortOrder()

Description

Retrieves the method used to sort the folder contents.



Returns

One of the Folder sort order constants (see page 6-364).

Example

Public folder As AgileAPI.Folder

'Code for activating the Folder Sort Order formPrivate Sub Form_Activate()

'Populate the Sort Order combo box cboSortOrder.AddItem "Random" cboSortOrder.AddItem "Name" cboSortOrder.AddItem "Insertion Order" cboSortOrder.AddItem "Custom" cboSortOrder.AddItem "Reverse Insertion Order"

'Get the current sort order cboSortOrder.ListIndex = folder.GetSortOrder

End Sub


Dim i As Long Dim str As String

If Not folder.SetSortOrder(cboSortOrder.ListIndex) Then MsgBox "Failed to set the folder sort order." + folder.ErrorMessage Else For i = 0 To folder.ItemCount - 1 str = folder.GetItemName(i) 'Additional code goes here Next i End If

End Sub

Folder::GetType()

Syntax

long GetType()

Description

Retrieves the folder type.

6-105


Returns

One of the Folder type constants (see page 6-365), either ftPublic, ftPrivate, or ftSystem.

Example

Public Sub EnableDeleteButton(folder As Object, user As Object)

Select Case folder.GetType

Case ftPublic 'Check if the user has privileges to delete Global Searches If user.CheckPrivilege(upidGlobalSearch, Null, 0) cmdDelete.Enabled = True Else cmdDelete.Enabled = False End If Case ftPrivate cmdDelete.Enabled = True Case ftSystem 'System folders cannnot be deleted cmdDelete.Enabled = False

End Select

End Sub

Folder::LoadByInfo()

Syntax


Description

Loads an existing Folder into the object by specifying an ObjectInfo object that uniquely identifies it. The specified ObjectInfo object must have TargetType and TargetID members.

Parameters

server

a pointer to a Server object used to initialize the Folder object



info

a reference to an ObjectInfo object that uniquely identifies the Folder. Make sure the ObjectInfo object specifies a TargetType of otFolder and the TargetID of the folder.

Returns


Example

See “Folder::GetItemInfo()” on page 6-102.

Folder::OrderItems()

Syntax

BOOL OrderItems(LPDISPATCH indices)

Description

Applies a custom sort order to the folder according to the specified indices.

Parameters

indices

a Collection containing the current index positions of folder items rearranged in a sequence. For example, if there are four items in the folder, passing in 0,1,3,2 swaps the last two items in the folder.

Returns


Example

Public Sub OrderFirst(folder As Object, currIndex As Long)

Dim indices As AgileAPI.Collection Dim b As Boolean

Set indices = CreateObject("AgileAPI.Collection")

'If the item is already ordered first, do nothing If currIndex = 0 Then Exit Sub 'Move the currIndex item to the first position Else indices.Add(currIndex, -1)

6-107


For i = 0 To Folder.ItemCount - 1 If i <> currIndex Then indices.Add(i, -1) End If Next i b = folder.OrderItems(indices) If Not b Then MsgBox "Unable to order items. " + folder.ErrorMessage End If End If End Sub

Folder::Refresh()

Syntax

BOOL Refresh()

Description

Refreshes the folder, retrieving the latest data from the Agile Advantage eHub. If other users make changes to a folder while you have it open, Folder::Refresh retrieves those changes.

Returns


Example

Private Sub RefreshFolder(Folder As Object)

'Refresh the folder If Not Folder.Refresh Then MsgBox "Failed to refresh. " + Folder.ErrorMessage Exit Sub End If

Call RefreshFolderView

End Sub



Folder::RemoveItem()

Syntax

BOOL RemoveItem(long index)

Description

Removes an item from the folder.

Note You cannot remove items from the Agile Home Folder. You also cannot remove most predefined system queries.

Parameters

index

index position of the item to remove

Returns


Example

Public info As Object

Private Sub cmdRemove_Click(info As Object)

Dim intResponse As Long Dim index As Long

intResponse = MsgBox("Remove the selected folder or query?", vbYesNo) If intResponse = vbYes Then index = folder.FindItemIndex(info) b = folder.RemoveItem(index) End If

End Sub

Folder::SetName()

Syntax

BOOL SetName(LPCTSTR name)

Description

Sets the name of the folder.

6-109


Note You cannot rename items in the Agile Advantage Home Folder. You also cannot rename most predefined system queries.

Parameters

name

the folder name

Returns


Example

See “Query::GetName()” on page 6-164.

Folder::SetSortOrder()

Syntax

BOOL SetSortOrder(long order)

Description

Sets the method used to sort the folder contents.

Parameters

order

one of the Folder sort order constants (see page 6-364)

Returns


Example

See “Folder::GetSortOrder()” on page 6-104.

Folder::SetType()

Syntax

BOOL SetType(long type)

Description

Sets the folder type. You can set the folder type to Public (ftPublic) or Private (ftPrivate). You cannot create a System folder.



Parameters

type

one of the Folder type constants (see page 6-365), either ftPublic or ftPrivate

Returns


Example

See “Folder::Create()” on page 6-100.

6-111


ItemOverview

An Item in the product change control process. By default, there are two types of Item subclasses available in the Agile Advantage system: Parts and Documents. In general, a Part is shipped as part of a product and has costs associated with it. A Document generally is an internal document, drawing, or procedure that references a Part. Your Agile administrator may define other types of Item subclasses for your company (for example, Capacitor or Resistor).

Item is an externally creatable object. However, when you use the constructor to create an Item in your program, it is an empty object that is not associated with an Agile Advantage eHub. To work with an existing Item, you need to use Item::LoadByAttr or Item::LoadByInfo to load an Item from an Agile Advantage eHub. To create a new Item on an Agile Advantage eHub, use Item::Create.

Hierarchy

❑ Base❑ Row

❑ DataObject❑ Item

Methods

Item::Create()

Syntax

BOOL Create(LPDISPATCH server,

Create SetIncorporated

GetIncorporated SetRevision

GetRevision SyncAML

GetRevisions SyncBOM

LoadByAttr VbsGetRevision

LoadByInfo


Chapter 6 Agile Advantage API Reference – Item

const VARIANT FAR& subClass,LPCTSTR number)

Description

Creates a new Item using the specified subclass.

Parameters

server

a pointer to a Server object used to initialize the new Item

subclass


number

number of the new Item

Returns


Example

Public server As AgileAPI.ServerPublic currPart As AgileAPI.Item

Private Sub cmdCreatePart_Click()

Dim b As Boolean

Set currPart = CreateObject("AgileAPI.Item") b = currPart.Create(server, "Part", txtNumber.Text) If Not b Then MsgBox "Failed to create object. " + currPart.ErrorMessage End If

End Sub

Item::GetIncorporated()

Syntax

BOOL GetIncorporated()

Description

Shows whether an Item is incorporated. When you incorporate an Item its attachments are locked to prevent unauthorized changes. To change the incorporated status of an Item, use Item::SetIncorporated.

6-113


Returns

Nonzero if the Item is incorporated; 0 otherwise.

Example

Public Item As AgileAPI.ItemPublic boolIncorp As Boolean

Private Sub Form_Activate()

'Get the incorporated status boolIncorp = Item.GetIncorporated

'Set the caption for the Incorporate/Unincorporate button If boolIncorp = False Then cmdIncorporate.Caption = "Incorporate" Else cmdIncorporate.Caption = "Unincorporate" End If

End Sub

Private Sub cmdIncorporate_Click()

'Change the Incorporated status If boolIncorp = False Then b = Item.SetIncorporated(1) boolIncorp = True cmdIncorporate.Caption = "Unincorporate" Else b = Item.SetIncorporated(0) boolIncorp = False cmdIncorporate.Caption = "Incorporate" End If

End Sub

Item::GetRevision()

SyntaxBOOL GetRevision(

BSTR FAR* changeNumber,BSTR FAR* revNumber)



Description

Retrieves the Change number associated with the Item’s current revision. GetRevision is paired with SetRevision, which lets you reset the revision for an Item.

Parameters

changeNumber

an output parameter that returns the Change number for the revision

revNumber

an output parameter that returns the revision number (or letter, such as A, B, or C) for the Item

Returns


Example


Private Sub Form_Activate()

Dim b As Boolean Dim i As Long Dim li As listitem Dim ChangeNumbers As AgileAPI.Collection Dim RevNumbers As AgileAPI.Collection Dim ChangeNum As String Dim RevNum As String

' Create the collections Set ChangeNumbers = CreateObject("AgileAPI.Collection") Set RevNumbers = CreateObject("AgileAPI.Collection")

' Clear the list view lvwRevList.ListItems.Clear

' Get the revisions for the Item If Not Item.GetRevisions(ChangeNumbers, RevNumbers) Then MsgBox "Failed to get revisions. " + Item.ErrorMessage Hide End If

For i = 0 To ChangeNumbers.count - 1

'Add the change numbers and their associated revision

6-115


'numbers to the list view Set li = lvwRevList.ListItems.Add(, , ChangeNumbers.Get(i)) li.SubItems(1) = RevNumbers.Get(i)

'Select the current revision b = Item.GetRevision(ChangeNum, RevNum) If ChangeNumbers.Get(i) = ChangeNum Then li.Selected = True End If

Next i

End Sub

Private Sub OKButton_Click()

Rev = lvwRevList.SelectedItem.Text

'Set the revision to the one selected in the list view If Not Item.SetRevision(Rev) Then MsgBox "Failed to set revision " + Rev + ". " + Item.ErrorMessage Hide End IfEnd Sub

Item::GetRevisions()

Syntax

BOOL GetRevisions(LPDISPATCH FAR* changeNumbers,LPDISPATCH FAR* revNumbers)

Description

Returns the Collection of all revisions. Each revision is paired with a Change number.

Parameters

changeNumbers

an output parameter that returns the Collection of Change numbers for the Item. changeNumbers must point to an existing Collection object; it cannot be Null.



revNumbers

an output parameter that returns the Collection of revision numbers for the Item. revNumbers must point to an existing Collection object; it cannot be Null.

Returns


Example

See “Item::GetRevision()” on page 6-114.

Item::LoadByAttr()

Syntax


Description

Loads an existing Item into the object by specifying an attribute and its value.

Parameters

server

a pointer to a Server object used to initialize the Item

attr

a fully qualified attribute, such as “Title Block.Description,” or a base ID. You can also type 0 to use the default attribute, “Title Block.Item Number.” For lists of attributes for each Agile Advantage class, see “” on page 6-261.

value


Returns


Example

Public server As AgileAPI.ServerPublic currPart As AgileAPI.Item

Private Sub GetItem_Click()

6-117


Dim b As Boolean

Set currPart = CreateObject("AgileAPI.Item") b = currPart.LoadByAttr(server, 0, txtNumber.Text) If Not b Then MsgBox "Failed to get object. " + currPart.ErrorMessage End If

End Sub

Item::LoadByInfo()

Syntax


Description

Loads an existing Item into the object by specifying an ObjectInfo object that uniquely identifies it. The specified ObjectInfo object must have TargetID and TargetType members.

Parameters

server

a pointer to a Server object used to initialize the Item

info

a reference to an ObjectInfo object that uniquely identifies the Item

Returns


Example


Item::SetIncorporated()

Syntax

BOOL SetIncorporated(BOOL incorporated)



Description

Sets whether the Item is incorporated. When you incorporate an Item, you lock its attachments, preventing anyone from making unauthorized changes. To add or edit attachments on an incorporated Item, the Item must first be unincorporated.

Note The incorporated status of an Item is specific to a particular revision. When you incorporate a revision of an Item, previous unincorporated revisions remain unincorporated. The default incorporated status is unincorporated.

Parameters

incorporated

a nonzero value to indicate that the Item is incorporated; 0 to indicate that it is not incorporated

Returns


Example

See “Item::GetIncorporated()” on page 6-113.

Item::SetRevision()

Syntax

BOOL SetRevision(LPCTSTR changeNumber)

Description

Sets the current revision for the Item to one associated with a specified Change number. The default revision is always the latest released one. To set the Item to an earlier revision, specify the number of the Change associated with the revision.

Parameters

changeNumber

Change number associated with a particular revision for the Item

Returns


Example

See “Item::GetRevision()” on page 6-114.

6-119


Item::SyncAML()

Syntax

BOOL SyncAML(LPCTSTR sourceItem,LPCTSTR change,LPDISPATCH option)

Description

Synchronizes the AML of the target Item with the AML of a specified source Item. Only attributes specified by the option parameter are synchronized. Changes to the target Item’s AML are redlined, and the target Item is added to the Affected Items table of a specified Change. Neither the target Item nor the specified source Item needs to be released to use the SyncAML method; both can be preliminary Items. However, a Manufacturing Change Order (MCO) or an Engineering Change Order (ECO) must be created to synchronize the two AMLs. If an MCO is used, the Rev is not rolled for the target Item.

SyncAML results in server side processing on the Agile Advantage database. To avoid unnecessary processing, you should use Server::DiffAML to determine if the source Items and target Items have different AMLs. If the AMLs are identical, SyncAML does not need to be used.

Parameters

sourceItem

number of the source Item used to compare and synchronize AMLs

change

number of the pending Change (an MCO or ECO) for the target Item. The target Item must not be listed on the Affected Items table of the Change; otherwise the method fails. The specified Change must not be released yet. Otherwise, the SyncAML method cannot change the Affected Items table.

option

a SyncOption object that contains a Collection object filled with base ID numbers for attributes. To guarantee that the correct attributes are redlined, the SyncOption object should be the same one used for Server::DiffAML. The SyncOption object identifies columns on the Manufacturers tab that you want redlined. Any attributes not specified in the SyncOption object are not redlined. If option is Null, contains no ID numbers, or contains no valid ID numbers for the Manufacturers tab, all columns on the Manufacturers tab are redlined. For more information, see “SyncOption” on page 6-241. For lists of attributes for each Agile Advantage class, see “” on page 6-261.



Returns


Example

Private Sub RedlineAML()

Dim bRet As Boolean Dim lRet As Long Dim colSource As AgileAPI.Collection Dim colTarget As AgileAPI.Collection Dim colResult As AgileAPI.Collection Dim objItem As AgileAPI.Item Dim sChangeOrder As String Dim sObjectId As String Dim sTempObjectId As String Dim soRedlineColumns As AgileAPI.SyncOption 'Initialize the Agile API Collections Set colSource = CreateObject("AgileAPI.Collection") Set colTarget = CreateObject("AgileAPI.Collection") Set colResult = CreateObject("AgileAPI.Collection") bRet = colSource.SetDataType(dtString) bRet = bRet And colTarget.SetDataType(dtString) bRet = bRet And colResult.SetDataType(dtString)

'Specify the ID numbers for the source 'and target Items and the Change sObjectID = P01201 sTempObjectId = TMP00001 sChangeOrder = C00100

'Add the Target Item to the Source Collection lRet = colSource.Add(sObjectId, 0)

'Add the Temporary Item to the Target Collection lRet = colTarget.Add(sTempObjectId, 0)

'Create a new SyncOption object to use for DiffAML Set soRedlineColumns = CreateObject("AgileAPI.SyncOption")

'Diff the target Item/temp Item pair bRet = server.DiffAML(colSource, colTarget, colResult, soRedlineColumns) If (Not bRet) Then MsgBox Server.ErrorMessage Else

6-121


If colResult.Count > 0 Then 'Get the target Item Set objItem = CreateObject("AgileAPI.Item") b = objItem.LoadByAttr(server, 0, colResult.Get(0)) If Not b Then MsgBox objItem.ErrorMessage End If 'Synchronize the AMLs bRet = objItem.SyncAML(colTarget.Get(0), _ sChangeOrder, _ soRedlineColumns) End If End If

End Sub

Item::SyncBOM()

Syntax

BOOL SyncBOM(LPCTSTR sourceItem,LPCTSTR changeLPDISPATCH option)

Description

Synchronizes the BOM of the target Item with the BOM of a specified source Item. Only attributes specified by the option parameter are synchronized. Changes to the target Item’s BOM are redlined, and the target Item is added to the Affected Items table of a specified Change. Neither the target Item nor the specified source Item needs to be released to use the SynchBOM method; both can be preliminary Items. An Engineering Change Order (ECO) must be created to synchronize the two BOMs. The target Item cannot have existing pending Changes with redlines.

When you use the SyncBOM method to synchronize the BOMs of two Items, you effectively create a new revision of the target Item. After synchronizing BOMs, you should release the Change to the target Item using RouteObject::Release.

Parameters

sourceItem

number of the source Item used to compare and synchronize BOMs



change

number of the pending ECO for the target Item. The target Item must not be listed on the Affected Items table of the ECO; otherwise the method fails. The specified ECO must not be released yet. Otherwise, the SyncBOM method cannot change the Affected Items table.

option

a SyncOption object that contains a Collection object filled with base ID numbers for attributes. The SyncOption object identifies columns on the BOM tab that you want redlined. Any attributes not specified in the SyncOption object are not redlined. If option is Null, contains no ID numbers, or contains no valid ID numbers for the BOM tab, all columns on the BOM tab are redlined. For more information, see “SyncOption” on page 6-241. For lists of attributes for each Agile Advantage class, see “” on page 6-261.

Returns


Example

Public server As AgileAPI.ServerPublic item As AgileAPI.Item

Private Sub cmdSyncBOM_Click()

Dim so As AgileAPI.SyncOption Dim b As Boolean

' Create a new instance of the SyncOption Set so = CreateObject("AgileAPI.SyncOption")

' Add attribute IDs to the SyncOption so.CompareIDs.Add(aidParts_BOM_ItemNumber, -1) so.CompareIDs.Add(aidParts_BOM_PartDescription, -1) so.CompareIDs.Add(aidParts_BOM_ItemRev, -1) so.CompareIDs.Add(aidParts_BOM_FindNum, -1) so.CompareIDs.Add(aidParts_BOM_Qty, -1) so.CompareIDs.Add(aidParts_BOM_RefDes, -1)

' Get the specified target Item Set item = CreateObject("AgileAPI.Item") b = item.LoadByAttr(server, 0, txtTarget.Text)

' Synchronize the BOMs of the two Items If item.SyncBOM(txtSource.Text, txtChange.Text, SyncOption) Then

6-123


'If SyncBOM is successful, set the new Rev item.SetRevision txtChange.Text

Else MsgBox "Failed to synchronize BOMs. " + item.ErrorMessage End If

End Sub

Item::VbsGetRevision()

Syntax

BOOL VbsGetRevision(VARIANT FAR* changeNumber,VARIANT FAR* revNumber)

Description

A VBScript-supported version of GetRevision that retrieves the Change number associated with the Item's current revision.

Parameters

changeNumber

an output parameter that returns the Change number for the revision

revNumber

an output parameter that returns the revision number (or letter, such as A, B, or C) for the Item

Returns



Chapter 6 Agile Advantage API Reference – ListElement

ListElementOverview

An element in a SingleList or MultiList field, which contains a list of items that the user can select. You can retrieve the Collection of ListElement objects for a field using the ListElements property; see “ListElements” on page 6-86 and 6-147.

ListElement is an externally creatable object. After you create a ListElement object, you can set its value. You cannot set its ID because that is a read-only property. The Agile Advantage eHub sets a ListElement ID automatically when you use Property::SetListElements to update a List property.

Modifying the List Property of an Attribute

The ListElement object is important if you are using the Agile Administrator API to modify the List property of an Agile Advantage attribute. For example, you can use the Agile Advantage API to modify Change Category list values for the “Cover Page.Change Category” attribute.

Unlike other types of properties, the List property of an Attribute cannot be modified using Property::SetValue. Instead, you must use Property::SetListElements.

To modify the List property of an Attribute:

1 Retrieve the List property for an Attribute.

2 Use Property::ListElements to retrieve the read-only Collection of ListElement objects for a List property.

3 Create a new Collection object and use Collection::SetDataType(dtObject) to set its data type.

4 Copy the ListElement objects from the Collection returned by Property::ListElements to the new editable Collection you created. Use Collection::Get to retrieve an object from the read-only Collection. Use Collection::Add to add an object to the editable Collection.

5 To add a new value to the list, create a new ListElement object and use ListElement::Value to set its value. Use Collection::Add to add the new ListElement object to the editable Collection.

6 To remove a value from the list, use Collection::Remove.

6-125


7 Use Property::SetListElements to save the list. Specify the editable Collection object, which contains ListElement objects, as the value parameter.

Hierarchy

❑ Base ❑ ListElement

Properties

Table 6-16: ListElement properties


ID LONG Read-only Returns the unique identifier of the list element.

IsObsolete BOOL Read-only Returns a nonzero value if the list element is obsolete and cannot be set as the property value. Otherwise, it returns 0. A list element is obsolete when it has been removed from the list in Agile Administrator.

Value BSTR Read/Write Sets or gets the string value of the list element.

Note: You cannot set the value of an internally created ListElement object.


Chapter 6 Agile Advantage API Reference – Mfr

MfrOverview

A Manufacturer. To work with a Mfr object, use methods and properties of DataObject.

Mfr is an externally creatable object. However, when you use the constructor to create a Mfr object in your program, it is an empty object that is not associated with an Agile Advantage eHub. To work with an existing Manufacturer, you need to use Mfr::LoadByAttr or Mfr::LoadByInfo to load a Manufacturer from an Agile Advantage eHub. To create a new Manufacturer on an Agile Advantage eHub, use Mfr::Create.

Hierarchy

❑ Base❑ Row

❑ DataObject❑ Mfr

Methods

Create

LoadByAttr

LoadByInfo

Mfr::Create()

Syntax

BOOL Create(LPDISPATCH server,const VARIANT FAR& subClass,LPCTSTR name)

Description

Creates a Mfr (a Manufacturer) using the specified subclass.

Parameters

server

a pointer to a Server object used to initialize the new Mfr

subclass


6-127


name

name of the new Manufacturer

Returns


Example

Public server As AgileAPI.ServerPublic currMfr As AgileAPI.Mfr

Private Sub cmdCreateMfr_Click()

Dim b As Boolean

Set currMfr = CreateObject("AgileAPI.Mfr") b = currMfr.Create(server, "Manufacturer", txtName.Text) If Not b Then MsgBox "Failed to create object. " + currMfr.ErrorMessage End If

End Sub

Mfr::LoadByAttr()

Syntax


Description

Loads an existing Mfr into the object by specifying an attribute and its value.

Parameters

server

a pointer to a Server object used to initialize the Mfr

attr

a fully qualified attribute, such as “General Info.Address,” or a base ID. You can also type 0 to use the default attribute, “General Info.Name.” For lists of attributes for each Agile Advantage class, see “” on page 6-261.


Chapter 6 Agile Advantage API Reference – Mfr

value


Returns


Example

Public server As AgileAPI.ServerPublic currMfr As AgileAPI.Mfr

Private Sub GetMfr_Click()

Dim b As Boolean

Set currMfr = CreateObject("AgileAPI.Mfr") b = currMfr.LoadByAttr(server, 0, txtNumber.Text) If Not b Then MsgBox "Failed to get object. " + currMfr.ErrorMessage End If

End Sub

Mfr::LoadByInfo()

Syntax


Description

Loads an existing Mfr (a Manufacturer) into the object by specifying an ObjectInfo object that uniquely identifies it. The specified ObjectInfo object must have TargetID and TargetType members.

Parameters

server

a pointer to a Server object used to initialize the Mfr

info

a reference to an ObjectInfo object that uniquely identifies the Mfr

6-129


Returns


Example



Chapter 6 Agile Advantage API Reference – MfrPart

MfrPartOverview

A Manufacturer Part. To work with a MfrPart object, use methods and properties of DataObject.

MfrPart is an externally creatable object. However, when you use the constructor to create a MfrPart object in your program, it is an empty object that is not associated with an Agile Advantage eHub. To work with an existing Manufacturer Part, you need to use MfrPart::LoadByAttr or Mfr::LoadByInfo to load a Manufacturer Part from an Agile Advantage eHub. To create a new Manufacturer Part on an Agile Advantage eHub, use MfrPart::Create.

Hierarchy

❑ Base❑ Row

❑ DataObject❑ MfrPart

Properties

Methods

Create

LoadByAttr

LoadByInfo

MfrPart::Create()

Syntax

BOOL Create(LPDISPATCH server,const VARIANT FAR& subClass,

Table 6-17: MfrPart properties


Mfr LPDISPATCH Read-only Returns a pointer to the Mfr associated with this MfrPart.

6-131


LPCTSTR mfrName,LPCTSTR number)

Description

Creates a MfrPart (a Manufacturer Part) using the specified subclass.

Parameters

server

a pointer to a Server object used to initialize the new MfrPart

subclass


name

Manufacturer name

number

number of the new Manufacturer Part

Returns


Example

Public server As AgileAPI.ServerPublic currMfrPart As AgileAPI.MfrPart

Private Sub cmdCreateMfrPart_Click()

Dim b As Boolean

Set currMfrPart = CreateObject("AgileAPI.MfrPart") b = currMfrPart.Create(server, "Manufacturer Part", _ txtMfrName.Text, txtNumber.Text) If Not b Then MsgBox "Failed to create object. " + currMfrPart.ErrorMessage End If

End Sub


Chapter 6 Agile Advantage API Reference – MfrPart

MfrPart::LoadByAttr()

Syntax


Description

Loads an existing MfrPart into the object by specifying an attribute and its value.

Parameters

server

a pointer to a Server object used to initialize the MfrPart

attr

a fully qualified attribute, such as “General Info.Description,” or a base ID. You can also type 0 to use the default attribute, “General Info.Manufacturer Part Number.” For lists of attributes for each Agile class, see “” on page 6-261.

Note You cannot use the attribute “General Info.Manufacturer Name” or base ID 1647 to load a MfrPart.

value

a value for the specified attribute; if attr is 0 or 1648 (“General Info.Manufacturer Part Number”), the value must consist of a ManufacturerName::PartNumber pair

Returns


Example

Public server As AgileAPI.ServerPublic currMfrPart As AgileAPI.MfrPart

Private Sub GetMfrPart_Click()

Dim b As Boolean

Set currMfrPart = CreateObject("AgileAPI.MfrPart") b = currMfrPart.LoadByAttr(server, 0, txtMfrName.Text + "::" + _ txtNumber.Text)

6-133


If Not b Then MsgBox "Failed to get object. " + currMfrPart.ErrorMessage End If

End Sub

MfrPart::LoadByInfo()

Syntax


Description

Loads an existing MfrPart (a Manufacturer Part) into the object by specifying an ObjectInfo object that uniquely identifies it. The specified ObjectInfo object must have TargetID and TargetType members.

Parameters

server

a pointer to a Server object used to initialize the MfrPart

info

a reference to an ObjectInfo object that uniquely identifies the MfrPart

Returns


Example



Chapter 6 Agile Advantage API Reference – Node

NodeOverview

A node in the Agile Administrator tree. For example, in Figure 6-1 the Agile Database root node is selected.

Figure 6-1: Agile Administrator Tree View

Examples of nodes are Agile Database (the root node), Agile Classes, Preferences, Roles and Privileges, and SmartRules. Many nodes also have child nodes, which is why the node structure is called a tree view in Agile Administrator.

To retrieve a specific Agile Administrator node, use Server::GetNode.

The Agile Advantage API provides read/write access to subnodes of the Agile Classes and Users nodes. You can use the Agile Advantage API to read and modify Agile Advantage subclasses, and add, modify, or delete Agile Advantage users. All other Agile Administrator nodes and their properties are read-only.

Note To modify a subnode of the Agile Classes or Users nodes, you must have Administrator privileges and log in to the Agile eHub using Server::LoginEx.

Hierarchy

❑ Base

6-135


❑ Node

Properties

Methods

CreateUser

Delete

Node::CreateUser()

Syntax

LPDISPATCH CreateUser(LPCTSTR name,LPCTSTR userName)

Description

Creates a new Agile Advantage user with blank passwords. To assign initial passwords for the user, use User::ChangePassword. The new user is automatically assigned a Full Agile user license, which is required to log in to an Agile Advantage ADK client application.

CreateUser is available only if you log in using Server::LoginEx. You must also have Administrator privileges to the Agile Advantage system.

Parameters

name

the name of the user (29 characters maximum). The name appears in the Agile Administrator user interface. It is not used to log in to the Agile Advantage system. Therefore, it can be any combination of uppercase or lowercase characters. It can also include both the user’s first and last names.

Table 6-18: Node properties


ChildNodes LPDISPATCH. Read-only Returns a Collection object containing all child Node objects of the current Node.

Name BSTR Read-only Returns the name of the node.

Properties LPDISPATCH Read-only Returns a Collection object containing all Property objects for the node.

Type NodeTypeConstants Read-only Returns one of the Node type constants (see page 6-429).


Chapter 6 Agile Advantage API Reference – Node

userName

the user’s login name for the Agile Advantage system (99 characters maximum). User names are not case-sensitive. The user name you specify must be unique. Otherwise, the CreateUser method fails.

Returns

A pointer to the newly created User object.

Node::Delete()

Syntax

BOOL Delete()

Description

Deletes an Agile Advantage user. The Node object must be a User. You cannot use Delete to delete other types of Node objects.

Delete is available only if you log in using Server::LoginEx. You must also have Administrator privileges to the Agile Advantage system.

Returns

Nonzero if the method was successful; 0 otherwise

6-137


ObjectInfoOverview

Provides a record that uniquely identifies an Agile Advantage API object. You can use ObjectInfo to find information about an object (for example, its target type or class ID) without creating an instance of the object. You can also use ObjectInfo as an input parameter to Server::GetObject to retrieve an object.

ObjectInfo is an externally creatable object. You can create a new ObjectInfo object and then set its properties. You can also return the ObjectInfo for an object (such as an Item or Change) using Base::GetObjectInfo.

Hierarchy

❑ Base❑ ObjectInfo

Properties

Table 6-19: ObjectInfo properties


ClassID LONG Read/Write Sets and gets the class ID for the target object. The Agile system has a set number of classes, which are listed in the class type constants. (see page 6-298). You cannot create new classes, but you can define new subclasses.

Mask ObjectInfoMask-Constants

Read/Write Sets or gets the mask used to specify the data members of ObjectInfo that are valid for this object. See “ObjectInfo Mask Constants” on page 6-434.

SubClassID LONG Read/Write Sets or gets the subclass ID for the object.

TargetID LONG Read/Write Sets or gets the object ID for the object.

TargetType ObjectTypeConstants Read/Write Sets or gets the object type for the target object. See “Object Type Constants” on page 6-432.


Chapter 6 Agile Advantage API Reference – Package

PackageOverview

A collection of data that describes a a proposed product. A Package includes some basic information about the proposed product as well as attached files. The attachments might include specifications, schematics, assembly drawings, test procedures, or any other file type required. A Package is different from other Agile Advantage objects for the following reasons:

❑ It has no relationship to any other Agile Advantage object.❑ It does not have a revision level.❑ You can not write Changes against it.❑ It has no Manufacturers tab.❑ It has no Bill of Material.

Package is an externally creatable object. However, when you use the constructor to create a Package object in your program, it is an empty object that is not associated with an Agile Advantage eHub. To work with an existing Package, you need to use Package::LoadByAttr or Package::LoadByInfo to load a Package from an Agile Advantage eHub. To create a new Package on an Agile Advantage eHub, use Package::Create.

Hierarchy

❑ Base❑ Row


❑ Package

Methods

Create

LoadByAttr

LoadByInfo

Package::Create()

Syntax

BOOL Create(LPDISPATCH server,

6-139


const VARIANT FAR& subClass,LPCTSTR number)

Description

Creates a new Package using the specified subclass. A package is a collection of product data.

Parameters

server

a pointer to a Server object used to initialize the new Package

subclass


number

number of the new Package

Returns


Example

Public server As AgileAPI.ServerPublic currPkg As AgileAPI.Package

Private Sub cmdCreatePkg_Click()

Dim b As Boolean

Set currPkg = CreateObject("AgileAPI.Package") b = currPkg.Create(server, "Package", txtNumber.Text) If Not b Then MsgBox "Failed to create object. " + currPkg.ErrorMessage End If

End Sub

Package::LoadByAttr()

Syntax

BOOL LoadByAttr(LPDISPATCH server,


Chapter 6 Agile Advantage API Reference – Package

const VARIANT FAR& attr,const VARIANT FAR& value)

Description

Loads an existing Package, a collection of product data, into the object by specifying an attribute and its value.

Parameters

server

a pointer to a Server object used to initialize the Package

attr

a fully qualified attribute, such as “Cover Page.Description,” or a base ID. You can also type 0 to use the default attribute, “Cover Page.Package Number.” For lists of attributes for each Agile Advantage class, see “” on page 6-261.

value


Returns


Example

Public server As AgileAPI.ServerPublic currPkg As AgileAPI.Package

Private Sub GetPackage_Click()

Dim b As Boolean

Set currPkg = CreateObject("AgileAPI.Package") b = currPkg.LoadByAttr(server, 0, txtNumber.Text) If Not b Then MsgBox "Failed to get object. " + currPkg.ErrorMessage End IfEnd Sub

6-141


Package::LoadByInfo()

Syntax


Description

Loads an existing Package, a collection of product data, into the object by specifying an ObjectInfo object that uniquely identifies it. The specified ObjectInfo object must have TargetID and TargetType members.

Parameters

server

a pointer to a Server object used to initialize the Package

info

a reference to an ObjectInfo object that uniquely identifies the Package

Returns


Example



Chapter 6 Agile Advantage API Reference – PrintOption

PrintOptionOverview

Contains property settings for the Agile Advantage Viewer, including the banners (headers and footers) and watermark printed with each file. You can use PrintOption to retrieve current print options for an attachment using Attachment::GetPrintOption. You can also modify the individual PrintOption properties.

PrintOption is an externally creatable object. After you create a PrintOption object, you can set its properties, then use it to print a file.

PrintOption properties correspond to Agile Advantage Viewer preferences you can set in Agile Administrator. You can set banner and watermark properties for each class of object.

In your program’s user interface, you can retrieve the default PrintOption settings from Agile Administrator using Attachment::GetPrintOption and display them in a dialog box, as shown in Figure 6-2.

Figure 6-2: Sample Print Options dialog box

Hierarchy

❑ Base ❑ PrintOption

6-143


Properties

When you specify a string for any of the PrintOption properties, you can use the variables shown in Table 6-21.

Table 6-20: PrintOption properties


LeftHeader BSTR Read/Write Text that appears in the left portion of the header.

MidHeader BSTR Read/Write Text that appears in the center portion of the header.

RightHeader BSTR Read/Write Text that appears in the right portion of the header.

LeftFooter BSTR Read/Write Text that appears in the left portion of the footer.

MidFooter BSTR Read/Write Text that appears in the center portion of the footer.

RightFooter BSTR Read/Write Text that appears in the right portion of the footer.

ShowRedlines BOOL Read/Write Sets or gets whether a printed attachment should show redlines.

Note: To determine whether an Attachment has redlines, use Row::GetStatus.

Watermark BSTR Read/Write Watermark text that appears on each printed page of an Attachment.

Table 6-21: PrintOption variables

Variable Description

%User% User name.

%Date% Current date.

%Status% Current status of the object that contains the attachment.

%ItemNumber% Depending on the object containing the attachment, either its number or name:

For Item objects, %ItemNumber% = Item number

For Change objects, %ItemNumber% = Change number

For Mfr objects, %ItemNumber% = Manufacturer name

For MfrPart objects, %ItemNumber% = MfrName MfrPartNumber(a space separates the MfrName and MfrPartNumber strings)


Chapter 6 Agile Advantage API Reference – PrintOption

PrintOption variables must be enclosed by percent signs (%). You can use multiple variables and place a variable in any position in a PrintOption header or footer string.

Example

To create a PrintOption object in Visual Basic, use the CreateObject method:

Dim po As AgileAPI.PrintOptionSet po = CreateObject("AgileAPI.PrintOption")

After you create or get a PrintOption object, you can set its properties:

po.LeftHeader = "Printed by %User%"po.RightHeader = "Date printed: %Date%"po.LeftFooter = "Number: %ItemNumber%"po.RightFooter = "Confidential"

%Page% Current page of the printout.

%Rev% Current revision of the object that contains the attachment. For Change, Mfr, and MfrPart objects, %Rev% is equivalent to %Status%.

Table 6-21: PrintOption variables

Variable Description

6-145


PropertyOverview

A row in the Agile Administrator property view. Each Node in Agile Administrator can have multiple Property objects. Some Property objects are not visible in the Agile Administrator user interface even though they can be retrieved using the Agile Advantage API.

Figure 6-3: Agile Administrator Property View

Property, unlike Field, is a persistent property stored in a table in the Agile Advantage database. Field, which is not persistent, is simply an instance of an Attribute.

The data types for Property and Field are different. For a list of Property types, see “Property Type Constants” on page 6-491.

Hierarchy

❑ Base ❑ Property

Property View


Chapter 6 Agile Advantage API Reference – Property

Properties

Table 6-22: Property properties


DisplayString BSTR Read-only Returns the string that appears in the second column of the property view in Agile Administrator. This display string can be different from the actual value for the Property if its type is not ptString. For example, for list properties (Type = ptSingleList) the display string is “(List).”

ID LONG Read-only Returns the Property’s ID number.

IsReadOnly BOOL Read-only Returns a nonzero value if the Property is read-only and cannot be modified. Otherwise, it returns 0.

Note: The Agile Advantage API allows you to modify Agile Advantage Classes and User node properties only. Other Agile Administrator node properties cannot be modified even if they are not read-only

ListElements LPDISPATCH Read-only Returns a read-only Collection object for properties of type ptSingleList or ptMap. For properties of type ptSingleList, the method returns a Collection of ListElement objects. For properties of type ptMap, the method returns a collection of String objects. For other property types, ListElements returns an empty Collection.

ListID LONG Read-only Returns the list ID number for a Property whose Type is ptSingleList. For Property objects whose Type is not ptSingleList, ListID returns 0.

Name BSTR Read-only Returns the Property’s name.

6-147


Methods

GetValue

SetListElements

SetValue

Property::GetValue()

Syntax

BOOL GetValue(VARIANT FAR* value)

Description

Retrieves the value of a Property object, an Agile Administrator property.

The data type of value depends on the data type of the Property object (Property::Type), as shown in Table 6-23.

If no value is currently selected for a SingleList field, GetValue returns an empty Collection object (Collection::Count = 0).

Parameters

value

an output parameter that returns the Property value

Returns


Type PropertyType-Constants

Read-only Returns the Property’s type. See “Property Type Constants” on page 6-491.

Table 6-23: Data types of Property values

Property::Type value Variant Data Type

ptString VT_BSTR (a string)

ptInteger VT_I4 (an integer)

ptDate VT_DATE (a date)

ptMap VT_DISPATCH (a Collection of one or more strings)

ptSingleList VT_DISPATCH (a Collection of one ListElement)

Table 6-22: Property properties




Example

Public Sub GetIconMotif()

Dim genPrefNode As AgileAPI.Node Dim prop As AgileAPI.Property Dim b As Boolean Dim vValue As Variant

'Get the General Preferences node Set genPrefNode = server.GetNode(nidGeneral)

'Get the Icon Motif property Set prop = genPrefNode.Properties.Find("IconMotif")

'Get the Icon Motif property value b = prop.GetValue(vValue) If Not b Then MsgBox "Unable to get Icon Motif value. " + prop.ErrorMessage Else MsgBox "Icon Motif = " + vValue.Get(0).Value End If

End Sub

Property::SetListElements()

Syntax

BOOL SetListElements(LPDISPATCH value)

Description

Sets the available values for a List Property. The Property type must be either ptSingleList or ptMap; SetListElements cannot be used for other Property types.

You can use Property::ListElements to retrieve a read-only Collection of ListElement objects for the Property. For more information on how to modify a List Property, see “ListElement” on page 6-125.

Note SetListElements is available only if you log in using Server::LoginEx. You must also have Administrator privileges to the Agile Advantage system.

Parameters

value

a Collection object containing ListElement objects

6-149


Returns


Example

Public Sub AddToListProperty(ListProp As AgileAPI.Property)

Dim colCurValues As AgileAPI.Collection Dim colNewValues As AgileAPI.Collection Dim le As AgileAPI.ListElement Dim index As Long

Set colCurValues = ListProp.ListElements Set colNewValues = CreateObject("AgileAPI.Collection) colNewValues.SetDataType(dtObject)

'Populate the collection with the list’s current values For i = 0 to colCurValues.Count - 1 colNewValues.Add(colCurValues.Get(i), -1) Next i

'Add a new ListElement for "foobar" to the collection Set le = CreateObject("AgileAPI.ListElement") le.Value = "foobar" index = colNewValues.Add(le, -1)

'Set the value of the Property b = ListProp.SetListElements(colNewValues)

End Sub

Property::SetValue()

Syntax

BOOL SetValue(const VARIANT FAR& value)

Description

Sets the value for a Property. You can set property values only for Agile Classes and Users node properties. Other Agile Administrator nodes are read-only.

You cannot use SetValue to change the list of values for a List Property. Use Property::SetListElements instead.



Note SetValue is available only if you log in using Server::LoginEx. You must also have Administrator privileges to the Agile Advantage system.

Parameters

value

new property value to set

Returns


6-151


QueryOverview

A query, or Search, in the Agile Advantage system.

Query is an externally creatable object. However, when you use the constructor to create a Query object in your program, it is an empty object that is not associated with an Agile Advantage eHub. To work with an existing query, you need to use Query::LoadByInfo to load a query from an Agile Advantage eHub. To create a new query on an Agile Advantage eHub, use Query::Create.

A query can return a large data set for its results, which can take a long time to process at the Agile Advantage eHub. You can restrict the size of the query results to a range of rows (using Query::ResultRange and Query::ResultStart), thereby fetching the results faster and using less memory.

Hierarchy

❑ Base❑ Query

Properties

Table 6-24: Query properties


Attributes LPDISPATCH Read-only Returns the Collection of available query attributes. For lists of attributes for each Agile class, see “” on page 6-261.

CriteriaCount LONG Read-only Returns the total number of search conditions.

IsCaseSensitive BOOL Read/Write Sets or gets whether a query is case-sensitive. A nonzero value indicates that the query is case-sensitive.

Owner BSTR Read-only Returns the full name of the query owner.


Chapter 6 Agile Advantage API Reference – Query

ResultCacheSize LONG Read-only Returns the maximum number of records returned for each executed query. This property equivalent to Preferences | General | Maximum Query Results Displayed in Agile Administrator. The default value is 1000.

ResultCount LONG Read-only Returns the number of records in the query results list minus the value specified for ResultStart.

ResultMissingCount LONG Read-only Returns the number of records missing from the query results list due to the user’s lack of the Discovery privilege for those objects.

Results LPDISPATCH Read-only Returns a Collection of query results.

ResultStart LONG Read/Write Sets or gets the number of the first row in the query result range (0 or greater). If the start of the result range is greater than the result count, the query returns no results (Results returns an empty Collection).

ResultRange LONG Read/Write Sets or gets the number of rows in the query result range. 0 means all rows are in the result range. If the range is greater than the result count, the query returns the result count. The default ResultRange value is 1000.

Table 6-24: Query properties


6-153


Methods

Query::Abort()

Syntax

BOOL Abort()

Description

Cancels all changes made to the query.

Returns


Example

Public Sub AbortChanges(query As Object)

'Cancel all changes If Not query.Abort Then MsgBox "Failed to abort." + query.ErrorMessage End If

End Sub

Abort GetType

AddCriteria GetWhereUsedType

ClearCache LoadByInfo

Create Refresh

Delete Save

DeleteCriteria SaveAs

Execute SetClass

GetAttrValues SetCriteriaData

GetClass SetName

GetCriteriaData SetResultDisplay

GetLogicalOperators SetType

GetName SetWhereUsedType

GetRelationalOperators VbsGetCriteriaData

GetResultDisplay



Query::AddCriteria()

Syntax

LONG AddCriteria(const VARIANT FAR& attr,LONG relOp,LPCTSTR value,LONG logicOp,LONG leftParen,LONG rightParen)

Description

Adds a new search condition to end of list.

Note If you specify no criteria, Query::Execute returns all records in the specified class.

Parameters

attr

a fully qualified search attribute, such as “Title Block.Description,” or the base ID of an attribute. For lists of attributes for each Agile class, see “” on page 6-261.

relOp

relational operator constant used for the search condition, for example, qroStartsWith or qroContains. See “Query Relational Operator Constants” on page 6-517.

value

value to search for (2000 characters maximum)

logicOp

logical operator constant used for the search condition; can be qloAnd, qloOr, or qloNone. See “Query Logical Operator Constants” on page 6-516.

leftParen

number of left parentheses before the search condition

rightParen

number of right parentheses at the end of the search condition

6-155


Returns

The index number of the new search condition if the method was successful; otherwise -1.

Example

See “Query::Create()” on page 6-157.

Query::ClearCache()

Syntax

void ClearCache()

Description

Clears the query result set from the Agile eHub cache. This forces the query to process the complete result set the next time you run the query using Execute.

The Agile Advantage API supports partial queries. After you use Execute to run a query for the first time, the complete result set is stored in the Agile Advantage eHub cache. In your client program, you can then run partial queries of the result set by specifying the Result Start and Result Range values (using Query::ResultStart and Query::ResultRange).

Example

Public Sub ResetQuery(query As Object)

Dim b As Boolean

'Clear the current query results query.ClearCache

'Run the query again b = query.Execute If Not b Then MsgBox "Unable to run the query. " + query.ErrorMessage End If

End Sub



Query::Create()

Syntax

BOOL Create(LPDISPATCH server)

Description

Creates a new Query, also called a Search.

Parameters

server

a pointer to a Server object used to initialize the new Query

Returns


Example

Public server As AgileAPI.ServerPublic col as AgileAPI.CollectionPublic query As AgileAPI.Query

Private Sub Find_Click()

Dim number As Variant Dim desc As Variant Dim attrID As Long Dim b As Boolean

'Create a query that finds objects containing the specified 'text in their Number. Set query = CreateObject("AgileAPI.Query") b = query.Create(server)

attrID = aidParts_TitleBlock_Number query.SetClass(ctItem) l = query.AddCriteria(attrID, qroContains, txtNumber.Text, qloNone, 0, 0) b = query.Execute Set col = query.Results

'Display the query results in the Results list view. 'The list view has two columns, Number and Description. lvwResults.ListItems.Clear For i = 0 To col.Count - 1 Set object = col.Get(i)

6-157


attrID = aidParts_TitleBlock_Number b = object.GetValue(attrID, number) attrID = aidParts_TitleBlock_Description b = object.GetValue(attrID, desc) Set li = lvwResults.ListItems.Add(, , number) li.SubItems(1) = desc Next i

End Sub

Query::Delete()

Syntax

BOOL Delete()

Description

Deletes a Query from the database. When you create a Query using Query::Create, the object is automatically saved. If you do not remove a Query using Delete, it remains in the database even though you did not specifically save it using Query::Save or Query::SaveAs. If you do not want to save a “temporary” Query, you must explicitly delete it. Otherwise, unwanted Query objects will accumulate in the database.

Returns


Example

Public Sub PromptSave(query As Object)

Dim intResponse As Long

intResponse = MsgBox("Do you want to save the query?", vbYesNo) If intResponse = vbYes Then query.Save Else query.Delete End If End Sub



Query::DeleteCriteria()

Syntax

BOOL DeleteCriteria(LONG index)

Description

Deletes the search condition at the specified position.

Parameters

index

index number of the search condition to delete; for example, type 0 to delete the first search condition

Returns


Example

Private Sub Delete_Click()

If Query.DeleteCriteria(lvwCriteria.SelectedItem.Index - 1) Then lvwCriteria.ListItems.Remove Criteria.SelectedItem.Index Else MsgBox "Failed to delete criteria. " + Query.ErrorMessage End If

End Sub

Query::Execute()

Syntax

BOOL Execute()

Description

Runs the query.

Note If you specify no criteria, the query returns all records in the specified class.

Returns


6-159


Example


Query::GetAttrValues()

Syntax

BOOL GetAttrValues(const VARIANT FAR& attr,LPDISPATCH col)

Description

Returns a Collection containing the available values for a specified search attribute (such as “Title Block.Lifecycle Phase”). If you are creating a Search dialog box in your program, you can use the GetAttrValues method to populate the Value field with valid values for a particular search attribute.

Parameters

attr

a fully qualified search attribute, such as “Title Block.Lifecycle Phase,” or the base ID of an attribute. The attribute should be of type dtSingleList or dtMultiList. Use Attribute::DataType to return the data type of a particular attribute.

col

an output parameter that returns the Collection of valid string values for a SingleList or MultiList attribute. col must point to an existing Collection object; it cannot be Null. If the attribute is not a SingleList or MultiList attribute, the Collection is empty.

Returns


Query::GetClass()

Syntax

LONG GetClass()

Description

Retrieves the object class to query on. To set the class to query on, use Query::SetClass.



Returns

The ID number of the object class.

Example

Public Query As AgileAPI.QueryPublic col As AgileAPI.Collection

Sub DisplayResults() 'Set col equal to the collection of query results Set col = Query.Results

'If querying on the Document or Part class, then call 'the FillItemResults procedure. Otherwise, call FillChangeResults. If Query.GetClass = ctItemDocument Or Query.GetClass = ctItemPart Then Call FillItemResults Else Call FillChangeResults End IfEnd Sub

Query::GetCriteriaData()

Syntax

BOOL GetCriteriaData(LONG index,LONG FAR* attrID,LONG FAR* relOp,BSTR FAR* value,LONG FAR* logicOp,LONG FAR* leftParen,LONG FAR* rightParen)

Description

Retrieves the search condition at the specified position.

Parameters

index

index number of the search condition to retrieve; for example, type 0 to retrieve the first search condition

attrID

an output parameter that returns the base ID of the attribute. For lists of attributes for each Agile class, see “” on page 6-261.

6-161


relOp

an output parameter that returns the relational operator constant used for the search condition. See “Query Relational Operator Constants” on page 6-517.

value


logicOp

an output parameter that returns the logical operator constant used for the search condition; can be qloAnd, qloOr, or qloNone. See “Query Logical Operator Constants” on page 6-516.

leftParen


rightParen

an output parameter that returns the number of right parentheses at the end of the search condition

Returns


Example

Public Query As AgileAPI.Query

Private vAttrID As LongPrivate vRelOp As QueryRelationalOperatorConstantsPrivate vValue As StringPrivate vLogicOp As QueryLogicalOperatorConstantsPrivate vLeftParen As Long, vRightParen As LongPrivate Index As Long

Private Sub SetCriteriaListItem(li As listitem, Index As Long)

If Query.GetCriteriaData(Index, vAttrID, vRelOp, vValue, _ vLogicOp, vLeftParen, vRightParen) Then li.text = CStr(vLeftParen) li.SubItems(1) = Query.Attributes.Find(vAttrID).Name li.SubItems(2) = RelOpToString(vRelOp) li.SubItems(3) = vValue li.SubItems(4) = LogicOpToString(vLogicOp) li.SubItems(5) = CStr(vRightParen)



Else li.text = "" End If

End Sub

Query::GetLogicalOperators()

Syntax

BOOL GetLogicalOperators(const VARIANT FAR& attr,LPDISPATCH col)

Description

Retrieves the logical operators for a specified attribute.

Parameters

attr

a fully qualified search attribute, such as “Title Block.Description,” or the base ID of the attribute. For lists of attributes for each Agile class, see “” on page 6-261.

col

an output parameter that returns a pointer to a Collection containing ListElement objects. col must point to an existing Collection object; it cannot be Null. To retrieve a logical operator ID, get the ListElement::ID property. To retrieve a logical operator name, get the ListElement::Name property.

Returns


Example


Private Sub FillLogicOp(AttrID As Long)

Dim b As Boolean Dim col As AgileAPI.Collection

'Create a collection Set col = CreateObject("AgileAPI.Collection")

6-163


'Get the logical operators for the specified attribute b = Query.GetLogicalOperators(AttrID, col)

' Populate the Logical Operators list lstLogicOp.Clear lstLogicOp.AddItem LogicOpToString(qloNone), 0 lstLogicOp.ItemData(i) = qloNone For i = 0 To col.count - 1 lstLogicOp.AddItem col.Get(i).Name, i lstLogicOp.ItemData(i) = col.Get(i).ID Next i

End Sub

Query::GetName()

Syntax

BSTR GetName()

Description

Retrieves the query name. This is equivalent to the query description that appears in the Agile Advantage Windows client Search window. To set the query name, use Query::SetName.

Returns

A string description of the query.

Example


'Code for Query Name formPrivate Sub Form_Activate() 'Get the current query name and fill the Name field with it txtName.Text = Query.GetName

End Sub


If Not Query.SetName(txtName.Text) Then MsgBox "Failed to set the query name." + Query.ErrorMessage End If

End Sub



Query::GetRelationalOperators()

Syntax

BOOL GetRelationalOperators(const VARIANT FAR& attr,LPDISPATCH col)

Description

Retrieves the relational operators for a specified attribute.

Parameters

attr

a fully qualified search attribute, such as “Title Block.Description,” or the base ID of an attribute. For lists of attributes for each Agile class, see “” on page 6-261.

col

an output parameter that returns a pointer to a Collection containing ListElement objects. col must point to an existing Collection object; it cannot be Null. To retrieve a relational operator ID, get the ListElement::ID property. To retrieve a relational operator name, get the ListElement::Name property.

Returns


Example


Private Sub FillRelOp(AttrID As Long)

Dim b As Boolean Dim col As AgileAPI.Collection


'Get the relational operators for the specified attribute b = Query.GetRelationalOperators(AttrID, col)

'Populate the Relational Operators list lstRelOp.Clear For i = 0 To col.count - 1 lstRelOp.AddItem col.Get(i).Name, i

6-165


lstRelOp.ItemData(i) = col.Get(i).ID Next i

End Sub

Query::GetResultDisplay()

Syntax

BOOL GetResultDisplay(LPDISPATCH FAR* ids,LPDISPATCH FAR* widths)

Description

Retrieves the list of attributes and width values used to display the query results in a graphical user interface (GUI).

Parameters

ids

an output parameter that returns the collection of base IDs for the columns that appear in the result display. ids must point to an existing Collection object; it cannot be Null. For lists of attributes for each Agile Advantage class, see “” on page 6-261.

width

an output parameter that returns the collection of width values for the columns that appear in the result display. width must point to an existing Collection object; it cannot be Null.

Returns


Example

See “Query::SetResultDisplay()” on page 6-172.

Query::GetType()

Syntax

long GetType()

Description

Returns the query type (Private, Public, or System).



Returns

One of the Query type constants (see page 6-518).

Example

Dim i As Long

'If the query is a System query, disable the Save buttonIf query.GetType = qtSystem Then cmdSave.Enabled = FalseEnd If

Query::GetWhereUsedType()

Syntax

WhereUsedTypeConstants GetWhereUsedType()

Description

Retrieves the type of where-used query being used. For more information about where-used queries, see Query::SetWhereUsedType.

Returns

One of the Where Used type constants (see page 6-552).

Query::LoadByInfo()

Syntax


Description

Loads an existing Query into the object by specifying an ObjectInfo object that uniquely identifies it. The specified ObjectInfo object must have a TargetID member.

Parameters

server

a pointer to a Server object used to initialize the Query

info

a reference to an ObjectInfo object that uniquely identifies the Query

6-167


Returns


Example

Public server As AgileAPI.ServerPublic gsfolder As AgileAPI.Folder 'Global Searches folder

Public Sub GetAllChangesQuery(gsfolder As Object)

Dim folder As AgileAPI.Folder Dim info As AgileAPI.ObjectInfo Dim query As AgileAPI.Query


'Create a Query object Set query = CreateObject("AgileAPI.Query")

'Get the All Changes query For i = 0 To gsfolder.ItemCount - 1 If gsfolder.GetItemName(i) = "All Changes" Then b = gsfolder.GetItemInfo(i, info) b = query.LoadByInfo(server, info) End If Next i

End Sub

Query::Refresh()

Syntax

BOOL Refresh()

Description

Refreshes both the Query object and the query results table, making the data current with the latest information from the server.

Returns


Example

Public query As AgileAPI.Query



Private Sub cmdRefresh_Click()

Dim b As Boolean

b = query.Refresh If Not b Then MsgBox "Unable to refresh query. " + query.ErrorMessage End If

End Sub

Query::Save()

Syntax

BOOL Save()

Description

Saves changes made to the query since the last save.

Note When you create a query using Query::Create, the object is automatically saved.

Returns


Example

See “Query::Delete()” on page 6-158

Query::SaveAs()

Syntax

long SaveAs(LPCTSTR name)

Description

Saves the Query with a different name.

Parameters

name

name of the Query

Returns

The Query ID number, which can be used to get the Query again later.

6-169


Example


Dim id As Long

id = query.SaveAs(txtQueryName.Text) End Sub

Query::SetClass()

Syntax

BOOL SetClass(LONG classID)

Description

Sets the object class to query on. You can query on a class or a subclass. Use SubClass::SubClassID to get the ID number of a subclass.

Note For each query, a class must be set. To access Page Two and Page Three attributes in the query results, specify a subclass ID.

Parameters

classID

ID of the class or subclass to query on. You can also enter a class type constant. See “Class Type Constants” on page 6-298.

Returns


Example


Query::SetCriteriaData()

Syntax

BOOL SetCriteriaData(LONG index,const VARIANT FAR& attr,LONG relOp,LPCTSTR value,LONG logicOp,LONG leftParen,



LONG rightParen)

Description

Modifies the search condition at the specified position.

Parameters

index

index number of the search condition

attr

a fully qualified search attribute, such as “Title Block.Description,” or the base ID of an attribute. For lists of attributes for each Agile Advantage class, see “” on page 6-261.

relOp

relational operator constant used for the search condition, for example, qroStartsWith or qroContains. See “Query Relational Operator Constants” on page 6-517.

value

value to search for (2000 characters maximum)

logicOp

logical operator constant used for the search condition; can be qloAnd, qloOr, or qloNone. See “Query Logical Operator Constants” on page 6-516.

leftParen

number of left parentheses before the search condition

rightParen

number of right parentheses at the end of the search condition

Returns


Example


Private Sub cmdSet_Click()

Index = lvwCriteria.SelectedItem.Index - 1 b = Query.SetCriteriaData(Index, aidParts_TitleBlock_Number, _

6-171


qroContains, txtNumber.Text, qloAnd, 0, 0) If b = 0 Then MsgBox "Failed to set criteria data. " + Query.ErrorMessage End If

End Sub

Query::SetName()

Syntax

BOOL SetName(LPCTSTR name)

Description

Sets the description of the query.

Parameters

name

string describing the query (80 characters maximum)

Returns


Example

See “Query::GetName()” on page 6-164.

Query::SetResultDisplay()

Syntax

BOOL SetResultDisplay(LPDISPATCH ids,LPDISPATCH widths)

Description

Sets the list of attributes and width values used to display the query results in a graphical user interface (GUI).

To set the query result display:

1 Use Query::GetResultDisplay to get variables for column IDs and column widths.

2 Use Collection methods to modify the column IDs and column widths.

3 Use Query::SetResultDisplay to set the new result display.



Parameters

ids

collection of base IDs for the columns that appear in the result display. The base IDs must be for valid searchable attributes for the specified query class. For lists of attributes for each Agile Advantage class, see “” on page 6-261.

width

collection of width values for the columns that appear in the result display. If width is Null or it contains a different number of values than ids, the default width of 100 is used.

Returns


Example

Private Sub SetResultDisplay()

Dim li As listitem Dim colIDs As AgileAPI.Collection, colWidths As AgileAPI.Collection

If Query.GetResultDisplay(colIDs, colWidths) Then colIDs.Clear colWidths.Clear For Each li In lsvResultDisplay.ListItems colIDs.Add CLng(li.Tag), -1 colWidths.Add CLng(li.SubItems(1)), -1 Next li If Not Query.SetResultDisplay(colIDs, colWidths) Then MsgBox "Failed to set the result display. " + Query.ErrorMessage Exit Sub End If

Else MsgBox "Failed to get the result display. " + Query.ErrorMessage End If

End Sub

6-173


Query::SetType()

Syntax

BOOL SetType(long type)

Description

Sets the query type (Private or Public). You cannot change a query to System type.

Parameters

type

one of the Query Type Constants (see page 6-518)

Returns


Example

Public query As AgileAPI.Query

Public Sub CreatePrivateQuery(server As Object)

Dim b As Boolean

Set query = CreateObject("AgileAPI.Query") b = query.Create(server) b = query.SetType(qtPrivate)

End Sub

Query::SetWhereUsedType()

Syntax

BOOL SetWhereUsedType(long type)

Description

Sets the type of where-used query to use.

The Agile Advantage system supports two types of queries: an object query or a where-used query. In an object query, the search conditions define the objects to find. In a where-used query, the search conditions define the Items that appear on the BOMs of objects. A where-used query finds assemblies that have BOM Items that match the search conditions.



Parameters

type

One of the Where Used type constants (see page 6-518).

Returns


Query::VbsGetCriteriaData()

Syntax

BOOL GetCriteriaData(LONG index,VARIANT FAR* attrID,VARIANT FAR* relOp,VARIANT FAR* value,VARIANT FAR* logicOp,VARIANT FAR* leftParen,VARIANT FAR* rightParen)

Description

A VBScript-supported version of GetCriteriaData that retrieves the search condition at the specified position.

Parameters

index

index number of the search condition to retrieve; for example, type 0 to retrieve the first search condition

attrID

an output parameter that returns the base ID of the attribute. For lists of attributes for each Agile Advantage class, see “” on page 6-261.

relOp

an output parameter that returns the relational operator constant used for the search condition. See “Query Relational Operator Constants” on page 6-517.

value


6-175


logicOp

an output parameter that returns the logical operator constant used for the search condition; can be qloAnd, qloOr, or qloNone. See “Query Logical Operator Constants” on page 6-516.

leftParen


rightParen

an output parameter that returns the number of right parentheses at the end of the search condition

Returns



Chapter 6 Agile Advantage API Reference – RouteObject

RouteObjectOverview

An object that can be routed to other Agile Advantage users. Change, Package, and ServiceRequest objects derive from RouteObject and inherit its properties and methods.

Hierarchy

❑ Base❑ Row


Properties

Methods

RouteObject::AddApprovers()

Syntax

BOOL AddApprovers(long statusID,LPCTSTR approvers,LPCTSTR observers,

Table 6-25: RouteObject properties


StatusID LONG Read-only Retrieves the status ID for a routable object.

AddApprovers GetNextStatusIDs

Approve GetStatusIDs

Audit GetWorkflowID

ChangeStatus GetWorkflowIDs

Comment Reject

GetApprovers RemoveApprovers

GetDefaultNextStatusID SetWorkflowID

GetDefaultNotifyList

6-177


BOOL urgent,LPCTSTR comment)

Description

Adds users to the Signoff table for a Change (TableType = ttChangeSignoff) or a Package (TableType = ttPackageSignoff).

Parameters

statusID

status ID number for a Change or Package. Each workflow has a list of valid statuses, and each status has a unique ID number. You can retrieve the current status ID using RouteObject::StatusID. To retrieve the default next status ID, use GetDefaultNextStatusID.

approvers

semicolon-delimited list of users to add to the Approvers list (2000 characters maximum)

observers

semicolon-delimited list of users to add to the Observers list (2000 characters maximum)

urgent

a nonzero value to add an urgent icon to the mail message; otherwise, 0

comment

a string providing comments about the Change or Package (2000 characters maximum)

Returns


Example

Private Sub SetApprovers(Action As String, obj As Object)

Select Case Action

Case "Add" If Not obj.AddApprovers(obj.StatusID, txtApprovers.Text, _ txtObservers.Text, chkUrgent.Value, txtComment.Text) Then MsgBox "Failed to add approvers. " + obj.ErrorMessage Exit Sub End If



Case "Remove" If Not obj.RemoveApprovers(obj.StatusID, txtApprovers.Text, _ txtObservers.Text, chkComment.Value) Then MsgBox "Failed to remove approvers. " + obj.ErrorMessage End If

End Select

End Sub

RouteObject::Approve()

Syntax

BOOL Approve(LPCTSTR password,LPCTSTR comment)

Description

Approves a Change.

Parameters

password

the user’s approval password

comment

a string providing comments about the Change (2000 characters maximum)

Returns


Example

Private Sub ApproveOrReject(Action As String, Change As Object)

Select Case Action Case "Approve" b = Change.Approve(txtPassword.Text, txtComment.Text) Case "Reject" b = Change.Reject(txtPassword.Text, txtComment.Text) End Select If Not b Then MsgBox "Failed to " + Action + ". " + Change.ErrorMessage End If

6-179


Hide

End Sub

RouteObject::Audit()

Syntax

BOOL Audit(long statusID,BOOL auditRelease,LPDISPATCH col)

Description

Returns a collection of strings describing incomplete data in required fields for the Change. Before the Change can be released, all required fields must be completed.

Parameters

statusID

the current status ID number. Each workflow has a list of valid statuses, and each status has a unique ID number. You can retrieve the current status ID using RouteObject::StatusID.

auditRelease

nonzero to audit the release or 0 to audit the present status. If you audit the release, the Audit method checks whether the Change is ready to be released, making sure required fields are completed, SmartRules are complied with, revisions do not conflict with each other, and attachments are not checked out on any of the affected Items. If you audit the present status, the Audit method makes sure all required fields are completed.

col

an output parameter that returns a pointer to a Collection object containing strings describing any incomplete data. If all required fields are completed and no errors are found, the collection contains one string that reads “No errors or warnings.” col must point to an existing Collection object; it cannot be Null.

Returns


Example

Private Sub AuditChange(obj As Object)



Dim li As ListItem Dim result As String Dim col As AgileAPI.Collection Set col = new AgileAPI.Collection

'Get the collection of audit results b = obj.Audit(obj.StatusID, 0, col)

'Display the audit results in the Audit Results list view lvwAuditResults.ListItems.Clear For i = 0 To col.Count - 1 result = col.Get(i) Set li = lvwAuditResults.ListItems.Add(, , result) Next i

End Sub

RouteObject::ChangeStatus()

Syntax

BOOL ChangeStatus(long newStatusID,BOOL auditRelease,LPCTSTR comment,BOOL notifyOriginator,BOOL notifyCCB,LPCTSTR notifyList,LPCTSTR approvers,LPCTSTR observers,BOOL urgent)

Description

Changes settings for the specified status. For example, you can change the list of Approvers or Observers, the comment, and the types of notification to use.

Parameters

newStatusID

status ID number for a Change or Package. Each workflow has a list of valid statuses, and each status has a unique ID number. You can retrieve the current status ID using RouteObject::StatusID. To retrieve the default next status ID, use GetDefaultNextStatusID.

6-181


auditRelease

nonzero to audit the release or 0 to audit the present status before changing the status. If you specify nonzero, the ChangeStatus method checks whether the Change is ready to be released, making sure required fields are completed, SmartRules are complied with, revisions do not conflict with each other, and attachments are not checked out on any of the affected Items. If you specify 0, the ChangeStatus method makes sure all required fields are completed. If an error is detected during the audit, ChangeStatus fails.

comment


notifyOriginator

a nonzero value to notify the originator of the Change; otherwise, 0

notifyCCB

a nonzero value to notify the members of the Change Control Board

notifyList

semicolon-delimited list of users to notify that the Change has expired (2000 characters maximum)

approvers

semicolon-delimited list of users to approve the Change (2000 characters maximum)

observers

semicolon-delimited list of users to observe the Change (2000 characters maximum)

urgent

a nonzero value to add an urgent icon to the mail message that notifies users of the change in status; 0 otherwise

Returns


Example

Private Sub ChangeToNextStatus(change As Object)

Dim b As Boolean Dim lStatusID As Long



lStatusID = change.GetDefaultNextStatusID(1) If lStatusID = 0 Then MsgBox change.ErrorMessage End Sub Else b = change.ChangeStatus(lStatusID, 0, txtComment.Text, _ chkNotifyOrig.Value, chkNotifyCCB.Value, txtNotifyList.Text, _ txtApprovers.Text, txtObservers.Text, 0) End If

End Sub

RouteObject::Comment()

Syntax

BOOL Comment(BOOL notifyOriginator,BOOL notifyCA,BOOL notifyCCB,LPCTSTR comment)

Description

Comments a Change.

Parameters

notifyOriginator

a nonzero value to notify the originator of the Change; 0 otherwise

notifyCA

a nonzero value to notify the Change Analyst of the Change; 0 otherwise

notifyCCB

a nonzero value to notify the members of the Change Control Board

comment


Returns


Example

Private Sub Comment(Change As Object)

6-183


Dim b As Boolean b = Change.Comment(chkNotifyOrig.Value, chkNotifyCA.Value, _ chkNotifyCCB.Value, txtComment.Text) If Not b Then MsgBox "Failed to comment on the Change. " + Change.ErrorMessage End If Hide

End Sub

RouteObject::GetApprovers()

Syntax

BOOL GetApprovers(long statusID,LPDISPATCH approvers,LPDISPATCH observers)

Description

Returns the separate collections of Approvers and Observers for a Change or Package. GetApprovers can get Approvers and Observers only for current and future statuses, not past statuses.

Parameters

statusID

status ID number for a Change or Package. Each workflow has a list of valid statuses, and each status has a unique ID number. To specify the current status ID, type 0 or use RouteObject::StatusID. To retrieve the default next status ID, use GetDefaultNextStatusID.

approvers

an output parameter that returns the Collection of users on the Approvers list. approvers must point to an existing Collection object; it cannot be Null.

observers

an output parameter that returns the Collection of users on the Observers list. observers must point to an existing Collection object; it cannot be Null.

Returns




Example

Private Sub cmdGetApprovers_Click(obj as Object)

Dim Approvers As AgileAPI.Collection Dim Observers As AgileAPI.Collecton Set Approvers = CreateObject("AgileAPI.Collection") Set Observers = CreateObject("AgileAPI.Collection")

If obj.GetApprovers(obj.StatusID, Approvers, Observers) Then FillApproversList FillObserversLis Else MsgBox "Failed to get approvers. " + obj.ErrorMessage End If

End Sub

RouteObject::GetDefaultNextStatusID()

Syntax

long GetDefaultNextStatusID(BOOL checkPrivilege)

Description

Retrieves the default next status ID for a Change or Package.

Parameters

checkPrivilege

nonzero to check whether the user has privileges required to go to the next workflow status. Specify 0 to return the default next status ID number regardless of the user’s privileges.

Returns

The next status ID number. If checkPrivilege is TRUE (nonzero) and the user does not have privileges required to go to the next workflow status, the method returns 0.

Example

See “RouteObject::ChangeStatus()” on page 6-181.

6-185


RouteObject::GetDefaultNotifyList()

Syntax

BOOL GetDefaultNotifyList(long statusID,LPDISPATCH userNames)

Description

Retrieves the Collection of user names that have been added to the notification list for a particular workflow status.

Parameters

statusID

status ID number for a Change or Package. Each workflow has a list of valid statuses, and each status has a unique ID number. You can retrieve the current status ID using GetStatus. To retrieve the default next status ID, use GetDefaultNextStatusID.

userNames

an output parameter that returns a Collection containing Agile Advantage user names. userNames must reference an existing Collection object.

Returns


RouteObject::GetNextStatusIDs()

Syntax

BOOL GetNextStatusIDs(BOOL checkPrivilege,LPDISPATCH ids)

Description

Retrieves the Collection of status ID numbers that can be used to select the next status for a workflow.

Parameters

checkPrivilege

nonzero to check whether the user has been assigned privileges to choose the next status ID number different from the default. Specify 0 to return all possible next status ID numbers, regardless of the user’s privileges.



ids

an output parameter that returns a Collection containing status ID numbers. ids must reference an existing Collection object.

Returns


RouteObject::GetStatusIDs()

Syntax

BOOL GetStatusIDs(long workFlowID,LPDISPATCH ids)

Description

Retrieves the Collection of status ID numbers that can be used for a specific workflow.

Parameters

workflowID

workflow ID number. To retrieve the workflow ID, use GetWorkflowID.

ids

an output parameter that returns a Collection containing status ID numbers. ids must reference an existing Collection object.

Returns


RouteObject::GetWorkflowID()

Syntax


Description

Retrieves the workflow ID for a Change or Package.

Returns


6-187


RouteObject::GetWorkflowIDs()

Syntax

BOOL GetWorkflowIDs(BOOL checkCriteria,LPDISPATCH ids)

Description

Retrieves the Collection of workflow ID numbers that can be used for a Change or Package.

Parameters

checkCriteria

nonzero to return the workflow ID numbers that match the workflow criteria for the Change or Package; 0 to return workflow ID numbers for all Change and Package objects, regardless of workflow criteria

ids

an output parameter that returns a Collection containing workflow ID numbers. ids must reference an existing Collection object.

Returns


Example

See “RouteObject::SetWorkflowID()” on page 6-190.

RouteObject::Reject()

Syntax

BOOL Reject(LPCTSTR password,LPCTSTR comment)

Description

Rejects a Change.

Parameters

password

the user’s approval password



comment


Returns


Example

See “RouteObject::Approve()” on page 6-179.

RouteObject::RemoveApprovers()

Syntax

BOOL RemoveApprovers(long statusID,LPCTSTR approvers,LPCTSTR observers,LPCTSTR comment)

Description

Removes users from the Signoff table for a Change (TableType = ttChangeSignoff) or a Package (TableType = ttPackageSignoff).

Parameters

statusID

status ID number for a Change or Package. Each workflow has a list of valid statuses, and each status has a unique ID number. You can retrieve the current status ID using GetStatus. To retrieve the default next status ID, use GetDefaultNextStatusID.

approvers

semicolon-delimited list of users to remove from the Approvers list (2000 characters maximum)

observers

semicolon-delimited list of users to remove from the Observers list (2000 characters maximum)

comment

a string providing comments about the Change or Package (2000 characters maximum)

6-189


Returns


Example

See “RouteObject::AddApprovers()” on page 6-177.

RouteObject::SetWorkflowID()

Syntax


Description

Sets the workflow ID for a Change or Package. You can set the workflow ID for a Change or Package only if the workflow ID has not yet been assigned.

You can use the Agile Administrator API to retrieve information about custom workflows that have been designed for your Agile system. For example, once you get the Agile Workflows node from the Agile Administrator tree, you can use Node::ChildNodes to retrieve the Collection of all workflow nodes. Once you have the Collection of workflow nodes, you can use properties of the Node object to retrieve the names and ID numbers of workflows.

The following GetWorkflowNodes function shows how to retrieve workflow nodes.

Public Function GetWorkflowNodes(Server As AgileAPI.Server) As AgileAPI.Collection

Dim wfNode As AgileAPI.Node Set wfNode = Server.GetNode(nidWorkflows) Set GetWorkflowNodes = wfNode.ChildNodes

End Function

Parameters

newWorkflowID

workflow ID number. To get the Collection of valid workflow ID numbers, use GetWorkflowIDs.

Returns




Example


Private Sub cmdCreateECO_Click()

Dim b As Boolean

'Create a Collection to hold the Workflow IDs Dim colWFIDs As AgileAPI.Collection Set colWFIDs = CreateObject("AgileAPI.Collection")

'Create a new ECO Set currECO = CreateObject("AgileAPI.Change") b = currECO.Create(server, "ECO", txtNumber.Text) If Not b Then MsgBox "Failed to create object. " + currECO.ErrorMessage Else 'Get the Collection of Workflow IDs b = currECO.GetWorkflowIDs(1, colWFIDs) 'Set the Workflow ID b = currECO.SetWorkflowID(colWFIDs.Get(0)) End If

End Sub

6-191


RowOverview

A single row in an Agile Advantage table. ApprovedMfr, Attachment, BOMComponent, and DataObject all derive from Row.

Hierarchy

❑ Base❑ Row

Properties

Table 6-26: Row properties


DiscoveryPrivilege BOOL Read-only Returns whether the user has the Discovery privilege for a particular row object in a table.

Note: If the Discovery feature is disabled in the Agile Database node in Agile Administrator, users with the Read privilege are able to discover all objects.

Fields LPDispatch Read-only Returns the Collection of fields in the row.


Chapter 6 Agile Advantage API Reference – Row

Referent LPDispatch Read-only Returns the referenced object, either an Item, Manufacturer, Manufacturer Part, Change, or Package. For example, if you are working with the Changes table for an Item, you can use Referent to return the referenced Change. This is equivalent to double-clicking a row in the Agile Advantage Windows client to open the referenced object listed on the row.

Note: If the user does not have the Discovery privilege for the referenced object (Row::DiscoveryPrivilege returns 0), Referent fails and sets the ErrorMessage value to “No privilege.”

RowIndex LONG Read-only Returns the index number of the row.

Table 6-26: Row properties


6-193


Methods

CheckValidOperation

GetFieldDiscPriv

GetReferentInfo

GetStatus

GetValue

LogAction

SetValue

Row::CheckValidOperation()

Syntax

BOOL CheckValidOperation(long op)

Description

Checks whether the specified row operation is valid. You can use CheckValidOperation to check whether a particular operation is valid before activating a related command or button in your program’s user interface.

Parameters

op

one of the Row operation constants (see page 6-518).

Returns

Nonzero if the specified operation is valid; 0 otherwise.

Example

Public Sub EnableAddButton(attachment As Object)

Dim b As Boolean

' Check whether the Add button should be enabled If attachment.IsImage Then b = attachment.CheckValidOperation(roAddImage) Else b = attachment.CheckValidOperation(roAddFile) End If If Not b Then cmdAdd.Enabled = False



Else cmdAdd.Enabled = True End If

End Sub

Row::GetFieldDiscPriv()

Syntax

BOOL GetFieldDiscPriv(long FieldID)

Description

Returns whether the user has the Read privilege for a specified field. If the user does not have the Read privilege for a field, GetValue returns the string “No Privilege.”

Parameters

FieldID

the base ID number for the field. The field you specify must be one of the valid fields for the active table. A field has the same base ID as its corresponding attribute. For lists of attributes for each Agile Advantage class, see “” on page 6-261.

Returns

Nonzero if the user has the Read privilege for the field; 0 otherwise.

Row::GetReferentInfo()

Syntax

BOOL GetReferentInfo(LPDISPATCH info)

Description

Retrieves the ObjectInfo object for the referenced object. Use GetReferentInfo instead of Referent when you want to return information about the referenced object without actually instantiating it.

Note To retrieve information about the redline object associated with a row, make sure you use ShowRedline first.

6-195


Parameters

info

output parameter that returns the ObjectInfo for the referenced object. info must point to an existing ObjectInfo object; it cannot be Null.

Returns

Nonzero if the specified operation is valid; 0 otherwise.

Example

Public Function GetReferentObjectType(row As Object) As Long


'Create an instance of the ObjectInfo object Set info = CreateObject("AgileAPI.ObjectInfo")

'Get the ObjectInfo for the referenced row object b = row.GetReferentInfo(info)

'Get the object type of the referenced object GetReferentObjectType = info.TargetType

End Function

Row::GetStatus()

Syntax

BOOL GetStatus(LONG type,LONG FAR* value)

Description

Retrieves the specified status values.

Parameters

type

one of the Row status type constants (see page 6-520)

value

an output parameter that returns the status value (currently all values are Boolean, 0 or nonzero)



Returns


Example

Sub CheckStatus(Row As Object)

Dim status As Long Dim b As Boolean

' Display whether the row object has a pending ECO b = Row.GetStatus(rstHasPendingECO, status) If status <> 0 Then MsgBox "The object has a pending ECO." Else MsgBox "The object does not have a pending ECO." End If

End Sub

Row::GetValue()

Syntax

BOOL GetValue(const VARIANT FAR& key,VARIANT FAR* value)

Description

Retrieves the value for a field with the specified name or ID. The data type of the return value depends on the data type of the Field object, as shown in Table 6-27:

The field may not have a value. For a Text field with no value, GetValue returns an empty string. For a SingleList or MultiList field with no value, GetValue returns an empty Collection object.

Table 6-27: Date types of Field values

Field::DataType value Variant Data Type

dtString VT_BSTR (a string)

dtLong VT_I4 (an integer)

dtDate VT_DATE (a date)

dtSingleList VT_DISPATCH (a Collection of one ListElement)

dtMultiList VT_DISPATCH (a Collection of ListElements)

6-197


The selected field value could be obsolete if it was removed from the list in Agile Administrator after the value was last set. You can check if a value is obsolete using ListElement::IsObsolete.

Parameters

key

fully qualified name (for example, “Title Block.Description”) or base ID of the field. A field has the same base ID as its corresponding attribute. For lists of attributes for each Agile Advantage class, see “” on page 6-261.

value

an output parameter that returns the field value

Returns


Example: Getting a String Value

The following Visual Basic code shows how to use Row::GetValue to get the value for “Title Block.Description,” a string value.

Public Item As AgileAPI.ItemPublic vDesc As Variant

Public Sub GetDescription() 'Get the "Title Block.Description" value b = Item.GetValue(aidParts_TitleBlock_Description, vDesc) If Not b Then MsgBox Item.ErrorMessage, vbInformation, "Error Getting Value" Exit Sub End If

'Populate the Description field with the value frmMain.txtDesc.Text = vDescEnd Sub

Example: Getting a Numeric Value

The following Visual Basic code shows how to use Row::GetValue to get the value for “Page Two.Standard Cost,” a custom text field whose format has been set to Numeric.

Public Item As AgileAPI.ItemPublic vStdCost As Variant

Public Sub GetStdCost()



'Get the "Page Two.Standard Cost" (Text01) value b = Item.GetValue(aidParts_PageTwo_Text01, vStdCost) If Not b Then MsgBox Item.ErrorMessage, vbInformation, "Error Getting Value" Exit Sub End If

'Populate the Standard Cost field with the value frmMain.txtStdCost.Text = vStdCost

End Sub

Example: Getting a Date Value

The following Visual Basic code shows how to use Row::GetValue to get the value for a custom date field, “Page Two.Target Draft Date.”

Public Item As AgileAPI.ItemPublic vTargetDraftDate As Variant

Public Sub GetTargetDraftDate()

'Get the "Page Two.Target Draft Date" (Date01) value b = Item.GetValue(aidParts_PageTwo_Date01, vTargetDraftDate) If Not b Then MsgBox Item.ErrorMessage, vbInformation, "Error Getting Value" Exit Sub End If

'Populate the Draft Date field with the value If CStr(vTargetDraftDate) <> "" Then frmMain.txtDraftDate.Text = FormatDateTime(vTargetDraftDate, _ vbShortDate) Else frmMain.txtTargetDraftDate.Text = "" End If

End Sub

Example: Getting a List Value

The following Visual Basic code shows how to use Row::GetValue to get the value for “Title Block.Part Category,” a list value.


6-199


Public Sub GetPartCat()

'Get the "Title Block.Part Category" value b = Item.GetValue(aidParts_TitleBlock_PartCategory, vPartCat) If Not b Then MsgBox Item.ErrorMessage, vbInformation, "Error Getting Value" Exit Sub End If

'Select the "Title Block.Part Category" value in the list If vPartCat.Count = 0 Then frmMain.cmbPartCat.ListIndex = -1 Else If vPartCat.Get(0).IsObsolete = True Then frmMain.cmbPartCat.ListIndex = -1 Else frmMain.cmbPartCat.Text = vPartCat.Get(0).Value End If End If

End Sub

Example: Getting a MultiList Value

The following Visual Basic code shows how to use Row::GetValue to get the value for “Title Block.Product Line(s),” a MultiList value.


Public Sub GetProdLines()

'Get the "Title Block.Product Line(s)" value b = Item.GetValue(aidParts_TitleBlock_ProductLines, vProdLines) If Not b Then MsgBox Item.ErrorMessage, vbInformation, "Error Getting Value" Exit Sub End If

'Populate the Product Lines field with the value If vProdLines.Count = 0 Then frmMain.txtProdLines.Text = "" Else frmMain.txtProdLines.Text = ListElementsToString(vProdLines) End If



End Sub

Public Function ListElementsToString(col As Variant) As String

Dim ListElements As String

For I = 0 To col.Count - 1 If col.Get(I).Obsolete = False Then ListElementsToString = ListElementsToString + col.Get(I).Value If Not I = col.Count - 1 Then ListElementsToString = ListElementsToString + "," End If End If Next IEnd Function

Row::LogAction()

Syntax

BOOL LogAction(long at,LPCTSTR param)

Description

Logs an action to the History table. For most actions, LogAction isn’t needed because the Agile Advantage API automatically logs actions to the History table. LogAction should only be used to manually add an entry to the History table.

Parameters

at

one of the Row action type constants (see page 6-518)

param

if at is ratPrintTab, specify the tab name that was printed; otherwise, type an empty string ("")

Returns


6-201


Row::SetValue()

Syntax

BOOL SetValue(const VARIANT FAR& key,const VARIANT FAR& value)

Description

Sets the value of the field with the specified name. The change is not saved to the database until you use DataObject::Save. The data type of value depends on the data type of the Field object; for more information, see Table 6-27 on page 6-197.

When you set a value for a field, the Agile Advantage API automatically sets Base::IsDirty equal to 1. This locks the object and prevents other users from modifying it. The object remains locked until you either save or abort your changes.

Parameters

key

fully qualified name (for example, “Title Block.Description”) or base ID of the field. For lists of attributes for each Agile Advantage class, see “” on page 6-261.

value

new field value to set

Returns


Example: Setting a String Value

The following Visual Basic code shows how to use Row::SetValue to set the value for “Title Block.Description,” a string value.


Public Sub SetDesc()

'Set the "Title Block.Description" value b = Item.SetValue(aidParts_TitleBlock_Description, frmMain.txtDesc.Text) If Not b Then MsgBox Item.ErrorMessage, vbInformation, "Error Setting Value" Call GetDescription End If

End Sub



Example: Setting a Numeric Value

The following Visual Basic code shows how to use Row::SetValue to set the value for “Page Two.Standard Cost,” a custom text field whose format has been set to Numeric.


Public Sub SetStdCost() 'Set the "Page Two.Standard Cost" (Text01) value b = Item.SetValue(aidParts_PageTwo_Text01, frmMain.txtStdCost.Text) If Not b Then MsgBox Item.ErrorMessage, vbInformation, "Error Setting Value" Call GetStdCost End IfEnd Sub

Example: Setting a Date Value

The following Visual Basic code shows how to use Row::SetValue to set the value for a custom date field, “Page Two.Target Draft Date.”


Public Sub SetTargetDraftDate()

'Set the "Page Two.Target Draft Date" (Date01) value b = Item.SetValue(aidParts_PageTwo_Date01, dtTargetDraftDate.Value)

If Not b Then MsgBox Item.ErrorMessage, vbInformation, "Error Setting Value" Call GetTargetDraftDate End If

End Sub

Example: Setting a List Value

The following Visual Basic code shows how to use Row::SetValue to set the value for “Title Block.Part Category,” a list value.


Public Sub SetPartCat()

Dim field As AgileAPI.Field Dim col As AgileAPI.Collection Dim listelement As AgileAPI.ListElement

6-203


'Get the Part Category field Set field = Item.Fields.Find(aidParts_TitleBlock_PartCategory)

'Get the collection of Part Category values Set col = field.ListElements

'Clear the Part Category collection retrieved 'earlier using GetValue vPartCat.Clear 'Set the "Title Block.Part Category" value If frmMain.cmbPartCat.ListIndex = -1 Then b = Item.SetValue(aidParts_TitleBlock_PartCategory, vPartCat) Else Set listelement = col.Get(frmMain.cmbPartCat.ListIndex) vPartCat.Add listelement, -1 b = Item.SetValue(aidParts_TitleBlock_PartCategory, vPartCat) End If If Not b Then MsgBox Item.ErrorMessage, vbInformation, "Error Setting Value" Call GetPartCat End If

End Sub

Example: Setting a MultiList Value

The following Visual Basic code shows how to use Row::SetValue to set the value for “Title Block.Product Line(s),” a MultiList value.


Public Sub UpdateProductLines()

Dim field As AgileAPI.Field Dim col As AgileAPI.Collection Dim listElement As AgileAPI.ListElement Dim li As ListItem

'Get the Product Lines field Set field = Item.Fields.Find(aidParts_TitleBlock_ProductLines)

'Get the collection of Product Lines values Set col = field.ListElements



'Clear the Product Lines collection retrieved 'earlier using GetValue vProdLines.Clear

'Compare the selected Product Lines values with 'each of the possible values for the attribute. 'For each matching value, add the list element to 'the vProdLines collection. For I = 0 To frmMultiList.lvwSelections.ListItems.Count - 1 Set li = frmMultiList.lvwSelections.ListItems(I + 1) For x = 0 To col.Count - 1 If li.Text = col.Get(x).Value Then Set listElement = col.Get(x) vProdLines.Add listElement, -1 End If Next x Next I

'Populate the Product Lines field with the value If vProdLines.Count = 0 Then frmMain.txtProdLines.Text = "" Else frmMain.txtProdLines.Text = ListElementsToString(vProdLines) End If frmMultiList.Hide

'Set the "Title Block.Product Line(s)" value b = Item.SetValue(aidParts_TitleBlock_ProductLines, vProdLines) If Not b Then MsgBox Item.ErrorMessage, vbInformation, "Error Setting Value" GetProdLines End If

End Sub

6-205


ServerOverview

Agile Advantage servers, including both Agile Advantage eHub (application server) and Agile Advantage iFS (file server). Server is an externally creatable object. Before your application can work with other Agile Advantage objects, you must first create an instance of the Server object. Once an instance of the Server object is created, you can use methods and properties to create instances of other Agile Advantage objects.

Hierarchy

❑ Base❑ Server

Properties

Table 6-28: Server properties


CurrentUser LPDISPATCH Read-only Returns the currently logged in user.

FileServerBufferSize LONG Read-only Returns the current size of the Agile Advantage iFS buffer.

FileServerCacheDir BSTR Read-only Returns the Agile Advantage iFS cache directory.

FileServerHostname BSTR Read-only Returns the Agile Advantage iFS host name.

FileServerPassword BSTR Read-only Returns the Agile Advantage iFS password.

FileServerPort LONG Read-only Returns the Agile Advantage iFS network port.

FileServerSchema BSTR Read-only Returns the name of the Agile Advantage iFS schema.

Hostname BSTR Read-only Returns the Agile Advantage eHub computer name.


Chapter 6 Agile Advantage API Reference – Server

IsConnected BOOL Read-only Returns nonzero if the Server object is currently connected. Otherwise, it returns 0. If it is not connected, you can use Connect to reconnect to an Agile Advantage eHub.

IsLogin BOOL Read-only Verifies whether a user is currently logged in to the Server object. If not, you can use Server::Login to log in.

MfrNames LPDISPATCH Read-only Returns a collection of all Manufacturer names.

Port LONG Read-only Returns the Agile Advantage eHub Server port number.

QueryClasses LPDISPATCH Read-only Returns the collection of all query classes, the types of objects for which you can define a query.

SubClasses LPDISPATCH Read-only Returns the Collection of all SubClass objects for the Agile Advantage eHub.

Users LPDISPATCH Read-only Returns the collection of all user names.

Table 6-28: Server properties


6-207


Methods

Creating an Instance of the Server Object

In Visual Basic you can create an instance of the Server object using the CreateObject function. Immediately after creating an instance of the Server, you must validate the Agile Advantage API license key using the SetLicenseKey method.

Note Failure to set the license key for a Server instance causes all calls to the Agile Advantage API to fail with an error that reads “Invalid API license.” You must set the license key for each Server instance that your application creates.

The following code shows an example of the CreateObject function and the SetLicenseKey, Connect, and Login methods.


Private Sub Form_Load()

Set server = CreateObject("AgileAPI.Server") server.SetLicenseKey "AgileAPILicenseKey" b = server.Connect(ehubserver, 9013, scfAll) b = server.Login("username", "password", _ "c:\temp", 16384)End Sub

You can also assign a reference to the Server object using the New keyword:

' Declare an object variable for the Agile API ServerDim server As Object

' Create a new instance of the Server

Connect GetNode

DiffAML GetObject

Disconnect GetVersion

GetAttribute Login

GetFailoverServerList LoginEx

GetHomeFolderInfo SetClientTime

GetLicenseType SetLicenseKey

GetListElement TranslateClassID

GetListElements



Set server = New AgileAPI.Server

Note You can use the Base::Server property to access properties and methods of the Server object from another object.

Server::Connect()

Syntax

BOOL Connect(LPCTSTR hostname,long port,long connectFlags)

Description

Connects to the Agile Advantage eHub. An application must connect to the server before a user can log in.

If you are developing a Windows application, you can have your program fetch values for Connect parameters from the registry at run time. Agile registers its network settings in one of the following registry keys, depending on the privileges of the person who installed the software:

❑ [HKEY_CURRENT_USER\Software\Agile\AgileNetwork]❑ [HKEY_LOCAL_MACHINE\Software\Agile\AgileNetwork]

The hostname and port parameters correspond to the “eHub_Hostname” and “eHub_InPort” registry values, respectively.

Parameters

hostname

computer name where the Agile Advantage eHub is located; for test purposes, you can enter localhost if the Agile Advantage eHub is installed on your local computer

port

network port of the Agile Advantage eHub; the default Agile Advantage eHub port is 9013

connectFlags

one of the Server connect flag constants (see page 6-521), which sets options for connecting to the Agile Advantage eHub; all programs should connect using the scfAll flag

6-209


Returns


Example

b = server.Connect(ehubserver, 9013, scfAll)If Not b Then MsgBox "Failed to connect to the server because " _ + server.ErrorMessageEnd If

Server:ConnectAdvEx()

Server::DiffAML()

Syntax

BOOL DiffAML(LPDISPATCH sourceItems,LPDISPATCH targetItems,LPDISPATCH result,LPDISPATCH option)

Description

Compares AMLs in lists of source Items and target Items and creates a list of item numbers that have different AMLs.

DiffAML is used to process AML import data before running Item::SyncAML. It is not necessary to run SyncAML against a source and target Item if their AMLs are identical. DiffAML identifies the AMLs that are different so that they can be imported and redlined.

If you are using DiffAML to compare the AMLs of target Items with those of temporary Items you created to import data, it is sometimes practical to place the target Item numbers in the sourceItems parameter and the temporary Item numbers in the targetItems parameter. That way, the result parameter holds true Item numbers and not temporary ones. The example for “Item::SyncAML()” on page 6-120 illustrates this approach.

DiffAML compares the source Item’s AML with the target Item’s AML for the most recent pending Change against it. This could be different from the target Item’s AML for the current released revision.



Parameters

sourceItems

a Collection object that you created and filled with strings representing the Item numbers listed on the source AML

targetItems

a Collection object that you created and filled with strings representing the Item numbers listed on the target AML

result

a Collection object that you created to hold the list of Item numbers from sourceItems whose AML is different from the respective AML in targetItems for the attributes specified in option

option

a SyncOption object that contains a Collection object filled with attribute ID numbers. The SyncOption object identifies columns on the Manufacturers tab that you want to compare. Any attributes not specified in the SyncOption object are not compared. If option is Null, contains no ID numbers, or contains no valid ID numbers for the Manufacturers tab, all columns on the Manufacturers tab are compared. For more information, see “SyncOption” on page 6-241.

Returns


Example

See “Item::SyncAML()” on page 6-120

Server::Disconnect()

Syntax

void Disconnect()

Description

Disconnects the Server object from the Agile Advantage eHub. Forces shutdown of the Server object, which frees up any Agile Advantage licenses the object was using.

Once you disconnect, you can use the Server object to reconnect to the same Agile Advantage eHub or to a different one.

6-211


Example

Private Sub cmdLogout_Click()

Dim intResponse As Long

intResponse = MsgBox("Are you sure you want to log out?", vbYesNo) If intResponse = vbYes Then server.Disconnect End If

End Sub

Server::GetAttribute()

Syntax

LPDISPATCH GetAttribute(long classID, const VARIANT FAR& attr)

Description

Retrieves an Attribute object by the specified class and an attribute name or ID.

Parameters

classID

ID number of a class or subclass. You can also enter one of the class type constants.

attr

a fully qualified name (for example, “Title Block.Description”) or base ID of an attribute. For lists of attributes for each Agile Advantage class, see “” on page 6-261.

Returns

A pointer to an Attribute object if the method was successful; Null otherwise.

Example

Dim attr As AgileAPI.Attribute

'Get the "Cover Page.Workflow" attribute for an ECO objectSet attr = server.GetAttribute(6141, aidChangeOrders_CoverPage_Workflow)

If attr Is Nothing Then MsgBox server.ErrorMessage



End If

Server::GetFailoverServerList()

Syntax

BOOL GetFailoverServerList(LPDISPATCH HostNames,LPDISPATCH HostPorts)

Description

Returns separate Collection objects containing the list of hostnames and port numbers for Agile Advantage eHub servers used for failover purposes.

Note This function is available only if you are licensed to use clustered eHubs. Otherwise, the function fails. If only one Agile Advantage eHub is installed, GetFailoverServerList returns empty Collection objects.

Parameters

HostNames

an output parameter that returns a pointer to a Collection object containing the hostnames (strings) of all clustered eHubs.

HostPorts

an output parameter that returns a pointer to a Collection object containing the port numbers of all clustered eHubs.

Returns


Example

The following program demonstrates how to use GetFailoverServerList to test the failover capabilities of the system. Before running the program, stop one or more of the clustered eHub servers. Run the program to check if the system automatically connects you to one of the other failover eHubs.

Dim Server As AgileAPI.Server

Sub Main()

Dim bRet As Boolean Dim S As AgileAPI.Base

Set Server = New AgileAPI.Server

6-213


Call Server.SetLicenseKey("AgileAPILicenseKey")

Dim FailoverHostList As New AgileAPI.Collection Call FailoverHostList.SetDataType(dtString)

Dim FailoverPortList As New AgileAPI.Collection Call FailoverPortList.SetDataType(dtLong)

' Customer implemented procedure ReadFromResourceFile(FailoverHostList, FailoverPortList)

Dim IFSHost As String IFSHost = "localhost"

For i = 0 To FailoverHostList.Count - 1 bRet = Server.Connect(FailoverHostList.Get(i), _ FailoverPortList.Get(i), scAll) If bRet Then Call Server.GetFailoverServerList(FailoverHostList, _ FailoverPortList)

' Customer implemented procedure WriteToResourceFile(FailoverHostList, FailoverPortList)

bRet = Server.Login("username", "password", "C:\TEMP", 16368) If bRet Then ' ' User business logic goes here ' Server.Disconnect Exit For End If End If Next i Debug.Print "Test completed"End Sub



Server::GetHomeFolderInfo()

Syntax

BOOL GetHomeFolderInfo(LPDISPATCH info)

Description

Retrieves the Home Folder information in Agile Advantage. The Home Folder lets you browse all public and private queries.

Parameters

info

an output parameter that returns an ObjectInfo object containing information about the Home Folder. info must point to an existing ObjectInfo object; it cannot be Null.

Returns


Example

Public Sub GetHomeFolder(server As Object)

Dim homefolder As AgileAPI.Folder Dim info As AgileAPI.ObjectInfo Dim b As Boolean

'Create a folder object Set homefolder = CreateObject("AgileAPI.Folder")


'Get the home folder info b = server.GetHomeFolderInfo(info) If Not b Then Msg server.ErrorMessage Exit Sub End If

'Load the home folder b = homefolder.LoadByInfo(server, info) If Not b Then Msg homefolder.ErrorMessage End If

6-215


End Sub

Server::GetLicenseType()

Syntax

BOOL GetLicenseType(LONG FAR* type)

Description

Specifies the type of Agile Advantage license you have. If you use the Subscription license model (type=sltNamed), each subscriber, or named user, has access to the Agile Advantage products that are assigned to that user. If you use the Concurrent license model (type=sltConcurrent), each user has access to the Agile Advantage products that are assigned to that user if those licenses are currently available from the pool at login time.

Before using GetLicenseType, you must establish a connection to the Agile Advantage eHub using Server::Connect.

Parameters

type

an output parameter that returns a Server license type constant (see page 6-521)

Returns


Example


Public Sub CheckIfConcurrentUsers()

Dim licType As Long

b = server.GetLicenseType(licType) If licType = sltConcurrent Then chkCheckLicenses.Enabled = True Else chkCheckLicenses.Enabled = False End If

End Sub



Server::GetListElement()

Syntax

LPDISPATCH GetListElement(long listID,const VARIANT FAR& key)

Description

Retrieves a ListElement for an Agile list by specifying its value.

Parameters

listID

a number that uniquely identifies a list used for a Property object in Agile Administrator; to retrieve the ID for a list, use Property::ListID.

key

ListElement value; to retrieve the value for a ListElement, use ListElement::Value.

Returns

A pointer to a ListElement object if the method was successful; Null otherwise.

Example

Public Sub SetPartCategory(server As Object, item as Object)

Dim listelement As AgileAPI.ListElement Dim col As AgileAPI.Collection Dim b As Boolean

'Create a collection and set its data type Set col = CreateObject("AgileAPI.Collection") b = col.SetDataType(dtObject)

'Get the Electrical Part Category list element Set listelement = server.GetListElement(1023, "Electrical")

'Add the list element to the collection col.Add listelement, -1

'Set the Part Category value to Electrical b = item.SetValue(aidParts_TitleBlock_PartCategory, col) If Not b Then MsgBox item.ErrorMessage End If

6-217


End Sub

Server::GetListElements()

Syntax

BOOL GetListElements(long listID,LPDISPATCH col)

Description

Retrieves the Collection of values that appear in a specified list. A list is associated with either a Field or a Property whose Type is dtSingleList or ptSingleList, respectively. Both the Field and Property objects have a ListElements property that allows you to retrieve the list’s values. However, GetListElements lets you retrieve a list’s values without first retrieving a Field or Property.

Parameters

listID

the List ID number of an Agile list field; you can retrieve a List ID for a list field using Property::ListID

col

an output parameter that returns a Collection object containing the list elements for the specified list. col must point to an existing Collection object; it cannot be Null.

Returns


Example

Dim genPrefNode As AgileAPI.NodeDim prop As AgileAPI.PropertyDim listElements As AgileAPI.CollectionDim listString As StringDim listID As IntegerDim b As BooleanDim i As Integer

'Create a listElements collectionSet listElements = CreateObject("AgileAPI.Collection")

'Get the General Preferences node



Set genPrefNode = server.GetNode(nidGeneral)

'Get the Icon Motif propertySet prop = genPrefNode.Properties.Find("IconMotif")

'Get the list elements for the IconMotif propertylistID = prop.listID

'Get the collection of valid list elements for the IconMotif listb = server.GetListElements(listID, listElements)

'Put the list elements in a comma-delimited stringFor i = 0 To listElements.Count - 1 listString = listString + listElements.Get(i).Value If Not i = listElements.Count - 1 Then listString = listString + "," End IfNext i

'Display the list elements in a message boxMsgBox listString

Server::GetNode()

Syntax

LPDISPATCH GetNode(LONG id)

Description

Retrieves a Node object for the specified Node ID constant. You can use GetNode to quickly retrieve a specific node in the Agile Administrator tree view, such as the root node or the SmartRules node.

Parameters

id

one of the Node ID constants (see page 6-428)

Returns

A pointer to a Node object if the method was successful; Null otherwise.

Example

Dim node as AgileAPI.node

‘Get the SmartRules node

6-219


Set node = server.GetNode(nidSmartRules)

If node Is Nothing Then MsgBox "Unable to get SmartRules node. " + server.ErrorMessageEnd If

Server::GetObject()

Syntax

LPDISPATCH GetObject(LPDISPATCH info)

Description

Retrieves an Agile Advantage object based on the specified object information. You can use GetObject to retrieve the following types of objects:

❑ Change❑ Item❑ Folder❑ Mfr

❑ MfrPart

❑ Package❑ Query

For all types of Agile Advantage objects, the info parameter should be an ObjectInfo object that includes TargetType and TargetID members. For Item, Change, Mfr, MfrPart, and Package objects, GetObject returns an object from the Agile Advantage eHub faster if the specified ObjectInfo object also includes the ClassID member.

Parameters

info

a reference to an ObjectInfo object that uniquely identifies the Agile Advantage object to retrieve

Returns

A pointer to the object if the method was successful; Null otherwise

Example

Public item As AgileAPI.ItemPublic server As AgileAPI.ServerPublic colHistoryInfo As AgileAPI.Collection

Private Sub LoadObjectFromHistory(index As Long)




Set info = colHistoryInfo.Get(index)

b = server.GetObject(info) If Not b Then MsgBox "Unable to load object. " + server.ErrorMessage End If

End Sub

Server::GetVersion()

Syntax

BSTR GetVersion(LPCTSTR hostName,long port)

Description

Returns the Agile Advantage eHub version number as a string without actually logging in to the server. You can use GetVersion to determine the Agile Advantage eHub version number and then run a program that provides functionality appropriate for that server.

Parameters

hostName

computer name where the Agile Advantage eHub is located; for test purposes, you can enter localhost if the Agile Advantage eHub is installed on your local computer

port

network port of the Agile Advantage eHub; the default Agile Advantage eHub port is 9013. If you specify an incorrect port number, GetVersion may take several minutes to return an error.

Returns

The Agile Advantage eHub version number (a string).

Example

Dim strVersion As String

6-221


'Get the Agile eHub versionSet strVersion = server.GetVersion(ehub1, 9013)

'Display the version number in a message boxMsgBox "Agile eHub version: " + strVersion

Server::Login()

Syntax

BOOL Login(LPCTSTR username,LPCTSTR password,LPCTSTR fileServerCacheDir,LONG fileServerBufferSize)

Description

Logs in to the Agile Advantage eHub and specifies connection information for the Agile Advantage iFS. Before logging in, a user must first connect to the server using Server::Connect.

The fileServerHostName, fileServerCacheDir, and fileServerPort parameters are used whenever your Agile Advantage API program needs to connect to an Agile Advantage iFS. Therefore, you can specify incorrect Agile Advantage iFS parameters and still successfully log in to an Agile Advantage eHub. However, if your program attempts to pull something from the incorrectly specified Agile Advantage iFS (for example, by using Attachment::GetFile) you receive an error.

If you are developing a Windows application, you can have your program fetch values for Login parameters from the registry at run time. Agile Advantage registers its network settings in one of the following registry keys, depending on the privileges of the person who installed the software:

❑ [HKEY_CURRENT_USER\Software\Agile Advantage\AgileNetwork]❑ [HKEY_LOCAL_MACHINE\Software\Agile Advantage\AgileNetwork]

The fileServerHostname, fileServerCacheDir, fileServerPort, and fileServerBufferSize parameters correspond to the “iFS_Hostname,” “iFS_CacheDirectory,” “iFS_Port,” and “iFS_BufferSize” registry values, respectively.

Note Agile Advantage users must have a Full user license to log in to an Agile Advantage ADK application.



Parameters

username

Agile username

password

the user’s Agile login password; this value is case-sensitive

fileServerHostname

computer name where Agile Advantage iFS (file server) is installed; for test purposes, you can enter localhost if Agile Advantage iFS is installed on your local computer; connections to the Agile Advantage iFS are made as needed by your program

fileServerCacheDir

cache directory of the Agile Advantage iFS (256 characters maximum)

fileServerPort

network port of the Agile Advantage iFS; the default Agile Advantage iFS port is 9012

fileServerBufferSize

current size of the Agile Advantage iFS buffer; the default Agile Advantage iFS buffer size is 16384

Returns


Example

b = server.Login("jpowers", "agile", "localhost", "c:\temp", 9012, 16384)If b = False Then MsgBox "Failed to login because " + server.ErrorMessageEnd If

Server::LoginEx()

Syntax

BOOL LoginEx(LPCTSTR userName,LPCTSTR password,long flags)

6-223


Description

Performs a special login to the Agile Advantage eHub in order to create, modify, and delete Agile Advantage users.

Note An Agile Advantage user must have a Full user license to log in to an Agile Advantage ADK application. To modify users, you must have Administrator privileges to the Agile Advantage system.

Parameters

userName

Agile Advantage username

password

the user’s Agile Advantage login password; this value is case-sensitive

flags

one of the Server LoginEx flag constants (see page 6-522) used to set the type of login. To create or modify Agile Advantage users, use the slfAdministrator flag, which is equivalent to logging in to Agile Administrator. Only one user at a time can log in to Agile Administrator.

Returns


Example

Dim node As AgileAPI.NodeDim aauser As AgileAPI.User

'Log in using the special Administrator flagserver.LoginEx("jpowers", "agile", slfAdministrator)

'Get the Users nodeSet node = server.GetNode(nidUsers)

'Create a new userSet aauser = node.CreateUser(txtName, txtUserName)



Server::LoginAdvEx()

Server::SetClientTime()

Syntax

BOOL SetClientTime(long bias)

Description

Sets the time of the client computer that is connecting to the Agile Advantage eHub.

Parameters

bias

the current bias, in minutes, for local time translation on the client computer that is connecting to the Agile Advantage eHub. The bias is the difference, in minutes, between coordinated universal time (UTC) and local time. UTC is equivalent to Greenwich mean time (GMT). All translations between UTC and local time are based on the following formula:

UTC = local time + bias

Returns


Example

Private Declare Function GetTimeZoneInformation _ Lib "kernel32" (lpTimeZoneInformation As _ TIME_ZONE_INFORMATION) As Long

Private Type SYSTEMTIME wYear As Integer wMonth As Integer wDayOfWeek As Integer wDay As Integer wHour As Integer wMinute As Integer wSecond As Integer wMilliseconds As IntegerEnd Type

Private Type TIME_ZONE_INFORMATION Bias As Long StandardName(0 To 63) As Byte StandardDate As SYSTEMTIME

6-225


StandardBias As Long DaylightName(0 To 63) As Byte DaylightDate As SYSTEMTIME DaylightBias As LongEnd Type Private Sub Command1_Click() ... Dim tz As TIME_ZONE_INFORMATION Call GetTimeZoneInformation(tz) Dim bRet as Boolean bRet = Server.SetClientTime(tz.Bias) If Not bRet Then MsgBox Server.ErrorMessage End If ...

End Sub

Server::SetLicenseKey()

Syntax

void SetLicenseKey(BSTR key)

Description

Validates the license key for the Server instance. To enable your application to have access to Agile Advantage API functionality, you must set the license key for each Server instance that your application creates. Failure to set the license key causes all calls to the Agile Advantage API to fail with an error that reads “Invalid API license.”

Parameters

key

The Agile Advantage API license key text. The license key file is a text file named AgileAPI.lic located in the LicenseKey folder of your Agile Advantage ADK installation. The license key text is the first line of the file.

Example

Note In the following example, a placeholder named AgileAPILicenseKey is used in place of the actual key.




Private Sub Form_Load()

Set server = CreateObject("AgileAPI.Server") server.SetLicenseKey "AgileAPILicenseKey" b = server.Connect(eHub1, 9013, scfAll) b = server.Login("jpowers", "agile", "c:\temp", 16384)

End Sub

Server::TranslateClassID()

Syntax

long TranslateClassID(long id)

Description

Returns the Agile Advantage object type (for example, otItem or otChange) for the specified class ID or subclass ID. TranslateClassID is helpful for identifying the object type for a subclass without actually instantiating a SubClass object.

Parameters

id

class ID or subclass ID

Returns

One of the object type constants (see page 6-432).

Example

Public Sub GetObjectType(server As Object)

Dim i As Long

'Translate the specified subclass ID into the object type i = server.TranslateClassID(txtSubClassID.txt)

Select Case i Case otServer MsgBox "The object type is Server."

Case otItem MsgBox "The object type is Item."

6-227


Case otChange MsgBox "The object type is Change."

'Cases for all other object types go here.

End Select

End Sub


Chapter 6 Agile Advantage API Reference – ServiceRequest

ServiceRequestOverview

A product service request (PSR), which is a reported problem, defect, or issue for a particular part.

There are two types of PSRs:

❑ Problem report — describes a problem that a customer experienced with a product. It can be submitted by a customer, sales representative, or customer service representative.

❑ Issue — a problem that has been investigated by a Quality Analyst and has been determined to be a defect that needs correction.

A ServiceRequest includes some basic information about the problem report or issue, attachments, and a list of associated objects.

ServiceRequest is an externally creatable object. However, when you use the constructor to create a ServiceRequest object in your program, it is an empty object that is not associated with an Agile Advantage eHub. To load an existing ServiceRequest from an Agile Advantage eHub, use ServiceRequest::LoadByAttr or ServiceRequest::LoadByInfo. To create a new ServiceRequest on an Agile Advantage eHub, use ServiceRequest::Create.

Hierarchy

❑ Base❑ Row


❑ ServiceRequest

Methods

Create

LoadByAttr

LoadByInfo

6-229


ServiceRequest::Create()

Syntax

BOOL Create(LPDISPATCH server,const VARIANT FAR& subClass,LPCTSTR number)

Description

Creates a new ServiceRequest using the specified subclass.

Parameters

server

a pointer to a Server object used to initialize the new ServiceRequest

subClass


number

number of the new ServiceRequest

Returns


Example

Private Sub CreateSR(server As AgileAPI.Server)

Dim b As Boolean Dim pr As AgileAPI.ServiceRequest

Set pr = CreateObject("AgileAPI.ServiceRequest") b = pr.Create(server, "Problem Report", "PR00001") If Not b Then MsgBox "Failed to create problem report. " + pr.ErrorMessage End If

End Sub


Chapter 6 Agile Advantage API Reference – ServiceRequest

ServiceRequest::LoadByAttr()

Syntax


Description

Loads an existing ServiceRequest into the object by specifying an attribute and its value.

Parameters

server

a pointer to a Server object used to initialize the ServiceRequest

attr

a fully qualified attribute, such as “Cover Page.Description,” or a base ID. You can also type 0 to use the default attribute, “Cover Page.Number,” or type an attribute ID constant.

value


Returns


Example

Private Sub LoadPR(server As AgileAPI.Server)

Dim b As Boolean Dim pr As AgileAPI.ServiceRequest

Set pr = CreateObject("AgileAPI.ServiceRequest") b = pr.LoadByAttr(server, 0, "PR00001") If Not b Then MsgBox "Failed to load problem report. " + pr.ErrorMessage End If

End Sub

6-231


ServiceRequest::LoadByInfo()

Syntax


Description

Loads an existing ServiceRequest into the object by specifying an ObjectInfo object that uniquely identifies it. The specified ObjectInfo object must have TargetID and TargetType members.

Parameters

server

a pointer to a Server object used to initialize the ServiceRequest

info

a reference to an ObjectInfo object that uniquely identifies the ServiceRequest

value


Returns


Example



Chapter 6 Agile Advantage API Reference – SubClass

SubClassOverview

The class definition used to identify the category to which another object belongs. Use SubClass when creating objects to specifically define the class of object. SubClass also determines the list of Field objects that an object contains.

Hierarchy

❑ Base❑ Node

❑ SubClass

Properties

Table 6-29: SubClass properties


Attributes LPDISPATCH Read-only Retrieves a pointer to the Collection of attributes for all table types.

AutoNumber-Sources

LPDISPATCH Read-only Returns the collection of AutoNumber sources.

ClassID LONG Read-only Returns an ID number for the class to which the object belongs.

IsAutoNumber-Required

BOOL Read-only Returns a nonzero value if AutoNumber must be used when creating new objects. Otherwise, it returns 0.

Note: The Agile Advantage API doesn’t automatically enforce automatic numbering of objects. This is true even if the AutoNumberRequired property is True (nonzero). For subclasses that require AutoNumber, your application must determine whether to force an object number to the next AutoNumber.

Name BSTR Read-only Returns the class name.

6-233


SubClassID LONG Read-only Returns an ID number for the subclass to which the object belongs.

Tabs LPDISPATCH Read-only Returns the Collection of Tab objects for the SubClass. A Tab corresponds to an individual tab of a multi-tabbed window in the Agile Advantage Windows client that contains a collection of attributes, usually in table format. Examples of tabs for the Parts class are Title Block, Page Two, Changes, BOM, Manufacturers, Where Used, Attachments, and History.

Note: To return a particular tab, use Tabs::Find.

TargetType ObjectTypeConstants Read-only Returns one of the object type constants (see page 6-432), which indicates the type of object that can be created. Five possible object types can be returned: otItem, otChange, otMfr, otMfrPart, and otPackage.

Table 6-29: SubClass properties




Methods

FindAttributes

GetNextNumber

VbsGetNextNumber

SubClass::FindAttributes()

Syntax

BOOL FindAttributes(long tt,LPDISPATCH col)

Description

Retrieves the Collection of attributes for a specified table. For example, you can get the attributes for Page Three for a SubClass.

Parameters

tt

one of the Table type constants (see page 6-545); you can specify ttUnknown to return the Collection of attributes for all Table types

col

an output parameter that returns a Collection object containing attributes. col must point to an existing Collection object; it cannot be Null.

Returns


Example


Sub FillAttributesList(SubClass As Object)

Dim col As AgileAPI.Collection Dim Attribute As AgileAPI.Attribute Dim li As ListItem Dim b As Boolean


'Get all attributes for all table types for the SubClass b = SubClass.FindAttributes(ttUnknown, col)

6-235


'Fill the Attributes list lvwAttributes.ListItems.Clear For i = 0 To col.Count - 1 Set Attribute = col.Get(i) Set li = lvwAttributes.ListItems.Add(, , Attribute.Name) li.SubItems(1) = Attribute.BaseID Next i

End Sub

SubClass::GetNextNumber()

Syntax

BOOL GetNextNumber(LPCTSTR source,BSTR FAR* number)

Description

Generates the next AutoNumber.

Note The last number available for each AutoNumber source is 99999.

Parameters

source

string representing the AutoNumber source, a predefined consecutive number series used to automatically number objects; you can use the SubClass::AutoNumberSources property to return the collection of AutoNumber sources.

number

an output parameter that returns the next AutoNumber (a string)

Returns


Example

Private Sub GetNextNumber(SubClass As Object)

Dim nextnum As String 'Get the next AutoNumber using the first AutoNumber source If SubClass.GetNextNumber(SubClass.AutoNumberSources.Get(0), _ nextnum) Then



MsgBox "Next AutoNumber is " + nextnum Else MsgBox "Failed to get AutoNumber. " + SubClass.ErrorMessage End If

End Sub

SubClass::VbsGetNextNumber()

Syntax

BOOL GetNextNumber(LPCTSTR source,VARIANT FAR* number)

Description

A VBScript-supported version of GetNextNumber that generates the next AutoNumber.

Note The last number available for each AutoNumber source is 99999.

Parameters

source

string representing the AutoNumber source, a predefined consecutive number series used to automatically number objects; you can use the SubClass::AutoNumberSources property to return the collection of AutoNumber sources.

number

an output parameter that returns the next AutoNumber (a Variant string)

Returns


6-237


SupplierOverview

A supplier is a vendor that supplies your company with materials and various manufacturer parts. The Supplier object can originate in another system, such as a Supplier Relationship Management (SRM) system, and subsequently be imported to the Agile system. To work with the Supplier object, use methods and properties of DataObject.

Supplier is an externally creatable object. However, when you use the constructor to create a Supplier object in your program, it is an empty object that is not associated with an Agile eHub. To load an existing Supplier from an Agile Advantage eHub, use Supplier::LoadByAttr or Supplier::LoadByInfo. To create a new Supplier on an Agile Advantage eHub, use Supplier::Create.

Hierarchy

❑ Base❑ Row

❑ DataObject ❑ Supplier

Methods

Create

LoadByAttr

LoadByInfo

Supplier::Create()

Syntax

BOOL Create(LPDISPATCH server,const VARIANT FAR& subClass,LPCTSTR number,LPCTSTR name)

Description

Creates a new supplier using the specified subclass.

Parameters

server

a pointer to a Server object used to initialize the new supplier


Chapter 6 Agile Advantage API Reference – Supplier

subClass


number

number of the new supplier

name

name of the new supplier

Returns


ExamplePublic server As AgileAPI.ServerPublic currSupplier As AgileAPI.SupplierPrivate Sub cmdCreateSupplier_Click() Dim b As Boolean Set currSupplier = CreateObject("AgileAPI.Supplier") b = currSupplier.Create(server, "Broker", txtNumber.txt, txtName.Text) If Not b Then MsgBox "Failed to create supplier. " + currSupplier.ErrorMessage End IfEnd Sub

Supplier::LoadByAttr()

Syntax


Description

Loads an existing supplier into the object by specifying an attribute and its value.

Parameters

server

a pointer to a Server object used to initialize the supplier

attr

a fully qualified attribute, such as “General Info.Address,” or a base ID. You can also type 0 to use the default attribute, “General Info.Number,” or type an attribute ID constant. For a list of attributes for each class, refer to “” on page 6-261.

6-239


value

a value for the specified attribute.

Returns


ExamplePublic server As AgileAPI.ServerPublic currSupplier As AgileAPI.SupplierPrivate Sub GetSupplier_Click() Dim b As Boolean Set currSupplier = CreateObject("AgileAPI.Supplier") b = currSupplier.LoadByAttr(server, 0, txtNumber.Text) If Not b Then MsgBox "Failed to load supplier. " + currSupplier.ErrorMessage End IfEnd Sub

Supplier::LoadByInfo()

Syntax


Description

Loads an existing supplier into the object by specifying an ObjectInfo object that uniquely identifies it. The specified ObjectInfo object must have TargetID and TargetType members.

Parameters

server

a pointer to a Server object used to initialize the supplier

info

a reference to an ObjectInfo object that uniquely identifies the supplier

Returns


Example



Chapter 6 Agile Advantage API Reference – SyncOption

SyncOptionSpecifies the attributes that you want redlined when using other Agile Advantage API functions. SyncOption has a CompareIDs property that contains a Collection object filled with base ID numbers of Agile Advantage attributes.

SyncOption is an externally creatable object that is a required parameter for the following Agile Advantage API methods:

❑ Item::SyncBOM❑ Item::SyncAML❑ Server::DiffAML

These methods are used to import data to non-preliminary BOMs and AMLs. The SyncOption object is used to specify the attributes that you want redlined. Any attributes not specified in the SyncOption object are not redlined. If the SyncOption object is Null, all attributes are redlined.

After you create a SyncOption object, you can add attribute IDs to its CompareIDs property. CompareIDs is a Collection object; to add attribute IDs to it, use Collection::Add.

The following Visual Basic code shows how to create a SyncOption object with IDs for BOM redlining:

Dim ids As AgileAPI.CollectionDim syncOption As AgileAPI.SyncOption

' Create a new instance of the SyncOptionSet syncOption = CreateObject("AgileAPI.SyncOption")

' Add attribute IDs to the collectionsyncOption.CompareIDs.Add 1011, -1 'ID for BOM.Item NumbersyncOption.CompareIDs.Add 1020, -1 'ID for BOM.Part DescriptionsyncOption.CompareIDs.Add 1021, -1 'ID for BOM.Item RevsyncOption.CompareIDs.Add 1012, -1 'ID for BOM.Find NumbersyncOption.CompareIDs.Add 1035, -1 'ID for BOM.QtysyncOption.CompareIDs.Add 1019, -1 'ID for BOM.Ref Des

Hierarchy

❑ Base❑ SyncOption

6-241


Properties

Table 6-30: SyncOption properties


CompareIDs LPDISPATCH Read-only Returns a Collection object containing Long values representing base ID numbers for Agile Advantage attributes.


Chapter 6 Agile Advantage API Reference – Tab

TabOverview

A Tab object in Agile Administrator. Tab is a special kind of Node object that serves as a container of attributes for Agile Advantage classes. Examples of tabs for the Parts class are Title Block, Page Two, Changes, BOM, Manufacturers, Where Used, Attachments, and History.

Hierarchy

❑ Base❑ Node

❑ Tab

Properties

Table 6-31: Tab properties


Attributes LPDISPATCH Read-only Returns a Collection containing the tab’s attributes.

Type TabTypeConstants Read-only Returns one of the Tab type constants (see page 6-545).

6-243


TableOverview

A table containing an ordered array of Row objects. For example, the ApprovedMfrs, Attachments, and BOMComponents objects all derive from Table.

Hierarchy

❑ Base❑ Table

Properties

Table 6-32: Table properties


Attributes LPDISPATCH Read-only Returns a collection of all attributes in the table.

IsRedlinable BOOL Read-only Returns a nonzero value if a BOMComponents object can be redlined.

MissingCount LONG Read-only Returns the number of rows missing from the table due to the user’s lack of Discovery privilege for those rows.

RowCount LONG Read-only Returns the total number of rows in the table.

RowRange LONG Read/Write Sets or gets the number of rows in the row range.

Rows LPDISPATCH Read-only Returns a pointer to the Collection of rows in the table’s row range. To get individual rows from the collection, use Collection::Get.

RowStart LONG Read/Write Sets or gets the start row for the row range.

RowType ObjectTypeConstants Read-only Returns one of the object type constants (see page 6-432), which indicates the type of object contained in each row of the table.


Chapter 6 Agile Advantage API Reference – Table

Methods

AddRow

Refresh

RemoveRow

UnremoveRow

Table::AddRow()

Syntax

LPDISPATCH AddRow()

Description

Adds a new empty row at the bottom of the table. The type of object added depends on the table type. The AddRow method fails if you try to add a row to a read-only table.

You can use Table::AddRow with the table types listed in Table 6-33.

You cannot use Table::AddRow with the following read-only table types:

❑ ttChangeRelatedItems

❑ ttChangeRelatedQCR

❑ ttCustomerHistory

❑ ttCustomerRelatedPSR

Type TableTypeConstants Read-only Returns one of the Table type constants (see page 6-545), which indicates the type of table.

Table 6-33: Table types that support Table::AddRow

Table Type Type of Object Added

ttItemBOM BOMComponent

ttItemRedlineBOM BOMComponent

ttChangeAffectedItems Row

ttChangeRelatedPSR ServiceRequest

ttChangeRelatedChanges Change

ttServiceRequestRelatedPSR ServiceRequest

Table 6-32: Table properties


6-245


❑ ttItemChangeHistory ❑ ttItemHistory ❑ ttItemPendingChanges ❑ ttItemQuality ❑ ttItemWhereUsed ❑ ttChangeHistory ❑ ttMfrHistory ❑ ttMfrWhereUsed ❑ ttMfrPartHistory ❑ ttMfrPartWhereUsed ❑ ttPackageHistory ❑ ttServiceRequestHistory ❑ ttSupplierHistory

To add a row to an Attachments table, use Attachments::AddRow. To add a row to an Approved Manufacturers List (AML), use ApprovedMfrs::AddRow.

To add Approvers or Observers to the Signoff table, use RouteObject::AddApprovers.

Returns

A pointer to the Row object if the method was successful; Null otherwise.

Example

Private Sub AddRow(Table As Object)

Dim rowObject As Object

'Add a new row to the table Set rowObject = Table.AddRow

'Add the new row to the list view If Not rowObject Is Nothing Then Call RefreshTableView Else MsgBox "Failed to add DataObject. " + Table.ErrorMessage End If

End Sub



Table::Refresh()

Syntax

BOOL Refresh()

Description

Re-populates the table, making it current with the latest information from the server.

Returns


Example

Private Sub RefreshTable(Table As Object)

'Refresh the table If Not Table.Refresh Then MsgBox "Failed to refresh. " + Table.ErrorMessage Exit Sub End If

Call RefreshListView

End Sub

Table::RemoveRow()

Syntax

BOOL RemoveRow(LONG index)

Description

Removes a row item at the specified position. For all tables except the redline BOM (TableType = ttItemRedlineBOM) and the redline Manufacturers (TableType = ttItemRedlineAML), RemoveRow also decrements the Table::RowCount property by 1 and reindexes the table.

After you remove a row from a table, make sure you save the parent object using DataObject::Save. Otherwise, the row you removed remains in the table.

You cannot use Table::Remove with the following read-only table types:

❑ ttChangeRelatedItems

❑ ttChangeRelatedQCR

❑ ttCustomerRelatedPSR

6-247


❑ ttCustomerHistory

❑ ttItemChangeHistory

❑ ttItemHistory

❑ ttItemPendingChanges

❑ ttItemQuality

❑ ttItemWhereUsed

❑ ttChangeHistory

❑ ttMfrHistory

❑ ttMfrWhereUsed

❑ ttMfrPartHistory

❑ ttMfrPartWhereUsed

❑ ttPackageHistory

❑ ttServiceRequestHistory

❑ ttSupplierHistory

To remove Approvers or Observers from the Signoff table, use RouteObject::RemoveApprovers.

Parameters

index

index number of the row item to remove from the table

Returns


Example

Private Sub TableRemove(Table As Object)

'Remove the first row in the table If Not Table.RemoveRow(0) Then MsgBox "Failed to remove row. " + Table.ErrorMessage Exit Sub End If

Call RefreshListView

End Sub



Table::UnremoveRow()

Syntax

BOOL UnremoveRow(LONG index)

Description

Undoes a BOMComponents or ApprovedMfrs redline delete. This method is valid only for the redline BOM (TableType = ttItemRedlineBOM) and redline Manufacturers (TableType = ttItemRedlineAML) tables. You cannot use this method for other tables in the Agile Advantage Windows client.

Parameters

index

index number of the object to restore

Returns


Example

Private Sub TableUnremove(Table As Object)

'Unremove the object in the first row If Not Table.UnremoveRow(0) Then MsgBox "Failed to unremove row. " + Table.ErrorMessage End If

End Sub

6-249


UserOverview

An Agile Advantage user. You can use the User object to change a user’s login password or approval password. The Agile Advantage API also lets you create, modify, and delete users:

❑ To get a collection of user names, use Server::Users.❑ To get the current user, use Server::CurrentUser.❑ To create a new user, use Node::CreateUser.❑ To modify a user’s properties, use Property::SetValue or User::SetValue.❑ To delete a user, use Node::Delete.

Note To modify a subnode of the Users nodes, you must have Administrator privileges and log in to the Agile Advantage eHub using Server::LoginEx.

Hierarchy

❑ Base❑ Node

❑ User

Methods

ChangePassword

CheckPrivilege

GetValue

HasLicense

IsLicensed

ReleaseLicense

SetValue

VbsChangePassword

User::ChangePassword()

Syntax

BOOL ChangePassword(LPCTSTR oldLoginPwd,LPCTSTR newLoginPwd,


Chapter 6 Agile Advantage API Reference – User

LPCTSTR oldApprovalPwd,LPCTSTR newApprovalPwd)

Description

Changes the user’s login or approval passwords, or both. Use this method in the event that a user’s password expires and your application needs to allow her to reset it.

If oldLoginPwd is Null (an empty string), only the approval password is changed. If oldApprovalPwd is Null, only the login password is changed. Otherwise, both passwords are changed.

Note Users who do not have a separate approval password (in Agile Administrator, the “Use Login Password” option is checked) cannot change their approval password.

Parameters

oldLoginPassword

the old login password

newLoginPassword

the new login password

oldApprovalPassword

the old approval password

oldApprovalPassword

the new approval password

Returns


Example

Public server As AgileAPI.ServerPublic currUser As AgileAPI.User

Private Sub Change_Password_Click()

'Get the current user Set currUser = server.CurrentUser

'Determine which password to change based on whether the 'Login Password or Approval Password option buttons are selected If optLoginPassword.Value Then

6-251


b = User.ChangePassword(txtOldLoginPassword.Text, _ txtNewLoginPassword.Text, "", "") Else b = User.ChangePassword("", "", txtOldApprovalPassword.Text, _ txtNewApprovalPassword.Text) End If If b Then MsgBox "Password changed successfully." Else MsgBox "Failed to change password! " + currUser.ErrorMessage End If End Sub

User::CheckPrivilege()

Syntax

BOOL CheckPrivilege(long privID,LPDISPATCH dataObject,long attrID)

Description

Checks whether a user has a particular privilege for an Agile Advantage object. If the user does not have the specified privilege, CheckPrivilege returns 0.

Parameters

privID

one of the User privilege ID constants (see page 6-550)

dataObject

a pointer to one of the five main objects in the Agile Advantage system: Change, Item, Mfr, MfrPart, or Package.

For the following privID values, dataObject can be Null:

❑ upidAdministrator❑ upidGlobalGroups❑ upidGlobalSearch❑ upidReports❑ upidCustomizeResults❑ upidServerMonitor



attrID

if privID is equal to upidCreate, enter the subclass ID for the object; if privID is equal to upidModify, enter the base ID of an Attribute; if privID is another privilege ID constant, the privID parameter is ignored (you can enter any number).

Returns

Nonzero if the user has the specified privilege; 0 otherwise.

Example

Private Sub CheckPrivs(obj As Object, user as Object)

Dim b As Boolean

'Check if the user has GetFile privileges b = user.CheckPrivilege(upidGetFile, obj, 0) If b Then cmdGetFile.Enabled = True Else cmdGetFile.Enabled = False End If

'Check if the user has CheckOut privileges b = user.CheckPrivilege(upidCheckOut, obj, 0) If b Then cmdCheckout.Enabled = True Else cmdCheckout.Enabled = False End If

'Check if the user has CheckIn privileges b = user.CheckPrivilege(upidCheckIn, obj, 0) If b Then cmdCheckin.Enabled = True Else cmdCheckin.Enabled = False End If

End Sub

6-253


User::GetValue()

Syntax

BOOL GetValue(long vt,VARIANT FAR* value)

Description

Returns a User property value by specifying a User value type constant. This method allows you to determine whether the user has a separate approval password or is currently set to use the login password for approvals.

Parameters

vt

one of the User value type constants (see page 6-552)

value

the value for the specified user value type; for uvtUseLoginPwdForApproval the return value is a Boolean value (nonzero or 0).

Returns

Nonzero if the user has the specified privilege; 0 otherwise.

Example

Public server As AgileAPI.ServerPublic currUser As AgileAPI.User

Private Sub CheckIfTwoPasswords()

Dim b as Boolean Dim val As Variant

'Check if the user has a separate approval password b = currUser.GetValue(uvtUseLoginPwdForApproval, val)

'If val is TRUE then disable the Change Approval Password button If val Then cmdChangeApprovalPwd.Enabled = False Else cmdChangeApprovalPwd.Enabled = True End If End Sub



User::HasLicense()

Syntax

BOOL HasLicense(LicenseConstants license)

Description

Specifies whether the user has a license to a particular Agile Advantage product during the current login session.

Parameters

license

one of the User license constants (see page 6-550)

Returns


Example

Public currUser As AgileAPI.User

Private Sub frmCheckLicenses_Activate(server As Object)

Set currUser = server.CurrentUser

If currUser.HasLicense(ulProductChange) Then chkProductChange.Value = 1 chkProductChange.Enabled = True Else chkProductChange.Value = 0 chkProductChange.Enabled = False End If

If currUser.HasLicense(ulAML) Then chkAML.Value = 1 chkAML.Enabled = True Else chkAML.Value = 0 chkAML.Enabled = False End If

If currUser.HasLicense(ulPackage) Then chkPackage.Value = 1 chkPackage.Enabled = True Else

6-255


chkPackage.Value = 0 chkPackage.Enabled = False End If

End Sub

User::IsLicensed()

Syntax

BOOL IsLicensed(LicenseConstants license)

Description

Specifies whether the user has been assigned rights to use a particular Agile Advantage product license. Users are assigned Agile Advantage product licenses in Agile Administrator. A user who has not been assigned an Agile Advantage product license does not have access to that product’s features in your Agile Advantage API program.

By default, your Agile Advantage API program uses all available product licenses that have been assigned to a user. You can use IsLicensed to check whether a user has been assigned an Agile Advantage product license. If IsLicensed returns 0 for a particular license, then HasLicense also returns 0 for the same license.

Parameters

license

one of the User License Constants (see page 6-550)

Returns


Example


Private Sub CheckIfLicensed(server As Object)


'Check if the user has a Product Change license. 'If not, show an error message and prevent login. b = currUser.IsLicensed(ulProductChange) If Not b Then MsgBox "You do not have a Product Change license," & Chr(13) _ & "which is required to run this program." & Chr(13) _



& "Please see your Agile system administrator.", _ vbExclamation, "Error" End End If

End Sub

User::ReleaseLicense()

Syntax

BOOL ReleaseLicense(LicenseConstants license)

Description

Releases an Agile Advantage product license to other users for their use. If you have a limited number of Agile Advantage licenses, you may need to release a license for another user to use the product.

ReleaseLicense is available only if your Agile Advantage installation uses the Concurrent license model. If you use the Subscription license model, the ReleaseLicense method fails. To find which type of Agile license you have, use Server::GetLicenseType (see page 6-216).

Note You cannot release the Product Definition license (license = ulProductDefinition) because it is required for all Agile API applications.

Before attempting to release a particular license, use HasLicense to determine if the user has the license for the current login session.

Parameters

license

one of the User license constants (see page 6-550)

Returns


Example




'If the Product Change checkbox is enabled and unchecked,

6-257


'then release the license If chkProductChange.Enabled = True Then If chkProductChange.Value = 0 Then currUser.ReleaseLicense ulProductChange End If End If

'If the AML checkbox is enabled and unchecked, 'then release the license If chkAML.Enabled = True Then If chkAML.Value = 0 Then currUser.ReleaseLicense ulAML End If End If

'If the Package checkbox is enabled and unchecked, 'then release the license If chkPackage.Enabled = True Then If chkPackage.Value = 0 Then currUser.ReleaseLicense ulPackage End If End If

frmLicenses.Hide frmMain.Show

End Sub

User::SetValue()

Syntax

BOOL SetValue(long vt, const VARIANT FAR& value)

Description

Sets a User property value by specifying one of the User Value Type constants.

Parameters

vt

one of the User Value Type constants (see page 6-552). The only supported values are uvtMyAgileUsername, which sets the MyAgile.com username, and uvtMyAgilePwd, which sets the MyAgile.com password.



value

the value for the specified user value type; for both uvtMyAgileUsername and uvtMyAgilePwd, the Variant value must be a string.

Returns


User::VbsChangePassword()

Syntax

BOOL ChangePassword(VARIANT oldLoginPwd,VARIANT newLoginPwd,VARIANT oldApprovalPwd,VARIANT newApprovalPwd)

Description

A VBScript-supported version of ChangePassword that changes the user’s login or approval passwords, or both. Use this method in the event that a user’s password expires and your application needs to allow her to reset it. The major difference between VbsChangePasword and ChangePassword is that VbsChangePassword parameters are Variant types, not strings, which permits you to pass null values for the oldLoginPwd and oldApprovalPwd parameters in a VBScript.

If oldLoginPwd is Null (an empty string), only the approval password is changed. If oldApprovalPwd is Null, only the login password is changed. Otherwise, both passwords are changed.

Note Users who do not have a separate approval password (in Agile Administrator, the “Use Login Password” option is checked) cannot change their approval password.

Parameters

oldLoginPassword

the old login password

newLoginPassword

the new login password

oldApprovalPassword

the old approval password

6-259


oldApprovalPassword

the new approval password

Returns



Chapter 6 Agile Advantage API Reference –

6-261



INDEX

AAbbreviations 2-7Abort method 6-75, 6-154Active Server Pages 2-19

ASP 4-39, Index-1ActivityQuery object 6-3

Create() 6-4Execute() 6-5FromDate() 6-3GetItemInfo() 6-6GetItemNumber() 6-7GetItemRevision() 6-8GetTargetStates() 6-9GetWorkflowID() 6-10ItemCount() 6-3MissingCount() 6-3SetTargetStates() 6-10SetWorkflowID() 6-11States() 6-3ToDate() 6-3Type() 6-3

Add method 6-59AddApprovers method 6-177AddCriteria method 6-155AddFile method 6-17AddItem method 6-98AddRow method 6-14, 6-26, 6-245Adobe Acrobat Reader 1-4Agile Advantage API objects 2-2Agile CM features 2-22Agile SDK

Features 1-2Overview 1-1

AgileAPI75.dll 1-3, 2-35AgileAPI80.dll 1-3, 2-35AgileAPI85.dll 1-3, 2-35AgileAPI90.dll 1-3, 2-35

AgileAPI.dll 1-1, 1-3, 2-35AgileAPI.lic 1-4APMsg32.dll 1-3, 2-35Approve method 6-179ApprovedMfr object 6-12, 6-14

AddRow() 6-14SetMfrPart() 6-12

Attachment object 6-16, 6-26AddFile() 6-17AddRow() 6-26CancelCheckOut() 6-18CheckIn() 6-18CheckOut() 6-19DeleteVersion() 6-20FileCount() 6-16GetFileID() 6-21GetFile() 6-20GetPrintOption() 6-22GetVersionInfo() 6-20, 6-22GetVersions() 6-23Image() 6-16IsImage() 6-26IsSecure() 6-16PrintFile() 6-24SetCurrentVersion() 6-25VbsGetVersionInfo() 6-25

Attribute object 6-29BaseID() 6-29DataType() 6-29FullName() 6-29IsVisible() 6-29ListElements() 6-29Name() 6-29TableName() 6-29

Attribute property 6-42, 6-85, 6-152, 6-233, 6-243, 6-244

Attributes 2-13–2-18

Index-1


Fully qualified 2-15IDs 2-14Names 2-14Referencing 2-14Shared between classes 2-17Tabs and tables 2-15

Audit method 6-180AutoNumberSources property 6-233

BBase object 6-30

CancelBlockingCall() 6-32Compact() 6-33DisableError() 6-33EnableError() 6-34ErrorCode() 6-30ErrorMessage() 6-30GetObjectInfo() 6-35IsDirty() 6-30IsInit() 6-31ObjectID() 6-31ObjectType() 6-31Parent() 6-31Server() 6-31Tag() 6-31

BaseID property 6-29, 6-85Batch printing 6-24BOMComponent object 6-37, 6-39

Children() 6-37Expand() 6-37GetEffectivePeriod() 6-39SetEffectivePeriod() 6-40

BOOL data type 2-13Boolean data type 2-13BSTR data type 2-13

CCancelBlockingCall method 6-32CancelCheckOut method 6-18CARs 2-32, 5-12CCBQuery object 6-42

Attributes() 6-42

ColumnAttribute() 6-42ColumnCount() 6-42Create() 6-44Execute() 6-45FilterQuery() 6-42FromDate() 6-42FromState() 6-42GetColumnHeader() 6-46GetItemCount() 6-47GetItemInfo() 6-48GetItemValue() 6-48GetRowHeader() 6-50GetValue() 6-50GetWorkflowID() 6-52MissingCount() 6-43RowCount() 6-43SetWorkflowID() 6-52States() 6-43TimeInterval() 6-43ToDate() 6-43ToState() 6-43Type() 6-43

Change object 6-53Create() 6-53LoadByAttr() 6-54LoadByInfo() 6-55

ChangePassword method 6-250CheckIn method 6-18CheckOut method 6-19CheckPrivilege method 6-252CheckValidOperation method 6-76, 6-194ChildNode property 6-136Children property 6-37Class ID 2-16ClassID property 6-138, 6-233Clear method 6-60, 6-99ClearCache method 6-156Close method 6-181, 6-183Clustered eHubs 6-213Collection object 6-58

Add() 6-59Clear() 6-60

Index-2 Developer Guide

Index

ContainsKey() 6-61Contains() 6-61Count() 6-59DataType() 6-59FindIndex() 6-63Find() 6-62Get() 6-64IsReadOnly() 6-59Remove() 6-65SetDataType() 6-65

ColumnAttribute property 6-42ColumnCount property 6-42Comment method 6-181, 6-183Common terms 2-6Compact method 6-33Connect method 6-209Constants 6-261–??

Prefixes 2-8Containers 2-2Contains method 6-61ContainsKey method 6-61Count property 6-59Create method 6-4, 6-44, 6-53, 6-71, 6-100,

6-112, 6-127, 6-131, 6-157, 6-230,6-238

CreateUser method 6-136Creating objects 2-4CriteriaBag object 6-67

CriteriaCount() 6-67GetAttributes() 6-68GetCriteriaData() 6-69IsCaseSensitive() 6-67

CriteriaCount property 6-67, 6-152CurrentUser property 6-206Customer object 6-71

Create() 6-71LoadByAttr() 6-73LoadByInfor() 6-74

Customers 2-32, 5-3

DData types 2-13

DataObject object 6-75Abort() 6-75CheckValidOperation() 6-76Delete() 6-78GetTable() 6-80IsDeleted() 6-75IsUpToDate() 6-75Refresh() 6-81SaveAs() 6-82Save() 6-81Send() 6-83Undelete() 6-84

DataType property 6-29, 6-59, 6-85Date fields

Getting values for 6-88, 6-199Setting values for 6-93, 6-203

Declaring object variables 2-3Delete method 6-78, 6-101, 6-137, 6-158DeleteCriteria method 6-159DeleteVersion method 6-20Deleting objects

Hard-delete 6-79Soft-delete 6-79Undeleting 6-84

Description property 6-97, 6-98Deviation Change object 6-53DiffAML method 6-210DisableError method 6-33Disconnect method 6-211Discovery privilege 6-195DiscoveryPrivilege property 6-85, 6-192DisplayString property 6-147Distributing applications 2-35Document Item object 6-112

EEarly binding 2-3, 4-6ECO Change object 6-53ECR Change object 6-53Effective period

GetEffectivePeriod method 6-39SetEffectivePeriod method 6-40

Index-3


eHubMsg.dll 1-3, 2-35EnableError method 6-34Encryption 1-5Error handling 4-9ErrorCode property 6-30ErrorMessage property 6-30Execute method 6-5, 6-45, 6-159Expand method 6-37Expire method 6-184Externally createable objects 2-4

FFailover support 6-213Field object 6-85

Attribute() 6-85BaseID() 6-85DataType() 6-85DiscoveryPrivilege() 6-85GetValue() 6-86IsReadOnly() 6-86IsRedlined() 6-86IsRedlineShown() 6-86ListElements() 6-86Name() 6-86SetNull() 6-91SetValue() 6-91ShowRedline() 6-96UndoRedline() 6-96

Fields property 6-192FileCount property 6-16FileServerBufferSize property 6-206FileServerCacheDir property 6-206FileServerHostname property 6-206FileServerPort property 6-206FileServerSchema property 6-206FilterQuery property 6-42Find method 6-62FindAttributes method 6-235FindIndex method 6-63FindItemIndex method 6-102Folder object 6-97

AddItem() 6-98

Clear() 6-99Create() 6-100Delete() 6-101Description() 6-97, 6-98FindItemIndex() 6-102GetItemInfo() 6-102GetItemName() 6-103GetName() 6-104GetSortOrder() 6-104GetType() 6-105ItemCount() 6-97LoadByInfo() 6-106OrderItems() 6-107Refresh() 6-108RemoveItem() 6-109SetName() 6-109SetSortOrder() 6-110SetType() 6-110

FromDate property 6-3, 6-42FromState property 6-42FullName property 6-29Fully qualified attributes 2-15

GGet method 6-64GetApprovers method 6-184GetAttribute method 6-212GetAttributes method 6-68GetAttrValues method 6-160GetClass method 6-160GetColumnHeader method 6-46GetCriteriaData method 6-69, 6-161GetDefaultNextStatusID method 6-185GetDefaultNotifyList method 6-186GetEffectivePeriod method 6-39GetFailoverServerList method 6-213GetFieldDiscPriv method 6-195GetFile method 6-20GetFileID method 6-21GetHomeFolderInfo method 6-215GetIncorporated method 6-113GetItemCount method 6-47


Index

GetItemInfo method 6-6, 6-48, 6-102GetItemName method 6-103GetItemNumber method 6-7GetItemRevision method 6-8GetItemValue method 6-48GetLicenseType method 6-216GetListElement method 6-217GetListElements method 6-218GetLogicalOperators method 6-163GetName method 6-104, 6-164GetNextNumber method 6-236GetNextStatusIDs method 6-186GetNode method 6-219, 6-220GetObjectInfo method 6-35GetPrintOption method 6-22GetReferentInfo method 6-195GetRelationalOperators method 6-165GetResultDisplay method 6-166GetRevision method 6-114GetRevisions method 6-116GetRowHeader method 6-50GetSortOder method 6-104GetStatus method 6-196GetStatusIDs method 6-187GetTable method 6-80GetTargetStates method 6-9GetType method 6-105, 6-166GetValue method 6-50, 6-86, 6-148, 6-197,

6-254GetVersionInfo method 6-20, 6-22GetVersions method 6-23GetWhereUsedType method 6-167GetWorkflowID method 6-10, 6-52, 6-187GetWorkflowIDs method 6-188

HHard-delete 6-79HasLicense method 6-255History list 6-201Hold method 6-188Home folder 6-215Hostname property 6-206

IID property 6-126, 6-147Image property 6-16Incorporating an Item

GetIncorporated method 6-113SetIncorporated method 6-118

Inheritance 2-2Inheritance model 2-2IsAutoNumberRequired property 6-233IsCaseSensitive property 6-67, 6-152IsConnected property 6-207IsDeleted property 6-75IsDirty property 6-30IsImage property 6-26IsInit property 6-31IsLicensed method 6-256IsLogin property 6-207IsObsolete property 6-126IsReadOnly property 6-59, 6-86, 6-147IsRedlinable property 6-244IsRedlined property 6-86IsRedlineShown property 6-86IsSecure property 6-16Issues 2-32, 5-7IsUpToDate property 6-75IsVisible property 6-29Item object 6-112

Create() 6-112GetIncorporated() 6-113GetRevisions() 6-116GetRevision() 6-114LoadByAttr() 6-117LoadByInfor() 6-118SetIncorporated() 6-118SetRevision() 6-119SyncAML() 6-120SyncBOM() 6-122VbsGetRevision() 6-124

ItemCount property 6-3, 6-97

LLate binding 2-3

Index-5


LeftFooter property 6-144LeftHeader property 6-144List fields


ListElement object 6-125ID() 6-126IsObsolete() 6-126Value() 6-126

ListElements property 6-29, 6-86, 6-147ListID property 6-147LoadByAttr method 6-54, 6-73, 6-117, 6-

128, 6-133, 6-140, 6-231, 6-239LoadByInfo method 6-55, 6-74, 6-106, 6-

167, 6-232, 6-240LoadByInfor method 6-118, 6-129, 6-134,

6-142Loading

Changes 6-54, 6-55Folders 6-106Items 6-117, 6-118Manufacturer Parts 6-133, 6-134Manufacturers 6-128, 6-129Packages 6-140, 6-142Queries 6-167

LogAction method 6-201Login method 6-222, 6-223LoginEx method 6-223LONG data type 2-13LPCTSTR data type 2-13LPDISPATCH data type 2-13

MMapping features to APIs 2-22Mask property 6-138MCO Change object 6-53Memory management 2-18Methods 2-11mfc42.dll 1-4Mfr object 6-127

Create() 6-127LoadByAttr() 6-128

LoadByInfor() 6-129Mfr property 6-131MfrNames property 6-207MfrPart object 6-131

Create() 6-131LoadByAttr() 6-133LoadByInfor() 6-134Mfr() 6-131

MidFooter property 6-144MidHeader property 6-144MissingCount property 6-3, 6-43, 6-244MSVCRT.dll 1-4, 2-35MultiList fields


Multithreading 2-19

NName collisions 2-3Name property 6-29, 6-86, 6-136, 6-147, 6-

233Naming conventions 2-5New features 1-1

Classes 3-1, 3-2Constants 3-2, 3-3Methods 3-2, 3-3

Node object 6-135ChildNode() 6-136CreateUser() 6-136Delete() 6-137Name() 6-136Properties() 6-136Type() 6-136

Numeric text fieldsGetting values for 6-88, 6-198Setting values for 6-92, 6-203

OObject Browser 4-3Object data type 2-13Object hierarchy 2-2Object variables 2-19


Index

ObjectID property 6-31ObjectInfo object 6-138

ClassID() 6-138Mask() 6-138SubClassID() 6-138TargetID() 6-138TargetType() 6-138

ObjectType property 6-31OrderItems method 6-107Owner property 6-152

PPackage method 6-139Package object 6-139

LoadByAttr() 6-140LoadByInfor() 6-142Package() 6-139

Parent property 6-31Part Item object 6-112PDF documentation 1-4Port property 6-207Prefixes for constants 2-8PrintFile method 6-24Printing image attachments 6-24PrintOption object 6-143

LeftFooter() 6-144LeftHeader() 6-144MidFooter() 6-144MidHeader() 6-144RightFooter() 6-144RightHeader() 6-144ShowRedlines() 6-144Watermark() 6-144

Problem reports 2-32, 5-6Properties 2-9Properties property 6-136Property object 6-146

DisplayString() 6-147GetValue() 6-148ID() 6-147IsReadOnly() 6-147ListElements() 6-147

ListID() 6-147Name() 6-147SetListElements() 6-149SetValue() 6-150Type() 6-148

QQuality 5-1–5-21

Objects 5-2Roles and privileges 5-2

Quality Change Requests 2-32Query object 6-152

Abort() 6-154AddCriteria() 6-155Attribute() 6-152ClearCache() 6-156Create() 6-157CriteriaCount() 6-152DeleteCriteria() 6-159Delete() 6-158Execute() 6-159GetAttrValues() 6-160GetClass() 6-160GetCriteriaData() 6-161GetLogicalOperators() 6-163GetName() 6-164GetRelationalOperators() 6-165GetResultDisplay() 6-166GetType() 6-166GetWhereUsedType() 6-167IsCaseSensitive() 6-152LoadByInfo() 6-167Owner() 6-152Refresh() 6-168ResultCacheSize() 6-153ResultCount() 6-153ResultMissingCount() 6-153ResultRange() 6-153ResultStart() 6-153Results() 6-153SaveAs() 6-169Save() 6-169

Index-7


SetClass() 6-170SetCriteriaData() 6-170SetName() 6-172SetResultDisplay() 6-172SetType() 6-174SetWhereUsedType() 6-174VbsGetCriteriaData() 6-175

QueryClasses property 6-207

RRead privilege 6-195Redlines

IsRedlinable property 6-244IsRedlineShown property 6-86ShowRedline method 6-96UndoRedline method 6-96

redlinesIsRedlined property 6-86

Referent property 6-193Refresh method 6-81, 6-108, 6-168, 6-247Registry settings 6-223Reject method 6-188ReleaseLicense method 6-257Releasing objects from memory 2-18Remove method 6-65RemoveApprovers method 6-189RemoveItem method 6-109RemoveRow method 6-247ResultCacheSize property 6-153ResultCount property 6-153ResultMissingCount property 6-153ResultRange property 6-153Results property 6-153ResultStart property 6-153Revisions

GetRevision method 6-114GetRevisions method 6-116SetRevision method 6-119

RightFooter property 6-144RightHeader property 6-144RouteObject object 6-177

AddApprovers() 6-177

Approve() 6-179Audit() 6-180Close() 6-181, 6-183Comment() 6-181, 6-183Expire() 6-184GetApprovers() 6-184GetDefaultNextStatusID() 6-185GetDefaultNotifyList() 6-186GetNextStatusIDs() 6-186GetStatusIDs() 6-187GetWorkflowIDs() 6-188GetWorkflowID() 6-187Hold() 6-188Reject() 6-188RemoveApprovers() 6-189SetWorkflowID() 6-190StatusID() 6-177

Row object 6-192CheckValidOperation() 6-194DiscoveryPrivilege() 6-192Fields() 6-192GetFieldDiscPriv() 6-195GetReferentInfo() 6-195GetStatus() 6-196GetValue() 6-197LogAction() 6-201Referent() 6-193RowIndex() 6-193SetValue() 6-202

RowCount property 6-43, 6-244RowIndex property 6-193RowRange property 6-244Rows property 6-244RowStart property 6-244RowType property 6-244

SSave method 6-81, 6-169SaveAs method 6-82, 6-169Searching

Running a search 6-159Security 1-5


Index

Send method 6-83Server object 6-206

Connect() 6-209CurrentUser() 6-206DiffAML() 6-210Disconnect() 6-211FileServerBufferSize() 6-206FileServerCacheDir() 6-206FileServerHostname() 6-206FileServerPort() 6-206FileServerSchema() 6-206GetAttribute() 6-212GetFailoverServerList() 6-213GetHomeFolderInfo() 6-215GetLicenseType() 6-216GetListElements() 6-218GetListElement() 6-217GetNode() 6-219, 6-220Hostname() 6-206IsConnected() 6-207IsLogin() 6-207LoginEx() 6-223Login() 6-222, 6-223MfrNames() 6-207Port() 6-207QueryClasses() 6-207SetClientTime() 6-225SetLicenseKey() 6-226SubClasses() 6-207TranslateClassID() 6-227Users() 6-207

Server property 6-31ServiceRequest object

Create() 6-230LoadByAttr() 6-231LoadByInfo() 6-232

SetClass method 6-170SetClientTime method 6-225SetCriteriaData method 6-170SetCurrentVersion method 6-25SetDataType method 6-65SetEffectivePeriod method 6-40

SetIncorporated method 6-118SetLicenseKey method 6-226SetListElements method 6-149SetMfrPart method 6-12SetName method 6-109, 6-172SetNull method 6-91SetResultDisplay method 6-172SetRevision method 6-119SetSortOrder method 6-110SetTargetStates method 6-10SetType method 6-110, 6-174SetValue method 6-91, 6-150, 6-202, 6-258SetWhereUsedType method 6-174SetWorkflowID method 6-11, 6-52, 6-190ShowRedline method 6-96ShowRedlines property 6-144Signoff table 6-178, 6-189Soft-delete 6-79States property 6-3, 6-43Status (GetStatus method) 6-196StatusID property 6-177Stop Ship Change object 6-53String data type 2-13String values

Getting 6-87, 6-198Setting 6-92, 6-202

SubClass objectAttributes() 6-233AutoNumberSources() 6-233ClassID() 6-233FindAttributes() 6-235GetNextNumber() 6-236IsAutoNumberRequired() 6-233Name() 6-233SubClassID() 6-234Tabs() 6-234TargetType() 6-234VbsGetNextNumber() 6-237

Subclass object 6-233SubClasses property 6-207SubClassID property 6-138, 6-234Supplier object 6-238

Index-9


Create() 6-238LoadByAttr() 6-239LoadByInfor() 6-240

SyncAML method 6-120SyncBOM method 6-122SyncOption object 6-241

TTab object 6-243

Attributes() 6-243Type() 6-243

Table object 6-244AddRow() 6-245Attributes() 6-244Getting 6-80IsRedlinable() 6-244MissingCount() 6-244Refresh() 6-247RemoveRow() 6-247RowCount() 6-244RowRange() 6-244RowStart() 6-244Rows() 6-244RowType() 6-244Type() 6-245UnremoveRow() 6-249

TableName property 6-29Tabs property 6-234Tag property 6-31TargetID property 6-138TargetType property 6-138, 6-234Text fields


Thread synchronization 2-19TimeInterval property 6-43ToDate property 6-3, 6-43ToState property 6-43TranslateClassID method 6-227Tutorials 4-1–4-47

Active Server Pages (ASP) 4-39Creating a query 4-11

Redlining a BOM 4-33Synchronizing BOMs 4-23Visual Basic 4-1Visual InterDev 4-39

Type property 6-3, 6-43, 6-136, 6-148, 6-243, 6-245

UUndelete method 6-84UndoRedline method 6-96UnremoveRow method 6-249Upgrading programs 3-1–3-4User object 6-250

ChangePassword() 6-250CheckPrivilege() 6-252GetValue() 6-254HasLicense() 6-255IsLicensed() 6-256ReleaseLicense() 6-257SetValue() 6-258VbsChangePassword() 6-259

UsersCreating and modifying 2-20

Users property 6-207

VValue property 6-126VARIANT data type 2-13VbsChangePassword method 6-259VBScript 2-19, 4-45VbsGetCriteriaData method 6-175VbsGetNextNumber method 6-237VbsGetRevision method 6-124VbsGetVersionInfo method 6-25Visual Basic 2-13Visual InterDev 4-39

WWatermark property 6-144Where Used queries 6-167, 6-174


Index

Index-11

