Permissions API Overview

Learn more about the Permissions API.

With the Permissions API, you can programmatically update, create, and delete permissions in Visier as needed.

Note:  

  • To assign permissions to users or user groups, see Users API.
  • Permissions are versioned in Visier, meaning any permission changes through the API cause a project to publish to production with your changes. We recommend that you make permission changes sequentially and in bulk; for example, wait until your create call is successful before trying to update a permission. You can make up to 1000 definitions (create, update, delete) per API call.

Before working with permissions, you first need to understand the parts of a permission. For more information, see Permission Management.

With this API, you can retrieve all the parts that exist in your tenant: permission capabilities, content packages, and data security objects. After you have the data security objects (the available analytic objects you can assign data security to), you can retrieve the analytic object's dimensions and then retrieve the dimension's members. The dimension members are the populations to define security access for; for example, you might retrieve the members of the dimension Location so that you can assign security access to employees in New York specifically. For more information about security filters, see Security Filters.

After retrieving all the information, you can use the returned IDs to assign specific components to permissions with the API.

Create permissions in bulk

To create permissions in bulk and assign the permissions to users, use these API calls in order:

  1. GET /v1/admin/capabilities Retrieve a list of all permission capabilities: Get the list of available capabilities so you know what capabilities are available to assign to permissions.
  2. GET /v1/admin/content-packages Retrieve a list of all content packages: Get the list of available content packages so you know what content packages are available to assign to permissions.
  3. GET /v1/admin/data-security-objects Retrieve a list of data security objects: Get the list of available analytic objects so you know what objects are available to assign to permissions.
  4. GET /v1/data/model/analytic-objects/{objectId}/dimensions Retrieve a list of dimensions: Get the dimensions associated with a specific analytic object so you know what dimensions you can define security access to.
  5. GET /v1/data/model/analytic-objects/{objectId}/dimensions/{dimensionId}/members Retrieve a list of dimension members: Get the members of a specific dimension so you know what members you can define security access to.
  6. POST /v1/admin/permissions Create permissions: Put together an API call using the unique IDs retrieved from the previous API calls to create one or more permissions.
  7. PUT /v1/admin/permissions/users Assign permissions to users: Use the permission IDs returned by the previous API call to assign the permission to a list of users.

Update permissions in bulk

When you're ready to update a permission, you can retrieve the list of permissions to get the ID of the permissions you want to update.

To update permissions in bulk, use these API calls in order:

  1. GET /v1/admin/capabilities Retrieve a list of all permission capabilities: Get the list of available capabilities so you know what capabilities are available to assign to permissions.
  2. GET /v1/admin/content-packages Retrieve a list of all content packages: Get the list of available content packages so you know what content packages are available to assign to permissions.
  3. GET /v1/admin/data-security-objects Retrieve a list of data security objects: Get the list of available analytic objects so you know what objects are available to assign to permissions.
  4. GET /v1/data/model/analytic-objects/{objectId}/dimensions Retrieve a list of dimensions: Get the dimensions associated with a specific analytic object so you know what dimensions you can define security access to.
  5. GET /v1/data/model/analytic-objects/{objectId}/dimensions/{dimensionId}/members Retrieve a list of dimension members: Get the members of a specific dimension so you know what members you can define security access to.
  6. GET /v1/admin/permissions Retrieve a list of all permissions: Get the list of available permissions so you know what permissions you can update.
  7. PUT /v1/admin/permissions Update permissions: Put together an API call using the unique IDs retrieved from the previous API calls to update one or more permissions.

    Caution: In PUT (update) API calls, the request body replaces the target resource. When updating a permission, the PUT request body must contain all data security objects, capabilities, and content packages applicable to the permission.

Delete permissions in bulk

If the permission is assigned to any users or user groups, deleting the permission removes it from their security context. We recommend reviewing permission assignments before deleting it to ensure your users will have the correct capabilities, access to content, and data security after you delete the permission.

To delete permissions in bulk, use these API calls in order:

  1. GET /v1/admin/permissions Retrieve a list of all permissions: Get the list of available permissions so you know what permissions you can delete.
  2. DELETE/v1/admin/permissions Delete permissions: Put together an API call using the unique IDs retrieved from the previous API call to delete one or more permissions.

Assign access for data columns that aren't in Visier yet

If your organization added new columns to your data, you can use the Permissions API to secure access to those columns before the data is sent to Visier. You can streamline your data security workflow by updating population and data access ahead of time through this API before Visier receives the new data columns or before you create the objects in Visier.

Note: You can assign access to properties and dimensions that aren't in Visier yet, but not analytic objects. To assign access to analytic objects that aren't in Visier yet, contact your Customer Success Manager. The analyticObjectId in the API request must exactly match the analytic object's object name when you create it in Visier.

If assigning access for data columns that aren't in Visier yet, ensure:

  • The ID you use in the API call:
    • Only contains alphanumeric characters (A-Z, a-z, 0-9) or underscores (_).
    • Is between 3 and 200 characters long.
    • Doesn't begin with a number (0-9).
  • The ID you use in the API call must match the object name in Visier exactly. Let's say you assigned a member filter for a new data column with the dimensionId No_Data_Dimension. When you create the associated dimension in Visier, its object name must be No_Data_Dimension. This is because Visier connects source data to Visier objects by matching the column name and object name.
  • The propertyId, namePath, or hierarchyPropertyId in the API call must match the data column values exactly. Let's say you assigned a member filter for a new data column with the namePath No_Data_Dimension_Member. When you send the data to Visier, the data column value must contain No_Data_Dimension_Member. This is because Visier populates dimension members based on the data column values. If your data column values don't match the IDs you provided in the API call, data access isn't assigned correctly.

To assign access to data that isn't yet in Visier, you can use the following POST or PUT endpoints:

  • POST /v1/admin/permissions Create permissions: Create one or more permissions. In the API call, use the propertySetConfig and memberFilterConfigs request body fields to assign access in a new permission. For an example of this API call, see Create permissions.
  • PUT /v1/admin/permissionsUpdate permissions: Update one or more existing permissions. In the API call, use the propertySetConfig and memberFilterConfigs request body fields to assign access in existing permissions.

    Caution: In PUT (update) API calls, the request body replaces the target resource. When updating a permission, the PUT request body must contain all data security objects, capabilities, and content packages applicable to the permission.

If you want to know if a permission already has access assigned for your new data or if the data is already in Visier, use the following GET endpoints with the URL parameter includeDetailsWithStatus=true:

  • GET /v1/admin/permissions?includeDetailsWithStatus=true Retrieve a list of all permissions: Get the list of available permissions and the status of assigned data access for properties and population access for dimensions.
  • GET /v1/admin/permissions/{permissionId}?includeDetailsWithStatus=true Retrieve a permission's details: Get the details of a specific permission and the status of assigned data access for properties and population access for dimensions. For an example of this API call, see Retrieve a permission's details.

The response returns a Status field for each property assigned data access and each dimension or dimension member assigned population access in the permission. The possible statuses are:

  • Valid: The object exists in Visier and has loaded data. This means the new data is in Visier, mapped to a Visier object, and permission access is set.
  • NoData: The object exists in Visier but doesn't have loaded data. This means the object is available in Visier but doesn't have data loaded or mapped to it, and permission access is set.
  • NotFound: The object doesn't exist in Visier. This means you haven't created the object in Visier yet, data isn't mapped to it (because it doesn't exist), and permission access is set.

If you don't see your new data columns or column values returned by the API call, you haven't assigned permission access to the data yet.

The following table describe permission behavior if any of the assigned dimensions or properties don't have data or don't exist in Visier.

Scenario

Description

Examples

Permission with data access to a property that doesn't have data or doesn't exist in Visier.

The permission ignores the property until data is available. The permission's data security is valid and grants access to all other valid properties.

In this example, a permission grants data access to EmployeeID, Gender, and Birth Date. If EmployeeID and Gender have data but Birth Date doesn't, the permission grants access to EmployeeID and Gender. It will grant access to Birth Date after Birth Date data is loaded.

Permission with population access to a dimension that doesn't have data or doesn't exist in Visier.

The population access isn't valid because the dimension doesn't have data or doesn't exist. The permission doesn't grant population access until data is available for all dimensions in the filter.

In this example, a permission grants population access to Gender: Woman and Location: North America. If Gender has data but Location doesn't, North America isn't valid so the permission doesn't grant population access for Gender: Woman and Location: North America until Location has data.

Permission with population access to a dimension that has data and exists with multiple dimension members selected. Some dimension members have data and exist in Visier, and some do not exist in Visier.

The permission ignores dimension members that don't exist until data is available. The population access is valid, and the permission grants access to any dimension members that have data and exist and ignores dimension members that don't exist.

In this example, a permission grants population access to Gender: Woman and Location: North America, South America. If Gender: Woman and Location: South America both have data but Location: North America doesn't, the permission only grants population access to subject members who are women in South America. The permission will grant access to women in South America and women in North America after the North America dimension member exists in Visier.

Permission with population access to a dimension that has data and exists, but the filter is only for dimension members that don't have data or don't exist in Visier.

The population access isn't valid because there are no dimension members that have data or exist. The permission doesn't grant population access for the dimension members in the filter until data is available.

In this example, a permission grants population access to Location: North America, South America. If Location: North America and South America both don't have data the permission doesn't grant any population access because the entire filter is not valid.