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 Required
Sub 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 as Plan1, 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 or Deny 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: `ImportCLSPlan1`	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"
    }
}