Skip to main content

General Statements

All the general OpenDataDSL statement commands

api-key​

Command to manage your user API Keys

Syntax​

apikey: api-key (create (start="string")? (expires="string")? |delete) "name";

Description​

An API Key is used as a password to authenticate you in OpenDataDSL from an external application that cannot use OAUTH2 or Azure Active Directory.

Explanation of the syntax​
  • The name is a string that is used to identify what you are going to use the key for
  • The create directive creates a key
    • You can add an optional start date for the key
    • You can add an optional expires date for the key
  • The delete directive deletes (revokes) the named key
info

After running the create command, the key is output into the debug console, make sure you copy the key as this is the only time you will see it.

Examples​

Create a key that starts now and never expires

api-key create "mykey"

Create a key that starts and a date and expires

api-key create start="2024-05-01" expires="2024-12-31T23:59:59" "mykey"

Revoke a key

api-key delete "mykey"

List all your keys

print ${user:"me"}.keys

import​

Imports functions from a script into the current script

Syntax​

import ${script:"name"}

Description​

The import command gets the named script from the script service and makes all the user defined functions in that script available in your current script.

Example​

If we have a script with a function, e.g. this functions.odsl script saved in the server:

// functions.odsl
function agricultural(input)
    // Agricultural curve forward filled and extended to end of 3 years
    filled = forwardFillCurve(input)
    extended = extendCurve(filled, 3)
    agricultural = shape(extended)
end

We can import that script and call the agricultural function, e.g.

// Import the functions we defined in functions.odsl
import ${script:"functions"}

inputcurve = ${data:"inputcurve"}
curve = agricultural(inputcurve)

log​

Outputs a message to the console and to a process execution log

Syntax​

log LEVEL message

Description​

If the script is running in a process, the message is output into the process execution log. The message is also output to the console.

The LEVEL option allows you to specify the log level of the message from one of:

  • debug
  • info
  • warn
  • fatal

Examples​

log debug "This is a debug message"
log info "This is an info message"
log warn "This is a warning message"
log fatal "This is a fatal message"

a = 12.2
log debug "The value is " + a

logout​

Used to log out the current user

Syntax​

logout

Description​

This command is used in a script to log out the current user

onerror​

Determines how errors are handled

Syntax​

on error (exit|ignore)

Description​

The on error statement instructs OpenDataDSL on how you want to handle errors. You have 2 options:

  • exit - this is the default action which stops the currently running script and outputs the error message
  • ignore - this option doesn’t stop the script running, but it places the error message into a scalar variable called error

Examples​

Using on error exit:

on error exit

// Create a date variable
d = Date()

// Call an unknown method that will force throwing an error
print d.unknown()

Using on error ignore:

on error ignore

// Create a date variable
d = Date()

// Call an unknown method that will force throwing an error
print d.unknown()

// Script continues and we can see the error message in the variable called error
print error

pause​

Pauses execution of a script for a certain amount of time

Syntax​

pause number ('second'|'seconds'|'minute'|'minutes'|'hour'|'hours')

Description​

Pauses execution of a script

Examples​

pause 10 seconds

pause 1 minute

print​

Prints a message to the console

Syntax​

print message

Description​

The print command prints a message to the console. The message can be a string, variable or expression.

Examples​

a = "example"
print a
example
print "This is an " + a
This is an example

return​

Terminates the currently running script and returns a variable

Syntax​

return expression

Description​

The return statement terminates running of a script and returns a variable to the calling application

Examples​

return "Finished"

run​

Runs a process remotely

Syntax​

run processname (with input)? (log reason)? (in delay TIMEUNIT)?

Description​

The run command remotely triggers a manual run of a process. You can optionally provide a variable with input run parameters, a reason log message that will be added to the audit log and a delay for when to run the process.

Options​

With input​

You can optionally provide a variable with some input information which will override or provide specific context to the process, e.g.

// Run a curve
ondate = Object()
ondate.date = "2021-04-26"
run CURVE_TEST with ondate
Log reason​

You can optionally give a reason for manually triggering a process, this will be logged in the audit log

In delay​

You can optionally delay the starting of the process, e.g.

run MY_PROCESS in 1 hour

The timeunit parameter can be one of:

  • second
  • seconds
  • minute
  • minutes
  • hour
  • hours

send​

Send a batch of objects to a message queue

Syntax​

send variable (to queue)? (size INT)? (-noevent)?

Description​

The send command sends a batch variable to a message queue in order to be processed by either the data loader or an external application.

If no queue name is specified, the batch is sent to your default queue.

Options​

TO queue

You can optional specify the name of the queue to send the batch to.

SIZE INT

You can override the default number of items sent per message using the size command

-noevent

Add this option if you don’t want to trigger downstream processes, exports etc. from the sending of this message. This would be usually done if you are back-filling some historic data and only require that the data is added.

Examples​

// Create a batch
batch=PROCESS.createBatch()

// Add some objects to the batch
...

// Send to the default queue
send batch

// Send the batch to the queue named 'myqueue'
send batch to myqueue

// Send the batch to the queue in batches of 10 objects at a time
send batch size 10 

// Send the batch to update but not trigger downstream events
send batch -noevent

set​

Used to set a session option

Syntax​

set (precision INT|
    rounding ROUNDING_METHOD|
    missing (ignore|number)?|
    crs (earth|planar)|
    observed (default|beginning|end|averaged|summed|high|low|delta)|
    distribution (none|constant|linear|cubic)|
    autoscale (on|off)|
    credentials for source as user password|
    auto_follow_references (true|false)|
    while_limit number
    )

Description​

The set command is used to set an option within the current script session. The following options are supported:

  • decimal precision
  • rounding method
  • missing value treatment
  • coordinate reference system
  • timeseries scaling methods
  • credentials for interacting with external systems
  • options for following referenced data
  • while loop iteration limit
Setting decimal precision​

The decimal precision determines the number of decimal places to use with real numbers, e.g.

set precision 2

Sets the decimal places to 2 for all numbers

Setting the rounding method​

The rounding method determines how numbers are rounded when shortening to meet the decimal precision value, you can select from one of the following methods:

  • ceiling
  • down
  • up
  • floor
  • half_down
  • half_up
Setting missing value treatment​

Missing values can affect the way calculations are performed and therefore you can set the way that you want missing values to be treated. You can instruct ODSL to ignore missing values using the statement:

set missing ignore

Or you can tell ODSL to use a specific value to replace missing values, e.g. if you are summing up a list of values, you can set missing as 0 so that it would not take them into account.

Setting the coordinate reference system (CRS)​

You can set the CRS to either:

  • earth
  • planar

This affects the way geospatial data is handled

Timeseries scaling methods​

There are 3 set commands which allow you to define how timeseries are scaled:

  • autoscale on|off

    By default, all timeseries are autoscaled once they reach a certain threshold in terms of number of observations. You can turn this off using the following command:

set autoscale off

See this page for more information on autoscaling.

  • observed (default|beginning|end|averaged|summed|high|low|delta)

    This defines how numbers are aggregated when a timeseries is scaled from high frequency e.g. hourly to a lower frequency e.g. daily

    See this page for more information on the observed setting.

  • distribution (none|constant|linear|cubic)

    This defines how numbers are distributed when a timeseries is scaled from low frequency e.g. daily to a higher frequency e.g. hourly

    See this page for more information on the distribution setting.

Credentials​

If you need to define personal credentials to an external system that the OpenDataDSL platform interacts with you use the set credentials command. This securely stores the credentials in an Azure Vault and only uses them when needed to interact with the external system.

Automatically follow references​

This command enables or disables automatically retrieving the underlying data from a referenced entity.

For example, if we take the master data record #ABN_FX.EURAED, it has a SPOT reference to the SPOT timeseries data. In the following example (the default), the information output is the actual timeseries data.

set auto_follow_references true

o = ${object:"#ABN_FX.EURAED"}
print o.SPOT

In this example, the information output is the information about the reference link

set auto_follow_references false

o = ${object:"#ABN_FX.EURAED"}
print o.SPOT

While loop iteration limit​

While loops can iterate infinitely causing performance issues, so we have an artificial limit on while loops of 1000 iterations.

If this limit is reached, a 6036 While loop iteration exception is thrown.

You can override the 1000 iterations limit using the set while_limit command, e.g.

set while_limit 100

trigger​

Used to manually trigger a subscription

Syntax​

trigger name for date

Description​

The trigger command is used to manually trigger a subscription. Subscriptions are usually triggered by an a new data event, but you can also manually trigger a subscription for a specific date using this command.

Example​

// Trigger the subscription called test for the 11th June 2021
trigger test for 2021-06-11

use​

Instructs OpenDataDSL to use a specific named environment

Syntax​

use environmentname

Description​

You can create multiple environments such as dev and test which are separate from your production environment, this command instructs OpenDataDSL that from this point it should use that named environment for the rest of the running script.

NOTE: For more information on environments - see here

Example​

If you have created an environment called test, you can use it with the following command:

use test