NAME

BuildForge::Services::DBO::Template


SYNOPSIS

        use BuildForge::Services;
        $conn = new BuildForge::Services::Connection($hostname);
        $token = $conn->authUser($user, $pass);
        
        # Getting existing templates
        $allProjectTemplates = BuildForge::Services::DBO::Template->findByProjectId($conn, $projectId);
        $oldtemplate = BuildForge::Services::DBO::Template->findById($conn, $projectId, $stepId, 
                        $templateName);
        # Getter / setter functions
        $projectId = $oldtemplate->getProjectId();
        $stepId = $oldtemplate->getStepId();
        $templateName = $oldtemplate->getName();
        $description = $oldtemplate->getDescription();
        $from = $oldtemplate->getFrom();
        $subject = $oldtemplate->getSubject();
        $body = $oldtemplate->getBodyText();
        $locale = $oldtemplate->getLocale();
        $oldtemplate->setProjectId($projectId);
        $oldtemplate->setStepId($stepId);
        $oldtemplate->setName('build_break');
        $oldtemplate->setDescription('New Template Description');
        $oldtemplate->setFrom('user@company.com');
        $oldtemplate->setSubject('Subject of email message');
        $oldtemplate->setBodyText('Body of email message');
        $oldtemplate->setLocale('en_US');
        $oldtemplate->update();
        
        # Template creation, updating, deletion
        $newtemplate = new BuildForge::Services::DBO::Template($conn);
        $newtemplate->setProjectId($projectId);
        $newtemplate->setStepId($stepId);
        $newtemplate->setName('build_pass');
        $newtemplate->setLocale('es_ES');
        $newtemplate->create();
        $newtemplate->setDescription('Another Template Description');
        $newtemplate->update();
        
        $newtemplate->delete();
        BuildForge::Services::DBO::Template->deleteById($conn, $projectId, $stepId, $templateName);
                
        $conn->logout;
        $conn->close;


DESCRIPTION

Template allows you to create, access, and delete BuildForge notification templates, used to send emails to users upon encountering various alert events.


METHODS

new BuildForge::Services::DBO::Template(connection, {TemplateParamsHashRef})

Returns a new instance of a Template object.

connection

A connected BuildForge::Services::Connection object.

TemplateParamsHashRef

An optional reference to a hash containing any or all of the following fields.

projectId

The project ID (from $project->getProjectId()) of the project that the template is connected to. A value of 0 indicates that this is one of the base templates which get used in the absence of a specific project template. Base templates should not be created or deleted, only edited.

stepId

The step number (from $step->getStepOrdinal()) of the step that the template is used for for step-specific templates. A value of 0 (the default) indicates that this template is used for all steps and for project-specific purposes.

name

The key for the template type. This should be identical to one of the keys for the base templates.

locale

The code for the locale of the template. Defaults to 'en_US', the English language locale. A template for a given locale will be sent to users from that locale when the appropriate event is kicked off. For example, if a build is set to send an email on success to a given access group, it'll send the 'en_US' template to the english speakers, the 'es_ES' template to the spanish speakers, etc.

description

The description of the template.

from

The ``From'' field of the outgoing email message.

subject

The ``Subject'' field of the outgoing email message. This may have a number of template-specific variables included. For more details of the variables, see the BuildForge online help topic Setting Up Notification->Notification Templates->Special Notification Template Variables.

bodyText

The body of the outgoing email message. This may have a number of template-specific variables included. For more details of the variables, see the BuildForge online help topic Setting Up Notification->Notification Templates->Special Notification Template Variables.

BuildForge::Services::DBO::Template->findByProjectId(connection, projectId)

Returns a reference to an array of BuildForge::Services::DBO::Template objects corresponding to all templates in the database for the given project.

connection

A connected BuildForge::Services::Connection object.

projectId

The project ID of the project that the templates relate to (from $project->getProjectId()), or 0 to get all of the base templates.

BuildForge::Services::DBO::Template->findById(connection, projectId, stepNumber, templateKey)

Returns the BuildForge::Services::DBO::Template object corresponding to the given database template, or undef if no such object exists.

connection

A connected BuildForge::Services::Connection object.

projectId

The project ID of the project that the template relates to (from $project->getProjectId()), or 0 to get one of the base templates.

stepNumber

The step number of the step that the project relates to (from $step->getStepOrdinal()), or 0 for the all-step or project-specific templates.

templateKey

The key for the template (from $template->getName()).

$template->create()

Creates the template record within the database. Base templates (those with project ID of 0) cannot be created.

$template->update()

Updates the template record within the database.

$template->delete()

Deletes the template record from the database. Base templates (those with project ID of 0) cannot be deleted.

BuildForge::Services::DBO::Template->deleteById(connection, projectId, stepNumber, templateKey)

Deletes the template record from the database with the given project, step, and ID. Base templates (those with project ID of 0) cannot be deleted.

connection

A connected BuildForge::Services::Connection object.

projectId

The project ID of the project that the template relates to (from $project->getProjectId()).

stepNumber

The step number of the step that the project relates to (from $step->getStepOrdinal()), or 0 for the all-step or project-specific templates.

templateKey

The key for the template (from $template->getName()).

$template->getName()

Returns the template's key.

$template->getProjectId()

Returns the project ID for the project the template is connected to, or 0 for the base templates.

$template->getStepId()

Returns the step number for the step the template is connected to, or 0 for the all-step or project-specific templates.

$template->getDescription()

Returns the template's description.

$template->getFrom()

Returns the ``From'' field of the emails the template sends out.

$template->getSubject()

Returns the ``Subject'' field of the emails the template sends out. This may have a number of template-specific variables included. For more details of the variables, see the BuildForge online help topic Setting Up Notification->Notification Templates->Special Notification Template Variables.

$template->getBodyText()

Returns the body of the emails the template sends out. This may have a number of template-specific variables included. For more details of the variables, see the BuildForge online help topic Setting Up Notification->Notification Templates->Special Notification Template Variables.

$template->getLocale()

Returns the code for the locale of the template. A template for a given locale will be sent to users from that locale when the appropriate event is kicked off. For example, if a build is set to send an email on success to a given access group, it'll send the 'en_US' template to the english speakers, the 'es_ES' template to the spanish speakers, etc.

$template->setName(templateKey)

Sets the template's key. $template->update() must be run before changes are replicated in the database.

templateKey

The new key for the template. This should be identical to one of the keys of the base templates.

$template->setProjectId(projectId)

Sets the project that the template is connected to. $template->update() must be run before changes are replicated in the database.

projectId

The project ID (from $project->getProjectId()) of the project that this template will get connected to.

$template->setStepId(stepNumber)

Sets the step that the template is connected to. $template->update() must be run before changes are replicated in the database.

stepNumber

The step number (from $step->getStepOrdinal()) that the template is connected to or 0 for templates connected to all project steps or used for project-specific purposes.

$template->setDescription(description)

Sets the description of the template. $template->update() must be run before changes are replicated in the database.

description

The new template description.

$template->setFrom(from)

Sets the ``From'' field for the emails sent with this template. $template->update() must be run before changes are replicated in the database.

from

The email address this message is listed as coming from.

$template->setSubject(subject)

Sets the ``Subject'' field for the emails sent with this template. $template->update() must be run before changes are replicated in the database.

subject

The new email subject line. This may have a number of template-specific variables included. For more details of the variables, see the BuildForge online help topic Setting Up Notification->Notification Templates->Special Notification Template Variables.

$template->setBodyText(body)

Sets the message body for the emails sent with this template. $template->update() must be run before changes are replicated in the database.

body

The new email body. This may have a number of template-specific variables included. For more details of the variables, see the BuildForge online help topic Setting Up Notification->Notification Templates->Special Notification Template Variables.

$template->setLocale(locale)

Sets the template's locale. A template for a given locale will be sent to users from that locale when the appropriate event is kicked off. For example, if a build is set to send an email on success to a given access group, it'll send the 'en_US' template to the english speakers, the 'es_ES' template to the spanish speakers, etc. $template->update() must be run before changes are replicated in the database.

locale

The key for the locale to set.


COPYRIGHT

Copyright (c)2006-2007 International Business Machines, Inc. All rights reserved.