...
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
Starting October 11, 2024 (Zephyr Enterprise 8.2), the Zephyr Enterprise documentation moved from its current location on Atlassian to a dedicated, standalone Zephyr Enterprise documentation page. Please see: https://support.smartbear.com/zephyr-enterprise/docs/en/zephyr-enterprise/zephyr-rest-api/import---synchronize-ldap-crowd-groups.html |
If your Zephyr administrator set up LDAP or Crowd for authentication, you can use Zephyr Enterprise REST API to programmatically import and synchronize LDAP or Crowd groups programmaticallyto 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 (for example, contains or begins with)that is part of the sought-for name. If this parameter is not specified, all the groups will be fetched.
pagesize - explain the max and default size (waiting for a message from Govind)
Both query parameters are optional.
Import one or more groups from LDAP or Crowd
Request URL
...
(optional) the number of groups to be fetched. The default number is 100; the maximum number is 499.
Sample response
For LDAP:
| Code Block | ||
|---|---|---|
| ||
[
{
"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:
| Code Block | ||
|---|---|---|
| ||
[
{
"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:
| Code Block | ||
|---|---|---|
| ||
{ "names": [ |
...
"CN=PerformanceQA,OU=QA"
]
} |
| Info |
|---|
LDAP groups must be specified by their distinguished name (DN). For example: |
For Crowd:
| Code Block | ||
|---|---|---|
| ||
{
"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/importGroupsAndUserssync
Headers
Content-Type: application/json
Sample Request
For LDAP:
| Code Block | ||
|---|---|---|
| ||
{ "names": [ |
...
Authentication
...
"CN=PerformanceQA,OU=QA"
]
} |
For Crowd:
| Code Block | ||
|---|---|---|
| ||
{
"names": [
"crowd-administrators"
]
} |
Response
On success, the operations return operation returns status code 200 and a JSON object containing metadata and found results. The structure of these results varies depending on the sought-for entities, items and so on. Below is a sample response obtained when searching for an execution: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 permissions to perform this operation. |
500 | Unknown internal error. |