Getting Started With The API

Modified on Tue, 06 Jun 2023 at 12:14 PM

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\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.
  • 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
VariableExamplePurpose
AutomationFolderC:\inetpub\ManagementStudio\wwwroot\AutomationThe 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.


  • 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:

If the script runs successfully the output should show:

ResultContent
-------------
[time] ...                                                                          


If you see the error API_Start_Here.ps1 cannot be loaded because running scripts is disabled on this system the PowerShell Execution Policy may need modifying:

  • Open PowerShell ISE as Administrator
  • Run the command Set-ExecutionPolicy Unrestricted
  • Click Yes to All
  • Close the PowerShell ISE window


In the original PowerShell ISE window commands can be run in the lower pane to query the API. 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. i.e. Return the three machine objects defined in items.


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

            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.





Further Support

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