NAME

BuildForge::Services::DBO::Step


SYNOPSIS

        use BuildForge::Services;
        $conn = new BuildForge::Services::Connection($hostname);
        $token = $conn->authUser($user, $pass);
        
        # Getting existing steps
        $project = BuildForge::Services::DBO::Project->findById($conn, $pid);
        $allSteps = $project->getSteps();
        $step1 = $project->getStep(2);
        $step2 = $project->getStep($stepUID);
        # Getter / setter functions
        $id = $step1->getUid();
        $projectId = $step1->getProjectId();
        $description = $step1->getDescription();
        $directory = $step1->getDirectory();
        $command = $step1->getCommandText();
        $isAbsolute = $step1->getAbsolute();
        $isActive = $step1->getActive();
        $isBroadcast = $step1->getBroadcast();
        $envGroupId = $step1->getEnvironmentId();
        $failChainProjectId = $step1->getFailChainId();
        $failNotifyAccessGroupId = $step1->getFailNotify();
        $failWait = $step1->getFailWait();
        $filterId = $step1->getFilterSetId();
        $inlineProjectId = $step1->getInlineChainId();
        $accessGroupId = $step1->getLevel();
        $continueOnFail = $step1->getOnFail();
        $passChainProjectId = $step1->getPassChainId();
        $passNotifyAccessGroupId = $step1->getPassNotify();
        $passWait = $step1->getPassWait();
        $selectorId = $step1->getResource();
        $stepNumber = $step1->getStepOrdinal();
        $thread = $step1->getThreaded();
        $timeoutInSeconds = $step1->getTimeout();
        $step1->setDescription('New Step Description');
        $step1->setDirectory('/');
        $step1->setCommandText('echo hi');
        $step1->setAbsolute(1);
        $step1->setActive(1);
        $step1->setBroadcast(1);
        $step1->setEnvironmentId($envGroupId);
        $step1->setFailChainId($projectId);
        $step1->setFailNotify($accessGroupId);
        $step1->setFailWait(1);
        $step1->setFilterSetId($filterId);
        $step1->setInlineChainId($projectId);
        $step1->setLevel($accessGroupId);
        $step1->setOnFail(ENUM_STEP_ONFAIL->CONTINUE);
        $step1->setPassChainId($projectId);
        $step1->setPassNotify($accessGroupId);
        $step1->setPassWait(1);
        $step1->setResource($selectorId);
        $step1->setThreaded(ENUM_STEP_THREADED->YES);
        $step1->setTimeout(300);
        $step1->update();
        
        # Step creation, updating, deletion
        $newstep = new BuildForge::Services::DBO::Step($conn);
        $newstep->setDescription('New Step Description');
        $newstep->setDirectory('/');
        $newstep->setCommandText('echo hi');
        $project->addStep($newstep);
        
        $newstep2 = $newstep->clone();
        $newstep2->setDescription('Duplicate Step Description');
        $project->addStep($newstep2);
        $newstep->setLevel(2);
        $newstep->update();
        
        $newstep->disable();
        $newstep->enable();
        
        $newstep->delete();
        $project->removeStep($step1->getUid());
        $conn->logout;
        $conn->close;


DESCRIPTION

Step allows you to access, and delete BuildForge project steps. To create steps within the database, see $project->addStep().


METHODS

new BuildForge::Services::DBO::Step(connection, {project}, {StepParamsHashRef})

Returns a new instance of a Step object.

connection

A connected BuildForge::Services::Connection object.

environment

This should be undef or not passed - it is only used internally.

StepParamsHashRef

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

description

The step name.

directory

The directory the step commands will be executed in. This is relative to the server base directory if the step is absolute or to the build directory if the step is relative. For example, if the server base directory is ``/tmp'', the project is ``Project'', the build tag is ``BUILD_57'', and the step path is ``/Step'', the step will execute in ``/tmp/Step'' if the step is absolute and in ``/tmp/Project/BUILD_57/Step'' if the step is relative. While the build directory is created by the engine, the step directory is not. In the above example, in order for the step not to fail due to a nonexistant directory, a previous step will need to create the ``Step'' directory. This defaults to ``/'' if unset and may be either in Unix or Windows format.

commandText

The commands that will be run within the step separated by newlines.

absolute

If this evaluates to true, the step will be absolute, and the step commands will execute inside the server base directory. If this evaluates to false, the step will be relative and the step commands will execute inside of the build directory. It defaults to relative if unset.

active

If this evaluates to true the step is enabled and will run on build execution. If this evaluates to false the step is disabled and will not run until enabled. It defaults to active if unset.

broadcast

If this evaluates to true the step is a broadcast step. If false (the default) the step is not. Where non-broadcast steps operate on a single server in the selector, broadcast steps run on every server that the selector matches.

environmentId

The environment group ID (from $environmentGroup->getEnvironmentGroupId()) of the environment group that gets applied to the step, or 0 (the default) to just use the project's environment. If an environment group is set, first the server's environment is applied, then the project's, then the step's, so that the project variables overwrite the server variables if they duplicate, then the step's variables overwrite both the others if they duplicate.

failChainId

The project ID (from $project->getProjectId()) of the project that gets run if this step fails or 0 (the default) to have no project start up.

failNotify

The access group ID (from $accessGroup->getLevel()) of the access group that gets notified if this step fails or 0 (the default) to have no access group be notified.

failWait

If this evaluates to true, fail wait is set. If false, fail wait is not set. When a project gets kicked off due to this step failing and failChainId being set, if fail wait is set, the execution of this step will pause until that project finishes before continuing. If fail wait isn't set, the other project will get kicked off and then execution of this project will continue immediately.

filterSetId

The filter set ID (from $filter->getFilterId()) for the filter to use to set this step's result status. If this is set to 0 (the default), no filter set is used and the return code of the step's commands is used to determine step result status.

inlineChainId

The project ID (from $project->getProjectId()) of the project to inline from this step. Inlined projects have their steps inserted after this one when executing this project. If this is 0 (the default), no project is inlined by this step.

level

The access group ID (from $accessGroup->getLevel()) of the access group this step belongs to, or 0 (the default) to use the project's access group. If a user does not belong to this access group, they cannot view or edit this step, and when they start this project this step will only be executed if the user has the ``Execute Inaccessible Steps'' permission.

onFail

This may either be 'HALT', the default, in which case if this step fails the project execution stops immediately with a failure, or 'CONTINUE', in which case if the step fails the project execution continues and (if it encounters no further failures) finishes with a warning.

passChainId

The project ID (from $project->getProjectId()) of the project that gets run if this step succeeds or 0 (the default) to have no project start up.

passNotify

The access group ID (from $accessGroup->getLevel()) of the access group that gets notified if this step succeeds or 0 (the default) to have no access group be notified.

passWait

If this evaluates to true, pass wait is set. If false, pass wait is not set. When a project gets kicked off due to this step succeeding and passChainId being set, if pass wait is set, the execution of this step will pause until that project finishes before continuing, and then this step will pass or fail depending on the result of that project execution. If pass wait isn't set, the other project will get kicked off and then execution of this project will continue immediately and this step's result will be unaffected by the operation of the kicked off project.

resource

The selector ID (from $selector->getSelectorId()) of the selector that this step runs on. If this is set to the empty string (the default), the step uses the project's selector.

threaded

This may be 'NO', the default, for no threading, 'YES' for threading, or 'JOIN' to make this a join step. Threaded/join steps in the same thread block will run simultaneously up to the project's limit of concurrent threads. A thread block is delimited by either a non-threading step or a join step.

timeout

The time in seconds before no response from the server causes a step failure. It defaults to 300.

$step->clone()

Returns a BuildForge::Services::DBO::Step object that is a duplicate of this one. For the new step to exist in the database, it must be added to a project with $project->addStep($copy).

$step->update()

Updates the step record in the database.

$step->enable()

Enables the step within the database. Similar to $step->setActive(1), except that $step->enable() doesn't need to have $step->update() run afterwards to update the database record.

$step->disable()

Disables the step within the database. Similar to $step->setActive(0), except that $step->disable() doesn't need to have $step->update() run afterwards to update the database record.

$step->delete()

Deletes the step from the database.

$step->getUid()

Returns the step's unique ID.

$step->getProjectId()

Returns the project ID of the project this step belongs to.

$step->getDescription()

Returns the step's description.

$step->getDirectory()

Returns the directory the step commands will be executed in. This is relative to the server base directory if the step is absolute or to the build directory if the step is relative. For example, if the server base directory is ``/tmp'', the project is ``Project'', the build tag is ``BUILD_57'', and the step path is ``/Step'', the step will execute in ``/tmp/Step'' if the step is absolute and in ``/tmp/Project/BUILD_57/Step'' if the step is relative. While the build directory is created by the engine, the step directory is not. In the above example, in order for the step not to fail due to a nonexistant directory, a previous step will need to create the ``Step'' directory.

$step->getCommandText()

Returns the commands that will be run within the step separated by newlines.

$step->getAbsolute()

Returns 1 if the step is absolute and the step commands will execute inside the server base directory. Returns 0 if the step is relative and the step commands will execute inside of the build directory.

$step->getActive()

Returns 1 if the step is enabled and will run on build execution or 0 if the step is disabled and will not run until enabled.

$step->getBroadcast()

Returns 1 if the step is a broadcast step or 0 otherwise. Where non-broadcast steps operate on a single server in the selector, broadcast steps run on every server that the selector matches.

$step->getEnvironmentId()

Returns the environment group ID (from $environmentGroup->getEnvironmentGroupId()) of the environment group that gets applied to the step, or 0 if it just uses the project's environment. If an environment group is set, first the server's environment is applied, then the project's, then the step's, so that the project variables overwrite the server variables if they duplicate, then the step's variables overwrite both the others if they duplicate.

$step->getFailChainId()

Returns the project ID (from $project->getProjectId()) of the project that gets run if this step fails or 0 if no such project gets run.

$step->getFailNotify()

Returns the access group ID (from $accessGroup->getLevel()) of the access group that gets notified if this step fails or 0 if no such access group is notified.

$step->getFailWait()

Returns 1 if fail wait is set or 0 if fail wait is not set. When a project gets kicked off due to this step failing and failChainId being set, if fail wait is set, the execution of this step will pause until that project finishes before continuing. If fail wait isn't set, the other project will get kicked off and then execution of this project will continue immediately.

$step->getFilterSetId()

Returns the filter set ID (from $filter->getFilterId()) for the filter to use to set this step's result status or 0 if no filter set is used and the return code of the step's commands is used to determine step result status.

$step->getInlineChainId()

Returns the project ID (from $project->getProjectId()) of the project to inline from this step or 0 if no project is inlined. Inlined projects have their steps inserted after this one when executing this project.

$step->getLevel()

Returns the access group ID (from $accessGroup->getLevel()) of the access group this step belongs to or 0 if it belongs to the project's access group. If a user does not belong to this access group, they cannot view or edit this step, and when they start this project this step will only be executed if the user has the ``Execute Inaccessible Steps'' permission.

$step->getOnFail()

Returns either 'HALT' in which case if this step fails the project execution stops immediately with a failure, or 'CONTINUE', in which case if the step fails the project execution continues and (if it encounters no further failures) finishes with a warning.

$step->getPassChainId()

Returns the project ID (from $project->getProjectId()) of the project that gets run if this step succeeds or 0 if no such project gets run.

$step->getPassNotify()

Returns the access group ID (from $accessGroup->getLevel()) of the access group that gets notified if this step succeeds or 0 if no such access group is notified.

$step->getPassWait()

Returns 1 if pass wait is set or 0 if pass wait is not set. When a project gets kicked off due to this step succeeding and passChainId being set, if pass wait is set, the execution of this step will pause until that project finishes before continuing, and then this step will pass or fail depending on the result of that project execution. If pass wait isn't set, the other project will get kicked off and then execution of this project will continue immediately and this step's result will be unaffected by the operation of the kicked off project.

$step->getResource()

Returns the selector ID (from $selector->getSelectorId()) of the selector that this step runs on or the empty string if the step uses the project's selector.

$step->getStepOrdinal()

Returns the step's step number within this project. The first step returns 1, the second returns 2, etc.

$step->getThreaded()

Returns either 'NO' for no threading, 'YES' for threading, or 'JOIN' for join steps. Threaded/join steps in the same thread block will run simultaneously up to the project's limit of concurrent threads. A thread block is delimited by either a non-threading step or a join step.

$step->getTimeout()

Returns the time in seconds before no response from the server causes a step failure.

$step->setDescription(description)

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

description

The new step description.

$step->setDirectory(directory)

Sets the directory the step commands will be executed in. This is relative to the server base directory if the step is absolute or to the build directory if the step is relative. For example, if the server base directory is ``/tmp'', the project is ``Project'', the build tag is ``BUILD_57'', and the step path is ``/Step'', the step will execute in ``/tmp/Step'' if the step is absolute and in ``/tmp/Project/BUILD_57/Step'' if the step is relative. While the build directory is created by the engine, the step directory is not. In the above example, in order for the step not to fail due to a nonexistant directory, a previous step will need to create the ``Step'' directory. $step->update() must be run before changes are replicated in the database.

directory

The new step directory. This may be either in Unix or Windows format.

$step->setCommandText(command)

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

command

The commands that will be run within the step separated by newlines.

$step->setAbsolute(isAbsolute)

Sets whether this step is absolute or relative. If absolute, the step commands will execute inside the server base directory. If relative, the step commands will execute inside of the build directory. $step->update() must be run before changes are replicated in the database.

isAbsolute

If this evaluates to true, the step will be absolute. If this evaluates to false, the step will be relative.

$step->setActive(isActive)

Sets if this step is active or not. If the step is active, it runs when this project is executed. If inactive, the step will not run until it is activated. $step->update() must be run before changes are replicated in the database.

isActive

If this evaluates to true, the step is active. If false, the step is inactive.

$step->setBroadcast(isBroadcast)

Sets whether or not the step is a broadcast step. Where non-broadcast steps operate on a single server in the selector, broadcast steps run on every server that the selector matches. $step->update() must be run before changes are replicated in the database.

isBroadcast

If this evaluates to true the step becomes a broadcast step. If false the step becomes not a broadcast step..

$step->setEnvironmentId(envGroupId)

Sets the step's environment. If an environment group is set, first the server's environment is applied, then the project's, then the step's, so that the project variables overwrite the server variables if they duplicate, then the step's variables overwrite both the others if they duplicate. $step->update() must be run before changes are replicated in the database.

envGroupId

The environment group ID (from $environmentGroup->getEnvironmentGroupId()) of the environment group that gets applied to the step, or 0 (the default) to just use the project's environment.

$step->setFailChainId(projectId)

Sets a project to run if the execution of this step fails. $step->update() must be run before changes are replicated in the database.

projectId

The project ID (from $project->getProjectId()) of the project that gets run or 0 to have no project start up.

$step->setFailNotify(accessGroupId)

Sets an access group to notify if the execution of this step fails. $step->update() must be run before changes are replicated in the database.

accessGroupId

The access group ID (from $accessGroup->getLevel()) of the access group to notify or 0 to have no access group be notified.

$step->setFailWait(isFailWait)

Sets whether or not fail waiting is set. When a project gets kicked off due to this step failing and failChainId being set, if fail wait is set, the execution of this step will pause until that project finishes before continuing. If fail wait isn't set, the other project will get kicked off and then execution of this project will continue immediately. $step->update() must be run before changes are replicated in the database.

isFailWait

If this evaluates to true, fail wait is set. If false, fail wait is not set.

$step->setFilterSetId(filterId)

Sets the filter set for the step. If a step has a filter set, that filter set is used to set the step's result status. If not, the return code of the step's commands is used to determine step result status. $step->update() must be run before changes are replicated in the database.

filterId

The filter set ID (from $filter->getFilterId()) for the filter to use or 0 to use the step command's return code.

$step->setInlineChainId(projectId)

Sets the project to inline from this step. Inlined projects have their steps inserted after this one when executing this project. $step->update() must be run before changes are replicated in the database.

projectId

The project ID (from $project->getProjectId()) of the project to inline from this step or 0 to not inline a project.

$step->setLevel(accessGroupId)

Sets the access group this step belongs to. If a user does not belong to this access group, they cannot view or edit this step, and when they start this project this step will only be executed if the user has the ``Execute Inaccessible Steps'' permission. $step->update() must be run before changes are replicated in the database.

accessGroupId

The access group ID (from $accessGroup->getLevel()) of the access group this step should belong to or 0 to use the project's access group.

$step->setOnFail(onFail)

Sets the step's on fail settings. This may either be 'HALT', in which case if this step fails the project execution stops immediately with a failure, or 'CONTINUE', in which case if the step fails the project execution continues and (if it encounters no further failures) finishes with a warning. $step->update() must be run before changes are replicated in the database.

onFail

Should either be 'HALT' or 'CONTINUE'

$step->setPassChainId(projectId)

Sets the project to get chained if this step succeeds. $step->update() must be run before changes are replicated in the database.

projectId

The project ID (from $project->getProjectId()) of the project to get chained or 0 to have no project be chained.

$step->setPassNotify(accessGroupId)

Sets the access group that gets notified if this step succeeds. $step->update() must be run before changes are replicated in the database.

accessGroupId

The access group ID (from $accessGroup->getLevel()) of the access group or 0 to have no access group be notified.

$step->setPassWait(isPassWait)

Sets the step's pass wait setting. When a project gets kicked off due to this step succeeding and passChainId being set, if pass wait is set, the execution of this step will pause until that project finishes before continuing, and then this step will pass or fail depending on the result of that project execution. If pass wait isn't set, the other project will get kicked off and then execution of this project will continue immediately and this step's result will be unaffected by the operation of the kicked off project. $step->update() must be run before changes are replicated in the database.

isPassWait

If this evaluates to true, pass wait gets set. If false, pass wait gets unset.

$step->setResource(selectorId)

Sets the selector for this step to run on. $step->update() must be run before changes are replicated in the database.

selectorId

The selector ID (from $selector->getSelectorId()) of the selector to use or the empty string to cause the step to use the project's selector.

$step->setThreaded(threading)

Sets the threading status of the step. Threaded/join steps in the same thread block will run simultaneously up to the project's limit of concurrent threads. A thread block is delimited by either a non-threading step or a join step. $step->update() must be run before changes are replicated in the database.

threading

This may be 'NO' for no threading, 'YES' for threading, or 'JOIN' to make this a join step.

$step->setTimeout(timeout)

Sets the time before no response from the server causes a step failure. $step->update() must be run before changes are replicated in the database.

timeout

The timeout time in seconds.


COPYRIGHT

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