Support provisioning teams from external sources (#3011)

Co-authored-by: ci.datadog-api-spec <[email protected]>

Author: api-clients-generation-pipeline[bot]

.generator/schemas/v2/openapi.yaml

@@ -52263,14 +52263,31 @@ components:
     TeamSyncAttributes:
       description: Team sync attributes.
       properties:
+        frequency:
+          $ref: '#/components/schemas/TeamSyncAttributesFrequency'
         source:
           $ref: '#/components/schemas/TeamSyncAttributesSource'
+        sync_membership:
+          $ref: '#/components/schemas/TeamSyncAttributesSyncMembership'
         type:
           $ref: '#/components/schemas/TeamSyncAttributesType'
       required:
       - source
       - type
       type: object
+    TeamSyncAttributesFrequency:
+      description: How often the sync process should be run. Defaults to `once` when
+        not provided.
+      enum:
+      - once
+      - continuously
+      - paused
+      example: once
+      type: string
+      x-enum-varnames:
+      - ONCE
+      - CONTINUOUSLY
+      - PAUSED
     TeamSyncAttributesSource:
       description: The external source platform for team synchronization. Only "github"
         is supported.
@@ -52280,15 +52297,22 @@ components:
       type: string
       x-enum-varnames:
       - GITHUB
+    TeamSyncAttributesSyncMembership:
+      description: Whether to sync members from the external team to the Datadog team.
+        Defaults to `false` when not provided.
+      example: true
+      type: boolean
     TeamSyncAttributesType:
-      description: The type of synchronization operation. Only "link" is supported,
-        which links existing teams by matching names.
+      description: The type of synchronization operation. "link" connects teams by
+        matching names. "provision" creates new teams when no match is found.
       enum:
       - link
+      - provision
       example: link
       type: string
       x-enum-varnames:
       - LINK
+      - PROVISION
     TeamSyncBulkType:
       description: Team sync bulk type.
       enum:
@@ -52298,10 +52322,15 @@ components:
       x-enum-varnames:
       - TEAM_SYNC_BULK
     TeamSyncData:
-      description: Team sync data.
+      description: A configuration governing syncing between Datadog teams and teams
+        from an external system.
       properties:
         attributes:
           $ref: '#/components/schemas/TeamSyncAttributes'
+        id:
+          description: The sync's identifier
+          example: aeadc05e-98a8-11ec-ac2c-da7ad0900001
+          type: string
         type:
           $ref: '#/components/schemas/TeamSyncBulkType'
       required:
@@ -52322,6 +52351,15 @@ components:
       required:
       - data
       type: object
+    TeamSyncResponse:
+      description: Team sync configurations response.
+      properties:
+        data:
+          description: List of team sync configurations
+          items:
+            $ref: '#/components/schemas/TeamSyncData'
+          type: array
+      type: object
     TeamTarget:
       description: Represents a team target for an escalation policy step, including
         the team's ID and resource type.
@@ -81182,6 +81220,52 @@ paths:
 
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).'
   /api/v2/team/sync:
+    get:
+      description: 'Get all team synchronization configurations.
+
+        Returns a list of configurations used for linking or provisioning teams with
+        external sources like GitHub.'
+      operationId: GetTeamSync
+      parameters:
+      - description: Filter by the external source platform for team synchronization
+        in: query
+        name: filter[source]
+        required: true
+        schema:
+          $ref: '#/components/schemas/TeamSyncAttributesSource'
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TeamSyncResponse'
+          description: OK
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIErrorResponse'
+          description: Team sync configurations not found
+        '429':
+          $ref: '#/components/responses/TooManyRequestsResponse'
+      security:
+      - apiKeyAuth: []
+        appKeyAuth: []
+      - AuthZ:
+        - teams_read
+      summary: Get team sync configurations
+      tags:
+      - Teams
+      x-permission:
+        operator: OR
+        permissions:
+        - teams_read
+      x-unstable: '**Note**: This endpoint is in Preview. To request access, fill
+        out this [form](https://www.datadoghq.com/product-preview/github-integration-for-teams/).
+
+        If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).'
     post:
       description: 'This endpoint attempts to link your existing Datadog teams with
         GitHub teams by matching their names.
@@ -81208,7 +81292,8 @@ paths:
         using a normalized exact match; case is ignored and spaces are removed. No
         modifications are made
 
-        to teams in GitHub. This will not create new Teams in Datadog.'
+        to teams in GitHub. This only creates new teams in Datadog when type is set
+        to `provision`.'
       operationId: SyncTeams
       requestBody:
         content:

features/v2/teams.feature

@@ -235,6 +235,22 @@ Feature: Teams
     Then the response status is 200 OK
     And the response has 3 items
 
+  @generated @skip @team:DataDog/aaa-omg
+  Scenario: Get team sync configurations returns "OK" response
+    Given operation "GetTeamSync" enabled
+    And new "GetTeamSync" request
+    And request contains "filter[source]" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 200 OK
+
+  @generated @skip @team:DataDog/aaa-omg
+  Scenario: Get team sync configurations returns "Team sync configurations not found" response
+    Given operation "GetTeamSync" enabled
+    And new "GetTeamSync" request
+    And request contains "filter[source]" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 404 Team sync configurations not found
+
   @generated @skip @team:DataDog/aaa-omg
   Scenario: Get user memberships returns "API error response." response
     Given new "GetUserMemberships" request

features/v2/undo.json

@@ -4287,6 +4287,12 @@
       "type": "unsafe"
     }
   },
+  "GetTeamSync": {
+    "tag": "Teams",
+    "undo": {
+      "type": "safe"
+    }
+  },
   "SyncTeams": {
     "tag": "Teams",
     "undo": {

private/bdd_runner/src/support/scenarios_model_mapping.ts

@@ -8693,6 +8693,13 @@ export const ScenariosModelMappings: { [key: string]: OperationMapping } = {
     },
     operationResponseType: "TeamResponse",
   },
+  "TeamsApi.V2.GetTeamSync": {
+    filterSource: {
+      type: "TeamSyncAttributesSource",
+      format: "",
+    },
+    operationResponseType: "TeamSyncResponse",
+  },
   "TeamsApi.V2.SyncTeams": {
     body: {
       type: "TeamSyncRequest",

services/teams/src/v2/TeamsApi.ts

@@ -38,7 +38,9 @@ import { TeamPermissionSettingUpdateRequest } from "./models/TeamPermissionSetti
 import { TeamResponse } from "./models/TeamResponse";
 import { TeamsField } from "./models/TeamsField";
 import { TeamsResponse } from "./models/TeamsResponse";
+import { TeamSyncAttributesSource } from "./models/TeamSyncAttributesSource";
 import { TeamSyncRequest } from "./models/TeamSyncRequest";
+import { TeamSyncResponse } from "./models/TeamSyncResponse";
 import { TeamUpdateRequest } from "./models/TeamUpdateRequest";
 import { UserTeam } from "./models/UserTeam";
 import { UserTeamRequest } from "./models/UserTeamRequest";
@@ -702,6 +704,63 @@ export class TeamsApiRequestFactory extends BaseAPIRequestFactory {
     return requestContext;
   }
 
+  public async getTeamSync(
+    filterSource: TeamSyncAttributesSource,
+    _options?: Configuration,
+  ): Promise<RequestContext> {
+    const _config = _options || this.configuration;
+
+    if (!_config.unstableOperations["TeamsApi.v2.getTeamSync"]) {
+      throw new Error(
+        "Unstable operation 'getTeamSync' is disabled. Enable it by setting `configuration.unstableOperations['TeamsApi.v2.getTeamSync'] = true`",
+      );
+    }
+
+    // verify required parameter 'filterSource' is not null or undefined
+    if (filterSource === null || filterSource === undefined) {
+      throw new RequiredError("filterSource", "getTeamSync");
+    }
+
+    // Path Params
+    const localVarPath = "/api/v2/team/sync";
+
+    // Make Request Context
+    const { server, overrides } = _config.getServerAndOverrides(
+      "TeamsApi.v2.getTeamSync",
+      TeamsApi.operationServers,
+    );
+    const requestContext = server.makeRequestContext(
+      localVarPath,
+      HttpMethod.GET,
+      overrides,
+    );
+    requestContext.setHeaderParam("Accept", "application/json");
+    requestContext.setHttpConfig(_config.httpConfig);
+
+    // Set User-Agent
+    if (this.userAgent) {
+      requestContext.setHeaderParam("User-Agent", this.userAgent);
+    }
+
+    // Query Params
+    if (filterSource !== undefined) {
+      requestContext.setQueryParam(
+        "filter[source]",
+        serialize(filterSource, TypingInfo, "TeamSyncAttributesSource", ""),
+        "",
+      );
+    }
+
+    // Apply auth methods
+    applySecurityAuthentication(_config, requestContext, [
+      "apiKeyAuth",
+      "appKeyAuth",
+      "AuthZ",
+    ]);
+
+    return requestContext;
+  }
+
   public async getUserMemberships(
     userUuid: string,
     _options?: Configuration,
@@ -1955,6 +2014,66 @@ export class TeamsApiResponseProcessor {
     );
   }
 
+  /**
+   * Unwraps the actual response sent by the server from the response context and deserializes the response content
+   * to the expected objects
+   *
+   * @params response Response returned by the server for a request to getTeamSync
+   * @throws ApiException if the response code was not in [200, 299]
+   */
+  public async getTeamSync(
+    response: ResponseContext,
+  ): Promise<TeamSyncResponse> {
+    const contentType = normalizeMediaType(response.headers["content-type"]);
+    if (response.httpStatusCode === 200) {
+      const body: TeamSyncResponse = deserialize(
+        parse(await response.body.text(), contentType),
+        TypingInfo,
+        "TeamSyncResponse",
+      ) as TeamSyncResponse;
+      return body;
+    }
+    if (
+      response.httpStatusCode === 403 ||
+      response.httpStatusCode === 404 ||
+      response.httpStatusCode === 429
+    ) {
+      const bodyText = parse(await response.body.text(), contentType);
+      let body: APIErrorResponse;
+      try {
+        body = deserialize(
+          bodyText,
+          TypingInfo,
+          "APIErrorResponse",
+        ) as APIErrorResponse;
+      } catch (error) {
+        logger.debug(`Got error deserializing error: ${error}`);
+        throw new ApiException<APIErrorResponse>(
+          response.httpStatusCode,
+          bodyText,
+        );
+      }
+      throw new ApiException<APIErrorResponse>(response.httpStatusCode, body);
+    }
+
+    // Work around for missing responses in specification, e.g. for petstore.yaml
+    if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) {
+      const body: TeamSyncResponse = deserialize(
+        parse(await response.body.text(), contentType),
+        TypingInfo,
+        "TeamSyncResponse",
+        "",
+      ) as TeamSyncResponse;
+      return body;
+    }
+
+    const body = (await response.body.text()) || "";
+    throw new ApiException<string>(
+      response.httpStatusCode,
+      'Unknown API Status Code!\nBody: "' + body + '"',
+    );
+  }
+
   /**
    * Unwraps the actual response sent by the server from the response context and deserializes the response content
    * to the expected objects
@@ -2602,6 +2721,14 @@ export interface TeamsApiGetTeamPermissionSettingsRequest {
   teamId: string;
 }
 
+export interface TeamsApiGetTeamSyncRequest {
+  /**
+   * Filter by the external source platform for team synchronization
+   * @type TeamSyncAttributesSource
+   */
+  filterSource: TeamSyncAttributesSource;
+}
+
 export interface TeamsApiGetUserMembershipsRequest {
   /**
    * None
@@ -3081,6 +3208,28 @@ export class TeamsApi {
     });
   }
 
+  /**
+   * Get all team synchronization configurations.
+   * Returns a list of configurations used for linking or provisioning teams with external sources like GitHub.
+   * @param param The request object
+   */
+  public getTeamSync(
+    param: TeamsApiGetTeamSyncRequest,
+    options?: Configuration,
+  ): Promise<TeamSyncResponse> {
+    const requestContextPromise = this.requestFactory.getTeamSync(
+      param.filterSource,
+      options,
+    );
+    return requestContextPromise.then((requestContext) => {
+      return this.configuration.httpApi
+        .send(requestContext)
+        .then((responseContext) => {
+          return this.responseProcessor.getTeamSync(responseContext);
+        });
+    });
+  }
+
   /**
    * Get a list of memberships for a user
    * @param param The request object
@@ -3271,7 +3420,7 @@ export class TeamsApi {
    * [A GitHub organization must be connected to your Datadog account](https://docs.datadoghq.com/integrations/github/),
    * and the GitHub App integrated with Datadog must have the `Members Read` permission. Matching is performed by comparing the Datadog team handle to the GitHub team slug
    * using a normalized exact match; case is ignored and spaces are removed. No modifications are made
-   * to teams in GitHub. This will not create new Teams in Datadog.
+   * to teams in GitHub. This only creates new teams in Datadog when type is set to `provision`.
    * @param param The request object
    */
   public syncTeams(