Navigation

Scripting API

One Platform Scripting

Scripts are written in Lua 5.2 scripting language. For general information about Lua 5.2, please reference the Lua 5.2 Reference Manual

The scripting capabilities of the OnePlatform are accessible via the `script` type datarule.

Script capabilities

Scripts can execute arbitrary Lua 5.2 code and access OnePlatform functionality. The exposed OnePlatform functionality consists of read and write access to Aliased client data and access to dispatching content to external recipients.

Scripts execute with the permissions of the script’s owner client.

Aliased data can both be historically accessed as well as waited on in order to process data as it is received.

OnePlatform dispatches may be sent from scripts over a variety of transports and services.

Script environment

Scripts are completely isolated from one another, each running in its own, secure environment, complete with access to a set of Lua tables and functions, as well as a set of OnePlatform functions, tables and properties.

Lua tables

The following global Lua tables have been made available to scripts. They operate exactly ¹ ² as described in the Lua 5.2 reference manual.

Lua functions

The following global Lua functions have been made available to scripts. They operate exactly as described in the Lua 5.2 reference manual.

OnePlatform tables

The following global OnePlatform tables have been made available to scripts.

alias_
json_
manage_

alias

In the OnePlatform, resources of a client are referenced using Aliases. In the scripting environment, all of the script owner’s Aliases are accessible via the `alias` table. To access an Alias, index the `alias` table with a string of the Alias name or resource ID. eg.:

alias["room_temp"] or alias[{rid = ResourceID}]

It is a good idea to create a local reference for Aliases used in the script. eg.:

local room_temp = alias["room_temp"]

Each Alias has properties and functions through which the script can interact with the Aliased resource as defined here.

alias[<Alias>]

.alias

(client aliases only)

This sub alias table is only available if the referenced alias is a client. It provides the same functionality as the global alias table but for the referenced client.

.manage

(client aliases only)

The manage table is only available if the referenced alias is a client. For the functionality provided, see the ‘manage’ table chapter.

.last

When read, it returns the timestamp returned by the most recent call to `.wait` function. When written, the next call to the `.wait` function will wait for the next data point having a timestamp after the written timestamp. Thus it is possible to set `.last` to a point in the past and iterate through historical data using `.wait`. When the script starts `.last` is initialized to the current time.

read

number

write

number

.meta

(read-only)

Provides access to the ‘meta’ field of the Alias’ resource.

read

string

.name

(read-only)

Provides access to the ‘name’ field of the Alias’ resource.

read

string

.status

(read-only)

Indicates the outcome of the most recent activity performed on the Alias. Actions include the reading or writing of any of the Alias properties and functions, excluding `.last` and `.status` itself.

The actual values this property can return are listed with each property and function that can affect the value of `.status`.

read

string

.timestamp

(read-only)

The timestamp of the most recent datapoint written to the resource. If the resource contains no datapoints, `.timestamp` will read nil.

read

number | nil

status

"ok" | "badarg"

.value

When read, it returns the value of the most recent datapoint written to the resource. If the resource contains no datapoints, `.value` will read nil. When written, the given value is recorded with the current timestamp.

read

boolean | number | string | nil

write

boolean | number | string

status

"ok" | "badarg"

.wait () | (<expire>)

Returns the timestamp for the next data point. Next being relative to the timestamp held by `.last`. If there is no datapoint available, the call will block. The optional `<expire>` parameter sets an expiration timestamp in case no datapoint becomes available, in which case nil is returned. When the call returns, .last will be updated to the timestamp of the next unprocessed datapoint or the expiration timestamp.

:<expire>: number :returns: number | nil :status: "ok" | "badarg" | "expired"

[<timestamp>]

Historical data may be accessed using a numerical timestamp.

When read, the value of the datapoint with the given timestamp is returned. If no value exists for the given timestamp then ‘nil’ will be returned.

When written, the given non-nil value gets recorded to the resource at the given timestamp.

:<timestamp>: number :read: boolean | number | string | nil :write: boolean | number | string :status: "ok" | "badarg"

Example

Wait for Aliased resource to receive a data point containing a value representing temperature Celsius; convert the value to Fahrenheit and store it:

local tempC = alias["tempC"]
local tempF = alias["tempF"]
local timestamp = tempC.wait()
if nil ~= timestamp then
  local valueC = tempC[timestamp]
  local valueF = valueC * 9 / 5 + 32
  tempF[timestamp] = valueF
end

json

|JSONORG|_ provides a convienent format for data exchange. The `json` table provides encode and decode routines for processing JSON strings.

json

.array (<table>)

Initializes a Lua table to represent a JSON array. If the given Lua table can not be represented as a JSON array, returns nil and an error string.

:<table>: table :returns: table | nil, error_msg

.decode (<json>)

Decodes the provided JSON encoded string into a Lua type. A special value of `json.null` is decoded for the JSON `null` value. If an error occurs, returns `nil` and an error string.

:<json>: string :returns: string | number | table | true | false | json.null

.encode (<value>)

Encodes the provided Lua value as a JSON string.

:<value>: string | number | table | true | false | json.null :returns: string | nil, error_msg

.null

Represents the JSON ‘null’ constant, use it when constructing Lua tables.

.object (<table>)

Initializes a Lua table to represent a JSON object. If the given Lua table can not be represented as a JSON object, returns nil and an error string.

:<table>: table :returns: table | nil, error_msg

.type (<value>)

Returns the JSON specific type of the supplied value. If the `value` is not a JSON type, `nil` is returned.

:<value>: string | number | table | true | false | json.null :returns: "array" | "object" | "string" | "number" | "boolean" | "null"

manage

The manage table provides resource management functionality.

The manage table can be referenced globally and on client type alias objects. When invoked globally, the functions in the table will act on behalf of the script owner client. When invoked on an alias object, they will act on the alias object owner’s behalf.

manage

.activate (<type>, <code>)

Given an Activation Code `code`, the associated entity is activated for the calling client. Returns `true` if activation was successful.

:<type>: "client" | "dispatch" | "share" :<code>: string :returns: true | false, error_msg

.create (<type>, <description>)
Create a One Platform resource of specified `type` and `description`. Returns `true` if resource was created. `description` is a table

:<type>: "client" | "dataport" | "datarule" | "dispatch" :<description>: table :returns: true, rid | false, error_msg

`description` table formats for the different `type`s are as follows:
"client" description ::
  {
    limits = {
      client = <non_neg_integer> | "inherit"
     ,dataport = <non_neg_integer> | "inherit"
     ,datarule = <non_neg_integer> | "inherit"
     ,disk = <non_neg_integer> | "inherit"
     ,dispatch = <non_neg_integer> | "inherit"
     ,email = <non_neg_integer> | "inherit"
     ,email_bucket = <non_neg_integer> | "inherit"
     ,http = <non_neg_integer> | "inherit"
     ,http_bucket = <non_neg_integer> | "inherit"
     ,io = <non_neg_integer> | "inherit"
     ,share = <non_neg_integer> | "inherit"
     ,sms = <non_neg_integer> | "inherit"
     ,sms_bucket = <non_neg_integer> | "inherit"
     ,xmpp = <non_neg_integer> | "inherit"
     ,xmpp_bucket = <non_neg_integer> | "inherit"
    }
   ,locked = true | false
   ,meta = <string>
   ,name = <string>
   ,visibility = "ancestor" | "parent" | "private" | "public"
   ,writeinterval = <non_neg_integer> | "inherit"
  }

"dataport" description ::
  {
    format = "binary" | "boolean" | "float" | "integer" | "string"
   ,meta = <string>
   ,name = <string>
   ,preprocess = {
      "add"|"sub"|"mod"|"div"|"mul"|"gt"|"lt"|"eq"|"geq"|"leq"|"neq"|"value" =
      <constant> ,...
    }
   ,retention = {
      count = <non_neg_integer> | "infinity"
     ,duration = <non_neg_integer> | "infinity"
    }
   ,subscribe = <rid> | ""
   ,visibility = "ancestor" | "parent" | "private" | "public"
  }

"datarule" description ::
  {
    format = "boolean" | "float" | "integer" | "string"
   ,meta = <string>
   ,name = <string>
   ,preprocess = {
      "add"|"sub"|"mod"|"div"|"mul"|"gt"|"lt"|"eq"|"geq"|"leq"|"neq"|"value" =
      <constant> ,...
    }
   ,retention = {
      count = <non_neg_integer> | "infinity"
     ,duration = <non_neg_integer> | "infinity"
    }
   ,rule = {
      simple = {
        comparision = "gt" | "lt" | "eq" | "geq" | "leq" | "neq"
       ,constant = <number>
       ,repeat = true | false
      }
      |
      timeout = {
        repeat = true | false
       ,timeout = <number>
      }
      |
      interval = {
        comparison = "gt" | "lt" | "eq" | "geq" | "leq" | "neq"
       ,constant = <number>
       ,repeat = true | false
       ,timeout = <number>
      }
      |
      duration = {
        comparison = "gt" | "lt" | "eq" | "geq" | "leq" | "neq"
       ,constant = <number>
       ,repeat = true | false
       ,timeout = <number>
      }
      |
      count = {
        comparison = "gt" | "lt" | "eq" | "geq" | "leq" | "neq"
       ,constant = <number>
       ,count = <number>
       ,repeat = true | false
       ,timeout = <number>
      }
      |
      script = <string>
   }
   ,subscribe = <rid> | ""
   ,visibility = "ancestor" | "parent" | "private" | "public"
  }

"dispatch" description ::
  {
    locked = true | false
   ,message = <string>
   ,meta = <string>
   ,method = "email" | "http_get" | "http_post" | "http_put" | "sms" | "xmpp"
   ,name = <string>
   ,preprocess = {
      "add"|"sub"|"mod"|"div"|"mul"|"gt"|"lt"|"eq"|"geq"|"leq"|"neq"|"value" =
      <constant> ,...
    }
   ,retention = {
      count = <non_neg_integer> | "infinity"
     ,duration = <non_neg_integer> | "infinity"
    }
   ,subject = <string>
   ,subscribe = <rid> | ""
   ,visibility = "ancestor" | "parent" | "private" | "public"
  }
.deactivate (<type>, <code | rid>)

Given an activation `code`, or associated resource ID, `rid`, for shares, the associated entity is deactivated for the calling client. Returns `true` if the deactivation was successful.

:<type>: "client" | "dispatch" | "share" :<code | rid>: string :returns: true | false, error_msg

.drop (<rid | {alias = <alias>}>)

Drop resource specified by either `rid` or "{alias=`alias`}". Returns true if resource is successfully dropped.

:<rid | {alias = <alias>}>: string :returns: true | false, error_msg

.info (<rid | {alias = <alias>}>, <options>)
Provide creation and usage information of resource specified by either `rid` or "{alias=`alias`}". Information is provdided according to the specified `options` (eg, Options could specify to only return the Description). Returns true with an `info` table if successful.

:<rid | {alias = <alias>}>: string :<options>: table :returns: true, info | false, error_msg

`options` table format is as follows. Specify one or more, not all are valid for every resource type:
{
  "aliases"
 ,"basic"
 ,"description"
 ,"endtime"
 ,"key"
 ,"shares"
 ,"starttime"
 ,"storage"
 ,"subscribers"
 ,"tags"
 ,"usage"
}
returned `info` table format is as follows:
{
  -- for all resource types
  basic = {
    created = <timestamp>
   ,modified = <timestamp>
   ,subscribers = <number>
   ,type = "client" | "dataport" | "datarule" | "dispatch"
  }
 ,description = <description> - See 'create' function.
 ,shares = {
    {
      activated = {{<timestamp> ,<rid>} ,...}
     ,code = <code_string>
     ,count = <number>
     ,duration = <number>
    }
    ,...
  }
 ,storage = {
    count = <number>
   ,first = <timestamp>
   ,last = <timestamp>
   ,size = <number>
  }
 ,subscribers = {
    {client | dataport | datarule | dispatch = {<rid> ,...}} ,...
  }
 ,tags = {
    <string> ,...
  }

  -- for clients:
 ,aliases = {
    {<rid> ,{<string> ,...}} ,...
  }
 ,basic = {
    status = "activated" | "locked" | "notactivated" | "expired"
  }
 ,key = <cik_string>
 ,usage = {
    client = <number>
   ,dataport = <number>
   ,datarule = <number>
   ,disk = <number>
   ,dispatch = <number>
   ,email = <number>
   ,http = <number>
   ,io = <number>
   ,share = <number>
   ,sms = <number>
   ,xmpp = <number>
  }

  -- for datarules (scripts only):
 ,basic = {
    status = "completed" | "error" | "running" | "waiting"
   ,activity = {{<timestamp> = {<status> ,...}} ,...}
  }

  -- for dispatches:
 ,basic = {
    status = "activated" | "locked" | "notactivated"
  }
}
.listing (<type>, <options>)
List resource IDs of given `type`s, filtered according to specified `options`. Resource IDs qualified by all options will be returned. If no option is specified, owned resources will be returned by default.

:<type>: table :<options>: table :returns: true, list | false, error_msg

`type` table format is as follows. Specify one or more:
{
  "client"
 ,"dataport"
 ,"datarule"
 ,"dispatch"
}
`options` table format is as follows. Specify none or more:
{
  "activated"
 ,"aliased"
 ,"owned"
 ,"public"
 ,"tagged"
}
returned `list` format is as follows:
{{client | dataport | datarule | dispatch = {<rid> ,...}} ,...}
.lookup (<type>, <rid | {alias = <alias>} | code>)

Lookup an aliased resource from `{alias = <alias>}`, a resource’s owner from `rid`, or a shared resource from `code`. Returns true and the rid of the resource being looked up.

:<type>: "aliased" | "owner" | "shared" :<rid | {alias = <alias>} | code>: string :returns: true, rid | false, error_msg

.map (<type>, <rid | {alias = <alias>}>, <mapping>)

Give the specified resource an alias or a tag named `mapping`. Resource can be specified by Resource ID `rid` or by Alias `{alias = <alias>}`. Returns true if mapping the Resource to the new alias or tag was successful.

:<type>: "alias" | "tag" :<rid | {alias = <alias>}>: string :<mapping>: string :returns: true | false, error_msg

.revoke (<type>, <code>)

Given an activation code, the associated entity is revoked after which the activation code can no longer be used. Returns `true` if the code was successfully revoked.

:<type>: "client" | "share" :<code>: string :returns: true | false, error_msg

.share (<rid | {alias = <alias>}>, <options>)
Generates a share code for the given Resource. Resource can be specified either by `rid` or by `{alias = <alias>}`. Returns `true` with the share code if successful.

:<rid | {alias = <alias>}>: string :<options>: table :returns: true, code | false, error_msg

`options` table format is as follows:
{
  count = <number>
  duration = <number> | "infinity"
}
.unmap (<type>, <mapping>)

Remove the specified `type` of `mapping`. `type` can only be "alias" and `mapping` is the alias name. Returns `true` if the unmap operation was successful.

:<type>: "alias" :<mapping>: string :returns: true | false, error_msg

.update (<rid | {alias = <alias>}>, <description>)
Updates the description of specified resource. See ‘create’ for description parameter content, however that content may be restricted as described below. Returns `true` if update was successful.

:<rid | {alias = <alias>}>: string :<description>: table :returns: true | false, error_msg

`description` restrictions are as follows:
Client Description
``````````````````
Resource limits must not be lowered below current use level.  Resources 
must be dropped prior to lowering the limits. For daily limits, those may 
be lowered at any point and take immediate affect.

Dataport Description
````````````````````
Format must not be changed.

Datarule Descriptions
`````````````````````
Format must not be changed.

Dispatch Description
````````````````````
If the recipient or method is changed, and the recipient/method
combination has never been used before, then further dispatches will be
halted until a validation request is sent and validated.

OnePlatform functions

The following OnePlatform functions have been made available to scripts.

date_
debug_
email_
headline_
sms_
tweet_

These functions can be invoked on the global space and on client type alias objects. When invoked globally, dispatch functions will send messages on behalf of the script owner client. When invoked on an alias object, it will dispatch on the alias object owner’s behalf.

date

Synposis

local result ,error = date(format)

local result ,error = date(format ,time)

Description

Returns the current or supplied time, formatted as specified. Non-specifier characters are copied verbatim to the returned string.

Interface

input/output*	Type	Description
format	string	`*t` or strftime compliant format specifier
		If omitted, defaults to `%c`.
	table	if format was specified as `*t`, the Lua
		table with the following number fields::
		.sec – seconds (0-59)
		.min – minutes (0-59)
		.hour – hours (0-23)
		.day – day of month (1-31)
		.month – month (1-12)
		.year – year
		.wday – weekday (Sun=1-7)
		.yday – days since January 1 (1-366)
time	number	UNIX time value to be formatted
		If omitted, defaults to current UTC time.
result*	string	formatted date and/or time string or `nil`
error*	string	`"badspecifier"` when result is `nil`

debug

Synposis

debug(message)

Description

Writes the given message to the calling script’s datastack. It prepends the message with the line number from which it was called. No return value.

Interface

input/output*	Type	Description
message	string	message to output to script’s datastack

email

Synposis

local status ,error = email(address ,subject ,message ,type)

Description

Dispatches an email `message` to `address` with `subject` line. `type` is optional and specifies the email ‘Content-Type’ header, and defaults to:

"text/plain; charset=UTF-8"

Interface

input/output*	Type	Description
address	string	email address
subject	string	email subject line text
message	string	email body text
type	string	(optional) message content type
status*	boolean	`true` if successful else `false`
error*	string	`"undelivered"` or `"limit"` when `status` is
		`false` otherwise `nil`

headline

Synopsis

local status ,error = headline(address ,subject ,message)

Description

Dispatches an XMPP headline `message` to `address` with `subject` line.

Interface

input/output*	Type	Description
address	string	XMPP JID
subject	string	headline subject line text
message	string	headline body text
status*	boolean	`true` if successful else `false`
error*	string	`"undelivered"` or `"limit"` when `status` is
		`false` otherwise `nil`

setlocale

Synposis

local status = setlocale(locale)

Description

Locale controls formatting and internationalization of various outputs. In the One Platform scripting environment, these are the `date` function and some of the built in Lua functions, such as `tonumber`.

By default, scripts use the en_US.utf8 locale. Scripts can switch to another locale by calling this function and specifying the new locale. The new locale remains in effect until a subsequent invocation of this function.

Interface

input/output*	Type	Description
locale	string	the name of the locale. Supported are the ‘C’ and
		‘POSIX’ locales and the <language>_<country>.utf8
		locales as follows::
		aa_DJ, af_ZA, an_ES, ar_AE, ar_BH, ar_DZ, ar_EG,
		ar_IQ, ar_JO, ar_KW, ar_LB, ar_LY, ar_MA, ar_OM,
		ar_QA, ar_SA, ar_SD, ar_SY, ar_TN, ar_YE, as_IN,
		az_AZ, be_BY, bg_BG, br_FR, bs_BA, ca_AD, ca_ES,
		ca_FR, ca_IT, cs_CZ, cy_GB, da_DK, de_AT, de_BE,
		de_CH, de_DE, de_LI, de_LU, el_CY, el_GR, en_AU,
		en_BW, en_CA, en_DK, en_GB, en_HK, en_IE, en_NZ,
		en_PH, en_SG, en_US, en_ZA, en_ZW, es_AR, es_BO,
		es_CL, es_CO, es_CR, es_DO, es_EC, es_ES, es_GT,
		es_HN, es_MX, es_NI, es_PA, es_PE, es_PR, es_PY,
		es_SV, es_US, es_UY, es_VE, et_EE, eu_ES, eu_FR,
		fi_FI, fo_FO, fr_BE, fr_CA, fr_CH, fr_FR, fr_LU,
		ga_IE, gd_GB, gl_ES, gv_GB, he_IL, hr_HR, hu_HU,
		id_ID, is_IS, it_CH, it_IT, iw_IL, ja_JP, ka_GE,
		kk_KZ, kl_GL, ko_KR, ku_TR, kw_GB, lg_UG, lt_LT,
		lv_LV, mg_MG, mi_NZ, mk_MK, ms_MY, mt_MT, nb_NO,
		nl_BE, nl_NL, nn_NO, oc_FR, om_KE, pl_PL, pt_BR,
		pt_PT, ro_RO, ru_RU, ru_UA, sk_SK, sl_SI, so_DJ,
		so_KE, so_SO, sq_AL, st_ZA, sv_FI, sv_SE, tg_TJ,
		th_TH, tl_PH, tr_CY, tr_TR, tt_RU, uk_UA, uz_UZ,
		wa_BE, xh_ZA, yi_US, zh_CN, zh_HK, zh_SG, zh_TW,
		zu_ZA
status*	boolean	`true` if new locale was successfully set else
		`false`

settimezone

Synposis

local status = settimezone(timezone)

Description

The timezone set for the script affects the output of the `date` function.

By default, scripts use the UTC timezone. Scripts can call this function to switch to a different timezone. The new timezone setting will remain in effect until a subsequent invocation of this function.

Interface

input/output*	Type	Description
timezone	string	the name of the timezone. For a list of available
		time zones, reference ‘List’ table in the following
		article: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
		For the argument to this function, use the timezone
		name values found in the TZ* column of that table.
status*	boolean	`true` if new timezone was successfully set else
		`false`

sms

Synopsis

local status ,error = sms(number ,message)

Description

Dispatches an sms `message` to phone `number`. Phone number must include country code.

Interface

input/output*	Type	Description
address	string	phone number (including country code) with SMS
		capability
message	string	SMS text
status*	boolean	`true` if successful else `false`
error*	string	`"undelivered"` or `"limit"` when `status` is
		`false` otherwise `nil`

Synopsis

local status ,error = tweet(auth ,message)

Description

Dispatches a ‘message’ to www.twitter.com on behalf of the authenticated twitter user application.

Interface

input/output*	Type	Description
auth	table	tweet authentication (see `auth`_)
message	string	tweet text
status*	boolean	`true` if successful else `false`
error*	string	`"undelivered"` or `"limit"` when `status` is
		`false` otherwise `nil`

auth

Authentication with www.twitter.com requires that a user have a twitter.com account and, under their user account, a twitter application, on behalf of which, the OnePlatform script will be able to send tweets. Follow the process described on www.twitter.com to set up an account and an application for your account. Then, under the new application’s settings, obtain the above four values.

Twitter.com rejects subsequent, identical tweets. This can be one of the reasons a tweet API call returns ‘undelivered’.

auth

.oauth_token

A `string` having the Twitter OAuth Access Token.

.oauth_token_secret

A `string` having the Twitter OAuth Access Token Secret.

.oauth_consumer_key

A `string` having the Twitter OAuth Consumer Key

.oauth_consumer_secret

A `string` having the Twitter OAuth Consumer Secret

OnePlatform properties

The following global OnePlatform properties have been made available to scripts.

now_

now

This is a read-only property that returns the current UNIX timestamp.

The string.dump function is not available.↩
The math.randomseed function is not available.↩

Navigation

Scripting API

One Platform Scripting

Script capabilities

Script environment

Lua tables

Lua functions

OnePlatform tables

alias

Example

json

manage

OnePlatform functions

date

debug

email

headline

setlocale

settimezone

sms

tweet

auth

OnePlatform properties

now

Products

Resources

About

Latest Posts