Reading BOs Through Catalogs

There are three standard descriptors of business objects – its order number, moniker and the BODescription. The meaning of the first should be clear (the objects are read as they are saved in the database), while the moniker represents a unique string identifier of the object and finally, BODescription represents a field that always provides the key, explicit and preferably easily comprehensible information about the BO.

Accordingly, if you want to read business objects from the database, you have three possible solutions: read the object by its order number or, search for an object by its BODescription. These are described below. For information about reading objects by monikers, see Monikers.

Counting objects

To determine the total number of objects held by the catalog:

ApiCatalog.length()

Returns the number of business objects in the catalog.

Note: only the BOs the current user is allowed to read are included in the total.

Reading Objects by Order Number

Each business object (Business object is an entity in an information system bearing some information. In Valuemation, all Valuemation objects are called "business objects") contained in a catalog has its unique order number according to which you can read certain BO(s). When you know the order number, you call:

ApiCatalog.item(int)

The method returns business object by the specified order number. When you finally get an object from the database, you can go on listing and working with its attributes (BOFields). If you want to list all BOs contained in the catalog, simply put this method in a “for” cycle where the “int” parameter is a variable.

Example - Listing catalogs

We assume that you have run Valuemation and logged in correctly before starting this code. oVM variable now holds Application object. See Login Syntax for the section of the opening code.

Set oVM=getObject("S3:de.usu.s3.api.Application")

'creates transaction

Set oTransaction = oVM.createTransaction

'get Catalog

Set oCatalog = oVM.getCatalogs.find(otransaction,"Department")

strTmp=""

'lists all Bos in Catalog and adds information to a string

for i=0 to oCatalog.length-1

strTmp=strTmp & " " & i & " " & oCatalog.item(i).getBOFields.find("description").getValue & ";"

Wscript.echo strTmp

Comment: The scripts goes through the catalog “Department” from item 1 to the last item and in each run of the “for” cycle, script adds the value that the object has in its “description” field to the strTmp string. Finally, this string containing description of all departments is printed on the user’s screen.

Reading Objects by Name

Catalog provides a method allowing you to read objects by their name, i.e. to find an object by its BODescription field:

ApiCatalog.find(String)

The method returns the first instance of BObject with BODescription field matching the string you pass as a parameter. The main purpose of this method is to make things easier and to help you find a BObject by the specified name quickly. To solve the obvious limitation of only one BObject it returns at a time and to get all other BObjects matching the search string (if exist – i.e. the BODescription is not unique), you have to browse through all objects in a cycle.

Example - Finding BOs by specified name

We assume that you have run Valuemation and logged in correctly before starting this code. oVM variable now holds Application object. See Login Syntax for the section of the opening code.

‘creates transaction

Set oTransaction = oVM.createTransaction

'get Person catalog

Set oCatalog = oVM.getCatalogs.find(oTransaction,"Person")

strTmp="Zimmerman"

‘returns a BO with BODescription field “Zimmerman” that is, person with this name

‘oBO variable will hold the person object

oBO=oCatalog.find(strTmp)

Comment: First, a transaction and the “Person” catalog are created. The scripts fills the search string with desired text. Next, the BOs matching the criteria are found using the “find” method.

Note: only the first match is returned.