Automated commit 'ADI-706 add specs to public beta and v3 (#1413)

* ADI-706 add specs to public beta and v3

* ADI-706 updated descriptions' by github action: 6249488971

idn/beta/paths/account-usages.yaml

@@ -3,7 +3,7 @@ get:
     - Account Usages
   summary: Returns account usage insights
   description: >-
-    This API returns summary of account usage insights for past 12 months.
+    This API returns a summary of account usage insights for past 12 months.
   operationId: getUsagesByAccountId
   parameters:
     - name: accountId

idn/beta/paths/source-usages.yaml

@@ -3,7 +3,7 @@ get:
     - Source Usages
   summary: Returns source usage insights
   description: >-
-    This API returns summary of source usage insights for past 12 months.
+    This API returns a summary of source usage insights for past 12 months.
   operationId: getUsagesBySourceId
   parameters:
     - name: sourceId

idn/sailpoint-api.beta.yaml

@@ -884,6 +884,16 @@ tags:
   - name: Workflows
     description: |
       Workflows allow administrators to create custom automation scripts directly within IdentityNow.  These automation scripts respond to [event triggers](https://developer.sailpoint.com/idn/docs/event-triggers#how-to-get-started-with-event-triggers) and perform a series of actions to perform tasks that are either too cumbersome or not available in the IdentityNow UI.  Workflows can be configured via a graphical user interface within IdentityNow, or by creating and uploading a JSON formatted script to the Workflow service.  The Workflows API collection provides the necessary functionality to create, manage, and test your workflows via REST.
+  - name: Source Usages
+    description: |
+      Use this API to implement source usage insight functionality.
+      With this functionality in place, administrators can gather information and insights about how their tenants' sources are being used.
+      This allows organizations to get the information they need to start optimizing and securing source usage.
+  - name: Account Usages
+    description: |
+      Use this API to implement account usage insight functionality.
+      With this functionality in place, administrators can gather information and insights about how their tenants' source accounts are being used.
+      This allows organizations to get the information they need to start optimizing and securing source account usage.
 
 security:
   - UserContextAuth: [ ]
@@ -970,6 +980,12 @@ components:
       $ref: './beta/schemas/SectionDetails.yaml'
     Field:
       $ref: './beta/schemas/FieldDetails.yaml'
+    AccountUsage:
+      $ref: './beta/schemas/AccountUsage.yaml'
+    SourceUsage:
+      $ref: './beta/schemas/SourceUsage.yaml'
+    SourceUsageStatus:
+      $ref: './beta/schemas/SourceUsageStatus.yaml'
 
 paths:
   /access-profiles:
@@ -1560,3 +1576,9 @@ paths:
     $ref: './beta/paths/form-instance-data-source.yaml'
   /form-definitions/predefined-select-options:
     $ref: './beta/paths/form-definitions-predefined-select-options.yaml'
+  /source-usages/{sourceId}/status:
+    $ref: "./beta/paths/source-usage-status.yaml"
+  /source-usages/{sourceId}/summaries:
+    $ref: "./beta/paths/source-usages.yaml"
+  /account-usages/{accountId}/summaries:
+    $ref: "./beta/paths/account-usages.yaml"

idn/sailpoint-api.v3.yaml

@@ -789,6 +789,16 @@ tags:
       When they complete the work item, they can select 'Mark Complete' to add it to their list of completed work items. 
 
       Refer to [Task Manager](https://documentation.sailpoint.com/saas/user-help/task_manager.html) for more information about work items, including the different types of work items users may need to complete.
+  - name: Source Usages
+    description: |
+      Use this API to implement source usage insight functionality.
+      With this functionality in place, administrators can gather information and insights about how their tenants' sources are being used.
+      This allows organizations to get the information they need to start optimizing and securing source usage.
+  - name: Account Usages
+    description: |
+      Use this API to implement account usage insight functionality.
+      With this functionality in place, administrators can gather information and insights about how their tenants' source accounts are being used.
+      This allows organizations to get the information they need to start optimizing and securing source account usage.
 paths:
   /access-profiles:
     $ref: './v3/paths/access-profiles.yaml'
@@ -1094,6 +1104,12 @@ paths:
     $ref: "./v3/paths/work-items-bulk-reject-approval-item.yaml"
   /work-items/{id}/submit-account-selection:
     $ref: "./v3/paths/work-items-account-selection.yaml"
+  /source-usages/{sourceId}/status:
+    $ref: "./v3/paths/source-usage-status.yaml"
+  /source-usages/{sourceId}/summaries:
+    $ref: "./v3/paths/source-usages.yaml"
+  /account-usages/{accountId}/summaries:
+    $ref: "./v3/paths/account-usages.yaml"
 
 security:
   - UserContextAuth: []
@@ -1241,3 +1257,9 @@ components:
       $ref: "./v3/schemas/WorkItemsCount.yaml"
     WorkItemsSummary:
       $ref: "./v3/schemas/WorkItemsSummary.yaml"
+    AccountUsage:
+      $ref: './v3/schemas/AccountUsage.yaml'
+    SourceUsage:
+      $ref: './v3/schemas/SourceUsage.yaml'
+    SourceUsageStatus:
+      $ref: './v3/schemas/SourceUsageStatus.yaml'

idn/v3/paths/account-usages.yaml

@@ -0,0 +1,50 @@
+get:
+  tags:
+    - Account Usages
+  summary: Returns account usage insights
+  description: >-
+    This API returns a summary of account usage insights for past 12 months.
+  operationId: getUsagesByAccountId
+  parameters:
+    - name: accountId
+      in: path
+      description: ID of IDN account
+      required: true
+      schema:
+        type: string
+      example: 'ef38f94347e94562b5bb8424a56397d8'
+    - $ref: '../../v3/parameters/limit.yaml'
+    - $ref: '../../v3/parameters/offset.yaml'
+    - $ref: '../../v3/parameters/count.yaml'
+    - in: query
+      name: sorters
+      schema:
+        type: string
+        format: comma-separated
+      description: >-
+        Sort results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#sorting-results)
+
+
+        Sorting is supported for the following fields: **date**
+      example: -date
+  security:
+      - UserContextAuth: [ idn:accounts:read ]
+  responses:
+    '200':
+      description: Summary of account usage insights for past 12 months.
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '../schemas/AccountUsage.yaml'
+    '400':
+      $ref: '../../v3/responses/400.yaml'
+    '401':
+      $ref: '../../v3/responses/401.yaml'
+    '403':
+      $ref: '../../v3/responses/403.yaml'
+    '429':
+      $ref: '../../v3/responses/429.yaml'
+    '500':
+      $ref: '../../v3/responses/500.yaml'

idn/v3/paths/source-usage-status.yaml

@@ -0,0 +1,34 @@
+get:
+  tags:
+    - Source Usages
+  summary: Finds status of source usage
+  description: >-
+    This API returns the status of the source usage insights setup by IDN source ID.
+  operationId: getStatusBySourceId
+  parameters:
+    - name: sourceId
+      in: path
+      description: ID of IDN source
+      required: true
+      schema:
+        type: string
+      example: '2c9180835d191a86015d28455b4a2329'
+  security:
+    - UserContextAuth: [ idn:accounts:read ]
+  responses:
+    '200':
+      description: Status of the source usage insights setup by IDN source ID.
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/SourceUsageStatus.yaml'
+    '400':
+      $ref: '../../v3/responses/400.yaml'
+    '401':
+      $ref: '../../v3/responses/401.yaml'
+    '403':
+      $ref: '../../v3/responses/403.yaml'
+    '429':
+      $ref: '../../v3/responses/429.yaml'
+    '500':
+      $ref: '../../v3/responses/500.yaml'

idn/v3/paths/source-usages.yaml

@@ -0,0 +1,50 @@
+get:
+  tags:
+    - Source Usages
+  summary: Returns source usage insights
+  description: >-
+    This API returns a summary of source usage insights for past 12 months.
+  operationId: getUsagesBySourceId
+  parameters:
+    - name: sourceId
+      in: path
+      description: ID of IDN source
+      required: true
+      schema:
+        type: string
+      example: '2c9180835d191a86015d28455b4a2329'
+    - $ref: '../../v3/parameters/limit.yaml'
+    - $ref: '../../v3/parameters/offset.yaml'
+    - $ref: '../../v3/parameters/count.yaml'
+    - in: query
+      name: sorters
+      schema:
+        type: string
+        format: comma-separated
+      description: >-
+        Sort results using the standard syntax described in [V3 API Standard Collection Parameters](https://developer.sailpoint.com/idn/api/standard-collection-parameters#sorting-results)
+
+
+        Sorting is supported for the following fields: **date**
+      example: -date
+  security:
+    - UserContextAuth: [ idn:accounts:read ]
+  responses:
+    '200':
+      description: Summary of source usage insights for past 12 months.
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '../schemas/SourceUsage.yaml'
+    '400':
+      $ref: '../../v3/responses/400.yaml'
+    '401':
+      $ref: '../../v3/responses/401.yaml'
+    '403':
+      $ref: '../../v3/responses/403.yaml'
+    '429':
+      $ref: '../../v3/responses/429.yaml'
+    '500':
+      $ref: '../../v3/responses/500.yaml'

idn/v3/schemas/AccountUsage.yaml

@@ -0,0 +1,14 @@
+type: object
+properties:
+  date:
+    type: string
+    format: date
+    description:
+      The first day of the month for which activity is aggregated.
+    example: '2023-04-21'
+  count:
+    type: integer
+    format: int64
+    description: >-
+      The number of days within the month that the account was active in a source.
+    example: 10

idn/v3/schemas/SourceUsage.yaml

@@ -0,0 +1,14 @@
+type: object
+properties:
+  date:
+    type: string
+    format: date
+    description: >-
+      The first day of the month for which activity is aggregated.
+    example: '2023-04-21'
+  count:
+    type: number
+    format: float
+    description: >-
+      The average number of days that accounts were active within this source, for the month.
+    example: 10.45

idn/v3/schemas/SourceUsageStatus.yaml

@@ -0,0 +1,14 @@
+type: object
+properties:
+  status:
+    type: string
+    description: >-
+      Source Usage Status. Acceptable values are:
+        - COMPLETE
+            - This status means that an activity data source has been setup and usage insights are available for the source.
+        - INCOMPLETE
+            - This status means that an activity data source has not been setup and usage insights are not available for the source.
+    example: COMPLETE
+    enum:
+      - COMPLETE
+      - INCOMPLETE