teamadmin

Synopsis

An Heroku plug-in named "teamadmin" extending the Heroku Platform API to list, add, update, and delete Heroku Organization/Team members for Team Apps using wildcards.

Prerequisites

This plug-in requires:

1. Heroku User Account - This will require you to have a Heroku Account. If you are part of the EliLillyCo Heroku orginisation then you have a Heroku account
2. Heroku Team/Orginisation Membership - This will be the elilillyco orginisation within Lilly.
3. NodeJS and npm - Please ensure you have the latest version of Node & NPM are installed.
4. Heroku CLI installed - Please ensure you have the Heroku CLI installed.

Pre-Installation

Open a shell/command window.

Verify Node version by typing in the following command at the prompt:

node -v

You should see v8.1.4 or similar. You do not need to have version 8.x to run this Heroku plugin.

Verify npm version by typing in the following command at the prompt:

npm -v

You should see 5.0.3 or similar

Verify Heroku CLI version by typing in the following command at the prompt:

heroku --version

You should see heroku-cli/6.13.9-58fc9ef (windows-x64) node-v8.2.1 or similar. NOTE: please ensure you are running the latest version of the Heroku CLI. Please run heroku update to update your CLI.

Installation of Heroku Plugin.

To use plug-in as a typical user -

Install the teamadmin plugin by typing the following command at the prompt:

heroku plugins:install teamadmin

If you are installing the add-on on the Lilly network, please ensure you have configured the proxy for the Heroku CLI. Please find more information here.

Code Examples

Log in to Heroku by typing the following command at the prompt:

heroku auth:login --sso

Supply your Heroku User Account credentials when prompted (This will be your Lilly account credentials).

Note: The teamadmin plugin is limited by your account and its permissions.

If you attempt to perform any add, delete, or update operation, your Heroku account must have appropriate permission to do so. Otherwise, (portions of) your request may not be executed.

There are 5 commands available in teamadmin:

1. addTeamAppUser - Adds a collaborator to Heroku Team Application(s).
2. deleteTeamAppUser - Deletes a collaborator from Heroku Team Application(s).
3. getTeamAppRoster - Generates a Collaborator roster for Heroku Team Application(s).
4. getTeamMembers - Generates a Member roster for Heroku Team(s).
5. updateTeamAppUser - Updates collaborator permissions for Heroku Team Application(s).

More information can be seen by typing the following at the prompt:

heroku help teamadmin

More information about each command can be seen by typing the following at the prompt:

heroku help teamadmin:COMMAND

for example, heroku help teamadmin:getTeamMembers

Example: addTeamAppUser

With this command it is possible to preview the result by adding the --dryrun flag to the command.

For example, the command entered at the command prompt:

$ heroku teamadmin:addTeamAppUser --dryrun --teams elililly* --apps *test* --email [e-mail] --perms view,deploy

may generate this response:

Request Started.

Add [e-mail]
to Teams named like: elililly*
and Apps named like: *test*

Team: elilillyco
[e-mail] is not a member of this team, skipping team.

Team: elilillyco-evaluation
App: dashboard-testing - User might have been added with 'permissions': view,deploy 
App: automation-test-2 - User might have been added with 'permissions': view,deploy 

Request Completed. Processed 2 team(s) 2 application(s)

Removing the --dryrun flag will actually execute the command with result similar to:

$ heroku teamadmin:addTeamAppUser --teams elililly* --apps *test* --email [e-mail] --perms view,deploy

Request Started.

Add [e-mail]
to Teams named like: elililly*
and Apps named like: *test*

Team: elilillyco
[e-mail] is not a member of this team, skipping team.

Team: elilillyco-evaluation

App: dashboard-testing - User added @ 2017-01-01 12:00:00 AM
App: automation-test-2 - User added @ 2017-01-01 12:00:00 AM

Example: deleteTeamAppUser

With this command it is possible to preview the result by adding the --dryrun flag to the command.

For example, the command entered at the command prompt:

$ heroku teamadmin:deleteTeamAppUser --dryrun --teams elililly* --apps *test* --email [e-mail]

may generate this response:

Request Started.

Delete [e-mail]
from Teams named like: elililly*
and Apps named like: *test*

Team: elilillyco
[e-mail] is not a member of this team, skipping team.

Team: elilillyco-evaluation
App: dashboard-testing - User might have been deleted 
App: automation-test-2 - User might have been deleted 

Request Completed. Processed 2 team(s) 2 application(s)

Removing the --dryrun flag will actually execute the command with result similar to:

$ heroku teamadmin:deleteTeamAppUser --teams elililly* --apps *test* --email [e-mail]

Request Started.

Delete [e-mail]
from Teams named like: elililly*
and Apps named like: *test*

Team: elilillyco
[e-mail] is not a member of this team, skipping team.

Team: elilillyco-evaluation

App: dashboard-testing - User deleted @ 2017-01-01 12:00:00 AM
App: automation-test-2 - User deleted @ 2017-01-01 12:00:00 AM

Example: getTeamAppRoster

A typical command entered at the command prompt:

$ heroku teamadmin:getTeamAppRoster --teams elililly* --apps *test* 

may generate this response:

Team                      Application               Collaborator                            Role         Permissions
------------------------- ------------------------- ---------------------------------------- ------------ ------------
elilillyco                dashboard-testing          [e-mail]                       member       deploy
elilillyco-evaluation     automation-test-2          [e-mail]  owner        owner
elilillyco-evaluation     automation-test-1          [e-mail]                      member       view

Two optional output formats are supported:

flag   description
--csv   generates Comma-Separated Variable (CSV) format 
--json  generates Javascript Object Notation (JSON) format

This command will put a CSV result in a file named 'myroster.csv':

$ heroku teamadmin:getTeamAppRoster --teams elililly* --apps *test* --csv >myroster.csv

This command will put a JSON result in a file named 'myroster.json':

$ heroku teamadmin:getTeamAppRoster --teams elililly* --apps *test* --json >myroster.json

Example: getTeamMembers

A typical command entered at the command prompt:

$ heroku teamadmin:getTeamMembers --teams elililly*

may generate this response:

Team                      Member                          Role
------------------------- ------------------------------- ---------------------------- ------------
elilillyco                 [e-mail]   admin
elilillyco-evaluation      [e-mail]     admin
elilillyco-evaluation      [e-mail]      member

Two optional output formats are supported:

flag    description
------- ---------------------------------------------------
--csv   generates Comma-Separated Variable (CSV) format 
--json  generates Javascript Object Notation (JSON) format

This command will put a CSV result in a file named 'teamlist.csv':

$ heroku teamadmin:getTeamMembers --teams elililly* --csv >teamlist.csv

This command will put a JSON result in a file named 'teamlist.json':

$ heroku teamadmin:getTeamMembers --teams elililly* --json >teamlist.json

Example: updateTeamAppUser

With this command it is possible to preview the result by adding the --dryrun flag to the command.

For example, the command entered at the command prompt:

$ heroku teamadmin:updateTeamAppUser --dryrun --teams elililly* --apps *test* --email [e-mail] --perms view,deploy

may generate this response:

Request Started.

Update [e-mail]
for Teams named like: elililly*
and Apps named like: *test*

Team: elilillyco
[e-mail] is not a member of this team, skipping team.

Team: elilillyco-evaluation
App: dashboard-testing - User might have been updated with 'permissions': view,deploy 
App: automation-test-2 - User might have been updated with 'permissions': view,deploy 

Request Completed. Processed 2 team(s) 2 application(s)

Removing the --dryrun flag will actually execute the command with result similar to:

$ heroku teamadmin:updateTeamAppUser --teams elililly* --apps *test* --email [e-mail] --perms view,deploy

Request Started.

Update [e-mail]
for Teams named like: elililly*
and Apps named like: *test*

Team: elilillyco
[e-mail] is not a member of this team, skipping team.

Team: elilillyco-evaluation

App: dashboard-testing - User updated @ 2017-01-01 12:00:00 AM with permissions view,deploy
App: automation-test-2 - User updated @ 2017-01-01 12:00:00 AM with permissions view,deploy

Motivation

The current set of commands available through the "access" plug-in for Heroku does not support modifying multiple apps with a single request. This plug-in provides this capability with the use of a wildcard character * in the specifications for teams or apps to modify.

Contributing.

To further develop the plug-in -

You will need to link this plugin to heroku after cloning this repository to continue development.

To link the project:

Open a shell/command window

Navigate to the root of the this project

Type the following command at the prompt:

heroku plugins:link

To see a list of already installed plugins type the collowing command at the prompt:

heroku plugins

Tests

This project uses yarn for testing.

Type the following command that the prompt:

yarn test

Contributors

Eli Lilly and Company Responsible IT Organization: GIS - Cirrus and Enterprise Architecture Team Maintainer Group: CIRR_BATCH_ADMIN

License

ISC

Copyright 2017 Eli Lilly and Company

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.