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, run actions. The buttons support sub-buttons to create granular and easy to use menus.




Setting up User Defined Buttons

User-defined buttons are created in the Administration\[module]UI Buttons section of the Administration screen.



Click on the UI Buttons icon and the User-defined buttons grid will appear:



To add a new Button, click on "Click here to add new item". 


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


BUTTONButton LabelThis 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-ButtonClick 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 Enabledif unticked then the Button will not be available in the context menu

IconIcon 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  

IconPicture of Icon represented by the Icon Text above
OPTIONSGrant 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. 

OrderSort order of the Button or Sub-button

Context MenuTicking 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

Ribbon (Hidden)Show this button in the ribbon toolbar of the main grid.

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.

Ribbon Group (Hidden)

The name of the group in the ribbon toolbar. Buttons with the same ribbon group name will all be added to the same group on the toolbar.



Are You SureWhen 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.

Get User Input (Hidden)Popups up a Textbox, Number Picker, Date Picker to the User. The result will be sent to the script in the 'UserInput' variable.

Running Msg to User (Hidden)The text that shows in the alert bar at the bottom of the screen when the button is clicked.
ACTIONRun ScriptChoose which script will be run on clicking this button. These scripts are defined in Administration\PowerShell Scripts

Note: Only scripts that target this module will show in the list.

Send EmailChose 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.


DeleteTick this checkbox to delete the User-defined button upon next save

IdInternal 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 hierarchy of buttons. 


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