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 centrally in the shared scanner cluster database, 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 use their default state (typically off). Defaults for each feature are listed under Currently supported features.

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. Settings configured this way are tracked as managed by PowerShell.
• Portal takes precedence. When a feature has been configured from the Microsoft Purview portal, the portal becomes the source of truth for that feature. PowerShell attempts to change the same feature are skipped with a warning, and the cluster state is left unchanged. Other features in the same -FeatureSettings call 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 for each feature at any time.
• Get always reflects state. Regardless of where a feature was configured, Get-ScannerConfiguration returns the current state and source for every configured feature. 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 for that feature. Supported values for each feature are listed in the Currently supported features table.

Both the feature name and its value are validated before any change is written. If any entry is invalid, the cmdlet terminates with an error and no entries from the hashtable are applied.

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=$true}

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=$true}

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=$true}

Example: Review the current feature state

Get-ScannerConfiguration

For each configured feature, the Features line in the output shows the current state and which surface configured it (PowerShell or the Microsoft Purview portal). For example, with Custom Reporting enabled from PowerShell:

Features            : {CustomReporting: True (Source: PowerShell)}

Features that have never been configured don't appear and use their default state.

Disable a feature

To turn Custom Reporting off, set its value to $false. 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=$false}

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