ACL Management Commands

27 minute readReference

breakAclInheritance

Breaks access control list (ACL) inheritance at the specified object. When inheritance is broken, only the access control entries directly on the ACL will be considered. You must specify one or more of the following arguments (called locator arguments) to find the object where you want to break inheritance.

Arguments Descriptions

applicationName

The name of the application.

Argument type: String

applicationTierName

The name of the application tier.

Argument type: String

artifactName

The name of the artifact.

Argument type: String

artifactVersionName

The name of the artifact version. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly.

Argument type: String

componentName

The name of the component.

Argument type: String

configName

The name of the email configuration.

Argument type: String

credentialName

The name of the credential that can be one of these formats:

  • relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object. A qualifying project name is required.

  • absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the project where the target object is.

Argument type: String

environmentName

The name of the environment.

Argument type: String

environmentTemplateName

The name of the environment template.

Argument type: String

environmentTemplateTierName

The name of the environment template tier.

Argument type: String

environmentTierName

The name of the environment tier.

Argument type: String

flowName

The name of the flow.

Argument type: String

flowRuntimeName

The name of the flow runtime.

Argument type: String

flowStateName

The name of the flow state.

Argument type: String

flowTransitionName

The name of the flow transition.

Argument type: String

gatewayName

The name of the gateway.

Argument type: String

groupName

The full name of the group. For Active Directory and LDAP, the full name if the full domain name.

Argument type: String

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

notifierName

The name of the email notifier.

Argument type: String

objectId

This is an object identifier returned by findObjects and getObjects. This value is a "handle" only for passing to API commands. The internal structure of this value is subject to change; do not parse this value.

Argument type: String

objectType

(Optional) The type of object.

Argument type: String

path

The property path.

Argument type: String

pipelineName

The name of the pipeline.

Argument type: String

pluginName

The plugin key for a promoted plugin or a plugin key and version for an unpromoted plugin.

Argument type: String

procedureName

The name of the procedure or a path to a procedure that includes the name. If you use this argument, you must also use projectName.

Argument type: String

processName

The name of the process if the container is a process or process step.

Argument type: String

processStepName

The name of the process step if the container is a process step.

Argument type: String

projectName

The name of the project, which can be a path.

The project name is ignored for credentials, procedures, steps, and schedules when they are specified as a path.

Argument type: String

propertySheetId

The unique identifier for a property sheet that is assigned automatically when the property sheet is created.

Argument type: UUID

releaseName

The name of the release.

Argument type: String

repositoryName

The name of the repository used for artifact management.

Argument type: String

resourceName

The name of the resource.

Argument type: String

resourcePoolName

The name of the resource pool.

Argument type: String

resourceTemplateName

The name of the resource template.

scheduleName

The name of a schedule, which can be a path to the schedule. If you use this argument, you must also use projectName.

Argument type: String

snapshotName

The name of the snapshot.

Argument type: String

stageName

The name of the stage in a pipeline.

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, which can be a path to the step. If you use this argument, you must also use projectName and procedureName.

Argument type: String

systemObjectName

The name of the system object. System objects names include: admin|artifactVersions|directory|emailConfigs|log|plugins| server|session|workspaces.

Argument type: SystemObjectName

taskName

The name of the task in a pipeline stage.

Argument type: String

transitionDefinitionName

The name of the transition definition.

Argument type: String

transitionName

The name of the transition.

Argument type: String

userName

The full name of a user. For Active Directory or LDAP, this may be user@domain ).

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workflowName

The name of the workflow.

Argument type: String

workspaceName

The name of a workspace.

Argument type: String

zoneName

The name of the zone.

Argument type: String

Positional arguments

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

Response

None or a status OK message.

ec-perl

syntax: $<object>->breakAclInheritance({<optionals>});

Example

$cmdr->breakAclInheritance ({projectName => "Default", pipelineName => "Q1 2-16 Trading System"});

ectool

syntax: ectool breakAclInheritance [optionals]

Example

ectool breakAclInheritance --projectName "Default" --pipeline "Q1 2-16 Trading System"

checkAccess

Checks access control list (ACL) permission information associated with an object for the current user, including inherited ACLs.

You must specify object locator arguments to define the object where you need to verify access.

Arguments Descriptions

Locator arguments:

applicationName

The name of the application that must be unique among all projects.

Argument type: String

applicationTierName

The name of the application tier.

Argument type: String

artifactName

The name of the artifact.

Argument type: String

artifactVersionName

The name of the artifact version. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched when you specify its name one of these ways. The CloudBees CD/RO server interprets the name form correctly.

Argument type: String

componentName

The name of the component.

Argument type: String

configName

The name of the email configuration.

Argument type: String

credentialName

The name of the credential container of the property sheet that owns the property. Specify credentialName using one of two forms:

  • relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object. This form requires a qualifying project name.

  • absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the project target object project.

Argument type: String

environmentName

The name of the environment that must be unique among all projects.

Argument type: String

environmentTemplateName

The name of the environment template.

Argument type: String

environmentTemplateTierName

The name of the environment template tier.

Argument type: String

environmentTierName

The name of the environment tier.

Argument type: String

flowName

The name of the flow that must be unique within the project.

Argument Type: String

flowRuntimeName

The name of the flow runtime that must be unique within the flow.

Argument Type: String

flowRuntimeStateName

The name of the flow run-time state.

Argument Type: String

flowStateName

Name of the flow state that must be unique within the flow.

Argument Type: String

flowTransitionName

Name of the flow transition that must be unique within the flow state.

Argument Type: String

gatewayName

The name of the gateway.

Argument type: String

groupName

The full name of the group. For Active Directory and LDAP, this is a full domain name.

Argument type: String

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

notifierName

The name of the email notifier.

Argument type: String

objectId

The object identifier returned by findObjects and getObjects. This value is a "handle" only for passing to API commands. The internal structure of this value is subject to change. Do not parse this value.

Argument type: String

objectType

The type of object.

Argument type: String

path

Property path string.

Argument type: String

pipelineName

The name of the pipeline.

Argument type: String

pluginName

The name of the plugin. This is the plugin key for a promoted plugin or a plugin key and version for an unpromoted plugin.

Argument type: String

procedureName

The name of the procedure. It can be be a path to the procedure. When using this procedure, you must also use 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 that must be unqiue among all projects. It can be a path to the project. The project name is ignored for credentials, procedure, steps, and schedules when it is specified as a path.

Argument type: String

propertySheetId

The unique identifier for a property sheet that is assigned automatically when the property sheet is created.

Argument type: UUID

releaseName

The name of the release that owns the property.

Argument type: String

repositoryName

The name of the repository for artifact management.

Argument type: String

resourceName

The name of the resource.

Argument type: String

resourcePoolName

The name of a pool containing one or more resources.

Argument type: String

resourceTemplateName

The name of the resource template.

Argument type: String

scheduleName

The name of the schedule, which can be the path to the schedule. When using this argument, you must also enter projectName.

Argument type: String

searchFilterName

The name of the search filter container of the property sheet.

Argument type: String

snapshotName

The name of the snapshot, which can be the path to the snapshot.

Argument type: String

stageName

The name of the stage.

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. It can be a path to the step. When using this argument, you must also enter projectName and procedureName.

Argument type: String

systemObjectName

System object names include: admin|directory|licensing|log|plugins|priority|projects|.

Argument type: SystemObjectName

taskName

The name of the task in a stage in a pipeline.

Argument type: String

transitionDefinitionName

The name of the transition definition.

Argument type: String

transitionName

The name of the transition.

Argument type: String

userName

The full name of the user. For Active Directory and LDAP, the name can be user@domain.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workflowName

The name of the workflow.

Argument type: String

workspaceName

The name of the workspace.

Argument type: String

zoneName

The name of the zone.

Argument type: String

Positional arguments

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

Response

For the specified object, returns the effective permissions for the current user.

ec-perl

syntax: $<object>->checkAccess ({<optionals>});

Example

$cmdr->checkAccess ({projectName =>"Production"});

ectool

syntax: ectool checkAccess [optionals]

Example

ectool checkAccess –-projectName "Production"

createAclEntry

Creates an access control list entry (ACE) on an object for a given principal.

You must specify the principalType, principalName, and locator options for the object to modify.

Arguments Descriptions

principalType

This is either user, group, or serviceAccount.

Argument type: PrincipalType

principalName

This is either a user, group, or service account name. Project ACL settings are managed as a user type with value project: yourProject (observe spaces).

Argument type: PrincipalName

Locators:

applicationName

The name of the application that must be unique among all projects.

Argument type: String

applicationTierName

The name of the application tier.

Argument type: String

artifactName

The name of the artifact.

Argument type: String

artifactVersionName

The name of the artifact version. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly.

Argument type: String

changePermissionsPrivilege

< allow|deny > –Determines whether the principal can modify access control for the object.

Argument type: Access

componentName

The name of the component.

Argument type: String

configName

The name of the email configuration ( emailConfig ).

Argument type: String

credentialName

The name of the credential specified in one of these formats:

  • relative (for example, "cred1" )—The credential is assumed to be in the project that contains the requested target object.

  • absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the project for the target object.

When using this argument, you must also enter projectName.

Argument type: String

environmentName

The name of the environment that must be unique among all projects.

Argument type: String

environmentTemplateName

The name of the environment template.

Argument type: String

environmentTemplateTierName

The name of the environment template tier.

Argument type: String

environmentTierName

The name of the environment tier.

Argument type: String

executePrivilege

< allow|deny > –Determines whether the principal can invoke this object as part of a job. This privilege is only relevant for a few objects such as procedures and procedure steps.

Argument type: Access

flowName

The name of the flow.

Argument: String

flowRuntimeName

The name of the flow runtime.

Argument: String

flowRuntimeStateName

The name of the flow state.

Argument: String

flowStateName

The name of the flow state.

Argument: String

flowTransitionName

The name of the flow transition.

Argument: String

gatewayName

The name of the gateway.

Argument type: String

groupName

The name of a group.

Argument type: String

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

modifyPrivilege

< allow|deny > –Determines whether the principal can change the contents of the object.

Argument type: Access

notifierName

The name of the email notifier.

Argument type: String

objectId

The object identifier returned by findObjects and getObjects.

Argument type: String

objectType

(Optional) The type of object.

Argument type: String

path

The path to the property.

Argument type: String

pipelineName

The name of the pipeline.

Argument type: String

pluginName

The name of the plugin. It is the plugin key for a promoted plugin or the plugin key and version for an unpromoted plugin.

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.

Argument type: String

propertySheetId

The unique identifier for a property sheet that is assigned automatically when the property sheet is created.

Argument type: UUID

readPrivilege

< allow|deny > –Determines whether the principal can examine the contents of the object.

Argument type: Access

releaseName

The name of the release.

Argument type: String

repositoryName

The name of the repository for artifact management.

Argument type: String

resourceName

The name of the resource.

Argument type: String

resourcePoolName

The name of a pool containing one or more resources.

Argument type: String

resourceTemplateName

The name of the resource template.

Argument type: String

scheduleName

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

Argument type: String

searchFilterName

The name of the search filter container of the property sheet.

Argument type: String

snapshotName

The name of the snapshot.

Argument type: String

stageName

The name of the stage.

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

systemObjectName

System object names include: admin|artifacts|directory|emailConfigs|forceAbort|licensing| log|plugins|priority|projects|repositories|resources|server| session|test|workspaces|zonesAndGateways

Argument type: SystemObjectName

taskName

The name of the task.

Argument type: String

transitionDefinitionName

The name of the transition definition.

Argument type: String

transitionName

The name of the transition.

Argument type: String

userName

The full name of the user.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workflowName

The name of the workflow.

Argument type: String

workspaceName

The name of the workspace.

Argument type: String

zoneName

The name of the zone.

Argument type: String

Positional arguments

principalType, principalName, and locator options.

Response

None or a status OK message.

ec-perl

syntax: $<object>->createAclEntry(<principalType> <principalName>, {<optionals>});

Example

$cmdr\->createAclEntry("user", "j smith", {"projectName"=>"Sample Project", "readPrivilege"=>"allow", "modifyPrivilege"=>"deny", "executePrivilege"=>"deny", "changePermissionsPrivilege"=>"deny"});

ectool

syntax: ectool createAclEntry <principalType> <principalName> [optionals]

Example

ectool createAclEntry user "j smith" --projectName "Sample Project" --readPrivilege allow --modifyPrivilege deny --executePrivilege deny --changePermissionsPrivilege deny

deleteAclEntry

Deletes an access control entry (ACE) in an access control list (ACL) on an object for a given principal (user or group).

You must specify principalType, principalName, and locator arguments.

Arguments Descriptions

principalType

This is either user, group, or serviceAccount.

Argument type: PrincipalType

principalName

This is either a user, group, or service account name. Project ACL settings are managed as a user type with value project: yourProject (observe spaces).

Argument type: PrincipalName

applicationName

(Optional) The name of the application that must be unique among all projects.

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

(Optional) The name of the artifact version. An artifact version name is interpreted by the server as the ` artifactVersionName` attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly.

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration.

Argument type: String

credentialName

(Optional) The name of the credential specified in one of these formats:

  • relative (for example, "cred1" )—The credential is assumed to be in the project that contains the requested target object.

  • absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the project for the target object.

Argument type: String

environmentName

(Optional) The name of the environment that must be unique among all projects.

Argument type: String

environmentTemplateName

(Optional) The name of the environment template that must be unique among all projects.

Argument type: String

environmentTemplateTierName

(Optional) Name of the environment template tier that must be unique among all tiers for the environment template.

Argument Type: String

environmentTierName

(Optional) The name of the environment tier.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowRuntimeName

(Optional) Name of the flow runtime.

Argument Type: String

flowRuntimeStateName

(Optional) Name of the flow state.

Argument Type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

flowTransitionName

(Optional) The name of the flow transition.

Argument type: String

gatewayName

(Optional) The name of the gateway.

Argument type: String

groupName

(Optional) The name of a group whose ACL entry you want to delete.

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

notifierName

(Optional) The name of the email notifier with the ACE that you want to delete.

Argument type: String

objectId

(Optional) An object identifier returned by findObjects and getObjects.

Argument type: String

objectType

(Optional) The type of object.

Argument type: String

path

(Optional) Path to the property.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin with the ACE that you want to delete.

Argument type: String

procedureName

(Optional) The name of the procedure with the ACE that you want to delete. When you use this argument, you must also enter projectName for the project of which this procedure is a member.

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 with the ACE that you want to delete.

Argument type: String

propertySheetId

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

Argument type: UUID

releaseName

(Optional) The name of the release which owns the property.

Argument type: String

repositoryName

(Optional) The name of the repository for artifact management.

Argument type: String

resourceName

(Optional) The name of the resource with the ACE that you want to delete.

Argument type: String

resourcePoolName

(Optional) The name of a pool containing one or more resources.

Argument type: String

resourceTemplateName

(Optional) Name of the resource template.

Argument Type: String

scheduleName

(Optional) The name of the schedule with the ACE that you want to delete. When you use this argument, you must also enter the projectName from which this schedule runs procedures.

Argument type: String

searchFilterName

(Optional) The name of the search filter container of the property sheet.

Argument type: String

snapshotName

(Optional) The name of the snapshot.

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 with the ACE that you want to delete. When using this argument, you must also enter projectName and procedureName to indicate where this step resides.

Argument type: String

systemObjectName

(Optional) System object names include: admin|directory|licensing|log|plugins|priority|projects|resources|server|session|workspaces

Argument type: SystemObjectName

taskName

(Optional) The name of the task.

Argument type: String

transitionDefinitionName

(Optional) The name of the transition definition.

Argument type: String

transitionName

(Optional) The name of the transition.

Argument type: String

userName

(Optional) The name of the user with the ACE that you want to delete.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

workspaceName

(Optional) The name of the workspace with the ACL entry that you want to delete.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

principalType, principalName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteAclEntry(<principalType>, <principalName>, {<optionals>});

Example

$cmdr->deleteAclEntry('user', 'j smith', {projectName => 'Default'});

ectool

syntax: ` ectool deleteAclEntry <principalType> <principalName> [optionals]`

Example

ectool deleteAclEntry "user" "j smith" --projectName "Default"

getAccess

Retrieves access control list (ACL) information associated with an object, including inherited ACLs.

You must specify object locators to find the object to which you need to verify access.

Arguments Descriptions

applicationName

(Optional) The name of the application that must be unique among all projects.

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

(Optional) The name of the artifact version. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly.

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration.

Argument type: String

credentialName

(Optional) The name of the credential specified in one of these formats:

  • relative (for example, "cred1" )—The credential is assumed to be in the project that contains the requested target object.

  • absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the project for the target object.

Argument type: String

emulateRestoreInheritance

(Optional) < Boolean flag— 0|1|true|false > Whether or not to include one level of broken inheritance, if it exists. If set to true or 1, this argument returns ACL information to what it would be if inheritance were restored on this object. Use to preview how access would look like if the lost level of broken inheritance is restored.

Argument type: Boolean

environmentName

(Optional) The name of the environment that must be unique among all projects.

Argument type: String

environmentTemplateName

(Optional) Name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) Name of the environment template tier.

Argument type: String

environmentTierName

(Optional) The name of the environment tier.

Argument type: String

flowName

(Optional) The name of the flow.

Argument type: String

flowRuntimeName

(Optional) Name of the flow runtime.

Argument Type: String

flowRuntimeStateName

(Optional) Name of the flow state.

Argument Type: String

flowStateName

(Optional) The name of the flow state.

Argument type: String

flowTransitionName

(Optional) The name of the flow transition.

Argument type: String

gatewayName

(Optional) The name of the gateway.

Argument type: String

groupName

(Optional) The name of the group.

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

notifierName

(Optional) The name of the email notifier with the ACL.

Argument type: String

objectId

(Optional) An object identifier returned by findObjects and getObjects.

Argument type: String

objectType

(Optional) The type of object.

Argument type: String

path

(Optional) Property path.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin with the ACL.

Argument type: String

procedureName

(Optional) The name of the procedure with the ACL. 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 that contains the ACL that must be unique among all projects.

Argument type: String

propertySheetId

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

Argument type: UUID

releaseName

(Optional) The name of the release.

Argument type: String

repositoryName

(Optional)The name of the repository for artifact management.

Argument type: String

resourceName

(Optional)The name of the resource with the ACL.

Argument type: String

resourcePoolName

(Optional)The name of a pool with one or more resources.

Argument type: String

resourceTemplateName

(Optional) Name of the resource template.

Argument type: String

scheduleName

(Optional) The name of the schedule with the ACL. Also requires projectName.

searchFilterName

(Optional) The name of the search filter container of the property sheet.

Argument type: String

snapshotName

(Optional) The name of a snapshot.

Argument type: String

stageName

(Optional) The name of the stage definition.

Argument type: String

stateDefinitionName

(Optional) The name of the state definition.

stateName

(Optional) The name of the state.

stepName

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

Argument type: String

systemObjectName

(Optional) System objects include: admin|artifactVersions|directory|emailConfigs|log|plugins| server|session|workspaces

Argument type: SystemObjectName

taskName

(Optional) The name of the task.

Argument type: String

transitionDefinitionName

(Optional) The name of the transition definition.

Argument type: String

transitionName

(Optional) The name of the transition.

Argument type: String

userName

(Optional) The name of the user with the ACL.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

workspaceName

(Optional) The name of the workspace with the ACL.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

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

Response

One or more object elements, each consisting of one or more aclEntry elements. Each object represents an object in the ACL inheritance chain starting with the most specific object. Each aclEntry identifies a user or group and the privileges granted or denied by the entry, and includes a breakInheritance element if applicable.

ec-perl

syntax: $<object>->getAccess({<optionals>});

Example

$cmdr->getAccess({projectName => "Quarterly Summary Results"});

ectool

syntax: ` ectool getAccess [optionals]`

Example

ectool getAccess --projectName "Quarterly Summary Results"

getAclEntry

Retrieves an access control entry (ACE) list on an object for a given principal.

You must specify a principalType, principalName, and an object locator to specify the ACE.

Arguments Descriptions

principalType

This is either user, group, or serviceAccount.

Argument type: PrincipalType

principalName

This is either a user, group, or service account name. Project ACL settings are managed as a user type with value project: yourProject (observe spaces).

Argument type: PrincipalName

applicationName

(Optional) The name of the application that must be unique among all projects.

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

(Optional) The name of the artifact version. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly.

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration.

Argument type: String

credentialName

(Optional) The name of the credential specified in one of these formats:

  • relative (for example, "cred1" )—The credential is assumed to be in the project that contains the requested target object.

  • absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the project for the target object.

Argument type: String

dashboardName

(Optional) The name of the dashboard.

Argument type: String

environmentName

(Optional) The name of the environment that must be unique among all projects.

Argument type: String

environmentTemplateName

(Optional) Name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) Name of the environment template tier.

Argument type: String

environmentTierName

(Optional) Name of the environment tier.

Argument type: String

flowName

Name of the flow that must be unique within the project.

Argument Type: String

flowRuntimeName

(Optional) Name of the flow runtime.

Argument Type: String

flowRuntimeStateName

(Optional) Name of the flow state.

Argument Type: String

flowStateName

Name of the flow state that must be unique within the flow.

Argument Type: String

flowTransitionName

Name of the flow transition that must be unique within the flow state.

Argument Type: String

gatewayName

(Optional) The name of the gateway.

Argument type: String

groupName

(Optional) The name of the group.

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: String

notifierName

(Optional) The name of the email notifier.

Argument type: String

objectId

(Optional) This is an object identifier returned by findObjects and getObjects.

Argument type: String

objectType

(Optional) The type of object.

Argument type: String

path

(Optional) The property path.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin. The plugin key for a promoted plugin or the plugin key and version for an unpromoted plugin.

Argument type: String

procedureName

(Optional) The name of the procedure with the ACL. 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.

Argument type: String

propertySheetId

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

Argument type: String

releaseName

(Optional) The name of the release.

Argument type: String

repositoryName

(Optional) The name of the repository for artifact management.

Argument type: UUID

resourceName

(Optional) The name of the resource.

Argument type: String

resourcePoolName

(Optional) The name of a pool containing one or more resources.

Argument type: String

resourceTemplateName

(Optional) The name of the resource template.

Argument type: String

scheduleName

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

Argument type: String

searchFilterName

(Optional) The name of the search filter container of the property sheet.

Argument type: String

snapshotName

(Optional) The name of a snapshot.

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

systemObjectName

(Optional) System objects include: admin|artifactVersions|directory|emailConfigs|log|plugins| server|session|workspaces

Argument type: SystemObjectName

taskName

(Optional) The name of the task.

Argument type: String

transitionDefinitionName

(Optional) The name of the transition definition.

Argument type: String

transitionName

(Optional) The name of the transition.

Argument type: String

userName

(Optional) The full name of the user.

Argument type: String

widgetName

(Optional) The name of a widget.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

workspaceName

(Optional) The name of the workspace.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

principalType, principalName, and arguments to specify the object, beginning with the top-level object locator.

Response

One aclEntry element.

ec-perl

syntax: $cmdr->getAclEntry(<principalType>, < principalName>, {<optionals>});

Example

$cmdr->getAclEntry("user", "j smith", {projectName => "Sample Project"});

ectool

syntax: ectool getAclEntry <principalType> <principalName> [optionals]

Example

ectool getAclEntry user "j smith" --projectName "Sample Project"

modifyAclEntry

Modifies an ACE (access control entry) in an access control list (ACL) on an object for a given principal.

If a privilege is not specified, an object inherits it from its parent object ACL.

You must specify principalType, principalName, and object locator arguments to identify the target ACL.

Arguments Descriptions

principalType

Type of principal for this access control entry: user or group.

Argument type: PrincipalType

principalName

Name of the user or group for this access control entry. Project ACL settings are managed as a user type with value project: yourProject (observe spaces).

Argument type: PrincipalName

applicationName

(Optional) The name of the application that must be unique among all projects.

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

(Optional) The name of the artifact version. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly.

Argument type: String

changePermissionsPrivilege

(Optional) < allow|deny > –Determines whether the principal can modify access control for the object.

Argument type: Access

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration.

Argument type: String

credentialName

(Optional) The name of the credential specified in one of these formats:

  • relative (for example, "cred1" )—The credential is assumed to be in the project that contains the requested target object.

  • absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the project for the target object.

Argument type: String

environmentName

(Optional) The name of the environment that must be unique among all projects.

Argument type: String

environmentTemplateName

(Optional) The name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) The name of the environment template tier.

Argument type: String

environmentTierName

(Optional) The name of the environment tier.

Argument type: String

executePrivilege

(Optional) < allow|deny > –Determines whether the principal can invoke this object as part of a job. This privilege is only relevant for a few objects such as procedures and procedure steps.

Argument type: Access

flowName

(Optional) The name of the flow that must be unique within the project.

Argument Type: String

flowRuntimeName

(Optional) The name of the flow runtime.

Argument Type: String

flowRuntimeStateName

(Optional) The name of the flow state.

Argument Type: String

flowStateName

(Optional) The name of the flow state that must be unique within the flow.

Argument Type: String

flowTransitionName

(Optional) The name of the flow transition that must be unique within the flow state.

Argument Type: String

gatewayName

(Optional) The name of the gateway.

Argument type: String

groupName

(Optional) The name of the group with the ACE.

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

modifyPrivilege

(Optional) < allow|deny > –Determines whether the principal can change the contents of the object.

Argument type: Access

notifierName

(Optional) The name of the email notifier with the ACE.

Argument type: String

objectId

(Optional) The object identifier returned by findObjects and getObjects.

Argument type: String

objectType

(Optional) The type of object.

Argument type: String

path

(Optional) The property path.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin with the ACE.

Argument type: String

procedureName

(Optional) The name of the procedure with the ACL entry. 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 with the ACE.

Argument type: String

propertySheetId

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

Argument type: UUID

readPrivilege

(Optional) < allow|deny > –Determines whether the principal can examine the contents of the object.

Argument type: Access

releaseName

(Optional) The name of the release.

Argument type: String

repositoryName

(Optional) The name of the repository for artifact management.

Argument type: String

resourceName

(Optional) The name of the resource containing the ACE.

Argument type: String

resourcePoolName

(Optional) The name of a resource pool.

Argument type: String

resourceTemplateName

(Optional) The name of the resource template.

Argument type: String

scheduleName

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

Argument type: String

searchFilterName

(Optional) The name of the search filter container of the property sheet.

Argument type: String

snapshotName

(Optional) The name of a snapshot.

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) The name of the step with the ACE. When using this argument, you must also enter projectName.

Argument type: String

systemObjectName

(Optional) System object names include: admin|artifacts|directory|emailConfigs|forceAbort|licensing|log|plugins|priority|projects|repositories|resources|server|session|test|workspaces|zonesAndGateways

Argument type: SystemObjectName

taskName

(Optional) The name of the task in a stage in a pipeline.

Argument type: String

transitionDefinitionName

(Optional) The name of the transition definition.

Argument type: String

transitionName

(Optional) The name of the transition.

Argument type: String

userName

(Optional) The username containing the ACE.

Argument type: String

workflowDefinitionName

The name of the workflow definition.

Argument type: String

workflowName

The name of the workflow.

Argument type: String

workspaceName

The name of the workspace containing the ACE.

Argument type: String

zoneName

The name of the zone.

Argument type: String

Positional arguments

principalType, ` principalName`, and arguments to specify the object, beginning with the top-level object locator

Response

Retrieves a modified ACE element..

ec-perl

syntax: $cmdr->modifyAclEntry(<principalType>, <principalName>, {<optionals>});

Example

$cmdr->modifyAclEntry("user", "j smith", {projectName => "Sample Project", snapshotName => "LastGood", });

ectool

syntax: ectool modifyAclEntry <principalType> <principalName> [optionals]

Example

ectool modifyAclEntry "user" "j smith" --projectName "Sample Project" --snapshotName "LastGood"

restoreAclInheritance

Restores the ACL (access control list) inheritance for the specified object.

You must use object locators to specify the object where you want to restore ACL inheritance.
Arguments Descriptions

applicationName

(Optional) The name of the application that must be unique among all projects.

Argument type: String

applicationTierName

(Optional) The name of the application tier.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

artifactVersionName

(Optional) The name of the artifact version. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly.

Argument type: String

componentName

(Optional) The name of the component.

Argument type: String

configName

(Optional) The name of the email configuration.

Argument type: String

credentialName

(Optional) The name of the credential specified in one of these formats:

  • relative (for example, "cred1" )—The credential is assumed to be in the project that contains the requested target object.

  • absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the project for the target object.

When using this argument, you must also enter projectName.

Argument type: String

environmentName

(Optional) The name of the environment that must be unique among all projects.

Argument type: String

environmentTemplateName

Name of the environment template.

Argument type: String

environmentTemplateTierName

(Optional) Name of the environment template tier.

Argument type: String

environmentTierName

(Optional) The name of the environment tier.

Argument type: String

flowName

(Optional) Name of the flow that must be unique within the project.

Argument Type: String

flowRuntimeName

(Optional) Name of the flow runtime.

Argument Type: String

flowRuntimeStateName

(Optional) Name of the flow state.

Argument Type: String

flowStateName

(Optional) Name of the flow state that must be unique within the flow.

Argument Type: String

flowTransitionName

Name of the flow transition that must be unique within the flow state.

Argument Type: String

gatewayName

(Optional) The name of the gateway.

Argument type: String

groupName

(Optional) The name of the group with the ACL inheritance that you want to restore.

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

notifierName

(Optional) The name of the email notifier with the ACL inheritance that you want to restore. Also requires ` projectName` and procedureName ; projectName, procedureName, and stepName ; jobId or jobStepId

Argument type: String

objectId

(Optional) This is an object identifier returned by findObjects and getObjects.

Argument type: String

objectType

(Optional) The type of object.

Argument type: String

path

(Optional) Property path.

Argument type: String

pipelineName

(Optional) The name of the pipeline.

Argument type: String

pluginName

(Optional) The name of the plugin with the ACL inheritance that you want to restore.

Argument type: String

procedureName

(Optional) The name of the procedure with the ACL inheritance that you want to restore. 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 with the ACL inheritance that you want to restore.

Argument type: String

propertySheetId

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

Argument type: UUID

releaseName

(Optional) The name of the release.

Argument type: String

repositoryName

(Optional) The name of the repository for artifact management.

Argument type: String

resourceName

(Optional) The name of the resource whose ACL inheritance you want to restore.

Argument type: String

resourcePoolName

(Optional) The name of a pool containing one or more resources.

Argument type: String

resourceTemplateName

(Optional) Name of the resource template.

Argument type: String

scheduleName

(Optional) The name of the schedule with the ACL inheritance that you want to restore. When using this argument, you must also enter projectName.

Argument type: String

searchFilterName

(Optional) The name of the search filter container of the property sheet.

Argument type: String

snapshotName

(Optional) The name of a snapshot.

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

(Optional) The name of the state.

Argument type: String

stepName

(Optional) The name of the step with the ACL inheritance that you want to restore. When using this argument, you must also enter projectName and procedureName.

Argument type: String

systemObjectName

(Optional) The name of the system object whose ACL inheritance you want to restore. System objects include: admin|artifactVersions|directory|emailConfigs|log|plugins|server|session|workspaces

Argument type: SystemObjectName

taskName

(Optional) The name of the task.

Argument type: String

transitionDefinitionName

(Optional) The name of the transition definition.

Argument type: String

transitionName

(Optional) The name of the transition.

Argument type: String

userName

(Optional) The name of the user with the ACL inheritance that you want to restore.

Argument type: String

workflowDefinitionName

(Optional) The name of the workflow definition.

Argument type: String

workflowName

(Optional) The name of the workflow.

Argument type: String

workspaceName

(Optional) The name of the workspace with the ACL inheritance that you want to restore.

Argument type: String

zoneName

(Optional) The name of the zone.

Argument type: String

Positional arguments

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

Response

None or a status OK message.

ec-perl

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

Example

$cmdr->restoreAclInheritance({projectName => "Software tools"});

ectool

syntax: ectool restoreAclInheritance [optionals]

Example

ectool restoreAclInheritance --projectName "Software tools"