Rulebook API

This is the base reference of the available rulebook ops in your system.

This documentation is dynamic and may change according to the plugins installed.


call

Call another rulebook

Allowed parametersdata, file
Required parametersfile
Accepts single value

change_status

Change topic status

Allowed parametersfrom, mid, to
Required parametersmid, to

Examples:

Example 1
'change_status ':
  mid: 1234
  to: Review
Example 2
'change_status ':
  mid:
  - 123
  - 456
  to: Review
Example 3
'change_status ':
  from:
  - To Do
  - In Progress
  mid: 1234
  to: Review

create_topic

Create a new topic

Allowed parameterscategory, data, status, title
Required parameterscategory, status, title

Examples:

Example 1
'mid = create_topic ':
  category: Feature
  data:
    description: Just a short description
  status: To Do
  title: My topic title

do

Run rule ops or ClaJS code

Accepts single value

Examples:

Example 1
do: ' var x = 100; print( x ); '
Example 2
do:
- echo: This is a rulebook op too
- if: '{{ myvar == "foo" }}'
  then:
  - echo: it's foo

dump

Dumps a data structure to a variable or file

Allowed parametersdata, encoding, file, format, options, returning
Defaultsreturn_body → 1
Required parametersdata, file|returning, format

Examples:

Example 1
dump:
  data:
    bar:
    - joe
    - moe
    - doe
    foo: 100
  file: /tmp/myfile
  format: yaml
Example 2
do:
- dump:
    data:
      bar:
      - joe
      - moe
      - doe
      foo: 100
    format: xml
    returning: myvar
- echo: 'heres the xml as a string: ${myvar}'

echo

Prints a string with a new line

Allowed parametersmsg, stream
Required parametersmsg
Accepts single value

Examples:

Example 1
echo: hello world
Example 2
echo:
  msg: hello there my error
  stream: stderr

email

Send an email

Allowed parametersattachment, attachment_filename, body, cc, subject, template, template_engine, to
Required parametersbody, subject

Examples:

Example 1
email:
  body: |-
    multiline message
    with html accepted
  cc:
  - email2@example.com
  subject: test email
  to:
  - email@example.com
  - username1
Example 2
email:
  attachment: "here are the\nfile contents\n"
  attachment_filename: myattachment.txt
  body: hello world of attachments
  subject: test with attachments
  to:
  - username1

export_vars

Imports var from global stash

Required parametersvar
Accepts single value

fail

Throws an error and dies

Accepts single value

fetch

fetch a file remotely

Required parametersfrom, host, to

field_combo

Combo Fieldlet

Allowed parameterscolspan, default, edit, id, label, options, readonly, required, rowspan, view
Required parametersid, label, options

Examples:

Example 1
field_combo:
  label: Select From List
  options:
  - option1
  - options2

field_date

Date Fieldlet

Allowed parameterscolspan, default, edit, id, label, readonly, required, rowspan, view
Required parametersid, label

Examples:

Example 1
field_date:
  label: Enter Date

field_grid

Combo Fieldlet

Allowed parameterscolspan, columns, default, edit, id, label, readonly, required, rowspan, view
Required parameterscolumns, id, label

Examples:

Example 1
field_grid:
  columns:
  - Task
  - Description
  label: Select From List
Example 2
field_grid:
  columns:
  - Task
  - name: User
    type: users
  - name: Expected Date
    type: date
  label: Assign Tasks To Users

field_pills

Pills Fieldlet

Allowed parameterscolspan, default, edit, id, label, options, readonly, required, rowspan, view
Required parametersid, label, options

Examples:

Example 1
field_pills:
  default: Low
  label: Priority
  options:
  - color: red
    name: High
  - color: green
    name: Low

field_richtext

Richtext (HTML) Editor Fieldlet

Allowed parameterscolspan, default, edit, id, label, readonly, required, rowspan, view
Required parametersid, label

Examples:

Example 1
field_richtext:
  label: Long Description
  rowspan: 6

field_text

Text Fieldlet

Allowed parameterscolspan, default, edit, id, label, readonly, required, rowspan, view
Required parametersid, label

Examples:

Example 1
field_text:
  default: '0'
  id: my_value
  label: Enter Value

field_textarea

Textarea Fieldlet

Allowed parameterscolspan, default, edit, id, label, readonly, required, rowspan, view
Required parametersid, label

Examples:

Example 1
field_textarea:
  default: '0'
  id: my_value
  label: Enter Value

field_time

Time Fieldlet

Allowed parameterscolspan, default, edit, id, label, readonly, required, rowspan, view
Required parametersid, label

Examples:

Example 1
field_time:
  label: Enter Time

field_upload

Upload Fieldlet

Allowed parameterscolspan, default, edit, id, label, readonly, required, rowspan, view
Required parametersid, label

Examples:

Example 1
field_upload:
  label: Attach Documents

foreach

Loop thorugh the elements of an array or hash

Allowed parametersin, var
Nested ops?do
Nested as hashin
Required parametersin
Accepts single value

Examples:

Example 1
data:
  foreach:
    do:
    - print: ${myvar}
    in: '[1,2,3]'
    var: myvar

if

If condition Then or Else...

Nested as hashcond
Required parameterscond, then

image

Set a Docker image to run commands from

Allowed parametersdo, environment, name, repository, runner, tag, user
Required parametersname|repository
Accepts single value

import_vars

Imports var from global stash

Required parametersvar
Accepts single value

literal

This is a no-op unless assigned to an inline variable

Accepts single value

Examples:

Example 1
foo =: my value

log

Log a message

Allowed parametersbody, dump, file, filename, level, link, msg
Accepts single value

Examples:

Example 1
data:
  log:
    level: debug
    msg: short debug message
Example 2
data:
  log:
    data: "lines\nof\ndata"
    level: info
    msg: a info message with data

parse

Parses a string or file

Allowed parametersbody, encoding, file, format, options, returning
Defaultsfail_if_not_found → 1
Required parametersfile^body, format|file

print

Prints a string

Required parametersmsg
Accepts single value

Examples:

Example 1
print: hello world
Example 2
print:
  msg: hello there my error
  stream: stderr

publish

Publish files in the artifacts repository

Allowed parametersfrom, repository, to
Required parametersfrom, repository, to

Examples:

Example 1
publish:
  from: /path/to/myreport.html
  repository: repository_name
  to: /path/to/file_report.html

readonly_fields

Disables Fieldlets by Name or Id

Allowed parametersfields
Accepts single value

Examples:

Example 1
readonly_fields:
- some_id
- Some Label

remove_fields

Removes Fieldlets by Name or Id

Allowed parametersfields
Accepts single value

Examples:

Example 1
remove_fields:
- some_id
- Some Label

request

HTTP(s) request agent

Allowed parametersargs, body, encoding, headers, insecure, method, returning, timeout, url
Required parametersurl

Examples:

Example 1
do:
- res = request:
    method: POST
    url: http://jsonplaceholder.typicode.com/posts
- echo: this is the content ${res.content}

return

Return from rulebook declared ops

Accepts single value

sed

Replace variables in files

Allowed parametersexcludes, includes, output, path, patterns, slurp, suffix
Required parameterspath

Examples:

Example 1
sed:
  path: mydir/mypath
Example 2
sed:
  includes:
  - txt$
  path: mydir/mypath
Example 3
sed:
  excludes:
  - .exe$
  path: mydir/mypath

set

Sets a variable to a value

Required parametersvalue, var

Examples:

Example 1
set:
  value: myvalue
  var: myvar
Example 2
set:
  value:
  - 1
  - 2
  - ${myvar}
  var: myvar2

shell

Runs a command locally or remotely

Allowed parametersargs, cmd, host, image, pipe_in, pipe_out, pipe_stderr, pipe_stdout
Required parameterscmd
Accepts single value

ship

Sends a local file to a remote node

Allowed parametersanchor_path, chunk_size, exclude, from, host, include, mode, to
Defaultsrel_path → rel_path_job
mode → preserve
recursive → 1
backup_mode → none
rollback_mode → none
Required parametersfrom, host, to

tar

Tar Local Files

Allowed parametersattributes, base, exclude, files, from, include, time, to, verbose
Defaultsbase → /
Required parametersfrom, to

try

Try - Catch

Nested as hashdo
Required parametersdo
Accepts single value

update_topic

Update a topic

Allowed parametersdata, mid
Required parametersmid

Examples:

Example 1
'update_topic ':
  data:
    description: Changing the description
    title: Changing the title
  mid: '12345'

var

Sets a variable to a value

Examples:

Example 1
var:
  myvar: myvalue
Example 2
var:
  myvar2:
  - 1
  - 2
  - ${myvar}

web_request

Data transfer to and from an URL

Allowed parametersargs, body, encoding, headers, insecure, method, returning, timeout, url
Required parametersurl

Examples:

Example 1
do:
- web_request:
    method: POST
    returning: response
    url: http://jsonplaceholder.typicode.com/posts
- echo: this is the content ${response.content}

web_response

Build response to webservice rule

Examples:

Example 1
web_response:
  baz: quux
  foo: bar

while

Loop while argument true

Allowed parameterscond
Nested ops?do
Nested as hashcond
Required parameterscond

Examples:

Example 1
data:
  do:
  - print: ${myvar}
  while: '{{ value != "done" }}'

write_file

Write a local or remote file

Allowed parametersbody, body_encoding, file, file_encoding, host
Required parametersfile

Examples:

Example 1
write_file:
  body: "hello\nworld"
  file: /tmp/myfile
Example 2
write_file:
  body: "hello\n∫a∫∫y utf-8"
  file: /tmp/myfile
  file_encoding: UTF-8

zip

Zip files into an archive

Allowed parametersbase, from, time, to
Defaultsbase → /
Required parametersfrom, to

Examples:

Example 1
zip:
  base: /
  from: /tmp/zzz/
  to: /tmp/rr.zip