.. _workbook-messaging:

==================
Messaging Workbook
==================

:Workbook name: tripleo.messaging.v1

TripleO Zaqar Workflows

Workflows in the Messaging Workbook

.. object:: tripleo.messaging.v1.send

   Send a message to a Zaqar queue and optionally persist it to Swift
   This workflow sends a standard message to Zaqar (taking care of the error handling and retry logic) and optionally persists the message to Swift. The output of the workflow directly matches the input, this means it can be used to send a message and set the output of the parent calling workflow.
   If plan_name is provided the message will be persisted to Swift. In a container named "{plan_name}-messages". The swift objects will be named:
   
       {TYPE}/{TIMESTAMP}.yaml
   
   If a deployment_status is provided, the top-level deployment_status.yaml will also be updated, which will contain the deployment_status and the related message.
   The standard message format will be::
   
       body: {
         type: 'tripleo.workflow.name', # Matches the workflow name
         payload: {
           status: 'STATUS', # One of RUNNING, SUCCESS, FAILED
           root_execution_id: 'UUID of the root execution',
           execution_id: 'UUID',
           message: "Human readable description",
           < Arbitrary data. This should match the workflow output data >
         }
       }
   
   Workflow Input:
     queue_name - The Zaqar queue name to post to.
     type - The message type, this should match the calling workflows name
     execution - Details about the workflow execution. Should be passed by using <% execution() %>
     status - Optional. The status of the message. SUCCESS/RUNNING/FAILED.
     message - Optional. A human readable message to be included
     payload - Optional. A dictionary output data to be sent in the message.
     plan_name - Optional. The deployment plan name. This is used for the swift messages container.
     deployment_status - Optional. If set the top-level deployment_status.yaml will be updated.

   Workflow inputs:

   :input queue_name: Required.
   :input type: Required.
   :input execution: Required.
   :input {'status': 'SUCCESS'}: Required.
   :input {'message': None}: Required.
   :input {'payload': {}}: Required.
   :input {'plan_name': None}: Required.
   :input {'deployment_status': None}: Required.
