Email Notifier Management

createEmailNotifier

Creates an email notifier attached to the specified object, such as a job, job step, project, procedure, application process or process step, or a workflow.

You must specify a notifierName and object locators for a job, job step, procedure, or procedure step.

Arguments Descriptions

notifierName

The name of the email notifier.

Argument type: String

applicationName

(Optional) The name of the application that is related to the target email container. The email notifier is attached to an application process or process step.

Argument type: String

componentName

(Optional) The name of the component that is related to the target email container. The email notifier is attached to the component.

Argument type: String

condition

(Optional) Only send mail if the condition evaluates to "true". The condition is a string subject to property expansion. The notification will not be sent if the expanded string is "false" or "0". If no condition is specified, the notification is always sent.

Argument type: String

configName

(Optional) If specified, this argument must be the name of an emailConfig object. If it is not specified, the default is the name of the first emailConfig object defined for the CloudBees CD/RO server ( emailConfig objects are "ordered" CloudBees CD/RO entities).

When using this argument, you must also include the formattingTemplate or the formattingTemplateFile argument .

Argument type: String

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>

Argument type: String

destinations

(Optional) A mandatory argument for a create operation. A space-separated list of valid email addresses, email aliases, or CloudBees CD/RO user names, or a string subject to property expansion that expands into such a list.

Argument type: String

environmentNames

(Optional) The environment names.

Argument type: Collection

eventType

(Optional) Use one of these values: < onStart|onCompletion >.

onStart –Triggers an event when the job or job step begins.
onCompletion –Triggers an event when the job ends, regardless of the results.

The default is onCompletion.

Argument type: EventType

flowName

(Optional) The name of the flow.

Argument type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

formattingTemplate

(Optional) A template for formatting email messages when an event [notification] is triggered by the emailNotifier. Make sure the content is formatted correctly, such as no illegal characters or spacing.

Argument type: String

formattingTemplateFile

(Optional) Contents of the formatting template file is read and stored in the "formatting template" field. This is an alternative argument for --formattingTemplate and is useful if the "formatting template" field spans multiple lines.

This option is supported only in Perl and ectool bindings—it is not part of the XML protocol.

gateType

(Optional) The type of the gate.

Argument type: GateType

groupNames

(Optional) A list of groups that receive the notification.

Argument type: Collection

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

(Optional) The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: UUID

notificationType

(Optional) The notification type that is stored to the ec_notificationType property.

Argument type: NotificationType

pipelineName

(Optional) The name of the pipeline when a credential attached to a stage task.

procedureName

(Optional) The name of the procedure. When using this argument, you must also enter the projectName.

Argument type: String

processName

(Optional) The name of the process that contains of the email notifier.

Argument type: String

processStepName

(Optional) The name of the process step that contains of the email notifier.

Argument type: String

projectName

(Optional) The name of the project. When using this argument, you must also enter the procedureName.

Argument type: String

releaseName

The name of the release containing the pipeline.

serviceName

The name of the service which is related to the target email container (Process/ProcessStep).

stageName

(Optional) The name of the stage.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stateName

(Optional) The name of the state.

Argument type: String

stepName

(Optional) The name of the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

userNames

(Optional) The names of the users who receive the notification.

Argument type: Collection

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

Positional arguments

notifierName

Response

Returns an emailNotifier element.

ec-perl

syntax: $cmdr->createEmailNotifier(<notifierName>, {<optionals>});

Example

$cmdr->createEmailNotifier("testNotifier",
        {eventType => "onStart",
         condition => "$[/javascript if(myJobStep.outcome == 'warning') 'true'; else 'false';]",
      destinations => 'user1@abc.com user2@abc.com emailAlias1@example.com',
        configName => "testConfiguration",
       projectName => "Project_test",
     procedureName => "Procedure_test",
formattingTemplate => "Subject: Job started Notification: Job: $[/myJob/jobName] $[/myEvent/type]
  Job: $[/myJob/jobName] $[/myEvent/type] at $[/myEvent/time]",});▼

ectool

syntax: ectool createEmailNotifier <notifierName> [optionals]

Example

ectool createEmailNotifier testNotifier --condition "$[/javascript if(myJobStep.outcome
== 'warning') 'true'; else 'false';]"
    --destinations "user1@abc.com user2@abc.com emailAlias1@example.com"
    --configName EmailConfig_test --formattingTemplate "Notification: Job:
$[/myJob/jobName]
    $[/myEvent/type] Job: $[/myJob/jobName] $[/myEvent/type] at $[/myEvent/time]"
    --projectName Project_test
    --procedureName Procedure_test
    --description "This is a test email notifier for Job completion"▼

createEventSubscription

Creates a list of event subscriptions.

You must specify a notifierName.

Arguments Descriptions

Arguments	Descriptions
notifierName	The name of the email notifier. Argument type: String
applicationName	(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
componentName	The name of the component that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
flowName	(Optional) The name of the flow. Argument type: String
flowStateName	(Optional) The name of the flow state. Argument type: String
gateType	(Optional) The type of the gate. Argument type: GateType
groupNames	A list of groups that receive the notification. Argument type: Collection
jobId	The unique CloudBees CD/RO -generated identifier (a UUID) for a job that is assigned automatically when the job is created. The system also accepts a job name assigned to the job by its name template. Argument type: UUID
jobStepId	The unique identifier for a job step that is assigned automatically when the job step is created. Argument type: UUID
pipelineName	(Optional) The name of the pipeline. Argument type: String
procedureName	The name of the procedure. When using this argument, you must also enter `projectName`. Argument type: String
processName	The name of the process. Argument type: String
processStepName	The name of the process step. Argument type: String
projectName	The name of the project. When using this argument, you must also enter `procedureName`. Argument type: String
serviceName	The name of the service which is related to the target email container (Process/ProcessStep). Argument type: String
stageName	(Optional) The name of the stage definition. Argument type: String
stateDefinitionName	The name of the state definition. Argument type: String
stateName	The name of the state. Argument type: String
stepName	The name of the step. When using this argument, you must also enter `projectName` and `procedureName`. Argument type: String
userNames	The names of the users who receives the notification. Argument type: Collection
workflowDefinitionName	The name of the workflow definition. Argument type: String
workflowName	The name of the workflow. Argument type: String

notifierName

The name of the email notifier.

Argument type: String

applicationName

(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

componentName

The name of the component that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

gateType

(Optional) The type of the gate.

Argument type: GateType

groupNames

A list of groups that receive the notification.

Argument type: Collection

jobId

The unique CloudBees CD/RO -generated identifier (a UUID) for a job that is assigned automatically when the job is created. The system also accepts a job name assigned to the job by its name template.

Argument type: UUID

jobStepId

The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: UUID

pipelineName

(Optional) The name of the pipeline.

Argument type: String

procedureName

The name of the procedure. When using this argument, you must also enter projectName.

Argument type: String

processName

The name of the process.

Argument type: String

processStepName

The name of the process step.

Argument type: String

projectName

The name of the project. When using this argument, you must also enter procedureName.

Argument type: String

serviceName

The name of the service which is related to the target email container (Process/ProcessStep).

Argument type: String

stageName

(Optional) The name of the stage definition.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

stateName

The name of the state.

Argument type: String

stepName

The name of the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

userNames

The names of the users who receives the notification.

Argument type: Collection

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workflowName

The name of the workflow.

Argument type: String

Positional arguments

notifierName

Response

Returns an eventSubscription element.

ec-perl

syntax: $cmdr->createEventSubscription (<notifierName>, {<optionals>});

Example

$cmdr->createEventSubscription ("testNotifier", {applicationName => "Pass or Fail"});▼

ectool

syntax: ectool createEventSubscription <notifierName> [optionals]

Example

ectool createEventSubscription testNotifier --applicationName "Pass or Fail"▼

deleteEmailNotifier

Deletes an email notifier from an object.

You must specify a notifierName, and you must specify locator arguments to find the email notifier you want to delete.

Arguments Descriptions

Arguments	Descriptions
notifierName	The name of the email notifier that you want to delete. Argument type: String
Locator arguments:
applicationName	The name of the application that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
componentName	The name of the component that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
flowName	(Optional) The name of the flow. Argument type: String
flowStateName	(Optional) The name of the flow state. Argument type: String
gateType	(Optional) The type of the gate. Argument type: GateType
jobId	The unique CloudBees CD/RO -generated identifier (a UUID) for a job that is assigned automatically when the job is created. The system also accepts a job name assigned to the job by its name template. Argument type: UUID
jobStepId	The unique identifier for a job step that is assigned automatically when the job step is created. Argument type: UUID
pipelineName	(Optional) The name of the pipeline. Argument type: String
procedureName	The name of the procedure. When using this argument, you must also enter `projectName`. Argument type: String
processName	Name of the process. Argument type: String
processStepName	Name of the process step. Argument type: String
projectName	Name of the project. Argument type: String
releaseName	Name of the release containing the pipeline. Argument Type: String
serviceName	The name of the service which is related to the target email container (Process/ProcessStep).
stageName	The name of the stage definition. Argument type: String
stateDefinitionName	Name of the state definition. Argument type: String
stateName	Name of the state. Argument type: String
stepName	Name of the step. When using this argument, you must also enter `projectName` and `procedureName`. Argument type: String
taskName	(Optional) The name of the task. Argument type: String
workflowDefinitionName	The name of the workflow definition. Argument type: String
workflowName	The name of the workflow. Argument type: String

notifierName

The name of the email notifier that you want to delete.

Argument type: String

Locator arguments:

applicationName

The name of the application that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

componentName

The name of the component that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

gateType

(Optional) The type of the gate.

Argument type: GateType

jobId

The unique CloudBees CD/RO -generated identifier (a UUID) for a job that is assigned automatically when the job is created. The system also accepts a job name assigned to the job by its name template.

Argument type: UUID

jobStepId

The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: UUID

pipelineName

(Optional) The name of the pipeline.

Argument type: String

procedureName

The name of the procedure. When using this argument, you must also enter projectName.

Argument type: String

processName

Name of the process.

Argument type: String

processStepName

Name of the process step.

Argument type: String

projectName

Name of the project.

Argument type: String

releaseName

Name of the release containing the pipeline.

Argument Type: String

serviceName

The name of the service which is related to the target email container (Process/ProcessStep).

stageName

The name of the stage definition.

Argument type: String

stateDefinitionName

Name of the state definition.

Argument type: String

stateName

Name of the state.

Argument type: String

stepName

Name of the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

taskName

(Optional) The name of the task.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workflowName

The name of the workflow.

Argument type: String

Positional arguments

notifierName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteEmailNotifier(<notifierName>, {optionals});

Example

$cmdr->deleteEmailNotifier("emailNotifier_stepTest", {projectName => "Project_test",
    procedureName => "Procedure_test", stepName => "Step_test2"});▼

ectool

syntax: ectool deleteEmailNotifier <notifierName> [optionals]

Example

ectool deleteEmailNotifier "emailNotifier_stepTest" --projectName "Project_test"
   --procedureName "Procedure_test" --stepName "Step_test2"▼

deleteEventSubscription

Deletes a list of event subscriptions.

You must specify a notifierName, and you must specify locator arguments to find the email notifier you want to delete.

Arguments Descriptions

Arguments	Descriptions
notifierName	The name of the email notifier. Argument type: String
applicationName	(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
componentName	(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
flowName	(Optional) The name of the flow. Argument type: String
flowStateName	(Optional) The name of the flow state. Argument type: String
gateType	(Optional) The type of the gate. Argument type: GateType
groupNames	(Optional) A list of groups that receive the notification. Argument type: Collection
jobId	(Optional) include::partial$job-id.adoc[] Argument type: UUID
jobStepId	(Optional) The unique identifier for a job step that is assigned automatically when the job step is created. Argument type: String
pipelineName	(Optional) The name of the pipeline. Argument type: String
procedureName	(Optional) The name of the procedure. When using this argument, you must also enter `projectName`. Argument type: String
processName	(Optional) Name of the process. Argument type: String
processStepName	(Optional) Name of the process step. Argument type: String
projectName	(Optional) The name of the project. When using this argument, you must also enter `procedureName`. Argument type: String
releaseName	(Optional) Name of the release containing the pipeline. Argument Type: String
serviceName	(Optional) The name of the service which is related to the target email container (Process/ProcessStep). Argument type: String
stageName	(Optional) The name of the stage. Argument type: String
stateDefinitionName	(Optional) The name of the state definition. Argument type: String
stateName	(Optional) The name of the state. Argument type: String
stepName	(Optional) Name of the step. When using this argument, you must also enter `projectName` and `procedureName`. Argument type: String
taskName	(Optional) The name of the task. Argument type: String
userNames	(Optional) A list of names of the users who receives the notification. Argument type: Collection
workflowDefinitionName	(Optional) The name of the workflow definition. Argument type: String
workflowName	(Optional) The name of the workflow. Argument type: String

notifierName

The name of the email notifier.

Argument type: String

applicationName

(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

componentName

(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

gateType

(Optional) The type of the gate.

Argument type: GateType

groupNames

(Optional) A list of groups that receive the notification.

Argument type: Collection

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

(Optional) The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure. When using this argument, you must also enter projectName.

Argument type: String

processName

(Optional) Name of the process.

Argument type: String

processStepName

(Optional) Name of the process step.

Argument type: String

projectName

(Optional) The name of the project. When using this argument, you must also enter procedureName.

Argument type: String

releaseName

(Optional) Name of the release containing the pipeline.

Argument Type: String

serviceName

(Optional) The name of the service which is related to the target email container (Process/ProcessStep).

Argument type: String

stageName

(Optional) The name of the stage.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stateName

(Optional) The name of the state.

Argument type: String

stepName

(Optional) Name of the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

taskName

(Optional) The name of the task.

Argument type: String

userNames

(Optional) A list of names of the users who receives the notification.

Argument type: Collection

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

Positional arguments

notifierName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteEventSubscription (<notifierName>, {<optionals>});

Example

$cmdr->deleteEventSubscription (mySubscription, {applicationName => myAppEvent});▼

ectool

syntax: ectool deleteEventSubscription<notifierName> [optionals]

Example

ectool deleteEventSubscription mySubscription --applicationName myAppEvent▼

getEmailNotifier

Retrieves an email notifier from a property sheet container.

You must specify a notifierName and object locators to identify the object where the notifier is attached.

Arguments Descriptions

Arguments	Descriptions
notifierName	The name of the email notifier. Argument type: String
applicationName	(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
componentName	(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
flowName	(Optional) The name of the flow. Argument type: String
flowStateName	(Optional) The name of the flow state. Argument type: String
gateType	(Optional) Type of the gate. Argument type: String
jobId	(Optional) include::partial$job-id.adoc[] Argument type: UUID
jobStepId	(Optional) The unique identifier for a job step that is assigned automatically when the job step is created. Argument type: UUID
pipelineName	(Optional) The name of the pipeline. Argument type: String
procedureName	(Optional) The name of the procedure. When using this argument, you must also enter `projectName`. Argument type: String
processName	(Optional) Name of the process. Argument type: String
processStepName	(Optional) Name of the process step. Argument type: String
projectName	(Optional) The name of the project. When using this argument, you must also enter `procedureName`. Argument type: String
releaseName	Name of the release containing the pipeline. Argument Type: String
serviceName	The name of the service which is related to the target email container (Process/ProcessStep).
stageName	(Optional) The name of the pipeline stage. Argument type: String
stateDefinitionName	The name of the state definition. Argument type: String
stateName	The name of the state. Argument type: String
stepName	Name of the step. When using this argument, you must also enter `projectName` and `procedureName`. Argument type: String
workflowDefinitionName	The name of the workflow definition. Argument type: String
workflowName	The name of the workflow. Argument type: String

notifierName

The name of the email notifier.

Argument type: String

applicationName

(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

componentName

(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

gateType

(Optional) Type of the gate.

Argument type: String

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

(Optional) The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: UUID

pipelineName

(Optional) The name of the pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure. When using this argument, you must also enter projectName.

Argument type: String

processName

(Optional) Name of the process.

Argument type: String

processStepName

(Optional) Name of the process step.

Argument type: String

projectName

(Optional) The name of the project. When using this argument, you must also enter procedureName.

Argument type: String

releaseName

Name of the release containing the pipeline.

Argument Type: String

serviceName

The name of the service which is related to the target email container (Process/ProcessStep).

stageName

(Optional) The name of the pipeline stage.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

stateName

The name of the state.

Argument type: String

stepName

Name of the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workflowName

The name of the workflow.

Argument type: String

Positional arguments

notifierName

Response

Returns one emailNotifier element.

ec-perl

syntax: $cmdr->getEmailNotifier(<notifierName>, {<optionals>});

Example

$cmdr->getEmailNotifier("Error", {projectName => "Test",
                                procedureName => "Build"});▼

ectool

syntax: ectool getEmailNotifier <notifierName> [optionals]

Example

ectool getEmailNotifier Error --projectName Test --procedureName Build▼

getEmailNotifiers

Retrieves all email notifiers defined for the specified property sheet.

You must specify one or more object locators.

Arguments Descriptions

Arguments	Descriptions
applicationName	The name of the application that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
componentName	The name of the component that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
flowName	(Optional) The name of the flow. Argument type: String
flowStateName	(Optional) The name of the flow state. Argument type: String
gateType	(Optional) Type of the gate. Argument type: String
jobId	(Optional) include::partial$job-id.adoc[] Argument type: UUID
jobStepId	(Optional) The unique identifier for a job step that is assigned automatically when the job step is created. Argument type: UUID
pipelineName	(Optional) The name of the pipeline. Argument type: String
procedureName	(Optional) The name of the procedure. When using this argument, you must also enter `projectName`. Argument type: String
processName	(Optional) The name of the process. Argument type: String
processStepName	(Optional) The name of the process step. Argument type: String
projectName	(Optional) The name of the project . When using this argument, you must also enter `procedureName`. Argument type: String
releaseName	Name of the release containing the pipeline. Argument Type: String
serviceName	The name of the service which is related to the target email container (Process/ProcessStep).
stageName	(Optional) The name of the pipeline stage. Argument type: String
stateDefinitionName	(Optional) The name of the state definition. Argument type: String
stateName	(Optional) The name of the state. Argument type: String
stepName	(Optional) The name of the step. When using this argument, you must also enter `projectName` and `procedureName`. Argument type: String
workflowDefinitionName	The name of the workflow definition. Argument type: String
workflowName	The name of the workflow. Argument type: String

applicationName

The name of the application that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

componentName

The name of the component that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

gateType

(Optional) Type of the gate.

Argument type: String

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

(Optional) The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: UUID

pipelineName

(Optional) The name of the pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure. When using this argument, you must also enter projectName.

Argument type: String

processName

(Optional) The name of the process.

Argument type: String

processStepName

(Optional) The name of the process step.

Argument type: String

projectName

(Optional) The name of the project . When using this argument, you must also enter procedureName.

Argument type: String

releaseName

Name of the release containing the pipeline.

Argument Type: String

serviceName

The name of the service which is related to the target email container (Process/ProcessStep).

stageName

(Optional) The name of the pipeline stage.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stateName

(Optional) The name of the state.

Argument type: String

stepName

(Optional) The name of the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workflowName

The name of the workflow.

Argument type: String

Positional arguments

Arguments to locate the notifier, beginning with the top-level object locator.

Response

Returns one or more emailNotifier elements.

ec-perl

syntax: $cmdr->getEmailNotifiers({<optionals>});

Example

$cmdr->getEmailNotifiers({projectName => "Test",
                        procedureName => "Build"});▼

ectool

syntax: ectool getEmailNotifiers [optionals]

Example

ectool getEmailNotifiers --projectName "Test" --procedureName "Build"▼

getEventSubscription

Retrieves an event subscription for the specified user or group.

You must specify a notifierName.

Arguments Descriptions

Arguments	Descriptions
notifierName	The name of the email notifier. Argument type: String
applicationName	(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
componentName	(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
flowName	(Optional) The name of the flow. Argument type: String
flowStateName	(Optional) The name of the flow state. Argument type: String
gateType	(Optional) Type of the gate. Argument type: String
groupName	The name of the group that receives the notification. Argument type: String
jobId	(Optional) include::partial$job-id.adoc[] Argument type: UUID
jobStepId	(Optional) The unique identifier for a job step that is assigned automatically when the job step is created. Argument type: UUID
pipelineName	(Optional) The name of the pipeline. Argument type: String
procedureName	(Optional) The name of the procedure. When using this argument, you must also enter `projectName`. Argument type: String
processName	Name of the process. Argument type: String
processStepName	Name of the process step. Argument type: String
projectName	The name of the project . When using this argument, you must also enter `procedureName`. Argument type: String
releaseName	(Optional) Name of the release containing the pipeline. Argument Type: String
stageName	(Optional) The name of the pipeline stage. Argument type: String
stateDefinitionName	The name of the state definition. Argument type: String
stateName	The name of the state. Argument type: String
stepName	Name of the step. When using this argument, you must also enter `projectName` and `procedureName`. Argument type: String
taskName	(Optional) The name of the task. Argument type: String
userName	The names of the users who receives the notification. Argument type: String
workflowDefinitionName	The name of the workflow definition. Argument type: String
workflowName	The name of the workflow. Argument type: String

notifierName

The name of the email notifier.

Argument type: String

applicationName

(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

componentName

(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

gateType

(Optional) Type of the gate.

Argument type: String

groupName

The name of the group that receives the notification.

Argument type: String

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

(Optional) The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: UUID

pipelineName

(Optional) The name of the pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure. When using this argument, you must also enter projectName.

Argument type: String

processName

Name of the process.

Argument type: String

processStepName

Name of the process step.

Argument type: String

projectName

The name of the project . When using this argument, you must also enter procedureName.

Argument type: String

releaseName

(Optional) Name of the release containing the pipeline.

Argument Type: String

stageName

(Optional) The name of the pipeline stage.

Argument type: String

stateDefinitionName

The name of the state definition.

Argument type: String

stateName

The name of the state.

Argument type: String

stepName

Name of the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

taskName

(Optional) The name of the task.

Argument type: String

userName

The names of the users who receives the notification.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workflowName

The name of the workflow.

Argument type: String

Positional arguments

notifierName

Response

Returns an event subscription for a user or group.

ec-perl

syntax: $cmdr->getEventSubscription (<notifierName>, {<optionals>});

Example

$cmdr->getEventSubscription("Error", {groupName => "QA"});▼

ectool

syntax: ectool getEventSubscription <notifierName> [optionals]

Example

ectool getEventSubscription "Error" --groupName "QA"▼

getEventSubscriptions

Retrieves a list event subscriptions for a specified event.

You must specify a notifierName.

Arguments Descriptions

Arguments	Descriptions
notifierName	The name of the email notifier. Argument type: String
applicationName	(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
componentName	(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
flowName	(Optional) The name of the flow. Argument type: String
flowStateName	(Optional) The name of the flow state. Argument type: String
gateType	(Optional) Type of the gate. Argument type: String
jobId	(Optional) include::partial$job-id.adoc[] Argument type: String
jobStepId	(Optional) The unique identifier for a job step that is assigned automatically when the job step is created. Argument type: String
pipelineName	(Optional) The name of the pipeline. Argument type: String
procedureName	(Optional) The name of the procedure. When using this argument, you must also enter `projectName`. Argument type: String
processName	(Optional) Name of the process. Argument type: String
processStepName	(Optional) Name of the process step. Argument type: String
projectName	(Optional) The name of the project . When using this argument, you must also enter `procedureName`. Argument type: String
releaseName	(Optional) Name of the release containing the pipeline. Argument Type: String
stageName	(Optional) The name of the stage definition. Argument type: String
stateDefinitionName	(Optional) The name of the state definition. Argument type: String
stateName	(Optional) The name of the state. Argument type: String
stepName	(Optional) Name of the step. When using this argument, you must also enter `projectName` and `procedureName`. Argument type: String
taskName	(Optional) The name of the task. Argument type: String
workflowDefinitionName	(Optional) The name of the workflow definition. Argument type: String
workflowName	(Optional) The name of the workflow. Argument type: String

notifierName

The name of the email notifier.

Argument type: String

applicationName

(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

componentName

(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

gateType

(Optional) Type of the gate.

Argument type: String

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: String

jobStepId

(Optional) The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure. When using this argument, you must also enter projectName.

Argument type: String

processName

(Optional) Name of the process.

Argument type: String

processStepName

(Optional) Name of the process step.

Argument type: String

projectName

(Optional) The name of the project . When using this argument, you must also enter procedureName.

Argument type: String

releaseName

(Optional) Name of the release containing the pipeline.

Argument Type: String

stageName

(Optional) The name of the stage definition.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stateName

(Optional) The name of the state.

Argument type: String

stepName

(Optional) Name of the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

taskName

(Optional) The name of the task.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

Positional arguments

notifierName

Response

Returns an event subscription for a specific event.

ec-perl

syntax: $cmdr->getEventSubscriptions (<notifierName>, {<optionals>});

Example

$cmdr->getEventSubscriptions("Error", {applicationName => "Pet Store"});▼

ectool

syntax: ectool getEventSubscriptions <notifierName> [optionals]

Example

ectool getEventSubscriptions "Error" --applicationName "Pet Store"▼

modifyEmailNotifier

Modifies an email notifier in a property sheet container specified by an emailNotifierSelector.

Email notifiers are evaluated and sent based on the privileges of the notifier’s owner. "Owner" can be changed to the current user if that user has sufficient privileges to have deleted the notifier object and recreated it. Modify privilege on the "admin" system ACL is required.

You must specify a notifierName.

Arguments Descriptions

notifierName

The name of the email notifier.

Argument type: String

applicationName

(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

componentName

(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

condition

(Optional) Only send mail if the condition evaluates to "true ." The condition is a string subject to property expansion. Notification will not be sent if the expanded string is "false" or "0". If no condition is specified, the notification is always sent.

Argument type: String

configName

(Optional) If specified, this argument must be the name of an emailConfig object. If it is not specified, the default is the name of the first emailConfig object defined for the CloudBees CD/RO server ( emailConfig objects are "ordered" CloudBees CD/RO entities). When using this argument, you must also include the formattingTemplate or the formattingTemplateFile argument .

Argument type: String

description

(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>.

Argument type: String

destinations

(Optional) A space-separated list of valid email addresses, email aliases, or CloudBees CD/RO user names, or a string subject to property expansion that expands into such a list.

This argument is mandatory for the "create" operation.

Argument type: String

environmentNames

(Optional) The names of the environments.

Argument type: Collection

eventType

(Optional) Use one of these values: < onStart|onCompletion >.

onStart –Triggers an event when the job or job step begins.
onCompletion –Triggers an event when the job ends, regardless of the results.

The default is onCompletion.

Argument type: EventType

flowName

(Optional) The name of the flow.

Argument type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

formattingTemplate

(Optional) A template for formatting email messages when an event [notification] is triggered by the emailNotifier. Make sure the content is formatted correctly, such as no illegal characters or spacing.

Argument type: String

formattingTemplateFile

(Optional) Contents of the formatting template file is read and stored in the "formatting template" field. This is an alternative argument for formattingTemplate and is useful if the "formatting template" field spans multiple lines.

This option is supported only in Perl and ectool bindings—it is not part of the XML protocol.

gateType

(Optional) Type of the gate.

Argument type: String

groupNames

(Optional) The list of the groups that receives the notification.

Argument type: Collection

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

(Optional) The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: UUID

newName

(Optional) New name of the email notifier.

Argument type: String

notificationType

(Optional) The notification type that is stored to the ec_notificationType property.

Argument type: NotificationType

pipelineName

(Optional) The name of the pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure. When using this argument, you must also enter the projectName.

Argument type: String

processName

(Optional) The name of the process that contains of the email notifier.

Argument type: String

processStepName

(Optional) The name of the process step that contains of the email notifier.

Argument type: String

projectName

(Optional) The name of the project. When using this argument, you must also enter the procedureName.

Argument type: String

releaseName

(Optional) Name of the release containing the pipeline.

Argument Type: String

serviceName

The name of the service which is related to the target email container (Process/ProcessStep).

stageName

(Optional) The name of the stage definition.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stateName

(Optional) The name of the state.

Argument type: String

stepName

(Optional) Name of the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

taskName

(Optional) The name of the task.

Argument type: String

userNames

(Optional) The names of the users who receives the notification.

Argument type: Collection

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

Positional arguments

notifierName

Response

Returns a modified emailNotifier element.

ec-perl

syntax: $cmdr->modifyEmailNotifier(<notifierName>, {<optionals>});

Example

$cmdr->modifyEmailNotifier("testNotifier",
        {eventType => "onCompletion",
       projectName => "Project_test",
     procedureName => "Procedure_test",});▼

ectool

syntax: ectool modifyEmailNotifier <notifierName> [optionals]

Example

ectool modifyEmailNotifier testNotifier --eventType onCompletion
   --projectName Project_test
   --procedureName Procedure_test▼

modifyEventSubscription

Modifies a list of event subscriptions.

You must specify a notifierName.

Arguments Descriptions

Arguments	Descriptions
notifierName	The name of the email notifier. Argument type: String
applicationName	(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
componentName	(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step. Argument type: String
flowName	(Optional) The name of the flow. Argument type: String
flowStateName	(Optional) The name of the flow state. Argument type: String
gateType	(Optional) Type of the gate. Argument type: String
groupNames	(Optional) The list of the groups that receives the notification. Argument type: Collection
jobId	(Optional) include::partial$job-id.adoc[] Argument type: UUID
jobStepId	(Optional) The unique identifier for a job step that is assigned automatically when the job step is created. Argument type: UUID
pipelineName	(Optional) The name of the pipeline. Argument type: String
procedureName	(Optional) The name of the procedure. When using this argument, you must also enter the `projectName`. Argument type: String
processName	(Optional) The name of the process that contains of the email notifier. Argument type: String
processStepName	(Optional) The name of the process step that contains of the email notifier. Argument type: String
projectName	(Optional) The name of the project. When using this argument, you must also enter the `procedureName`. Argument type: String
releaseName	(Optional) Name of the release containing the pipeline. Argument Type: String
stageName	(Optional) The name of the stage definition. Argument type: String
stateDefinitionName	(Optional) The name of the state definition. Argument type: String
stateName	(Optional) The name of the state. Argument type: String
stepName	(Optional) The name of the step. When using this argument, you must also enter `projectName` and `procedureName`. Argument type: String
taskName	(Optional) The name of the task. Argument type: String
userNames	(Optional) The names of the users who receives the notification. Argument type: Collection
workflowDefinitionName	(Optional) The name of the workflow definition. Argument type: String
workflowName	(Optional) The name of the workflow. Argument type: String

notifierName

The name of the email notifier.

Argument type: String

applicationName

(Optional) The name of the application that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

componentName

(Optional) The name of the component that is related to the target email container. The email notifier is attached to a process or process step.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

gateType

(Optional) Type of the gate.

Argument type: String

groupNames

(Optional) The list of the groups that receives the notification.

Argument type: Collection

jobId

(Optional) include::partial$job-id.adoc[]

Argument type: UUID

jobStepId

(Optional) The unique identifier for a job step that is assigned automatically when the job step is created.

Argument type: UUID

pipelineName

(Optional) The name of the pipeline.

Argument type: String

procedureName

(Optional) The name of the procedure. When using this argument, you must also enter the projectName.

Argument type: String

processName

(Optional) The name of the process that contains of the email notifier.

Argument type: String

processStepName

(Optional) The name of the process step that contains of the email notifier.

Argument type: String

projectName

(Optional) The name of the project. When using this argument, you must also enter the procedureName.

Argument type: String

releaseName

(Optional) Name of the release containing the pipeline.

Argument Type: String

stageName

(Optional) The name of the stage definition.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

Argument type: String

stateName

(Optional) The name of the state.

Argument type: String

stepName

(Optional) The name of the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

taskName

(Optional) The name of the task.

Argument type: String

userNames

(Optional) The names of the users who receives the notification.

Argument type: Collection

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

Positional arguments

notifierName

Response

Returns a modified event subscription for a user or group.

ec-perl

syntax: $cmdr->modifyEventSubscription (<notifierName>, {<optionals>});

Example

$cmdr->modifyEventSubscription("Error", {componentName => "Config files"});▼

ectool

syntax: ectool modifyEventSubscription <notifierName> [optionals]

Example

ectool getEventSubscription "Error" --componentName "Config files"▼

sendEmail

Facilitates sending an email from the command-line or a Command Job Step without setting up an Email Notifier. This API is more dynamic than an email notifier because you do not need to setup some kind of a template beforehand. This API also makes sending email attachments easier than using a notifier template.

Instead of (or in addition to) specifying a configName, any of the configuration options for an email configuration can be specified as options. These options are: mailHost,mailPort, mailFrom, mailUser, and mailUserPassword.

If both a configName and some or all of the configuration options are specified, the specified options override values stored in the configuration. In this case, the user must have both modify and execute permission on the configuration.

Specify the options you need to create the type of email message you want to send.

Arguments Descriptions

attachment

One or more client-side files to send as attachments. The file name extension is examined to determine the content type. You can enter this argument more than once to specify multiple attachments.

Argument type: Collection

bcc

A "Bcc" recipient for the email message. The recipient can be a user name, group name or complete email address. You can enter this argument more than once to specify multiple recipients.

Argument type: Collection

cc

A "Cc" recipient for the email message. The recipient can be a user name, group name or complete email address. You can enter this argument more than once to specify multiple recipients.

Argument type: Collection

configName

The name of the email configuration. If no configuration is specified, the configuration named "default" is used.

The user must have execute permission on the configuration.

Argument type: String

header

An RFC822 email header line (for example: "reply-to: user@example.com"). This option can be specified multiple times.

Argument type: Collection

html

The body of a simple HTML message.

Argument type: String

htmlFile

Reads the specified client-side file and uses it as the body of a simple HTML message.

inline

Inline attachments in this format: <contentId>=<fileName> [<contentId>=<fileName> …].

One or more inline attachments specified as a contentId and a client-side filename. The filename extension is examined to determine the content-type. The contentId can be referenced in an HTML body using the cid:protocol.

For example: <img src=cid: myImage "> could reference ` --inline` myImage=image.jpg

You can enter this argument more than once to add multiple attachments.

Argument type: Collection

mailFrom

The email address used in the "From" header to use when sending CloudBees CD/RO notification email. When the email configuration is specified, this value overrides the value in the configuration.

Argument type: String

mailHost

The name of the email server host to use when the configName is not specified. When the email configuration is specified, this value overrides the value in the configuration.

Argument type: String

mailPort

The mail server port to use when the configName is not specified. When the email configuration is specified, this value overrides the value in the configuration.

Argument type: Integer

mailProtocol

The name of the mail protocol that must be SMTP or SMTPS. When the email configuration is specified, this value overrides the value in the configuration.

Argument type: String

mailUser

The name of the email user for whom CloudBees CD/RO sends email notifications. CloudBees CD/RO also uses it when authenticating to the mail server. When the email configuration is specified, this value overrides the value in the configuration.

Argument type: String

mailUserPassword

The password that CloudBees CD/RO uses when when authenticating to the mail server. When the email configuration is specified, this value overrides the value in the configuration.

Argument type: String

multipartMode

The multipart message mode: <none|mixed|related|mixedRelated>

none – Non-multipart message
mixed –Single-root multipart element of type "mixed". Texts, inline elements, and attachments will be added to this root element.
related – Multipart message with a single root multipart element of "related" type. Texts, inline elements, and attachments will be added to this root element. It works on most mail clients, except Lotus Notes.
mixedRelated –Multipart "mixed" element with a nested multipart "related" element. Texts and inline elements will be added to the nested "related' element, while attachments will be added to the "mixed' root element. It works on most mail clients other than Mac Mail and some situations on Outlook. If you experience problems, use the "related" value.

multipartMode defaults to none unless there are multiple parts, in which case it defaults to mixedRelated. If both text and html arguments are specified, both values are sent as alternates in a multipart message.

Argument type: MultipartMode

raw

A raw RFC 822 email message including headers to use as the basis for the email message. Additional options can be applied to this message. Argument type: String

rawFile

Reads the specified client-side file and uses it as the entire mail message, including headers.

subject

The subject of the email message.

Argument type: String

text

The body of a simple text message.

Argument type: String

textFile

Reads the specified client-side file and uses it as the body of a simple text message.

to

A "To" recipient for the email message. The recipient can be a user, group name or complete email address. You can enter this argument more than once to specify multiple recipients.

Argument type: Collection

Positional arguments

None

Response

None or a status OK message.

ec-perl

syntax: $cmdr->sendEmail

Note: The to, cc, bcc, header, and attachment options can have multiple values specified as an array. The inline option can have multiple values specified as an array of hashes with contentId and fileName values.

Example

$cmdr->sendEmail({
    configName => 'config1',
       subject => 'Test message',
            to => ['user1', 'user2'],
          html => '<html><body>Some stuff</body></html>',
        inline => [{contentId => 'image1', fileName => 'image1.jpg'},
                   {contentId => 'image2', fileName => 'image2.jpg'}],
    attachment => ['report1.html', 'report2.pdf']
   })▼

ectool

syntax: ectool sendEmail

Note: Options that take multiple values may be specified as a single option with each value as a separate argument or as multiple options, each with a single argument.

Examples

ectool sendEmail \
     --to user1 \
     --to user2 \
     --subject Test \
     --html '<html><body>Some stuff</body></html>' \
     --inline image1=image1.jpg \
     --inline image2=image2.jpg \
     --attachment report1.html \
     --attachment report2.pdf


ectool sendEmail \
     --to user1 user2 \
     --subject Test \
     --html '<html><body>Some stuff</body></html>' \
     --inline image1=image1.jpg image2=image2.jpg \
     --attachment  report1.html report2.pdf▼