TABLE OF CONTENTS
- Introduction
- Prerequisites
- Validate the PowerShell Version
- Set the PowerShell Execution Policy
- Downloading the API
- Preparing the API
- Testing the Connection
- Example Commands
- Further Support
Introduction
The API allows the development of code to run against the ManagementStudio platform. This could take the form of external scripts running on disparate systems or code that runs within ManagementStudio to create new custom functions or events.
Prerequisites
- PowerShell 7.3.x (not 7.4 or 7.5)
- Download link
- Install with the default options
- Visual Studio Code (PowerShell ISE does not work)
- Download Link
- Install with the default options
- Access to the API reference documentation: https://docs.managementstudio.cloud/
Validate the PowerShell Version
- Open Visual Studio Code
- To turn on the Terminal panel (if not showing) click View -> Terminal
- In the Terminal panel at the bottom of the window type $PSVersionTable and press <Enter>
- The version displayed should be 7.3.x
- Close Visual Studio Code
Set the PowerShell Execution Policy
- Click the Windows button
- Type pwsh
- Right-click PowerShell 7 (x64) -> Run as administrator
- Type Set-ExecutionPolicy Unrestricted and press <Enter>
- Close the PowerShell window
Downloading the API
- In a web browser navigate to the address of your ManagementStudio instance, for example: http://ManagementStudio.local/
- Click the button Looking for the ManagementStudio SDK?
- Enter a ManagementStudio username and password at this point, then click Log in
- Once authenticated it will display the same page again and at this point click "Looking for the ManagementStudio SDK?" once again
- Click Download ManagementStudio PowerShell SDK
- It is essential to follow the instructions on the screen as later versions may contain different information from this document
- The ManagementStudio API is delivered as a zip file, it is essential that the zip be 'Unblocked' before it is unzipped. Otherwise, Windows will block the PowerShell module files inside the zip and API calls will fail. Instructions are provided further down the page:
- In Windows Explorer, right-click on the downloaded file and select Properties
- In the General tab, tick the Unblock checkbox at the bottom and click Apply
- If updating an existing setup then you must delete the existing 'ManagementStudioApi' folder that was created from the previous install and replace it with this one
Preparing the API
- Extract the zip file to a new folder, e.g. C:\ManagementStudioAPI
- Create a new directory in C:\ManagementStudioAPI specifically for log files, e.g. C:\ManagementStudio\API\Logs
- Navigate to C:\ManagementStudioAPI\Dev\Examples\
- Duplicate the file API_Start_Here.ps1 and rename the copy to API_Baseline.ps1. This protects the original file and any related API files.
- Right-click the API_Baseline.ps1 file and Open With -> Visual Studio Code
- If you are prompted to install the PowerShell Extension, click Install and follow the instructions to install the extension
- The script needs to be configured for the target environment. Look for the area tagged # REQUIRED: Script will not run without these settings, which starts on line 23 in this example:
- Populate the values below in the script. These values are used to create an object called $ScriptArgs.
| Variable | Example | Purpose |
|---|---|---|
| AutomationFolder | C:\inetpub\ManagementStudio\wwwroot\ Automation\ManagementStudioApi | The path to the folder containing the ManagementStudio API |
| LogsFolder | C:\ManagementStudioAPI\Logs | The path where the log files should be written |
| ApiUrl | http://ManagementStudio.Local | The URL to the ManagementStudio environment |
| UserName | JSmith | The account that will run the script. The account should be in the API Role Group in ManagementStudio. |
| Password | JSmithPassword | The password for the username, above. |
| ProjectId | 1 | Specify the ManagementStudio Project that will be used by the script. The default is 1. |
| Module | Devices | The module that the script targets. |
| ScriptName | MyScriptName | The name that will be used when creating log files. |
- Save the file by pressing CTRL + S
Testing the Connection
- Test the connection to ManagementStudio by clicking the Run button or by pressing F5 on the keyboard
- If this window below appears, click Trust Workspace and Continue
- If the connection is successful the output should show:
Example Commands
To run a single command, enter it into the Terminal panel and press <Enter>
Examples:
- $ScriptArgs.Module will show which module the script is running against
- $ScriptArgs.UserName will show the user account the script is running as
- Get-MSModuleItems -Module $scriptArgs.Module -All -IdsOnly will list the IDs of all the records in the module
These variables can be used in the scripts, for example here we use $scriptArgs.Module to use the module which was set in the script to return all the Devices:
Get-MSModuleItems -Module $scriptArgs.Module -All
To get a list of the applications with IDs 2000, 2001 and 2002:
Get-MSModuleItems -Module 'Applications' -Ids 2000, 2001, 2002
To get a list of the applications matching the search 'chrome':
Get-MSApplications -All -SearchTerm 'chrome'
For more advanced options the Data Mining Report can be called:
If a multi-line script needs testing. enter this as shown below, then select the script and press F8. The output will be shown in the Terminal panel.
Example of a two line script:
$chromeapps = Get-MSApplications -All -SearchTerm 'chrome' $chromeapps.title
Further Support
If you require further support, please visit ManagementStudio's Service Desk to search the knowledge base or create a new support ticket.