Context Data

Rules mostly execute within a context, such as webhooks, topic events or pipelines.

To use the data that triggered the context, there's a ClaJS namespace called ctx that is always available to rulebooks.

Context Function	Context	Data Type	Contents
ctx.category()	any topic event	Object	Category information
ctx.fields()	topic_modify	Array	List of changed fields, with old and new value
ctx.job()	pipelines	Object	Job information
ctx.env()	pipelines	String	Current job environment
ctx.branch()	pipelines	String	Name of the branch checked out for the job
ctx.request()	webhook	Request	Web request parameters
ctx.status()	any topic event	Object	Status information
ctx.topic()	any topic event	Object	Topic information
ctx.user()	(any)	String	User id

undefined when not in context

When not in context, all context functions will return undefined and emit a warning to stderr [warn] X not in context.

Make sure to check the return value or use ctx.has() before proceeding under the assumption that the return value is a hash {}

Usage

Context calls are useful to the detail of the event the rule is processing:

topic_modify:
   - echo: "Topic modify event for {{ ctx.topic("name") }}"
   - echo: |
        These fields have changed: {{ ctx.fields().map( function(field){ return field.field } ) }}"

Context Objects

These are the context objects available in Clarive.

Remember, if you are not in the correct context, they will return undefined instead of a hash Object. Use ctx.has() to check the context, otherwise strange side effects may happen.

ctx.var(varname)

Return variable values for the current context scope and input varname.

Depending on the scope, the variable value (if available) will change.

deploy:
   - instance_id =: "{{ ctx.var("aws_instance_id") }}"
   - image: docker4x/shell-aws
   - aws ec2 start-instances --instance-ids ${instance_id}

   # or in one go:

   - aws ec2 start-instances --instance-ids {{ ctx.var("instance_id") }}

ctx.topic()

This is the hash returned by the ctx.topic() ClaJS function. The hash has the following keys:

Key	Context
ctx.topic("mid")	topic id
ctx.topic("title")	status name string
ctx.topic("status")	status name string
ctx.topic("category")	category name string
[category dependent fields]	additional fields, depending on the category

do: |
   print( "Topic ID=" + ctx.topic("mid") );
   print( "Topic Title=" + ctx.topic("title") );
   print( "Status name=" + ctx.topic("status") );      # "To Do", "In Progress", etc.
   print( "Category name=" + ctx.topic("category") );  # "Bugfix", "Feature", etc.

Head over to the document on event rules for more info.

ctx.fields()

The ctx.fields() context function returns a list (array) of modified fields in the topic_modify event.

Here's a list of fields available:

Key	Type	Description
field	string	Field name (ie. "title", "description", etc)
old_value	(variable)	Field value before change. Type depends on field.
new_value	string	Field value after change. Type depends on field.

ctx.job()

Here's a description of the hash returned by the ctx.job() function:

Key	Type	Description
ctx.job("project")	String	Current project being processed, if any
ctx.job("repository")	String	Current repository name being processed, if any
ctx.job("change_version")	String	Version number from the Release topic, etc.
ctx.job("environment")	String	Current deployment environment (DEV, QA, PROD...)
ctx.job("env")	String	Same as environment above
ctx.job("items")	Array	List of job items
ctx.job("name")	String	Job name (as shown in the Monitor)
ctx.job("type")	String	static, promote or demote
ctx.job("user")	String	User that created job
ctx.job("mode")	String	forward or rollback
ctx.job("step")	String	current job step: CHECK, INIT, PRE, RUN, POST
ctx.job("status_from")	String	Current project being processed, if any
ctx.job("status_to")	String	Version id from the Release topic, etc.
ctx.job("is_rollback")	String	Current deployment environment (DEV, QA,
ctx.job("failing")	Boolean	In the post: pipeline rule, set to 1 if previous steps failed

ctx.request()

The web request context is only available in webhook url call events.

Key	Type	Contents
ctx.request('params')	String	The URL query-string or form params in a hash
ctx.request('args')	String	Array with each of the /path components of the URL
ctx.request('body')	String	The full request body as a string
ctx.request('headers')	Object	HTTP request headers
ctx.request('upload')	String	Uploaded files
ctx.user()	String	The user id who made the (authenticated) request

Checking if context is available

If the context is not available, trying to use the ctx context functions will generate an error such as:

context `CONTEXT_NAME` is not available

To check before using a function, use the ctx.has('context_name') function, which returns true or false depending on the context.

This is specially useful for ops defined with def:. That way one can check if the op is in the correct context or not.

def:
   reset_topic_title:
      - if: "{{ ctx.has('topic') }}"
        then:
          - update_topic:
                mid: ${mid}
                data:
                   title: "The new title is this now"
        else:
          - fail: "No topic available in context"

This is the list of arguments one can test the context with ctx.has():

• topic
• status
• category
• job
• fields
• request
• user