Time-related Feature

This chapter discusses the methods that are closely related to the Time Related Links feature of Valuemation. The following methods apply exclusively to BOCollections. For a comprehensive coverage of the TRL issue, see Time Related Links (TRLs).

To learn whether a collection is time-related (in other words, if the validity of the objects it holds is time-dependent):

ApiBOCollection.isTimeRelated()

Returns TRUE if the collection is time-related and therefore, you use time-related methods to read the data it holds. Otherwise returns FALSE.

Some time related collections simulate a “N to 1” relationship where only one of the objects can be valid at a time, the example might be the “System x location” relationship. Thanks to this feature, some of the methods that are normally used only with fields holding objects can also be applied to collections implementing a “N:1” relationship.

For example, you can use ApiBOField.getObject on a field holding a collection simulating a “To 1” relationship, which will return the currently valid object. Nevertheless, you can still call ApiBOField.getCollection to get a whole TRL collection, including the link objects.

Check whether a collection is a “TRL to 1” by calling:

ApiBOCollection.isTRLTo1()

Returns TRUE if the collection represents a “TRL to 1” relation. Such collection simulates a “N to 1” relationship where only one of the objects can be valid at a time, the example might be the "System x location” relationship – in other words, the system can be located at exactly one place at a time.

To switch a collection to display all objects regardless their time information:

ApiBOCollection.setReadAll()

Switches the collection to display all BOs it holds, including historic and pre-planned objects. To revert to the normal state that returns only the currently valid BO, simply re-get the collection from the BOField.

To switch a collection to display only objects valid in the past, future or a specific point in time, use one of the two following methods:

ApiBOCollection.setReadHistoric()

Switches the collection to display only the historic BOs, in other words, the BOs valid in the past. To revert to the normal state that returns only the currently valid BO, call setReadValid() or simply re-get the collection from the BOField.

ApiBOCollection.setReadFuture()

Switches the collection to display only the future (pre-planned) BOs. To revert to the normal state that returns only the currently valid BO, call setReadValid() or simply re-get the collection from the BOField.

ApiBOCollection.setReadValid()

Switches the collection to display only the currently valid objects.

ApiBOCollection.setReadToDate(Date)

Switches the collection to return objects valid on a specific date.

Note: Since Valuemation version 4.6, function 'ApiBoField.linkObject()' returns current Link Business Object for TRL relations. This means that it can be used in cases such as linking of Persons to Systems by the Compare process, where the TRL linking object contains additional 'Role' information which needs to be specified.

Example - Print cost centers related to a given System BO

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.

'Prints cost centers related to a given System BO now, in the past and in the future.

‘Creates a transaction in which all the objects will be created

Set oTrans = oVM.createTransaction

'Gets the "System" BOType and a collection of all systems

Set oBOT = oVM.getBOTypes.find("System")

Set oSysCol = oBOT.createFilter(oTrans,"")

'Takes the first item in the collection and retrieves the TRL- collection in its "syscostcenters" BOFields.

’In its default state, the collection returns the currently valid items.

Set oSys = oSysCol.item(0)

Set oBOF = oSys.getBOFields.find("syscostcenters")

Set oColl = oBOF.getCollection

'If the collection is empty, writes appropriate messages, otherwise, lists the currently valid costcenters

if oColl.isEmpty then

sTmp = "No costcenters are related to System " & oSys.getBODescription()

else

sTmp = "Costcenters which are related to System "_

& oSys.getBODescription() & ":" & vbNewLine & vbNewLine

for i=0 to oColl.length-1

sTmp = sTmp & oColl.item(i).getBODescription

end if

'Writes the list on the screen

msgBox sTmp 'Switches the collection to return only items valid in the past. If the collection is empty, writes ‘appropriate message, otherwise, lists the historic costcenters

oColl.setReadHistoric

if oColl.isEmpty then

sTmp = "No costcenters which are no longer valid were related to System " & oSys.getBODescription()

else

sTmp = "Costcenters which were related to System "_

& oSys.getBODescription() & "in the past:" & vbNewLine & vbNewLine

for i=0 to oColl.length-1

sTmp = sTmp & oColl.item(i).getBODescription

end if

'Writes the list on the screen

msgBox sTmp

'Switches the collection to return only items valid in the future. If the collection is empty, writes ‘appropriate messages, otherwise, lists the future cost centers

oColl.setReadFuture

if oColl.isEmpty then

sTmp = "No costcenters will be related to System " & oSys.getBODescription() & "in the future."

else

sTmp = "Costcenters which will be related to System "_

& oSys.getBODescription() & "in the future:" & vbNewLine & vbNewLine

for i=0 to oColl.length-1

sTmp = sTmp & oColl.item(i).getBODescription

end if

'Writes the list on the screen

msgBox sTmp