openapi: 3.2.0 info: title: Visier Administration User Groups V2 API description: Visier APIs for managing your tenant or tenants in Visier. license: name: Apache License, Version 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 22222222.99201.3040 security: - ApiKeyAuth: [] BearerAuth: [] - ApiKeyAuth: [] CookieAuth: [] - ApiKeyAuth: [] OAuth2Auth: [] tags: - name: User Groups V2 x-displayName: User Groups V2 description: Manage user groups in Visier, such as creating, updating, and deleting user groups in bulk. paths: /v2/admin/user-groups: get: tags: - User Groups V2 summary: Retrieve a list of user groups description: 'Retrieve a collection of user groups. Use `with` to control the amount of detail returned in the response. `with` supports these values: * **permissions**: Include the user group''s permissions. * **users**: Include the users in the user group. * **details**: Include all available information. This API can return a maximum of 1000 user groups. The default number of user groups to return is 100. To specify the project in which to return user groups, provide a project UUID in the `ProjectID` request header. To specify the tenant in which to retrieve user groups, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header.' operationId: UserGroupsV2_GetUserGroups parameters: - name: with in: query description: "Controls the amount of detail to return in the response. Omit to return basic information.\n * **permissions**: Include the user group's permissions.\n * **users**: Include the users in the user group.\n * **details**: Include all available information." schema: enum: - permissions - users - details type: string format: enum - name: limit in: query description: The number of results to return. The maximum number of user groups to retrieve is 1000. The default is 100. schema: type: integer format: uint32 - name: start in: query description: The index to start retrieving results from, also known as offset. The index begins at 0. schema: type: integer format: uint32 - name: displayNameFilter in: query description: "The display name filter to narrow the set of user groups to return. This filter must be defined using glob syntax with the following wildcards and is case-sensitive. The value in parentheses is the equivalent hex code, which is used when URL-encoding the filter string:\n - `'*'` (`%2A`) matches any sequence of characters.\n - `'?'` (`%3F`) matches a single character.\n - `' '` (`%20`) matches a space character.\n \n Example: \n - `Sales*` matches any user group that starts with \"Sales\".\n - `* ?egional * Office` is expressed as `%2A%20%3Fegional%20%2A%20Office` and can have many matches, such as \"Western Regional Support Office\"." schema: type: string - name: correlationIds in: query description: "If defined, `correlationIds` limits the response to the user groups associated with the specified correlation IDs.\n You can specify multiple correlation IDs in the `correlationIds` parameter separated by commas; for example, `correlationIds=123,abc,456`.\n\n **Note**:\n - Correlation IDs must be between 3 and 64 characters long and may only contain alphanumeric characters, underscores and hyphens.\n - Correlation IDs have a lifetime of up to 7 days after creation. After a correlation ID expires, you can only retrieve specific user groups using the user group ID.\n - Correlation IDs are optional during user group creation and are only applicable to those objects created with a defined correlation ID." schema: type: string - name: TargetTenantID in: header description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant. schema: type: string - name: ProjectID in: header description: Optionally, specify a project in which to make the request. schema: type: string format: uuid - name: NonVersioned in: header description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`. schema: type: boolean responses: default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' '200': description: OK content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupsChangeDTO' put: tags: - User Groups V2 summary: Update multiple user groups description: 'Update existing user groups. To specify the tenant in which to update a user group, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header or `tenantCode` for each user group in the request body. When updating user groups, the user group definition in your API call replaces the prior definition. You must provide the entire definition in the `PUT` call. If you omit values from the update request, those values are removed from the user group. We recommend that you retrieve a user group''s details before you update the user group with new values. To specify the project in which to update user groups, provide a project UUID in the `ProjectID` request header or `projectId` for each user group in the request body.' operationId: UserGroupsV2_PutUserGroups parameters: - name: TargetTenantID in: header description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant. schema: type: string - name: ProjectID in: header description: Optionally, specify a project in which to make the request. schema: type: string format: uuid - name: NonVersioned in: header description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`. schema: type: boolean requestBody: content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupsChangeDTO' required: true responses: default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' '200': description: OK content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupChangeResponseDTO' post: tags: - User Groups V2 summary: Create multiple user groups description: 'Create new user groups. To specify the tenant in which to add new user groups, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header. To specify the project in which to create new user groups, provide a project UUID in the `ProjectID` request header or `projectId` for each user group in the request body.' operationId: UserGroupsV2_CreateUserGroups parameters: - name: TargetTenantID in: header description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant. schema: type: string - name: ProjectID in: header description: Optionally, specify a project in which to make the request. schema: type: string format: uuid - name: NonVersioned in: header description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`. schema: type: boolean requestBody: content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupsChangeDTO' required: true responses: default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' '200': description: OK content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupChangeResponseDTO' delete: tags: - User Groups V2 summary: Delete multiple user groups description: 'Delete user groups in bulk. To specify the tenant in which to delete user groups, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header. To specify the project in which to delete user groups, provide a project UUID in the `ProjectID` request header or `projectId` for each user group in the request body.' operationId: UserGroupsV2_DeleteUserGroups parameters: - name: TargetTenantID in: header description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant. schema: type: string - name: ProjectID in: header description: Optionally, specify a project in which to make the request. schema: type: string format: uuid - name: NonVersioned in: header description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`. schema: type: boolean requestBody: content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupsDeleteRequestDTO' required: true responses: default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' '200': description: OK content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupDeleteResponseDTO' patch: tags: - User Groups V2 summary: Patch multiple user groups description: 'Make partial changes to user groups. To specify the tenant in which to patch a user group, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header or `tenantCode` for each user group in the request body. Unlike `PUT`, which completely replaces the user group definition, use `PATCH` to change specific fields in the user group without affecting omitted fields. To specify the project in which to patch user groups, provide a project UUID in the `ProjectID` request header or `projectId` for each user group in the request body.' operationId: UserGroupsV2_PatchUserGroups parameters: - name: TargetTenantID in: header description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant. schema: type: string - name: ProjectID in: header description: Optionally, specify a project in which to make the request. schema: type: string format: uuid - name: NonVersioned in: header description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`. schema: type: boolean - name: Prefer in: header description: 'When `NonVersioned: true`, use `Prefer` to optionally specify if API calls should be subject to locking. Locking prevents incremental changes in multiple API calls from overwriting each other. The `Prefer` header works alongside a tenant feature flag. When enabled, the default is `nvLock=global`. When disabled, the default is not to lock API calls. Contact Visier Technical Support to enable the tenant feature flag. Valid values for the `Prefer` header: * `nvLock=global`: Run API calls sequentially. Sequential API calls prevent calls from unintentionally overwriting each other. * `nvLock=artifact`: Allow API calls in parallel. Parallel API calls only work if the calls do not conflict with each other. If a change wasn''t applied, the request fails and returns the HTTP 409 conflict error. Run the request again until successful. * `nvLock=none`: Disable the global lock if the tenant feature flag is enabled.' schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupsChangeDTO' required: true responses: default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' '200': description: OK content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupChangeResponseDTO' /v2/admin/user-groups/revert-to-parent: post: tags: - User Groups V2 summary: Revert user groups description: 'Revert a user group to its parent version. For example, if you revert a: - Tenant override object: The object reverts to the Blueprint version or, for administrating tenants who revert an analytic tenant''s object, the administrating tenant''s object version. - Tenant object: The API request fails. The object is unique to your tenant and no parent version exists. - Blueprint object: Nothing happens. The object is inherited from the parent and there is nothing to revert on this tenant.' operationId: UserGroupsV2_RevertUserGroupsToParent parameters: - name: TargetTenantID in: header description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant. schema: type: string - name: ProjectID in: header description: Optionally, specify a project in which to make the request. schema: type: string format: uuid - name: NonVersioned in: header description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`. schema: type: boolean requestBody: content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupsRevertRequestDTO' required: true responses: default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' '200': description: OK content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupChangeResponseDTO' /v2/admin/user-groups/{userGroupId}: get: tags: - User Groups V2 summary: Retrieve the details of a user group description: 'Retrieve all available information about a specific user group. To specify the tenant in which to retrieve a user group, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header. To specify the project in which to return a user group, provide a project UUID in the `ProjectID` request header.' operationId: UserGroupsV2_GetUserGroup parameters: - name: userGroupId in: path description: The ID of user group. required: true schema: type: string - name: with in: query description: "Controls the amount of detail to return in the response. Omit to return detailed information.\n * **permissions**: Include the user group's permissions.\n * **users**: Include the users in the user group.\n * **details**: Include all available information." schema: enum: - permissions - users - details type: string format: enum - name: TargetTenantID in: header description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant. schema: type: string - name: ProjectID in: header description: Optionally, specify a project in which to make the request. schema: type: string format: uuid - name: NonVersioned in: header description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`. schema: type: boolean responses: default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' '200': description: OK content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupChangeDefinitionDTO' delete: tags: - User Groups V2 summary: Delete a user group description: 'Delete a specific user group. To specify the tenant in which to delete a user group, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header. To specify the project in which to delete a user group, provide a project UUID in the `ProjectID` request header.' operationId: UserGroupsV2_DeleteUserGroup parameters: - name: userGroupId in: path description: The ID of user group to delete. required: true schema: type: string - name: TargetTenantID in: header description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant. schema: type: string - name: ProjectID in: header description: Optionally, specify a project in which to make the request. schema: type: string format: uuid - name: NonVersioned in: header description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`. schema: type: boolean responses: default: description: Default error response content: application/json: schema: $ref: '#/components/schemas/Status' '200': description: OK content: application/json: schema: $ref: '#/components/schemas/admin.UserGroupSingleDeleteResponseDTO' components: schemas: admin.UserGroupsChangeDTO: type: object properties: userGroups: type: array items: $ref: '#/components/schemas/admin.UserGroupChangeDefinitionDTO' description: The user groups and their definitions. admin.UserGroupChangeSuccessDTO: type: object properties: displayName: type: string description: The display name of the user group that was successfully changed. userGroupId: type: string description: The unique identifier of the user group. tenantCode: type: string description: The code of the tenant in which the user group was changed. projectId: type: string description: The unique identifier of the project in which the user group was changed. correlationId: type: string description: An identifier to associate the matching request field. Only returned if a `correlationId` was defined for the corresponding request field. admin.UserGroupsRevertRequestDTO: type: object properties: userGroups: type: array items: $ref: '#/components/schemas/admin.UserGroupRevertDTO' description: The user groups to revert. admin.ElementIDsDTO: type: object properties: ids: type: array items: type: string description: The unique identifiers. admin.UserGroupFiltersDTO: type: object properties: filters: type: array items: $ref: '#/components/schemas/admin.UserGroupChangeFilterDTO' description: The filters that define user group membership. admin.UserGroupSingleDeleteResponseDTO: type: object properties: success: allOf: - $ref: '#/components/schemas/admin.UserGroupDeleteSuccessDTO' description: The user group was successfully deleted. failure: allOf: - $ref: '#/components/schemas/admin.UserGroupDeleteFailureDTO' description: The user group was not successfully deleted. admin.UserGroupChangeResponseDTO: type: object properties: successes: type: array items: $ref: '#/components/schemas/admin.UserGroupChangeSuccessDTO' description: The user groups that were successfully changed (created, updated, patched, or reverted). failures: type: array items: $ref: '#/components/schemas/admin.UserGroupChangeFailureDTO' description: The user groups that were not successfully changed (created, updated, patched, or reverted). admin.UserGroupDeleteSuccessDTO: type: object properties: tenantCode: type: string description: The code of the tenant the user group was deleted from. userGroupId: type: string description: The unique identifier of the user group that was deleted. projectId: type: string description: The ID of the project in which user group was deleted. admin.UserGroupChangeMemberSelectionDTO: type: object properties: isExcluded: type: boolean description: If `true`, the specified member must not be defined for members of the user group. namePath: type: array items: type: string description: The name path for dimension members; for example, `[ "North America", "US", "CA" ]`. admin.UserGroupRevertDTO: type: object properties: tenantCode: type: string description: "The code of the tenant in which to revert the user group.\n Omit if reverting user groups in the current tenant." userGroupId: type: string description: The unique identifier for the user group. projectId: type: string description: "The unique identifier of the project in which to revert the user group.\n If omitted and the `ProjectID` request header is not defined, the change is published to production immediately." admin.VisibleForSelectionDTO: type: object properties: enabled: type: boolean description: "If `true`, the user group is visible in features such as sharing an analysis with user groups or assigning user groups a Vee sample question. Cannot update to `true` if `features` is empty.\n If `false`, the user group is not visible to select in any features.\n Default is `true`." features: type: array items: enum: - AnalyticsFeatures - StudioFeatures type: string format: enum description: "The features in which the user group is visible. Default is empty.\n If `enabled` is `true`, the user group is visible in features listed.\n If `enabled` is `false`, this field is ignored." admin.UserGroupChangeDimensionFilterDTO: type: object properties: dimensionId: type: string description: The object name of the dimension. subjectReferencePath: allOf: - $ref: '#/components/schemas/admin.ElementIDsDTO' description: "A qualifying path if the dimension is from an analytic object that references Employee.\n For example, use `subjectReferencePath` to create a filter on the `Employment_Start_Type` dimension from the `Employment_Start` object, which references `Employee`: `{ \"ids\": [ \"Employee\", \"Employment_Start\" ] }`." memberSelections: type: array items: $ref: '#/components/schemas/admin.UserGroupChangeMemberSelectionDTO' description: The dimension members to select in the dynamic filter. admin.UserGroupDeleteDTO: type: object properties: tenantCode: type: string description: "The code of the tenant from which to delete the user group.\n Omit if deleting user groups in the current tenant." userGroupId: type: string description: Unique identifier for the user group. projectId: type: string description: "The project ID in which to delete the user group.\n If omitted and the `ProjectID` request header is not defined, the change is published to production immediately." admin.UserGroupsDeleteRequestDTO: type: object properties: userGroups: type: array items: $ref: '#/components/schemas/admin.UserGroupDeleteDTO' description: The user groups to delete. admin.UserGroupChangeUsersDTO: type: object properties: includeAllUsers: type: boolean description: "If `true`, all users are included in the user group. If `true`:\n * You can manually exclude users with `manuallyExcludedIds`.\n * Cannot be combined with `manuallyIncludedIds` or `dynamicFilterDefinition`." manuallyIncludedIds: allOf: - $ref: '#/components/schemas/admin.ElementIDsDTO' description: "Includes specified user IDs in the user group.\n * May be combined with `dynamicFilterDefinition`.\n * Omit if `includeAllUsers` is `true`." manuallyExcludedIds: allOf: - $ref: '#/components/schemas/admin.ElementIDsDTO' description: "Excludes specified user IDs from the user group.\n * You can manually exclude users if `includeAllUsers` is `true` or if `dynamicFilterDefinition` is defined.\n * Excluded IDs must not overlap with user IDs in `manuallyIncludedIds`." dynamicFilterDefinition: allOf: - $ref: '#/components/schemas/admin.UserGroupFiltersDTO' description: "The filters that dynamically define a population through dimensions or dimensions accessible through references from the analytic object.\n * Omit if `includeAllUsers` is `true`.\n * You can combine dynamic filters with manually-assigned users." admin.UserGroupChangeDefinitionDTO: type: object properties: userGroupId: type: string description: The unique identifier of the user group. Omit if creating a new user group. displayName: type: string description: An identifiable user group name to display in Visier, such as "Leadership User Group". description: type: string description: A detailed description of the population and purpose of the user group. permissionIds: allOf: - $ref: '#/components/schemas/admin.ElementIDsDTO' description: The unique identifiers of permissions assigned to members of this user group. users: allOf: - $ref: '#/components/schemas/admin.UserGroupChangeUsersDTO' description: The users assigned to the user group. You can define user group members dynamically with `dynamicFilterDefinition` or manually with `includeAllUsers` or `manuallyIncludedIds`. tenantCode: type: string description: "The code of the tenant to which the user group belongs or should be created in.\n Omit if creating or updating user groups in the current tenant." projectId: type: string description: "The project ID in which to update or create the user group.\n If omitted and the ProjectID request header is not defined, the change is published to production immediately." visibleForSelection: allOf: - $ref: '#/components/schemas/admin.VisibleForSelectionDTO' description: The features in which your users can see and select this user group. If omitted, the user group is visible in all features. correlationId: type: string description: "An optional identifier to associate bulk request fields with their corresponding response fields. Correlation IDs may be between 3 and 64 characters long and\n consist of alphanumeric characters, `-`, and `_`.\n\n **Note**:\n - Each request field must have a unique `correlationId`.\n - Cannot reuse a `correlationId` in subsequent POST requests while the ID is still active. A `correlationId` is active for 7 days after creation." admin.UserGroupChangeFailureDTO: type: object properties: displayName: type: string description: The display name of the user group that couldn't be changed. message: type: string description: The error message containing the cause of the failure. rci: type: string description: The root cause identifier to provide to Visier Technical Support if you require further troubleshooting. tenantCode: type: string description: The code of the tenant in which the user group couldn't be changed. projectId: type: string description: The unique identifier of the project in which the user group couldn't be changed. userGroupId: type: string description: The unique identifier of the user group that couldn't be changed. correlationId: type: string description: An identifier to associate the matching request field. Only returned if a `correlationId` was defined for the corresponding request field. admin.UserGroupDeleteFailureDTO: type: object properties: tenantCode: type: string description: The code of the tenant from which the user group could not be deleted. userGroupId: type: string description: The unique identifier of the user group that could not be deleted. message: type: string description: The error message containing the cause of the failure. rci: type: string description: The root cause identifier to provide to Visier Technical Support if you require further troubleshooting. projectId: type: string description: The ID of the project in which the user group could not be deleted. admin.UserGroupDeleteResponseDTO: type: object properties: successes: type: array items: $ref: '#/components/schemas/admin.UserGroupDeleteSuccessDTO' description: The user groups that were successfully deleted. failures: type: array items: $ref: '#/components/schemas/admin.UserGroupDeleteFailureDTO' description: The user groups that were not deleted successfully. admin.UserGroupChangeFilterDTO: type: object properties: filterId: type: string description: The unique identifier of the filter. Omit if creating a new filter. analyticObjectId: type: string description: The analytic object the filter applies to. Currently, the only supported analytic object is `Employee`. Default is `Employee`. dimensionFilters: type: array items: $ref: '#/components/schemas/admin.UserGroupChangeDimensionFilterDTO' description: The dimensions in the dynamic filter. Status: type: object properties: localizedMessage: type: string description: Localized error message describing the root cause of the error. code: type: string description: Error classification. message: type: string description: Not used. rci: type: string description: Optional root cause identifier. userError: type: boolean description: Indicates whether the error is a user error. description: The response structure for errors. securitySchemes: CookieAuth: type: apiKey name: VisierASIDToken in: cookie ApiKeyAuth: type: apiKey name: apikey in: header BearerAuth: type: http scheme: bearer OAuth2Auth: type: oauth2 flows: authorizationCode: authorizationUrl: /v1/auth/oauth2/authorize tokenUrl: /v1/auth/oauth2/token scopes: read: Grants read access write: Grants write access password: tokenUrl: /v1/auth/oauth2/token scopes: read: Grants read access write: Grants write access x-tagGroups: - name: administration tags: - Projects - ProductionVersions - UsersV3 - UsersV2 - UserGroupsV2 - UsersV1 - Profiles - Permissions - TenantsV2 - TenantsV1 - ConsolidatedAnalytics - Sources - SystemStatus - EmailDomains - EncryptionKeys - NetworkSubnets - SidecarSolutions - ReleaseVersionConfiguration - VeeConfiguration