Import Cell-Level Security
This REST API imports cell-level security settings from a ZIP file that contains an Excel file with cell-level security definitions into Planning or Tax Reporting business processes. Cell-level security enables Service Administrators to restrict who can view data in the application by defining rules that remove read or write access to cells that a user would normally have access to due to their regular security.
The file must be present in the Inbox. You can use the Upload REST API to upload the file. Any rejected records are generated in an Excel file that is zipped and copied to the Outbox.
The best method to get the import file format template is to export cell-level security from the application.
The following is a general explanation of the Excel file. The file contains two Excel worksheets:
Rules
- contains cell-level security definitions, dimensions included, properties such as Unspecified Valid, and Additional Dims RequiredSub Rules
- contains member selections and exclusions
The Rules
worksheet has the following column headings:
- Name
- Position
- Description
- Enabled
- Valid Cubes - This column can contain either
All
or a list of comma-separate names of cubes, such asPlan1, Plan2
- Anchor Dim Name
- Anchor Dimension Apply to Unselected Members
- Dim1
- Dim1 Required
- Dim2
- Dim2 Required
- DimX
- DimX Required
The Sub Rules
worksheet has the following column headings:
- Name - This column must contain the name of the Rules from the first worksheet
- Users
- User Groups
- Restriction - This column can contain
Deny Read
orDeny Write
- Anchor Members
- Anchor Exclusion
- Dim1 Members
- Dim1 Exclusion
- Dim2 Members
- Dim2 Exclusion
- DimX Members
- DimX Exclusion
Required Roles
Service Administrator
Using this REST API requires prerequisites, such as understanding how to use jobs. See Prerequisites. Be sure that you understand how to use jobs as described in Managing Jobs.
REST Resource
POST /HyperionPlanning/rest/{api_version}/applications/{application}/jobs
Request
Supported Media Types: application/json
Parameters
The following table summarizes the client request parameters specific to this job. For parameters that are common to all jobs, see Execute a Job.
Table 8-31 Import Cell-Level Security
Name | Description | Required | Default |
---|---|---|---|
jobType |
Import Cell-Level Security or IMPORT_CELL_LEVEL_SECURITY |
Yes | None |
jobName |
The name of the job to be used. This job name appears on the job console. Example: |
No | Import Cell-Level Security Definitions |
fileName |
The name of the ZIP file containing the input Excel file. The file must be present in the Inbox. Before using this REST API, you can use the Upload REST API to upload the file. |
Yes | None |
errorFile |
Optionally, create a separate error file for recording any errors that occur during the import process. If this is not specified, an error file is auto-generated with a name containing the user name, current date, and time stamp. For example, admin_ImportError_2020- 02-26-04-34-45-420.txt .
The file containing the error messages is stored in the Outbox. You can download it using the Download API. This API overrides any existing error file with the same name. |
No | The file is auto-generated |
For a sample URL, see the sample URL and payload in Execute a Job
Example 1: Imports cell-level security records from the input file ImportCLSRecordsFile.zip
.
{
"jobType": "Import Cell-Level Security",
"jobName": "ImportCLSJob",
"parameters": {
"fileName": "ImportCLSRecordsFile.zip"
}
}
Example 2: Imports cell-level security records from the input file ImportCLSRecordsFile.zip
and exports the error messages to the file ImportCLSFileLog.txt
.
{
"jobType": "Import Cell-Level Security",
"jobName": "ImportCLSJob",
"parameters": {
"fileName": "ImportCLSRecordsFile.zip",
"errorFile": "ImportCLSRecordsFileLog.txt"
}
}