get:
  operationId: getSource
  security:
    - UserContextAuth: [ idn:sources:read ]
  tags:
    - Sources
  summary: Get Source by ID
  description: >-
    This end-point gets a specific source in IdentityNow.

    A token with ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to call this API.
  parameters:
    - in: path
      name: id
      schema:
        type: string
      required: true
      description: The Source id
      example: 2c9180835d191a86015d28455b4a2329
  responses:
    '200':
      description: A Source object
      content:
        application/json:
          schema:
            $ref: '../schemas/Source.yaml'
    '400':
      $ref: '../../v3/responses/400.yaml'
    '401':
      $ref: '../../v3/responses/401.yaml'
    '403':
      $ref: '../../v3/responses/403.yaml'
    '404':
      $ref: '../../v3/responses/404.yaml'
    '429':
      $ref: '../../v3/responses/429.yaml'
    '500':
      $ref: '../../v3/responses/500.yaml'
put:
  operationId: putSource
  security:
    - UserContextAuth: [ idn:sources:manage ]
  tags:
    - Sources
  summary: Update Source (Full)
  description: |
    This API updates a source in IdentityNow, using a full object representation. In other words, the existing Source
    configuration is completely replaced.

    Some fields are immutable and cannot be changed, such as:

    * id
    * type
    * authoritative
    * connector
    * connectorClass
    * passwordPolicies

    Attempts to modify these fields will result in a 400 error.

    A token with ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to call this API.
  parameters:
    - in: path
      name: id
      schema:
        type: string
      required: true
      description: The Source id
      example: 2c9180835d191a86015d28455b4a2329
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '../schemas/Source.yaml'
  responses:
    '200':
      description: >-
        Updated Source object. Any passwords will only show the the encrypted cipher-text, as they are not decrypt-able
        in IdentityNow cloud-based services, per IdentityNow security design.
      content:
        application/json:
          schema:
            $ref: '../schemas/Source.yaml'
    '400':
      $ref: '../../v3/responses/400.yaml'
    '401':
      $ref: '../../v3/responses/401.yaml'
    '403':
      $ref: '../../v3/responses/403.yaml'
    '404':
      $ref: '../../v3/responses/404.yaml'
    '429':
      $ref: '../../v3/responses/429.yaml'
    '500':
      $ref: '../../v3/responses/500.yaml'
patch:
  operationId: updateSource
  security:
    - UserContextAuth: [ idn:sources:manage ]
  tags:
    - Sources
  summary: Update Source (Partial)
  description: |
    This API partially updates a source in IdentityNow, using a list of patch operations according to the
    [JSON Patch](https://tools.ietf.org/html/rfc6902) standard.

    Some fields are immutable and cannot be changed, such as:

    * id
    * type
    * authoritative
    * created
    * modified
    * connector
    * connectorClass
    * passwordPolicies

    Attempts to modify these fields will result in a 400 error.

    A token with ORG_ADMIN, SOURCE_ADMIN, SOURCE_SUBADMIN, or API authority is required to call this API.
  parameters:
    - in: path
      name: id
      schema:
        type: string
      required: true
      description: The Source id
      example: 2c9180835d191a86015d28455b4a2329
  requestBody:
    required: true
    description: >-
      A list of account update operations according to the [JSON Patch](https://tools.ietf.org/html/rfc6902) standard.
      Any password changes are submitted as plain-text and encrypted upon receipt in IdentityNow.
    content:
      application/json-patch+json:
        schema:
          type: array
          items:
            $ref: '../schemas/JsonPatchOperation.yaml'
        examples:
          Edit the source description:
            description: This example shows how to edit a source description.
            value:
              [
                {
                "op": "replace",
                "path": "/description",
                  "value": "new description"
                }
              ]
          Edit the source cluster:
            description: This example shows how to edit a source cluster by id.
            value:
              [
                {
                  "op": "replace",
                  "path": "/cluster/id",
                  "value": "2c918087813a902001813f3f85736b45"
                }
              ]

          Edit source features:
            description: This example illustrates how you can update source supported features.
            value:
              [
                {
                  "op": "replace",
                  "path": "/features",
                  "value": [
                      "PASSWORD",
                      "PROVISIONING",
                      "ENABLE",
                      "AUTHENTICATE"
                  ]
                }
              ]
          Change a source description and cluster in One Call:
            description: This example shows how multiple fields may be updated with a single patch call.
            value:
              [
                {
                  "op": "replace",
                  "path": "/description",
                  "value": "new description"
                },
                {
                  "op": "replace",
                  "path": "/cluster/id",
                  "value": "2c918087813a902001813f3f85736b45"
                }
              ]
          Add a filter string to the connector:
            description: This example shows how you can add a filter to incoming accounts during the account aggregation process. In the example below, any account that does not have an "m" or "d" in the id will be aggregated.
            value:
              [
                  {
                  "op": "add",
                  "path": "/connectorAttributes/filterString",
                      "value": "!( id.contains( \"m\" ) ) || !( id.contains( \"d\" ) )"
                  }
              ]
          Update connector attribute for specific operation type:
            description: This example shows how you can update the 3rd object in the connection parameters operationType. This will change it from a standard group aggregation to a group aggregation on the "test" entitlement type.
            value:
              [
                  {
                  "op": "replace",
                  "path": "/connectorAttributes/connectionParameters/2/operationType",
                      "value": "Group Aggregation-test"
                  }
              ]
  responses:
    '200':
      description: >-
        Updated Source object. Any passwords will only show the the encrypted cipher-text, as they are not decrypt-able
        in IdentityNow cloud-based services, per IdentityNow security design.
      content:
        application/json:
          schema:
            $ref: '../schemas/Source.yaml'
    '400':
      $ref: '../../v3/responses/400.yaml'
    '401':
      $ref: '../../v3/responses/401.yaml'
    '403':
      $ref: '../../v3/responses/403.yaml'
    '404':
      $ref: '../../v3/responses/404.yaml'
    '429':
      $ref: '../../v3/responses/429.yaml'
    '500':
      $ref: '../../v3/responses/500.yaml'
delete:
  operationId: deleteSource
  security:
    - UserContextAuth: [ idn:sources:manage ]
  tags:
    - Sources
  summary: Delete Source by ID
  description: >-
    This end-point deletes a specific source in IdentityNow.

    A token with ORG_ADMIN, SOURCE_ADMIN, or SOURCE_SUBADMIN authority is required to call this API.

    All of accounts on the source will be removed first, then the source will be deleted.
    Actual status of task execution can be retrieved via method GET `/task-status/{id}`
  parameters:
    - in: path
      name: id
      schema:
        type: string
      required: true
      description: The Source id
      example: 2c9180835d191a86015d28455b4a2329
  responses:
    '202':
      description: Accepted - Returned if the request was successfully accepted into the system.
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                description: The type of object being referenced
                type: string
                enum:
                  - TASK_RESULT
                example: TASK_RESULT
              id:
                type: string
                description: ID of the task result
                example: 2c91808779ecf55b0179f720942f181a
              name:
                type: string
                description: Human-readable display name of the task result (should be null/empty)
                example: null
          examples:
            deleteSource:
              summary: Response returned when deleting a source
              value: {"type": "TASK_RESULT", "id": "2c91808779ecf55b0179f720942f181a", "name": null}
    '400':
      $ref: '../../v3/responses/400.yaml'
    '401':
      $ref: '../../v3/responses/401.yaml'
    '403':
      $ref: '../../v3/responses/403.yaml'
    '404':
      $ref: '../../v3/responses/404.yaml'
    '429':
      $ref: '../../v3/responses/429.yaml'
    '500':
      $ref: '../../v3/responses/500.yaml'