Event '<action name>-action'

Event > List of events > <action name>-action

See also: How to handle charm actions
Source: ops.charm.ActionEvent

This document describes the <action name>-action event. Actions are methods of a charm designed to be directly called by the cloud administrator when the charm is deployed, in contrast with events, which are fired by juju and allow the charm to automatically respond to changing circumstances.

An action can have “parameters” (passed by the cloud admin to the charm) and “results” (passed by the charm back to the cloud admin, once the handler returns).

Note: If hyphens are used in action names, they are replaced with underscores in the corresponding event names. For example, an action named snapshot-database would result in an event named snapshot_database_action being triggered when the action is invoked.

Contents:

• Emission sequence
• Observing this event in Ops

Emission sequence

The <action name>-action event will trigger after a user invokes the action-name from the Juju CLI. It can be emmited to a single unit:

Or to several units of a same application:

Note that the action handler in the charm can in principle cause other events to be fired. For example:

• Deferred events will trigger before the action.
• If the action handler updates relation data, a <relation name>_relation_changed will be emitted afterwards on the affected units.

Observing this event in Ops

You can subscribe to the event:

self.framework.observe(
    charm.on.<action name>_action, 
    self.<action name>_action
)

Actions are surfaced as events that a charm can observe, similarly to lifecycle events. Action names are parsed by the Charmed Operator Framework and surfaced as events named <action_name>_action.

Action handlers are passed an ActionEvent as their first parameter, and thus have access to the action parameter values through the <event>.params construct. In addition to the params dict, the ActionEvent class provides three convenience methods to the developer:

• <event>.fail(message=""): Report to the administrator that the action has failed, optionally providing a message indicating why the failure occured.
• <event>.log(message): Log a message for the administrator (available while the action is running).
• <event>.set_results(results): Report the result of the action, where results is a dictionary. The maximum size must be under the maximum size allowed by the OS for arguments (typically around 100KB).

def do_something_action(self, event):
	"""Handle *do-something* action."""
	result_dict = _my_results_getter()
	event.set_results(result_dict)