lib/Brokers.ps1


function New-TMBroker {
    <#
    .SYNOPSIS
    Creates a new TMBroker class object
 
    .DESCRIPTION
    This function
 
    .PARAMETER TMSession
    The name of the TransitionManager sesssion to use with the new Broker
 
    .PARAMETER TMEvent
    A TMEvent class object representing the TransitionManager Event in which the Broker will be operating
 
    .PARAMETER TaskId
    The Id of the Broker task
 
    .PARAMETER ExecutionMode
    The type of scoping the Broker will use to determine its subject Tasks. The Inline scope type will
    determine
 
    .PARAMETER SubjectScopeTaskProperty
    A property on the Tasks that will be evaluated to determine the Broker's subject Tasks
 
    .PARAMETER SubjectScopeMatchingCriteria
    The value(s) to match on the SubjectScopeTaskProperty
 
    .PARAMETER SubjectScopeMatchExpression
    A ScriptBlock that will be used to filter the Tasks to determine the Broker's subject Tasks
 
    .PARAMETER SubjectScopeTaskFilter
    A TMBrokerTaskFilter object that will be used in the TMQL query to filter the Tasks to determine the Broker's subject Tasks
 
    .PARAMETER TimeoutMinutes
    The amount of time in minutes that the Broker can run before automatically terminating its execution
 
    .PARAMETER PauseSeconds
    The amount of time in seconds that the Broker should pause in between processing subject tasks
 
    .PARAMETER Parallel
    Switch: This switch will have the broker run multiple parallel runspaces for subjects it encounters.
 
    .PARAMETER Throttle
    Required when Parallel is used. This Parameter controls how many concurrent threads the Broker will be allowed to use
 
    .EXAMPLE
    # Login to TransitionManager
    $SessionSplat = @{
        SessionName = 'Broker'
        Server = ([URI]$ActionRequest.options.callback.siteUrl).host
        Credential = (Get-StoredCredential TM)
        Project = $ActionRequest.task.project.name
    }
    $Session = New-TMSession @SessionSplat
 
    # Get the Event
    $TMEvent = Get-TMEvent -TMSession 'Broker' -Name $ActionRequest.task.event.name -ProjectId $ActionRequest.options.projectId
 
    # Create a new Broker
    $Broker = New-TMBroker -TMSession 'Broker' -TMEvent $TMEvent -TaskId $ActionRequest.task.id
 
    .EXAMPLE
    # Create a new Broker that scopes all Tasks with a Category of 'AWS MGN' or 'VMware vCenter'
    $BrokerSplat = @{
        ExecutionMode = 'Service'
        SubjectScopeTaskProperty = 'Category
        SubjectScopeMatchingCriteria = 'AWS MGN', 'VMware vCenter'
        Parallel = $true
    }
    $Broker = New-TMBroker -TaskId $ActionRequest.task.id
 
    .EXAMPLE
    # Create a new Broker that scopes all Tasks whose Action names match either 'vCenter' or 'MGN' and
    # have an associated 'VM' type Asset
    $BrokerSplat = @{
        ExecutionMode = 'Service'
        SubjectScopeMatchExpression = {($_.Action.Name -match '(vCenter)|(MGN)) -and ($_.Asset.Type -eq 'VM')}
        Parallel = $true
    }
    $Broker = New-TMBroker -TaskId $TM.Task.Id
 
    .OUTPUTS
    A TMBroker class object
    #>


    [CmdletBinding(DefaultParameterSetName = 'ByTaskProperty')]
    param (
        [Parameter(Mandatory = $false, Position = 0)]
        [String]$TMSession = 'Default',

        [Parameter(Mandatory = $false, Position = 1)]
        [TMEvent]$TMEvent,

        [Parameter(Mandatory = $false, Position = 2)]
        [Int]$TaskId,

        [Parameter(Mandatory = $false)]
        [ValidateSet('Service', 'Inline')]
        [Alias('Type')]
        [String]$ExecutionMode = 'Service',

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperty')]
        [ValidateSet('Title', 'Category', 'Team', 'Action')]
        [Alias('TaskProperty')]
        [String]$SubjectScopeTaskProperty = 'Title',

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperty')]
        [Alias('MatchingCriteria')]
        [String[]]$SubjectScopeMatchingCriteria,

        [Parameter(Mandatory = $true, ParameterSetName = 'ByExpression')]
        [Alias('MatchExpression')]
        [ScriptBlock]$SubjectScopeMatchExpression,

        [Parameter(Mandatory = $true, ParameterSetName = 'ByFilter')]
        [Alias('MatchFilter', 'Filter')]
        [TMBrokerTaskFilter]$SubjectScopeTaskFilter,

        [Parameter(Mandatory = $false)]
        [Int]$TimeoutMinutes = 120,

        [Parameter(Mandatory = $false)]
        [Int]$PauseSeconds = 15,

        [Parameter()]
        [Switch]$Parallel,

        [Parameter(Mandatory = $false)]
        [Int]$Throttle = 8
    )


    # Get the session configuration
    Write-Verbose 'Checking for cached TMSession'
    $TMSessionConfig = $global:TMSessions[$TMSession]
    Write-Debug 'TMSessionConfig:'
    Write-Debug ($TMSessionConfig | ConvertTo-Json -Depth 5)
    if (-not $TMSessionConfig) {
        throw "TMSession '$TMSession' not found. Use New-TMSession command before using features."
    }

    # Initialize a new broker
    if ($PSCmdlet.ParameterSetName -eq 'ByTaskProperty') {
        $Broker = [TMBroker]::new(
            $ExecutionMode,
            $SubjectScopeTaskProperty,
            $SubjectScopeMatchingCriteria,
            $TimeoutMinutes,
            $PauseSeconds,
            $Parallel.IsPresent,
            $Throttle
        )
    } elseif ($PSCmdlet.ParameterSetName -eq 'ByFilter') {
        $Broker = [TMBroker]::new(
            $ExecutionMode,
            $SubjectScopeTaskFilter,
            $TimeoutMinutes,
            $PauseSeconds,
            $Parallel.IsPresent,
            $Throttle
        )
    } else {
        $Broker = [TMBroker]::new(
            $ExecutionMode,
            $SubjectScopeMatchExpression,
            $TimeoutMinutes,
            $PauseSeconds,
            $Parallel.IsPresent,
            $Throttle
        )
    }

    # Load the TM Session into the broker
    $Broker.TMSession = $TMSessionConfig

    if ($TMEvent) {
        # Add the TM Event supplied by the invocation
        $Broker.EventData.Event = $TMEvent
    } elseif ([String]::IsNullOrWhiteSpace($Broker.TMSession.UserContext.Event.Name)) {
        throw "TMSession $($TMSession.Name) does not contain an Event Name in the UserContext property. Provide a value for the -TMEvent parameter"
    }

    # Load the Event's data into the broker
    $Broker.GetEventData()

    # Fill the task data if a Task Id was provided
    if ($TaskId) {
        $Broker.GetTaskData($TaskId)
    }

    # Return the new broker
    $Broker
}


function Get-TMBrokerTaskData {
    <#
    .SYNOPSIS
    Gets information about the Tasks that will be managed by the Broker
 
    .DESCRIPTION
    This function will load the following information into the provided Broker object:
        - The Broker's Task information
        - The Init Task (if present)
        - Information on each of the subject tasks that are to be managed by the Broker
 
    .PARAMETER Broker
    A TMBroker object that has been loaded with TMSession and TMEvent data
 
    .PARAMETER TaskId
    The Id of the Broker task
 
    .EXAMPLE
    Get-TMBrokerTaskData -Broker $Broker -TaskId $ActionRequest.task.id
 
    .OUTPUTS
    None
    #>


    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [TMBroker]$Broker,

        [Parameter(Mandatory = $true, Position = 1)]
        [Int]$TaskId
    )

    if (-not $Broker.EventData) {
        throw "The Broker has not been loaded with Event data. Use either the New-TMBroker command or the Broker's GetEventData() method"
    }

    $Broker.GetTaskData($TaskId)
}


function Get-TMBrokerCache {
    <#
    .SYNOPSIS
    Loads the Broker with a data cache by executing the Init Task
 
    .DESCRIPTION
    This function will populate the Broker's data cache by executing the Init Task (if present)
 
    .PARAMETER Broker
    The TMBroker object that will be updated with cache data
 
    .EXAMPLE
    # Load the cache if there's an init task
    if ($Broker.Init) {
        Get-TMBrokerCache -Broker $Broker
    }
 
    .OUTPUTS
    None
    #>


    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [TMBroker]$Broker
    )


    begin {

    }

    process {
        if (-not $Broker.TMSession) {
            throw "The Broker has not been loaded with a TM Session. Use either the New-TMBroker command or load the Broker's TMSession property"
        }

        if (-not $Broker.EventData) {
            throw "The Broker has not been loaded with Event data. Use either the New-TMBroker command or the Broker's GetEventData() method"
        }

        if (-not $Broker.Task -or -not $Broker.Subjects) {
            throw "The Broker has not been loaded with Task data. Use either the Get-TMBrokerTaskData command or the Broker's GetTaskData() method"
        }

        if (-not $Broker.Init) {
            throw "The Broker has not been loaded with an Init Task. Use either the Get-TMBrokerTaskData command or the Broker's GetInitTask() method"
        }

        ## Run the Init Task
        $Broker.PopulateCache()
    }
}


function Start-TMBroker {
    <#
    .SYNOPSIS
    Runs the Broker to execute the subject tasks in its scope
 
    .DESCRIPTION
    This function will execute the Broker. This will, in turn, execute all of the Subject Tasks in its scope.
 
    .PARAMETER Broker
    The TMBroker object that will be updated with cache data
 
    .EXAMPLE
    # Start the Broker
    Start-TMBroker -Broker $Broker
 
    .OUTPUTS
    None
    #>


    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [TMBroker]$Broker
    )


    begin {

    }

    process {
        if (-not $Broker.TMSession) {
            throw "The Broker has not been loaded with a TM Session. Use either the New-TMBroker command or load the Broker's TMSession property"
        }

        if (-not $Broker.EventData) {
            throw "The Broker has not been loaded with Event data. Use either the New-TMBroker command or the Broker's GetEventData() method"
        }

        if (-not $Broker.Task) {
            throw 'The Broker does not have a task assigned.'
        }
        if (-not $Broker.Subjects -and -not $Broker.ServiceSubjects) {
            throw "The Broker has not been loaded with Task data. Use either the Get-TMBrokerTaskData command or the Broker's GetTaskData() method"
        }

        ## Run the Broker
        $Broker.Run()
    }
}