Import-PimSettings
Apply a settings document to a PIM Manager environment (settings as code)
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Purpose
Applies a settings document (written by Export-PimSettings.ps1, or kept in source control) to a named PIM Manager environment's store: it shows the plan per setting (add / change / same), backs up what it would replace, and only with -Apply writes each setting and reads it back. A second -Apply changes nothing.
When to run it
When an environment should be set to settings kept as code -- a new environment baselined from a known-good one, or a reviewed change to settings applied by an operator or a pipeline. A document that carries a secret, or a setting that names an environment itself (who may use it, approvers, break-glass accounts, demo mode, environment name, licence and install keys, rings, the scenario, runtime state), is refused as a whole; so is a document from a newer format version.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| other | Store writer (application with a certificate, member of the target SQL admin group) | the target environment's SQL database (pim.Settings) | Reads the target's current values and, with -Apply, writes the document's values. Given with -ClientId / -CertThumbprint; the certificate must be in the local machine certificate store. |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Target environment SQL database | update | pim.Settings row for each setting of the document that is added or changed (one JSON document per setting) | the target environment only | The point of the script: the target gets the document's value (with -MergeKeys, the document's top-level keys plus the keys only the target has). Settings the document does not name are not touched; nothing is deleted. | Import the TARGET-BEFORE backup file the run wrote (Import-PimSettings.ps1 -Path <backup> -Apply); a setting the import added is listed in it as addedByImport. | |
| Local temp folder | create | TARGET-BEFORE-<time>.settings.json in -BackupDir (default: <temp>\pim-settings-import) | this computer | The target's values before any change, as a settings document, so they can be restored; taken on every run that would change something, also a plan run. | Delete the backup file. |
What it only reads
- the settings document at -Path
- pim.Settings in the target store (the document's settings and the environment name, before and after the write)
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -Path | yes | The settings document (.json) to apply. | |
| -Name | no | Apply only these settings of the document. Default: all of them. | |
| -Server | yes | The target store's SQL server (FQDN). | |
| -Database | no | PimPlatform | The target database. |
| -TenantId | yes | The target tenant id. | |
| -ClientId | yes | Application (client) id of the identity that writes the target store. | |
| -CertThumbprint | yes | Thumbprint of that identity's certificate in the local machine store. | |
| -EnvironmentName | no | The target environment's name; when given, a store with a different environment name is refused. | |
| -BackupDir | no | <temp>\pim-settings-import | Where the target's current values are written before anything changes. |
| -MergeKeys | no | false | For an object setting: keep the top-level keys only the target has (the document's keys win). Arrays and plain values are replaced whole. |
| -Apply | no | false | Write. Without it the script only shows the plan. |
Preview with -WhatIf
Reads the document and the target store, prints the plan (add / change / same per setting) and 'What if: Performing the operation "<add|change> from the settings document" on target "pim.Settings['<Name>'] in <server>/<database> (tenant <id>)"'. Nothing is written to the store; a backup in the temp folder is still taken, a backup elsewhere is only announced.
Undo
Import the TARGET-BEFORE backup file with -Apply (it restores the values that were replaced). The local backup can be deleted.
Network
It connects to: login.microsoftonline.com (tokens for Azure SQL, certificate sign-in), <target server>.database.windows.net:1433
How it runs
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Release 3.0.70
Every script, identity and permission for your security review: PIM Manager