Using the projectpermission bulkupdate endpoint / how can I make a user a viewer to all projects in a workspace / create a user and add to all projects in a workspace

Products

• Rally SaaS

Issue/Introduction

This article outlines how the projectpermission bulkupdate endpoint works.

 

Resolution

Authorization

You will need to be an administrator for the project(s) you wish to assign or remove permissions from (this means either Subscription, Workspace, or Project Administrator).

Depending on whether you use an API Key or an authenticated browser session, you sill either need one or two public keys:

ZSESSIONID:

In order to execute the operation from the command line or an external script, the simplest mechanism you can use is an authorization key. Go to (https://rally1.rallydev.com/login), navigate to the API Keys tab, and create a new API key if you need to (or use an existing one). This will be your ZSESSIONID.

Security Token

If you want to execute the operation from within a custom application while logged into CA Agile Central, you may use the current browser authorization without creating any new authorization key. You can discover this by inspecting the network traffic in a browser, and looking for the ZSESSIONID header or cookie - but, in addition, you will need to get a security token. Go to (http://rally1.rallydev.com/slm/webservice/v2.0/security/authorize). This is your Security Token.

Parameters

The input parameters are:

• userOID: The OID (ObjectID) of the User who will be granted new project permissions (or downgraded, if specified - see below for an explanation of this).
• rootProjectOID: The OID of the root of the Project tree of which to change the permissions for the given user. The user's Project permission for all Projects rooted at this one will be changed, unless (see below for further explanation)
  • the Project is on the exclusions list, or
  • the operation would result in a downgrade but the force downgrade parameters was not set to tree.
• excludedRootProjectOIDs: The OIDs of any child Project (or a child of a child, or any ancestor to any level) under the root project which are to be excluded from the permission change operation. This is a comma-delimited list.
  • Explanation: The children of these projects will not be affected by the operation either - the whole subtree rooted at each excludedRootProjectOID is excluded.
• permission: The permission to grant. Must be one of No Access, Viewer, Editor, or Project Admin.
• forceDowngradePermissions: If you intend to downgrade any existing project permissions, set this to true.
  • Explanation: For example, if the user already is Project Admin or Editor for some projects but you wish to downgrade her to Viewer in those cases, set this to true. Otherwise, you can omit it or set it to false, and no project permissions will be downgraded for any permission higher than Viewer.

Invoking the command

To invoke the project change operation, do the following HTTP request:

• Http verb: POST
• URL: https://rally1.rallydev.com/slm/webservice/v2.0/projectpermission/bulkupdate
• Body: form-encoded list of parameters (meaning, the parameters are in the format userOID=123&rootProjectOID=<PROJECT_OID>..., and the MIME type is application/x-www-form-urlencoded)

Invoking using the command line

Here are some examples using two common command-line tools. See the Authentication section above for the values to use for and

... With httpie:

In order to use the Unix/Linux command http (which is the executable for open source program httpie):

If you are using an API Key:

http POST https://rally1.rallydev.com/slm/webservice/v2.0/projectpermission/bulkupdate zsessionid:<API Key - include the underscore before the key> userOID==<USER_OID> rootProjectOID==<PROJECT_OID> excludedRootProjectOIDs==<PROJECT_OID>,<PROJECT_OID> permission=='Project Admin' forceDowngradePermissions==true

If you are using an authenticated browser session:

http POST https://rally1.rallydev.com/slm/webservice/v2.0/projectpermission/bulkupdate\?key=<your-Security-Token> zsessionid:<API Key - include the underscore before the key> userOID==<USER_OID> rootProjectOID==<USER_OID> excludedRootProjectOIDs==<PROJECT_OID>,<PROJECT_OID> permission=='Project Admin' forceDowngradePermissions==true

... With curl:

Alternatively, cURL, supplied with lots of Unix-like systems, can be used like this:

If you are using an API Key:

curl -X POST -H 'zsessionid:<API Key - include the underscore before the key>' --data 'userOID=<USER_OID>&rootProjectOID=<PROJECT_OID>&permission=Project%20Admin&excludedRootProjectOIDs=<PROJECT_OID>,<PROJECT_OID>&forceDowngradePermissions=true' http://localhost:7001/slm/webservice/v2.0/projectpermission/bulkupdate

If you are using an authenticated browser session:

curl -X POST -H 'zsessionid:<API Key - include the underscore before the key>' --data 'userOID=<USER_OID>&rootProjectOID=<PROJECT_OID>&permission=Project%20Admin&excludedRootProjectOIDs=<PROJECT_OID>,<PROJECT_OID>&forceDowngradePermissions=true' http://localhost:7001/slm/webservice/v2.0/projectpermission/bulkupdate\?key\=<your-Security-Token>

Response

After some time (there is potentially a lot of work to do), as long as all went well, you should get a valid HTTP response with status 200, which contains a fairly flat JSON structure containing a small number of string messages which summarize what was done:

{
  "Result": {
    "OperationResult": [
      "Projects Processed: count=3",
      "Permission unchanged (ProjectAdmin): count=1",
      "Changed NoAccess to Editor: count=2"
    ]
  }
}

Of course, you might also get an error. Some expected errors are:

• The user to be modified is already a Workspace Admin or Subscription Admin. These users cannot be modified using this endpoint.
• Lack of permission to the endpoint, or to the objects referenced by the input OIDs.
• Malformed or missing input parameters.
• The endpoint is disabled. In this case, the entire response consists of a single OperationResult with a single Result: 'Disabled'.