Getting Main Objects from the Database

To begin work with API objects, you have to retrieve them from the database. For this purpose designated ”get” methods are implemented in Application and other objects. The output can be a container, business object (Business object is an entity in an information system bearing some information. In Valuemation, all Valuemation objects are called "business objects") or a string. Methods implemented in Application allow you to get the main, “root” objects – these containers enable you to retrieve further objects in API through the relations they contain.

The following methods are used to retrieve containers from the database:

Application.getBOTypes()

Returns BOTYPES container with all business BOTypes defined in Valuemation.

Application.getTechnicalBOTypes()

Returns BOTYPES container with all technical BOTypes defined in Valuemation.

Application.getAllBOTypes()

Returns BOTYPES container with all BOTypes defined in Valuemation, both business and technical.

Application.getCatalogs()

Returns CATALOGS container with all default Catalogs in Valuemation.

Application.getMetaWorkflows()

Returns METAWORKFLOWS container with all MetaWorkflows defined in Valuemation. Since MetaWorkflow represents only a metadata, no transaction is needed.

The following methods are all related to user management. To access them, you have to be authorized to run the User Manager action , which normally opens User Manager in GUI.

Application.getUsers(ApiTransaction)

Returns USERS container with all users in Valuemation. The users are created in the transaction you pass as a parameter.

Application.getRoles(ApiTransaction)

Returns ROLES container containing all Roles in Valuemation. The Roles are created in the transaction you pass as a parameter.

Application.getGroups(ApiTransaction)

Returns GROUPS container with all Groups in Valuemation. The Groups are created in the transaction you pass as a parameter.

Application.getClients(ApiTransaction)

Returns CLIENTS container with all Clients in Valuemation. The Client (A region dividing objects in the databas. The ability to support Client allows a company to create several completely independent and separate regions within one Valuemation database. Each client then has its own data and configuration and can work independently of the other clients. Maintaining separate regions of data is an efficient and secure way of using one installation to provide services for different clients. Users can switch clients both on logon and in the runtime during their work. The process of assigning users to clients is client mapping.) objects are created in the transaction you pass as a parameter

Application.getModules()

Returns the MODULES container holding all Modules installed in Valuemation. The Module (In order to fit your specific requirements, Valuemation® is built from modular, freely adaptable components - modules, which provide enhanced functionality (such as Service/Change Management or Finance). They may or may not be installed according to the needs of a particular customer. Modules are displayed as icons in the My Valuemation bar in the left-hand side of the screen.) whose content is displayed first by default through GUI is the first one, with order number 0.

Application.getMainFolders()

Returns the MAINFOLDERS container holding all MainFolders in Valuemation. The MainFolder whose content is displayed first by default through GUI is the first one, with order number 0.

Application.getRootFolder()

Returns the first MainFolder (i.e. the MainFolder with order number 0). In GUI, it is the top item in the sidebar; under it you can see its contents: subfolders and catalogs it holds. For more information about Folder system see Organizing Data (Sidebar, Modules).

The code that follows is an example that can be easily applied to all of the previously mentioned methods:

Example - Getting objects from the database

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.

'gets BOTypes

Set oBOTypes =oVM.getBOTypes

strTmp=""

'lists all BOTypes

for i=0 to oBOTypes.length-1

'and adds their names to a string

strTmp=strTmp & " ;" & i & " " &oBOTypes.item(i).getName

'prints strTmp string on user’s screen

Wscript.echo strTmp

Comment: At the beginning, we get the Application object, where oVM stands for the name of the Valuemation application as set in J-Integra. Next, a new object called “oBOTypes” is created, holding the result of getBOTypes call - all BOTypes used in the system. This object – container is processed by a cycle that goes through the items and calls getName method that returns the name of each BOType. The result is added to the strTmp string variable. Finally, this string representing all BOTypes in the system is printed on user’s screen.

Example - Get objects from the database

‘creates the transaction

Set oTransaction = oVM.createTransaction

' Finds the catalog

set oCatalog =oVM.getCatalog.find(oTransaction, "Person")

' Goes through all catalogs and creates objects from the items of the catalog

for i=0 to oCatalogs.length-1

Set oBo = oCatalog.item (i)

'Clears the string

Email = “”

' Change email address-fills email string with data

Email = oBo.getBOFields.find("firstname").getValue & "." &

oBo.getBOFields.find("lastname").getValue & "@usu.de"

‘Sets the value of the “email” field to email string we created before

oBo.getBOFields.find("email").setValue = Email

' Save transaction

oTransaction.doCommit

Comment: The aim of this script is to create the e-mail addresses of the employees of a company in following format: firstname.lastname@usu.de. You can use this script, for example, to solve a real-world situation when the format of the company e-mail address changes, for example, if there is a new domain name following a merger with another company. It would be almost impossible to make all these changes manually.

In the first section, we logged in and got the Application object, “oVM”. The transaction "oTransaction” is created. Next, we want to find a catalog called “Person”. To enable search through catalogs, we must first get the container of all catalogs by calling Application.getCatalogs method. find method is used to search through this container, with the name of our transaction “oTransaction” and a search string “Person” as parameters. The result is the first oCatalog (“Person”) matching the search criteria, which is created in "oTransaction”. Then, we step by step go through the items from the catalog in a “for” cycle, from the first one with order number 0 to the last one. In each run, we create an object. This object "Bo” represents a person and contains various BOFields, including “firstname” and “lastname”. We create a string called “Email” from these fields. Then we list the firstname and the lastname fields of the person using getValue, according to the new company address format, into this string. These fields we have obtained by searching the container of BOFields held by the "oBo” object. Calling BOField.setValue sets the value of the “Email” field. Finally, the “"Transaction” is saved to the database by calling doCommit.