Empower Toolkit Whitepaper March 2009

Transcription

1 Empower Toolkit Whitepaper March 2009

2 Empower 2 Introduction... 6 Project Object & User Object Changes... 6 System Audit Trail Policy Changes... 7 Project Audit Trail Policy Changes Project Hierarchies DBProject Changes SampleSetLine Object Dissolution Empower 2 Feature Releases Empower 2 Feature Release 3 Method Validation Manager Validation Application Launch Validation Results ValidationResultViewer ValidationResults ValidationResult Validation Protocol Method RequiredApprovalSet ProtocolTestLines ProtocolTestLine SampleSetRequestLines SampleSetRequestLine AcquisitionParameterSet AcquisitionParameterSetLevel AcquisitionParameterSetFilter AcquisitionParameterSetSolnStab AcquisitionParameterSetRobustness Factors Factor Sample Fields Sample Set Fields Result Fields Peak Fields Default Strings Project Properties User Privileges User Types Project Type Restrictions ViewFilters enhancement to Viewer objects Report Publisher Launch Enhancement InjectionViewer Object Injections collection Waters Corporation 2 of 97

3 Injection object CustomFieldViewer Object CustomFields collection CustomField object Instrument Configurations Empower 2 Feature Release 4 Toolkit Enhancements Enhancement SCR (ChannelViewer and ResultViewer objects) Empower 2 Feature Release Documentation issue PCS#30944(TKCtrl) Enhancement (Toolkit Help) Defect Fixed PCS # Defect Fixed PCS #40649 (Project) Defect Fixed PCS # Empower Introduction Creating Custom Menus QuickStart Interface DBProject Object Empower Service Packs Problems Fixed with Empower Toolkit Service Pack Fix defect PCS #28591 (Toolkit Memory Leak) Fix defect PCS #28480 (Quick Start Interface) Fix defect PCS #28474 (Apex Track) Fix defect PCS #29096 (LaunchMillApp Method) Fix defect PCS #29563 (Enforce Unique User Account Names) Fix defect PCS #29565 (Project Object Login) Fix defect PCS #29594 (Result and Sample Information Changes) Fix defect PCS #29675 (Copy From Non-FAT to FAT Projects) Fix defect PCS #28711 (User Object) Fix defect PCS #30959 (KPRIME) Fix defect PCS #31170 (Data Acquisition Privileges) Fix defect PCS #31242 (Copy Preferences) New Features Added with Empower Toolkit Service Pack PCS #28590 (Summarize Function) Custom Menu Item Argument Com Instrument XML Interface IEEE Instrument Setup for Waters 486, 410, 2410, 2414, 2790/5 and Agilent 5890/7673, 5890S/7673S, 6890 GC s InstSetup InstSetup InstSetup InstSetup InstSetup InstSetup InstSetup7673S Plate Layout Position Property Problems Fixed with Empower 1154 Service Pack I Waters Corporation 3 of 97

4 Fix defect PCS #36635 (project archival) Enhancements made to Toolkit with Empower 1154 Service Pack L Enhancement SCR Make View Filters Accessible via ToolKit Enhancement SCR Launch Report Publisher With a Specified Report.66 Enhancement SCR Make Injections Accessible via ToolKit Enhancement SCR (InstConfig) Enhancement SCR (CustomfieldViewer) Millennium 32 V4.0 Introduction Versioning Changes to the Instrument Object Archive File Versioning SampleSetViewer, ResultSetViewer Objects Sample Set Viewer SampleSets SampleSet ResultSetViewer ResultSets ResultSet Instrument Status Return Codes Alter Sample Queue Instrument Object changes SampleSetQueueEntries SampleSetQueueEntry Project.Login enhancements PlateDef and PlatePosition objects PlatePosition PlateLayouts PlateLayout PlateDef Access in SampleSetMethod Object Sample Set Editor/Wizard Dialogs User Type Object MethodSet Object Enhance - Derived Chans MethodSet Object Properties Addition: Derived Channels Derived Channel Method Fetching Enhancement - FetchById() InstSetup Instrument Method Enhancement - Monitor Baseline Method Instrument Matching Examples & Example Versioning Remove Toolkit Diskettes Millennium 32 V4.0 Service Pack J Problems Fixed with Service Pack J PCS #28590 (Summarize Function) Fix defect PCS #28591 (Toolkit Memory Leak) Fix defect PCS #28589 (samplesetline.components.add) Waters Corporation 4 of 97

5 Archive Object vs. cmgrlib.dll FAQ Waters Corporation 5 of 97

6 Chapter 1 Empower 2 Introduction This chapter outlines changes and enhancements made to the Empower 2 Toolkit with the release of Empower version 2. Due to major enhancements in base Empower functionality with features such as multiple User Roles and Project Hierarchies, your existing toolkit applications must be updated to properly operate within Empower 2. Keep in mind that Toolkit calls are checked against the user account logged into the system, ensuring that user account has the appropriate Empower privilege to perform the action. For your convenience, we have listed some of the major Toolkit calls within this chapter. Project Object & User Object Changes Empower users often have multiple accounts to allow them to perform different jobs with varying privileges. Empower 2 now allows a user account to take on more than one role within the database. An optional parameter that allows the ToolKit user to specify a role (UserType) for the user provided has been added to the Project object s Login method. The AllowedUserTypes property, which provides access to the list of user types a given user is allowed to login as, has also been added to the User object. Project Method changes: Login(Database, ProjectName, UserName, Password, [optional] UserType) Database as String Contains the name of the node where the database resides. An empty string indicates that the local service is to be used. ProjectName as String Contains the project name which will be accessed by all other Project objects. An empty string indicates that a Login without a password is to be performed. This allows the Names() property to be called. Once the desired project name is obtained, Login must be called again with a full set of parameters. UserName as String Contains the user s name. Password as String Contains the password associated with the user name. UserType as String [optional] Contains the role for this login session for this particular user. The given role must be one of the allowed user types for this user, otherwise an error is returned. If this parameter is not specified, the default user type is selected for this session. Action: Waters Corporation 6 of 97

7 Logs user into Empower database at the Database location onto the desired project. If the Database is (a zero length string), then the local database is logged onto. User Property addition: AllowedUserTypes() as Variant Sets the allowed user types for the user. Returns the current allowed user types for this user. Action: The user types are returned in a variant array of strings, each string specifying a user type. To add a user type that has Administrator privileges, the currently logged in user must have the Administrator privilege. System Audit Trail Policy Changes Empower 2 now allows system administrators the ability to provide more granularity in the way that system-level audit trails are performed. System administrators can now define how changes to a particular system-level object will be audit trailed. A new system policies tab called System Audit Trail Policies was added to Empower System Policies. It allows individual settings against system objects. The following list details the system objects related to Toolkit objects: System Object Project User User Types User Groups Toolkit Object(s) DBProject (Copy, Remove, Store, BackupProject, RestoreProject, LockProject) User (Store, Remove) User Type (Store, Remove) User Group (Create, Remove, Rename) The new tab contains a comment type column combo box with three comment types. These comment types modify the system behavior when a user modifies a system object, logging the change to the object, the name of the user who made the change, the date/time the change occurred, and the user s comment. The comment types are as follows: Unrestricted The comment entry dialog allows the user to select from a list of default strings or to enter free-form comments within the Comments text box. Restricted The comment entry dialog allows the user to select one of the predefined comments in the comment combo box only. The user may not alter the selected comment and the Comments text box is disabled. Silent Performs the Empower 1154 style audit trail where system objects are always audit trailed, but no comments are solicited from the user. The new tab also contains a Confirm Identity column, which, when selected, requires the user to re-authenticate himself before the system object is created or altered. Waters Corporation 7 of 97

8 From a Toolkit perspective, the following scenarios exist for Unrestricted, Restricted, and Silent comments: Unrestricted There are two scenarios to consider: 1. You want to present the following box to a user, allowing them to choose a default comment or enter their own comment. The Toolkit programmer should not use the Project object s DefaultAuditTrailComment property. In this scenario, if the Confirm Identity column is selected for that object, the user must also enter their password. 2. You want this to be seamless to a user by entering the default comment programmatically. The Toolkit programmer uses the Project object s DefaultAuditTrailComment property to programmatically enter a default comment. No dialog box is presented to the user. In this scenario, if the Confirm Identity column is selected for that object, the box shown below is presented to the user. The user must enter their password, but the default comments section has been automatically filled. Waters Corporation 8 of 97

9 Restricted There are two scenarios to consider: 1. You want to present the dialog box shown above to a user, allowing them to choose a default comment. The user may not alter the selected comment and the Comments text box is disabled. The Toolkit programmer should not use the Project object s DefaultAuditTrailComment property. In this scenario, if the Confirm Identity column is selected for that object, the user must also enter in their password. 2. You want this to be seamless to a user by entering the default comment programmatically. The Toolkit programmer uses the Project object s DefaultAuditTrailComment property to programmatically enter a default comment. No dialog box is presented to the user. In this scenario, if the Confirm Identity column is selected for that object, the box shown above is presented to the user. The user must enter in their password, but the default comments section has been automatically filled; the user may not alter the selected comment and the Comments text box is disabled. When using the DefaultAuditTrailComment property, Toolkit programmers should be sure to use the exact default audit trail comment stored within Empower 2. A check is performed and an error returned if the comment does not match. Toolkit programmers can use the DefaultStrings object to retrieve the exact default comment for a particular category. Silent Performs the Empower 1154 style audit trail, where system objects are always audit trailed, but no comments are solicited from the user. If the Confirm Identity column is selected, the box shown above is presented to the user. The user must enter their password but may not alter any comments, as the Default Comments drop down list box and Comments text box are disabled. Waters Corporation 9 of 97

10 Project Audit Trail Policy Changes Empower 2 now allows system administrators the ability to provide more granularity in the way that project audit trails are performed. System administrators can now define how changes to a project will be audit trailed. New Project Audit Trail Options were added to the Empower System Policies New Project Policies tab, which now allows individual settings against projects. The following list details the system objects tracked per project: System Object Method Result Sample Deletion The new tab contains a comment type column combo box with three comment types. These comment types modify the system behavior when a user modifies a system object within the project, logging the change to the project, the name of the user who made the change, the date/time the change occurred, and the user s comment. The comment types are as follows: Unrestricted The comment entry dialog allows the user to select from a list of default strings or to enter free-form comments within the Comments text box. Restricted The comment entry dialog allows the user to select one of the predefined comments in the comment combo box only. The user may not alter the selected comment and the Comments text box is disabled. Silent Performs the Empower 1154 style audit trail where system objects are always audit trailed, but no comments are solicited from the user. The new tab also contains a Signoff Required column, which, when selected, requires the user to re-authenticate himself before the project object is created or altered. Note: This change affects the following objects: Result (Update), Instrument (Run, Rerun, Inject, ReadyInject, Replace, StopInjecting) and ProcessingRequest (Run). Certain Toolkit objects allow revision comments to be set as a property (Comments) of the specific object. This applies to the following objects: Method (Copy, Copy to project, Remove), AlterSample (Update), ExportMethod (Store), InstrumentMethod (Store), LCProcMethod (Store), MethodSet (Store), and SampleSetMethod (Store). Waters Corporation 10 of 97

11 From a Toolkit perspective, the following scenarios exist for Unrestricted, Restricted, and Silent comments: Unrestricted There are two scenarios to consider: 1. You want to present the following box (which differs depending on the action) to a user, allowing them to choose a default comment or enter their own comment. The Toolkit programmer should not use the Project object s DefaultAuditTrailComment property or the Comments property from any of the objects listed above. In this scenario, if the Signoff Required column is selected for that object, the user must also enter their password. 2. You want this to be seamless to a user by entering the default comment or comment programmatically. The Toolkit programmer uses the Project object s DefaultAuditTrailComment property to programmatically enter a default comment. No dialog box is presented to the user. In this scenario, if the Signoff Required column is selected for that object, the box shown below is presented to the user. The user must enter their password, but the default comments section has been automatically filled. If this is a Method system object change, the Toolkit programmer may also use the Comment property (In lieu of DefaultAuditTrailComment) for the objects mentioned in the above note. Waters Corporation 11 of 97

12 Restricted There are two scenarios to consider: 1. You want to present the dialog box shown above to a user, allowing them to choose a default comment. The user may not alter the selected comment and the Comments text box is disabled. The Toolkit programmer should not use the Project object s DefaultAuditTrailComment property. In this scenario, if the Signoff Required column is selected for that object, the user must also enter their password. 2. You want this to be seamless to a user by entering the default comment programmatically. The Toolkit programmer uses the Project object s DefaultAuditTrailComment property to programmatically enter a default comment. No dialog box is presented to the user. In this scenario, if the Signoff Required column is selected for that object, the box shown above is presented to the user. The user must enter their password but the default comments section has been automatically filled. When using the DefaultAuditTrailComment property, Toolkit programmers should be sure to use the exact default audit trail comment stored within Empower 2. A check is performed and an error returned if the comment does not match. Toolkit programmers can use the DefaultStrings object to retrieve the exact default comment for a particular category. If this is a Method system object change, the Toolkit programmer should not use the Comment property for any of the objects mentioned in the above note, as the comments text area is disabled. Ensure the Comment property string is empty/clear of contents. Silent Performs the Empower 1154 style audit trail, where system objects are always audit trailed, but no comments are solicited from the user. If the Signoff Required column is selected, the box shown above is presented to the user. The user must enter their password but may not alter any comments, as the Default Comments drop down list box and Comments text box are disabled. Instrument Object If Full Audit Trail Support was enabled within New Project Policies, specific Result and Sample object settings check for appropriate comments when a run is started via the Instrument object. See this section for details regarding Restricted, Unrestricted, and Silent settings. Waters Corporation 12 of 97

13 Project Hierarchies Project hierarchies allow customers to better manage project naming and access, particularly in large enterprise environments. In such environments, the current requirement to have unique names for every project makes the naming of projects difficult when multiple departments, across multiple facilities are involved. Conceptually, project hierarchies will function similarly to the directory structure and user access implementation employed by Microsoft Windows. This requires ToolKit to handle full path names anywhere a project name is specified. For the DBProject object, changes to the Name or Names property must be parsed and handled so the proper information is stored in the database. For the new DBProject Backup and Restore functions, a new Children parameter has been added. This parameter is a boolean flag that is tested to determine whether the corresponding children of the named project should be backed up/restored. An example of project hierarchies naming is as follows: \Parent\Child1\Child1a The following define the behavior and appearance within Empower 2. Projects can have sub-projects, just as Windows folders can have subfolders. A subproject is simply a project that has another project as a parent. The Projects view in Configuration Manager depicts the project hierarchy in a logical manner. Multiple projects may have the same project name as long as they are not at the same level in the project hierarchy. Each project will, however, be uniquely identifiable within a database. Access to a project or sub-project may be assigned to the project owner, a series of groups, or to all users exactly as it is in Empower Project hierarchy can be defined during project creation. Project access and user privilege settings shall apply, i.e. a user creating a new project cannot define a parent project unless the user has access to the parent project, etc. Project hierarchies can be modified after project creation abiding by the user access and privilege settings. All changes to the project hierarchy are audit trailed. All references to projects in the audit trail are unique. The project hierarchy can be viewed and changed within Project Properties. Sub-projects can be (optionally) backed up and restored together with the parent. User permissions apply. When backing up a project, all hierarchy information is included with the backup. This ensures that the project can be restored to its original hierarchical location. During a project restore, project(s) can be restored to their original hierarchal location or to another unrelated hierarchal location. When creating a sub-project, the user access settings shall default to those of the parent project. These settings, however, can be changed. When locking/unlocking projects, users can also lock/unlock sub-projects. Waters Corporation 13 of 97

14 DBProject Changes There are several changes to the DBProject object: 1. The changes described within the System/Project Audit Trail and Project Hierarchies section affect how Empower 2 projects are created or modified via the DBProject object. In certain cases, the Toolkit user must utilize the following properties and handle audit trail entries as described above. Property Additions: Descendents() as Variant Returns the list of child projects for this parent project (if any). Action: The list of projects descending from this parent are returned in a variant array of strings, each string specifying a particular sub project. The hierarchy tree information uses the backslash to denote children of children, etc. (i.e. child1, child1\childschild1, child1\childschild2, child2, etc.). If the logged in user has Administrator privileges, all children are returned, otherwise only children the user has access to are returned. DeletionSignoff() as Boolean Yes or No. Returns the current state of this property. Action: Determines whether or not the user is prompted for their password against the Deletion object if the New Project Policies Full Audit Trail Support has been enabled. MethodSignoff() as Boolean Yes or No. Returns the current state of this property. Action: Determines whether or not the user is prompted for their password against the Method object if the New Project Policies Full Audit Trail Support has been enabled. ResultsSignoff() as Boolean Yes or No. Returns the current state of this property. Action: Determines whether or not the user is prompted for their password against the Result object if the New Project Policies Full Audit Trail Support has been enabled. SampleSignoff() as Boolean Yes or No. Returns the current state of this property. Action: Determines whether or not the user is prompted for their password against the Sample object if the New Project Policies Full Audit Trail Support has been enabled. Waters Corporation 14 of 97

15 DeletionChanges() as mtkaudittrailcommenttype (mtksilent, mtkunrestricted, mtkrestricted) Specifies Silent, Unrestricted, or Restricted. Returns the current Comment setting for this property. Action: Determines how the user is prompted (or not) for their comments against Sample object changes if the New Project Policies Full Audit Trail Support has been enabled. MethodChanges() as mtkaudittrailcommenttype (mtksilent, mtkunrestricted, mtkrestricted) Specifies Silent, Unrestricted, or Restricted. Returns the current Comment setting for this property. Action: Determines how the user is prompted (or not) for their comments against Method object changes if the New Project Policies Full Audit Trail Support has been enabled. ResultChanges() as mtkaudittrailcommenttype (mtksilent, mtkunrestricted, mtkrestricted) Specifies Silent, Unrestricted, or Restricted. Returns the current Comment setting for this property. Action: Determines how the user is prompted (or not) for their comments against Result object changes if the New Project Policies Full Audit Trail Support has been enabled. SampleChanges() as mtkaudittrailcommenttype (mtksilent, mtkunrestricted, mtkrestricted) Specifies Silent, Unrestricted, or Restricted. Returns the current Comment setting for this property. Action: Determines how the user is prompted (or not) for their comments against Sample object changes if the New Project Policies Full Audit Trail Support has been enabled. 2. Empower 2 separates the Lock privilege into two distinct privileges, one to Lock and the other to Unlock projects. Property Additions: LockStatus() as mtkprojectlocktype Returns the project lock type. Method Additions: LockProject(Service, Project, locktype, Children) Service as string The database name for the project of interest. Project as string The name of the project to be Locked (a fully expanded hierarchy path name is allowable). locktype as mtkprojectlocktype Specifies the type of lock. Children as boolean Lock this project s children. Action: Calling this function locks a project, and its children (if the flag is set), to the lock type specified. An error is returned if the user does not have access to the project or a Waters Corporation 15 of 97

16 child project (if the child flag is set). You can use this function to unlock a project by setting the locktype to MtkNoLock. 3. A new feature allows the DBProject object to fetch the list of options installed on the system. The Toolkit user can set particular installed options for a given Project and can enable an option that is not installed in the system. Property Additions: Options() as Variant Sets the enabled options for the DBProject object. Returns the current enabled options for the DBProject object. Action: The options are returned in a variant array of strings, each string specifying an option. AvailableOptions() as Variant N/A Returns the current set of installed Empower options available for setting using the Options property above. Action: The options are returned in a variant array of strings, each string specifying an option. 4. Allow Toolkit users to fetch the list of options installed on the system. The Toolkit user can set particular installed options for a given Project, but cannot enable an option that is not installed in the system. Property Additions: Options() as Variant Sets the enabled options for the DBProject object. Returns the current enabled options for the DBProject object. Action: The options are returned in a variant array of strings, each string specifying an option. AvailableOptions() as Variant N/A Returns the current set of installed Empower options available for setting using the Options property above. Action: The options are returned in a variant array of strings, each string specifying an option. 5. The Project object includes three new methods; BackupProject, RestoreProject and DeleteProject. These methods perform all necessary setup and error checking within the system. They are checked against the logged in user account to ensure the account has the appropriate User Type privilege to perform these actions. If not, an error message is returned to the Toolkit programmer. The Toolkit user can also specify the path to backup to and restore from when using these methods. These new methods replace the functionality previously found in the cmgrlib.dll which has been removed from Empower 2. Waters Corporation 16 of 97

17 Method Additions: BackupProject(Service, Project, Path, Children) Service as string The database name for the project of interest. Project as string The name of the project to be backed up (a fully expanded hierarchy path name is allowable). Path as string The path where the backup information/files will be stored. Children as boolean Back up this project s children. Action: Performs a project backup. Produces the following files: path\project.inf Backup info file path\project.exp Database export file path\backup.log Text journal of the database export file path\*.dat All datafiles associated with the project Calling this function invokes all setup and error checking necessary to start the backup process. A ToolKit error is thrown during this check process if a current backup/restore is already in progress, or if the specified path does not exist, etc. The function then launches a worker thread to perform the actual backup duties. Periodic calls to DbProject.IsBusy() determine when the job is complete. A subsequent call to DbProject.GetLastError returns any errors the worker thread may have encountered during the backup process. Once IsBusy() returns FALSE and GetLastError returns an empty string, the backup is successfully complete and all files have been stored to the specified backup path. DeleteProject(Service, Project, Children) Service as string The database name for the project of interest. Project as string The name of the project to be deleted (a fully expanded hierarchy path name is allowable). Children as boolean Delete this project s children. Action: Calling this function deletes a project, and its children, if the flag is set. An error is returned if the user does not have access to the project itself or to a child project (if the child flag is set). It also returns an error if an attempt is made to delete a parent with children present and the flag is not set. Waters Corporation 17 of 97

18 RestoreProject(Service, Project, Path, Quota) Service as String The database name for the project of interest. Project as String The proposed name of the newly restored project (this can contain hierarchy tree information). Path as String The path where the project backup data files exist. Quota as Double The quota for the newly restored project. Action: Performs a standard Millennium project Restore. Expects the following files to be present in the supplied directory: path\project.inf Restore info file path\project.exp path\*.dat Database export file All datafiles accociated with the project Error checking is done during this process to make sure the project doesn t currently exist, any specified parent exists, user has privileges for the restore operation, etc. A successful call to RestoreProject launches a worker thread that actually restores the project. Thus, a call to RestoreProject() is asynchronous and does not block the calling program. Periodic calls to DbProject.IsBusy() determine whether the restore process is complete. Once it is done (returns FALSE) a call to DbProject.GetLastError() returns a string describing any errors the worker thread encountered during the restore process. If the call to GetLastError() returns an empty string, the restore process has been successfully completed. Note: Any necessary updates are automatically performed on the restored project. ReadInfFile(Path, Project, User, Quota) Path as String The full path name for the inf file of interest. Project as String Returns the name of the project referenced in the inf file. User as String Returns the user name of the project referenced in the inf file. Quota as Double Returns the quota for the project referenced in the inf file. Action: This method reads the information from an INF file and returns that information. It can be called prior to calling RestoreProject, as it contains pertinent information that can be supplied to that method. Waters Corporation 18 of 97

19 GetLastError() As String Returns details of any error encountered by the worker thread. IsBusy() as Bool Returns true if the worker thread is currently backing up or restoring a project. SampleSetLine Object Toolkit users can now pause a running sample set for a user definable period of time. This is useful for reviewing the system suitability injections for precision. Toolkit users can set a maximum duration for the pause. This is useful in cases, where the samples are considered unusable if they are not run within a certain time after their preparation. All actions when pausing and resuming a Sample Set are audit trailed in Full Audit Trail projects. No user comments are required. Dissolution The SampleSetMethod object has been extended so that dissolution parameters are available to Toolkit users. SampleSetMethod Property Additions: BathA() as DissolutionBath Returns the current DissolutionBath object corresponding to BathA. Returns NULL if this is not a dissolution enabled Sample Set Method. BathB() as DissolutionBath Returns the current DissolutionBath object corresponding to BathB. Returns NULL if this is not a dissolution enabled Sample Set Method. DissolutionBath Object This object wraps the Empower Dissolution Bath object. It contains information about the dissolution bath such as media volume, taken volume, temperatures, etc. Properties: DissolutionComponents() as DissolutionComponents Sets the DissolutionComponents collection for this DissolutionBath object. Returns the current DissolutionComponents collection object corresponding to this bath. Returns NULL if there are no components. Waters Corporation 19 of 97

20 Fields() as Fields Returns the current collection of Fields. Default: A static Fields collection containing all the possible Dissolution Bath fields. Field Type is mtkdissolutionbath. TransferTimes() as Variant Sets the transfer times. Returns the transfer times. Action: The transfer times are returned in a variant array of Singles (floats). XXX([FormatData as Variant]) as Variant Dynamic property where XXX stands for the name of the field whose value is to be returned. Only the names of the fields in the Fields property can be used. All DissolutionBath dynamic properties can Get() functions. If the optional FormatData parameter is set to non-zero, then the returned data is a formatted string using the Empower width and precision specifications. Methods: Get(FieldName, [FormatData]) as Variant FieldName as string Contains name of the dynamic field whose value is to be retrieved. FormatData as BOOLEAN Set True if data is to be returned as a Empower formatted string. Default: False. Value as variant Contains the data for which to set the passed FieldName. Action: Returns the value of the desired dynamic field name. This provides another way to retrieve a dynamic property. Using val = object.xxx in Visual Basic is equivalent to doing val = object.get( xxx ). The Get gives greater programmatic flexibility. Set(FieldName, Value) FieldName as string Contains name of the dynamic field whose value is to be assigned. Value as variant Contains the data for which to set the passed FieldName. Action: This provides another way to set a dynamic property. Using object.xxx = val in Visual Basic is equivalent to doing object.set( xxx, val). The Set gives greater programmatic flexibility. Waters Corporation 20 of 97

21 DissolutionComponents Object This is a Dynamic array (and as such, has all the properties of Toolkit defined dynamic arrays) of DissolutionComponent objects. It is returned by the DissolutionBath object and can be manipulated by the Toolkit user. DissolutionComponent Object This object wraps the DissolutionComponent object. It contains information about an individual dissolution component such as name, claimed amount, Q factor minutes, etc. Properties: Fields() as Fields Returns the current collection of Fields. Default: A static Fields collection containing all the possible Dissolution Component fields. Field Type is mtkdissolutioncomponent. XXX([FormatData as Variant]) as Variant Dynamic property where XXX stands for the name of the field whose value is to be returned. Only the names of the fields in the Fields property can be used. All DissolutionComponent dynamic properties can Get() functions. If the optional FormatData parameter is set to nonzero, then the returned data will be a formatted string using the Empower width and precision specifications. Methods: Get(FieldName, [FormatData]) as Variant FieldName as string Contains name of the dynamic field whose value is to be retrieved. FormatData as BOOLEAN Set True if data is to be returned as a Empower formatted string. Default: False. Value as variant Contains the data for which to set the passed FieldName. Action: Returns the value of the desired dynamic field name. This provides another way to retrieve a dynamic property. Using val = object.xxx in Visual Basic is equivalent to doing val = object.get( xxx ). The Get gives greater programmatic flexibility. Set(FieldName, Value) FieldName as string Contains name of the dynamic field whose value is to be assigned. Value as variant Contains the data for which to set the passed FieldName. Action: This provides another way to set a dynamic property. Using object.xxx = val in Visual Basic is equivalent to doing object.set( xxx, val). The Set gives greater programmatic flexibility. Waters Corporation 21 of 97

22 Empower 2 Feature Releases This section outlines changes and enhancements made to the Empower Toolkit in Empower 2 Feature Releases. Empower 2 Feature Release 3 Method Validation Manager Toolkit now includes functions that support the Method Validation option. This includes new types of results, studies, sign offs, methods and method changes, new fields for existing field types, new user privileges, and new project properties. Validation Application Launch A new enumeration, mtkvalidationreview, can be passed to the Project object s LaunchMillApp() method and the new Validation application can be launched via ToolKit. The optional arguments are validation result ids in an array, similar to the arguments used to launch Review via LaunchMillApp(). Validation Results Validation Results are fetchable via the ToolKit. A new ToolKit object in the Viewer family of objects is nearly identical in form and function to existing viewer objects, most notably the ResultViewer object. ValidationResultViewer This object is similar to the ResultViewer object. It provides the selected lines/by ids/search criteria methods of retrieving ValidationResult data (Results). Properties Fields() as Fields Assign a Fields collection for use by viewer. Get Returns the current Fields collection. Default: A Fields collection containing all the possible ValidationResult fields. Action: The viewer retrieves all the fields in the Fields collection. If the Fields Type is not mtkvalidationresult, an error is generated. Criteria() as mtkcriteria mtkcriteria: An enumeration of possible criteria for means by which to view the ValidationResults. Enumerations are: mtksearch: Use the SearchFields property to view the result sets. Ignores the Ids property. Value is 0. mtkselected: Use the Ids selected in the Project Window s Result Set view. An error is generated if Project is not running per the Toolkit Login parameters or if the Result Set view is not the current view,. The SearchFields and Ids properties are ignored. Value is 1. Waters Corporation 22 of 97

23 mtkids: Use the Ids property to view channels. The SearchFields property is ignored. Value is 2. Assigns the Criteria value. An error is generated if the value is out of range (0 to 2). Returns the current value. Default: mtksearch FormatData() as Boolean Assigns True if fetched data is to be returned as a formatted string. Returns the current state. Default: False Action: When set True, the Peak(s), Result(s), Result Set(s) values and dynamic properties are formatted strings. The data is formatted using the field width and precision specifications set by Empower. If the data is a null value, an empty string is returned. SearchFields() as SearchFields Assigns a new collection of SearchField objects. Returns the current SearchFields collection. Default: An empty collection. Fields are acquired in no specific order. Action: Used when Criteria is mtksearch. Ids() as Ids Default: Action: Assigns a new collection of Id objects. Returns the current collection of Ids. An empty Ids collection. Used when Criteria is mtkids. The ids must be Result Set ids. Methods Fetch() as ValidationResults Action: Per the Criteria property, fetch all the requested fields from the database. Returns the values in a ValidationResults collection. ValidationResults Static collection of ValidationResult objects. The collection is filled and returned by the ValidationResultViewer. Properties: Value() as Variant Returns a variant array of variants representing all the field name columns by the number of rows (ids) that were retrieved. The number of elements in the variant array is the same as the number of items in the ValidationResultViewer s Fields property. The data type of each variant in the array is the same as the Empower field that it represents. Each variant in the array is a variant array containing a data item for each row (id) retrieved from the database. Waters Corporation 23 of 97

24 ValidationResult The ValidationResult object is obtained from the ValidationResults collection that is returned from the ValidationResultViewer s Fetch() method. The validation result id can be obtained from the Id property. Using dynamic properties, each field requested by the ValidationResultViewer s Fields property can be retrieved. Properties: ID() as Long Returns the Validation Result ID for this Validation Result. Default: Action: After a Fetch() is performed in the ValidationResultViewer, this field shows the id for this validation result. Value() as Variant Default: Action: Returns a variant that contains all the fetched result set fields. Returns a variant array of variants. The number of elements in the array corresponds to the number of fields in ValidationResultViewer Fields. Each variant in the array contains the returned field value and the type of the data depends on the type of the Millennium 32 field. Value is the default property of the ValidationResult object. RelatedObjectIds() as Variant Returns the ids of related objects. Default: An empty variant. Action: Returns a variant array of arrays. Each array is a set of ids related to this validation result. The first value of each variant array indicates the type of ids that comprise the array (i.e. mtkresult, mtkpeak, etc.); the array is subsequently filled with the ids of that type that are related to the particular result. Only the related result ids are returned. Methods XXX() as Variant Dynamic property where XXX stands for the name of the field whose value is to be returned. Only the names of the fields in the ResultViewer Fields collection can be used. Get(FieldName) as Variant FieldName as string Contains name of the dynamic field whose value is to be retrieved. Value as variant Contains the data for which to set the passed FieldName. Action: Returns the value of the desired dynamic field name. The format of the returned data is based on the FormatData property s setting before the Fetch(). This provides another way to retrieve a Waters Corporation 24 of 97

25 Validation Protocol Method dynamic property. Using val = object.xxx in Visual Basic is equivalent to doing val = object.get( xxx ). The Get gives greater programmatic flexibility. Toolkit provides the ability to fetch and modify validation protocol methods. The ValidationProtocolMethod object allows creation and modification of Empower validation protocol methods. An existing validation protocol method may be retrieved by using the object s Fetch() method. The name property is used by the Fetch() method to retrieve a named method which can then be modified. After modifying and/or the properties of the method object or sub objects of the method object the Store() method updates the existing validation protocol method in the database. A new validation protocol method can be created by saving the ValidationProtocolMethod object with a new name. The Name property is used when Fetching and Storing the ValidationProtocolMethod. The ValidationProtocolMethod object is one of the more complex objects in Toolkit. It is recommended that the programmer be familiar with Empower s Method Validation Protocol editor. Properties: Name() as String Default: Action: Assigns a name to the protocol test line method object. Returns the name of the protocol test line method. Toolkit The Name is used by the Fetch() method to open the desired protocol test line method. If a new object is created, the Name property must be set before using the Store() method. If the Name is the same as an existing protocol test line method, the date and version of the method in the database will be updated at the Store(). ProtocolTestLines() as ProtocolTestLines Assigns a new collection of ProtocolTestLines to the ValidationProtocolMethod object. Returns the current collection of protocol test lines. Default: Empty collection. Action: The ProtocolTestLines collection is filled by using the Fetch() method. SystemPrecisionParameterSet() as AcquistionParameterSet Returns the current SystemPrecisionParameterSet object for this method. Default: An object containing the method s system precision acquisition parameters. ApprovalSet() as RequiredApprovalSet Returns the current RequiredApprovalSet object for this method. Default: An object containing the method s set of required approval criteria. Waters Corporation 25 of 97

26 Comments() as String Default: Action: Date() as date Default: Version() as long Default: Assign a comment to the protocol test line method. Returns the currently assigned comment. Empty string. Sets comments property for the method. Returns the date of the latest revision of the protocol test line method. Returns the version number of the protocol test line method. RevisionComment() as string Assigns a revision comment to the protocol test line method. Returns the currently assigned revision comment. Default: Empty string. Action: Each time a method is saved, a revision comment can be added. RevisionHistory() as variant Returns a variant array of strings containing the revision history of the method. Note: The number of strings in the history array is independent of the version number. Default: Methods: Fetch() Store() Action: Action: Opens the desired protocol test line method using the Name property. This resets the property values per the fetched method. If the method to be opened is locked or being edited, an error is generated. Saves the ValidationProtocolMethod object per the Name property. Only after the Store() are the properties of the Method and of each contained ProtocolTestLine object of the ProtocolTestLines collection stored in the database. If the Name is the same as an existing sample set method, the date and version of the method in the database are updated. If a new method is being created, the date and version are set appropriately. Waters Corporation 26 of 97

27 RequiredApprovalSet The RequiredApprovalSet object wraps the set of required approvals for a Validation Protocol Method. This object contains the fields associated with the Validation Protocol Method s Approvals/Sign Offs tab. Properties: Fields() as Fields Default: Returns the current Fields collection. A Fields collection containing all the possible approval set fields. Field Type is mtkrequiredapprovalset. XXX([FormatData as Variant]) as Variant Dynamic property where XXX stands for the name of the field whose value is to be returned. Only the names of the fields in the Fields property can be used. All RequiredApprovalSet dynamic properties can use both Set() and Get() functions. After a property is set, it s get reflects the current setting; yet, it is only officially stored in the database at the ValidationProtocolMethod Store(). If the optional FormatData parameter is set to non-zero, then the returned data will be a formatted string using the Empower width and precision specifications. Methods: Set(FieldName, Value) FieldName as string Contains name of the dynamic field whose value is to be assigned. Value as variant Contains the data for which to set the passed FieldName. Action: This provides another way to set a dynamic property. Using object.xxx = val in Visual Basic is equivalent to doing object.set( xxx, val). The Set gives greater programmatic flexibility. Get(FieldName, [FormatData]) as Variant FieldName as string Contains name of the dynamic field whose value is to be retrieved. FormatData as BOOLEAN Set True if data is to be returned as a Millennium formatted string. Default: False. Value as variant Contains the data for which to set the passed FieldName. Action: Returns the value of the desired dynamic field name. This provides another way to retrieve a dynamic property. Using val = object.xxx in Visual Basic is equivalent to doing val = object.get( xxx ). The Get gives greater programmatic flexibility. Waters Corporation 27 of 97

28 ProtocolTestLines The ProtocolTestLines collection object represents the array of rows in the Validation Protocol Method s Tests to Perform table. It is a dynamic array of ProtocolTestLine objects, and as such has all the properties of a Toolkit defined dynamic array. This collection is part of the ValidationProtocolMethod object and can be accessed there. ProtocolTestLine The ProtocolTestLine object is the base object for all the specific protocol test line objects. Each individual protocol test line object is derived from this base class. Its type property identifies the particular protocol test line type that it is. With that information it can be "cast" as the appropriate individual protocol test line object. The ProtocolTestLines collection contains a list of these objects. Once retrieved, each ProtocolTestLine object's type can be examined and then handled appropriately as a particular protocol test line object. The dynamic fields contained in the object also reflect the differences in the various types of protocol test lines. Properties: Name() as String Default: Returns the name of the protocol test line. Type() as mtkprotocoltestlinetype Returns the type of the protocol test line. Default: Related constants: Enumeration Identifier Value Used By mtkprotocoltestline Type mtkmvnone 0 mtkspecificity 1 mtklinearity 2 mtklinearitycomparison 3 mtkaccuracy 4 mtkrepeatability 5 mtkintermediateprecision 6 mtkintermediateprecisiondoe 7 mtkreproducibility 8 mtklodloqdetermination 9 mtkrobustness 10 mtksolstability 11 mtkfiltervalidation 12 mtksystemsuitability 13 ProtocolTestLineType property Waters Corporation 28 of 97