Overview

The BitTitan PowerShell module is a set of PowerShell commands that let you manage your BitTitan data. Examples of operations you can perform with the BitTitan PowerShell module are:

• Creating customers and resources associated with these customers
• Deploying services and monitoring the status of their tasks
• Configuring MigrationWiz projects and users
• Submitting migrations and monitoring migration progress and statistics

The list of all BitTitan cmdlets can be found in the BitTitan cmdlet reference.

The following documentation contain sample scripts that illustrate actions that you can perform using the BitTitan SDK. You will find more sample scripts at the BitTitan internal repository.

Note that some of the sample scripts below use a .\Init.ps1 script, you can also find in the BitTitan internal repository.

System requirements

• Microsoft Windows PowerShell 4.0
• Microsoft.NET Framework 4.6.1

PowerShell module installation

Uninstall previous versions of the PowerShell

Versions that were installed before October 5, 2016 are listed as "MigrationWiz PowerShell" under your program list in the Control Panel. This is because earlier versions were known as "MigrationWiz PowerShell" rather than "BitTitan PowerShell." The current version is "BitTitan PowerShell". If you are using MigrationWiz PowerShell, we recommend you to uninstall it and install BitTitan PowerShell.

Install the SDK

Step 1: Click HERE to download our BitTitan PowerShell module.

Step 2: Run the MSI to install the PowerShell module and associated sample scripts.

Step 3: Import the BitTitanPowershell module containing the cmdlets and associated scripts.

To import the module and make the commands available use the following:

Import-Module 'C:\Program Files (x86)\BitTitan\BitTitan PowerShell\BitTitanPowerShell.dll'

Note: You will have to import the module for each PowerShell session; alternatively, you can modify your PowerShell Profile to include the Import-Module command.

Get the list of BitTitan PowerShell module commands

The BitTitan PowerShell module contains two types of commands: MigrationWiz commands and BitTitan commands. MigrationWiz commands and BitTitan commands use different authentication tickets and you will need to use MigrationWiz tickets with MigrationWiz commands, and BitTitan tickets with BitTitan commands.

MigrationWiz commands use a MW_ prefix, while BitTitan commands use a BT_ prefix.

You can get the full list of BitTitan PowerShell commands by invoking the following cmdlet:

Get-Command -Module BitTitanPowerShell

You will find the following types of commands:

1. MigrationWiz

# MigrationWiz retrieve commands
Get-Command -Module BitTitanPowerShell | Where-Object {$_.Name -like "Get-MW_*"}
# MigrationWiz create commands
Get-Command -Module BitTitanPowerShell | Where-Object {$_.Name -like "Add-MW_*"}
# MigrationWiz update commands
Get-Command -Module BitTitanPowerShell | Where-Object {$_.Name -like "Set-MW_*"}
# MigrationWiz delete commands
Get-Command -Module BitTitanPowerShell | Where-Object {$_.Name -like "Remove-MW_*"}
# MigrationWiz new commands
Get-Command -Module BitTitanPowerShell | Where-Object {$_.Name -like "New-MW_*"}
# Other MigrationWiz commands
Get-Command -Module BitTitanPowerShell | Where-Object {$_.Name -notlike "Get-BT_*" -and $_.Name -notlike "Get-MW_*" -and $_.Name -notlike "Add-BT_*" -and $_.Name -notlike "Add-MW_*" -and $_.Name -notlike "Set-BT_*" -and $_.Name -notlike "Set-MW_*" -and $_.Name -notlike "Remove-BT_*" -and $_.Name -notlike "Remove-MW_*"}

2. BitTitan

# BitTitan retrieve commands
Get-Command -Module BitTitanPowerShell | Where-Object {$_.Name -like "Get-BT_*"}
# BitTitan create commands
Get-Command -Module BitTitanPowerShell | Where-Object {$_.Name -like "Add-BT_*"}
# BitTitan update commands
Get-Command -Module BitTitanPowerShell| Where-Object {$_.Name -like "Set-BT_*"}
# BitTitan delete commands
Get-Command -Module BitTitanPowerShell | Where-Object {$_.Name -like "Remove-BT_*"}
# BitTitan new commands
Get-Command -Module BitTitanPowerShell | Where-Object {$_.Name -like "New-BT_*"}

Overview

Enable authentication by obtaining an authentication ticket. There are several types of authentication tickets:

• BitTitan ticket: You can use a BitTitan ticket with the BitTitan cmdlets (i.e. the cmdlets prefixed with BT_). There are two types of BitTitan tickets:
  • Regular ticket (also called an unscoped ticket): A ticket associated with your BitTitan user account.
  • Ticket scoped to an organization: A ticket bound to your user account and a specified organization.
    • There are two types of organizations: Workgroup organizations or Customer organizations.
    • This section provides more details about Workgroup and Customer organizations.
• MigrationWiz tickets: A ticket that can be used with the MigrationWiz cmdlets (i.e. the cmdlets prefixed with MW_)

The following sections describe how to get each type of ticket via the PowerShell SDK.

BitTitan ticket

# This script shows how to get an authentication ticket

# Get a ticket
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

BitTitan ticket with organization id

You can scope a ticket to:

• A customer, by using the customer's OrganizationId.
• A workgroup, by using the workgroup's WorkgroupOrganizationId.

The ticket's OrganizationId will be set to either the customer's OrganizationId or the workgroup's WorkgroupOrganizationId.

When using a ticket scoped to a customer (or a workgroup):

• Operations on data that belongs to other customers (or workgroups) will be forbidden.
• Retrieve requests will only return results that belong to the scoped customer (or workgroup).

The following example illustrates how to get scoped tickets:

# This script shows how to get an authentication ticket
# 1) Scoped to a customer
# 2) Scoped to a workgroup

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# 1) Get a ticket scoped to a customer
$customerId = [GUID](Read-Host -Prompt 'Customer ID')  
$customer = Get-BT_Customer -Ticket $ticket -Id $customerId
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# 2) Get a ticket scoped to a workgroup
$workgroupId = [GUID](Read-Host -Prompt 'Workgroup ID')  
$workgroup = Get-BT_Workgroup -Ticket $ticket -Id $workgroupId
$workgroupTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $workgroup.WorkgroupOrganizationId

Setting the default ticket

Use the SetDefault parameter to set the default ticket. When doing so, you don't need to set the ticket on the cmdlets. You can have one default ticket for MigrationWiz commands and one default ticket for BitTitan commands.

# This script shows how to set a ticket to be used by default

# Get a ticket and set it as default
$creds = Get-Credential
Get-BT_Ticket -Credentials $creds -ServiceType BitTitan -SetDefault

# Retrieve customers without specifying the ticket
# This will use the ticket previously set as default
$customers = Get-BT_Customer

MigrationWiz ticket

# This script shows how to get an authentication ticket for MigrationWiz

# Get a ticket for MigrationWiz
$creds = Get-Credential
$mwTicket = Get-MW_Ticket -Credentials $creds

Overview

This section describes how to perform CRUD operations using the BitTitan SDK.

Initialize-MSPC_Context

The cmdlet, Initialize-MSPC_Context, creates a global variable $mspc, which contains a number of useful fields:

• Ticket: A ticket used in BT cmdlets
• MigrationWizTicket: A ticket used in MW cmdlets
• Customer: A customer.
• CustomerTicket: A customer scoped ticket.
• Workgroup: A workgroup.
• WorkgroupTicket: A workgroup scoped ticket.
• Data: A hashtable that stores global data.

The $mspc context object created by this cmdlet is identical to the $mspc variable available to every script running on the MSPC automation platform.

Thus it is recommended to run the Initialize-MSPC_Context cmdlet before testing Runbook scripts locally.

Since the $mspc context created is a global variable, it is useful when debugging a single script or multiple scripts as you do not need to enter credentials and variable inputs each time.

A few syntaxes are available for the cmdlet:

# This script illustrates how to use the Initialize-MSPC_Context cmdlet.

# Case 1: Initialize an mspc context with a customer ID
# Note: the customer's workgroup is used in creating both the workgroup and workgroup ticket.
Initialize-MSPC_Context -Credentials $credentials -CustomerId 'your customer ID here'

# Case 2: Initialize an mspc context with a workgroup ID
# Note: no customer nor customer ticket are created in this case.
Initialize-MSPC_Context -Credentials $credentials -WorkgroupId 'your workgroup ID here'

# Case 3: Clear the existing global $mspc context
# Note: clears the existing $mspc context before creating a new mspc context.
Initialize-MSPC_Context -Clear

Retrieve requests

Retrieve requests require tickets and have the following parameters:

• Ticket: The authentication ticket
• PageSize: The number of items per page. Default value is 100.
• PageOffset: The number of pages skipped. Default value is 0.
• <PropertyName>: See "Filtering"
• Sort_By_<PropertyName>_<Order>: See "Sorting"
• RetrieveAll: Used to retrieve all entities. More examples below.

Retrieve requests return PowerShell objects.

Here are a few common use cases:

# This script shows different ways to retrieve entities

# Authenticate
$creds = Get-Credential -Message "Enter BitTitan credentials"
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve a customer and get a ticket for it
$customerId = [GUID](Read-Host -Prompt 'Customer ID') 
$customer = Get-BT_Customer -Ticket $ticket -Id $customerId
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# Here are 3 common ways to retrieve entities
# 1. Retrieve all the endpoints under a customer and process them one by one
# Use -RetrieveAll and piping with ForEach 
Get-BT_Endpoint -Ticket $customerTicket -IsDeleted False -RetrieveAll | ForEach {
    # Process each endpoint retrieved
    Write-Host $_.Name
}

# 2. Retrieve and process endpoints under a customer in batches
# Use paging
$pageSize = 100
$count = 0
While( $true ) {   
    # Retrieve endpoints in batch
    [array]$batch = Get-BT_Endpoint -Ticket $customerTicket -IsDeleted False -PageOffset $($count * $pageSize)
    if ( -not $batch ) { 
        break
    }
    
    # Update each endpoint in the batch
    ForEach($endpoint in $batch) {
        $endpoint.Name += "_test"
    }

    # Send update request
    Set-BT_Endpoint -Ticket $customerTicket -Endpoint $batch

    # Increase count
    $count ++
}

# 3. Retrieve all the endpoints under a customer to get certain info, e.g. count 
# Use -RetrieveAll
# Note: This is the least efficient way among the 3 cases since it loads all the entities into the memory
$endpoints = Get-BT_Endpoint -Ticket $customerTicket -IsDeleted False -RetrieveAll
$endpoints.Count

Create requests

Create requests require tickets and have the following parameters:

• Ticket: The authentication ticket
• <PropertyName>: The property field of the object to create

Most of the created objects will have the following fields:

• Id: Guid representing the unique object id
• Created: Creation time
• Updated: Time of the latest update
• IsDeleted: Whether the entity has been deleted. Will always be false.
• Version: Field reserved for future versions
• SystemUserId: Id of the system user who created the object
• OrganizationId: Id of the organization of the customer who owns the object

In this example, we create a customer:

# This script illustrates how to create entities

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Create a customer
$customer = Add-BT_Customer -Ticket $ticket -CompanyName "TestCustomer" -PrimaryDomain "testCustomer.com"
Write-Output $customer

Update requests

Update requests require tickets and have the following parameters:

• Ticket: The authentication ticket
• <EntityName>: The entity(ies) to update
• <PropertyName>: The new value of the property of the object(s) to update

This example shows:

• How to update a single endpoint
• How to update multiple endpoints at a time

In this example, we update the endpoints' names.

# This script illustrates how to update entities

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Get a customer ticket
$customer = Get-BT_Customer -Ticket $ticket -CompanyName "Default"
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# Retrieve and update a single endpoint
# In this example, we update the endpoint's name
$endpoint = Get-BT_Endpoint -Ticket $customerTicket -Name "Endpoint1" -IsDeleted False
$endpoint = Set-BT_Endpoint -Ticket $customerTicket -Endpoint $endpoint -Name "Endpoint1 updated"
Write-Output $endpoint

# Alternatively, the endpoint's properties can also be modified directly on the object
$endpoint.Name = "Endpoint1 updated again"
$endpoint = Set-BT_Endpoint -Ticket $customerTicket -Endpoint $endpoint
Write-Output $endpoint

# Retrieve and update multiple endpoints
$endpoints = Get-BT_Endpoint -Ticket $customerTicket -Name @("Endpoint2", "Endpoint3") -IsDeleted False
$endpoints | ForEach {
    $_.Name += " updated"
}
$endpoints = Set-BT_Endpoint -Ticket $customerTicket -Endpoint $endpoints
Write-Output $endpoints

Delete requests

Delete requests require tickets and have the following parameters:

• Ticket: The authentication ticket
• Id: The IDs of the entity(ies) to delete

This example shows:

• How to delete a single endpoint
• How to delete multiple endpoints at a time

# This script illustrates how to delete entities

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Get a customer ticket
$customer = Get-BT_Customer -Ticket $ticket -CompanyName "Default"
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# Retrieve and delete a single endpoint
$endpoint = Get-BT_Endpoint -Ticket $customerTicket -Name "Test Endpoint" -IsDeleted False
Remove-BT_Endpoint -Ticket $customerTicket -Id $endpoint.Id

# Retrieve and delete multiple endpoints
$endpoints = Get-BT_Endpoint -Ticket $customerTicket -Name @("Endpoint 1", "Endpoint 2") -IsDeleted False
Remove-BT_Endpoint -Ticket $customerTicket -Id $endpoints.Id

Filtering

Filter parameters perform filtering on the server side to improve performance. If performance is not a concern, you can perform filtering on the client side using the Where-Object cmdlet instead.

The comparison operators are >, <, =, ==, <=, >=, !, !=, eq, exacty, lt, le, gt, ge, ne, not, after, before. Filtering against null value is also provided with operators IsNull and IsNotNull.

The wildcard character % (percent sign) is supported for string filtering and represents zero, one, or multiple characters. Wildcard character works with =, ==, eq, exactly or simply with default operator. To escape the wildcard character and search for a percent sign, you can use "[%]" (e.g. "75[%]" to look for "75%").

There are five types of filters, corresponding to different property types

• Numbers and dates: <PropertyName> "<Operator> <PropertyValue>"

  e.g. -Created @("> 01-01-2016")

• Strings: <PropertyName> "<PropertyValue>"

  e.g. -CompanyName "BitTitan"

• Other types (equal only): <PropertyName> <PropertyValue>

  e.g. -Id 00000000-0000-0000-0000-000000000000

• Array of filters on numbers and dates: <PropertyName> @("<Operator1> <PropertyValue1>", "<Operator2> <PropertyValue2>")

  e.g. -Created @("> 01-01-2016", "< 01-01-2018")

• Filter against null: <PropertyName> "IsNull" or "IsNotNull"

  e.g. -Configuration "IsNull"

Filters accept an array of property values as well:

• <PropertyName> <Array of Property values>

  e.g. -CompanyName @("BitTitan", "Microsoft")

This example shows how to use different types of filters:

# This script illustrates how to filter entities when retrieving them

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan
$mwTicket = Get-MW_Ticket -Credentials $creds 

# Retrieve endpoints, filtered by date and string property
$endpoints = Get-BT_Endpoint -Ticket $ticket -Created @("> 01-01-2016", "< 01-01-2018") -Name @("Endpoint1", "Endpoint2") 

# Retrieve mailbox connectors, filtered by a string with a wildcard and by multiple Ids
$mailboxConnectors = Get-MW_MailboxConnector -Ticket $mwTicket -FilterBy_String_Name "%project" -SelectedExportEndpointId $endpoints.Id

Dependent entity filtering

What is a dependent entity?

A dependent entity is an entity that has a relationship with the main entity.

e.g. Subscription entity is a dependent entity of CustomerEndUser entity. A CustomerEndUser's Id is equal to its related subscription entity's EntityReferenceId.

How are dependent entity filtering parameters formed?

Dependent entity filtering parameters are used in Get-BT_* cmdlets.

A dependent entity filtering parameter is built by combining the dependent entity's name and the dependent entity property's name.

e.g. CustomerEndUser has a dependent entity: Subscription, which has a property named SubscriptionEndDate, so Get-BT_CustomerEndUser has a parameter -SubscriptionSubscriptionEndDate.

How does dependent entity filtering work?

Unlike normal filtering parameters, dependent entity filtering allows retrieval of entities based on the dependent entity's properties.

# This script illustrates how to retrieve entities with dependent entity filtering

# Authenticate
$creds = Get-Credential -Message "Enter BitTitan credentials"
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# To get a workgroup that has a customer named BitTitan
$workgroup = Get-BT_Workgroup -Ticket $ticket -CustomerCompanyName 'BitTitan'

# To get all customer end users with unprocessed subscriptions
$customerEndUsers = Get-BT_CustomerEndUser -Ticket $ticket -SubscriptionSubscriptionProcessState NotProcessed

Which entities support dependent entity filtering?

Dependent entity filtering is available for the list of entities below:

Sorting

Sort parameters perform sorting on the server side to improve performance. If performance is not a concern, you can perform sorting on the client side using the Sort-Object cmdlet.

Sort parameters are available for numbers and dates. The format is Sort_By_<PropertyName>_<Order> and only one sort parameter can be specified.

This example shows how to retrieve entities sorted by a property:

# This script illustrates how to sort entities when retrieving them

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve endpoints, sorted by created date
$endpoints = Get-BT_Endpoint -Ticket $ticket -SortBy_Created_Descending

Pipelined Input

In PowerShell, a pipeline is a series of commands connected by pipeline operators ( | ) and is used commonly. Each pipeline operator sends the results of the preceding command to the next command.

The SDK supports pipelined input for any Set-BT_* and Remove-BT_* cmdlet.

The following is an example of how to use BT cmdlets in a pipeline:

# This script illustrates how to use pipelines with the BitTitan SDK

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Get a customer ticket
$customer = Get-BT_Customer -Ticket $ticket -CompanyName "Default"
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# Get all users associated to the customer and archive them
Get-BT_CustomerEndUser -Ticket $customerTicket -IsDeleted $false -RetrieveAll | Set-BT_CustomerEndUser -Ticket $customerTicket -IsArchived $true

# Get all devices associated to the customer and delete them
Get-BT_CustomerDevice -Ticket $customerTicket -IsDeleted $false -RetrieveAll | Remove-BT_CustomerDevice -Ticket $customerTicket -Force

Error handling

A typical PowerShell error looks like this:

$endpoints = Get-BT_Endpoint -Ticket $btTicket -SortBy_Version_Ascending -SortBy_Created_Ascending

Get-BT_Endpoint : Only one SortBy_ switch should be specified.
At line:1 char:14
+ ... endpoints = Get-BT_Endpoint -Ticket $btTicket -SortBy_Version_Ascendi...
+                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Get-BT_Endpoint], Exception
    + FullyQualifiedErrorId : System.Exception,BitTitan.Powershell.Cmdlets.GetBTEndpoint

Following is a list of common error messages you might encounter:

• "Set-BT_Customer: Update failed with 'Error: EntityInstanceNotFound'": The object has been deleted from the database and cannot be updated.

• "Add-BT_Customer: Create failed with 'Error: PropertyMustBeSet,{ property : CompanyName },{ value : }'": The CompanyName is mandatory and you need to specify the value of CompanyName to create the object.

• "Add-BT_Customer: Create failed with 'Error: Unknown. Cause: Cannot insert duplicate key row in object 'dbo.Customer' with unique index 'Idx_Customer_Id'. The duplicate key value is (8525efb1-d113-11e5-9bde-104a7ddf0ef7).

• "Add-BT_Customer: The statement has been terminated.'": The object already exists and cannot be created a second time. You can retrieve the existing object instead with Get-BT_<Object>.

• "Add-BT_Organization: Create failed with 'Error: InsufficientRights,{ property : },{ value : }'": The current ticket does not have the right to execute the requested operation. If you cannot find any workaround, you can contact us.

• "Add-BT_CustomerEndUser: Create failed with 'Error: TicketMustBindToOrganization,{ property : },{ value : }'": The ticket must be scoped to an organization to execute the requested operation. See "BitTitan authentication ticket with organization id".

• "Get-MW_Mailbox : There is an error in XML document (2, 34468).": Your BitTitan PowerShell module is outdated and you need to install the latest version.

Overview

BitTitan cmdlets allow users to perform actions available in the MSPComplete Website, e.g. adding a new endpoint, importing users, deploying a service and starting a task.

Key Terminology

• Workgroup: represents an environment containing sets of customers, end users, teams, and member information
• Customer: represents one of your customers
• Ticket: represents a security ticket, validating the authentication of your BitTitan account
• Ticket organization: represents the scope of a security ticket, which can be scoped to either a customer or a workgroup
• Workgroup member: represent a member of a workgroup
• End user: represents one of the employees of one of your customers
• Team: represents a group of BitTitan users
• Team member: represents a member of a team
• Service: represents an IT service you can deliver to your customers with MSPComplete. A service is divided into tasks
• Task: represents an IT task, which belongs to an IT service you can launch from MSPComplete
• Feed: represents alerts, warning and information related to your account and to your workgroup
• Subscription: represents an end user subscription that is required to run MSPComplete services for this user

Workgroups and Customers

Workgroups

A workgroup represents an environment containing sets of customers, end users, teams, and member information. More information about workgroups is available in the Help Center article, Add, edit, and switch workgroups.

Every BitTitan account is associated with at least one workgroup.

This example shows how to retrieve and create workgroups, using the Get-BT_Workgroup and Add-BT_Workgroup cmdlets:

# This script illustrates how to retrieve and create workgroups

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve workgroups
$workgroups = Get-BT_Workgroup -Ticket $ticket
Write-Output $workgroups

# Create a new workgroup
$newWorkgroup = Add-BT_Workgroup -Ticket $ticket -Name "Test Workgroup"
Write-Output $newWorkgroup

Customers

Customers are the companies whose IT and cloud infrastructure you manage and to whom you deliver a customized array of managed services. You can retrieve and/or create new customers as illustrated in this sample script:

# This script illustrates how to create a customer

# Authenticate
$creds = Get-Credential -Message "Enter BitTitan credentials"
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Initialize variables
$primaryDomain = "an-it-company.com"
$companyName = "IT Company"
$countryName = "Italy" # Optional

# Retrieve the workgroup that the customer should be created under
$workgroupId = [GUID](Read-Host -Prompt 'Workgroup ID')    
$workgroup = Get-BT_Workgroup -Ticket $ticket -Id $workgroupId

# Check if a customer with the same domain already exists under this workgroup
$existingCustomer = Get-BT_Customer -Ticket $ticket -WorkgroupId $workgroup.Id -PrimaryDomain $primaryDomain
if ( $existingCustomer -ne $null ) {
    # Write a warning if a customer already exists
    Write-warning "Customer with primary domain $primaryDomain already exists. A new customer was not created."
}
else {
    # Add a new customer
    # Additional parameters can be set such as CityName, IndustryType, CompanySize and more
    # Use Get-Help Add-BT_Customer to see all parameters
    Add-BT_Customer -Ticket $ticket -WorkgroupId $workgroup.Id -PrimaryDomain $primaryDomain -CompanyName $companyName -CountryName $countryName
}

Ticket organization

A ticket is always bound to a BitTitan account and can also be scoped to an organization. An organization is associated with either a workgroup or a customer.

• A ticket scoped to a workgroup organization will only have access to the customers, end users, services, teams and information belonging to that workgroup
• A ticket scoped a customer organization will only have access to the end users, services and information related to the customer.
• A ticket that does not have an organization ID has access to all the workgroups and customers associated with the BitTitan account.

The following example shows how to create a ticket scoped to a workgroup and one scoped to a customer.

# This script shows how to get an authentication ticket
# 1) Scoped to a customer
# 2) Scoped to a workgroup

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# 1) Get a ticket scoped to a customer
$customerId = [GUID](Read-Host -Prompt 'Customer ID')  
$customer = Get-BT_Customer -Ticket $ticket -Id $customerId
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# 2) Get a ticket scoped to a workgroup
$workgroupId = [GUID](Read-Host -Prompt 'Workgroup ID')  
$workgroup = Get-BT_Workgroup -Ticket $ticket -Id $workgroupId
$workgroupTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $workgroup.WorkgroupOrganizationId

Following is an example of organizations and system users (also known as BitTitan accounts) that have access to these organizations:

• SystemUser A and SystemUser B are members of Organization 1

  • They have access to Workgroup 1
    • They have access to all the entities under Workgroup 1 (Teams, PaymentProfiles, Subscriptions, etc.)
    • They have access to Customer 1 and Customer 2
    • They have access to all the entities under Customer 1 and Customer 2 (Devices, Endpoints, Groups, etc.)

• SystemUser A is not a member of Organization 2

  • SystemUser A doesn't have access to Workgroup 2
    • SystemUser A doesn't have access to any entity under Workgroup 2 (Teams, PaymentProfiles, Subscriptions, etc.)
    • SystemUser A doesn't have access to Customer 3 nor Customer 4
    • SystemUser A doesn't have access to any entity under Customer 3 nor Customer 4 (Devices, Endpoints, Groups, etc.)

Agents and Teams

Agents

The following script shows how to retrieve the members of a workgroup, a.k.a agents. You can find more information about agents in the Help Center article View, add, and edit agents.

# This script illustrates how to retrieve agents in a workgroup

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve a workgroup and get a ticket for it
$workgroupId = [GUID](Read-Host -Prompt 'Workgroup ID')    
$workgroup = Get-BT_Workgroup -Ticket $ticket -Id $workgroupId
$workgroupTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $workgroup.WorkgroupOrganizationId

# Retrieve the IDs of the agents in the workgroup
$agentIDs = (Get-BT_OrganizationMember -Ticket $workgroupTicket).SystemUserId
Write-Output $agentIDs

Teams

A team is a set of agents who can be assigned to an MSPComplete task or service.

The following example shows how to manage teams:

• To retrieve the teams of a workgroup, you can use the Get-BT_Team cmdlet and either filter the results on the workgroup organization id, or use a ticket scoped to the workgroup.
• To create a team, you can use the Add-BT_Team cmdlet, with a ticket scoped to the workgroup

# This script illustrates how to manage teams

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve a workgroup and get a ticket for it
$workgroupId = [GUID](Read-Host -Prompt 'Workgroup ID')    
$workgroup = Get-BT_Workgroup -Ticket $ticket -Id $workgroupId
$workgroupTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $workgroup.WorkgroupOrganizationId

# Retrieve teams in the workgroup
$teams = Get-BT_Team -Ticket $workgroupTicket
Write-Output $teams

# Create a new team under the workgroup
$team = Add-BT_Team -Ticket $workgroupTicket -Name "Test Team" -AssignmentType LeastLoad
Write-Output $team

Team Members

To retrieve the members of a team, you can use the Get-BT_TeamMembership cmdlet and filter the results on the team id. The example below shows how to retrieve, add or remove agents from a team:

# This script illustrates how to manage team members

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve a workgroup and get a ticket for it
$workgroupId = [GUID](Read-Host -Prompt 'Workgroup ID')    
$workgroup = Get-BT_Workgroup -Ticket $ticket -Id $workgroupId
$workgroupTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $workgroup.WorkgroupOrganizationId

# Retrieve a team
$team = Get-BT_Team -Ticket $workgroupTicket -Name "Test Team"

# Retrieve the IDs of the agents in the workgroup
$agentIDs = (Get-BT_OrganizationMember -Ticket $workgroupTicket).SystemUserId

# Add one agent to the team
$newTeamMember = Add-BT_TeamMembership -Ticket $workgroupTicket -TeamId $team.Id -SystemUserId $agentIDs[0]

# Retrieve the team members
$teamMembers = Get-BT_TeamMembership -Ticket $ticket -TeamId $team.Id
Write-Output $teamMembers

# Remove the agent from the team
Remove-BT_TeamMembership -Ticket $workgroupTicket -Id $newTeamMember.Id

Endpoints, End Users and Subscriptions

Endpoints

An endpoint encapsulates connection information and credentials to allow MSPComplete to connect to an external server or service. More information about endpoints can be found in the Help Center article View, add, and edit customer endpoints . The script in the following example shows how to create an endpoint under a customer.

# This script illustrates how to create an endpoint

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve a customer and get a ticket for it
$customerId = [GUID](Read-Host -Prompt 'Customer ID')    
$customer = Get-BT_Customer -Ticket $ticket -Id $customerId
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# Initialize a configuration (in this case an Exchange configuration)
$endpointConfiguraton = New-BT_ExchangeConfiguration -AdministrativeUsername "TestUserName" -AdministrativePassword "TestPassword" -UseAdministrativeCredentials $True -ExchangeItemType Mail

# Create a new endpoint
$endpoint = Add-BT_Endpoint -Ticket $customerTicket -Configuration $endpointConfiguraton -Type ExchangeOnline2 -Name "Test Endpoint"
Write-Output $endpoint

End Users

An end user, also referred to as "user", is an employee of one of your customers. The following example shows how to manage end users:

• To retrieve the end users of a customer, you can use the Get-BT_CustomerEndUser cmdlet and either filter the results on the customer organization id, or use a ticket scoped to this customer.
• To create an end user, you can use the Add-BT_CustomerEndUser cmdlet, with a ticket scoped to the customer.

# This script illustrates how to manage customer end users

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve a customer and get a ticket for it
$customerId = [GUID](Read-Host -Prompt 'Customer ID')    
$customer = Get-BT_Customer -Ticket $ticket -Id $customerId
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# Create a new end user under that customer
$newEndUser = Add-BT_CustomerEndUser -Ticket $customerTicket -PrimaryEmailAddress "user@test.com" -FirstName John -LastName Smith
Write-Output $newEndUser

# Retrieve the end users under that customer
$endUsers = Get-BT_CustomerEndUser -Ticket $customerTicket
Write-Output $endUsers

Subscriptions

A subscription represents a user subscription that is required to run MSPComplete services for this user. For more information about subscriptions, see the Help Center article Subscription and licensing FAQ .

The script that follows shows how to retrieve and assign subscriptions to end users.

# This script shows how to assign subscriptions to customer end users

# Authenticate
$creds = Get-Credential -Message "Enter BitTitan credentials"
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan
     
# Retrieve a customer and its workgroup
$customerId = [GUID](Read-Host -Prompt 'Customer ID')    
$customer = Get-BT_Customer -Ticket $ticket -Id $customerId
$workgroup = Get-BT_Workgroup -Ticket $ticket -Id $customer.WorkgroupId

# Initialize additional tickets
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId
$workgroupTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $workgroup.WorkgroupOrganizationId        

# Get the end users under that customer (this example retrieves the top 100)
$customerEndUsers =  Get-BT_CustomerEndUser -Ticket $customerTicket -IsDeleted $False -PageSize 100
if ( $customerEndUsers ) {
    # Check for existing subscriptions
    $existingSubscriptions = Get-BT_Subscription -Ticket $workgroupTicket -ReferenceEntityType CustomerEndUser -ReferenceEntityId $customerEndUsers.Id -IsDeleted $False
    
    # Filter out end users who already have a subscription
    $customerEndUsersToSubscribe = $customerEndUsers | Where {
        $existingSubscriptions.ReferenceEntityId -notcontains $_.Id 
    }
    
    # Get the product sku id for the MSPC yearly subscription
    $productSkuId = Get-BT_ProductSkuId -Ticket $ticket -ProductName MspcEndUserYearlySubscription

    # Assign subscriptions to each customer end user
    $customerEndUsersToSubscribe | ForEach {
        Add-BT_Subscription -Ticket $workgroupTicket -ReferenceEntityType CustomerEndUser -ReferenceEntityId $_.Id -ProductSkuId $productSkuId 
    }
    $assignedSubscriptionCount = $customerEndUsersToSubscribe.Length
    Write-Verbose "Successfully assigned subscription to $assignedSubscriptionCount end users."
}

Extended properties

MSPComplete allows agents to set their own custom properties (a.k.a extended properties) on entities. Custom properties are included automatically when records are retrieved using the BitTitan SDK.

The following is an example of how to manage extended properties on entities:

# This script illustrates how to manage extended properties on entities
# Extended properties can be added to various entities. Examples include 'Customer', 'CustomerDevice' and 'CustomerEndUser'.

# Authenticate
$creds = Get-Credential -Message "Enter BitTitan credentials"
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve a customer
$customer = Get-BT_Customer -Ticket $ticket -CompanyName "Default"
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# Add two extended properties to this customer
$customer.ExtendedProperties.SomeProperty = 'SomeValue'
$customer.ExtendedProperties.AnotherProperty = 'AnotherValue'
$customer = Set-BT_Customer -customer $customer -Ticket $customerTicket

# Lookup the current extended properties
Write-Output "The customer has the following custom properties:"
$customer.ExtendedProperties
Write-Output "The value of the custom property with name 'SomeProperty' is '$($customer.ExtendedProperties.SomeProperty)'."

# Update one extended property, delete the other one
$customer.ExtendedProperties.SomeProperty = 'SomeNewValue'
$customer.ExtendedProperties.Remove('AnotherProperty')
$customer = Set-BT_Customer -customer $customer -Ticket $customerTicket

# Lookup the updated extended properties again
Write-Output "The customer now has the following custom properties:"
$customer.ExtendedProperties

Other entities

Feeds

A feed represents notification pertaining to your customers’ service activities and changes. There are two feeds available in the platform: a personal feed and a customer feed. For more information about feeds, see the Help Center article MSPComplete feeds and notifications .

There are two different types of entities for feeds:

1. The metadata, called FeedMetadata, which contains information about the feed, such as the name and type of feed.
2. The instance, called FeedInstance, which contains information about one of your instantiations of the feed, such as the content of the feed and the event date.

To retrieve the list of feed instances, use the Get-BT_FeedInstance cmdlet, as shown in the example below:

# This script illustrates how to retrieve feeds for a given workgroup

# Authenticate
$creds = Get-Credential

# Initialize variables
$workgroupId = [GUID](Read-Host -Prompt 'Workgroup ID')    

# Retrieve the top 10 most recent feeds under the workgroup
$ticketWithWorkgroupId = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan -WorkgroupId $workgroupId
$feedInstances = Get-BT_FeedInstance -Ticket $ticketWithWorkgroupId -PageSize 10 -SortBy_Created_Descending

# Retrieve the corresponding feed metadata
$feedMetadata = Get-BT_FeedMetadata -Ticket $ticketWithWorkgroupId -Id $feedInstances.FeedMetadataId

# Display the feeds
ForEach ($feedInstance in $feedInstances) {
    # Retrieve the metadata of the current feed instance
    $metadata = $feedMetadata | Where {
        $feedInstance.FeedMetadataId -eq $_.Id
    }
    
    # Display the feed keyname and parameters
    $parameterStrings = @()
    For ($i=0; $i -lt $feedInstance.Parameters.Length; $i++) {
       $parameterStrings +=  "$($feedInstance.Parameters[$i].Name)=$($feedInstance.Parameters[$i].Value)"
    }
    Write-Output "$($feedInstance.EventDate) - $($metadata.KeyName): $([string]::Join(", ", $parameterStrings))"
}

Reports

A report represents a snapshots of current state of your business and helps you track it over time. For more information about reports, see the Help Center article View and add workgroup reports .

To retrieve a generated report, you need to be the administrator of the workgroup. Use the Get-BT_ReportInstance cmdlet to list the reports and then use Get-BT_ReportWithData to get the data for a specific report.

The example below shows how to retrieve a report and its data:

# This script illustrates how to retrieve report data

# Authenticate
$creds = Get-Credential
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve a workgroup and get a ticket for it
$workgroupId = [GUID](Read-Host -Prompt 'Workgroup ID')    
$workgroup = Get-BT_Workgroup -Ticket $ticket -Id $workgroupId
$workgroupTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $workgroup.WorkgroupOrganizationId

# Retrieve the last generated report and its data.
$reportInstance = Get-BT_ReportInstance -Ticket $workgroupTicket -PageSize 1 -SortBy_GeneratedOn_Descending
$reportWithData = Get-BT_ReportWithData -Ticket $workgroupTicket -ReportInstanceId $reportInstance.Id
Write-Output $reportWithData

Overview

This section illustrates how to run MSPComplete services and simulate user inputs using BitTitan cmdlets. To understand the main MSPComplete concepts, we advise you to read the "MSPComplete concepts" section first.

Key Terminology

• Instructional task: represents an MSPComplete task that only contains instructions and images. Also known as a manual or prescriptive guidance task
• Input task: represents an MSPComplete task that asks the user for some input information. Input tasks can contain instructions and images
• Validation task: represents an MSPComplete task that validates the user input information
• Confirmation task: represents an MSPComplete task that asks the user to confirm the input information
• Processing parent task: represents an MSPComplete task associated with one or multiple background jobs. The background jobs will start running once the task has been started.
• Processing child task: represents an MSPComplete sub-task associated with a unique background job.
• Property bag: represents a set of text input information (for example, email address, mailbox size)
• Reference: represents some input information referencing data available in MSPComplete (for example, endpoints or end users)
• Task target: represents an association between a task instance and a reference, a property bag, or another task instance

Concepts

Services

A service represents an IT service you can deliver to your customers with MSPComplete. A service is divided into tasks. For more information about services and tasks, see the Help Center article Introduction to services and tasks.

There are two types of entities for services:

• The service metadata, called OfferingMetadata, which contains information about the service, such as the vendor and keywords
• The service instance, called OfferingInstance, which contains information about one of your executions of the service, such as the execution status and the customer organization id

To retrieve the details of a service, use the Get-BT_OfferingMetadata cmdlet.

$credentials = Get-Credential
$btTicket = Get-BT_Ticket -Credentials $credentials -ServiceType BitTitan
$offeringMetadata = Get-BT_OfferingMetadata -Ticket $btTicket -Name "Assess Azure ROI"

To retrieve the list of existing instances of the services, you can use the Get-BT_OfferingInstance cmdlet.

$credentials = Get-Credential
$btTicket = Get-BT_Ticket -Credentials $credentials -ServiceType BitTitan
$offeringInstances = Get-BT_OfferingInstance -Ticket $btTicket

The section below describes how to deploy a Service.

Tasks

A task represents an IT task, a single step in a service, which belongs to an IT service that you can launch from MSPComplete.

There are two different types of entities for tasks:

• The task metadata, called TaskMetadata, which contains information about the task, such as the name and the type of the task
• The task instance, called TaskInstance, which contains information about one of your executions of the task, such as the execution status and the customer organization id

To retrieve the list of tasks associated to a service, use the Get-BT_OfferingMetadataToTaskMetadata cmdlet. Once you have the task metadata ids, you can retrieve the details of the tasks using the Get-BT_TaskMetadata cmdlet.

$credentials = Get-Credential
$btTicket = Get-BT_Ticket -Credentials $credentials -ServiceType BitTitan
$offeringMetadata = Get-BT_OfferingMetadata -Ticket $btTicket -Name "Assess Azure ROI"
$offeringMetadataToTaskMetadataEntities = Get-BT_OfferingMetadataToTaskMetadata -Ticket $btTicket -OfferingMetadataId $offeringMetadata.Id -SortBy_TaskDefaultExecutionOrder_Ascending
$taskMetadataEntities = New-Object System.Collections.ArrayList
foreach ($offeringMetadataToTaskMetadata in $offeringMetadataToTaskMetadataEntities) {
	$taskMetadata = Get-BT_TaskMetadata -Ticket $btTicket -Id $offeringMetadataToTaskMetadata.TaskMetadataId
	$taskMetadataEntities.Add($taskMetadata)
}

To retrieve the list of existing instances of the tasks belonging to a given service, use the Get-BT_TaskInstance cmdlet.

$credentials = Get-Credential
$btTicket = Get-BT_Ticket -Credentials $credentials -ServiceType BitTitan
$offeringMetadata = Get-BT_OfferingMetadata -Ticket $btTicket -Name "Assess Azure ROI"
$offeringInstances = Get-BT_OfferingInstance -Ticket $btTicket -OfferingMetadataId $offeringMetadata.Id
$taskInstanceEntities = Get-BT_TaskInstance -Ticket $btTicket -OfferingInstanceId $offeringInstances[0].Id -SortBy_ExecutionOrder_Ascending

Property Bags

A property bag represents a set of text input information (e.g. email address, mailbox size).

You can retrieve the list of property bags with the Get-BT_PropertyBag cmdlet.

$credentials = Get-Credential
$btTicket = Get-BT_Ticket -Credentials $credentials -ServiceType BitTitan
$propertyBags = Get-BT_PropertyBag -Ticket $btTicket

The section below shows an example of how to create a property bag when executing an input task programmatically.

Task Targets

A task target represents an association between a task instance and a reference, a property bag, or another task instance.

You can retrieve the list of task targets using the Get-BT_TaskTarget cmdlet.

$credentials = Get-Credential
$btTicket = Get-BT_Ticket -Credentials $credentials -ServiceType BitTitan
$taskTargets = Get-BT_TaskTarget -Ticket $btTicket

The section below shows an example of how to create a task target when executing an input task programmatically.

Deploying a Service

To deploy a service, you simply instantiate a service instance with a ticket scoped to a customer and the Add-BT_OfferingInstance cmdlet.

# This script shows how to deploy a runbook to a customer

# Authenticate
$creds = Get-Credential -Message "Enter BitTitan credentials"
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Initialize variables
$offeringMetadataId = [GUID](Read-Host -Prompt 'Runbook ID')
$customerId = [GUID](Read-Host -Prompt 'Customer ID')    

# Retrieve the customer to deploy the runbook to
# And get a ticket for it
$customer = Get-BT_Customer -Ticket $ticket -Id $customerId
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# Deploy the runbook
Add-BT_OfferingInstance -Ticket $customerTicket -OfferingMetadataId $offeringMetadataId
Write-Verbose "Deployed runbook: $offeringMetadataId to customer: $($customer.CompanyName)."

Once the MSPComplete service has been deployed, the following entities have been created:

• Each instructional, input, validation, and processing parent task is created.
• A processing task can depend on one or multiple input tasks. For each dependency, a task target associating the processing parent task instance and the input task instance is created.

Executing the input Tasks

To execute an input task, select the input, then complete the task. To select the input, use one of the two cmdlets:

• Add-BT_TaskTarget cmdlet to select a reference as an input
• Add-BT_PropertyBag cmdlet to create a text input

Once the input has been selected, you can use the Complete-BT_TaskInstance cmdlet to complete the input task and go to the next task.

# This script follows the previous script (Add-BT_OfferingInstance cmdlet script)
$taskInstances = Get-BT_TaskInstance -Ticket $customerTicket -OfferingInstanceId $offeringInstance.Id -SortBy_ExecutionOrder_Ascending

# Execute the endpoint input task
$endpoints = Get-BT_Endpoint -Ticket $customerTicket
$endpointTaskTarget = Add-BT_TaskTarget -Ticket $customerTicket -ReferenceEntityType "Endpoint" -ReferenceEntityId $endpoints[0].Id -TaskInstanceId $taskInstances[0].Id
Complete-BT_TaskInstance -Ticket $customerTicket -TaskInstanceId $taskInstances[0].Id

# Execute the user input task
$groupMembers = Get-BT_GroupMembership -Ticket $customerTicket -GroupId $endpoints[0].GroupId
$endUsers = Get-BT_CustomerEndUser -Ticket $customerTicket -Id $groupMembers.EndUserId -SubscriptionType "ne None"
$endUserTaskTarget = Add-BT_TaskTarget -Ticket $customerTicket -ReferenceEntityType "CustomerEndUser" -ReferenceEntityId $endUsers[0].Id -TaskInstanceId $taskInstances[1].Id
Complete-BT_TaskInstance -Ticket $customerTicket -TaskInstanceId $taskInstances[1].Id

# Execute the proxy email address input task
$emailProperty = New-Object -TypeName ManagementProxy.ManagementService.PropertyString
$emailProperty.Value = "alias@company.com"
$emailProperty.Name = "ProxyEmailAddress"
$properties = @($emailProperty)
$propertyBag = Add-BT_PropertyBag -Ticket $customerTicket -Properties $properties -ReferenceEntityType "TaskInstance" -ReferenceEntityId $taskInstances[2].Id
Complete-BT_TaskInstance -Ticket $customerTicket -TaskInstanceId $taskInstances[2].Id

Once the input tasks have been executed, the following entities have been created:

Note that each input task is associated with either a property bag or a reference via a task target.

Executing the processing Task

To execute a processing task, use the Complete-BT_TaskInstance cmdlet once the input tasks have been executed:

# This script follows the previous script (Complete-BT_TaskInstance cmdlet script for input tasks)
Complete-BT_TaskInstance -Ticket $customerTicket -TaskInstanceId $taskInstances[3].Id

Once the processing task has been executed, the following entities have been created:

• A processing child task is created for each background job. The AddProxyOffice365 cmdlet from our example requires one background job per user while other processing parent tasks only require a unique background job.
• One task target is created for each input task and is associated with either a reference or a property bag. Most of the task targets are associated with the processing parent task but some task targets might be associated with the processing children tasks when the data is only relevant to a particular child task (for example, one end user).

Exporting / Importing a Service

The SDK can be used to export/import a service to/from a ZIP file. The following examples show how to do so:

# This script shows how to export a runbook to a file

# Authenticate
$creds = Get-Credential -Message "Enter BitTitan credentials"
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Initialize variables
$offeringMetadataId = [GUID](Read-Host -Prompt 'Runbook ID')
$folderPath = Read-Host -Prompt 'Folder path to export to'

# Export the runbook to FolderPath
Export-BT_OfferingMetadata -Ticket $ticket -OfferingMetadataId $offeringMetadataId -FolderPath $folderPath

# This script shows how to import a runbook to a workgroup

# Authenticate
$creds = Get-Credential -Message "Enter BitTitan credentials"
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Initialize variables
$workgroupId = [GUID](Read-Host -Prompt 'Workgroup ID to import to')
$filePath = Read-Host -Prompt 'File path to import from'

# Get a ticket scoped to the workgroup
$workgroup = Get-BT_Workgroup -Ticket $ticket -Id $workgroupId
$workgroupTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $workgroup.WorkgroupOrganizationId

# Import the runbook from FilePath
Import-BT_OfferingMetadata -Ticket $workgroupTicket -FilePath $filePath

Overview

MigrationWiz cmdlets allow users to perform actions available in the MigrationWiz website, for example, adding new MigrationWiz project, adding new migration items, starting a migration, removing a migration project, and so forth.

Key Terminology

• Mailbox Connector: represents a MigrationWiz project
• Mailbox: represents a migration item in a MigrationWiz project
• Mailbox Queue: represents the item added to the migration queue after a migration project is started

Starting a new project

Starting a new project

The following example shows how to programmatically create a project in MigrationWiz and start a migration.

In the script below we create the export configuration and the import configuration to be used in the project. You can find more information about how to create project configurations in this section.

# Get both bt and mw tickets
$cred = Get-Credential
$mwTicket = Get-MW_Ticket -Credentials $cred
$btTicket = Get-BT_Ticket -Credentials $cred -ServiceType BitTitan

# Get customer, filtered by company name
# Mailbox connector is scoped under customer
$customer = Get-BT_Customer -Ticket $btTicket -CompanyName 'company-name-here'

# Set up export and import configurations
# You can choose to provide admin credentials and set UseAdministrativeCredentials to true, then you do not need to provide usernames and passwords in mailbox creation.
$exportConfiguration = New-Object -TypeName MigrationProxy.WebApi.ExchangeConfiguration -Property @{
        "UseAdministrativeCredentials" = $false;
        "ExchangeItemType" = "Mail";
}

$importConfiguration = New-Object -TypeName MigrationProxy.WebApi.ExchangeConfiguration -Property @{
        "UseAdministrativeCredentials" = $false;
        "ExchangeItemType" = "Mail";
}

# Create a new project
$connector = Add-MW_MailboxConnector -ticket $mwTicket -ProjectType Mailbox `
    -ImportType Office365Groups -ExportType Office365Groups -Name "your_project_name" -UserId $ticket.UserId `
    -OrganizationId $customer.OrganizationId

# Create an migration item with export, import credentials
$mailbox = Add-MW_Mailbox -Ticket $mwTicket -ConnectorId $connector.Id `
	-ImportEmailAddress import@email.com -ExportEmail export@email.com -ExportPassword your_export_password -ImportPassword your_import_password `
	-ExportUserName exprot@email.com -ImportUserName import@email.com

# Start a migration
$migration = Add-MW_MailboxMigration -Ticket $mwTicket -ConnectorId $connector.Id -MailboxId $mailbox.Id -UserId $mwTicket.UserId -Type Full -ItemTypes Contact 
          

Starting a new project with existing endpoints

# Get both mw and bt ticket
$cred = Get-Credential
$mwTicket = Get-MW_Ticket -Credentials $cred
$btTicket = Get-BT_Ticket -Credentials $cred -ServiceType BitTitan

# Get customer, filtered by company name
# Mailbox connector is scoped under customer
$customer = Get-BT_Customer -Ticket $btTicket -CompanyName 'company-name-here'

# Get both import and export endpoints by their names
$importEndpoint = Get-BT_Endpoint -Ticket $btTicket -Name MyImportEndpoint
$exportEndpoint = Get-BT_Endpoint -Ticket $btTicket -Name MyExportEndpoint

# Create a new project
$connector = Add-MW_MailboxConnector -ticket $ticket -ProjectType Mailbox `
    -ImportType Office365Groups -ExportType Office365Groups -Name "your_project_name" -UserId $ticket.UserId `
    -SelectedExportEndpointId $exportEndpoint.Id -SelectedImportEndpointId $importEndpoint.Id -OrganizationId $customer.OrganizationId

# Create an migration item with export, import credentials
$mailbox = Add-MW_Mailbox -Ticket $ticket -ConnectorId $connector.Id `
	-ImportEmailAddress import@email.com -ExportEmail export@email.com 

# Start a migration
$migration = Add-MW_MailboxMigration -Ticket $ticket -ConnectorId $connector.Id -MailboxId $mailbox.Id -UserId $ticket.UserId -Type Full -ItemTypes Contact 
          

Adding an item to an existing project

# Get an existing project
# The simplest way is to filter by project name, but this requires that a unique project name is used. If there are multiple projects with the same name, a list of projects will be returned. 
$connector = Get-MW_MailboxConnector -ticket $ticket -Name "your_unique_project_name"

# Create an migration item
# Username and password are not required if the project(connector) is using admin credentials for migration.
$mailbox = Add-MW_Mailbox -Ticket $ticket -ConnectorId $connector.Id `
	-ImportEmailAddress import@email.com -ExportEmail export@email.com -ExportPassword your_export_password -ImportPassword your_import_password `
	-ExportUserName exprot@email.com -ImportUserName import@email.com

# Start a migration
$migration = Add-MW_MailboxMigration -Ticket $ticket -ConnectorId $connector.Id -MailboxId $mailbox.Id -UserId $ticket.UserId -Type Full -ItemTypes Contact
          

Starting migrations for existing items in a project

# Get an existing project
# The simplest way is to filter by project name, but this requires that a unique project name is used. If there are multiple projects with the same name, a list of projects will be returned. 
$connector = Get-MW_MailboxConnector -ticket $ticket -Name "your_unique_project_name"

# Get migration items in the project, filtered by project(connector) id
$mailboxItems = Get-MW_Mailbox -ticket $ticket -ConnectorId $connector.Id

# Start all items found in the project
foreach($mailbox in $mailboxItems)
{
     $migration = Add-MW_MailboxMigration -Ticket $ticket -ConnectorId $connector.Id -MailboxId $mailbox.Id -UserId $ticket.UserId -Type Full -ItemTypes Contact 
}

Overview

You can use the BitTitan SDK to automate your DMA scenarios, such as retrieving agent status, scheduling DeploymentPro, etc.

Devices

A device represents a computer, server or other type of devices that customer end users are using.

This example shows how to retrieve devices and the agent status information for each user on the device

# This script shows how to retrieve the DMA status for devices and users

# Authenticate
$creds = Get-Credential -Message "Enter BitTitan credentials"
$ticket = Get-BT_Ticket -Credentials $creds -ServiceType BitTitan

# Retrieve the customer and get a ticket for it
$customerId = [GUID](Read-Host -Prompt 'Customer ID')    
$customer = Get-BT_Customer -Ticket $ticket -Id $customerId
$customerTicket = Get-BT_Ticket -Ticket $ticket -OrganizationId $customer.OrganizationId

# Retrieve top 10 devices
$devices = Get-BT_CustomerDevice -Ticket $customerTicket -PageSize 10

# Retrieve information for each user on each device found previously
$devices | ForEach {
    # Retrieve the information for each user
    $deviceName = $_.DeviceName
    $deviceUsers = Get-BT_CustomerDeviceUser -Ticket $customerTicket -DeviceId $_.Id
    
    # Retrieve the corresponding end user information and print the agent status
    $deviceUsers | ForEach {
        $endUser = Get-BT_CustomerEndUser -Ticket $customerTicket -Id $_.EndUserId
        Write-Output "$($deviceName): $($endUser.PrimaryEmailAddress) - $($_.AgentStatus)"
    }
}

Overview

This section describes how to initialize configurations for endpoints or MigrationWiz projects.

Configurations for different types of endpoints require different fields (see the configuration table below). Moreover, the configuration types used in BitTitan and MigrationWiz cmdlets are different.

The New-BT_*Configuration and New-MW_*Configuration cmdlets can be used to create configurations for endpoints ("BT" (BitTitan) configurations) and MigrationWiz projects ("MW" (MigrationWiz) configurations) respectively. For example:

• New-BT_ExchangeConfiguration can be used to create a BitTitan Exchange configuration
• New-MW_SharePointConfiguration can be used to create a MigrationWiz SharePoint configuration
• Etc.

The configuration table lists all possible configuration types.

Endpoint configuration

Use New-BT_*Configuration cmdlets to create configurations for different types of endpoints.

# This is an exchange configuration used for Office 365 (ExchangeOnline2) server.
$configuration = New-BT_ExchangeConfiguration -AdministrativeUsername "your user name" -AdministrativePassword "your password" -UseAdministrativeCredentials $True -ExchangeItemType Mail

# Add a new endpoint
$endpoint = Add-BT_Endpoint -Ticket $ticket -Configuration $configuration -Type ExchangeOnline2 -Name "your-end-point-name"

Endpoint Credential

Endpoints with ExchangeConfiguration or GenericConfiguration, such as Office 365 endpoint and Exchange Server 2003+ endpoint, expose a PowerShell Credential field.

Note: In order to reveal the Credential field, ShouldUnmaskProperties parameter should be set to $True when using Get-BT_Endpoint to retrieve endpoints.

# Retrieve Endpoint
$endpoint = Get-BT_Endpoint -Ticket $ticket -ShouldUnmaskProperties $true

# Here PSCredential can be used to connect to Office 365 or Microsoft Exchange PowerShell
Msol-Connect -Credential $endpoint.Credential

MigrationWiz project configuration

New-MW_*Configuration cmdlets allow you to create MigrationWiz configurations for connectors.

# In this example, we create one Zimbra configuration and one Exchange configuration.
# Since Add-MW_MailboxConnector is a MigrationWiz cmdlet, MW configurations are used.
$exportConfiguration = New-MW_ZimbraConfiguration -AdministrativeUsername "your_export_admin_username" -AdministrativePassword "your_export_admin_password" `
        -Url "https://your-zimbra-url@test.com" -UseAdministrativeCredentials $true
$importConfiguration = New-MW_ExchangeConfiguration -AdministrativeUsername "your_import_admin_username" -AdministrativePassword "your_import_admin_password" `
        -Url "https://your-exchange-url@test.com" -UseAdministrativeCredentials $true -ExchangeItemType Mail

# Create a new project with the configurations
$connector = Add-MW_MailboxConnector -ticket $mwTicket -ProjectType Mailbox `
    -ExportType Zimbra -ImportType Office365 -Name "your_unique_project_name" -UserId $mwTicket.UserId `
    -ExportConfiguration $exportConfiguration -ImportConfiguration $importConfiguration -OrganizationId $customer.OrganizationId

Configuration Table