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 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:

  1. Rules - contains cell-level security definitions, dimensions included, properties such as Unspecified Valid, and Additional Dims Required
  2. 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
  • Dim X
  • Dim X 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
  • Dim X Members
  • Dim X Exclusion

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 5-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, identify the name of a text 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 REST API.

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"
    }
}