Cloud Workflow Functions

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 and returning the first resource that matches. 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.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.server_templates.get(filter: ["name==MySQL Database Manager","revision==137"]))

Arguments

Position	Possible Values	Required	Default Value	Comment

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.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.deployments.get(filter: "name==default").servers()
@sorted_servers = sort(@servers)

Sorting a collection of instances by their user data descending:

@instances = rs.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.deployments.get(filter: "name==default").servers()
@server = rs.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.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.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 passed in as a resource declaration. 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 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.

Resource	Behavior	Failure Behavior
Server	Create the Server Launch the Server Wait for the Server to become operational	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	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

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
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")

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 = rs.tags.by_tag(resource_type: "servers", tags: ["app:name=foo" ])
    @arrays = rs.tags.by_tag(resource_type: "server_arrays", tags: [ "app:name=foo" ])
    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.deployments.get(filter: "name==default").servers()
$type_name = type(@servers) # rs.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.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.

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.

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)

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
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).

Arguments

Position	Possible Values	Required	Default Value
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.

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])

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
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.

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.

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).

Arguments

Position	Possible Values	Required	Default Value
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.

Arguments

Position	Possible Values	Required	Default Value
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.

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.

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.

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.

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.

Arguments

Position	Possible Values	Required	Default Value
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.

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" }`

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.

now

Syntax

now()

Description

Returns the current time in a datetime value.

Arguments

None

Result

Date time value that represents the current time in UTC.

uuid

Syntax

uuid()

Description

Returns a string containing a Universally Unique IDentifier.

Arguments

None

Result

A string containing a UUID.

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.

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.

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.

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.

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.

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

Flexera CMP APIs

Cloud Comparison

Feedback

Release Notes

Cloud Workflow Functions

Functions Overview

Collections Management

find

Syntax

Description

Arguments

Result

size

Syntax

Description

Arguments

Result

first and last

Syntax

Description

Arguments

Result

Examples

sort

Syntax

Description

Arguments

Result

Examples

contains

Syntax

Description

Arguments

Result

Examples

empty

Syntax

Description

Arguments

Result

any

Syntax

Description

Arguments

Result

Examples

all

Syntax

Description

Arguments

Result

Examples

select

Syntax

Description

Arguments

Result

Examples

unique

Syntax

Description

Arguments

Result

Examples

Resource Management

provision

Syntax

Description

delete

Syntax

Description

Boolean Logic

equals

Syntax

Description

Arguments

Result

Examples

switch

Syntax