diff --git a/idn/beta/paths/account-usages.yaml b/idn/beta/paths/account-usages.yaml index df26489e..43c649e5 100644 --- a/idn/beta/paths/account-usages.yaml +++ b/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 diff --git a/idn/beta/paths/source-usages.yaml b/idn/beta/paths/source-usages.yaml index 9b508d25..69a9792e 100644 --- a/idn/beta/paths/source-usages.yaml +++ b/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 diff --git a/idn/sailpoint-api.beta.yaml b/idn/sailpoint-api.beta.yaml index 87e3e286..34207e36 100644 --- a/idn/sailpoint-api.beta.yaml +++ b/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" diff --git a/idn/sailpoint-api.v3.yaml b/idn/sailpoint-api.v3.yaml index d394b9c2..058ab1d2 100644 --- a/idn/sailpoint-api.v3.yaml +++ b/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' diff --git a/idn/v3/paths/account-usages.yaml b/idn/v3/paths/account-usages.yaml new file mode 100644 index 00000000..43c649e5 --- /dev/null +++ b/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' \ No newline at end of file diff --git a/idn/v3/paths/source-usage-status.yaml b/idn/v3/paths/source-usage-status.yaml new file mode 100644 index 00000000..b5655841 --- /dev/null +++ b/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' diff --git a/idn/v3/paths/source-usages.yaml b/idn/v3/paths/source-usages.yaml new file mode 100644 index 00000000..69a9792e --- /dev/null +++ b/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' \ No newline at end of file diff --git a/idn/v3/schemas/AccountUsage.yaml b/idn/v3/schemas/AccountUsage.yaml new file mode 100644 index 00000000..eeaffa78 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/idn/v3/schemas/SourceUsage.yaml b/idn/v3/schemas/SourceUsage.yaml new file mode 100644 index 00000000..410857e1 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/idn/v3/schemas/SourceUsageStatus.yaml b/idn/v3/schemas/SourceUsageStatus.yaml new file mode 100644 index 00000000..07139156 --- /dev/null +++ b/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 \ No newline at end of file