Functions Overview

Functions are built-in operations that execute inside the Cloud Workflow engine using RightScale Cloud Workflow Language (RCL). They provide various helpers to address needs like retrieving the current time, generating random numbers, sorting collections and arrays, etc. Functions may operate on values and/or on reference collections and return values and/or reference collections. Arguments passed to functions are read-only. For example, the sort() function will return the result of the sort rather than modify the argument. Functions use the lower_case() notation.

Collections Management

The first category of functions relate to managing resource collections and arrays of values.

find

Syntax

find($type, $name or $hash[, $revision])

Description

This function is syntactic sugar around the resource type get() action. It is the equivalent of calling the get() action with the given filters. It will return the first resource that matches the argument exactly, or if none match exactly, the first resource in the list of resources returned by the get() action.

Filters are specified with a hash or with a string and optional integer. If a string is specified then it is equivalent to a having a hash with a key name and the associated value (i.e. by default filter on name). If a integer is specified then is it equivalent to having a hash with a key revision. So:

@servers = find("servers", "default")
@servers = find("servers", { name: "default" })

are equivalent to:

@servers = first(rs_cm.servers.get(filter: ["name==default"]))

and

@server_template = find("server_templates", "MySQL Database Manager", 137)
@server_template = find("server_templates", { name: "MySQL Database Manager", revision: 137 })

are equivalent to:

@server_template = first(rs_cm.server_templates.get(filter: ["name==MySQL Database Manager","revision==137"]))

Arguments

Position Possible Values Required Default Value Comment
1 string yes none Resource type, e.g. servers, deployments, etc.
2 string or hash yes none Resource name or filters
3 string or integer no none Resource revision, if resource is versioned. Not specifying a value for versioned resources returns all resources with the given type and name.

Result

A resource collection containing the first resource matching the given filter if any.

size

Syntax

size($array, $hash, $string or @collection)

Description

This function simply returns the size of the resource collection or array of values given as argument.

Arguments

Position Possible Values Required Default Value Comment
1 resource collection or array of values or hash of values or string yes none

Result

An integer representing the size of the given array, hash, string or collection.

first and last

Syntax

first($array or @collection) and last($array or @collection)

Description

These functions simply retrieve the first or last element of a resource collection or array of values.

Note: For resource collections, the result is a resource collection itself, consisting of a single resource. However, for an array of values, the result is a single value.

Arguments

The only argument is the collection from which the first or last element should be extracted.

Position Possible Values Required Default Value Comment
1 resource collection or array of values yes none

Result

A resource collection if the argument is a resource collection or a value if the argument is an array of values.

Examples

$one = first([1, 2, 3]) # $one == 1
@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
@first = first(@servers) # size(@first) == 1

sort

Syntax

sort($array or @collection[, $field][, $order])

Description

The sort() function allows sorting resource collections and arrays of values. If sorting an array of values, then all values must be of the same type and the array must not contain null. The ordering follows the same logic as the comparison operators:

  • Numbers and datetime use the natural order (think of datetime in terms of seconds since the epoch for comparison)
  • Strings and arrays follow the lexicographical order
  • true > false

Hashes cannot be compared directly, instead the sort() function accepts an argument to specify recursively which key should be used for sorting. That same argument can be used on resource collections to specify which field should be used for sorting. If the field ends up being a hash, then recursively what key of the hash should be used. By default, sorting resource collections is done using the name field.

Arguments

Position Possible Values Required Default Value Comment
1 resource collection or array of values yes none collection to be sorted
2 string only if collection is an array of hashes name for resource collections name of resource field used to order resource collections or name of key of hash to be used to order for array of hashes
the definition is recursive, each key being separated with the character /
3 asc or desc no asc Sorting order (ascendant or descendant)

Result

The result type is the same as the first argument: a resource collection or an array of values.

Examples

Sorting a resource collection by name:

@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
@sorted_servers = sort(@servers)

Sorting a collection of instances by their user data descending:

@instances = rs_cm.deployments.get(filter: ["name==default"]).server().current_instance()
@sorted_instances = sort(@instances, "settings/user_data", "desc")

Sorting an array of hashes (using a key called timestamp in this example):

$data = [{ "value": 42, "timestamp": d"1/1/2012 12:32" },
         { "value": 43, "timestamp": d"1/1/2012 16:31" }]
$sorted_data = sort($data, "timestamp")

contains

Syntax

contains?($array or @collection, elements)

Description

This function checks whether all the elements of a given collection or a specific value are contained in another given collection. The elements may be in different order and they may appear a different number of times, but as long as all elements appear at least once, then the function returns true, otherwise it returns false.

Arguments

Position Possible Values Required Default Value Comment
1 resource collection or array of values yes none Container being tested
2 resource collection or array of values yes none Elements that must be in container for function to return true

Result

true if all elements are contained in given collection, false otherwise.

Examples

$array = [1, 2, 3, 4]
contains?($array, [1]) == true
contains?($array, [5]) == false
contains?($array, [2, 1, 3, 3]) == true
contains?($array, [1, 2, 3, 5]) == false
@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
@server = rs_cm.get(href: "servers/123") # Assume this server belongs to a deployment named 'default'
contains?(@servers, @server) == true

empty

Syntax

empty?($array or @collection)

Description

Returns true if the given collection (resource collection or array of values) is empty, false otherwise.

Arguments

Position Possible Values Required Default Value Comment
1 resource collection or array of values yes none

Result

true if given collection is empty, false otherwise.

any

Syntax

any?($array[, $value_or_regexp])

Description

This function checks for the existence of an element in an array of JSON values. When only an array is given then returns true if the array contains a value that is neither null nor false. When both an array and a value are provided then returns true if the array contains at least once the given value. If the value is a regular expression, it will return true if there is a least one value that is a string and that matches the regexp. The syntax used to write a regular expressions is /regexp/.

Arguments

Position Possible Values Required Default Value Comment
1 array of values yes none
2 value or regular expression no none

Result

true or false.

Examples

$array_of_false = [false, false, null]
any?($array_of_false) == false # All elements are null or false, result is false
$array = [1, 2, 3, "a", "b", "cde"]
any?($array) == true # Array contains values that are not either false or null, result is true
any?($array, 1) == true # Array contains the value 1
any?($array, "cd") == false # Array does not contain value "cd"
any?($array, "/cd/") == true # Value "cde" matches regular expression "cd"

all

Syntax

all?($array[, $value_or_regexp])

Description

This function checks whether all elements of an array have a given value. When only an array is provided, then it returns true if the array does not contain a value that is either null or false. When both an array and a value is provided, then it returns true if the array values all match the given value. If the value is a regular expression, it will return true if all the values in the array are all strings that match the regular expression. It returns true if the array is empty.

Arguments

Position Possible Values Required Default Value Comment
1 array of values yes none
2 value or regular expression no none

Result

true or false.

Examples

$array_with_one_false = [1, 2, false]
all?($array_with_one_false) == false # One element is null or false, result is false
$array = [1, 2, 3, "a", "b", "cde"]
all?($array) == true # Array contains no null or false, result is true
all?($array, 1) == false # Not all values are one
all?($array, "/cd/") == false # Not all values are strings that match regular expression "cd"

select

Syntax

select($array or @collection, $hash)

Description

This function extracts the elements of a resource collection or of an array of hashes that have fields or values with a given value. The name of the field or hash key that should be selected for comparison correspond to the keys of the hash given as second argument. The values of that hash are the values that the resource fields or hash entries must be selected. If the resource field or hash values are strings, then the selector hash value can represent regular expressions.

Arguments

Position Possible Values Required Default Value Comment
1 resource collection or array of values yes none Container being tested
2 hash yes none Resource field names associated with value that should be filtered on or Hash key name associated with value that should be filtered on

Result

A resource collection composed of resources that have fields with the given values or an array of hashes that have the given values for given keys.

Examples

@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
@app_servers = select(@servers, { "name": "/app/" }) # @app_servers contains servers whose name match
                                                     # the regular expression "app" (i.e. contain the string "app")
$hashes = [{ "key": "value1" }, { "key": "value2" }]
$hashes_with_value1 = select($hashes, { "key": "value1" }) # $hashes_with_value1 contains hashes whose values
                                                           # stored in key "key" is "value1"

unique

Syntax

unique($array or @collection)

Description

This function traverses the given collection and returns a new collection made of all the unique elements. Two resources are considered identical if they have the same href.

Arguments

Position Possible Values Required Default Value Comment
1 resource collection or array of values yes none Container to be traversed and whose unique elements should be extracted

Result

A collection composed of the distinct elements in the initial collection. The types of the elements is preserved (so the result is a resource collection or an array of values depending on the argument).

Examples

@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
@duplicated_servers = @servers + @servers
@unique_servers = unique(@duplicated_servers)
assert @servers == @unique_servers

Resource Management

The following functions help you to work with cloud resources. They are helper functions that encapsulate logic to help create and delete resources in a pre-defined way, saving you from having to implement the logic in your code.

provision

Syntax

provision(@declaration)

Description

This function provisions the resource(s) passed in as a resource declaration and returns a resource collection containing the provisioned resources, or raises an error. A resource declaration is a description of what a resource ought to be and consists of a hash which defines the resource namespace, type and fields which characterize the resource.

The general behavior is that this function creates the resource(s) and waits until it is in a usable state -- what exactly that means for each resource is a bit different. The following table lists the behavior of the provision function for each RightScale resource.

For a bulk resource declaration, the general behavior of the provision function is to retry the provision of each resource in the declaration up to 3 times. If after 3 retries, any resource in the bulk declaration has not provisioned successfully, the entire collection is destroyed and an error is raised. In this case, the $_errors array of hashes will contain errors with copy_index fields, indicating which of the resources in the declaration could not be provisioned. See below for resource-specific behavior.

Resource Behavior Failure Behavior
Server Create the Server
Launch the Server
Wait for the Server to become operational
For bulk: if after launching the server state is inactive, the launch call will be retried up to 3 times
Terminate the Server
Wait for the Server to terminate
Delete the Server
ServerArray Create the ServerArray
Enable the ServerArray
Launch the ServerArray
Wait for at least the min_count number of instances to become operational
Terminate all instances in the ServerArray
Wait for all instances to terminate
Delete the ServerArray
Instance Create the Instance
Launch the Instance
Wait for the Instance to become running
For bulk: if after launching the instance state is inactive, the launch call will be retried up to 3 times
Terminate the Instance
Wait for the Instance to terminate
Delete the Instance
IPAddress Create the IPAddress N/A
IPAddressBinding Create the IPAddressBinding N/A
Volume Create the Volume
Wait for the volume to become available
Delete the Volume
VolumeSnapshot Create the VolumeSnapshot N/A
VolumeAttachment Create the VolumeAttachment N/A

delete

Syntax

delete(@resource)

Description

This function cleans up and deletes the specified resource. Generally speaking, this function will take care to trigger the resource to be decommissioned and then remove the resource altogether -- the specific actions for each resource are a bit different. The following table lists the behavior of the delete function for each RightScale resource.

Resource Behavior
Server Terminate the Server
Wait for the Server to terminate
Delete the Server resource
ServerArray Disable the ServerArray
Terminate all instances in the ServerArray
Wait for all instances to terminate
Delete the ServerArray
Instance Terminate the Instance
Wait for the Instance to terminate
Delete the Instance
IPAddress Delete the IPAddress
IPAddressBinding Delete the IPAddressBinding
Volume Delete the Volume
VolumeSnapshot Delete the VolumeSnapshot
VolumeAttachment Delete the VolumeAttachment

copy

Syntax

copy(count, @declaration, [fields])

Description

The copy function provides a method to create a bulk resource declaration from a single declaration. The first argument must be a single resource declaration from which the bulk declaration will be based. The second argument specifies how many copies of the declaration to create. The third, optional, argument is a hash whose fields are merged into the fields of the base resource declaration -- the hash may contain a copy_index() function which will return the current iteration in the bulk declaration.

Arguments

Position Possible Values Required Default Value Comment
1 number yes none
2 declaration yes none
3 hash no none May not contain any direct resource field access (i.e. @server.name) - use field instead

Examples

# Create a bulk resource declaration with 10 @servers in it
@servers = copy(10, @server)

# Create a bulk resource declaration based on @server where every name is unique
@servers = copy(10, @server, {"name": "My Server #" + copy_index()})

field

Syntax

field(@resource, field_name)

Description

Extracts the current value of field_name from the first resource in the @resource collection. Note: this is different behavior than @resource.field_name, which would actually make an API call to get the latest information about the resource before returning the value.

This function is equivalent to: to_object(@resource)["fields"][0][field_name].

If the field_name string ends with [], then an array of values is returned, representing the value of the field for every element in the collection.

Arguments

Position Possible Values Required Default Value Comment
1 declaration yes none
2 string yes none If ending in [] will return an array of values, otherwise will return the first value

Boolean Logic

The following set of functions all evaluate to true or false. They provide an alternate notation to using operators that may lend itself better when writing declarative code (e.g. when defining the fields of a declaration).

equals

Syntax

equals?($left or @left, $right or @right)

Description

This function checks whether both arguments are equals, it is equivalent to doing left == right.

Arguments

Position Possible Values Required Default Value Comment
1 resource collection or value yes none
2 resource collection or value yes none

Result

true or false.

Examples

$a = 1
$b = 2
$c = 1
equals?($a, $b) == false
equals?($a, $c) == true

switch

Syntax

switch($condition, @true_exp or $true_exp, @false_exp or $false_exp)

Description

This function evaluates the condition and returns either the true expression or false expression based on the value of $condition.

Arguments

Position Possible Values Required Default Value Comment
1 value yes none
2 resource collection or value yes none
3 resource collection or value yes none

Note: Both true expression and false expression should be of the same type.

Result

true expression or false expression

Examples

$anything_but_null = "foobar"
$false_or_null = null
switch($anything_but_null, $var1, $var2) == $var1
switch($false_or_null, @ec2, @google) == @google

logic_and and logic_or

Syntax

logic_and($left, $right) and logic_or($left, $right)

Description

These functions apply the logical and or logical or operators respectively to their arguments. They are equivalent to $left && $right and $left || $right respectively.

Arguments

Position Possible Values Required Default Value Comment
1 value yes none
2 value yes none

Result

true or false.

Examples

$anything_but_null = "foobar"
logic_and($anything_but_null, false) == false
logic_and($anything_but_null, true) == true
logic_and($anything_but_null, null) == false
logic_and(null, null) == false

logic_or($anything_but_null, false) == true
logic_or($anything_but_null, true) == true
logic_or($anything_but_null, null) == true
logic_or(null, null) == false

logic_not

Syntax

logic_not($value​)

Description

Applies the logical not operator.

Arguments

Position Possible Values Required Default Value Comment
1 value yes none

Result

true or false.

Examples

logic_not(true) == false
logic_not(false) == true
$any_value_but_null = "foobar"
logic_not($any_value_but_null) == false
logic_not(null) == true

Data Conversion

The following set of functions are used to convert values from one type to another.

to_s

Syntax

to_s($value)

Description

Convert value to string. The semantic for each type is summarized in the following table:

Type Result Example
string no change to_s("foo") == "foo"
number string representation of number to_s(1) == "1"
boolean string representation of boolean to_s(true) == "true"
datetime string representation of datetime to_s(d"1/1/2012 6:59 PM") == "d\"2012/01/01 18:59\""
null string null to_s(null) == "null"
array JSON representation of an array to_s([1, 2, "3"]) == "[1,2,\"3\"]"
hash JSON representation of a hash to_s({ "one": 1, "two": 2, "three": 3 }) == "{\"one\":1,\"two\":2,\"three\":3}"

to_n

Syntax

to_n($value)

Description

Convert a value to a number. The only types that can be converted to numbers are strings, booleans, and datetimes. Attempting to convert a value of a different type (e.g. an array) will result in an error.

Type Result Example
string corresponding number or 0 if string does not represent a number to_n("1.23123") == 1.23123
to_n("foo") == 0
number no change to_n(1) == 1
boolean 1 for true, 0 for false to_n(true) == 1
datetime number of seconds since the epoch to_n(d"2012/01/26 1:49:35") == 1327542575
null 0 to_n(null) == 0

to_b

Syntax

to_b($value)

Description

Convert value to boolean. The only types that can be converted to booleans are strings and numbers. Attempting to convert a value of a different type (e.g. an array) will result in an error.

Type Result Example
string true if string is true, false otherwise to_b("true") == true
to_b("foo") == false
number true if non 0, false otherwise to_b(42) == true
to_b(0) == false
boolean no change to_b(true) == true

to_d

Syntax

to_d($value)

Description

Convert value to datetime. The only types that can be converted to datetimes are strings and numbers. Attempting to convert a value of a different type (e.g. an array) will result in an error. The accepted syntax for strings representing datetime is:

year/month/day [h:m[:s]] [AM|PM]

Trying to coerce a string that does not match this syntax to a datetime value results in an error.

Type Result Example
string Corresponding datetime if syntax is correct, error otherwise to_d("1/1/2012") == d"1/1/2012"
number datetime with corresponding unix timestamp to_d(42) == d"1/1/1970 00:00:42"
datetime no change

to_a

Syntax

to_a($value)

Description

Convert hash to array of pairs or a range to an array. Converting a value of type other than hash or range will result in an error.

Type Result Example
hash Corresponding array of pairs, ordering is random to_a({ "one": 1, "two": 2, "three": 3 }) == [ ["two", 2], ["one", 1], ["three", 3] ]
range Array of the given range to_a([1..3]) == [1, 2, 3]

to_object

Syntax

to_object(@declaration or @collection)

Description

Convert given resource declaration or resource collection into a JSON object. Especially useful to convert a declaration into an object, manipulate that object and assign it back to a declaration so that e.g. provision() may be called on it.

Type Result Example
collection or declaration JSON object containing declaration or collection fields. Note that objects created from declarations may be assigned back to a reference $data = to_object(@servers)

to_json

Syntax

to_json($value)

Description

Convert a value into a JSON string.

Type Result Example
any JSON string to_json({ "one": 1, "two": 2, "three": 3 }) == '{"one":1,"two":2,"three":3}'

from_json

Syntax

from_json($value)

Description

Convert a string value into a RCL value.

Type Result Example
string RCL value from_json('{"one":1,"two":2,"three":3}') == { "one": 1, "two": 2, "three": 3 }

strftime

Syntax

strftime($date, $format_string)

Description

Converts the given datetime to a string using the format/directives provided.

Arguments

Position Possible Values Required Default Value Comment
1 datetime value yes none
2 string value yes none Use any of the directives specified below when creating the string

The directive consists of a percent (%) character, zero or more flags, optional minimum field width, and a conversion specifier as follows:

%<flags><width><conversion>

Flags:

  • - don't pad a numerical output
  • _ use spaces for padding
  • 0 use zeros for padding
  • ^ upcase the result string
  • # change case

The minimum field width specifies the minimum width.

Format directives:

Date (Year, Month, Day)

Directive Description
%Y Year with century if provided, will pad result at least 4 digits. -0001, 0000, 1995, 2009, 14292, etc.
%C year / 100 (rounded down such as 20 in 2009)
%y year % 100 (00..99)
%m Month of the year, zero-padded (01..12)
%_m blank-padded ( 1..12)
%-m no-padded (1..12)
%B The full month name (January)
%^B uppercased (JANUARY)
%b The abbreviated month name (Jan)
%^b uppercased (JAN)
%h Equivalent to %b
%d Day of the month, zero-padded (01..31)
%-d no-padded (1..31)
%e Day of the month, blank-padded ( 1..31)
%j Day of the year (001..366)

Time (Hour, Minute, Second, Subsecond)

Directive Description
%H Hour of the day, 24-hour clock, zero-padded (00..23)
%k Hour of the day, 24-hour clock, blank-padded ( 0..23)
%I Hour of the day, 12-hour clock, zero-padded (01..12)
%l Hour of the day, 12-hour clock, blank-padded ( 1..12)
%P Meridian indicator, lowercase (am or pm)
%p Meridian indicator, uppercase (AM or PM)
%M Minute of the hour (00..59)
%S Second of the minute (00..60)
%L Millisecond of the second (000..999). The digits under millisecond are truncated to not produce 1000.
%N Fractional seconds digits, default is 9 digits (nanosecond)
%3N millisecond (3 digits)
%6N microsecond (6 digits)
%9N nanosecond (9 digits)
%12N picosecond (12 digits)
%15N femtosecond (15 digits)
%18N attosecond (18 digits)
%21N zeptosecond (21 digits)
%24N yoctosecond (24 digits). The digits under the specified length are truncated to avoid carry up.

Weekday

Directive Description
%A The full weekday name (Sunday)
%^A uppercased (SUNDAY)
%a The abbreviated name (Sun)
%^a uppercased (SUN)
%u Day of the week (Monday is 1, 1..7)
%w Day of the week (Sunday is 0, 0..6)

ISO 8601 week-based year and week number

The first week of YYYY starts with a Monday and includes YYYY-01-04. The days in the year before the first week are in the last week of the previous year.

Directive Description
%G The week-based year
%g The last 2 digits of the week-based year (00..99)
%V Week number of the week-based year (01..53)

Week number The first week of YYYY that starts with a Sunday or Monday (according to %U or %W). The days in the year before the first week are in week 0.

Directive Description
%U Week number of the year. The week starts with Sunday. (00..53)
%W Week number of the year. The week starts with Monday. (00..53)

Seconds since the Epoch

Directive Description
%s Number of seconds since 1970-01-01 00:00:00 UTC.

Literal string

Directive Description
%n Newline character (\n)
%t Tab character (\t)
%% Literal % character

Combination

Directive Description
%c date and time (%a %b %e %T %Y)
%D Date (%m/%d/%y)
%F The ISO 8601 date format (%Y-%m-%d)
%v VMS date (%e-%^b-%4Y)
%x Same as %D
%X Same as %T
%r 12-hour time (%I:%M:%S %p)
%R 24-hour time (%H:%M)
%T 24-hour time (%H:%M:%S)

Example

# Format the current date for CM API 1.5
$time = now()
$api_time = strftime($time, "%Y/%m/%d %H:%M:%S +0000")

to_base64

Syntax

to_base64($value)

Description

Encodes a string into a Base64 String

Type Result Example
string string to_base64("a string") == "YSBzdHJpbmc="

from_base64

Syntax

from_base64($value)

Description

Decodes a base64 string into a string

Type Result Example
string string from_base64("YSBzdHJpbmc=") == "a string"

to_html

Syntax

to_html($value)

Description

Encodes a string into a html encoded string

Type Result Example
string string to_html("&") == "&amp;"

from_html

Syntax

from_html($value)

Description

Decodes an html string into a string

Type Result Example
string string from_html("&amp;") == "&"

to_uri

Syntax

to_uri($value)

Description

Encodes a string into a Uri encoded String

Type Result Example
string string to_uri("http://example.com/?a=\11\15") == "http://example.com/?a=%09%0D"

to_uri_esc

Syntax

to_uri_esc($value)

Description

Encodes a string into a Uri encoded String with all non alphabet or number characters escaped

Type Result Example
string string to_uri_esc("http://example.com/?a=\11\15") == "http%3A%2F%2Fexample.com%2F%3Fa%3D%09%0D"

from_uri

Syntax

from_uri($value)

Description

Decodes a uri encoded string into a string

Type Result Example
string String from_uri("http://example.com/?a=%09%0D") == "http://example.com/?a=\t\r"

Process Information

task_name

Syntax

task_name()

Description

Returns the global name of the current task. See Cloud Workflow Processes for information on tasks.

Arguments

None.

Result

A string that represents the global name of the current task.

Examples

concurrent do
  sub task_name: "launch_app" do
    @servers = find("servers", "db")
    @arrays = find("server_arrays", "appserver")
    concurrent do
      sub task_name: "launch_servers" do
        @servers.launch()
        $name = task_name() # $name == "launch_app/launch_servers"
      end
      sub task_name: "launch_arrays" do
        @arrays.launch()
        $name = task_name() # $name == "launch_app/launch_arrays"
      end
    end
  end
  sub task_name: "notify" do
    # ... do things
  end
end

tasks

Syntax

tasks()

Description

Arguments

None

Result

Returns a hash of task status keyed by global task name. Valid values for a task status are: completed, aborted, canceled, paused, or running.

task_label

Syntax

task_label($label)

Description

Sets the label of the current task. This label is displayed in the Self-Service UI to End Users when an operation is running.

Arguments

Position Possible Values Required Default Value Comment
1 string yes none

Result

The new label string.

task_status

Syntax

task_status($task_name)

Description

Returns the status of the given task. The task name can be relative or absolute (relative match is tried first then absolute if there is no task with a relative name matching the argument).

Arguments

Position Possible Values Required Default Value Comment
1 strings yes none Name of task whose status should be returned

Result

completed, aborted, canceled, paused or running. Returns null for non-existent tasks.

Data Introspection

type

Syntax

type(object)

Description

Returns the name of the type of the given argument. This function is mainly meant to help developing and debugging processes. If the object is a value then the possible type names are: string, number, boolean, datetime, null, array or hash. If the object is a resource collection then the returned name consist of <namespace>.<resource type>. If the object is a declaration, then function will return declaration.

Arguments

Position Possible Values Required Default Value Comment
1 resource collection or value or declaration yes none Object for which type should be retrieved

Result

A string representation of the object type.

Examples

@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
$type_name = type(@servers) # rs_cm.servers

inspect

Syntax

inspect(object)

Description

The inspect() function returns a human readable representation of the object given as argument. This function is meant as a debugging aid.

Arguments

Position Possible Values Required Default Value Comment
1 resource collection or value yes none

Result

String representation of the given object.

Examples

@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
log_info(inspect(@servers))

String Manipulation

capitalize

Syntax

capitalize($string)

Description

Returns a string with first letter of string capitalized (if it is the first character) and the rest lower-case.

See also: downcase, upcase

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none

Result

String.

Examples

$string = "hello"
capitalize($string) == "Hello"
$string = "HeLlO"
capitalize($string) == "Hello"

downcase

Syntax

downcase($string)

Description

Returns a string with all ASCII letters in string changed to lower-case.

See also: capitalize, upcase

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none

Result

String.

Examples

$string = "HELLO"
downcase($string) == "hello"
$string = "HeLlO"
downcase($string) == "hello"

gsub

Syntax

gsub($string, $pattern, $replace)

See also: sub

Description

Returns a string with the all occurrences of pattern substituted for the replace argument. The pattern is typically a regular expression, but can be a string.

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none
2 string value or regex yes none
3 string value yes none

Result

String.

Examples

$string = "hello there howard"
gsub($string, "howard", "tom") == "hello there tom"
gsub($string, /e./, "!") == "h!lo th!!howard"

include?

Syntax

include?($string, $other_str)

Description

Returns true if string contains other_str.

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none
2 string value yes none

Result

Boolean.

Examples

$string = "hello"
include?($string, "el") == true
include?($string, "yo") == false

index

Syntax

index($string, $substr[, $offset])

Description

Returns the index of the first occurrence of substr in string. Returns null if not found. If the offset parameter is present, it specifies the position in string to begin the search (can be a negative number which will be relative to the end of the string).

See also: rindex

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none
2 string value or regex yes none
3 number no 0

Result

Number or null.

Examples

$string = "hello 123"
index($string, "he") == 0
index($string, "he", 2) == null
index($string, "23") == 7
index($string, /[1-9]/) == 6

insert

Syntax

insert($string, $index, $insertion_string)

Description

Returns a string with insertion_string inserted before the character at the given index of string. Negative indices count from the end of string, and insert after the given character. If a positive index is given past the end of string, insertion_string will be inserted at the end. If a negative index is given past the beginning of string, insertion_string will be inserted at the beginning.

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none
2 number yes none The position at which to insert the new string
3 string value yes none The string value to insert

Result

String.

Examples

$string = "hello"
insert($string, 0, "oh ") == "oh hello"
insert($string, -1, " there") == "hello there"
insert($string, 4, "llooo") == "helllloooo"

join

Syntax

join($array[, $separator])

Description

Join elements of array into a single string using given separator if any.

See also: split

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none
2 string value no "" Empty string by default

Result

String.

Examples

$values = ["some", "dash", "delimited", "string"]
join($values, "-") == "some-dash-delimited-string"
join($values) == "somedashdelimitedstring"

lines

Syntax

lines($string[, $separator])

Description

Returns an array of lines in string split using the supplied separator ($/ by default).

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none
2 string value no $/

Result

Array

Examples

$string = "hello\nthere"
lines($string) == ["hello\n","there"]
lines($string, "e") == ["he", "llo\nthe", "re"]

ljust

Syntax

ljust($string, $padded_length[, $padding_value])

See also: rjust

Description

If padded_length is greater than the length of string, returns a string of length padded_length with string left justified and padded with padding_value; otherwise, returns string.

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none
2 number yes none
3 string value no " "

Result

String.

Examples

$string = "hello"
ljust($string, 10) == "hello     "
ljust($string, 3) == "hello"
ljust($string, "10", "end") == "helloenden"

lstrip

Syntax

lstrip($string)

Description

Returns a string with leading whitespace removed from string.

See also: rstrip, strip

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none

Result

String.

Examples

$string = "  hello"
lstrip($string) == "hello"

pluralize

Syntax

pluralize($string)

Description

Returns the plural form of the word in the string. Currently only supports the English locale.

See also: singularize

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none

Result

String.

Examples

$singular_type = "cloud"
pluralize($singular_type) == "clouds"
pluralize("ip_address") == "ip_addresses"

reverse

Syntax

reverse($string)

Description

Returns a string with the characters from string in reverse order.

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none

Result

String.

Examples

$string = "hello"
reverse($string) == "olleh"

rindex

Syntax

rindex($string, $substr[, $offset])

Description

Returns the index of the last occurrence of substr in string. Returns null if not found. If the offset parameter is present, it specifies the position in string to end the search — characters beyond this point will not be considered (can be a negative number which will be relative to the end of the string).

See also: index

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none
2 string value or regex yes none
3 number no none

Result

Number or null.

Examples

$string = "hello 123 123"
rindex($string, "3") == 12
rindex($string, "3", 11) == 8
rindex($string, /1./) == 10
rindex($string, "4") == null

rjust

Syntax

rjust($string, $padded_length[, $padding_value])

Description

If padded_length is greater than the length of string, returns a string of length padded_length with string right justified and padded with padding_value; otherwise, returns string.

See also: ljust

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none
2 number yes none
3 string value no " "

Result

String.

Examples

$string = "hello"
rjust($string, 10) == "     hello"
rjust($string, 3) == "hello"
rjust($string, "10", "end") == "endenhello"

rstrip

Syntax

rstrip($string)

Description

Returns a string with trailing whitespace removed from string.

See also: lstrip, strip

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none

Result

String.

Examples

$string = "hello  "
rstrip($string) == "hello"

singularize

Syntax

singularize($string)

Description

The reverse of pluralize, returns the singular form of a word in a string. Currently only supports the English locale.

See also: pluralize

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none

Result

String.

Examples

$plural_type = "clouds"
singularize($plural_type) == "cloud"
singularize("ip_addresses") == "ip_address"

split

Syntax

split($string, $separator_or_regexp)

Description

Split given string around matches of the given separator or regular expression.

See also: join

Arguments

Position Possible Values Required Default Value Comment
1 String value yes none
2 String value or regex yes none

Result

Array of strings.

Examples

$text = "some-dash-delimited--string--"
$values = split($text, "/-+/") # ["some", "dash", "delimited", "string"]

strip

Syntax

strip($string)

Description

Returns a string with leading and trailing whitespace removed from string.

See also: lstrip, rstrip

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none

Result

String.

Examples

$string = "  hello  "
lstrip($string) == "hello"

sub

Syntax

sub($string, $pattern, $replace)

Description

Returns a string with the first occurrences of pattern substituted for the replace argument. The pattern is typically a regular expression, but can be a string.

See also: gsub

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none
2 string value or regex yes none
3 string value yes none

Result

String.

Examples

$string = "hello there howard"
sub($string, "howard", "tom") == "hello there tom"
sub($string, /e./, "!") == "h!lo there howard"

upcase

Syntax

upcase($string)

Description

Returns a string with all ASCII letters in string converted to upper-case.

See also: capitalize, downcase

Arguments

Position Possible Values Required Default Value Comment
1 string value yes none

Result

String.

Examples

$string = "hello"
upcase($string) == "HELLO"
$string = "HeLlO"
upcase($string) == "HELLO"

HTTP-HTTPS Functions

This set of functions provides the ability to call HTTP/HTTPS endpoints from within Cloud Workflow. There is one function for each of the well-known HTTP verbs (get, post, head, put, patch, delete, options, and trace). The functions take all request attributes as parameters and return the response in a hash value with the keys code, headers, cookies, and body (each containing their respective response attributes).

There is also a generic function called http_request which takes the verb as a parameter for any type of HTTP/HTTPS call. General Information

Making Requests

When using these functions, there is some specific behavior that is of interest:

  • If a body is given for the request and the corresponding value is not a string then the functions will encode the value in JSON.
  • The verb-specific functions take a single url argument that includes the scheme, host, href, and query strings.
  • The generic http_request function takes individual arguments (host, https, href, query_strings) to form the url.

Common Parameters for HTTP-HTTPS functions

The following parameters are available for all verb-specific and generic HTTP functions.

Name Possible Values Required Description Example Default
headers hash of string -> string values no HTTP request headers, the keys are the classical content-type (or content_type), accepts, etc. Passing lowercase with underscore instead of dash is OK, the implementation normalizes to standard HTTP header names behind the scenes. { "X-Api-Version": "1.0" }
body string (or any value if content-type is JSON) no The request body. When unspecified and the method is one of those that expect a body, will default to "" (empty string). A body can be given for methods that don't require it (GET, HEAD) and it will probably get discarded by the server.
raw_response boolean no The default is false. When false (default) and the response is application/json (or an extension of it), the response body will contain the parsed value (not the JSON string).
In case of XML content (and unless raw_response is set to true), the XML is turned into a JSON-compatible data structure (a representation of the XML tree).
true false
basic_auth an object with keys username and password no Specifies a pair (username, password) for the basic authentication of this request. { "username": "foo", "password": "bar" }
cookies Array of cookie objects no An array of cookies to send to the server. Only name and value are allowed. [ { "name": "zz", "value": "yy" } ]
noredirect boolean no The default is false. By default the http method will follow any redirection. Infinite loops are detected and raise an error. true false
insecure boolean no The default is false. By default the http method will verify SSL certificates. When set to true, the check is not done. true false
signature an object with keys type, access_key, and secret_key no Used for signing requests for AWS. The type should be aws. The access_key and secret_key fields specify the AWS credentials to use for signing the request. If the access_key or secret_key fields are not provided, the default AWS credentials (AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY) for the account will be used. Note: when using the default keys, the user launching the CAT must have admin role on the account in order to read credential values. { "type": "aws", "access_key": "myaccesskey", "secret_key": "mysecretkey" }
auth a credentials reference no A reference to credentials in the credentials service. When called from a policy, credentials references are automatically imported as global variables such as $$auth_aws. When developing via the console, you can use the signer function to generate an equivalent reference. signer(aws_default) or $$auth_aws

HTTP-HTTPS Function Responses

The return value of every HTTP/S function is a hash with the following elements:

Name Type Description Example
code number The response code. Eg: 200 200
headers hash The headers from the http response { "Connection": "keep-alive", "Content-Encoding": "gzip" }
cookies array of objects The cookies received in the response For a cookie received as string, zz=yy; Domain=.foo.com; path=/; secure, it will be parsed as follows:
[ { "name": "zz", "value": "yy", "path": "/", "domain": ".foo.com","expires": <DateTime formatted value>, "secure": true }]
body string if raw_response was set to true (or it was set to false but could not be parsed as an object)
object if raw_response was set to false (which is by default) and the content type was xml or json
The body of the response

http_get, http_post, http_head, http_put, http_patch, http_delete, http_options, http_trace

Syntax

http_get($params), http_post($params), http_head($params), http_put($params), http_patch($params), http_delete($params), http_options($params), http_trace($params)

Description

The verb-specific functions have the following parameters, in addition to the Common Parameters listed above. The return value from these functions is documented above in HTTP Function Responses.

Name Possible Values Required Description Example Default
url string yes The url for the request including the scheme (http/https), host, href, as well as query strings. https://www.googleapis.com/drive/v2...

http_request

Syntax

http_request($params)

Description

The general function has the following parameters, in addition to the Common Parameters listed above. The return value from these functions is documented above in HTTP Function Responses.

Name Possible Values Required Description Example Default
verb string yes The HTTP verb (should be one of get, post, patch, put, delete, options, head) get
host string yes The host of the external service www.googleapis.com
https boolean no Whether to https/http true false
href string no The href of the target resource relative to the host. /drive/v2/files/123 ""
query_strings hash no Query-string values (what comes after a ? in the URL). Keys must be strings. Values are turned into strings (arrays and hashes are JSON encoded). All the values are escaped. { "updateViewedDate": true } {}

Miscellaneous

assert

Syntax

assert(expression)

Description

This function evaluates an assertion. It takes an expression that resolves to a value as an argument. If the expression does not resolve to a value, resolves to null, or resolves to false then an error is raised. In all other cases it does nothing.

Arguments

Position Possible Values Required Default Value Comment
1 expression yes none The expression that should return a value to assert

Result

None.

cred

Syntax

cred($cred_name)

Description

Return the value of the Credential in Cloud Management with the given name. Note: using this function requires the admin role, or a permission that grants the admin role. Note: It will return an exact match if available, if not will return first partial match.

Arguments

Position Possible Values Required Default Value Comment
1 string yes none The name of the Credential in Cloud Management

Result

The string value of the specified Credential, or Raises an error if the Credential is not found or the user doesn't have the required privileges

signer

Syntax

signer($identifier)

Description

Return a signer reference defined in the Credentials dashboard. This is a newer version of the Cloud Management Credential resource. Note for policy developers: Signer references are automatically imported for all credentials and auth blocks from the Policy engine. Note: using this function requires the admin role, or a permission that grants the admin role. Note: Must exactly match the identifier field of the credential.

Arguments

Position Possible Values Required Default Value Comment
1 string yes none The identifier of the Credential in Credentials dashboard

Result

A reference to the Credentials resource, or raises an error if the Credentials is not found or the user doesn't have the required privileges

jwt_encode

Syntax

jwt_encode($algorithm, $payload, $key, $header_fields)

Description

This function creates a JWT from the fields provided. For more information on json web tokens visit: https://jwt.io/

Arguments

Position Possible Values Required Default Value Comment
1 string yes none Encryption Algorithms Supported(RS256,RS384,RS512,HS256,HS512256,HS384,HS512)
2 hash yes none Hash Payload for jwt token
3 string yes none Encryption key for the payload, RS* Encryption requires an RSA Key
4 hash no none header fields, such as typ

Result

A string containing a jwt token

keys

Syntax

keys($hash)

Description

Return an array made of all the keys of the provided hash.

Arguments

Position Possible Values Required Default Value Comment
1 hash yes none Hash for which keys should be retrieved

Result

Array of strings representing all the keys of the provided hash.

map

Syntax

map($mapping_name, $key_name, $value_name)

Description

Return the value of a two level hash given a key and value name. This function is syntactic sugar around the [] operator. It may provide a better notation when writing declarative code (e.g. in resource declarations). So doing map($hash, $key, $value) is equivalent to $hash[$key][$value].

Arguments

Position Possible Values Required Default Value Comment
1 hash yes none Hash for which value should be retrieved
2 string yes none Name of key
3 string yes none Name of value

Result

Hash value at given key and value name.

now

Syntax

now()

Description

Returns the current time in a datetime value. See the strftime function for formatting a datetime into a string.

Arguments

None

Result

Date time value that represents the current time in UTC.

rand

Syntax

rand($max_value)

Description

Generates a random number. If max_value if specified, the random number is an integer between 0 and max_value. If max_value is not specified, the random number is a double between 0 and 1.

Arguments

Position Possible Values Required Default Value Comment
1 number no see above max number to generate a random integer

sleep

Syntax

sleep($duration)

Description

Makes the current task sleep for the time expressed in duration. A duration consists of numbers suffixed with s (seconds), m (minutes), h (hours) or d (days). Each element of the duration is additive (so 2m30s means 2 minutes plus 30 seconds). If no suffix is specified then the number represents seconds.

Arguments

Position Possible Values Required Default Value Comment
1 duration yes none

Examples

sleep(60) # sleep one minute
sleep(1h) # sleep 60 minutes
sleep(2m30s) # sleep 150 seconds

Result

None.

sleep_until

Syntax

sleep_until(expression)

Description

This function takes an expression that resolves to a value as argument. If the expression does not resolve to a value, then an error is raised. Sleeps until the expression evaluates to a value that is neither null nor false.

Arguments

Position Possible Values Required Default Value Comment
1 expression yes none The expression that should return a value that is neither null nor false for the wait to stop

Result

None.

sleep_while

Syntax

sleep_while(expression)

Description

This function takes an expression that resolves to a value as argument. If the expression does not resolve to a value then an error is raised. Sleeps while the expression evaluates to a value that is neither null nor false.

Arguments

Position Possible Values Required Default Value Comment
1 expression yes none the expression that is run

Result

None.

tag_value

Syntax

tag_value(@resource, $tag_prefix)

Description

Returns the value part of a machine tag given the <namespace>:<predicate> of the tag.

Arguments

Position Possible Values Required Default Value Comment
1 resource yes none
2 string yes none <namespace>:<predicate> to find

Result

String containing the value part of the tag, if it is found. Otherwise, null

uuid

Syntax

uuid()

Description

Returns a string containing a Universally Unique IDentifier.

Arguments

None

Result

A string containing a UUID.

values

Syntax

values($hash)

Description

Return an array made of all the values of the provided hash.

Arguments

Position Possible Values Required Default Value Comment
1 hash yes none Hash for which values should be retrieved

Result

Array of strings representing all the values of the provided hash.

xpath

Syntax

xpath($xml_string, $xpath)

Description

Using a XPath string, extracts information out of an XML string.

Arguments

Position Possible Values Required Default Value Comment
1 string yes none XML string
2 string yes none XPath string like //item[2]/name/text() or css:div.li path

The xpath argument can be passed a css: prefix, in which case the path is a CSS path, not a XPath.

Result

Array of [XML] strings.