Getting Started With The API and PowerShell

Modified on Tue, 21 May 2024 at 11:23 AM

TABLE OF CONTENTS


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


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
VariableExamplePurpose
AutomationFolderC:\inetpub\ManagementStudio\wwwroot\
Automation\ManagementStudioApi
The path to the folder containing the ManagementStudio API
LogsFolderC:\ManagementStudioAPI\LogsThe path where the log files should be written
ApiUrlhttp://ManagementStudio.LocalThe URL to the ManagementStudio environment
UserNameJSmithThe account that will run the script. The account should be in the API Role Group in ManagementStudio.
PasswordJSmithPasswordThe password for the username, above.
ProjectId1Specify the ManagementStudio Project that will be used by the script. The default is 1.
ModuleDevicesThe module that the script targets.
ScriptNameMyScriptNameThe 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: 

https://support.managementstudio.com/support/solutions/articles/14000122898-creating-a-basic-report-using-the-api#Create-a-Simple-User-Migration-Report


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.