Import & Synchronize LDAP/Crowd Groups

If your Zephyr administrator set up LDAP or Crowd for authentication, you can use Zephyr Enterprise REST API to programmatically import LDAP or Crowd groups to Zephyr and synchronize them as, for example, part of some automated operations.

Base URL

The base URL for API calls is:

http(s)://SERVER[:PORT]/flex/services/rest/latest

or in case of Zephyr Enterprise Cloud instances:

https://YOUR_SUBDOMAIN.yourzephyr.com/flex/services/rest/latest

Authentication

You can authenticate your requests by using one of the methods described in the Zephyr REST API topic.

Get a list of groups

Request URL

GET http(s)://{ZEPHYR-SERVER}/flex/services/rest/v3/externalGroup/search?name=SEARCH_STRING&pagesize=100

Request parameters

name - (optional) a substring that is part of the sought-for name. If this parameter is not specified, all the groups will be fetched.

pagesize - (optional) the number of groups to be fetched. The default number is 100; the maximum number is 499.

Sample response

For LDAP:

[
    {
        "name": "FunctionalQA",
        "disabled": false,
        "externalGroupId": "CN=FunctionalQA,OU=QA"
    },
    {
        "name": "ClientDev",
        "disabled": false,
        "externalGroupId": "CN=ClientDev,OU=DEV"
    },
    {
        "name": "FullStackDev",
        "disabled": false,
        "externalGroupId": "CN=FullStackDev,OU=DEV"
    },
    {
        "name": "zeSupport",
        "disabled": false,
        "externalGroupId": "CN=zeSupport,OU=TQS,OU=QM,OU=S,OU=Support"
    },
    {
        "name": "TestA",
        "disabled": false,
        "externalGroupId": "CN=TestA,OU=DEV"
    },
    {
        "name": "Test B",
        "disabled": false,
        "externalGroupId": "CN=Test B,OU=DEV"
    },
    {
        "name": "Test1QA",
        "disabled": false,
        "externalGroupId": "CN=Test1QA,OU=QA"
    },
    {
        "name": "Test2QA",
        "disabled": false,
        "externalGroupId": "CN=Test2QA,OU=QA"
    },
    {
        "name": "Automation_QA",
        "disabled": false,
        "externalGroupId": "CN=Automation_QA,OU=QA"
    }
]

For Crowd:

[
    {
        "name": "Automation_QA",
        "description": "",
        "disabled": false,
        "externalGroupId": "Automation_QA"
    },
    {
        "name": "crowd-administrators",
        "description": "",
        "disabled": false,
        "externalGroupId": "crowd-administrators"
    },
    {
        "name": "data",
        "description": "32523535235",
        "disabled": false,
        "externalGroupId": "data"
    },
    {
        "name": "dt",
        "description": "dt",
        "disabled": false,
        "externalGroupId": "dt"
    },
    {
        "name": "jira-administrators",
        "description": "",
        "disabled": false,
        "externalGroupId": "jira-administrators"
    },
    {
        "name": "jira-software-users",
        "description": "",
        "disabled": false,
        "externalGroupId": "jira-software-users"
    },
    {
        "name": "NCR Test",
        "description": "",
        "disabled": false,
        "externalGroupId": "NCR Test"
    },
    {
        "name": "NCR Test1",
        "description": "",
        "disabled": false,
        "externalGroupId": "NCR Test1"
    },
    {
        "name": "test",
        "description": "",
        "disabled": false,
        "externalGroupId": "test"
    },
    {
        "name": "test1",
        "description": "",
        "disabled": false,
        "externalGroupId": "test1"
    },
    {
        "name": "white box",
        "description": "white box",
        "disabled": false,
        "externalGroupId": "white box"
    }
]

Import one or more groups

Request URL

POST http(s)://{ZEPHYR-SERVER}/flex/services/rest/v3/externalGroup/importGroupsAndUsers

Headers

Content-Type: application/json

Sample Request

For LDAP:

{
    "names": [
        "CN=PerformanceQA,OU=QA"
    ]
}

Note

LDAP groups must be specified by their distinguished name (DN). For example: CN=Automation_QA,OU=QA.

For Crowd:

{
    "names": [
        "Automation_QA"
    ]
}

Response

On success, the operation returns status code 200 and the job ID in the response body (for example, 100). To get the job details and progress, send the following GET request:

http://{ZEPHYR-SERVER}/flex/services/rest/v3/jobprogress/{job_ID}

Example:

http://yourzephyr.com/flex/services/rest/v3/jobprogress/100

For information on other response codes, see below.

Synchronize one or more groups

Synchronization is needed when a new group is added to or an existing group is deleted from LDAP or Crowd. It should be done to update the list of groups in Zephyr.

Request URL

PUT http(s)://{ZEPHYR-SERVER}/flex/services/rest/v3/externalGroup/sync

Headers

Content-Type: application/json

Sample Request

For LDAP:

{
    "names": [
        "CN=PerformanceQA,OU=QA"
    ]
}

For Crowd:

{
    "names": [
       "crowd-administrators"
    ]
}

Response

On success, the operation returns status code 200 and the job ID in the response body (for example, 101). To get the job details and progress, send the following GET request:

http://{ZEPHYR-SERVER}/flex/services/rest/v3/jobprogress/{job_ID}

Example:

http://yourzephyr.com/flex/services/rest/v3/jobprogress/101

For information on other response codes, see below.

Response codes

HTTP Status Code

Description

200

The request completed successfully.

400

Bad request.

401

The authentication token is missing.

403

The user has no permission to perform this operation.

500

Unknown internal error.

In this section:
© 2024
Publication date: