REST API for Oracle Analytics Cloud

Update workbook share permissions

post

/api/20210901/catalog/workbooks/{id}/actions/updateSharePermissions

Update share permissions for a workbook with a given ID.

Request

Path Parameters

id(required): string

Catalog item ID in base64url format.

Supported Media Types

application/json

Root Schema : schema

Type: object

Show Source

sharePermissions(required): array sharePermissions

Workbook share permissions to update. Each accountGuid and accountType pair must be unique. Setting both view and edit to false removes share permissions for that account.
updateMode: string

Default Value: ReplaceAll

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

Update mode. ReplaceAll removes all existing workbook share permissions and replaces them with the permissions provided. ReplaceMatchingAccounts replaces permissions for matching accounts, adds accounts that don't currently have share permissions, and preserves accounts omitted from the request. DeleteMatchingAccounts removes share permissions for the accounts provided and ignores their permissions property.

{
    "type":"object",
    "properties":{
        "updateMode":{
            "type":"string",
            "enum":[
                "ReplaceAll",
                "ReplaceMatchingAccounts",
                "DeleteMatchingAccounts"
            ],
            "default":"ReplaceAll",
            "description":"Update mode. ReplaceAll removes all existing workbook share permissions and replaces them with the permissions provided. ReplaceMatchingAccounts replaces permissions for matching accounts, adds accounts that don't currently have share permissions, and preserves accounts omitted from the request. DeleteMatchingAccounts removes share permissions for the accounts provided and ignores their permissions property."
        },
        "sharePermissions":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/WorkbookSharePermission"
            },
            "description":"Workbook share permissions to update. Each accountGuid and accountType pair must be unique. Setting both view and edit to false removes share permissions for that account."
        }
    },
    "required":[
        "sharePermissions"
    ]
}

Nested Schema : sharePermissions

Type: array

Workbook share permissions to update. Each accountGuid and accountType pair must be unique. Setting both view and edit to false removes share permissions for that account.

Show Source

Array of: object WorkbookSharePermission

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/WorkbookSharePermission"
    },
    "description":"Workbook share permissions to update. Each accountGuid and accountType pair must be unique. Setting both view and edit to false removes share permissions for that account."
}

Nested Schema : WorkbookSharePermission

Type: object

Show Source

accountDisplayName: string

Read Only: true

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

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

{
    "type":"object",
    "properties":{
        "accountGuid":{
            "type":"string",
            "description":"User ID or application role name."
        },
        "accountType":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/AccountType"
                },
                {
                    "description":"User or ApplicationRole."
                }
            ]
        },
        "accountDisplayName":{
            "type":"string",
            "readOnly":true,
            "description":"Display name for the user or application role, if available."
        },
        "permissions":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/WorkbookSharePermissionFlags"
                },
                {
                    "description":"Workbook share permissions for the account. This property can be omitted when updateMode is DeleteMatchingAccounts."
                }
            ]
        }
    },
    "required":[
        "accountGuid",
        "accountType"
    ]
}

Nested Schema : accountType

Match All

User or ApplicationRole.

Show Source

string

Allowed Values: [ "User", "ApplicationRole" ]
User or ApplicationRole.

{
    "allOf":[
        {
            "$ref":"#/components/schemas/AccountType"
        },
        {
            "description":"User or ApplicationRole."
        }
    ]
}

Nested Schema : permissions

Match All

Workbook share permissions for the account. This property can be omitted when updateMode is DeleteMatchingAccounts.

Show Source

object WorkbookSharePermissionFlags
Workbook share permissions for the account. This property can be omitted when updateMode is DeleteMatchingAccounts.

{
    "allOf":[
        {
            "$ref":"#/components/schemas/WorkbookSharePermissionFlags"
        },
        {
            "description":"Workbook share permissions for the account. This property can be omitted when updateMode is DeleteMatchingAccounts."
        }
    ]
}

Nested Schema : WorkbookSharePermissionFlags

Type: object

Show Source

edit(required): boolean

Whether the account can edit the workbook.
view(required): boolean

Whether the account can view the workbook.

{
    "type":"object",
    "properties":{
        "view":{
            "type":"boolean",
            "description":"Whether the account can view the workbook."
        },
        "edit":{
            "type":"boolean",
            "description":"Whether the account can edit the workbook."
        }
    },
    "required":[
        "view",
        "edit"
    ]
}

Response

Supported Media Types

application/json

200 Response

Successful operation

Root Schema : WorkbookSharePermissions

Type: array

Show Source

Array of: object WorkbookSharePermission

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

Nested Schema : WorkbookSharePermission

Type: object

Show Source

accountDisplayName: string

Read Only: true

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

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

{
    "type":"object",
    "properties":{
        "accountGuid":{
            "type":"string",
            "description":"User ID or application role name."
        },
        "accountType":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/AccountType"
                },
                {
                    "description":"User or ApplicationRole."
                }
            ]
        },
        "accountDisplayName":{
            "type":"string",
            "readOnly":true,
            "description":"Display name for the user or application role, if available."
        },
        "permissions":{
            "allOf":[
                {
                    "$ref":"#/components/schemas/WorkbookSharePermissionFlags"
                },
                {
                    "description":"Workbook share permissions for the account. This property can be omitted when updateMode is DeleteMatchingAccounts."
                }
            ]
        }
    },
    "required":[
        "accountGuid",
        "accountType"
    ]
}

Nested Schema : accountType

Match All

User or ApplicationRole.

Show Source

string

Allowed Values: [ "User", "ApplicationRole" ]
User or ApplicationRole.

{
    "allOf":[
        {
            "$ref":"#/components/schemas/AccountType"
        },
        {
            "description":"User or ApplicationRole."
        }
    ]
}

Nested Schema : permissions

Match All

Workbook share permissions for the account. This property can be omitted when updateMode is DeleteMatchingAccounts.

Show Source

object WorkbookSharePermissionFlags
Workbook share permissions for the account. This property can be omitted when updateMode is DeleteMatchingAccounts.

{
    "allOf":[
        {
            "$ref":"#/components/schemas/WorkbookSharePermissionFlags"
        },
        {
            "description":"Workbook share permissions for the account. This property can be omitted when updateMode is DeleteMatchingAccounts."
        }
    ]
}

Nested Schema : WorkbookSharePermissionFlags

Type: object

Show Source

edit(required): boolean

Whether the account can edit the workbook.
view(required): boolean

Whether the account can view the workbook.

{
    "type":"object",
    "properties":{
        "view":{
            "type":"boolean",
            "description":"Whether the account can view the workbook."
        },
        "edit":{
            "type":"boolean",
            "description":"Whether the account can edit the workbook."
        }
    },
    "required":[
        "view",
        "edit"
    ]
}

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

These examples show how to update share permissions for your workbooks:

Example 1 - Update workbook share permissions for a specific user (or application role)
Example 2 - Replace all existing share permissions for a workbook
Example 3 - Delete workbook share permissions for a specific user (or application role)

Example 1 - Update workbook share permissions for a specific user

In this example, you update share permissions for a workbook with the object ID /shared/Sales/MySalesWorkbook. The Base64URL-safe encoded ID value for this workbook is L3NoYXJlZC9TYWxlcy9NeVNhbGVzV29ya2Jvb2s. You use the ReplaceMatchingAccounts update mode to update the permissions for a specified account (Jane Doe) and preserve existing permissions for accounts not included in the request.

You can get the ID of a workbook by using Get catalog items by type.

cURL Example:

curl -i \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --request POST \
  --data '{
    "updateMode": "ReplaceMatchingAccounts",
    "sharePermissions": [
      {
        "accountGuid": "jane.doe@example.com",
        "accountType": "User",
        "permissions": {
          "view": true,
          "edit": false
        }
      }
    ]
  }' \
  'https://<hostname>/api/20210901/catalog/workbooks/L3NoYXJlZC9TYWxlcy9NeVNhbGVzV29ya2Jvb2s/actions/updateSharePermissions'

Example of Request Body

{
  "updateMode": "ReplaceMatchingAccounts",
  "sharePermissions": [
    {
      "accountGuid": "jane.doe@example.com",
      "accountType": "User",
      "permissions": {
        "view": true,
        "edit": false
      }
    }
  ]
}

Example of Response Body

[
  {
    "accountGuid": "jane.doe@example.com",
    "accountType": "User",
    "accountDisplayName": "Jane Doe",
    "permissions": {
      "view": true,
      "edit": false
    }
  }
]

Example 2 - Replace all existing share permissions for a workbook

In this example, you use the ReplaceAll update mode to remove all existing share permissions for a workbook with the object ID /shared/Sales/MySalesWorkbook. The Base64URL-safe encoded ID value for this workbook is L3NoYXJlZC9TYWxlcy9NeVNhbGVzV29ya2Jvb2s. You specify the new permissions in the same request, for example you give the user Jane Doe view-only access and users with the Sales application role view and edit access.

You can get the ID of a workbook by using Get catalog items by type.

cURL Example:

curl -i \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --request POST \
  --data '{
    "updateMode": "ReplaceAll",
    "sharePermissions": [
      {
        "accountGuid": "jane.doe@example.com",
        "accountType": "User",
        "permissions": {
          "view": true,
          "edit": false
        }
      },
      {
        "accountGuid": "Sales",
        "accountType": "ApplicationRole",
        "permissions": {
          "view": true,
          "edit": true
        }
      }
    ]
  }' \
  'https://<hostname>/api/20210901/catalog/workbooks/L3NoYXJlZC9TYWxlcy9NeVNhbGVzV29ya2Jvb2s/actions/updateSharePermissions'

Example of Request Body

{
  "updateMode": "ReplaceAll",
  "sharePermissions": [
    {
      "accountGuid": "jane.doe@example.com",
      "accountType": "User",
      "permissions": {
        "view": true,
        "edit": false
      }
    },
    {
      "accountGuid": "Sales",
      "accountType": "ApplicationRole",
      "permissions": {
        "view": true,
        "edit": true
      }
    }
  ]
}

Example of Response Body

[
  {
    "accountGuid": "jane.doe@example.com",
    "accountType": "User",
    "accountDisplayName": "Jane Doe",
    "permissions": {
      "view": true,
      "edit": false
    }
  },
  {
    "accountGuid": "Sales",
    "accountType": "ApplicationRole",
    "accountDisplayName": "Sales",
    "permissions": {
      "view": true,
      "edit": true
    }
  }
]

Example 3 - Delete workbook share permissions for a specific user or application role

In this example, you use the DeleteMatchingAccounts update mode to remove the share permissions for a specific user (Jane Doe) and application role (Sales). With DeleteMatchingAccounts, you omit the permissions property.

cURL Example:

curl -i \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --request POST \
  --data '{
    "updateMode": "DeleteMatchingAccounts",
    "sharePermissions": [
      {
        "accountGuid": "jane.doe",
        "accountType": "User"
      },
      {
        "accountGuid": "Sales",
        "accountType": "ApplicationRole"
      }
    ]
  }' \
  'https://<hostname>/api/20210901/catalog/workbooks/L3NoYXJlZC9TYWxlcy9NeVNhbGVzV29ya2Jvb2s/actions/updateSharePermissions'

Example of Request Body

{
  "updateMode": "DeleteMatchingAccounts",
  "sharePermissions": [
    {
      "accountGuid": "jane.doe",
      "accountType": "User"
    },
    {
      "accountGuid": "Sales",
      "accountType": "ApplicationRole"
    }
  ]
}

Example of Response Body

If these are the workbook’s only share permissions, the response is an empty array:

[]