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"
    ]
}

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

For Crowd:

{
    "names": [
        "Automation_QA"
    ]
}

Sample response

100

On success, the operation returns status code 200 and a JSON object containing the job ID. 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

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"
    ]
}

Sample response

101

On success, the operation returns status code 200 and a JSON object containing the job ID. 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

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 permissions to perform this operation.

500

Unknown internal error.