Object

The Object datatype can represent Corporater BMP objects, such as KPIs or Scorecards. Any properties of the object, including custom properties, can have their values accessed from the Object. Additionally, complex expressions can be written using objects. These expressions can allow a user to do things like access ancestor or descendant objects, filter children objects, access the properties of referenced objects, and more.

Objects can be referenced using a token expression consisting of their ID space and ID. The ID space can be thought of as the area of Configuration Studio that the object belongs to, such as the Template, Enterprise Model, Node, or Strategic Initiatives.

Syntax	Result
`<space>.<id>`	References the object with `id` in ID space `space`

o.123                         // Reference to Organization with ID 123
myOrg := o.123                // Stores the reference in a variable
myKpi := t.KPI001             // Stores reference to KPI with ID KPI001 in a variable
myKpi.parent.name             // Returns the name of the KPI's parent Strategic Objective
myKPI.parent.parent.name      // Returns the name of the KPI's Perspective

It is also possible to get multiple objects using queries and special token expressions. For more information on this see the Querying.

myKpis := SELECT Kpi            // Queries for and returns a list of all the model KPIs
myKpis.first().name             // Returns the name of the first KPI in the list

Object Equality

Objects are considered equal if they have the same ID and come from the same ID Spaces.
Two Objects may have the same name, or the same values for other properties, but they are still considered different Objects.
Objects with the same ID, but a different ID space are also not equal.

For example, Object t.100 from the Template ID Space would not equal n.100 from the Node ID Space.

Methods

ancestor [ 5.2.0.1 +]

The ancestor() method returns the first ancestor object that matches the specified type(s). “Ancestors” are objects that are above the current object in the object hierarchy.

Syntax	Result
`<object>.ancestor(<type>)`	The first ancestor object of `object` of type `type`

types: Class Name of the desired type of object or MISSING if no such type is found. Result will be limited to objects of this type.

Examples

t.123.ancestor(Perspective)                 // The first ancestor Perspective of the object with ID 123

t.KP001.ancestor(TaskList)                  // The first ancestor TaskList of the object with ID KP001

children [ 5.2.0.1 +]

The children() method returns all of the first level children-objects of the object. It can also take optional Type arguments to narrow down the results.

Syntax	Result
`<object>.children()`	All of the first level children objects of `object`
`<object>.children([<type>])`	All of the first level children objects of `object` of type `type`
`<object>.children([<type1>], [<type2>], ...)`	All of the first level children objects of `object` of any matching type

types: [Optional] Class Names of the desired types of objects or MISSING if no such type is found. Results will be limited to objects of these types.

Examples

t.123.children()                          // All the first level children of the object with ID 123

t.KP001.children(Task)                    // All of the first level children Tasks of the object with ID KP001

// All of the first level children BarCharts, LineCharts, FunctionStatuses of the object with ID KP001
t.KP001.children(BarChart, LineChart, FunctionStatus)

descendants [ 5.2.0.1 +]

The descendants() method returns all of the children objects, from all levels underneath the object. It can also take optional Type arguments to narrow down the results.

Syntax	Result
`<object>.descendants()`	All the children objects of `object` from all levels under `object`
`<object>.descendants([<type>])`	All the children objects of `object` of type `type`, from all levels under `object`
`<object>.descendants([<type1>], [<type2>], ...)`	All the children objects of `object` of any matching type, from all levels under `object`

types: [Optional] Class Names of the desired types of objects or MISSING if no such type is found. Results will be limited to objects of these types.

Examples

t.123.descendants()                          // All the children, from any level, of the object with ID 123

t.KP001.descendants(Task)                    // All of the children Tasks, from any level, of the object with ID KP001

// All of the child BarCharts, LineCharts, FunctionStatuses, from any level of the object with ID KP001

t.KP001.descendants(BarChart, LineChart, FunctionStatus)

generate

The generate() method is chained onto an object, or list of objects, and outputs the Transactional code needed to replicate the object(s). This code includes any descendant objects of the primary object(s).

By default, generate() will not output the code to replicate the ID of the object(s). However, if given an optional true argument, the id property will be included.

Syntax	Result
`<object>.generate()`	The code to create `object` and any descendant objects
`<object>.generate([true])`	The code to create `object` and any descendant objects, including their IDs.
`<objectList>.generate()`	The code to create the objects in `objectList` and any descendants
`<objectList>.generate([true])`	The code to create the objects in `objectList` and any descendants, including their IDs.

true: [Optional] Boolean true value. When true, generated script will include the ID property.

Examples

t.123.generate()                                // Code to create object with ID 123 and any descendants of it
t.123.generate(true)                            // Same as above, but will also include the IDs of the objects (id := '123', ...)

myKpis := SELECT Kpi FROM t.KPI_LIBRARY
myKpis.generate()                               // Code to create all the KPIs in the list, as well as any descendants of it

rref [ 5.2.0.1 +]

The rref() method performs a reverse lookup of objects that reference (via a reference property) the current object. It can take 4 optional arguments: Property, Type, Start Date, End Date.

The optional Property argument can be used to specify a particular reference property that must reference the current object. If no Property argument is provided, then all reference properties will be considered.

The optional Type argument can be used to filter the results to a particular object type. If no Type argument is specified, all object Types with the specified property will be considered. Object Types that do not have the property will be excluded.

The optional Start Date & End Date arguments can be used to control the time scope when using rref with a Historical Property. Only references that fall within the time range defined by the Start Date and End Date will be included. If a Historical Property is used, and no Start Date or End Date are specified, then the current time context will be used by default.

Syntax	Result
`<object>.rref()`	A list of objects that reference the current object in any way
`<object>.rref(<property>)`	A list of objects that reference the current object via `property`
`<object>.rref(<property>, [<type>])`	A list of the `type` objects that reference the current object via `property`
`<object>.rref(<property>, [<startDate>])`	A list of objects that reference the current object via `property` on or after `startDate`
`<object>.rref(<property>, [<startDate>], [<endDate>])`	A list of objects that reference the current object via `property` within the `startDate` - `endDate` time range
`<object>.rref(<property>, [<type>], [<startDate>)]`	A list of the `type` objects that reference the current object via `property` on or after `startDate`
`<object>.rref(<property>, [<type>], [<startDate>], [<endDate>])`	A list of the `type` objects that reference the current object via `property` within the `startDate` - `endDate` time range

property: A reference property. Objects with this property will be searched for instances where the property references the current object.
type: [Optional] An object Type to filter results by.
startDate: [Optional] A date on or after that references will be searched for
endDate: [Optional] A date on or before that references will be searched for

Examples

myKpi := t.KP001
myKpi.rref(affects)                             // Returns a list of the objects with an affects property that contains myKpi

myKpi.rref(affects, ActionPlan)                 // Returns a list of the ActionPlans with an affects property that contains myKpi

myUser := u.jtolkien
myUser.rref(responsible)                        // Returns a list of  the objects with a responsible property that contains myUser

myUser := u.gwashington
myStart := 1732-02-22
myEnd := 1799-12-14
myUser.rref(measureOwner, myStart, myEnd)       // Returns a list of the objects with a measureOwner property that contains myUser
                                                // at some point within the time range Feb 22, 1732 - Dec 14, 1799

myRisk := t.RSK100
myStart := 2018-01-01
myEnd := 2022-12-31
myRisk.rref(assignedRisks, Kpi, myStart)        // Returns a list of the Kpis with an assignedRisks property that contains myRisk
                                                // at some point within the time range Jan 1, 2018 - Dec 31, 2022

tree [ 5.2.0.1 +]

The tree() method creates a structure of nested lists called a treelist. These treelists greatly simplify the process of making tree tables. tree() takes two optional parameters: an expression resolving to a list of children used to create the treelist, and an expression resolving to a boolean that determines whether a level of children should be collapsed. The tree() method will continue to descend levels based on the first parameter (children expression) until nothing is returned. The table() method works with treelists.

Syntax	Result
`<object>.tree()`	Treelist of `object` and all the descendants of `object`
`<object>.tree([<childExp>])`	Treelist of `object` and all the objects returned by `childExp` expression
`<object>.tree([<childExp>], [boolExp])`	Treelist of `object` and all the objects returned by `childExp` expression, sublists collapsed if `boolExp` was true
`<objectList>.tree()`	Treelist of all descendants of the objects in `objectList`
`<objectList>.tree([<childExp>])`	Treelist of `objectList` and all the objects returned by `childExp` expression
`<objectList>.tree([<childExp>], [boolExp])`	Treelist of `objectList` and all the objects returned by `childExp` expression, sublists collapsed if `boolExp` was true

childExp: An expression resolving to a list of objects. These objects will be considered children of the current level. If no expression is specified, .children will be used.
boolExp: An expression resolving to a boolean. If true, the list of objects returned by childExp will be collapsed. If no expression is specified, the list of objects will not be collapsed.

Examples

root.organisation.tree(organisations)                       // treelist of all the organizations in the system

topOrg := o.100
topOrg.tree(children.filter(className = "Scorecard))        // treelist of all the scorecards under topOrg

managers := g.managers.members                              // Group of users
managers.tree(subordinates)                                 // Treelist of managers and their subordinates.
                                                            // Where subordinates is a custom user reference property added to User

myKpis := SELECT Kpi
myKpis.tree(indicators)                                     // Treelist of Kpis, their children indicators, and any descendant indicators

url [ 5.3.0.0 +]

The url() method is chained onto an object to create a link to that object or to an external URL. By default, the link will be displayed as the icon for the object. For example, using .url() on a KPI object would display a clickable KPI icon. The link can also be displayed as clickable text, or as a custom (non-default) icon.

url() has various optional parameters that can be used to:

display a clickable custom icon or a separate object’s icon instead of the object’s default icon
display a clickable text description
display a tooltip for the link
link to an external URL

The order of the arguments provided to url() plays an important role and functions as follows:

Argument	Function
Object reference	Converted to its icon for display
First String argument	Used as the display text
Second String argument	Used as the tooltip text
Third String argument	Used as an external URL to link to

Note

If an Object reference argument is being specified, it is a good practice to write it as the first argument. This makes it easily discernible from the varying-in-length String arguments.

String Arguments

Expressions can be used in place of hardcoded String arguments. This means that properties, variables, and longer expressions can be used. However, they must resolve to Strings. For example, parent.name is a valid argument, but parent would not be valid. It is possible to use the str() function to convert an invalid property type, such as a Number Property, to a valid String format. For example, str(myNumberProperty) would result in a valid argument.

When String arguments are specified, no icon will be shown unless an Object reference argument has also been specified.

Object References

As previously mentioned, Object references will be converted into their default icon, which will then be displayed. It is also possible to display a custom icon from an image. The image must be in .svg format, and must be uploaded to the Resources section of Configuration Studio. Once uploaded, it can be directly referenced as an argument like r.myFileResourceID, or via a Reference Property pointing to the file.

Syntax	Result
`<object>.url()`	A link to the object. Displayed as the object’s default icon.
`<object>.url([<displayText>])`	A link to the object. Displayed as `displayText` with no icon.
`<object>.url([<objectReference>], [<displayText>])`	A link to the object. Displayed as `displayText` and the object’s default icon side-by-side
`<object>.url([<objectReference>], <displayText>])`	A link to the object. Displayed as `displayText` and the default icon of `objectReference` side-by-side
`<object>.url([<FileResource>], [<displayText>])`	A link to the object. Displayed as `displayText` and a custom icon based on `resource` side-by-side
`<object>.url([<displayText>], [<tooltipText>])`	A link to the object. Displayed as `displayText`, with `tooltipText` as a tooltip and no icon.
`<object>.url([<displayText>], [<tooltipText>], [<externalURL>])`	A link to `externalURL`. Displayed as `displayText`, with `tooltipText` as a tooltip and no icon.
`<object>.url([<FileResource>], [<displayText>], [<tooltipText>], [externalURL>])`	A link to `externalURL`. Displayed as `displayText` and icon from `FileResource` side-by-side, with `tooltipText` as a tooltip

displayText: [Optional] The text to be displayed as a link. Can be hardcoded text, or an expression resolving to text. Displayed side-by-side with icon if an icon argument has been specified.
tooltipText: [Optional] The text to be displayed as a tooltip for the link. Can be hardcoded text, or an expression resolving to text.
externalURL: [Optional] The text (URL) to be linked to instead of the object chained to url(). Can be hardcoded text, or an expression resolving to text.
objectReference | FileResource: [Optional] The icon to be displayed as a link. Can be a direct object reference or an expresion resolving to an object reference. Displayed side-by-side with a displayText argument if one has been specified. If the object referenced is a valid SVG format image file in Resources, then the image from the file will be used as the icon. Otherwise, the default icon of the referenced object’s type will be used.

Examples

t.KPI001.url()                                                                                  // A clickable KPI icon linking to KPI001

t.KPI001.url("My KPI")                                                                          // Clickable "My KPI" text linking to KPI001

t.KPI001.parent.url("Click Here", "Parent Objective")                                           // Clickable "Click Here" text linking to the parent of KPI001, with tooltip "Parent Objective"

t.KPI001.parent.url(self, "Click Here", "Parent Objective")                                     // Clickable Strategic Objective icon + "Click Here" text linking to the parent of KPI001, with tooltip "Parent Objective"

t.KPI001.url("External Dashboard", "BI Dashboard", "company.com/dashboards/KPI001")             // Clickable "External Dashboard" text linking to "www.company.com/dashboards/KPI001" with tooltip "BI Dashboard"

t.KPI001.url(r.TABLEAUICON, "Dashboard", "Tableau", "company.com/dashboards/KPI001")            // Clickable custom icon + "Dashboard" text linking to "www.company.com/dashboards/KPI001" with tooltip "Tableau"

t.KPI001.url(dataSourceIcon, "Data Source", "SharePoint", "company.sharepoint.com/data" )       // Clickable custom icon (referenced by custom reference property dataSourceIcon) + "Data Source" text linking to
                                                                                                // "company.sharepoint.com/data" with tooltip "SharePoint"