Actions

An action, as used in a Job Action or a Command Action, is an instruction to CX Vizz to do something. There are three types of Action:

  • System Actions
  • Task Actions
  • Database Actions

An action can consist of one or more calls. For example:

queues()

This will download all queues

users()
groups()

This will download all users and groups

set(startdate = savepoint('mysavepoint'))
conversations(start_date = startdate)
setsavepoint('mysavepoint', conversations_end_date)

System Actions

The following System Actions are defined:

set(varname = value)

This sets the variable varname to the specified value.
The value may be any expression

print( expression )

This evaluates the expression and prints it to the log file.

printVars()

This prints all variables to the log files.

setsavepoint( name='savepointname', value='2024-01-01')

This sets a savepoint

Database Actions

Any stored procedure can also be called as an action. See standard stored procedures for examples.

Examples of Actions

You can perform calculations, prior to calling a stored procedure. For example:

conversations_from_datalake()
my_stored_procedure_to_calculate_interval_statistics( 
    start    = round_date( conversations_start_date, 15 minutes ),
    end      = round_date( conversations_end_date, 15 minutes) + 15 minutes, 
    interval = 15 minutes)

Expressions

Expressions are what you would expect. There are operations for additional, subtraction, multiplication and division:

  • a + b
  • a * b
  • a - c
  • a / c

Strings

Strings are constants in "double quotes" or 'single quotes'.

Integers

Integers are constant numbers

Time intervals

Time intervals are written an integer followed by a special keyword that denotes an interval - one of minute or minutes, hour or hours, day or days:

Examples of intervals

  • 1 minute
  • 15 minutes
  • 1 hour
  • 12 hours
  • 1 day
  • 30 days

Note that there is no signicant difference between "1 hours and 1 hour" - the plural is allowed for ease of use.

Dates and Date/Times

A Date is a string of the format 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS'. If the Hours, minutes and seconds are not present, then this represents midnight on the specified date.

Functions

Expressions can call functions, these are of the form function( expression1, expression2, expression3)

The following functions can be called:

  • now() provides the current Date/Time in UTC
  • year( date ) - provides the year of the date/time passed. For example, year( now() ) would return the current year. year( '2021-12-04' ) would return 2021.
  • month( date ) - provides the month of the date/time passed. For example, month(now() ) would return the current month. month( '2021-12-4' ) would return 12 (December).
  • config ( 'START_DATE' ) - provides the configuration string for 'START_DATE'. See configuration for more details.
  • round_date( datetime, interval ) - returns the provided date/time, rounded down to the nearest interval. For example, `round_date( '2024-10-12 19:26:57', 15 minutes) would return the date/time '2024-10-12 19:15:00'.
  • savepoint( name ) - returns the date/time from the savepoint specified.

Variables

Variables are set by some actions, and can be referenced, and they can also be set using the set() system action.

For example, the conversations_from_datalake() action sets two veriables, conversation_start_date and conversation_end_date. These can be passed to further actions in order to process these actions.

Type compatiblity

If two variables or expressions with incompatible types are operated on (addition, subtraction etc.) then an error will occur.

Operator Lhs Rhs Result
+ integer integer integer
+ string string string
+ datetime time interval datetime
+ time interval time interval time interval
- integer integer integer
- datetime time interval datetime
- time interval time interval time interval
* integer integer integer
/ integer integer integer

Savepoints

In orer to keep track of what data has already been downloaded, CX Vizz maintains a list of Savepoints. A savepoint is a record of the last successfully downloaded piece of data for an entity.

erDiagram
    SAVEPOINTS {
        varchar tablename PK
        datetime savepoint
        datetime db_last_updated
    }

For example, if the table contained the following

tablename savepoint db_last_updated
conversations 2024-05-05 05:00:53 2024-10-12 19:27:00

Then we could conclude that the most recent conversations we have in our database are from 5th May 2024, and that the data was last downloaded on 12 October.

Various Actions automatically set their savepoints, and you can also retrieve and set savepoints using System Actions.

Stored Procedures

CX Vizz can call stored procedures in exactly the same way as actions are carried out.

This is how aggregations are performed. For example, the following action will aggregate queue stats and users stats after
downloading conversations from the datalake:

conversations_from_datalake() aggregate_queue_stats(start_date = conversations_start_date, end_date = conversations_end_date) aggregate_user_stats(start_date = conversations_start_date, end_date = conversations_end_date)

There are a number of system stored procedures that are included with CX Vizz, but you can define their own and call them from their own pipeline, to (for example) create customised aggregations.