Trigger plugin

This topic details the Trigger plugin in Deploy, enabling configuration for email notifications based on specific events such as step failures or successful deployment completions.

Actions

With the trigger plugin, you can define notification actions for certain events. These Deploy objects are available to the actions:

• Deployed applications
• Tasks
• Steps
• The action object itself

Deployed applications

The entire deployed application (udm.DeployedApplication), containing application and environment configuration items, is available to the actions.

Task object

The task object contains information about the task. The following properties are available:

• id
• state
• description
• startDate
• completionDate
• nrSteps: The number of steps in the task
• currentStepNr: The current step been executed
• failureCount: The number of times the task has failed
• owner
• steps: The list of steps in the task. Not available when action triggered from StepTrigger.

Step object

The step object contains information about a step. It is not available when the action is triggered from TaskTrigger. The following properties are available:

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

Action object

The action object is a reference to the executing action itself.

Email action triggers

This section describes how to configure an email action.

Note: This procedure assumes you have already defined a #mail.SmtpServer CI under the Configuration root.

The trigger.EmailNotification CI is used to define the message template for the emails that will be sent. Under the Configuration root, define a trigger.EmailNotification configuration item. For example, using the CLI you can configure an action similar to the following:

myEmailAction = factory.configurationItem("Configuration/MyFailedDeploymentNotification", "trigger.EmailNotification")
myEmailAction.mailServer = "Configuration/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 ${deployedApplication.environment.name}"
repository.create(myEmailAction)

In this example:

• The subject, toAddresses, fromAddress, body properties accept FreeMarker template syntax and can access the following Deploy objects:

  • ${deployedApplication}
  • ${task}
  • ${step}

• The ${deployedApplication.version.application.name} refers to the name of the application being deployed.

You can also define the email body in an external template file and set the path to the file in the bodyTemplatePath property. This can be either an absolute path, or a relative path that will be resolved via Deploy's classpath. By specifying a relative path, Deploy will look in the ext directory of the Deploy Server and in all (packaged) plugin jar files.

State transition triggers

To enable a state-based trigger for deployments, add it to the triggers property of an environment. The trigger will then monitor 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.

Deploy ships with the EmailNotification trigger. Custom trigger actions can be written in Java.

Task state transitions

You can derive the task state transitions from the task state diagram in Understanding tasks in Deploy. The "any" state is a wildcard state that matches any state.

You can define a trigger.TaskTrigger under the Configuration root and associate it with the environment on which it should be triggered.

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

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

Step state transitions

You can derive the step state transitions from the step state diagram in Steps and step lists in Deploy. The "any" state is a wildcard state that matches any state.

You can define a trigger.StepTrigger under the Configuration root and associate it with the environment on which it should be triggered.

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

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