Introduction

User-defined buttons are used to provide custom functionality to the main grid view of the Applications, Users, Devices, Deployment Unit, and Bespoke modules through the use of Powershell Scripting and the ManagementStudio  API. The User-defined buttons are accessed using the right-click context menu when hovering over these main grid views. These buttons can be used to send emails, run scripts, and run actions. The buttons support sub-buttons to create granular and easy-to-use menus.

TABLE OF CONTENTS

• Introduction
  • Button Types
  • Script Buttons
    • User Input
  • ESM Plan Buttons
  • UI Buttons Grid Columns
• Further Support

Example - Custom Buttons added to Grid Context Menu

Button Types

• Script Buttons - Pass the selected Grid Items (Apps, Users, etc) to a PowerShell script for processing
• ESM Plan Buttons - Pass the selected Grid Items (Apps, Users, etc) to n ESM Plan for processing 
• Send Email Buttons - Send an Email to the selected Grid Items (Apps, Users, etc)  
• Action Buttons - Run a build in action on the selected Grid Items (Apps, Users, etc)

Note the top-level button that appears directly on the context menu can not perform any actions, it must have a sub-button under it to do the work

Note it is not possible to have button that perform multiple types of actions, e.g. a Button that Runs PowerShell, Calls and ESM Plan and Sends an Email. only one action type is allowed per button. 

Script Buttons

Script Buttons target PowerShell scripts registered in the PowerShell area of the Admin section. 

User Input

When creating buttons that call Scripts, it is possible to ask the user for some input that can then be passed to the script. For example, asking the User for a Date or selecting an option from a list. Many of the input types have associated control args that allow configuration of the input, such as setting a maximum date or number, or the items in a list.  

ESM Plan Buttons

Pass the selected Grid Items (Apps, Users, etc) to n ESM Plan for processing. To use select the name of the ESM Plan to run from the dropdown in the "Run ESM Plan" column of the Button UI Grid. 

Only ESM Plans for the UI Buttons module will be shown in the dropdown. i.e. When looking at Application Buttons only ESM Plans that target Applications will be shown in the drop-down. 

UI Buttons Grid Columns

The setup grid is broken split into the following sections BUTTON, OPTIONS, and ACTION  with the fields described in detail below:

Column	Description
Button Label	This is the label that will be seen in the right-click context menu. If there are any sub-buttons defined, they will be shown to the side.
Sub-Button	Click on the + icon next to the Button Label to create a Sub Button. These sub-buttons will be nested to the right in the context menu. Note: It is possible to have multiple levels of sub buttons
Is Enabled	if unticked then the Button will not be available in the context menu
Icon	Icon text representing the icon that will be displayed next to the button label in the context menu. The Icons come from Font Awesome Pro selection for example "bullseye-pointer" will show
Grant Access 1 Grant Access 2 Grant Access 3	Select the Role Group that will have access to use this button. A Button must have a role group associated with it to show in the UI. Only users in this role group can see the button. It is possible to have different permissions for different buttons in the same tree. The UI will still only show the User the buttons in the tree that they are allowed to see.
Order	Sort order of the Button or Sub-button
Context Menu	Ticking this will allow access through the context menu. Note: Buttons on the ribbon don't require any rows to be selected on the grid to run, but if there are items selected then these will be passed to the Button's script
Are You Sure	When ticked, a popup will appear asking whether the users wishes to continue running either the script, action or Email send.
UI Wait Complete (Hidden)	Puts the grid into a 'busy' state that waits for the script to finish before the user is allowed to do another action. For scripts that are short is good to wait, the grid will be automatically refreshed when the script is finished. For longer-running scripts like a report that takes fifteen minutes to complete then it's best not to wait. The use will still get a notification popup when the script completes.  Note: Buttons that wait for the UI are assumed to be short and get a new thread to run in. Buttons that don't wait are assumed to be long-running and are added to a queue of scripts to process. As such these no-wait scripts can take an extra-long time to run if there are other scripts in the queue. This is to protect the server from being overloaded.
Limit (Hidden)	The maximum items that can be selected on the grid to pass to the script. 0 = No maximum. For scripts that are long-running or particularly dangerous, it can be useful to limit the number of items it can affect at one time.
Script User Input	Popups up a Textbox, Number Picker, and Date Picker to the User. The result will be sent to the script in the 'UserInput' variable.
User Input Label	The text that appears on the input control that is defined in 'Script User Input'
User Input Control Args	Modifier args are used to set limits and other options on the User Input Control
Running Msg to User (Hidden)	The text that shows in the alert bar at the bottom of the screen when the button is clicked.
Run ESM Plan	Pass the selected Grid Items (Apps, Users, etc) to n ESM Plan for processing
Run Script	Choose which script will be run by clicking this button. These scripts are defined in Administration\PowerShell Scripts Note: Only scripts that target this module will show in the list.
Send Email	Chose which email template will be sent upon clicking this button. These email templates are defined within each of the modules under Administration\[module]\Email Templates
Args 1 (Hidden) Args 2 (Hidden) Args 3 (Hidden)	When ManagementStudio calls a script it passes three arguments to the script. This allows the same script to be used for multiple tasks and control the behavior via the arguments. e.g. A report generator script might be called with different reports at different times of the day.
Delete	Tick this checkbox to delete the User-defined button upon the next save
Id	Internal Id of the User-defined button
Parent Id (Hidden)	If this button is a Sub Button, then the Id of its Parent is identified here. Used in scripting and custom actions to check the hierarchy of buttons.

All options marked Hidden can be found using the column chooser button at the top right of the grid 

Further Support

If you require further support, please visit ManagementStudio's Service Desk to search the knowledge base or create a new support ticket.