| Altus Docs

Controlling visibility of a button based on a configuration setting

This is achievable using a built in javascript function in the sensei_SenseiProject.bundle.js.

sensei_SenseiProject.Generic.ConfigUtils.userHasSecurityRoleInConfig (

    // “Configuration Setting Name” the is what is expected to be configured inside the environments configuration settings
    configSettingName: string,

    // “Path” – this should be path separated by “/” between elements within the above “Configuration Setting Name”
    jsonPath: string,

    // “Label” – this should be the name of the array that contains a list of User defined root roles
    jsonLabel: string,

    // “Key” – this should be the key value within an array which contains a list of User defined root roles
    jsonKey: string,

    // “Default roles” – If there is no configuration setting present and active in the environment then these comma separated root roles will be able to see the configured buttons
    defaultValue: string

): Promise<boolean>

Below are some example uses of the function. Each example makes use of different parameters

Example use case - Show specific button based on user having security role/s in config

In order to conditionally show the "New" button if a user has permission to do so using a "configuration setting" to add new timesheets the following demonstration will illustrate how to configure ribbon workbench using XrmToolbox.

Install XrmToolbox
Open XrmToolbox
Create Connection to environment
1. In the bottom left corner create a new connection
  1. Click "Not connected"
  2. Click "Create new connection"
2. Make a new connection via the following:
3. Open the Login dialog box
4. Login to an "Office 365" tenant
  1. Select "Office 365"
  2. Toggle "Display list of available organizations"
  3. "Login"
5. Complete standard login and password with a minimum of system Customizer role to allow for editing of the ribbon.
6. Set the name it should be saved as:
  1. Recommend saving it under the tenant name
  2. Select finish to create connection
Now we need to connect to this created environment
1. Click "Not connected" in the bottom left corner
2. Expand "CM836721" in my example
3. Click "Connect"
Opening "Ribbon Workbench"
1. Click on "Tools"
2. Click in search box area, Search for "Ribbon Workbench"
3. Click on "Ribbon Workbench"
Using Ribbon Workbench to customize the environment
1. Ribbon workbench allows for customization of upto 5 entities at one time. This is done by the following steps
  1. Create new solution or edit an existing solution with 5 or less entities in dynamics
  2. Add Existing entities you wish to customize by adding references only as shown below
    1. Click Entities in left hand side
    2. Click the "Add Existing" button
  3. Select solution components:
    1. Select the Entity you wish to customize. ie. Timesheet in our case
    2. Click "OK" to confirm
  4. Select Entity Assets to Include in the Solution:
    1. We want to uncheck "Include entity metadata"
    2. We want to select the "Main" form
    3. Click "Finish" to add it to the solution
2. Select the solution which you wish to customize
  1. In this case we are using "RibbonWorkbench" solution
  2. Click on "OK" to load solution
Now we need to customize the command associated with the buttons within Ribbon Workbench
1. Select from the drop down menu “sensei_timesheet”
2. Left click on “+New” in the ribbon
3. You should see that the “Mscrm.HomepageGrid.sensei_timesheet.NewRecord” the key part is the “NewRecord” as there are two different ones under the “HomeGrid”
4. Now Right click on that new button
5. Select “Customize Command” this will populate the existing configuration for that button.
Repeat the above step 6 but for “SubGrid” and “Form”
1. Confirm its correct button and customizing it
  1. Left click “New {0}” and confirm that it ends with “NewRecord” at arrow 3
  2. Right click the “New {0}” and Customize button
2. Confirm its correct button and customizing it
  1. Left click “+New” and confirm that it ends with “NewRecord” at arrow 3
  2. Right click the “+New” button and Customize command
3. This value will change depending on which of the buttons selected. Ie HomepageGrid, SubGrid, Form
4. Look to see under “Enable Rules” – “sensei.sensei_timesheet.UserHasSecurityRoleInConfig.EnableRule” a. Click on this to edit the rules configuration in the next step – modifying this one value will adjust it for all three buttons as they all reference this “Enable Rule”
Now we are going to go through how to customize the “Enable Rule”
1. Left Click – sensei.sensei_timesheet.UserHasSecurityRoleInConfig.EnableRule
2. Based on the settings you want to test adjust the following. “InvertResult” should be True or False(blank)
3. “Configuration Setting Name” the is what is expected to be configured inside the environments configuration settings
4. “Path” – this should be path separated by “/” between elements within the above “Configuration Setting Name”
5. “Label” – this should be the name of the array that contains a list of User defined root roles
6. “Key” – this should be the key value within an array which contains a list of User defined root roles
7. “Default roles” – If there is no configuration setting present and active in the environment then these comma separated root roles will be able to see the configured buttons
For this example the following are values are used

Ribbon Workbench settings
```
{
    "InvertResult": "False(blank)",
    "Configuration Setting Name": "timesheetConfiguration",
    "Path": "",
    "Label": "timesheetAddNewButtonRoles",
    "Key": "",
    "Default roles": "4c0f0c74-8b09-ea11-a811-000d3a530fe5"
}
```
Now once these are configured we need to publish the settings to the environment ~2-5 minutes at a time. It also is know to throw errors even though it has worked.
1. Select “Publish” to apply the changes
  Confirm dialog about making sure you back up your solution
For the given configuration described above in part 9 we require a configuration setting called timesheetConfiguration it can be configured by using the following JSON Schema and UI Schema. The JSON Schema is the actual configuration, UI Schema configures the entity lookup to allow for easy search for roles.

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "title": "",
  "properties": {
    "timesheetAddNewButtonRoles": {
      "$id": "#root/items/timesheetAddNewButtonRoles",
      "title": "Security Roles that can see the New Timesheet button",
      "description": "Note: Ensure all roles who require this access are added here. When no roles are provided, the default role/s configured will have access.",
      "type": "array",
      "default": [
        "4c0f0c74-8b09-ea11-a811-000d3a530fe5"
      ],
      "items": {
        "$id": "#root/items/timesheetAddNewButtonRoles/items",
        "title": "Security Role Id",
        "description": "The role id as specified in Dynamics.",
        "type": "string",
        "default": "",
        "pattern": "^.*$"
      }
    }
  }
}

UI Schema

{
  "timesheetAddNewButtonRoles": {
    "ui:widget": "EntityLookupArrayWidget",
    "ui:options": {
      "endPoint": "roles",
      "valueField": "_parentrootroleid_value",
      "nameField": "name"
    }
  }
}

Example where path value is used

Ribbon Workbench settings

{
    "InvertResult": "False(blank)",
    "Configuration Setting Name": "simpleRoot",
    "Path": "level/permissions",
    "Label": "securityRoleIds",
    "Key": "",
    "Default roles": "4c0f0c74-8b09-ea11-a811-000d3a530fe5"
}