Writing and Using Automation Scripts

Script Context & Persistence

The illustration below provides a conceptual picture of how the MSPComplete platform interacts with automation scripts. Script context data is persisted along with authentication tickets and platform entities, and log entries, in the MSPComplete platform data store.

When automation scripts execute, the BitTitan scripting host enables interaction with MSPComplete and allows you to store and retrieve data. Interaction between the platform and scripting host is bidirectional, as shown in the illustration below.

  • The scripting host retrieves context data from the platform data store by using the MSPComplete context variable, $mspc.
  • It retrieves information or selections made by an agent in a previous input tasks.
  • It can pass arbitrary data from one task to another (within the same Service instance).
  • It can generate log entries and other information that is persisted and made available to MSPComplete agents.
  • It can use the BitTitan PowerShell module to interact with MSPComplete and MigrationWiz entities.

    Note: Read the How do I install the BitTitan SDK? article for more information about installing BitTitan PowerShell.

 

ngScriptContext.png

 

Automation Script Structure

Your automation scripts should follow a prescribed structure. This improves readability, enables maintenance, and supports testing scripts from a standard PowerShell console. Following are some guidelines:

  • Always comment your code, particularly to document the purpose of the automated task.
  • While optional, you should provide a parameter declaration block. You can see an example of this in the section below entitled “Get Data from Input Tasks” in the article Automation Building Blocks.
  • Make a call to the initialization script Init.ps1, which is available as part of the BitTitan PowerShell module. You can call the initialization script while automated tasks are executing. Calls to Init.ps1 also allow you to emulate script execution by running the script in a local PowerShell console.

Note: The script named Init.ps1 emulates the MSPComplete context variable $mspc when automation script executes directly from the PowerShell console.

 

Example automation script with no input tasks

Without input tasks, and therefore no input parameters, the script does not need an authorization ticket scoped to a Customer, so calling the script is simple:

.\Init.ps1
     

Example automation script with an input task

Scripts that reference data that was collected previously requires passing values using parameters. The following example uses a customer-scoped ticket associated with the parameter $selectUsers:

param ($selectUsers)
.\Init.ps1 -Customer
    

The Context Variable $mspc

The PowerShell module exposes a context variable, $mpsc, whose extensions provide access to entities in the MSPComplete platform. The table below summarizes properties that are exposed using the context variable $mpsc. In the “Supported Scenario” section, we provide code snippets that illustrate using these properties.

The following lists the available $mspc context variables, along with type declaration and descriptions:

Property

Type

Description

Ticket

ManagementProxy.ManagementService.Ticket

A BitTitan authentication ticket scoped to the agent (system user) who launched the service.

See 'help Get-BT_Ticket' for more details. A BitTitan ticket is for use with BitTitan cmdlets.

CustomerTicket

ManagementProxy.ManagementService.Ticket

A BitTitan authentication ticket scoped to the agent (system user) who launched the service and futher to the Customer record that the service is associated to.

See 'help Get-BT_Ticket' for more details.

WorkgroupTicket

ManagementProxy.ManagementService.Ticket

A BitTitan authentication ticket scoped to the agent (system user) who launched the service and futher to the Workgroup record that the service belongs to.

See 'help Get-BT_Ticket' for more details.

Agent

ManagementProxy.ManagementService.SystemUser

An object of type SystemUser (ManagementProxy.ManagementService.SystemUser) that represents BitTitan agent that launched the service. Note that this system user may be different from the user that the automated task is assigned to.

Customer

ManagementProxy.ManagementService.Customer

An object of type Customer (ManagementProxy.ManagementService.Customer) that represents a customer that the service is associated with.

Workgroup

ManagementProxy.ManagementService.Workgroup

An object of type Workgroup (ManagementProxy.ManagementService.Workgroup) that represents a workgroup associated with the service.

MigrationWizTicket

MigrationProxy.WebApi.Ticket

Authentication ticket that can be used to work with a MigrationWiz PowerShell command. The ticket corresponds to the same agent (system user) as $mpsc.Ticket.

Data

System.Collections.Hashtable

A hashtable that will be passed between multiple automated tasks in the same service instance. See About Hashtables for more information.

 

Naming variables

While the global variable $mspc is prepended with a dollar sign ($), PowerShell variables that you create should not have the dollar sign. However, when you reference your variables in PowerShell script, you should prepend those variable names with the dollar sign, since user-defined variables are passed as parameters.

 

Was this article helpful?
0 out of 0 found this helpful