Methods

Syntax

getCell("category")

Arguments

category A name of a category

Description

Returns the cell, of the specified category, of the item or portfolio on which the function is running. The return value is an object of the Cell type. Refer to the Cell table in Objects.

Applies to

Advanced function only.

Example

getCell("Budget Plan").Value

Syntax

getChildren ("category")

Arguments

category A name of a category

Description

Returns an array of cells, of the specified category, of all children of the portfolio on which the function is running.

Applies to

Advanced and Vertical function (Advanced).

Example

// sums up the portfolios planned budget
var sum = 0;
var bud = getChildren(":Budget Plan");
for (var i = 0; i < bud.length; i++)
{
if(bud[i].Value != null)
sum += bud[i].Value;
}
return sum;

Syntax

getSubItems ("category")

Arguments

category A name of a category

Description

Functions can be used to analyze sub-items. For example, they can calculate an item's budget by summing budget of its `Milestone' sub-items.

A function can access the sub-items using any category as source data (including the target category itself).

The information returned is an array of cells that belongs to the specified category. The elements of this array are objects of the SubItemCell type. Refer to the SubItemCell table in Objects.

Applies to

Advanced function only.

Example

var budgetList = getSubItems("Budget 2008");

var totalBudget = 0;

var MILESTONES = getValueList("Sub-Item Type", "Milestones");

for (var i = 0; i < budgetList.length; i++)

{

if (budgetList[i].SubItemType == MILESTONES)

totalBudget += budgetList[i].Value;

}

Syntax

getDependsOnItems ("category")

Arguments

category A name of a category

Description

Functions can be used to analyze the impact of the dependencies. For example, they can calculate a project's health by considering the weighted impact of its dependencies.

A function can access the item's associated dependencies using any category as source data (including the target category itself). This is true in both the `Depends On' and `Supports' directions.

The item (or portfolio) that the function operates on may depend on other items (or portfolios). If such dependencies exist, the getDependsOnItems method returns information about the other item(s) or portfolio(s). The information returned is an array of cells that belongs to the specified category. The elements of this array are objects of the DependencyCell type. Refer to the DependencyCell table in Objects.

Applies to

Advanced function only.

Example

// sums up the planned budget
// for items that this item is dependent on
var sum = 0;
var bud = getDependsOnItems ("Budget Plan");
for (var i = 0; i < bud.length; i++)
{
if(bud[i].Value != null)
sum += bud[i].Value;
}
return sum;

Syntax

getSupportsItems ("category")

Arguments

category A name of a category

Description

Functions can be used to analyze the impact of the dependencies. For example, they can calculate a project's health by considering the weighted impact of its dependencies.

A function can access the item's associated dependencies using any category as source data (including the target category itself). This is true in both the `Depends On' and `Supports' directions.

The item (or portfolio) that the function operates on may support other items (or portfolios). If a supporting relationship exists, the getSupportsItems method returns information about the other item(s) or portfolio(s). The information returned is in the form of an array of cells that belongs to the specified category. The elements of this array are objects of the DependencyCell type. Refer to the DependencyCell table in Objects.

Applies to

Advanced function only.

Example

// sums up the planned budget
// for items that this item supports
var sum = 0;
var bud = getSupportsItems ("Budget Plan");
for (var i = 0; i < bud.length; i++)
{
if(bud[i].Value != null)
sum += bud[i].Value;
}
return sum;

Syntax

getValueList ("valuelist","value")

Arguments

valuelist A name of a value list

value A name of a value in the specified value list

Description

Returns a float that specifies the value's weight. This syntax can be used to compare value list variables.

Applies to

Advanced and vertical function (advanced).

Note: The getValueList syntax does not work with the "Indicators" system values list.

Example

If Risk is a value list category with High, Medium, and Low values, then the following horizontal formula is valid:

("Risk" == getValueList("Risk","High"))?1:0

?: is the JavaScript conditional operator. The formula returns 1 if the item's Risk is High; otherwise it returns 0.

This syntax may be used in an advanced function, as illustrated in the following example:

var risk_score=getCell("Risk").Value;

if (risk_score == getValueList("Risk","High"))
return 1;

return 0;

Syntax

getPhases()

Description

Returns an array of phases representing the life cycle of the item or portfolio on which the function is running. The elements of this array are objects of type 'Phase'. For more information refer to the Phase table in Objects.

Note: The index for the current phase within the Phases array is stored in the CurrentPhaseIndex variable. See reserved words for more details.

Applies to

Advanced function only.

Example

var ph = getPhases();
...
if (ph[i].Health == red) return 0;

Syntax

getIndicator("name")

Arguments

Indicator An indicator name.

Description

Returns the indicator, of the specified category, of the item or portfolio on which the function is running. The return value represents the cell's indicator, and is comparable to the Indicator property of a Cell.

Applies to

Advanced function only.

Examples

Budget_Plan.Indicator==getIndicator("Blue")

getCell("Health").Indicator==getIndicator("Black")

Syntax

setAnnotation("Message")

Arguments

message The text to display in the updated cell's annotation.

Description

Writes the annotation into the cell on which the function is running.

Applies to

Advanced and vertical function (advanced).

Example

var enddate = getCell("End Date") Value;
var diff = (today - enddate.Value);

if (diff>5)
{
setAnnotation("item is" +diff+" days late");
return red;
} else if (diff>0)
{
setAnnotation("item is" +diff+" days late");
return yellow;
} else
{
setAnnotation("item is on time");
return green;
}

Syntax

disableTodayOptimization

Description

By default, a function which uses the today syntax propagates calculations to categories which depend on it, only if the function returns a different value than the current one. So if the category's current value is 3,000, and the categories function is triggered to return 3,000, depending functions will not be triggered and recalculated.

By calling the disableTodayOptimization method, you can ensure that depending functions will be retriggered even if the result does not change the current value.

Applies to

Advanced and vertical function (advanced).

Example

disableTodayOptimization();
var daysDiff = today-getCell("Start Date").Value;
if (daysDiff > 0)
{

return 1;

} else {

return 0;
}

Syntax

getItemName

Description

Returns the name of the item or portfolio that the function runs against. When used on the Value level, getItemName can return results as item names. To run this method on Portfolios, you must first define it in the Summary Value Advanced Function.

Applies to

Advanced function only.

Example

var itemName = getItemName;

return itemName;

Syntax

getSubItemParent

Description

Returns the category value of the item or portfolio that contains the sub-item that the function runs against.

Applies to

Advanced function only.

Example

var amtspent = getCell("Amount Spent on Phase").Value;

var totalamt = getSubItemParent("Total Amount" Spent").Value;

var percentage = (amtspent/totalamt)*100;

return percentage;

Syntax

getHomePortfolio

Description

Returns the category value of the home portfolio that contains the item that the function runs against.

Applies to

Advanced function only.

Example

var homeCategory = getHomePortfolio("Source1").Value;

return homeCategory;

Syntax

getUser

Description

Returns the user properties into a category.

Note: This method can be called only on User type categories.

Applies to

Advanced function only.

Example

var user = getUser("Source1").Value;

return user;