Retrieving and setting properties of a business object

After you initialized a business object, you can access its properties by using various functions.

For example, if your Requisition type has an amount property, you can access its property using the following statements:

var amount = tw.local.myVariable.amount;
tw.local.myVariable.amount = 123;

If you are using a property name in a business object type that is reserved by IBM® BPM, for example metadata, then you must use the getPropertyValue function to get the current value of the property.

To set the value of the property, you must use the setPropertyValue function.

var metadata = tw.local.myVariable.getPropertyValue("metadata");
tw.local.myVariable.setPropertyValue("metadata", "The new metadata");

Using predefined functions and properties

IBM BPM defines several functions and properties that you can use for your variables. Some of them are only applicable for objects, some are only applicable for lists, other are applicable to both.

Tip: If you try to set a predefined property or function, you see an exception that is similar to the exception you see when you try to access a non-existent property.

The following table describes the common functions and properties:

Table 1. Functions and properties
Function or property name	Scope	Description
getPropertyValue(propertyName)	Objects	Returns the value of a property
insertIntoList(index, value)	Lists	Inserts an item into a list.
isDirty()	Both	Checks if a shared business object has changes.
listAddSelected(index)	Lists	Marks an item in a list as selected.
listAllSelected	Lists	Returns a list of all selected items of the list.
listAllSelectedIndices	Lists	Returns a list of the indices of all selected items of the list.
listClearAllSelected()	Lists	Marks all items in a list as not selected.
listIsSelected(index)	Lists	Checks if an item in a list is selected.
listLength	Lists	Returns the number of items in the list.
listRemoveSelected(index)	Lists	Marks an item in a list as not selected.
listSelected	Lists	Returns the first selected item of the list.
listSelectedIndices	Lists	Returns the index of the first selected item of the list.
listToNativeArray()	Lists	Returns a JavaScript array with the items of the list.
load(key)	Objects	Loads the latest version of a shared business object or, if a key is provided, loads the latest version of specific shared business object.
metadata(key)	Both	Returns a metadata value of the object.
propertyNames	Objects	Returns an array of the properties of the object.
propertyValues	Objects	Returns an array of the property values of the object.
removeIndex(index)	Lists	Removes an item from a list.
removeProperty(propertyName)	Objects	Removes a property from an object.
save()	Objects	Saves a shared business object.
setPropertValue(propertyName, propertyValue)	Objects	Sets the value of a property.
toJSONString(formatted)	Both	Returns a JSON representation of the object or list
toXML()	Both	Returns a DOM representation of the object or list
toXMLString()	Both	Returns an XML representation of the object or list

Parsing a JSON string

To parse a JSON string (for example one that was created by toJSONString()) into a variable named myVariable, use JSON.parse():

tw.local.myVariable = JSON.parse(aJsonString);

If the business object type of myVariable is a complex type with properties of type ANY, then the values cannot be complex.

The property names in the JSON string and their values must match the business object type of myVariable.

If the business object type of myVariable contains any Date or Time, then you must enable the type-string-to-date property in the 100Custom.xml file so that the string representation in the JSON string is automatically parsed and converted to a Date or Time. For example:

<common merge="mergeChildren">
	<type-string-to-date merge="replace">true</type-string-to-date>
</common>

Tip: For more information about the 100Custom.xml file, see The 100Custom.xml file and configuration.

Parsing an XML string

To parse a DOM or XML string that was created by toXML() or toXMLString(), you must use the following JavaScript:

tw.local.myVariable = tw.system.serializer.fromXml(aXml);