Examples of using the Business Teams Service REST API

View the examples of how to use Business Teams Service REST APIs.

Creating a new team

To create a new team, you can use the following REST API call:

POST /teamserver/rest/teams

You must pass the team definition as input parameters in a JSON object in the request body of the call. A team definition consists of the team's distinguished and optional display name, optional description, and its members, which can consist of LDAP users, LDAP groups, and other teams. The distinguished name is required, and must be unique, which helps when you have to move a team from a test system to a production system. It is meaningful to follow the DN naming rules when creating distinguished names for teams. It is also advisable to provide a display name when creating a new team to make it easy to look-up when searching for a particular team.

To add users and groups as member of the new team, you must provide their distinguished names from the connected LDAP repository. To include another team, you must specify its internal ID (uuid).

For example, to create a new team that is built out of the users "John Doe", "Joe Bloggs" and the group "Department 4711" you can pass the following JSON object:

{
  "distinguishedName": "cn=Authors,ou=bpm,dc=example,dc=com",
  "displayName": "Authors",
  "description": "This team writes the technical documentation.",
  "users": [
    "cn=John Doe,ou=User,dc=example,dc=com",
    "cn=Joe Bloggs,ou=User,dc=example,dc=com"
  ],
  "groups": [
    "cn=Department 4711,ou=Group,dc=example,dc=com"
  ]
}

The response includes the internal ID (uuid) of the new team, which you might need, for example, to modify the team or add this team as a member of another team:

{
  "description": "This team writes the technical documentation.",
  "displayName": "Authors",
  "distinguishedName": "cn=authors,ou=bpm,dc=example,dc=com",
  "groups": [
    "cn=Department 4711,ou=Group,dc=example,dc=com"
  ],
  "metadata": {
    "created": "2020-02-18T14:28:33.040Z",
    "lastModified": "2020-02-18T14:28:33.040Z"
  },
  "teams": [],
  "users": [
    "cn=Joe Bloggs,ou=User,dc=example,dc=com",
    "cn=John Doe,ou=User,dc=example,dc=com"
  ],
  "uuid": "e60d02c1-7e55-4534-81f8-b3c079e83ee3"
}

Creating a new team that includes an existing team

To create another team that includes the "Authors" as a team member, you would call POST /teamserver/rest/teams with the following JSON object:

{
  "distinguishedName": "cn=Reviewers,ou=bpm,dc=example,dc=com",
  "displayName": "Reviewers",
  "description": "This team is responsible for reviewing the documentation.",
  "teams": [
    "e60d02c1-7e55-4534-81f8-b3c079e83ee3"
  ]
}

Retrieving a team

To retrieve a BTS team, you can use the following REST API call:

GET /teamserver/rest/teams/{uuid}

For example, to retrieve the "Authors" team that has the e60d02c1-7e55-4534-81f8-b3c079e83ee3 uuid, you can invoke the following REST API call:

GET /teamserver/rest/teams/e60d02c1-7e55-4534-81f8-b3c079e83ee3

The response object returns the information about the team. For example:

{
  "description": "This team writes the technical documentation.",
  "displayName": "Authors",
  "distinguishedName": "cn=authors,ou=bpm,dc=example,dc=com",
  "groups": [
    "cn=Department 4711,ou=Group,dc=example,dc=com"
  ],
  "metadata": {
    "created": "2020-02-18T14:28:33.040Z",
    "lastModified": "2020-02-18T14:28:33.040Z"
  },
  "teams": [],
  "users": [
    "cn=Joe Bloggs,ou=User,dc=example,dc=com",
    "cn=John Doe,ou=User,dc=example,dc=com"
  ],
  "uuid": "e60d02c1-7e55-4534-81f8-b3c079e83ee3"
}

Incrementally updating a team

To update a BTS team incrementally, you can use the following REST API call:

PATCH /teamserver/rest/teams/{uuid}

You must pass the update operation in a JSON object in the request body of the call.

For example, to update the description of the "Authors" team you can invoke the following REST API call:

PATCH /teamserver/rest/teams/e60d02c1-7e55-4534-81f8-b3c079e83ee3

and pass the following JSON object:

{
  "operations": [
    {
      "op": "replace",
      "path": "description",
      "value": "This team is responsible for the product documentation."
    }
  ]
}

Replacing a team

To replace a BTS team, you can use the following REST API call:

PUT /teamserver/rest/teams/{uuid}

You must pass the new team definition as an input parameter in a JSON object in the request body of the call.

For example, to remove the user "John Doe" you can invoke the following REST API call:

PUT /teamserver/rest/teams/e60d02c1-7e55-4534-81f8-b3c079e83ee3

and pass the following JSON object:

{
  "distinguishedName": "cn=Authors,ou=bpm,dc=example,dc=com",
  "displayName": "Authors",
  "description": "This team is responsible for the product documentation.",
  "users": [
    "cn=Joe Bloggs,ou=User,dc=example,dc=com"
  ],
  "groups": [
    "cn=Department 4711,ou=Group,dc=example,dc=com"
  ]
}

Retrieving a list of teams that you are a member of

To retrieve a list of all BTS teams that you are a member of, you can use the following REST API call:

GET /teamserver/rest/teams?my_teams=true

Note that only BTS administrators are authorized to perform this call without the my_teams query parameter to retrieve all teams with arbitrary filters. BTS users are restricted to see only those teams that they are a member of. To limit the list to those teams whose display name starts with "Aut" you can add the filter query parameter. For more information about filters, see the OpenAPI documentation for the full list of filters. Also, notice that for better readability the required URL query parameters encoding is omitted:

GET /teamserver/rest/teams?my_teams=true&filter=displayName SW "Aut"

Here is the example response:

{
  "items": [
    {
      "description": "This team is responsible for the product documentation.",
      "displayName": "Authors",
      "distinguishedName": "cn=authors,ou=bpm,dc=example,dc=com",
      "groups": [
        "cn=Department 4711,ou=Group,dc=example,dc=com"
      ],
      "metadata": {
        "created": "2020-02-18T14:28:33.040Z",
        "lastModified": "2020-02-18T14:33:57.688Z"
      },
      "teams": [],
      "users": [
        "cn=Joe Bloggs,ou=User,dc=example,dc=com"
      ],
      "uuid": "e60d02c1-7e55-4534-81f8-b3c079e83ee3"
    }
  ],
  "metadata": {
    "startIndex": 1,
    "totalSize": 1
  }
}

Deleting a team

To delete a BTS team, you can use the following REST API call:

DELETE /teamserver/rest/teams/{uuid}

The delete request removes the corresponding team from the database and also removes all references from other teams to that team.

For example, to delete the "Authors" team you can invoke the following REST API call:

DELETE /teamserver/rest/teams/e60d02c1-7e55-4534-81f8-b3c079e83ee3