Phi function reference

Working with data in Phi: functions for debugging, triggering alarms, setting data, getting reliability info

The following Assetwolf-specific functions are available in Phi:

  • dump(mixed value, mixed ...values)

    Returns null

    This function dumps the value of a variable given by variablename while doing a dry run of a Phi script.

    An alias of print(). When running outside of a dry run this function is ignored.

  • fireTrigger(string triggerCodeName, string explanation)

    Returns null

    Causes a trigger of an alarm to fire — in other words, for the trigger status to become True, and for any linked procedure to be enacted.

    triggerCodeName specifies the code name of the alarm trigger. An alarm trigger in the AssetWolf portal should be created with this code name before the Phi script referring to it can run.

    explanation is the text that will be passed to the trigger when it is fired. It can contain variables from the Phi script (e.g. the current temperature etc.). This text will be available to the called procedure, so that it can form the body of an email or SMS. To do this, use a merge field in the procedure with the text [[explanation]] (note the square brackets).

    If an alarm trigger is configured with the "Triggered from the Phi script in the schema" option, then running the fireTrigger() function in the Phi script for an asset or data pool will cause the trigger status to become True, in other words, that an alarm begins.

    If the script runs again (e.g. when more data is received or bubbles up) and fireTrigger() is called again while the status of that trigger is already True, there will be no further effect, and linked procedures will not be re-run. However if the Phi script runs and the fireTrigger() function is not called again, then the alarm trigger will end and any end-of-alarm procedures will then be called.

  • For this reason, the fireTrigger() function could be thought of as a "determine which alarm conditions are met" function.
  • formatValue(mixed value, string field[, boolean addUnits[, integer nodeId]])

    Returns string

    Normally in your Phi script, you'll be working with the actual values of fields. However in the portal, when we display a value to a user, we often format it first.

    If you have a value that you with to display formatted, you can use this function. You should pass the value as the first parameter, and the name of the field that it's for as the second parameter.

    For fields with units, you can use the third parameter to control whether the units will get automatically appended to the end. This option defaults to true if not set.

    Finally, if you're trying to format a value from a node that's not the current node being processed, you should pass the node's ID into the fourth parameter. (This can be omitted if the value/field is from the current node being processed.)

  • getAssetReliability(datetime fromTimestamp, datetime toTimestamp[, integer assetId])

    Returns float

    Returns a number between 0 and 1 of how reliable an asset's connectivity was between the specified timestamps.

    When called from within a metric, the parameters fromTimestamp and toTimestamp can be written verbatim, as these are created by the execution of the script.

    This will only return a meaningful result if the normal communication interval has been defined on the schema of the related asset (e.g. "every 15 minutes"). Given a time range, the function adds up all of the for and asset communicated regularly in the given time range. If the asset communicated within the normal communication interval (plus the tolerance for late communication, if set), every time, this means the asset was reliable; whereas if communications arrived late, the amount lateness time is summed up and proportionally subtracted from 1, in proportion to the measured time period.

    In summary, a result of 0 means the asset failed to communicate at all in the time period, whereas 1 menas it always communicated on time (allowing for tolerance) or sooner.

  • setValue(string field, string value)

    Returns null

    Sets the value of a calculated field whose code name is given by field to the value value.