In Oracle Analytics Cloud, users can programmatically review and change the access control list for catalog objects using the catalog REST API. This API is particularly useful to administrators, for example:

  • After importing new content, administrators often want to share the content with individual users or multiple users through application roles.
  • After a user leaves the organization, administrators might need to give other users access to that user’s content.
  • Administrators might need to keep track of the access granted to certain folders and assets.

Folder access

Catalog REST API

The catalog REST API enables you to perform the following operations programmatically:

  • Copy a catalog item
  • Create a folder
  • Get catalog ACL
  • Get catalog item details
  • Get catalog items
  • Get catalog items by type
  • Move a catalog item
  • Update a catalog item ACL

This article focuses on the ACL (Access Control List) operations. 

Listing Access Control Entries

When administrators inspect an object in the catalog through the dialog, they see the access control list entries for the users and roles who can access the object for different purposes:

Workbook ACL

You can return the same information using the catalog REST API. First, you must determine the ID of the catalog object, and then you can get the ACL for that object.

Tip: Take some time to become familiar with the Oracle Analytics Cloud documentation for REST APIs here. Authentication for these APIs is based on OAuth and the supported approaches are described here.

Finding the ID of Catalog Items

The documentation for the Catalog REST API gives an example of how to find the ID of a workbook:

Doc example get ID

This API call returns JSON for the results. Here’s a search for workbooks with a name containing the string “Change” that returned the following JSON:

ID return

The JSON contains the ID of the workbook (ChangemeACL). You use this ID to review and then modify the ACL of the catalog item.

Getting the ACL of a Catalog Item

Now that you know the ID of the catalog item that you want to update, you call the getACL operation to determine the current ACL. The getACL operation, as listed in the documentation, looks like this:

getACL

This API returns JSON that describes all the access control entries for the item:

ACL

Updating the ACL of a Catalog Item

Now that you have the ACL of the item that you want to update, you can modify the ACL in your favorite JSON editor. After changing the JSON, you use the updateACL operation to update the ACL.
 

update ACL signature

Here’s a curl command for updateACL using the modified ACL. The payload is the updated ACL in JSON format:

updateACL

You can check your updates through the dialog (or API):

updated ACL UI

Good to Know

Bear in mind that although the catalog API can deal with various different types of objects including workbooks, datasets, and connections, the API returns only objects that the user calling the API has permission to access. 

The catalog API doesn’t provide an “administrator view:” that is, the ability to list all the catalog objects regardless of their ACLs. The Content Management page does offer this functionality, but this feature isn’t possible through the API. If necessary, administrators can change ownership on catalog objects through the Content Management page, so they have the required access to list and change ACLs using the API.

Call to Action

Listing and updating catalog access control lists is just one of the tools available to effectively manage assets in your catalog. If you have related requirements that aren’t yet addressed, get involved in the Oracle Analytics Community. Add an idea in the Ideas Lab or vote for and comment on an existing idea that matches your requirements. Find the Ideas Lab here.