1. BitTitan Help Center
  2. Getting Started with BitTitan
  3. Products & Tools
  4. MSPComplete
  5. Runbooks

Automation Building Blocks

Following are common automation scenarios that are building blocks to help you build up your automation scripts.

Using the Script Init.ps1

The script named Init.ps1 emulates the MSPComplete context variable $mspc when the automation script executes directly from the PowerShell console. This is useful when testing scripts under development.

For example, suppose the following script is executed from the PowerShell console running on a local machine:

.\Init.ps1 -Customer
$InformationPreference = 'Continue'
Write-Information "Executing script for customer $($mspc.Customer.CompanyName)."

 The first time the script executes, Init.ps1 requests the following information from the user:

  • BitTitan credentials
  • Workgroup ID
  • Customer ID

Following is the corresponding output in the PowerShell console:

Initializing BitTitan Automated Task Environment

DEBUG: Customer: True.

Workgroup ID: <Workgroup ID>

Customer ID: <Customer ID>

Executing script for customer <customer name>.

 

The next time the script executes, it reuses the credentials and MSPComplete context, which it has written back to the platform data store.

Initializing BitTitan Automated Task Environment

DEBUG: Customer: True.

Executing script for customer <customer name>.

 

If you need to test the script using different credentials, or using a different workgroup or customer, you can invoke Init.ps1 using the -Clear switch so the script resets the saved context data.

.\Init.ps1 -Clear

 

Accessing the MSPComplete Context

You can retrieve MSPComplete context data by calling properties of the $mspc variable. Following are some examples:

  • $mspc.Ticket returns the BitTitan ticket for the agent who launched the service.
  • $mspc.Agent returns the SystemUser structure for the agent who launched the service.
  • $mspc.Agent.EmailAddress returns the email address of the agent.
  • $mspc.Customer returns the customer entity associated with the service that is running.

 

Get Data from Input Tasks

You can access a Runbook’s input tasks using script parameters. The script author must declare script parameters that match variable names specified for corresponding input tasks.

For example, if a Runbook has the following structure:

  • Task #1: Input task
    • Type: select end-users
    • Variable name: inputUsers
  • Task #2: Input task
    • Type: input string
    • Variable name: message
  • Task #3: Automated task

The script inside task #3 would then have the following structure

# Example of working with input tasks
param ($inputUsers, $accountName)
.\Init.ps1

# Parameters $inputUsers and $accountName can be used in the rest
# of the script to access inputs provided by MSPComplete agents
Write-Information "Processing end-user for account $accountName."
foreach ($user in $inputUsers) {
    Write-Information "Processing end-user $($user.PrimaryEmailAddress)"

Note: For more information about adding input tasks, see Edit Input Collections Tasks.

 

Pass Data Between Multiple Tasks in the Same Runbook

It is sometimes necessary to for one task to pass information to subsequent tasks. This is done using the MSPComplete platform data store to retain service context. Consider, for example, the following Runbook:

  • Task #1: Input Task
    • Type: enter string value
    • Variable name: userEmailAddress
  • Task #2: Automated Task
    • Create a new record
    • Store the ID of the new record in the service context
  • Task #3: Automated Task
    • Retrieve from service context the ID of the record created in Task #2
    • Use the record ID to retrieve the record.

The service context variable $mspc contains special hashtable data that is defined specifically for this purpose. The script for task #2 can use this syntax to store session data, as illustrated in the following snippet:

# Code that generates some data that needs to be passed to the next automated task
$myData = (New-Guid).Guid  # This is just an example
 
# Store the data
# Below 'MyRecordId' is an example of a key you can use to retrieve this data later

$mspc.Data.MyRecordId = $myData

 

Then, the code for Task #3 is able to retrieve the value of '$dataToBePassed' as follows:

# Retrieve data stored by prior task

$myData = $mspc.Data.MyRecordId
Write-Information "Data passed between multiple tasks: '$myData'."

 

Using the BitTitan PowerShell Module

Simple usage

Using the BitTitan PowerShell module inside automated tasks is straightforward. Two important requirements are provided initially:

  • The latest version of the PowerShell module is preloaded automatically.
  • Authentication tickets are provided as part of the $mspc context variable.

Following is an example of a basic implementation of the PowerShell module in an automated task:

.\Init.ps1 -Customer
 
$InformationPreference = 'Continue'
Write-Information "Executing script for customer
    $($mspc.Customer.CompanyName)."
 
$endUsers = Get-BT_CustomerEndUser -Ticket $mspc.CustomerTicket
$endUsers | foreach {
    Write-Information "End user:
        email=$($_.PrimaryEmailAddress) identity=$($_.PrimaryIdentity)"
}

This script retrieves a list of all of a customer's users. The customer is the one passed into the $mspc context. The script then prints the primary email address and identity for each user.

The example code produces the following output:

Executing script for customer 'Test Customer'.

End user: email=user1@sample.com identity=user1@sample.com

End user: email=johndoe@sample.comp identity=John.Doe

 

Using extended properties

MSPComplete allows agents to set their own ad hoc properties platform entities. Custom properties are included automatically when records are retrieved using the BitTitan PowerShell module.

The following is an example of code that shows a Customer record (CustomerEndUser) with a default property set (PrimaryEmailAddress). The code then shows two custom extended properties (“Hobby” and “Location”) that were created in the MSPComplete UI for the Customer record.

param ($endUserEmail)
.\Init.ps1 -Customer
 
$InformationPreference = 'Continue'
Write-Information "Executing script for customer
    '$($mspc.Customer.CompanyName)'."
 
# Get one user with specified email address
$endUser = Get-BT_CustomerEndUser -Ticket $mspc.CustomerTicket
    -PrimaryEmailAddress $endUserEmail -PageSize 1
Write-Information "End user: email=$($endUser.PrimaryEmailAddress)
    identity=$($endUser.PrimaryIdentity)"
 
# Show specific extended properties
Write-Information "Hobby: $($endUser.ExtendedProperties.Hobby)"
 
# Print values of all extended properties
Write-Information "Customer End-User $($endUser.PrimaryEmailAddress)
    has properties:"
$endUser.ExtendedProperties.Keys | foreach {
    Write-Information "  '$_' =
    '$($endUser.ExtendedProperties[$_])'"
}

The script example illustrates how to retrieve extended properties on an entity. 

Output from the automated task illustrated in the code sample above displays the same custom properties as were entered when the task executed:

Executing script for customer John Doe.

End user: email=johndoe@bittitan.com identity=John.Doe

Hobby: Bicycle

Customer End-User johndoe@bittitan.com has properties:

  'Hobby' = 'Bicycle'

     'Location' = 'Sammamish'

 

Installing PowerShell Modules from the Gallery

You can install PowerShell modules from the PowerShell Gallery programmatically in either of two ways:

  • Install and load a custom PowerShell module from the gallery:
Install-Module newtonsoft.json -Scope CurrentUser
Import-Module newtonsoft.json
  • Use a cmdlet from the installed module:
$serializedData = ConvertTo-JsonNewtonsoft @(1, 2, "hello!", 42)

 

Logging

You can use standard write- commands to output logging and debugging information. The output generated by write- commands is intercepted and persisted while the automated task is executing, and is displayed in the MPSComplete web UI.

Following are examples of outputs returned from common write- commands:

Write-Host "Executing script on $(get-date)."
    Output: Executing script on 09/22/2017 08:13:19

Write-Information "More scripting on $(get-date)."
    Output: More scripting on 09/22/2017 08:13:19

Write-Debug "Debugging script in $($(get-date).Year)."
    Output: Debugging script in 2017

Write-Verbose "Verbose output: $($(get-date).Year)."
    Output: Verbose output: 2017

 

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

Articles in this section

See more