Bulk Manipulation of Process Area Membership
Summary
This document provides some script examples of how to manipulate process area membership using cURL. The example snippets assume that you are authenticated to a server configured for Form-based Auth. Appendix A provides an example of how to do this.
Retrieve members (GET)
Retrieve all members from a given project area
set URL="https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw/members" curl -k -b %COOKIES% -o "pa-members.xml" -H "Accept: application/xml" %URL%
Retrieve all members from a given team area
set URL="https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw/team-areas/_leXUYAguEeCb0bE3YI1lQw/members" curl -k -b %COOKIES% -o "ta-members.xml" -H "Accept: application/xml" %URL%
Add members (POST)
Add members to a given project area
Assuming that the file pa-members-to-add.xml contains the XML representation of Members Resource, then the new members can be added into the given project area using the following script:
set URL="https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw/members" curl -D - -k -b %COOKIES% -H "Content-Type: application/xml" -X POST --data-binary @pa-members-to-add.xml %URL%
Add members to a given team area
Assuming that the file ta-members-to-add.xml contains the XML representation of Members Resource, then the new members can be added into the given team area using the following script:
set URL="https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw/team-areas/_leXUYAguEeCb0bE3YI1lQw/members" curl -D - -k -b %COOKIES% -H "Content-Type: application/xml" -X POST --data-binary @ta-members-to-add.xml %URL%
Delete members (DELETE)
Delete all members from a given project area
set URL="https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw/members" curl -D - -k -b %COOKIES% -X DELETE %URL%
Delete all members from a given team area
set URL="https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw/team-areas/_leXUYAguEeCb0bE3YI1lQw/members" curl -D - -k -b %COOKIES% -X DELETE %URL%
Delete a specific member from a given project area
set URL="https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw/members/ADMIN" curl -D - -k -b %COOKIES% -X DELETE %URL%
Delete a specific member from a given team area
set URL="https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw/team-areas/_leXUYAguEeCb0bE3YI1lQw/members/ADMIN" curl -D - -k -b %COOKIES% -X DELETE %URL%
Example: Using cURL to add members from a CSV file
This section provides a completed code example which uses cURL to add members from a CSV file on a Windows platform. The related files can be downloaded here: membership.csv and add-members.bat. The batch file reads the CSV file as the membership input. It then constructs the XML format representation of Members Resource and uses cURL to issue a POST request with the XML body to add members. This example assumes that you already have the URLs of the project/team areas that you want to manipulate and the URLs of the roles in the project/team areas as well. Please refer to Appendix B for how to get the URLs of project/team areas and roles.
The CSV File (membership.csv)
- Each line in this CSV file implies a POST operation that will add a new member with specified roles into a given project area or team area.
- The first column of this CSV file is the ID of the user you want to add. It cannot be empty.
- The second column of this CSV is the URL of a project area or team area to which the user will be added. It cannot be empty.
- For the third column of this CSV, called role columns, each is the URL of a role to which the user will be assigned. These role columns are optional. You can specify any number of roles. If no role column is provided here, the user will be added to the project area or team area without any role assignments.
- Example:
alex,https://localhost:9443/jazz/process/project-areas/_RzqysEraEeCfa_MU9BPqZg,https://localhost:9443/jazz/process/project-areas/_RzqysEraEeCfa_MU9BPqZg/roles/Team%20Member,https://localhost:9443/jazz/process/project-areas/_RzqysEraEeCfa_MU9BPqZg/roles/Team%20Lead jonathan,https://localhost:9443/jazz/process/project-areas/_RzqysEraEeCfa_MU9BPqZg,https://localhost:9443/jazz/process/project-areas/_RzqysEraEeCfa_MU9BPqZg/roles/Team%20Member jonathan,https://localhost:9443/jazz/process/project-areas/_RzqysEraEeCfa_MU9BPqZg/team-areas/_KFtPIEujEeCAEs9nLEPZfA,https://localhost:9443/jazz/process/project-areas/_RzqysEraEeCfa_MU9BPqZg/roles/Team%20Lead thomas,https://localhost:9443/jazz/process/project-areas/_RzqysEraEeCfa_MU9BPqZg/team-areas/_KFtPIEujEeCAEs9nLEPZfA
The Batch File for the Windows Platform (add-members.bat)
This file will read the CSV file line by line. For each line, a POST body (XML representation) will be created accordingly. And then cURL is used to add members to the given process area by issuing a POST to the REST service url.
@echo off rem The account that is used to login the server and call Members REST services. set USER=ADMIN set PASSWORD=ADMIN rem The context root of Jazz Team Server. set CONTEXT_ROOT=https://localhost:9443/jazz rem The input file that defines the memberships. set INPUT_FILE=membership.csv rem Three temporary files. set COOKIES=%cd%cookies.txt set SINGLE_RECORD_FILE=singleRecord.csv set POST_BODY_FILE=postBody.xml rem Connect server echo Connecting... curl -k -c %COOKIES% "%CONTEXT_ROOT%/authenticated/identity" curl -k -L -b %COOKIES% -c %COOKIES% -d j_username=%USER% -d j_password=%PASSWORD% "%CONTEXT_ROOT%/authenticated/j_security_check" rem 1. Read the csv file rem 2. Create post body rem 3. Add members using curl (POST) echo Adding members... setlocal enabledelayedexpansion for /f "tokens=1,2* delims=," %%a in (%INPUT_FILE%) do ( set USER_ID=%%a set PROCESS_AREA_URL=%%b set ROLES=%%c set SERVICE_URL=!PROCESS_AREA_URL!/members rem Contruct post body xml file echo ^<?xml version="1.0" encoding="UTF-8"?^> > %POST_BODY_FILE% echo ^<jp06:members xmlns:jp06="https://jazz.net/xmlns/prod/jazz/process/0.6/"^ > >> %POST_BODY_FILE% echo ^<jp06:member^> >> %POST_BODY_FILE% echo ^<jp06:user-url^>%CONTEXT_ROOT%/users/!USER_ID!^</jp06:user-url^> >> %POST_BODY_FILE% rem Contruct role assignments sections echo ^<jp06:role-assignments^> >> %POST_BODY_FILE% for %%i in (!ROLES!) do ( echo ^<jp06:role-assignment^> >> %POST_BODY_FILE% echo ^<jp06:role-url^>%%i^</jp06:role-url^> >> %POST_BODY_FILE% echo ^</jp06:role-assignment^> >> %POST_BODY_FILE% ) echo ^</jp06:role-assignments^> >> %POST_BODY_FILE% echo ^</jp06:member^> >> %POST_BODY_FILE% echo ^</jp06:members^> >> %POST_BODY_FILE% rem POST to the service url curl -D - -k -b %COOKIES% -H "Content-Type: application/xml" -X POST --data-binary @%POST_BODY_FILE% !SERVICE_URL! ) endlocal echo Ended adding members!
Appendix A: How to get authentication to a Jazz Team Server
This section tells you how to get authentication to a Jazz Team Server on a Windows platform. For a Linux platform, please refer to Authentication For JazzTeamServer Using cURL.
Form based authentication using cURL on a Windows platform
For small command line based tools, a script using cURL to interact with the Jazz Foundation server repository is often sufficient. The two common authentication options for a Jazz Foundation server repository setup are either Basic Auth or Form Based Auth. While Basic Auth is commonly supported by HTTP clients, Form Based Auth can be a bit trickier.
Accessing a project area via URL (e.g. “https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw”) on a server configured for Form Based Auth can be done using this script: (Please follow Appendix B to get the URL of a project area)
@echo off set COOKIES=%cd%cookies.txt rem Change the values of the following parameters as your required. set USER=ADMIN set PASSWORD=ADMIN set HOST="https://localhost:9443/jts" set PROJECT_URL="https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw" curl -k -c %COOKIES% "%HOST%/authenticated/identity" curl -k -L -b %COOKIES% -c %COOKIES% -d j_username=%USER% -d j_password=%PASSWORD% "%HOST%/authenticated/j_security_check" rem If this line returns the XML representation of the given project area, authentication was successful curl -k -b %COOKIES% -H "Accept: application/xml" "%PROJECT_URL%"
The login process (the first two cURL commands in the above example) is necessary only once per session. Any subsequent call can be made using "-b %COOKIES%". The option "-k" is only necessary when the server has a self-signed or expired certificate.
Basic authentication using cURL on a Windows platform
Using cURL with a server configured for Basic Auth is straightforward. E.g. a project area with the URL “https://localhost:9443/jts/process/project-areas/_iQId0AguEeCb0bE3YI1lQw” can be accessed on the command line as: (Please follow Appendix B to get the URL of a project area)
To use all the script examples in this document with Basic Auth, you would typically replace "-b %COOKIES%" with "-u <user:password>".
Appendix B: How to get URLs of project/team areas and roles
You can get any process area related URLs by navigating from the ProjectAreas Admin REST Service. This service is published in the rootservices document. Please refer to the Team Process Rest API for a detailed description of process admin services.
- Find projectAreas service url (e.g. https://localhost:9443/jts/process/project-areas) in the rootservices service (e.g. https://localhost:9443/jts/rootservices) of Jazz Team Server.
- If you are NOT using RRC 3.0, please go to step 4 directly. Otherwise, please follow Appendix C to get the application ID of your application.
- Append “?owningApplicationKey={Your_Application_ID}” to the projectAreas service url.
- Access this projectAreas service url to get all the available project areas. The value of url element in each project-area resource representation is the url of this project area.
- In each project-area resource representation, the value of team-areas-url element is the url of team areas collection resource url. Access this url, you can get all team areas under this project area.
- In each team-area resource representation, the value of url element is the URL of this team area.
- In each project-area or team-area resource representation, the value of roles-url is the URL of roles collection resource URL for this project-area or team-area. Accessing this resource URL, you can get all the roles defined in this project-area or team-area.
- In each role resource representation, the value of url element is the URL of this role.
Appendix C: How to get the application ID in RRC 3.0
- Navigate to main page of RRC3.0 (e.g. https://clmwb:9443/rm/web).
- Click the Manage Project Areas menu item.
- In the address box of the browser, you should be able to find the owningApplicationKey query parameter. This is the ID of this application.
References
About the author
QiongFeng Huang is a software engineer in Process team of Jazz Foundation project. He can be contacted at huangqf@cn.ibm.com.
© Copyright 2011 IBM