Copy Project Team Members and Roles to another Project

Introduction

This tutorial will demonstrate how to copy team members and roles from one Project to another. This tutorial is accompanied by a sample powershell script located here. Authorization is provided as a separate script.

Info

Skill level:

Basic

Duration:

10 minutes

Prerequisites

This tutorial assumes that you already have:

  • PowerShell (Recommended 7.0+ version) installed.
  • Access to, or create a new, two projects to use this sample.
  • Your own Desktop/Mobile application/client registered on iTwin Platform.
    • Steps to follow for registering an application can be found here.
    • Make sure that your application/client is associated with Projects API and has projects:read and projects:modify scopes enabled.

1. Request access token for use in Authorization header

Authorization is required for all iTwin Platform API endpoints. See the Authorization README for more information. This tutorial powershell sample already includes code that obtains an authorization token.

These samples require an Authorization Code + PKCE client. Registration of a Desktop/Mobile application/client will give you an Authorization Code + PKCE client.

2. Get project roles from the source project

Getting roles from the source project requires sending a GET request to the https://api.bentley.com/projects/{id}/roles endpoint.

Two headers are required. An authorization header is needed.

Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Example HTTP request


HTTP
GET https://api.bentley.com/projects/38b7e366-bc20-4bb1-9572-0797cf5221f/roles HTTP/1.1
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

On the successful response you will get returned the array of project roles from the source project.

Example response body


JSON
{
  "roles":[
    {
      "roleId":"752b5a3d-b9f2-4845-824a-99dd310b4898",
      "displayName":"Project Reader",
      "description":"Project Reader description"
    },
    {
      "roleId":"ce5399cc-088c-4c48-9f7b-0bff2d72fc25",
      "displayName":"Project Contributor",
      "description":"Project Contributor description"
    }
  ]
}

3. Add each role to the destination project

Adding a role to a project requires sending a POST request to the https://api.bentley.com/projects/{id}/roles endpoint.

Two headers are required. An authorization header is needed.

Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Example HTTP request


HTTP
POST https://api.bentley.com/projects/38b7e366-bc20-4bb1-9572-0797cf5221f/roles HTTP/1.1
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

The request body is specified as JSON and requires displayName and description as properties. The API works with one role at a time.

Example request body


JSON
{
  "displayName":"Sample role",
  "description":"Sample role description"
}

The response returns a JSON object that contains displayName, description and roleId properties. This response body could be used to set roleIds for the users we want to copy from the source project to the destination project.

Example response body


JSON
{
  "role":{
    "roleId":"faa3dca1-a901-4659-9da1-d9f29ddcc288",
    "displayName":"Project Role",
    "description":"An example project role"
  }
}

4. Get project team members from the source project

Getting team members from the source projects requires sending a GET request to the https://api.bentley.com/projects/{id}/members endpoint.

Two headers are required. An authorization header is needed.

Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Example HTTP request


HTTP
GET https://api.bentley.com/projects/38b7e366-bc20-4bb1-9572-0797cf5221f/members HTTP/1.1
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

On the successful response you will get returned the array of project members from the source project.

Example response body


JSON
{
  "members":[
    {
      "userId":"99cf5e21-735c-4598-99eb-fe3940f96353",
      "email":"John.Johnson@org.com",
      "givenName":"John",
      "surname":"Johnson",
      "organization":"Organization Corp.",
      "roles":[
        "Read Access",
        "Write Access"
      ]
    },
    {
      "userId":"25407933-cad2-41a2-acf4-5a074c83046b",
      "email":"Maria.Miller@org.com",
      "givenName":"Maria",
      "surname":"Miller",
      "organization":"Organization Corp.",
      "roles":[
        "Read Access"
      ]
    }
  ],
  "_links":{
    "next":{
      "href":"https://api.bentley.com/projects/806b19d5-c037-48a4-aa98-e297c81453f1/member?$skip=2&$top=2"
    }
  }
}

5. Add each team member to the destination project

Adding a member to a project requires sending a POST request to the https://api.bentley.com/projects/{id}/members endpoint.

Two headers are required. An authorization header is needed.

Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Example HTTP request


HTTP
POST https://api.bentley.com/projects/38b7e366-bc20-4bb1-9572-0797cf5221f/members HTTP/1.1
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

The request body is specified as JSON and requires the userId and roleIds properties. The API works with one user at a time. Multiple roles may be assigned to the user via the roleIds array.

Example request body


JSON
{
  "userId":"john.doe@my-org.com",
  "roleIds":[
    "722b866c-ef99-48e7-8d9b-d59953f2231c"
  ]
}

More resources that you may like

Manage the users, projects, and organizations that interact with your iTwin.
An overview and detailed Projects API documentation.
PowerShell samples demonstrating API endpoints.