Preface

This document describes the functionality provided by the Trigger Plugin.

Refer to the Deployit Reference Manual for background information on Deployit and deployment concepts.

Overview

When Deployit resolves a deployment plan, a task comprising of multiple steps is created and subsequently executed. The task, along with the steps, transition throught various states before finally completing. The Trigger Plugin allows a user to associate actions, example sending an email, to be triggered for one of these state transitions.

Features

• Ability to send emails for state transitions of Steps or Task.

Requirements

This plugin requires:

• Deployit: version 3.8+

Actions

The following Deployit objects are available to actions :

• deployedApplication: The entire deployed application containing application and environment configuration items. See UDM Ci reference.
• task: Contains information about the task. The following properties are available,
  • id
  • state
  • description
  • startDate
  • completionDate
  • nrSteps : number of steps in the task.
  • currentStepNr : the current step been executed.
  • failureCount : number of times the task has failed
  • owner
  • steps : List of steps in the task. Not available when action triggered from StepTrigger. See step information below for properties.

• step: Contains information about a step. Not available when action triggered from TaskTrigger. The following properties are available,

  • description
  • state
  • log
  • startDate
  • completionDate
  • failureCount

• action: Reference to the executing action.

Emai Action

First, you will need to define an SMTPServer under the Infrastructure root.

mailServer = factory.configurationItem("Infrastructure/MailServer","mail.SMTPServer")
mailServer.host = "smtp.mycompany.com"
mailServer.username = "mymailuser"
mailServer.password = "secret"
mailServer.fromAddress="noreply@mycompany.com"
repositort.create(mailServer)

The SMTPServer uses Java Mail to send emails. You can specify additional Java Mail properties in the smtpProperties attribute. Refer to http://javamail.kenai.com/nonav/javadocs/com/sun/mail/smtp/package-summary.html for a list of all properties.

The EmailNotification captures the email details that will be sent.

Under the Configuration root, define an EmailNotification configuration item.

myEmailAction = factory.configurationItem("Configuration/MyFailedDeploymentNotification", "trigger.EmailNotification")
myEmailAction.mailServer = "Infrastructure/MailServer"
myEmailAction.subject("Application ${deployedApplication.version.application.name} failed.")
myEmailAction.toAddresses = ["support@mycompany.com"]
myEmailAction.body = "Deployment of ${deployedApplication.version.application.name} was cancelled on environment $  {deployedApplicaiton.environment.name}"
repository.create(myEmailAction)

The subject, toAddresses, fromAddress, body properties can contain FreeMarker template scripting that can access the Deployit objects described above.

If prefered, the definition of the email body can be defined in an external template file. The path to the file can be set in the bodyTemplatePath property. This can either be an absolute path, or a relative path that will be resolved via Deployit's classpath.

State Transitions

When an environment has triggers defined in its triggers property, the Trigger plugin listens to state transitions in tasks and steps that occur during a deployment. When the state transition described by the trigger matches, the associated actions are executed. Currently the plugin has an email action.

Task state transitions

A TaskTrigger can be defined under the Configuration root and associated with the environment on which it should be triggered.

taskTrigger = factory.configurationItem("Infrastructure/TriggerOnCancel","trigger.TaskTrigger")
taskTrigger.fromState = "ANY"
taskTrigger.toState = "CANCELLED"
taskTrigger.actions = [myEmailAction]
repository.create(taskTrigger)

env = repository.read("Environments/Dev")
env.triggers = ["Configuration/TriggerOnCancel"]
repository.update(env)

Step state transitions

A StepTrigger can be defined under the Configuration root and associated with the environment on which it should be triggered.

stepTrigger = factory.configurationItem("Infrastructure/TriggerOnFailure","trigger.StepTrigger")
stepTrigger.fromState = "EXECUTING"
stepTrigger.toState = "FAILED"
stepTrigger.actions = [myEmailAction]
repository.create(stepTrigger)

env = repository.read("Environments/Dev")
env.triggers = ["Configuration/TriggerOnFailure"]
repository.update(env)