Persona Management

9 minute readReference

Privileged users are able to define a persona that can be assigned to different users or groups based on their role. A persona object includes

  • A collection of pages that the user or group is able to access.

  • A default home page.

When defining a persona, users are able to select pages from different persona categories. As installed, there are a few predefined categories, and it is possible for user to add new categories and pages to them. Additionally, as installed, the system has a few predefined personas that are immutable; however, users are able to copy and customize them. There is one system-wide default persona, that is configurable. Deletion of default persona is not allowed. Default persona is used for users who have no persona assigned to them. A persona is assignable to both users and groups. A single user or group can have multiple personas assigned. * Persona: A persona is a specific role that can be assigned to one or more users, such as Release Manager. It defines the list of pages that a persona can view. * Persona Details: Details for a given persona: categories and pages visible to them. * Persona Categories: A persona category is a container for as set of child persona pages. * Persona Pages: Persona pages are those relevant to a given persona. They are organized into persona categories. * Persona Assignment: Personas are assigned to users and groups.

addPersonaDetail

Creates a new personaDetail object. You must specify a personaName and personaCategoryName.

Arguments Descriptions

personaName

Existing persona name.

personaCategoryName

A valid persona category to create.

Argument type: String

personaPages

(Optional) Specific set of pages to be added to this persona detail object. If this argument is not provided then the category and all pages under will be added to persona.

Argument type: String

Positional arguments

personaName personaCategoryName

Response

Returns a personaDetail object.

ec-perl

syntax: $cmdr->addPersonaDetail(<personaName>, <personaCategoryName>, <optionals>);

Example

$cmdr->addPersonaDetail('Persona1', 'Deploy East' {personaPages => "application","environment"});

ectool

syntax: ectool addPersonaDetail <personaName> <personaCategoryName> [<optionals>]]

Example

ectool addPersonaDetail"Persona1" "Deploy East" --personaPages personaPage1 personaPage2"

removePersonaDetail

Removes a personaDetail object. You must specify a personaName and personaCategoryName.

Arguments Descriptions

personaName

Existing persona name.

personaCategoryName

A valid persona category to remove.

  • If personaCategoryName does not exists, then return.

  • If personaCategoryName exists, it is removed.

  • If personaPages are specified, keep personaCategoryName and remove only pages that are specified.

  • If homePageName is the only page in this category, then remove homepage.

Argument type: String

personaPages

(Optional) Specific set of pages to be removed from this persona detail object. If this argument is not provided then the category and all pages under will be added to persona.

Argument type: String

Positional arguments

personaName personaCategoryName

Response

Returns a personaDetail object.

ec-perl

syntax: $cmdr->removePersonaDetail(<personaName>, <personaCategoryName>, <optionals>);

Example

$cmdr->removePersonaDetail('persona1', 'Deploy East' {personaPages => "application"});

ectool

syntax: ectool removePersonaDetail <personaName> <personaCategoryName> [<optionals>]]

Example

ectool removePersonaDetail"Persona1" "Deploy East" --personaPages personaPage1"

createPersona

Creates a new persona object. You must specify a personaName.

Arguments Descriptions

personaName

The persona name.

Argument type: String

personaDetails

A JSON string providing the personaCategory / personaPages hierarchy for this persona detail. See Example Persona Detail for details.

Argument type: String

homePageName

(Optional) Specify one of pages included in the personaDetails argument.

If not specified, a home page is not defined for this persona.

Argument: String

description

(Optional) User-defined comment text describing this object.

Argument type: String

isDefault

(Optional) < Boolean flag0|1|true|false >

To set this object as the system-wide default persona, set to true ; otherwise, do not specify. For this persona to be the default, it must have a valid home page and at least one underlying personaDetail object.

Argument Type: Boolean

Positional arguments

personaName

Response

Returns a persona object.

=== Example Persona Detail

Below is an example on how to specify the value of the personaDetails argument. It defines two persona categories, each with two persona pages (line breaks added for readability). The personaPages specified under a given category must be valid for that category.

[{"personaCategory":"releaseorchestration", "personaPages":["pipeline","release"]}, {"personaCategory":"deployment", "personaPages":["application","environment"]}]

ec-perl

syntax: $cmdr->createPersona(<personaName>, {<optionals>});

Example

$cmdr->createPersona('persona1', {personaDetails => '{"personaCategory":"releaseorchestration","personaPages":["pipeline","release"]}, {"personaCategory":"deployment","personaPages":["application", "environment"]}', homePageName => application});

ectool

syntax: ectool createPersona <personaName> [<optionals>]

Example

ectool createPersona persona1 --personaDetails '[{"personaCategory":"releaseorchestration","personaPages":["pipeline","release"]}, {"personaCategory":"deployment","personaPages":["application", "environment"]}]' --homePageName application

deletePersona

Deletes the specified persona. You must specify the personaName object to delete.

Arguments Descriptions

personaName

The persona name to delete.

Argument type: String

Positional arguments

personaName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deletePersona(<personaName>);

Example

$cmdr->deletePersona("Release Manager West");

ectool

syntax: ectool deletePersona <personaName>

Example

ectool deletePersona "Release Manager West"

getPersona

Retrieves the specified persona. You must specify the personaName object you wish to retrieve.

Arguments Descriptions

personaName

The name of the persona to retrieve.

Argument type: String

Positional arguments

personaName

Response

Returns a persona object.

ec-perl

syntax: $cmdr->getPersona(<personaName>);

Example

$cmdr->getPersona("Test");

ectool

syntax: ectool getPersona <personaName>

Example

ectool getPersona "Test"

getPersonas

Retrieves persona objects subject to specified criteria sent with the request. If no parameter is specified, all personas in the system are returned, sorted by persona name.

Arguments Descriptions

userName

(Optional) Return all personas associated with this user, sorted by the timestamp when the persona was assigned to the user. Cannot be used with groupName at the same time.

Argument type: string

merged

(Optional) If set to 1 or true, used with userName parameter to merge all personas into one persona; persona name is a space separated string of all persona names for any personas contains personaDetails;

  • If no persona is assigned to user, then default persona is returned: homepage and persona details.

  • If multiple personas are assigned to the user, then the homepage from oldest persona assigned where homepage as not null.

  • If multiple personas are assigned to the user and all personas have home page as null, then the API picks oldest persona assigned that has a personaDetail collection and picks the first page sorted by index— index when page is added to category— from first personaDetail sorted by category index. If there are multiple oldest personas, the first one sorted by name is returned.

  • If multiple personas are assigned to the user and all personas have home page as null and all personas do not have persona detail, then the default persona is returned: homepage and persona details.

Argument type: boolean

excludeGroupPersonas

(Optional)Whether to exclude personas associated with groups. Used with the userName parameter:

  • If set to 1 or true, returns personas assigned directly to the user.

  • If set to 0 or false, all personas are returned that apply to the user, based on personas assigned to the group which user belongs.

Argument type: boolean

groupName

(Optional) Return all personas associated with this group, sorted by Persona object timestamp. Cannot be used with userName at the same time.

Positional arguments

None

Response

Returns zero or more persona objects.

ec-perl

syntax: $cmdr->getPersonas();

Example

$cmdr->getPersonas();

ectool

syntax: ectool getPersonas

Example

ectool getPersonas

modifyPersona

Modifies the specified persona object.

Arguments Descriptions

personaName

The persona name.

Argument type: String

clearDetails

(Optional) < Boolean flag0|1|true|false >

If 1 or true, clear all existing persona details; otherwise, do not specify.

Argument type: Boolean

personaDetails

(Optional) A JSON string providing the personaCategory / personaPages hierarchy for this persona detail. See Example Persona Detail for details.

Argument type: String

homePageName

(Optional) Specify one of pages included in the personaDetails argument.

If not specified, a home page is not defined for this persona.

Argument type: String

description

(Optional) User-defined comment text describing this object.

Argument type: String

isDefault

(Optional) < Boolean flag0|1|true|false >

To set this object as the system-wide default persona, set to true ; otherwise, do not specify. To set this object as the system-wide default persona, set to true ; otherwise, do not specify. For this persona to be the default, it must have a valid home page and at least one underlying personaDetail object.

Argument type: Boolean

newName

(optional) The new name for this persona.

Argument type: String

Positional arguments

personaName

Response

Returns a persona object.

ec-perl

syntax: $cmdr->modifyPersona(<personaName>, {<optionals>});

Example

$cmdr->modifyPersona("Test", {newName => "NewTest"});

ectool

syntax: ectool modifyPersona <personaName> [<optionals>]

Example

ectool modifyPersona "Test" --newName "NewTest"

createPersonaCategory

Creates a new personaCategory object. Specify the name of the new page with personaCategoryName.

Arguments Descriptions

personaCategoryName

The name of the new persona category.

Argument type: String

description

(Optional) User-defined comment text describing this object.

Argument type: String

personaPages

(Optional) One or more persona page names to add to this persona category. Use getPersonaPages for a list of currently defined pages.

Positional arguments

personaCategoryName

Response

Returns the new personaCategory object.

ec-perl

syntax: $cmdr->createPersonaCategory(<personaCategoryName>, {<optionals>});

Example

$cmdr->createPersonaCategory('Deploy East', {personaPages => "application","environment"});

ectool

syntax: ectool createPersonaCategory <personaCategoryName> [<optionals>]

Example

ectool createPersonaCategory "Deploy East" --personaPages "application" "environment"

deletePersonaCategory

Deletes the specified personaCategory object. You must specify the personaCategoryName to delete.

Arguments Descriptions

personaCategoryName

The persona category to delete.

Argument type: String

Positional arguments

personaCategoryName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deletePersonaCategory(<personaCategoryName>);

Example

$cmdr->deletePersona("Deploy East");

ectool

syntax: ectool deletePersonaCategory <personaCategoryName>

Example

ectool deletePersonaCategory "Deploy East"

getPersonaCategory

Retrieves the specified personaCategory object. You must specify the personaCategoryName to retrieve.

Arguments Descriptions

personaCategoryName

The name of the persona category to retrieve. Use getpersonaCategorys to determine personaCategoryName.

Argument type: String

Positional arguments

personaCategoryName

Response

Returns a personaCategory object.

ec-perl

syntax: $cmdr->getpersonaCategory(<personaName>);

Example

$cmdr->getPersonaCategory("Default Pipelines");

ectool

syntax: ectool getPersonaCategory <personaName>

Example

ectool getPersonaCategory "Default Pipelines"

getPersonaCategories

Retrieves all persona categories.

Arguments Descriptions

None

Positional arguments

None

Response

Returns a list of personaCategory objects.

ec-perl

syntax: $cmdr->getPersonaCategories();

Example

$cmdr->getPersonaCategories();

ectool

syntax: ectool getPersonaCategories

Example

ectool getPersonaCategories

modifyPersonaCategory

Modifies the specified personaCategory object. You must specify a personaCategoryName.

Arguments Descriptions

personaCategoryName

The persona category object to modify. Use getPersonaCategories to retrieve a list of existing categories.

Argument type: String

newName

(Optional) New name for personaCategoryName.

Argument type: String

description

(Optional) User-defined comment text describing this object.

Argument type: String

personaPages

(Optional) Create one or more new persona pages if they don’t already exist in this category. Use getPersonaPages for a list of currently defined pages.

clearPages

(Optional) < Boolean flag0|1|true|false >

If 1 or true, remove all pages before adding new pages; otherwise, do not specify.

Argument Type: Boolean

Positional arguments

personaCategoryName

Response

Returns the modified personaCategory object.

ec-perl

syntax: $cmdr->modifyPersonaCategory(<personaCategoryName>, {<optionals>});

Example

$cmdr->modifyPersonaCategory("Release Manager", {newName => "Release Manager West", personaPages=>"application","environment"});

ectool

syntax: ectool modifyPersonaCategory <personaCategoryName> [<optionals>]

Example

ectool modifyPersonaCategory "Release Manager" --newName "Release Manager West" --personaPages "application" "environment"

createPersonaPage

Creates a new personaPage object.

Specify the name of the new page with personaPageName.

Arguments Descriptions

personaPageName

The name of the new persona page.

Argument type: String

description

(Optional) User-defined comment text describing this object.

Argument type: String

url

(Optional) The persona page URL.

Argument type: String

Positional arguments

personaPageName

Response

Returns the new personaPage object.

ec-perl

syntax: $cmdr->createPersonaPage(<personaPageName>, {<optionals>});

Example

$cmdr->createPersonaPage('Default Pipelines', {description => "This is a description."});

ectool

syntax: ectool createPersonaPage <personaPageName> [<optionals>]

Example

ectool createPersonaPage "Default Pipelines" --description "This is a description."

deletePersonaPage

Deletes the specified personaPage object. You must specify the personaPageName to delete.

Arguments Descriptions

personaPageName

The persona page to delete.

Argument type: String

Positional arguments

personaPageName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deletePersonaPage(<personaPageName>);

Example

$cmdr->deletePersonaPage("Default Pipelines");

ectool

syntax: ectool deletePersonaPage <personaPageName>

Example

ectool deletePersonaPage "Default Pipelines"

getPersonaPage

Retrieves the specified personaPage object.

You must specify the personaPageName to retrieve.

Arguments Descriptions

personaPageName

The name of the persona page to retrieve. Use getPersonaPages to determine personaPageName.

Argument type: String

Positional arguments

personaPageName

Response

Returns a personaPage object.

ec-perl

syntax: $cmdr->getPersonaPage(<personaPageName>);

Example

$cmdr->getPersona("Default Pipelines");

ectool

syntax: ectool getPersonaPage <p>

Example

ectool getPersona "Default Pipelines"

getPersonaPages

Retrieves all persona pages.

Arguments Descriptions

None

Positional arguments

None

Response

Returns a list of personaPage objects.

ec-perl

syntax: $cmdr->getPersonaPages();

Example

$cmdr->getPersonaPages();

ectool

syntax: ectool getPersonaPages

Example

ectool getPersonaPages

modifyPersonaPage

Modifies the specified personaPage object. You must specify a personaPageName.

Arguments Descriptions

personaPageName

The persona page name to modify.

Argument type: String

newName

(Optional) New name for an existing personaPage if it is being renamed.

Argument type: String

description

(Optional) User-defined comment text describing this object.

Argument type: String

url

(Optional) The persona page URL.

Argument type: String

Positional arguments

personaPageName

Response

Returns the modified personaPage object.

ec-perl

syntax: $cmdr->modifyPersonaPage(<personaPageName>, {<optionals>});

Example

$cmdr->modifyPersonaPage("Applications", {newName => "v9.2 Applications"});

ectool

syntax: ectool modifyPersonaPage <personaPageName> [optionals]

Example

ectool modifyPersonaPage "Applications" --newName "v9.2 Applications"

assignPersonaToUser

Assigns a list of valid users to an existing persona.

Arguments Descriptions

personaName

The persona name . Use getPersonas for a list of existing personas.

Argument type: String

userNames

One or more user names to assign to personaName. Use getUsers for a list of currently defined users. If the user doesn’t exist in the local database, but is a valid directory user, then a user object is created and saved in the dateabase.

Argument type: String

Positional arguments

personaName

Response

Returns the new user object.

ec-perl

syntax: $cmdr->assignPersonaToUser(<personaName>, {<userNames⇒"user1", "user2", …​>});

Example

$cmdr->assignPersonaToUser('Release Manager', {userNames=> "Joe","Sue"});

ectool

syntax: ectool assignPersonaToUser<personaName> [--userNames>]

Example

ectool assignPersonaToUser "Release Manager" --userNames "Joe" "Sue"

unassignPersonaFromUser

Unassigns the specified list of users from the existing persona.

Arguments Descriptions

personaName

The persona name . Use getPersonas for a list of existing personas and user assignments.

Argument type: String

userNames

One or more user names to unassign from personaName. Use getUsers for a list of currently defined users and their persona assignment.

Argument type: String

Positional arguments

personaName

Response

Returns the new user object.

ec-perl

syntax: $cmdr->unassignPersonaFromUser(<personaName>, {<userNames⇒"user1", "user2", …​>});

Example

$cmdr->unassignPersonaFromUser('Release Manager', {userNames=> "Joe","Sue"});

ectool

syntax: ectool unassignPersonaFromUser<personaName> [--userNames>]

Example

ectool unassignPersonaFromUser "Release Manager" --userNames "Joe" "Sue"

assignPersonaToGroup

Assigns the specified list of groups to an existing persona.

Arguments Descriptions

personaName

The persona name . Use getPersonas for a list of existing personas.

Argument type: String

groupNames

One or more group names to assign to personaName. Use getGroups for a list of currently defined groups. If the group doesn’t exist in the local database, but is a valid directory group, then a group object is created and saved in the datebase.

Argument type: String

Positional arguments

personaName

Response

Returns the new group object.

ec-perl

syntax: $cmdr->assignPersonaToGroup(<personaName>, {<groupNames⇒"group1", "group2", …​>});

Example

$cmdr->assignPersonaToGroup('Release Manager', {groupNames=> "Dev","QA"});

ectool

syntax: ectool assignPersonaToGroup<personaName> [--usergroup

ectool assignPersonaToGroup "Release Manager" --groupNames "Dev" "QA"

unassignPersonaFromGroup

Unassigns the specified groups from the specified persona.

Arguments Descriptions

personaName

The persona name . Use getPersonas for a list of existing personas.

Argument type: String

groupNames

One or more group names to assign to personaName. Use getGroups for a list of currently defined groups.

Argument type: String

Positional arguments

personaName

Response

Returns the new group object.

ec-perl

syntax: $cmdr->unassignPersonaFromGroup (<personaName>, {<groupNames⇒"group1", "group2", …​>});

Example

$cmdr->unassignPersonaFromGroup ('Release Manager', {groupNames=> "Dev"});

ectool

syntax: ectool unassignPersonaFromGroup <personaName> [--usergroup

ectool unassignPersonaFromGroup "Release Manager" --groupNames "Dev"