Public/ConnectedSystems/Import-JIMConnectedSystemHierarchy.ps1

# Copyright (c) Tetron Limited. All rights reserved.
# Licensed under the Tetron Commercial License. See LICENSE file in the project root.

function Import-JIMConnectedSystemHierarchy {
    <#
    .SYNOPSIS
        Imports a Connected System's partitions and containers.
 
    .DESCRIPTION
        Reads a Connected System's partitions and containers into JIM, or refreshes those imported before: on an
        LDAP directory, its naming contexts and organisational units. Choose which to import from with
        Set-JIMConnectedSystemPartition and Set-JIMConnectedSystemContainer.
 
        A refresh keeps your selections. Partitions and containers are matched by the Connected System's own
        immutable identifier where it has one, so one that was renamed or moved keeps its selection. A selected
        partition or container the Connected System no longer reports is removed, and the result's
        HasSelectedItemsRemoved says so.
 
        Removing a partition that Run Profiles target would leave them reading every selected partition, so the
        refresh disables them instead, recording the partition's name, and warns about each one. Enable each again
        with Set-JIMRunProfile -Enabled $true, choosing its partition. With -RunProfileAction Cancel, such a refresh
        applies nothing and reports an error naming the Run Profiles.
 
    .PARAMETER Id
        The ID of the Connected System to import the hierarchy of.
 
    .PARAMETER InputObject
        A Connected System from Get-JIMConnectedSystem, through the pipeline.
 
    .PARAMETER RunProfileAction
        What to do when the refresh would remove a partition that Run Profiles target: Disable applies the refresh and
        disables them, and Cancel applies nothing from the refresh. A refresh that removes no such partition is applied
        either way.
 
    .PARAMETER PassThru
        Returns what the refresh changed.
 
    .OUTPUTS
        With -PassThru, what the refresh added, removed, renamed and moved, and the Run Profiles it disabled;
        otherwise nothing.
 
    .EXAMPLE
        Import-JIMConnectedSystemHierarchy -Id 1
 
        Imports the hierarchy for Connected System with ID 1.
 
    .EXAMPLE
        Import-JIMConnectedSystemHierarchy -Id 1 -PassThru
 
        Imports the hierarchy and returns the updated Connected System.
 
    .EXAMPLE
        Get-JIMConnectedSystem -Id 1 | Import-JIMConnectedSystemHierarchy -PassThru
 
        Imports hierarchy for a Connected System from the pipeline.
 
    .EXAMPLE
        Import-JIMConnectedSystemHierarchy -Id 1 -RunProfileAction Cancel
 
        Refreshes the hierarchy only if no Run Profile targets a partition the refresh would remove. Otherwise nothing
        is changed, and the error names each Run Profile and its partition.
 
    .EXAMPLE
        $system = New-JIMConnectedSystem -Name "AD" -ConnectorDefinitionId 1 -PassThru
        Set-JIMConnectedSystem -Id $system.id -SettingValues @{ ... }
        Import-JIMConnectedSystemSchema -Id $system.id
        Import-JIMConnectedSystemHierarchy -Id $system.id -PassThru
 
        Creates a Connected System, configures it, imports its schema and hierarchy.
 
    .LINK
        Get-JIMConnectedSystem
        Get-JIMConnectedSystemPartition
        Set-JIMConnectedSystemPartition
        Set-JIMConnectedSystemContainer
    #>

    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium', DefaultParameterSetName = 'ById')]
    [OutputType('JIM.HierarchyRefreshResultDto')]
    param(
        [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)]
        [int]$Id,

        [Parameter(Mandatory, ParameterSetName = 'ByInputObject', ValueFromPipeline)]
        [PSCustomObject]$InputObject,

        [ValidateSet('Disable', 'Cancel')]
        [string]$RunProfileAction = 'Disable',

        [switch]$PassThru
    )

    process {
        # Check connection first
        if (-not $script:JIMConnection) {
            Write-Error "You are not connected to JIM. Run Connect-JIM -Url <your JIM URL> to authenticate, then try again."
            return
        }

        $systemId = if ($InputObject) { $InputObject.id } else { $Id }

        if ($PSCmdlet.ShouldProcess("Connected System $systemId", "Import Hierarchy")) {
            Write-Verbose "Importing hierarchy for Connected System: $systemId"

            try {
                $result = Invoke-JIMApi -Endpoint "/api/v1/synchronisation/connected-systems/$systemId/import-hierarchy" -Method 'POST' `
                    -Body @{ runProfileAction = $RunProfileAction }

                Write-Verbose "Hierarchy imported for Connected System: $systemId ($($result.totalPartitions) partitions)"

                # A Run Profile disabled because its partition was removed stops running, Schedules included, so say
                # so whether or not the caller asked for the result.
                foreach ($runProfile in @($result.affectedRunProfiles) | Where-Object { $_.disabled }) {
                    Write-Warning ("Disabled Run Profile '$($runProfile.runProfileName)': the refresh removed partition " +
                        "'$($runProfile.partitionName)', which it targeted. Enable it again with Set-JIMRunProfile -Enabled `$true " +
                        "and -PartitionId or -AllSelectedPartitions.")
                }

                if ($PassThru) {
                    $result
                }
            }
            catch {
                Write-Error "Failed to import hierarchy: $_"
            }
        }
    }
}