Powershell Connectors
Developer guide
Use PowerShell to integrate NIM with systems that have a PowerShell module, SDK, command-line interface, or custom automation surface.
Custom connectors and scripts are used at your own risk. Validate them in a non-production environment before deployment. Tools4ever support covers connectors developed by Tools4ever.
When to use a PowerShell connectorDirect link to When to use a PowerShell connector
Choose a PowerShell connector when the target system is best accessed with PowerShell rather than a REST API—for example, through a vendor module, Windows management interface, or existing automation script.
Start with the PowerShell connector example. Treat it as the scaffold: preserve NIM's required functions, then replace the example connection and operation logic with the target system's implementation.
Build in this orderDirect link to Build in this order
- Define connection settings in
Idm-SystemInfo. - Implement and test the connection with the values passed through
-ConnectionParams. - Define a table's metadata so NIM knows which resources can be collected and mapped.
- Implement Read, then test collection with representative data.
- Add Create, Update, and Delete only when the target API, authorization, and rollback behavior are understood.
- Mask secrets and clean up sessions before releasing the connector.
Required framework functionsDirect link to Required framework functions
Idm-SystemInfoDirect link to idm-systeminfo
Every PowerShell connector must implement Idm-SystemInfo. It describes the connector to NIM, including connection settings, test-connection behavior, and optional system configuration.
Your test-connection implementation must use the supplied -ConnectionParams and throw an exception if the target cannot be reached or authenticated.
Table operationsDirect link to Table operations
NIM calls two layers for each table operation:
| Layer | Purpose |
|---|---|
GetMeta | Describes the resources available for a table so administrators can select collection columns. |
| Operation | Reads, creates, updates, or deletes records in the target system. |
For static connectors, use the naming pattern Idm-<Class><Operation>, such as Idm-UserCreate or Idm-GroupDelete. Use Idm-Dispatcher when operations must be selected dynamically at runtime; keep that routing logic explicit and testable.
Operation contractDirect link to Operation contract
| Operation | Expected result |
|---|---|
| Read | An array of objects, or individual output objects, for collection. |
| Create | One object representing the newly created record. |
| Update | One object representing the updated record. |
| Delete | No output is required. Throw on failure. |
Start every new table with metadata and Read. Do not expose writes just because a module supports them—limit write behavior to approved business actions.
Connection controlsDirect link to Connection controls
Each connection item has a stable name, a type, a user-facing label, and optional tooltip and value. NIM supports controls such as textbox, checkbox, radio, combo, checkgroup, date, grid, and static text.
@{
name = 'nr_of_sessions'
type = 'textbox'
label = 'Max. number of simultaneous sessions'
value = 5
}
Two reserved session settings are useful for connectors that hold target-system sessions:
| Setting | Purpose |
|---|---|
nr_of_sessions | Limits simultaneous target-system sessions. |
sessions_idle_timeout | Closes idle sessions after the selected number of minutes; 0 disables cleanup. |
Security and lifecycleDirect link to Security and lifecycle
Mask secrets in logsDirect link to Mask secrets in logs
Declare sensitive attribute names in $Log_MaskableKeys so connector logging does not expose passwords, tokens, PINs, or client secrets.
$Log_MaskableKeys = @('Password', 'ClientSecret', 'accountPassword')
Release resourcesDirect link to Release resources
Implement optional Idm-OnUnload to close sessions, dispose connections, and remove temporary resources when NIM unloads the PowerShell session.
Development checklistDirect link to Development checklist
- Test connections with invalid as well as valid credentials.
- Keep metadata and operation output consistent.
- Test Read with empty, typical, and large result sets.
- Verify every write with disposable records before production use.
- Log useful context, but mask secrets and personal data.
- Keep connection-field names and output resource names stable after mappings depend on them.