Scanner feature control (preview)

This article describes how scanner administrators can enable, disable, and configure supported Microsoft Purview Information Protection scanner features at the cluster level by using PowerShell.

Admin-controlled feature configuration is available with Microsoft Purview Information Protection client and scanner version 3.2.89.0 or later.

How feature control works

Scanner features are configured once per scanner cluster. The settings are stored in a dedicated dbo.Features table in the shared scanner cluster database. Every node in the cluster reads from the same table, which means:

• An administrator runs a configuration cmdlet once from any node in the cluster, and all nodes pick up the change on the next scan cycle.
• No service restart is required.
• Nodes can't get into mismatched feature states.
• Disabling a feature stops the action that the feature performs (for example, writing to a new database table or producing a new file). Existing data isn't deleted, so the feature can be re-enabled later without data loss.
• Features that aren't explicitly configured don't have a row in the dbo.Features table and use the code default (typically Off). Rows are added only when an administrator explicitly sets a feature.

Each row in dbo.Features records the feature Name, the Setting (a string such as On or Off), and the Source that wrote the value (PowerShell or Portal).

Custom Reporting is the first feature delivered through admin-controlled feature configuration. For details about that feature, see Custom Reporting (preview).

Evolution of control: PowerShell and the Microsoft Purview portal

Admin-controlled feature configuration is designed to evolve over time. Today, supported features are configured by using PowerShell. As features become available in the Microsoft Purview portal, the portal becomes the source of truth for those features.

The following rules apply when both surfaces are available for a feature:

• PowerShell first. Until a feature is exposed in the Microsoft Purview portal, administrators configure it from PowerShell on any node in the cluster. Each PowerShell write sets the row's Source column to PowerShell.
• Portal takes precedence. When a feature has been configured from the Microsoft Purview portal, its row in dbo.Features carries Source = 'Portal'. The next time an administrator runs Set-ScannerConfiguration -FeatureSettings for that same feature, the cmdlet emits a warning of the form "Feature '<name>' is managed by the Purview portal and cannot be changed via PowerShell. Skipping." and leaves the cluster state unchanged. Other features in the same -FeatureSettings hashtable that aren't portal-managed are still applied.
• No synchronization. Settings aren't synchronized between PowerShell and the portal. Not every scanner feature will end up being configurable from the portal. When a feature is available in the portal and has been configured there, that portal-configured setting takes precedence and prevents updates from PowerShell. There's a single source of truth (the row in dbo.Features) at any time.
• Get always reflects state. Regardless of where a feature was configured, Get-ScannerConfiguration returns the current state of every configured feature, including the Setting and Source values. Administrators can audit the cluster from PowerShell at any time.

This model means scanner administrators can adopt new features through PowerShell as soon as they reach public preview, and switch to portal-based management at their own pace as features become available there.

Supported cmdlets and the -FeatureSettings parameter

The following cmdlets accept the -FeatureSettings parameter:

-FeatureSettings accepts a PowerShell hashtable of feature name and setting pairs, using the same pattern as -AdvancedSettings:

• The hashtable key is the feature Name (for example, CustomReporting).
• The hashtable value is the Setting and is stored as-is in the database Setting column (VARCHAR(MAX)). For Custom Reporting, the supported values are "On" and "Off".

Feature names are validated against the scanner's list of supported features before any change is written. An unknown feature name causes the cmdlet to terminate with an error that lists the supported features; no entries from the hashtable are applied in that call.

For background on the -AdvancedSettings pattern, including PowerShell quoting and hashtable tips, see PowerShell tips for specifying the advanced settings and the -AdvancedSettings parameter on Set-Label.

Example: Enable Custom Reporting on an existing cluster

Run the following from any node in the scanner cluster:

Set-ScannerConfiguration -FeatureSettings @{CustomReporting="On"}

All nodes in the cluster pick up the change on their next scan cycle.

Example: Enable Custom Reporting at install time

Install-Scanner -SqlServerInstance SQLSERVER1 -Cluster Europe -FeatureSettings @{CustomReporting="On"}

Example: Configure feature settings in one call

Use the FeatureSettings hashtable to pass feature names and values. Currently, this page documents only CustomReporting:

Set-ScannerConfiguration -FeatureSettings @{CustomReporting="On"}

Example: Review the current feature state

$cfg = Get-ScannerConfiguration
$cfg.Features                       # hashtable of all configured features
$cfg.Features.CustomReporting       # @{Source=PowerShell; Setting=On}

The Features property is a hashtable. Default list-view rendering inlines it as {[<feature>, @{Source=<source>; Setting=<setting>}]}. Each value exposes the current Setting and the Source (PowerShell or Portal) that wrote it. Features that have never been configured don't appear and take their code default.

Disable a feature

Set the value to "Off". Existing data that the feature wrote isn't deleted; the scanner stops performing the feature's action on the next scan cycle.

Set-ScannerConfiguration -FeatureSettings @{CustomReporting="Off"}

Currently supported features

Additional features will be added over time and listed in the release notes.

See also

• Custom Reporting (preview)
• Configure and install the Microsoft Purview Information Protection scanner
• Microsoft Purview Information Protection client release notes
• Install-Scanner
• Set-ScannerConfiguration
• Get-ScannerConfiguration