Support provisioning teams from external sources (#2952)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

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:

docs/datadog_api_client.v2.model.rst

@@ -23125,6 +23125,13 @@ datadog\_api\_client.v2.model.team\_sync\_attributes module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v2.model.team\_sync\_attributes\_frequency module
+----------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.team_sync_attributes_frequency
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v2.model.team\_sync\_attributes\_source module
 -------------------------------------------------------------------
 
@@ -23160,6 +23167,13 @@ datadog\_api\_client.v2.model.team\_sync\_request module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v2.model.team\_sync\_response module
+---------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.team_sync_response
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v2.model.team\_target module
 -------------------------------------------------
 

examples/v2/teams/GetTeamSync.py

@@ -0,0 +1,17 @@
+"""
+Get team sync configurations returns "OK" response
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.teams_api import TeamsApi
+from datadog_api_client.v2.model.team_sync_attributes_source import TeamSyncAttributesSource
+
+configuration = Configuration()
+configuration.unstable_operations["get_team_sync"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = TeamsApi(api_client)
+    response = api_instance.get_team_sync(
+        filter_source=TeamSyncAttributesSource.GITHUB,
+    )
+
+    print(response)

src/datadog_api_client/configuration.py

@@ -372,6 +372,7 @@ def __init__(
                 "v2.create_sca_resolve_vulnerable_symbols": False,
                 "v2.create_sca_result": False,
                 "v2.add_member_team": False,
+                "v2.get_team_sync": False,
                 "v2.list_member_teams": False,
                 "v2.remove_member_team": False,
                 "v2.sync_teams": False,

src/datadog_api_client/v2/api/teams_api.py

@@ -21,6 +21,8 @@
 from datadog_api_client.v2.model.team import Team
 from datadog_api_client.v2.model.team_response import TeamResponse
 from datadog_api_client.v2.model.team_create_request import TeamCreateRequest
+from datadog_api_client.v2.model.team_sync_response import TeamSyncResponse
+from datadog_api_client.v2.model.team_sync_attributes_source import TeamSyncAttributesSource
 from datadog_api_client.v2.model.team_sync_request import TeamSyncRequest
 from datadog_api_client.v2.model.add_member_team_request import AddMemberTeamRequest
 from datadog_api_client.v2.model.team_update_request import TeamUpdateRequest
@@ -368,6 +370,29 @@ def __init__(self, api_client=None):
             api_client=api_client,
         )
 
+        self._get_team_sync_endpoint = _Endpoint(
+            settings={
+                "response_type": (TeamSyncResponse,),
+                "auth": ["apiKeyAuth", "appKeyAuth", "AuthZ"],
+                "endpoint_path": "/api/v2/team/sync",
+                "operation_id": "get_team_sync",
+                "http_method": "GET",
+                "version": "v2",
+            },
+            params_map={
+                "filter_source": {
+                    "required": True,
+                    "openapi_types": (TeamSyncAttributesSource,),
+                    "attribute": "filter[source]",
+                    "location": "query",
+                },
+            },
+            headers_map={
+                "accept": ["application/json"],
+            },
+            api_client=api_client,
+        )
+
         self._get_user_memberships_endpoint = _Endpoint(
             settings={
                 "response_type": (UserTeamsResponse,),
@@ -966,6 +991,24 @@ def get_team_permission_settings(
 
         return self._get_team_permission_settings_endpoint.call_with_http_info(**kwargs)
 
+    def get_team_sync(
+        self,
+        filter_source: TeamSyncAttributesSource,
+    ) -> TeamSyncResponse:
+        """Get team sync configurations.
+
+        Get all team synchronization configurations.
+        Returns a list of configurations used for linking or provisioning teams with external sources like GitHub.
+
+        :param filter_source: Filter by the external source platform for team synchronization
+        :type filter_source: TeamSyncAttributesSource
+        :rtype: TeamSyncResponse
+        """
+        kwargs: Dict[str, Any] = {}
+        kwargs["filter_source"] = filter_source
+
+        return self._get_team_sync_endpoint.call_with_http_info(**kwargs)
+
     def get_user_memberships(
         self,
         user_uuid: str,
@@ -1228,7 +1271,7 @@ def sync_teams(
         `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``.
 
         :type body: TeamSyncRequest
         :rtype: None

src/datadog_api_client/v2/model/team_sync_attributes.py

@@ -3,45 +3,70 @@
 # Copyright 2019-Present Datadog, Inc.
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import Union, TYPE_CHECKING
 
 from datadog_api_client.model_utils import (
     ModelNormal,
     cached_property,
+    unset,
+    UnsetType,
 )
 
 
 if TYPE_CHECKING:
+    from datadog_api_client.v2.model.team_sync_attributes_frequency import TeamSyncAttributesFrequency
     from datadog_api_client.v2.model.team_sync_attributes_source import TeamSyncAttributesSource
     from datadog_api_client.v2.model.team_sync_attributes_type import TeamSyncAttributesType
 
 
 class TeamSyncAttributes(ModelNormal):
     @cached_property
     def openapi_types(_):
+        from datadog_api_client.v2.model.team_sync_attributes_frequency import TeamSyncAttributesFrequency
         from datadog_api_client.v2.model.team_sync_attributes_source import TeamSyncAttributesSource
         from datadog_api_client.v2.model.team_sync_attributes_type import TeamSyncAttributesType
 
         return {
+            "frequency": (TeamSyncAttributesFrequency,),
             "source": (TeamSyncAttributesSource,),
+            "sync_membership": (bool,),
             "type": (TeamSyncAttributesType,),
         }
 
     attribute_map = {
+        "frequency": "frequency",
         "source": "source",
+        "sync_membership": "sync_membership",
         "type": "type",
     }
 
-    def __init__(self_, source: TeamSyncAttributesSource, type: TeamSyncAttributesType, **kwargs):
+    def __init__(
+        self_,
+        source: TeamSyncAttributesSource,
+        type: TeamSyncAttributesType,
+        frequency: Union[TeamSyncAttributesFrequency, UnsetType] = unset,
+        sync_membership: Union[bool, UnsetType] = unset,
+        **kwargs,
+    ):
         """
         Team sync attributes.
 
+        :param frequency: How often the sync process should be run. Defaults to ``once`` when not provided.
+        :type frequency: TeamSyncAttributesFrequency, optional
+
         :param source: The external source platform for team synchronization. Only "github" is supported.
         :type source: TeamSyncAttributesSource
 
-        :param type: The type of synchronization operation. Only "link" is supported, which links existing teams by matching names.
+        :param sync_membership: Whether to sync members from the external team to the Datadog team. Defaults to ``false`` when not provided.
+        :type sync_membership: bool, optional
+
+        :param type: The type of synchronization operation. "link" connects teams by matching names. "provision" creates new teams when no match is found.
         :type type: TeamSyncAttributesType
         """
+        if frequency is not unset:
+            kwargs["frequency"] = frequency
+        if sync_membership is not unset:
+            kwargs["sync_membership"] = sync_membership
         super().__init__(kwargs)
 
         self_.source = source

src/datadog_api_client/v2/model/team_sync_attributes_frequency.py

@@ -0,0 +1,41 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelSimple,
+    cached_property,
+)
+
+from typing import ClassVar
+
+
+class TeamSyncAttributesFrequency(ModelSimple):
+    """
+    How often the sync process should be run. Defaults to `once` when not provided.
+
+    :param value: Must be one of ["once", "continuously", "paused"].
+    :type value: str
+    """
+
+    allowed_values = {
+        "once",
+        "continuously",
+        "paused",
+    }
+    ONCE: ClassVar["TeamSyncAttributesFrequency"]
+    CONTINUOUSLY: ClassVar["TeamSyncAttributesFrequency"]
+    PAUSED: ClassVar["TeamSyncAttributesFrequency"]
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "value": (str,),
+        }
+
+
+TeamSyncAttributesFrequency.ONCE = TeamSyncAttributesFrequency("once")
+TeamSyncAttributesFrequency.CONTINUOUSLY = TeamSyncAttributesFrequency("continuously")
+TeamSyncAttributesFrequency.PAUSED = TeamSyncAttributesFrequency("paused")