PROformajs uses restricted Javascript expressions to query the state of a runtime enactment and evaluate schedule, value and argument conditions. The source code for this functionality can be found in src/evaluator.coffee. This page details the functions that are exposed.

Validation

Expressions are restricted to logic and arithmetic functions and the predicates listed below. The aim is to restrict expressions so that they cannot have side effects on the engine state. All expressions are validated at design time and invalid expressions will block the creation of an runtime enactment.

Examples

If you define an integer data definition for age then you can use simple comparisons for argument conditions, task pre-conditions or data definition warning conditions, i.e. age>=18 or !age<=0. When you name a data definition as an argument in a predicate, however, you will need to add single quotes, i.e. is_known('age').

Paths

Many of the arguments for predicates in the following sections will need component paths to be passed as arguments. In all cases the absolute design path will work, but oftentimes a name is sufficient, if that name identifies a child or sibling component.

Task state

The task state engine evaluates the preCondition and waitCondition expressions that guard how a task moves through the four task states: dormant, in_progress, completed and discarded. The taskpath parameter in these predicates can be the full path of a task or the name of sibling/child task. At runtime the predicates will throw an error if the taskpath does not identify a task (i.e. if an external expression is evaluated via the Enactment.evaluate method).

is_dormant

is_dormant(taskpath): Boolean

Returns true if the indicated task is dormant, else false.

is_in_progress

is_in_progress(taskpath): Boolean

Returns true if the indicated task is in_progress, else false.

is_completed

is_completed(taskpath): Boolean

Returns true if the indicated task is completed, else false.

is_discarded

is_discarded(taskpath): Boolean

Returns true if the indicated task is discarded, else false.

is_finished

is_finished(taskpath): Boolean

Returns true if the indicated task is completed or discarded, else false.

num_finished

num_finished([taskpath]): Integer

Evaluates the status of tasks identified in the array of taskspaths presented and returns the number of them that are finished (discarded or completed).

num_completed

num_completed([taskpath]): Integer

Evaluates the status of tasks identified in the array of taskspaths presented and returns the number of them that are completed.

index

index(taskpath): Integer

Returns the current index of the cyclic task identified via the taskpath. Throws an error if the taskpath fails to identify a task.

last_finished

last_finished(taskpath): runtimepath

Returns the runtimepath of the most recently finished instance (i.e. the previous cycle) of a cyclic task.

Decision state

Decision tasks have a handful of predicates for use in a Candidate's recommendCondition attribute and Argument's activeCondition attribute.

net_support

net_support(candidatepath): Integer

Returns the aggregated support of all active arguments for the indicated candidate. The candidatepath parameter may be a full path or the name of a candidate associated with the current decision context or one of the current decision's siblings. Throws an error at runtime if candidatepath fails to identify a candidate.

result_set

result_set(decisionpath): [candidatename]

Returns an array of confirmed candidate names for a particular decision. Returns null if the decisionpath parameter fails to identify a decision.

result_of

result_of(decisionpath): candidatename

Returns the confirmed candidate name of a particular decision or undefined. Returns null if the decisionpath parameter fails to identify a decision.

Data state

Its useful to query the state of externally provided data.

is_known

is_known(datadef): Boolean

Returns true if a value for datadef is available, otherwise false. Throws an error at runtime if datadef is not defined in the guideline.

is_valid

is_valid(datadef): Boolean

Returns true if a value is provided for a datadef and there are no associated warnings, else false. Throws an error at runtime if datadef is not defined in the guideline.

caption

caption(datadef): String

Returns the caption of ranged and annotated data definition values. If the data definition isnt ranged and annotated, it returns the datadef value. If the data definition is multiValued it returns an array of captions.

captions

captions(datadef): String

Returns a readable list of multivalued range value captions, e.g. "one, two and three" when the datadef value is [1,2,3] and the data definition is multiValued and has a range of [{value: 1, caption: 'one'},{value: 2, caption: 'two'},{value: 3, caption: 'three'}].

includes

includes(arrayVal, member): Boolean

Returns true if member is in arrayVal. Note that this is much safer than arrayVal.includes(member) which will be accepted and will work unless arrayVal is undefined when it will create a runtime exception. This predicate can be used to check the result_set of decisions.

Temporal

Its often important to compare the timing of some events to now or other events. Several predicates allow you to do this.

These predicates return Moment objects which hold dates and provide three useful addition predicates: diff, add and subtract. So for instance, a Source requestCondition might contain the following expression !is_known('cough') || last_updated('cough').diff(now(), 'days')>0 which would make the source requested if cough isnt known or is more than a day out of date.

now

now(): Moment

Returns the current time.

last_updated

last_updated(datadef): Moment

Returns the date that the last value for datadef was provided else undefined if no value is available. Throws an error if datadef is not defined in the guideline.

in_progress_time

in_progress_time(taskpath): Moment

Returns the time that the indicated task went to in_progress. Throws an error at runtime if the taskpath parameter fails to identify a decision.

completed_time

completed_time(taskpath): Moment

Returns the time that the indicated task was completed. Throws an error at runtime if the taskpath parameter fails to identify a decision.

discarded_time

discarded_time(taskpath): Moment

Returns the time that the indicated task was discarded. Throws an error at runtime if the taskpath parameter fails to identify a decision.

finished_time

finished_time(taskpath): Moment

Returns the time that the indicated task was finished (completed or discarded). Throws an error at runtime if the taskpath parameter fails to identify a decision.

Mathematical

Some external data will be numeric. Predicates for standard mathematical operators are provided.

round

round(float): Integer

Returns the passed value rounded to the nearest integer.

abs

abs(float): Float

Returns the absolute value of a number, i.e. the size of the value.

random

random(): Float

Returns a number between 0 and 1.

sin

sin(float): Float

Returns the sine of a number.

cos

cos(float): Float

Returns the cosine of a number.

tan

tan(float): Float

Returns the tangent of a number.

asin

asin(float): Float

Returns the arcsine of a number.

acos

acos(float): Float

Returns the arcosine of a number.

atan

atan(float): Float

Returns the arctan of a number.

count

count(arr): Integer

Counts the array members. Returns the number of members in the array.

sum

sum(arr): Float

Sums the members of an array.

min

min(arr): Float

Returns the minimum value of an array.

max

max(arr): Float

Returns the maximum value of an array.

nth

nth(arr, idx): Object

Returns the idx value of an array.

exp

exp(float): Float

Returns the exponent of a value.

log

log(float): Float

Returns the log of a value.

Miscellaneous

includes

includes(arrayVal, member): Boolean

Returns true if member is in arrayVal. Note that this is much safer than arrayVal.includes(member) which will be accepted and will work unless arrayVal is undefined when it will create a runtime exception.