Support provisioning teams from external sources (DataDog#2779)

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.rb

@@ -0,0 +1,8 @@
+# Get team sync configurations returns "OK" response
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.get_team_sync".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::TeamsAPI.new
+p api_instance.get_team_sync(TeamSyncAttributesSource::GITHUB)

features/scenarios_model_mapping.rb

@@ -3072,6 +3072,9 @@
     "v2.CreateTeam" => {
             "body" => "TeamCreateRequest",
     },
+    "v2.GetTeamSync" => {
+            "filter_source" => "TeamSyncAttributesSource",
+    },
     "v2.SyncTeams" => {
             "body" => "TeamSyncRequest",
     },

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": {

lib/datadog_api_client/configuration.rb

@@ -314,6 +314,7 @@ def initialize
             "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,

lib/datadog_api_client/inflector.rb

@@ -4245,11 +4245,13 @@ def overrides
           "v2.teams_response_meta" => "TeamsResponseMeta",
           "v2.teams_response_meta_pagination" => "TeamsResponseMetaPagination",
           "v2.team_sync_attributes" => "TeamSyncAttributes",
+          "v2.team_sync_attributes_frequency" => "TeamSyncAttributesFrequency",
           "v2.team_sync_attributes_source" => "TeamSyncAttributesSource",
           "v2.team_sync_attributes_type" => "TeamSyncAttributesType",
           "v2.team_sync_bulk_type" => "TeamSyncBulkType",
           "v2.team_sync_data" => "TeamSyncData",
           "v2.team_sync_request" => "TeamSyncRequest",
+          "v2.team_sync_response" => "TeamSyncResponse",
           "v2.team_target" => "TeamTarget",
           "v2.team_target_type" => "TeamTargetType",
           "v2.team_type" => "TeamType",

lib/datadog_api_client/v2/api/teams_api.rb

@@ -883,6 +883,84 @@ def get_team_permission_settings_with_http_info(team_id, opts = {})
       return data, status_code, headers
     end
 
+    # Get team sync configurations.
+    #
+    # @see #get_team_sync_with_http_info
+    def get_team_sync(filter_source, opts = {})
+      data, _status_code, _headers = get_team_sync_with_http_info(filter_source, opts)
+      data
+    end
+
+    # 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 [TeamSyncAttributesSource] Filter by the external source platform for team synchronization
+    # @param opts [Hash] the optional parameters
+    # @return [Array<(TeamSyncResponse, Integer, Hash)>] TeamSyncResponse data, response status code and response headers
+    def get_team_sync_with_http_info(filter_source, opts = {})
+      unstable_enabled = @api_client.config.unstable_operations["v2.get_team_sync".to_sym]
+      if unstable_enabled
+        @api_client.config.logger.warn format("Using unstable operation '%s'", "v2.get_team_sync")
+      else
+        raise DatadogAPIClient::APIError.new(message: format("Unstable operation '%s' is disabled", "v2.get_team_sync"))
+      end
+
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: TeamsAPI.get_team_sync ...'
+      end
+      # verify the required parameter 'filter_source' is set
+      if @api_client.config.client_side_validation && filter_source.nil?
+        fail ArgumentError, "Missing the required parameter 'filter_source' when calling TeamsAPI.get_team_sync"
+      end
+      # verify enum value
+      allowable_values = ['github']
+      if @api_client.config.client_side_validation && !allowable_values.include?(filter_source)
+        fail ArgumentError, "invalid value for \"filter_source\", must be one of #{allowable_values}"
+      end
+      # resource path
+      local_var_path = '/api/v2/team/sync'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+      query_params[:'filter[source]'] = filter_source
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json'])
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'TeamSyncResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth, :AuthZ]
+
+      new_options = opts.merge(
+        :operation => :get_team_sync,
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type,
+        :api_version => "V2"
+      )
+
+      data, status_code, headers = @api_client.call_api(Net::HTTP::Get, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: TeamsAPI#get_team_sync\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
     # Get user memberships.
     #
     # @see #get_user_memberships_with_http_info
@@ -1245,7 +1323,7 @@ def sync_teams(body, opts = {})
     # [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 body [TeamSyncRequest] 
     # @param opts [Hash] the optional parameters

lib/datadog_api_client/v2/models/team_sync_attributes.rb

@@ -21,10 +21,16 @@ module DatadogAPIClient::V2
   class TeamSyncAttributes
     include BaseGenericModel
 
+    # How often the sync process should be run. Defaults to `once` when not provided.
+    attr_accessor :frequency
+
     # The external source platform for team synchronization. Only "github" is supported.
     attr_reader :source
 
-    # The type of synchronization operation. Only "link" is supported, which links existing teams by matching names.
+    # Whether to sync members from the external team to the Datadog team. Defaults to `false` when not provided.
+    attr_accessor :sync_membership
+
+    # The type of synchronization operation. "link" connects teams by matching names. "provision" creates new teams when no match is found.
     attr_reader :type
 
     attr_accessor :additional_properties
@@ -33,7 +39,9 @@ class TeamSyncAttributes
     # @!visibility private
     def self.attribute_map
       {
+        :'frequency' => :'frequency',
         :'source' => :'source',
+        :'sync_membership' => :'sync_membership',
         :'type' => :'type'
       }
     end
@@ -42,7 +50,9 @@ def self.attribute_map
     # @!visibility private
     def self.openapi_types
       {
+        :'frequency' => :'TeamSyncAttributesFrequency',
         :'source' => :'TeamSyncAttributesSource',
+        :'sync_membership' => :'Boolean',
         :'type' => :'TeamSyncAttributesType'
       }
     end
@@ -65,10 +75,18 @@ def initialize(attributes = {})
         end
       }
 
+      if attributes.key?(:'frequency')
+        self.frequency = attributes[:'frequency']
+      end
+
       if attributes.key?(:'source')
         self.source = attributes[:'source']
       end
 
+      if attributes.key?(:'sync_membership')
+        self.sync_membership = attributes[:'sync_membership']
+      end
+
       if attributes.key?(:'type')
         self.type = attributes[:'type']
       end
@@ -129,7 +147,9 @@ def to_hash
     def ==(o)
       return true if self.equal?(o)
       self.class == o.class &&
+          frequency == o.frequency &&
           source == o.source &&
+          sync_membership == o.sync_membership &&
           type == o.type &&
           additional_properties == o.additional_properties
     end
@@ -138,7 +158,7 @@ def ==(o)
     # @return [Integer] Hash code
     # @!visibility private
     def hash
-      [source, type, additional_properties].hash
+      [frequency, source, sync_membership, type, additional_properties].hash
     end
   end
 end