Support provisioning teams from external sources (#3252)

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:

examples/v2/teams/GetTeamSync.java

@@ -0,0 +1,26 @@
+// Get team sync configurations returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.TeamsApi;
+import com.datadog.api.client.v2.model.TeamSyncAttributesSource;
+import com.datadog.api.client.v2.model.TeamSyncResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setUnstableOperationEnabled("v2.getTeamSync", true);
+    TeamsApi apiInstance = new TeamsApi(defaultClient);
+
+    try {
+      TeamSyncResponse result = apiInstance.getTeamSync(TeamSyncAttributesSource.GITHUB);
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling TeamsApi#getTeamSync");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

src/main/java/com/datadog/api/client/ApiClient.java

@@ -812,6 +812,7 @@ public class ApiClient {
           put("v2.createSCAResolveVulnerableSymbols", false);
           put("v2.createSCAResult", false);
           put("v2.addMemberTeam", false);
+          put("v2.getTeamSync", false);
           put("v2.listMemberTeams", false);
           put("v2.removeMemberTeam", false);
           put("v2.syncTeams", false);

src/main/java/com/datadog/api/client/v2/api/TeamsApi.java

@@ -18,7 +18,9 @@
 import com.datadog.api.client.v2.model.TeamPermissionSettingUpdateRequest;
 import com.datadog.api.client.v2.model.TeamPermissionSettingsResponse;
 import com.datadog.api.client.v2.model.TeamResponse;
+import com.datadog.api.client.v2.model.TeamSyncAttributesSource;
 import com.datadog.api.client.v2.model.TeamSyncRequest;
+import com.datadog.api.client.v2.model.TeamSyncResponse;
 import com.datadog.api.client.v2.model.TeamUpdateRequest;
 import com.datadog.api.client.v2.model.TeamsField;
 import com.datadog.api.client.v2.model.TeamsResponse;
@@ -1987,6 +1989,162 @@ public ApiResponse<TeamPermissionSettingsResponse> getTeamPermissionSettingsWith
         new GenericType<TeamPermissionSettingsResponse>() {});
   }
 
+  /**
+   * Get team sync configurations.
+   *
+   * <p>See {@link #getTeamSyncWithHttpInfo}.
+   *
+   * @param filterSource Filter by the external source platform for team synchronization (required)
+   * @return TeamSyncResponse
+   * @throws ApiException if fails to make API call
+   */
+  public TeamSyncResponse getTeamSync(TeamSyncAttributesSource filterSource) throws ApiException {
+    return getTeamSyncWithHttpInfo(filterSource).getData();
+  }
+
+  /**
+   * Get team sync configurations.
+   *
+   * <p>See {@link #getTeamSyncWithHttpInfoAsync}.
+   *
+   * @param filterSource Filter by the external source platform for team synchronization (required)
+   * @return CompletableFuture&lt;TeamSyncResponse&gt;
+   */
+  public CompletableFuture<TeamSyncResponse> getTeamSyncAsync(
+      TeamSyncAttributesSource filterSource) {
+    return getTeamSyncWithHttpInfoAsync(filterSource)
+        .thenApply(
+            response -> {
+              return response.getData();
+            });
+  }
+
+  /**
+   * Get all team synchronization configurations. Returns a list of configurations used for linking
+   * or provisioning teams with external sources like GitHub.
+   *
+   * @param filterSource Filter by the external source platform for team synchronization (required)
+   * @return ApiResponse&lt;TeamSyncResponse&gt;
+   * @throws ApiException if fails to make API call
+   * @http.response.details
+   *     <table border="1">
+   *    <caption>Response details</caption>
+   *       <tr><td> Status Code </td><td> Description </td><td> Response Headers </td></tr>
+   *       <tr><td> 200 </td><td> OK </td><td>  -  </td></tr>
+   *       <tr><td> 403 </td><td> Forbidden </td><td>  -  </td></tr>
+   *       <tr><td> 404 </td><td> Team sync configurations not found </td><td>  -  </td></tr>
+   *       <tr><td> 429 </td><td> Too many requests </td><td>  -  </td></tr>
+   *     </table>
+   */
+  public ApiResponse<TeamSyncResponse> getTeamSyncWithHttpInfo(
+      TeamSyncAttributesSource filterSource) throws ApiException {
+    // Check if unstable operation is enabled
+    String operationId = "getTeamSync";
+    if (apiClient.isUnstableOperationEnabled("v2." + operationId)) {
+      apiClient.getLogger().warning(String.format("Using unstable operation '%s'", operationId));
+    } else {
+      throw new ApiException(0, String.format("Unstable operation '%s' is disabled", operationId));
+    }
+    Object localVarPostBody = null;
+
+    // verify the required parameter 'filterSource' is set
+    if (filterSource == null) {
+      throw new ApiException(
+          400, "Missing the required parameter 'filterSource' when calling getTeamSync");
+    }
+    // create path and map variables
+    String localVarPath = "/api/v2/team/sync";
+
+    List<Pair> localVarQueryParams = new ArrayList<Pair>();
+    Map<String, String> localVarHeaderParams = new HashMap<String, String>();
+
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "filter[source]", filterSource));
+
+    Invocation.Builder builder =
+        apiClient.createBuilder(
+            "v2.TeamsApi.getTeamSync",
+            localVarPath,
+            localVarQueryParams,
+            localVarHeaderParams,
+            new HashMap<String, String>(),
+            new String[] {"application/json"},
+            new String[] {"apiKeyAuth", "appKeyAuth", "AuthZ"});
+    return apiClient.invokeAPI(
+        "GET",
+        builder,
+        localVarHeaderParams,
+        new String[] {},
+        localVarPostBody,
+        new HashMap<String, Object>(),
+        false,
+        new GenericType<TeamSyncResponse>() {});
+  }
+
+  /**
+   * Get team sync configurations.
+   *
+   * <p>See {@link #getTeamSyncWithHttpInfo}.
+   *
+   * @param filterSource Filter by the external source platform for team synchronization (required)
+   * @return CompletableFuture&lt;ApiResponse&lt;TeamSyncResponse&gt;&gt;
+   */
+  public CompletableFuture<ApiResponse<TeamSyncResponse>> getTeamSyncWithHttpInfoAsync(
+      TeamSyncAttributesSource filterSource) {
+    // Check if unstable operation is enabled
+    String operationId = "getTeamSync";
+    if (apiClient.isUnstableOperationEnabled("v2." + operationId)) {
+      apiClient.getLogger().warning(String.format("Using unstable operation '%s'", operationId));
+    } else {
+      CompletableFuture<ApiResponse<TeamSyncResponse>> result = new CompletableFuture<>();
+      result.completeExceptionally(
+          new ApiException(0, String.format("Unstable operation '%s' is disabled", operationId)));
+      return result;
+    }
+    Object localVarPostBody = null;
+
+    // verify the required parameter 'filterSource' is set
+    if (filterSource == null) {
+      CompletableFuture<ApiResponse<TeamSyncResponse>> result = new CompletableFuture<>();
+      result.completeExceptionally(
+          new ApiException(
+              400, "Missing the required parameter 'filterSource' when calling getTeamSync"));
+      return result;
+    }
+    // create path and map variables
+    String localVarPath = "/api/v2/team/sync";
+
+    List<Pair> localVarQueryParams = new ArrayList<Pair>();
+    Map<String, String> localVarHeaderParams = new HashMap<String, String>();
+
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "filter[source]", filterSource));
+
+    Invocation.Builder builder;
+    try {
+      builder =
+          apiClient.createBuilder(
+              "v2.TeamsApi.getTeamSync",
+              localVarPath,
+              localVarQueryParams,
+              localVarHeaderParams,
+              new HashMap<String, String>(),
+              new String[] {"application/json"},
+              new String[] {"apiKeyAuth", "appKeyAuth", "AuthZ"});
+    } catch (ApiException ex) {
+      CompletableFuture<ApiResponse<TeamSyncResponse>> result = new CompletableFuture<>();
+      result.completeExceptionally(ex);
+      return result;
+    }
+    return apiClient.invokeAPIAsync(
+        "GET",
+        builder,
+        localVarHeaderParams,
+        new String[] {},
+        localVarPostBody,
+        new HashMap<String, Object>(),
+        false,
+        new GenericType<TeamSyncResponse>() {});
+  }
+
   /**
    * Get user memberships.
    *
@@ -2958,8 +3116,8 @@ public CompletableFuture<Void> syncTeamsAsync(TeamSyncRequest body) {
    * connected to your Datadog account</a>, and the GitHub App integrated with Datadog must have the
    * <code>Members Read</code> 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.
+   * removed. No modifications are made to teams in GitHub. This only creates new teams in Datadog
+   * when type is set to <code>provision</code>.
    *
    * @param body (required)
    * @return ApiResponse&lt;Void&gt;