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.


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 ManagementStudio Api 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\wwwroot\Automation\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.
  • Open API_Baseline.ps1 in a PowerShell editor. This example uses Windows PowerShell ISE.
  • The file 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:


  • The values are used to create an object called $ScriptArgs
Variable
Example
Purpose
AutomationFolder
C:\inetpub\ManagementStudio\wwwroot\Automation
The path to the folder containing the ManagementStudio API
LogsFolder
C:\ManagementStudioAPI\Logs
The path where the log files should be written
ApiUrl
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.


  • If you're not running PowerShell v7 or greater, comment out line 80 by adding the hash # symbol to the start of the line:


  • Save the file.



To determine the version of PowerShell, type $PSVersionTable into a PowerShell prompt and note the value of PSVersion:



The script is now ready to use. Test the connection to ManagementStudio by clicking the Run Script button in Windows PowerShell ISE or by pressing F5 on the keyboard:


Values can be recovered by calling $ScriptArgs.VariableName  i.e.

    $ScriptArgs.Module will return 'Devices' 

    $ScriptArgs.UserName will return 'DaveSmith'


These variables can be used in the scripts. i.e. Return the three machine objects defined in items.


            Get-MSModuleItems -Module $ScriptArgs.module -Ids $ScriptArgs.Items

            Get-MSModuleItems -Module $scriptArgs.Module -All






Further Support

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