 |
HPE Content Manager SDK 9.1
|
|
HPE Content Manager SDK 9.1
|
The .NET SDK has a few of abstract classes from which the rest of its objects descend. They are:
Most objects in the .NET SDK have their own constructors and can be created directly. If while programming an API based application you are unsure about how to perform a specific HPE Content Manager function it is often helpful to see how the function is performed in the HPE Content Manager Client.
This object has methods and properties which describe and adjust the environment which your application is running in. Two important methods are:
The Database object is one of the main objects managing other HPE Content Manager API objects. The Database object is responsible for managing the session connection to a HPE Content Manager Workgroup Server.
The Database object is a Creatable object, meaning that you can use the ‘New’ keyword to construct a new instance of it. Before the actual connection is created you might specify the ID of the database to use and the location of the Workgroup Server’s name or URL address to use.
If the ID and WorkgroupServerName (or URL address) property of the Database are not specified a connection will be made to the users default database when required. If the user has not specified a default database in this situation an exception will be thrown.
Before creating a new Record you need to load a RecordType object which specifies the type of Record you are creating. After creating a record or changing an existing record you need to save it.
To read information stored on records in an HPE Content Manager database, the API programmer must first determine how to access the records required. If a particular record’s internal or external unique identifier is known, the associated record can be accessed directly and efficiently using the Record’s constructor. If neither of these unique identifiers is known, it will be necessary to construct a search.
Every Record in HPE Content Manager has a unique record number. This follows a pattern defined by the record type and can be manually entered by the user or set to be automatically generated by HPE Content Manager. Although the commonly used term is ‘number’, it is more correctly an identifier, as it is a string that may contain alphanumeric characters. This string is accessible through the Record object’s Number property.
The record number can be used as the argument to be passed to the Record object’s constructor, which takes the current database and a variant for the unique identifier and returns a pointer to the instantiated record.
Note: HPE Content Manager stores the record number in two formats, expanded (e.g. "2015/0059") and compressed (e.g. "15/59"). Either can be substituted above.
The Unique Row Identifier or URI of a record is an internal unique number that is transparent to the everyday user of HPE Content Manager. It is the primary key on the TSRECORD table in the database and provides an internal unique identifier for every record. The URI can be used as the argument to be passed to the Record object’s constructor, similarly to the previous example.
Once a record object has been created, the programmer can access properties and call methods on the object. These are discussed in the following subsections.
Most of the metadata directly associated with a record is exposed through properties on the Record object. Most properties return primitive data types (strings, numbers or dates) and can be interrogated directly. The meanings of these properties are generally self-evident from their names, but are also given in the object browser.
| Property | Example Value |
|---|---|
| Number | "G1997/0770" |
| Title | "Greenhouse Journal of Global Warming - Dugong Habitats" |
| DateCreated | 8/20/1997 |
| ExternalId | "GJGW 97PB" |
| AccessionNumber | 5617 |
Many attributes of a HPE Content Manager Record represent other objects, such as the RecordType, Classification and Container attributes. These are properties where the data type of the property is an object.
An HPE Content Manager record has various properties concerning related location information. These properties of a Record all return an instantiated Location object:
So far we have only considered the methods for reading information from records in HPE Content Manager. The API also allows you to update HPE Content Manager records, either by updating the values of properties on a given record object, or by calling methods on the record. Updating properties is the simplest way to modify the metadata of a record. You simply assign a new value of the correct data type to the named property of the object. Field-level verification is carried out, and an error will be raised if the property update is invalid (see also the section on ‘Verifying’ below). For more complicated types of update to a record, you must generally call methods that instruct HPE Content Manager to modify the record, based on arguments passed.
The simplest way to update data in a HPE Content Manager record is to modify the named properties on the Record object. This can only be done on properties that are not marked as read-only. This includes most of the Date properties, certain Location properties (Author, Addressee and OtherContact) and miscellaneous properties such as ExternalReference, Priority, AccessionNumber and ForeignBarcode.
To update other data on a record where read-write properties are not available, you must call a method instead. Update methods often begin with the prefix ‘Set…’ and they include a parameter for the new data value you wish to apply.
In many cases other parameters can be specified that control the behavior of the update:
To update a record’s properties where the internal identifier of the property is known, you can use the SetProperty method. This requires passing the property identifier and a variant containing the data value.
HPE Content Manager allows user-defined fields to be assigned to records. These user-defined fields cannot be interrogated using normal named properties of the record object. Instead, accessing userdefined fields is carried out using a dedicated object for managing these fields - the FieldDefinition object. Each base object has a pair of methods for manipulating user-defined fields, GetFieldValue and SetFieldValue. Each method takes a populated FieldDefinition object as a parameter.
When a record object is modified via the API, there are two levels of verification that must be carried out before the changes can be committed to the database. The first is field-level verification, which checks that the change to an individual property is legal. An example would be that the Date Registered is not in the future. If a property update cannot be carried out because of field-level verification, the method call or property assignment will cause a run-time error to be raised and the update will not be carried out. The second level of validation is object-level verification (sometimes called cross-field verification). This checks that the values of all fields on the object are consistent with each other. An example of object-level verification would be that the Date Registered is not earlier than the Date Created. Objectlevel verification is performed when the object’s Verify or Save methods are called.
Every base object has a ‘Verify’ method. This can be called to perform object-level verification prior to saving the object. The method returns false if there are any errors in the state of the object, and the error description will be stored in the object’s ErrorMessage property. If there are no errors, the method returns true and the Verify property (see below) is set to true. The method contains an optional parameter "failOnWarning" which, if set to true, will cause the Verify method to check for warning conditions as well as error conditions, and to fail if a warning is encountered.
If it is not called explicitly in code, the Verify method will be automatically called before an object is saved (see below) and if verification fails it will not be saved. This ensures that data cannot become corrupted and that business rules are observed when using the API, just as they are for users of the HPE Content Manager Client interface.
Every base object also has a ‘Verified’ Boolean read-only property, which is false whenever the object is instantiated. It is set to true when the Verify method confirms that it is in a legal state to be saved to the database (regardless of warning conditions).
It is up to the programmer to determine how they wish to deal with possible errors when updating an object. However, they must be aware that error checking takes place even when directly updating properties, so it will be necessary to provide some error-trapping code to prevent run-time errors being displayed to the user if there is a possibility of errors being raised.
All of the update methods and property changes made through the Record interface are only applied to the object in memory. The changes are not committed on the HPE Content Manager database until the object is saved. Calling the Save method on the record object will commit the changes to the database, applying all updates since the object was instantiated (or since it was last saved). Note that if the record has not been verified, Save will automatically call the Verify method and will only commit the changes if the verification succeeds. Various code examples using this method can be found throughout this document.
This scenario describes the general processes for using the SDK to create a record of a generic record type we are calling a ‘Container File’. In this and the next scenario (Creating a Document) we are assuming that the reader is familiar with the concept of record types. While it is up to the administrator of each HPE Content Manager implementation to determine the record types to be used, it is typical to follow a standard records management practice of having at least two record types, one representing container files (or folders) and one representing documents (the actual names used for the record types may of course vary). Container files are usually created and maintained by specialist records managers, as it is generally at this level that classification systems, retention schedules, security, keywords, controlled titling and other records management metadata are applied. Documents, on the other hand, are usually created by end-users, and require little specific metadata other than the identification of the appropriate container file to which the document belongs, as all other metadata and context is inherited from the Container. The general steps for creating a new container file record are as follows:
When creating any record, the Record Type for the new record must be identified. This is passed to the record object’s constructor along with the database which the new record is to belong to. See the Creating new records example.
Note: It is possible to create new Record Types using the SDK; however, this is not recommended as this is generally an administrator’s function only.
Titles for container files are often subject to controlled vocabulary or classification structures such as a thesaurus or file plan, which give records managers’ greater control over file creation, retrieval and retention. Even when such controlled titling is used, each file will typically also have a ‘free text’ title part. The titling method used is determined by the record type, and is usually set by the HPE Records Manager administrator. Thus a record with Classification titling may have a title such as: "Insurance – Property – Storm damage to Mackay information center", where the first two terms are generated from a predefined hierarchical classification structure and the remaining part of the title is ‘free text’ describing the specifics of the file. The generated title terms are determined by the classification codes, usually defined as a numerical sequence such as "610/600/". The free text title is set via the TypedTitle property.
Similarly, Thesaurus or Keyword titling allows a file to be titled using either a choice of individual keywords from a controlled list or a specific ‘branch’ of related terms according to a hierarchical structure (similar to a record plan or classification).
The security profile of an individual HPE Content Manager record is governed by three security controls: a Security Level, a set of zero or more Caveats, and Access Control. Security Levels and Caveats determine the access that a HPE Content Manager user has to the metadata of a record. These security specifications are usually applied to Record Types (and inherited by records of each type when they are created) but can be set explicitly on individual records. Every user has a maximum security level and zero or more caveats – in order to access a particular record, the user must have the same or a higher security level and must have all the caveats associated with the record.
There are two ways to assign Security Levels and Caveats to a record via the SDK. If the value and number of Levels and Caveats are fixed then this method can be used.
The more preferred way (although more verbose) is to retrieve the level and caveats, add them to a security profile and assigning the profile to the record. Both the SecurityLevel object and the SecurityCaveat objects can be instantiated by full name or by abbreviation. The instantiated SecurityLevel object can then be assigned to a TrimSecurityProfile’s SecurityLevel property. Each instantiated SecurityCaveat object can be added via the SecurityProfile’s AddCaveat method. The SecurityProfile can then be assigned to a record’s SecurityProfile property.
Defining relationships between a container file and location objects (people and places) provides additional and useful context for the record. Unlike record relationships, which can be user-defined, you can only use HPE Content Manager’s predefined standard relationship types for record locations. Record Locations represent actual (in the case of paper and other physical records) or logical (in the case of electronic records) places where a record resides. Every record in HPE Content Manager has a property representing its Home Location (where the record should normally be). There is also a property for Owner Location – the exact meaning of this can vary according to the practices of each HPE Content Manager implementation, but normally represents the person or body that is responsible for the record. The Home and Owner location of a record are typically derived from the default values for each Record Type, but all record location properties can be set on creation of a new record or modified later. The record object has methods for setting or changing the value of these location properties, which allow the option of specifying the date & time of the change of location (the default is the current time).
Unlike record Locations which tend to be internal units, Record Contacts are more commonly people or organizations that have a direct association with the record, and may be internal or external to the organization. Using the AttachContact method, HPE Content Manager allows each contact to be specifically identified as an Author, Addressee, Representative or Client. Other contact relationship types must use the generic type of ‘Other’.
### Code Example ###
This scenario describes the general processes for using the SDK to create a record of a generic Record Type we are calling a ‘Document’.
While container files are usually created and maintained by specialist records managers, documents, on the other hand, are usually created by end-users, and require little specific metadata other than the identification of the appropriate container file to which the document belongs, as most other metadata and context is inherited from the container. A document record usually consists of an electronic object (the source document, image or other file), a unique identifier (which may be automatically generated by HPE Content Manager), a record title and any other metadata required to profile and index the record, and a pointer to the container file from which the document derives its context.
The general steps for creating a new document record are as follows:
Titling for documents is generally straightforward – free text titling is the norm, and the title simply needs to succinctly describe the document or record. Record numbers may be assigned explicitly or they may be automatically generated – this is configured on the Record Type properties. If the number is explicitly assigned, the number (in expanded format) must be assigned to the LongNumber property (it must be unique or the record will not be saved).
Although it is not compulsory, it is most common that an electronic record is logically assigned to a container file that represents the subject matter, case, client file or other contextual grouping relevant to the document.
To assign a record to a container, the existing container record must be instantiated (by Id or URI) and then passed as an argument to the (contained) record object’s SetContainer method. The method includes a parameter for specifying whether the record is also ‘enclosed in’ the container, i.e. that the current location should reflect that it is with the container.
Document records can represent physical paper documents, but mostly they will include an electronic attachment, whether this is a word-processing document, scanned image or other type of file. To attach an electronic document to a record, the file name and path must be used to instantiate an InputDocument object. This object is then passed as an argument to the record object’s SetDocument method. The method includes parameters for specifying whether this should replace any existing document (or be added as a new revision), whether it should be marked as checked out to the current user, and any comments to be added to the record’s Notes field. The title of the document (minuse the extension) becomes the title of the record by default.
Record Contacts are HPE Content Manager location objects commonly representing people or organizations that have a direct association with the record. The most common type of Contact to be specified for an electronic document is the Author. Although the AttachContact method can be used for this and other contact types, a shortcut is provided through the Author property. For examples how to do this, see the code examples for:
The Location object is an encapsulation of all properties and methods associated with Persons, Organizations, Positions and Groups. Locations can be identified by name or by URI, and can be selected on other criteria, such as date of birth, nicknames, or membership of a particular organization, role or group.
Although the names of non-persons (Units, Positions and Organizations) must be unique, this is not the case for persons (Staff Names & Contacts). However, HPE Content Manager allows you to store a ‘nickname’ for any person, and this can be used as a substitute for a person’s name when searching. To find a particular person by name, you must pass the person’s combined name and title to the Location object’s constructor.
If the sub-string does not uniquely identify a location (i.e. there are no matches, or there is more than one match) then a null object will be returned.
To create a new staff member, you must instantiate a new location by calling the Location’s constructor. You then define the type of the location by assigning a value (in this case Person) to the TypeOfLocation property. You can then set various properties representing the person’s name, contact details such as telephone numbers and addresses, administrative details such as employee id numbers and so on.
If the new person is to be a HPE Content Manager user, then there are login and security details to be provided. You will need to specify the user’s network login id and optionally an expiry date. For the security profile, you are required to either explicitly state the user’s security level (and optionally any Caveats) and a user category, or if role-based security is used you can specify that the user takes the profile of a predefined group or user.
Relationships such as membership of units or reporting lines are created using the AddRelationship method and passing parameters for the related location and the relationship type.
Addresses (including electronic addresses such as email or URL) are added by calling the New method on the location’s ChildAddresses or ChildEAddresses collection properties.
One of the most powerful features of HPE Content Manager is the wide range of search criteria that can be applied to select obects from the database. .NET SDK provides the TrimMainObjectSearch class to provide this functionality. This class allows you to combine a number of search criteria together using boolean logic and then iterate through a resulting set of objects. Note that the TrimMainObjectSearch class can only be used to search for objects of a specified type, for instance, you can create a TrimMainObjectSearch to retrieve records. As its name implies, this class can be used to search for any SDK object that inherits from TrimMainObject.
The TrimMainObjectSearch class provides a number of simple "canned" methods for searching that do not involve any boolean logic. These are simple to use if you have a straightforward query, they include:
To use the string search syntax available in HPE Content Manager (refer to the HPE Content Manager’s Help file for examples). There are three main components to a string search – the primary search string, a set of filters (these work as if they were combined with the primary search string using a boolean ‘and’) and the sort specification. To create a query in this way, you use the SetSearchString method to specify the primary search string, and then you can optionally specify any filters using SetFilterString and specify a sort using AddSortItemAscending/AddSortItemDescending. This approach is useful if you want to provide the user with a simple edit control for specifying a search, and is also very useful for web-based applications.
Another option is to work with TrimSearchStackItem objects. The primary search criteria is represented internally as an array of TrimSearchStackItem objects, arranged as a reverse-polish stack to indicate operator precedence. A TrimSearchStackItem can be an operator (TrimSearchOperator) or a search clause (TrimSearchClause). You can build up a query using the internal search stack of the TrimMainObjectSearch, by using such methods as AddSearchClause, And, Or and Not. A read of the Wikipedia article on Reverse Polish notation would be most beneficial for developers unfamiliar with this style of expression. Because filters are all automatically "and-ed" together, they are simply represented as an array of TrimSearchClause items. For sorting, there is a TrimSearchSortItem class and a corresponding array.
These individual classes provide extra features that allow even more elaborate queries to be built.
The TrimMainObjectSearch derives from IEnumerable and so you can use a standard "foreach" loop to retrieve items that match the selection. In addition, there are two methods that will return the search result as an array of unique object identifiers (corresponds to the Uri property of a TrimMainObject).
You can specify that the items in the selection are eventually intended for a specific pupose. This may apply additional hidden filtering to the selection, although not always. As you are iterating through the results, you can use the IsValidForPurpose method to test if the item is suitable for the purpose specified. Each TrimMainObject has a purpose enumeration associated with it – use this enumeration to specify suitable purpose values for the object you are selecting.
The TrimMainObjectSearch has a SearchAsXML property which will convert the search, filter and sort criteria to an XML string. This string is language-independent and is therefore useful if you wish to reuse the same search at some later stage, perhaps in a different locale. Item matching The TrimMainObjectSearch provides an ItemMatches method, which allows you to test whether an existing TrimMainObject matches the search criteria contained within the search.
There are two counts FastCount and Count. FastCount may, in the case of the use of multiple levels of inherited ACLs, return -1 rather than an actual count. Count should always return a result accurate at the time it was called. Count will first try to use FastCount, if that fails it will fetch all the Records and then loop through them to count them. So it will often be as fast as FastCount but may be a lot slower (especially for large result sets). So, use FastCount only when you need to avoid a slow response and can accept an invalid response.
User Defined Fields are not indexed in the database and are this not a part of the core sorting however it is possible to sort using them. Always take care when doing this as the lack of an index requires a the entire result set to be fetched and sorted in memory. On large result sets this can be very slow. To sort using a User Defined field use either GetEnumeratorSorted or GetResultAsUriArraySorted, as seen in this example:
1.8.11 
