psfdx-core/psfdx-core.psm1
|
function Import-PsfdxSharedModule { [CmdletBinding()] param( [string] $ModuleName = 'psfdx-shared' ) if (Get-Module -Name $ModuleName -ErrorAction SilentlyContinue) { return } $candidates = @() $repoManifest = Join-Path -Path $PSScriptRoot -ChildPath (Join-Path '..' (Join-Path $ModuleName "$ModuleName.psd1")) $candidates += $repoManifest $moduleParent = Split-Path -Path $PSScriptRoot -Parent if ($moduleParent) { $siblingManifest = Join-Path -Path $moduleParent -ChildPath (Join-Path $ModuleName "$ModuleName.psd1") $candidates += $siblingManifest $moduleRoot = Split-Path -Path $moduleParent -Parent if ($moduleRoot) { $sharedBase = Join-Path -Path $moduleRoot -ChildPath $ModuleName if (Test-Path -LiteralPath $sharedBase) { try { $versionDirectories = Get-ChildItem -Path $sharedBase -Directory -ErrorAction Stop | Sort-Object -Property Name -Descending foreach ($dir in $versionDirectories) { $candidates += Join-Path -Path $dir.FullName -ChildPath "$ModuleName.psd1" } } catch { # ignore directory inspection failures } $candidates += Join-Path -Path $sharedBase -ChildPath "$ModuleName.psd1" } } } $available = Get-Module -ListAvailable -Name $ModuleName -ErrorAction SilentlyContinue | Sort-Object -Property Version -Descending foreach ($item in $available) { if ($item.Path) { $candidates += $item.Path } } foreach ($candidate in $candidates | Where-Object { $_ } | Select-Object -Unique) { if (Test-Path -LiteralPath $candidate) { Import-Module -Name $candidate -ErrorAction Stop return } } Import-Module -Name $ModuleName -ErrorAction Stop } Import-PsfdxSharedModule #region Authentication & Orgs function Connect-Salesforce { [CmdletBinding()] Param( [Parameter(Mandatory = $false)][switch] $Sandbox, [Parameter(Mandatory = $false)][string] $CustomUrl, [Parameter(Mandatory = $false)][string] $Alias, [Parameter(Mandatory = $false)][switch] $SetDefault, [Parameter(Mandatory = $false)][switch] $SetDefaultDevHub, [Parameter(Mandatory = $false)][string][ValidateSet('chrome', 'edge', 'firefox')] $Browser, [Parameter(Mandatory = $false)][string] $OAuthClientId ) $command = "sf org login web" if ($Sandbox) { $command += " --instance-url https://test.salesforce.com" } if ($CustomUrl) { $command += " --instance-url $CustomUrl" } if ($Alias) { $command += " --alias $Alias" } if ($SetDefault) { $command += " --set-default" } if ($SetDefaultDevHub) { $command += " --set-default-dev-hub" } if ($Browser) { $command += " --browser $Browser" } if ($OAuthClientId) { $command += " --client-id $OAuthClientId" } $command += " --json" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams Show-SalesforceResult -Result $result } function Connect-SalesforceAuthUrl { [CmdletBinding()] Param( [Parameter(Mandatory = $true)][string] $SfdxUrlFile, [Parameter(Mandatory = $false)][string] $Alias, [Parameter(Mandatory = $false)][switch] $SetDefault, [Parameter(Mandatory = $false)][switch] $SetDefaultDevHub, [Parameter(Mandatory = $false)][switch] $IncludeToken ) if (-not (Test-Path -LiteralPath $SfdxUrlFile)) { throw "File does not exist: $SfdxUrlFile" } $segments = [System.Collections.Generic.List[string]]::new() $segments.Add('sf org login sfdx-url') | Out-Null $segments.Add("--sfdx-url-file `"$SfdxUrlFile`"") | Out-Null if ($Alias) { $segments.Add("--alias $Alias") | Out-Null } if ($SetDefault) { $segments.Add('--set-default') | Out-Null } if ($SetDefaultDevHub) { $segments.Add('--set-default-dev-hub') | Out-Null } $segments.Add('--json') | Out-Null $command = $segments -join ' ' $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams $details = Show-SalesforceResult -Result $result # -IncludeToken only passes through what the CLI returned. Current CLI versions do not # return tokens or auth URLs from 'sf org login sfdx-url --json', so these may be absent. if ($IncludeToken) { return $details } return Remove-SalesforceSensitiveProperty -InputObject $details } function Remove-SalesforceSensitiveProperty { [CmdletBinding()] Param( [Parameter(Mandatory = $false)][AllowNull()] $InputObject ) if ($null -eq $InputObject) { return $InputObject } $sensitiveKeys = @('accessToken', 'refreshToken', 'sfdxAuthUrl', 'password', 'clientSecret', 'privateKey') if ($InputObject -is [System.Collections.IEnumerable] -and -not ($InputObject -is [string])) { return @($InputObject | ForEach-Object { if ($_ -is [psobject] -and -not ($_ -is [string])) { $_ | Select-Object -Property * -ExcludeProperty $sensitiveKeys } else { $_ } }) } if ($InputObject -is [psobject] -and -not ($InputObject -is [string])) { return $InputObject | Select-Object -Property * -ExcludeProperty $sensitiveKeys } return $InputObject } function Disconnect-Salesforce { [CmdletBinding(DefaultParameterSetName = 'TargetOrg')] Param( [Parameter(Mandatory = $true, ParameterSetName = 'All')][switch] $All, [Parameter(Mandatory = $true, ParameterSetName = 'TargetOrg')][string] $TargetOrg, [Parameter(Mandatory = $false)][switch] $NoPrompt ) $command = "sf org logout" if ($PSCmdlet.ParameterSetName -eq 'All') { $command += " --all" } else { $command += " --target-org $TargetOrg" } if ($NoPrompt) { $command += " --no-prompt" } $command += " --json" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams Show-SalesforceResult -Result $result } function Connect-SalesforceJwt { [CmdletBinding()] Param( [Parameter(Mandatory = $true)][string] $ConsumerKey, [Parameter(Mandatory = $true)][string] $TargetOrg, [Parameter(Mandatory = $true)][string] $JwtKeyfile, [Parameter(Mandatory = $false)][switch] $Sandbox, [Parameter(Mandatory = $false)][string] $Alias, [Parameter(Mandatory = $false)][switch] $SetDefault, [Parameter(Mandatory = $false)][switch] $SetDefaultDevHub ) if (-not(Test-Path $JwtKeyfile)) { throw "File does not exist: $JwtKeyfile" } $url = "https://login.salesforce.com" if ($Sandbox) { $url = "https://test.salesforce.com" } $command = "sf org login jwt --client-id $ConsumerKey --username $TargetOrg --jwt-key-file `"$JwtKeyfile`" --instance-url $url" if ($Alias) { $command += " --alias $Alias" } if ($SetDefault) { $command += " --set-default" } if ($SetDefaultDevHub) { $command += " --set-default-dev-hub" } $command += " --json" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams $details = Show-SalesforceResult -Result $result return Remove-SalesforceSensitiveProperty -InputObject $details } function Open-Salesforce { [CmdletBinding()] Param( [Parameter(Mandatory = $false)][string] $TargetOrg, [Parameter(Mandatory = $false)][switch] $UrlOnly, [Parameter(Mandatory = $false)][string][ValidateSet('chrome', 'edge', 'firefox')] $Browser, [Parameter(Mandatory = $false)][string] $BrowserPrivateMode ) $command = "sf org open" if ($PSBoundParameters.ContainsKey('TargetOrg') -and -not [string]::IsNullOrWhiteSpace($TargetOrg)) { $command += " --target-org $TargetOrg" } if ($Browser) { $command += " --browser $Browser" } if ($BrowserPrivateMode) { $command += " --private $BrowserPrivateMode" } if ($UrlOnly) { $command += " --url-only" } $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters Invoke-Salesforce -Command $command @commonParams } function Get-SalesforceConnections { [CmdletBinding()] Param( [Parameter(Mandatory = $false)][switch] $ShowVerboseDetails ) $command = "sf org list" if ($ShowVerboseDetails) { $command += " --verbose" } $command += " --json" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams $details = Show-SalesforceResult -Result $result # Exclude scratch orgs. Older CLI versions return 'nonScratchOrgs'; newer ones may only # return the 'devHubs', 'sandboxes' and 'other' groups. Absent groups are tolerated. $orgs = @() if ($null -ne $details) { if ($null -ne $details.nonScratchOrgs) { $orgs = @($details.nonScratchOrgs) } else { foreach ($group in @('devHubs', 'sandboxes', 'other')) { if ($null -ne $details.$group) { $orgs += @($details.$group) } } } } # Only these fields are returned, so tokens and auth URLs are never passed on. return $orgs | Select-Object orgId, instanceUrl, username, connectedStatus, isDevHub, lastUsed, alias } function Repair-SalesforceConnections { [CmdletBinding()] Param([Parameter(Mandatory = $false)][switch] $NoPrompt) $command = "sf org list --clean" if ($NoPrompt) { $command += " --no-prompt" } $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters Invoke-Salesforce -Command $command @commonParams } #endregion #region Aliases & Limits function Get-SalesforceAlias { [CmdletBinding()] Param() $command = "sf alias list --json" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams return Show-SalesforceResult -Result $result } function Add-SalesforceAlias { [CmdletBinding()] Param( [Parameter(Mandatory = $true)][string] $Alias, [Parameter(Mandatory = $true)][string] $TargetOrg ) $command = "sf alias set $Alias=$TargetOrg" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters Invoke-Salesforce -Command $command @commonParams } function Remove-SalesforceAlias { [CmdletBinding()] Param([Parameter(Mandatory = $true)][string] $Alias) $command = "sf alias unset $Alias" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters Invoke-Salesforce -Command $command @commonParams } #endregion #region Limits & Usage function Get-SalesforceLimits { [CmdletBinding()] Param([Parameter(Mandatory = $false)][string] $TargetOrg) $command = "sf limits api display" if ($PSBoundParameters.ContainsKey('TargetOrg') -and -not [string]::IsNullOrWhiteSpace($TargetOrg)) { $command += " --target-org $TargetOrg" } $command += " --json" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams return Show-SalesforceResult -Result $result } function Get-SalesforceDataStorage { [CmdletBinding()] Param([Parameter(Mandatory = $false)][string] $TargetOrg) $values = Get-SalesforceLimits -TargetOrg $TargetOrg | Where-Object Name -eq "DataStorageMB" if ($null -eq $values) { Write-Verbose "No DataStorageMB limit reported for this org" return $null } $inUse = $values.max + ($values.remaining * -1) $values | Add-Member -NotePropertyName InUse -NotePropertyValue $inUse $values | Add-Member -NotePropertyName Usage -NotePropertyValue (Get-SalesforceUsagePercentage -InUse $inUse -Max $values.max) return $values } function Get-SalesforceApiUsage { [CmdletBinding()] Param([Parameter(Mandatory = $false)][string] $TargetOrg) $values = Get-SalesforceLimits -TargetOrg $TargetOrg | Where-Object Name -eq "DailyApiRequests" if ($null -eq $values) { Write-Verbose "No DailyApiRequests limit reported for this org" return $null } $inUse = $values.max + ($values.remaining * -1) $values | Add-Member -NotePropertyName Usage -NotePropertyValue (Get-SalesforceUsagePercentage -InUse $inUse -Max $values.max) return $values } function Get-SalesforceUsagePercentage { [CmdletBinding()] Param( [Parameter(Mandatory = $true)][AllowNull()][System.Nullable[double]] $InUse, [Parameter(Mandatory = $true)][AllowNull()][System.Nullable[double]] $Max ) if ((-not $Max) -or ($Max -eq 0)) { return $null } return ($InUse / $Max).ToString('P') } #endregion #region Data Management function Select-SalesforceRecords { [CmdletBinding()] Param( [Parameter(Mandatory = $false)][string] $Query, [Parameter(Mandatory = $false)][string] $File, [Parameter(Mandatory = $false)][string] $TargetOrg, [Parameter(Mandatory = $false)][switch] $UseToolingApi, [Parameter(Mandatory = $false)][switch] $IncludeDeletedRows, [Parameter(Mandatory = $false)][string][ValidateSet('human', 'json', 'csv')] $ResultFormat = 'json', [Parameter(Mandatory = $false)][string] $OutputFile ) $command = "sf data query" if ($Query) { $command += " --query `"$Query`"" } if ($File) { $command += " --file `"$File`"" } if ($PSBoundParameters.ContainsKey('TargetOrg') -and -not [string]::IsNullOrWhiteSpace($TargetOrg)) { $trimmedTargetOrg = $TargetOrg.Trim() if (-not [string]::IsNullOrWhiteSpace($trimmedTargetOrg)) { $command += " --target-org $trimmedTargetOrg" } } if ($UseToolingApi) { $command += " --use-tooling-api" } if ($IncludeDeletedRows) { $command += " --all-rows" } $command += " --result-format $ResultFormat" if ($OutputFile) { $command += " --output-file $OutputFile" } $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams # csv and human output are not JSON, so hand them back untouched if ($ResultFormat -ne 'json') { return $result } $result = $result | ConvertFrom-Json if ($result.status -ne 0) { Write-Debug ($result | ConvertTo-Json -Depth 10) throw $result.message } # Exclude Salesforce's built-in 'attributes' metadata from each row return ($result.result.records | Select-Object -ExcludeProperty attributes) } function Get-SalesforceUsers { [CmdletBinding()] Param( [Parameter(Mandatory = $false)][string] $Username, [Parameter(Mandatory = $false)][switch] $ActiveOnly, [Parameter(Mandatory = $false)][int] $Limit = 200, [Parameter(Mandatory = $false)][string] $TargetOrg ) $fields = 'Id, Name, Username, Email, IsActive, LastLoginDate' $query = "SELECT $fields FROM User" $filters = @() if ($ActiveOnly) { $filters += 'IsActive = true' } if ($Username) { $filters += ('Username = ' + (ConvertTo-SalesforceSoqlLiteral -Value $Username)) } if ($filters.Count -gt 0) { $query += ' WHERE ' + ($filters -join ' AND ') } $query += ' ORDER BY LastLoginDate DESC' $query += " LIMIT $Limit" return Select-SalesforceRecords -Query $query -TargetOrg $TargetOrg -ResultFormat json } function New-SalesforceRecord { [CmdletBinding()] Param( [Parameter(Mandatory = $true)][string] $Type, [Parameter(Mandatory = $true)][string] $FieldUpdates, [Parameter(Mandatory = $false)][string] $TargetOrg, [Parameter(Mandatory = $false)][switch] $UseToolingApi ) Write-Verbose $FieldUpdates $command = "sf data create record" $command += " --sobject $Type" $command += " --values `"$FieldUpdates`"" if ($UseToolingApi) { $command += " --use-tooling-api" } if ($PSBoundParameters.ContainsKey('TargetOrg') -and -not [string]::IsNullOrWhiteSpace($TargetOrg)) { $command += " --target-org $TargetOrg" } $command += " --json" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams return Show-SalesforceResult -Result $result } function Set-SalesforceRecord { [CmdletBinding()] Param( [Parameter(Mandatory = $true)][string] $Id, [Parameter(Mandatory = $true)][string] $Type, [Parameter(Mandatory = $true)][string] $FieldUpdates, [Parameter(Mandatory = $false)][string] $TargetOrg, [Parameter(Mandatory = $false)][switch] $UseToolingApi ) Write-Verbose $FieldUpdates $command = "sf data update record" $command += " --sobject $Type" $command += " --record-id $Id" $command += " --values `"$FieldUpdates`"" if ($UseToolingApi) { $command += " --use-tooling-api" } if ($PSBoundParameters.ContainsKey('TargetOrg') -and -not [string]::IsNullOrWhiteSpace($TargetOrg)) { $command += " --target-org $TargetOrg" } $command += " --json" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams return Show-SalesforceResult -Result $result } function Get-SalesforceRecordType { [CmdletBinding()] Param( [Parameter(Mandatory = $true)][string] $ObjectType, [Parameter(Mandatory = $false)][string] $TargetOrg ) $query = "SELECT Id, SobjectType, Name, DeveloperName, IsActive" $query += " FROM RecordType" if ($ObjectType) { $query += (' WHERE SobjectType = ' + (ConvertTo-SalesforceSoqlLiteral -Value $ObjectType)) } return Select-SalesforceRecords -Query $query -TargetOrg $TargetOrg } #endregion #region Salesforce REST API function Connect-SalesforceApi { [CmdletBinding()] Param( [Parameter(Mandatory = $true)][string] $TargetOrg, [Parameter(Mandatory = $true)][string] $Password, [Parameter(Mandatory = $true)][string] $Token, [Parameter(Mandatory = $true)][string] $ClientId, [Parameter(Mandatory = $true)][string] $ClientSecret, [Parameter(Mandatory = $false)][switch] $Sandbox, [Parameter(Mandatory = $false)][string] $CustomUrl ) $loginUrl = "https://login.salesforce.com/services/oauth2/token" if ($Sandbox) { $loginUrl = "https://test.salesforce.com/services/oauth2/token" } if ($CustomUrl) { $loginUrl = "$CustomUrl/services/oauth2/token" } return Invoke-RestMethod -Uri $loginUrl ` -Method Post ` -Body @{ grant_type = "password" client_id = "$ClientId" client_secret = "$ClientSecret" username = "$TargetOrg" password = ($Password + $Token) } } function Invoke-SalesforceApi { [CmdletBinding()] Param( [Parameter(Mandatory = $true)][string] $Url, [Parameter(Mandatory = $true)][string] $AccessToken, [Parameter(Mandatory = $false)][string][ValidateSet('GET', 'POST', 'PATCH', 'DELETE')] $Method = "GET" ) return Invoke-RestMethod -Uri $Url -Method $Method -Headers @{Authorization = "Bearer " + $AccessToken } } function Get-SalesforceApiVersions { [CmdletBinding()] Param( [Parameter(Mandatory = $false)][string] $TargetOrg ) $command = "sf api request rest /services/data" if ($PSBoundParameters.ContainsKey('TargetOrg') -and -not [string]::IsNullOrWhiteSpace($TargetOrg)) { $command += " --target-org $TargetOrg" } $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters $result = Invoke-Salesforce -Command $command @commonParams return $result | ConvertFrom-Json } function Get-SalesforceLatestApiVersion { [CmdletBinding()] Param( [Parameter(Mandatory = $false)][string] $TargetOrg ) $versions = Get-SalesforceApiVersions -TargetOrg $TargetOrg if (-not $versions -or (@($versions).Count -eq 0)) { return $null } # Sort numerically: a string sort ranks '99.0' above '100.0' $latest = @($versions) | Where-Object { $_.version } | Sort-Object -Property { [double] $_.version } -Descending | Select-Object -First 1 if (-not $latest) { return $null } return "v$($latest.version)" } #endregion #region Plugins function Test-SalesforceIsMacOS { [CmdletBinding()] Param() return [System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform([System.Runtime.InteropServices.OSPlatform]::OSX) } function Install-SalesforceCli { [CmdletBinding()] Param() $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters # npm is the Salesforce-supported install on Windows, Linux and macOS Invoke-Salesforce -Command "npm install --global @salesforce/cli" @commonParams } function Update-SalesforceCli { [CmdletBinding()] Param() $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters Invoke-Salesforce -Command "npm update --global @salesforce/cli" @commonParams } function Install-SalesforcePlugin { [CmdletBinding()] Param( [Parameter(Mandatory = $true)][string] $Name ) $command = "sf plugins install $Name" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters Invoke-Salesforce -Command $command @commonParams } function Get-SalesforcePlugins { [CmdletBinding()] Param( [Parameter(Mandatory = $false)][switch] $IncludeCore ) $command = "sf plugins" if ($IncludeCore) { $command += " --core" } $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters Invoke-Salesforce -Command $command @commonParams } function Update-SalesforcePlugins { [CmdletBinding()] Param() $command = "sf plugins update" $commonParams = Get-PsfdxCommonParameterSplat -BoundParameters $PSBoundParameters Invoke-Salesforce -Command $command @commonParams } #endregion #region Utilities function Get-SalesforceDateTime { [CmdletBinding()] Param([Parameter(Mandatory = $false)][datetime] $Datetime) if ($null -eq $Datetime) { $Datetime = Get-Date } return ConvertTo-SalesforceSoqlDateTime -Value $Datetime } #endregion |