Parameterized/Parametric Roles

See also: OpenID user authentication

Parameterized roles are roles that are created on the fly when a user logs in. It can contain properties that are dependant on the user - for example by setting a forced criteria to match the user's name. It only works together with OpenID Connect and the role is created in the login script.

In addition to the normal properties returned in the object from the login script (user_name, user_id, user_groups), you can now add either a roles or a replace_roles property. The only difference is that replace_roles will disable the normal roles in roles.xml, so the only roles active will be the ones returned from the login script. The roles property will just add the returned roles to the ones from roles.xml that matches the user's name or group membership.

The roles/replace_roles is either just a single object or an array of objects describing the roles.

The format of a role in the login scripts is based on the xml format in roles.xml - but expressed in a javascript object:

Role object

  name: "Role name",    // Optional - will be automatically set to "Embedded role #1,2,3..etc" if not set here
  startup_view: "vfs://personal/startup_view.xview",
  system_menu: "vfs://global/",
  forcedcriteria: {
    // For quickly setting forced criteria. These permissions will be merged with any permissions/forced criteria set in the databases property described later (if present)
    "[databaseName].[cubeName].[dimensionName].[hierarchyName]": [
      "[dimensionName].[hierarchyName].[uniqueName1]", // = uniqueName1
        key: "[dimensionName].[hierarchyName].[uniqueName2]", operator: "ne" // <> uniqueName2
  initialcriteria: {
    // For quickly setting initial criteria - same structure as forcedcriteria
  global_favorites: {
    // Objects here define the global favorites. The global_favorites property can be omitted completely if you do not wish to change anything in global favorites. If you add a string, it is assumed to be the vfs url to a file. Otherwise use an object with a name property. To describe a folder, add the children property:
    { name: "TestFolder", children: [
      { name: "vfs://personal/test3.xview" }
    ] }
  databases: { // object with the names of the database connections
    "*": "allow" // * property is if you want to define global permissions for all databases
    testdb1: "<permission>" // If you just want to set permissions and not change anything for children. Allowed values: allow/deny/none
    testdb2: { // Use an object if you want more fine-grained control
      permission: "<permission>",
      inherit: true/false,
      defaultchildpermission: "<default child permission>", // Allowed values: inherit/none/allow/deny
      cubes: {
        cube1: {
          dimensions: {
            dimension1: {
              hierarchies: {
                hierarchy1: { // Setting forced criteria and initial criteria for cube1.dimension1.hierarchy1:
                  forcedcriteria: [
                    "[dimension1].[hierarchy1].[level1].[value1]" // forced equal if just a string, otherwise use an object with key and operator properties:
                    { key: "[dimension1].[hierarchy1].[level1].[value1]", operator: "ne" } // Valid values for operator: eq/ne/lt/le/gt/ge
                  initialcriteria: [] // same format as forcedcriteria
  favorites: { // Similar structure to database if you want to specify vfs://global/ permissions
    folder1: {
      readpermission: "allow", // Instead of just a permission property, here you have readpermission and writepermission
      writepermission: "none",
    folder2: {
      permission: "allow", // You can still use the permission property. Write access is then set to "none"
    folder3: {
      permission: "allow/deny", // By using a forward slash, both read and write permissions can be set from the permission property
      folders: { // !! Remember folders property when describing subfolders
        "subfolder1": "allow"
    folder4: "<readpermission>/<writepermission>" // If you want to set both read and write permissions quickly, you can write the permissions with a forward slash between - e.g. "allow/deny" to allow read but deny write
  exportfolders: { // Permissions for export folders - same structure again as databases/favorites


Almost all properties are optional. The name of the role will have an impact if there are more than one role defining a startup view or system menu. The active roles are sorted according to their names, and the first startup view/system menu the user has access to will be selected. So if you want to be sure that the embedded role will control the startup view/system menu, make sure that the role will be first after sorting by e.g. setting the name of the role to "A"

Example login script with an embedded role:

Login script
function(token) {
    var upnparts = token["upn"].split("@"); // UPN (user principal name): user@domain.tld. After the call to split(), upnparts[0] contains the part before the '@'
    if (upnparts.length == 0) return null; // If no '@' found in the UPN, return null indicating that the user should be denied access
    return {
        user_name: "targit-inet\\" + upnparts[0],
        user_groups: lookup.getGroupsForUser(token["sid"]),
        roles: {
          forcedcriteria: {
            "[DemoData].[Sales].[Period].[YMD]": [
            "[DemoData].[Sales].[Customer].[Customer]": [
              "[Customer].[Customer].&[" + upnparts[0] + "]"


This login script will set a forced criteria in the DemoData connection on the YMD hierarchy of the Period dimension to only show values from 2019. There will also be set a criteria on the Customer dimension so that it will only be a customer with the same name as the user name logging in.

Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.