Difference between revisions of "Mistral/Blueprints/ActionsDesign"
| Line 14: | Line 14: | ||
Mistral action can be synchronous and asynchronous. Synchronous actions act as a regular Python method: when it's called it returns a result upon completion so a caller can immediately use this result. Asynchronous actions don't return a result immediately but rather "launch" an independent activity (e.g. sending a request to an external system to do the heavy job) and when it completes a result becomes know to Mistral. | Mistral action can be synchronous and asynchronous. Synchronous actions act as a regular Python method: when it's called it returns a result upon completion so a caller can immediately use this result. Asynchronous actions don't return a result immediately but rather "launch" an independent activity (e.g. sending a request to an external system to do the heavy job) and when it completes a result becomes know to Mistral. | ||
| − | + | class Action(object): | |
@abc.abstractmethod | @abc.abstractmethod | ||
def run(): | def run(): | ||
pass | pass | ||
| − | + | ||
def is_sync(): | def is_sync(): | ||
return False | return False | ||
| Line 34: | Line 34: | ||
==== Errors ==== | ==== Errors ==== | ||
| − | During action work various errors may occur. To notify action callers action | + | During action work various errors may occur. To notify action callers action must throw ActionException. In this case corresponding task state will be set to ERROR. |
def run(): | def run(): | ||
| Line 41: | Line 41: | ||
... | ... | ||
| − | ==== | + | ==== Dry-Run ==== |
| + | Actions may optionally implement dry_run() method so that a user can test their workflows in 'dry-run' mode, the mode in which every action doesn't perform a real work but instead emulates useful behaviour. | ||
| − | + | def dry_run(): | |
| + | LOG.info("Running action in dry-run mode [parameters=%s]" % self.parameters) | ||
| + | |||
| + | return 'my_result' | ||
==== Input ==== | ==== Input ==== | ||
| + | |||
==== Namespaces ==== | ==== Namespaces ==== | ||
Revision as of 05:35, 12 March 2014
Contents
Mistral Actions
NOT FINISHED
This BP describes the main requirements to how actions should be designed in Mistral in order to address flexibility and clarity of their usage.
From implementation perspective we'll be referring to python class Action that represents Mistral action:
class Action(object):
@abc.abstractmethod
def run():
pass
Method run() here implements action logic (issuing SSH command, sending a message over MQ etc.). All specific action classes must extend class Action and implement abstract method run().
Synchronous/Asynchronous
Mistral action can be synchronous and asynchronous. Synchronous actions act as a regular Python method: when it's called it returns a result upon completion so a caller can immediately use this result. Asynchronous actions don't return a result immediately but rather "launch" an independent activity (e.g. sending a request to an external system to do the heavy job) and when it completes a result becomes know to Mistral.
class Action(object):
@abc.abstractmethod
def run():
pass
def is_sync():
return False
Depending on action implementation and its properties method is_sync() returns True or False. This part of Action contract is required because a caller subsystem must know how to handle action result.
Result
The notion of 'result' only makes sense for synchronous type of actions since in case of asynchronous action a result gets delivered (conveyed directly via Mistral public API).
Asynchronous Actions
Method run() always returns None.
Synchronous Actions
Method run() returns action result. In cases when action is based on using some protocols like HTTP action implementation itself is responsible for converting protocol specific result to a form meaningful for a particular workflow. So, for example, HTTP response that action receives during its work typically can't be treated as action result since a user may be interested only in part of information residing in the response.
Errors
During action work various errors may occur. To notify action callers action must throw ActionException. In this case corresponding task state will be set to ERROR.
def run():
...
raise ActionException("Failed to send an SSH command. %s" % cause)
...
Dry-Run
Actions may optionally implement dry_run() method so that a user can test their workflows in 'dry-run' mode, the mode in which every action doesn't perform a real work but instead emulates useful behaviour.
def dry_run():
LOG.info("Running action in dry-run mode [parameters=%s]" % self.parameters)
return 'my_result'
