REST API for Oracle Analytics Cloud

Update a catalog item ACL

post

/api/20210901/catalog/{type}/{id}/actions/updateACL

Update the access control list (ACL) for a catalog item with a given id.

Request

Path Parameters

id(required): string

Catalog item ID in base64url format.
type(required):

Type of catalog item. The content types that this API supports include folders, workbooks, subject areas, analyses, dashboards, dashboard pages, reports, connections, datasets, data flows, sequences, scripts, and semantic models.

Supported Media Types

application/json

Root Schema : schema

Type: object

Show Source

aclList: array aclList

List of ACLs
recursive: boolean

If specified and true, and if the catalog item is a container item, all subitems will inherit the same ACLs.
updateMode: string

Default Value: replaceAll

Allowed Values: [ "ReplaceAll", "ReplaceMatchingAccounts", "DeleteMatchingAccounts" ]

Update mode. ReplaceAll removes all existing ACLs and replaces them with the ACLs provided. ReplaceMatchingAccounts replaces existing ACLs with provided ACLs only for matching accounts. DeleteMatchingAccounts deletes ACLs for the accounts provided.

{
    "type":"object",
    "properties":{
        "aclList":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/CatalogItemACL"
            },
            "description":"List of ACLs"
        },
        "updateMode":{
            "type":"string",
            "enum":[
                "ReplaceAll",
                "ReplaceMatchingAccounts",
                "DeleteMatchingAccounts"
            ],
            "default":"replaceAll",
            "description":"Update mode. ReplaceAll removes all existing ACLs and replaces them with the ACLs provided. ReplaceMatchingAccounts replaces existing ACLs with provided ACLs only for matching accounts. DeleteMatchingAccounts deletes ACLs for the accounts provided."
        },
        "recursive":{
            "type":"boolean",
            "description":"If specified and true, and if the catalog item is a container item, all subitems will inherit the same ACLs."
        }
    }
}

Nested Schema : aclList

Type: array

List of ACLs

Show Source

Array of: object CatalogItemACL

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/CatalogItemACL"
    },
    "description":"List of ACLs"
}

Nested Schema : CatalogItemACL

Type: object

Show Source

accountDisplayName: string

Display name for the user or application role, if available.
accountGuid(required): string

User ID or application role name.
accountType(required): string

Allowed Values: [ "User", "ApplicationRole" ]
permissions: object Permissions

{
    "type":"object",
    "properties":{
        "accountGuid":{
            "type":"string",
            "description":"User ID or application role name."
        },
        "accountType":{
            "$ref":"#/components/schemas/AccountType",
            "description":"User or ApplicationRole."
        },
        "accountDisplayName":{
            "type":"string",
            "description":"Display name for the user or application role, if available."
        },
        "permissions":{
            "$ref":"#/components/schemas/Permissions",
            "description":"Enabled permissions. If a permission isn't specified, the permission is disabled."
        }
    },
    "required":[
        "accountGuid",
        "accountType"
    ]
}

Nested Schema : Permissions

Type: object

Show Source

changePermission: boolean
delete: boolean
execute: boolean
list: boolean
read: boolean
takeOwnership: boolean
write: boolean

{
    "type":"object",
    "properties":{
        "read":{
            "type":"boolean"
        },
        "write":{
            "type":"boolean"
        },
        "execute":{
            "type":"boolean"
        },
        "list":{
            "type":"boolean"
        },
        "delete":{
            "type":"boolean"
        },
        "changePermission":{
            "type":"boolean"
        },
        "takeOwnership":{
            "type":"boolean"
        }
    }
}

Response

Supported Media Types

application/json

200 Response

Successful operation

Root Schema : CatalogItemACLs

Type: array

Show Source

Array of: object CatalogItemACL

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/CatalogItemACL"
    }
}

Nested Schema : CatalogItemACL

Type: object

Show Source

accountDisplayName: string

Display name for the user or application role, if available.
accountGuid(required): string

User ID or application role name.
accountType(required): string

Allowed Values: [ "User", "ApplicationRole" ]
permissions: object Permissions

{
    "type":"object",
    "properties":{
        "accountGuid":{
            "type":"string",
            "description":"User ID or application role name."
        },
        "accountType":{
            "$ref":"#/components/schemas/AccountType",
            "description":"User or ApplicationRole."
        },
        "accountDisplayName":{
            "type":"string",
            "description":"Display name for the user or application role, if available."
        },
        "permissions":{
            "$ref":"#/components/schemas/Permissions",
            "description":"Enabled permissions. If a permission isn't specified, the permission is disabled."
        }
    },
    "required":[
        "accountGuid",
        "accountType"
    ]
}

Nested Schema : Permissions

Type: object

Show Source

changePermission: boolean
delete: boolean
execute: boolean
list: boolean
read: boolean
takeOwnership: boolean
write: boolean

{
    "type":"object",
    "properties":{
        "read":{
            "type":"boolean"
        },
        "write":{
            "type":"boolean"
        },
        "execute":{
            "type":"boolean"
        },
        "list":{
            "type":"boolean"
        },
        "delete":{
            "type":"boolean"
        },
        "changePermission":{
            "type":"boolean"
        },
        "takeOwnership":{
            "type":"boolean"
        }
    }
}

400 Response

Bad Request (invalid query parameters, malformed headers, and so on).

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

401 Response

Unauthorized (missing or expired credentials, and so on).

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

403 Response

Forbidden (missing permissions for operation, request denied for unspecified reason, and so on).

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

404 Response

Not Found. The requested resource was not found.

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

500 Response

Internal Server Error. The server encountered an unexpected condition preventing fulfilment of the request.

Root Schema : Error

Type: object

Show Source

code(required): string

Short error code that defines the error, meant for programmatic parsing.
message(required): string

Human-readable error string.

{
    "type":"object",
    "properties":{
        "code":{
            "type":"string",
            "description":"Short error code that defines the error, meant for programmatic parsing.\n"
        },
        "message":{
            "type":"string",
            "description":"Human-readable error string.\n"
        }
    },
    "required":[
        "code",
        "message"
    ]
}

Examples

You can update the ACL for a catalog item in three different ways:

Example 1 - Replace the entire ACL for a catalog item (updateMode=ReplaceAll)
Example 2 - Update the ACL for one or more users and application roles with access to a catalog item (updateMode=ReplaceMatchingAccounts)
Example 3 - Delete the ACL for one or more users and application roles with access to a catalog object (updateMode=DeleteMatchingAccounts)

These examples show you how to update access control list (ACL) details for a specific catalog object, MySalesWorkbook. The item type value is workbooks. The workbook ID is /@Catalog/shared/Sales/MySalesWorkbook which has the Base64URL-safe encoded id value L0BDYXRhbG9nL3NoYXJlZC9TYWxlcy9NeVNhbGVzV29ya2Jvb2s.

First, obtain the object ID of the workbook you want ACL details for. You can obtain the Object ID value from the Inspect dialog for the item in Oracle Analytics Cloud. Then, Base64URL encode the value to determine the id.

Example 1 - Replace the entire ACL for a catalog item

In this example, you delete the current ACL and replace it with a new ACL for several application roles (BI Consumer, BI Service Administrator, DV Consumer, DV Content Author) and a single user (salesadmin).

cURL Example:

Run the cURL command with the required type and id. Set the update mode to ReplaceAll.

curl -i \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --request POST   'https://<hostname>/api/20210901/catalog/workbooks/L0BDYXRhbG9nL3NoYXJlZC9TYWxlcy9NeVNhbGVzV29ya2Jvb2s/actions/updateACL'  \
     --data '{"updateMode": "ReplaceAll",     \
        "aclList": [ \
         {           \
          "accountGuid": "BIConsumer",           \
          "accountType": "ApplicationRole",      \    
          "accountDisplayName": "BI Consumer",   \ 
          "permissions": {  \
            "read": true,   \
            "write": false, \
            "list": true,   \
            "delete": false, \
            "changePermission": false, \
            "takeOwnership": false    \    
           }   
          },   
          {       
           "accountGuid": "BIServiceAdministrator", \ 
           "accountType": "ApplicationRole",        \ 
           "accountDisplayName": "BI Service Administrator", \ 
           "permissions": { \
            "read": true,  \
            "write": true,  \
            "list": true,  \
            "delete": true, \
            "changePermission": true, \
            "takeOwnership": true     \  
            } \
           }, \
           {  \     
           "accountGuid": "DVConsumer",       \ 
           "accountType": "ApplicationRole",     \ 
           "accountDisplayName": "DV Consumer",   \
           "permissions": { \
            "read": true, \
            "write": false, \
            "list": true, \
            "delete": false, \
            "changePermission": false, \
            "takeOwnership": false      \
            } \
           },  \
           {     \   
           "accountGuid": "DVContentAuthor",     \   
           "accountType": "ApplicationRole",      \  
           "accountDisplayName": "DV Content Author",       
           "permissions": { \
            "read": true, \
            "write": false, \
            "list": true, \
            "delete": false, \
            "changePermission": false, \
            "takeOwnership": false     \   
            } \
           },   \    
           {    \    
           "accountGuid": "salesadmin",   \     
           "accountType": "User",     \   
           "permissions": { \
            "read": true, \
            "write": true, \
            "list": true, \
            "delete": true, \
            "changePermission": true, \
            "takeOwnership": false     \   
           }    \  
        }  \ 
       ] \
    }' \

Example of Request Body

Not applicable.

Example of Response Body

Status 200:

[
 {
   "accountGuid": "BIConsumer",
   "accountType": "ApplicationRole",
   "accountDisplayName": "BI Consumer",
      "permissions": {
          "read": true,
          "write": false,
          "list": true,
          "delete": false,
          "changePermission": false,
          "takeOwnership": false
       }
 },
 {
  "accountGuid": "BIServiceAdministrator",
  "accountType": "ApplicationRole",
  "accountDisplayName": "BI Service Administrator",
      "permissions": {
         "read": true,
         "write": true,
         "list": true,
         "delete": true,
         "changePermission": true,
         "takeOwnership": true
       }
 },
 {
  "accountGuid": "DVConsumer",
  "accountType": "ApplicationRole",
  "accountDisplayName": "DV Consumer",
      "permissions": {
         "read": true,
         "write": false,
         "list": true,
         "delete": false,
         "changePermission": false,
         "takeOwnership": false
       }
 },
 {
  "accountGuid": "DVContentAuthor",
  "accountType": "ApplicationRole",
  "accountDisplayName": "DV Content Author",
      "permissions": {
         "read": true,
         "write": false,
         "list": true,
         "delete": false,
         "changePermission": false,
         "takeOwnership": false
       }
 },
 {
  "accountGuid": "salesadmin",
  "accountType": "User",
      "permissions": {
         "read": true,
         "write": true,
         "list": true,
         "delete": true,
         "changePermission": true,
         "takeOwnership": false
       }
 }
]

Example 2 - Update the ACL for one or more users and application roles with access to a catalog item

In this example, you update the ACL for the DV Content Author application role.

cURL Example:

Run the cURL command with the required type and id. Set the update mode to ReplaceMatchingAccounts.

curl -i  \
     --header 'Authorization: Bearer <token>'  \
     --header 'Content-Type: application/json'  \
     --request POST
'https://<hostname>/api/20210901/catalog/workbooks/L0BDYXRhbG9nL3NoYXJlZC9TYWxlcy9NeVNhbGVzV29ya2Jvb2s/actions/updateACL'  \
     --data '{"updateMode": "ReplaceMatchingAccounts", \
        "aclList": [\
         {      \
            "accountGuid": "DVContentAuthor",    \
            "accountType": "ApplicationRole",   \
            "permissions": { \
              "read": true, \
              "write": false, \
              "list": true, \
              "delete": false , \
              "changePermission": false, \
              "takeOwnership": false     \
             }   \
          }   \
        ] \
     }' \

Example of Request Body

Not applicable.

Example of Response Body

Status 200:

[
 {
  "accountGuid": "DVContentAuthor",
  "accountType": "ApplicationRole",
  "accountDisplayName": "DV Content Author",
      "permissions": {
         "read": true,
         "write": false,
         "list": true,
         "delete": false,
         "changePermission": false,
         "takeOwnership": false
       }
 }
]

Example 3 - Delete the ACL for one or more users and application roles with access to a catalog item

In this example, you remove the ACL for the salesadmin user.

cURL Example:

Run the cURL command with the required type and id. Set the update mode to DeleteMatchingAccounts.

curl -i  \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --request POST
'https://<hostname>/api/20210901/catalog/workbooks/L0BDYXRhbG9nL3NoYXJlZC9TYWxlcy9NeVNhbGVzV29ya2Jvb2s/actions/updateACL' \
     --data '{"updateMode": "DeleteMatchingAccounts", \
        "aclList": [\
         {        \
          "accountGuid": "salesadmin",  \
          "accountType": "User",        \
          "permissions": {  \
            "read": true,   \
            "write": false, \
            "list": true,   \
            "delete": false,   \
            "changePermission": false,   \
            "takeOwnership": false     \
           }  \
        }     \
       ]      \
    }'        \

Example of Request Body

Not applicable.

Example of Response Body

Status 200: