Set-PimLicense
Register the PIM Manager licence
Purpose
Registers an issued PIM Manager licence in the environment's store: it verifies the signed licence document first, stores it as the License setting, reads it back and verifies it again; optionally stores the Invardia install key or queues its claim.
When to run it
When a licence file has been issued (a new Pro licence, a renewal or a replacement) and it cannot be registered in PIM Manager itself (Settings > Licence, SuperAdmin). The licence page shows the two lines -- download this script from Invardia, then run it -- with the environment's server and tenant filled in. The installer runs it for you.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| other | Member of the environment's SQL admin group (grp-pim-sql-admins), signed in through the browser or the Invardia Support app session (no command-line tool, no PowerShell module) | the environment's SQL database | The licence is kept in pim.Settings; only the SQL admin group may write it. With -UseSignedInAccount the person signs in through the browser (the recommended way). Alternatively, for automation, an Azure SQL access token (-SqlAccessToken), the admin application (-AdminAppId with -AdminCertThumbprint), or a ready -ConnectionString to a local SQL Server. |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Environment SQL database | update | pim.Settings row 'License' (the signed licence document exactly as issued) | this environment's PIM Manager and engine | Switches on the features the licence covers. The document is verified BEFORE the store is written (a tampered or foreign-signed document, a non-Pro licence or one not bound to this tenant is refused), then read back and verified again. | Register the previous licence file again (the replaced licence id is printed as 'replaces:'), or remove the License setting to return to Community. | |
| Environment SQL database | create | pim.Settings row 'EditionUpgrade' (only when the environment was Community until now) | this environment | Records the Community-to-Pro conversion so the update ring keeps working until the upgrade step gives the environment its Pro updater. | Remove the EditionUpgrade setting. | |
| Environment SQL database | update | pim.Settings rows 'InvardiaInstallKey' and (with -InstallKeyPath) 'InstallKeyClaimState' -- only with -InstallKey / -InstallKeyPath | this environment | Stores the install key Invardia issued with this installation so the engine does not claim another one. The key is never printed. | Remove the two settings; the engine's install-key job then claims a key again. | |
| Environment SQL database | update | pim.Settings row 'SchedulerTriggers' (adds one 'install-key' run-now entry) -- only with -QueueInstallKeyClaim and no key given | this environment's engine | So the engine claims the install key at its next run (within 5 minutes) instead of up to 6 hours later. | None needed -- the entry is consumed by the next engine run. | |
| Local file (only with -OutFile) | create | the result file named by -OutFile (licence id, status, features; never the install key) | this computer | For a caller that reads the outcome. | Delete the file. |
What it only reads
- the licence file named by -LicensePath (and the key file named by -InstallKeyPath)
- pim.Settings 'License' (what is stored now, to report the licence it replaces; a store that cannot be read is not written)
- pim.Settings 'SchedulerTriggers' (only with -QueueInstallKeyClaim, so an install-key entry is not added twice)
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -LicensePath | no | The issued licence file (.pimlicense / .aitlicense). Its content is imported; the file is not kept. Give this or -LicenseJson. | |
| -LicenseJson | no | The issued licence document as text, instead of -LicensePath. | |
| -ConnectionString | no | A ready connection string to the store (e.g. a local SQL Server) instead of -SqlServer. | |
| -SqlServer | no | The store's server (alias -SqlServerFqdn). An Azure SQL FQDN connects with a token. | |
| -Database | no | PimPlatform | The database (alias -SqlDatabase). |
| -TenantId | no | The tenant id; required for an Azure SQL store. The licence must name this tenant. | |
| -UseSignedInAccount | no | false | Reach the store as the signed-in person: a browser sign-in (a member of the SQL admin group), or the Invardia Support app session open in this window. The recommended way. |
| -SqlAccessToken | no | Automation: an Azure SQL access token the caller already holds; the machine's managed identity is never used. | |
| -AdminAppId | no | Automation: the admin application's client id (with -AdminCertThumbprint or -AdminSecret). | |
| -AdminCertThumbprint | no | Automation: the thumbprint of the admin application's certificate in the local machine store. | |
| -AdminSecret | no | Legacy automation only: a client secret for -AdminAppId. Not for customer use; prefer -UseSignedInAccount. | |
| -InstallKey | no | The install key Invardia issued with this installation (inv-...). Stored, never printed. | |
| -InstallKeyPath | no | The install key in a file (so it is never a command-line argument); the claim state is recorded as 'claimed'. | |
| -QueueInstallKeyClaim | no | false | With no key given: queue the engine's install-key claim for its next run. |
| -RequireMspRole | no | 'Master' or 'Slave' (managing / managed tenant): refuse, before storing, a licence that does not cover MSP for this tenant. | |
| -OutFile | no | Write the outcome as JSON to this file. |
Preview with -WhatIf
Verifies the licence document, reads what is stored now and prints the licence (id, customer, SKU, valid to, features, bound tenants, what it replaces), 'What if: Performing the operation "store the verified licence" on target "pim.Settings['License'] in <server>/<database>"' and 'What if: would store licence <id> ...' (plus the install key or its claim when asked). Nothing is written.
Undo
Register the previous licence file again (its id is printed as 'replaces:'), or remove the License setting to return the environment to Community. Remove InvardiaInstallKey / InstallKeyClaimState to have the engine claim a key again.
Network
It connects to: login.microsoftonline.com (sign-in / token for Azure SQL), <server>.database.windows.net:1433 (or the SQL Server in -ConnectionString)
Download and run
Run these lines in PowerShell: the first downloads the script into the current folder, the second runs it.
Invoke-WebRequest https://invardia.com/support/pim/Set-PimLicense.ps1 -OutFile Set-PimLicense.ps1
.\Set-PimLicense.ps1To check the download first, compare its SHA-256 with the published one:
SHA-256 436ee1d75fd9e5af2df3533e8effcbe6d1b153c3a969b9d1c47d3ed023210daf
Checksums: SHA256SUMS.txt · Version 3.0.70
Before you run it, compare the file's SHA-256 with its line in SHA256SUMS.txt.
Every parameter: Get-Help .\Set-PimLicense.ps1 -Full · Source: Set-PimLicense.ps1
Every script, identity and permission for your security review: PIM Manager