Modifications in Snippets

In addition to plugins, a snippet can define a list of modifications. The list of modifications can be understood as a recipe describing how the snippet should be applied to the base configuration. Modifications are instructions on how to connect plugins or how to set or change property values.

This enables snippets to be fully self-contained. Modifications are applied automatically when the snippet is imported into the base configuration using the iam config import-snippet CLI command or using the Config Editor.

Modifications in YAML

Modifications are part of a snippet only supported in YAML configuration files of type IamSnippet. If a YAML configuration contains modifications, the schema version must be at least v1.1.

Consider the following example snippet:

Example

schemaVersion: iam.airlock.com/v1.1
type: IamSnippet
metadata:                                  
  iamVersion: '8.6'                        
spec:             
- type: JdbcConnectionPool
  id: myDatabaseConnection
  properties:
    driverClass: org.postgresql.Driver
    url: jdbc:postgresql://host:5432/iamdb
    user: iam
    password: s3cre4t
modifications:                             
- connectPlugin:                           
    source: myDatabaseConnection
    destination: userPersister
    destinationType: DatabaseUserPersister
    property: sqlDataSource

The snippet defines one plugin with ID myDatabaseConnection.
The snippet contains one modification that connects the database plugin (the source) to the plugin with ID userPersister (the destination) after the plugin has been added to the base configuration.
Note the schema version v1.1. It is mandatory for snippets containing modifications. Snippets without modifications may still be on version v1.

Modification Types

IAM supports a list of modification types. While the set of supported operations is powerful, it is not “functionally complete” in that it does not cover all thinkable config manipulations.

The following table lists all supported operations. For a full specification of all modification types with all supported attributes, please refer to the YAML format specification (section Modifications).

Modification Type	Description
Operations connecting plugins:
`connectPlugin`	Connects a plugin to another plugin.
`connectToList`	Inserts a plugin into a plugin list.
`connectToMap`	Inserts a plugin into a plugin map.
Operations on simple properties and lists of simple properties:
`setSimpleProperty`	Sets or changes a simple property value (e.g., string, number, boolean, etc.).
`insertSimpleListElement`	Inserts a simple (e.g., a string or a number) into a list of simple values.
Operations applicable to both simple and plugin-related properties:
`removeProperty`	Removes a property and its value. This works for all property types.
`removeListElement`	Removes an element from a list of plugins or from a list of simple values.

For each operation, the config context and the config environment may be specified.
List operations have optional attributes to specify the position in the list (index, insertBefore, insertAfter). If not specified, the value or plugin is appended.
All modifications may contain a comment attribute.
The type of the manipulated plugin must be specified in the modification (pluginType or destinationType). This is required for IAM to be able to migrate modifications to new IAM versions.
The optional failOnError attribute allows making modifications skippable in that they do not result in an error if they cannot be executed.
For example, if a modification fails because the destination plugin does not exist, it does not result in an error if failOnError: false.
This can make snippets more robust: the same snippet can work with base configurations that include protected self-services as well as those that do not.
Note that not all errors are skippable. Please refer to the YAML format specification for details.

Example 1

The following example is based on the Airlock 2FA examples in Configuration snippets: The modifications it contains do the same as the list of iam config connect commands given in the snippet example.

The list of Airlock 2FA plugins are ommitted to keep it short.

Example

schemaVersion: iam.airlock.com/v1.1
type: IamSnippet
metadata:
  iamVersion: '8.6'
  history:
  - datetime: 2026-02-18T16:20:26.562Z
    author: mbutikof
    comment: Airlock 2FA plugins
spec:
...
List of Airlock 2FA Plugins omitted
...
modifications:
- connectPlugin:
    comment: Connect to main auth settings
    source: airlock2FA-mainSettings
    destination: mainAuthenticationSettings
    destinationType: GlobalAuthenticationSettings
    property: airlock2FASettings
- connectToList:
    comment: Connect A2FA token controller to adminapp user management
    source: airlock2faTokenController
    destination: userMgmtConfig
    destinationType: UsersConfiguration
    property: authenticationTokens
- setSimpleProperty:
    comment: Airlock 2FA Futurae service ID
    plugin: futuraeServerSettings
    pluginType: FuturaeServer
    property: serviceId
    value: "abcd1234-ef56-7890-abcd-1234567890ef"

Example 2

Note that a snippet may consist of only modifications and does not have to contain plugins. This may be used to just apply modifications to a configuration when importing the snippet.

The following example just sets a few deployment-specific values in a configuration:

Example

schemaVersion: iam.airlock.com/v1.1
type: IamSnippet
metadata:
  iamVersion: '8.6'
modifications:
- setSimpleProperty:
    comment: Set OATH OTP password to encrypt shared secret
    plugin: oathOtpSettings
    pluginType: OathOtpSettings
    property: password
    value: "abcdEF12/ghIjKl34MnOpQr56StUvWx78YzABcdEfGhIj"
    failOnError: false
- setSimpleProperty:
    comment: Show OATH OTP QR code in Adminapp
    plugin: adminappAccessControl
    pluginType: RoleBasedAccessControl
    property: viewOathOtpTokenSecret
    value: tokenadmin,superadmin
    failOnError: false

Best practices and limitations

In modifications, plugin IDs, plugin types, and property names are used. While property names are defined by Airlock IAM, the IDs can be chosen arbitrarily. Well-chosen IDs make modifications (and scripts) more readable and easier to maintain.
Automatic config migration of modifications is only possible to a limited extent: While simple changes, such as property name changes or type name changes, are automatically migrated, more complex changes may require manual adaptations to the modifications.
Starting with IAM 8.5, changes to the YAML config schema are documented in the release notes. We aim to keep changes that may make manual changes necessary to a minimum.