PowerShell Connectors
Danger
It is important to note that developing Connectors or Scripts comes with a "Use at Your Own Risk" policy. We would like to emphasize that any such tools, connectors, or scripts that have not been developed directly by Tools4ever are outside the scope of our standard support services. Users are advised to exercise caution and discretion when employing any non-official tools or scripts in conjunction with Tools4ever products.
A PowerShell connector enables seamless integration between NIM and any external system by leveraging PowerShell scripts structured in a well-defined and standardized format. These connectors provide a flexible and extensible approach to facilitate data exchange, automation, and interaction with third-party systems.
To streamline the development process and ensure consistency, we have published example source code on our official GitHub repository.
This repository serves as a comprehensive reference, offering a clear understanding of the required structure, best practices, and implementation guidelines. Developers can use this example as a starting point to create custom connectors tailored to their specific use cases.
For additional support or advanced customization, detailed documentation is available alongside the source code to guide you through setup, deployment, and troubleshooting.
$Log_MaskableKeys
Provide a comma-separated list of attribute names whose values should be masked to ensure sensitive information is not exposed in log files. For example: Password, PIN, ClientSecret
$Log_MaskableKeys = @( # Put a comma-separated list of attribute names here, whose value should be masked before # writing to log files. Examples are: 'Password', 'accountPassword' )
This approach helps maintain compliance with security and privacy standards by obfuscating sensitive data such as passwords, personally identifiable information (PII), or financial details before logging. Masking should replace the actual value with a placeholder (e.g., ****) to prevent unauthorized access to confidential information while retaining the log's usefulness for debugging and monitoring.
Functions
A variety of functions are available to NIM connectors.
Generic Functions
The NIM service provides generic functions that are used across all PowerShell connectors. You can find this by referencing it from a NIM Installation in the file C:\Program Files\Tools4ever\NIM\sysconfig\scripts\Generic.ps1
Idm-SystemInfo
The Idm-SystemInfo function is a mandatory component of the integration framework. Every IDM system is required to implement this function to ensure compatibility and proper operation within the ecosystem.
This function serves as a critical entry point, providing essential system metadata such as:
Connection Settings: Definition of fields for the system connection.
Test Connection: Ability to test the connection to the system without loading all data.
Configuration Settings: Additional configuration fields for the system.
By standardizing the implementation of Idm-SystemInfo, the framework ensures uniformity, making it easier to monitor, manage, and interact with integrated systems. Detailed implementation guidelines and examples are provided in the developer documentation to support adherence to this requirement.
Connection Settings
Various fields can be specified for the connection screen along with specific standard parameters for each. Each connection setting shares the following parameters:
Name
The unique ID of the field (e.g., MyField1).
Type
The type of input field being defined (e.g., Checkbox, Radio, Textbox).
Label
The display name of the field, shown on the connection screen (e.g., My Field).
Tooltip
The text shown to the user when they hover their cursor over the field.
Reserved: nr_of_sessions
This parameter defines the maximum number of concurrent sessions that NIM can establish at any given time. It acts as a limit to control resource usage and optimize performance when interacting with external systems.
@{ name = 'nr_of_sessions' type = 'textbox' label = 'Max. number of simultaneous sessions' value = 5 }
Reserved: session_idle_timeout
This parameter defines the duration (in seconds) for which a session remains open before being automatically closed. It ensures effective session management and resource utilization.
@{ name = 'sessions_idle_timeout' type = 'textbox' label = 'Session cleanup idle time (minutes)' tooltip = '0 disables session cleanup' value = 30 }
Checkbox
@{ name = 'checkbox_item_name' type = 'checkbox' label = 'Display name of checkbox item' tooltip = 'Tooltip of checkbox item' value = $false # Default value of checkbox item }
Checkgroup
@{ name = 'checkgroup_item_name' type = 'checkgroup' label = 'Display name of checkgroup item' tooltip = 'Tooltip of checkgroup item' table = @{ rows = @( @{ id = 'id of checkgroup entry 1'; display_text = 'Display text of checkgroup entry 1' } @{ id = 'id of checkgroup entry 2'; display_text = 'Display text of checkgroup entry 2' } @{ id = 'id of checkgroup entry 3'; display_text = 'Display text of checkgroup entry 3' } ) settings_checkgroup = @{ value_column = 'id' display_column = 'display_text' } } value = @('id of checkgroup entry 1', 'id of checkgroup entry 3') # Default value of checkgroup item }
Combo
@{ name = 'combo_item_name' type = 'combo' label = 'Display name of combo item' tooltip = 'Tooltip of combo item' table = @{ rows = @( @{ id = 'id of combo entry 1'; display_text = 'Display text of combo entry 1' } @{ id = 'id of combo entry 2'; display_text = 'Display text of combo entry 2' } @{ id = 'id of combo entry 3'; display_text = 'Display text of combo entry 3' } ) settings_combo = @{ value_column = 'id' display_column = 'display_text' } } value = 'id of combo entry 2' # Default value of combo item }
Date
@{ name = 'date_item_name' type = 'date' label = 'Display name of date item' tooltip = 'Tooltip of date item' value = Get-Date -Format "yyyy-MM-dd" # Default value of date item }
Grid
@{ name = 'grid_item_name' type = 'grid' label = 'Display name of grid item' tooltip = 'Tooltip of grid item' table = @{ rows = @( @{ column_A = 'Value of cell A1'; column_B = 'Value of cell B1'; column_C = 'Value of cell C1' } @{ column_A = 'Value of cell A2'; column_B = 'Value of cell B2'; column_C = 'Value of cell C2' } ) settings_grid = @{ selection = 'multiple' # Selection capability control; alternative: 'single' (default) key_column = 'column_A' checkbox = $true # Checkbox control filter = $true # Enabled search filter columns = @( @{ name = 'column_A'; display_name = 'Display name of column_A' } @{ name = 'column_B'; display_name = 'Display name of column_B' } @{ name = 'column_C'; display_name = 'Display name of column_C' } ) } } value = @('Value of cell A1') # Default value of grid item }
Radio
@{ name = 'radio_item_name' type = 'radio' label = 'Display name of radio item' tooltip = 'Tooltip of radio item' table = @{ rows = @( @{ id = 'id of radio entry 1'; display_text = 'Display text of radio entry 1' } @{ id = 'id of radio entry 2'; display_text = 'Display text of radio entry 2' } @{ id = 'id of radio entry 3'; display_text = 'Display text of radio entry 3' } ) settings_radio = @{ value_column = 'id' display_column = 'display_text' } } value = 'id of radio entry 2' # Default value of radio item }
Text
@{ name = 'text_item_name' type = 'text' text = 'Displayed static text' }
Textbox
@{ name = 'textbox_item_name' type = 'textbox' label = 'Display name of textbox item' tooltip = 'Tooltip of textbox item' value = 'Default value of textbox item' }
Test Connection
The function must test the connection using the parameters provided in the -ConnectionParams argument. This is a critical step to verify that the connection details are valid and the target system is reachable. On connection failure an exception must be thrown.
Configuration
Similar to the connection settings, you can define additional fields to support custom configurations tailored to your specific integration needs. These fields provide flexibility and extend the configurability of the system.
Idm-OnUnload
The Idm-OnUnload function is optional but provides a valuable mechanism for cleanly managing resources during the unloading of the PowerShell session. This is useful, for example, to close any open sessions to a system.
Class Operations
There are two primary methods for defining tables and operations within the PowerShell connector: static definition and dynamic definition. Each approach offers different advantages depending on the complexity and flexibility required by the integration.
Operation Types
Read
This function collects information from an external system and stores it into a table within the NIM system. It serves as an essential integration point for synchronizing data between systems, ensuring that relevant information is captured and stored in a structured manner for further processing or querying.
Ouput for this operation should be an array of objects or each individual object.
Create
The Create operation allows you to take action within the system by adding a new record into a specific system table. This operation will interact with the target system, gather the necessary data, and insert it into the system’s table to ensure the data is stored properly.
Output for this operation should be a single object with the new values
Update
The Update operation modifies an existing record in a specific system table. This operation allows for changes to be made to existing data within the system, such as updating user details, modifying configurations, or altering status information.
Output for this operation should be a single object with the new values
Delete
The Delete operation is used to remove an existing record from a specific system table. This operation is necessary when records are no longer needed, are invalid, or need to be purged for cleanup purposes.
Output is not required for this operation.
Calls
Each IDM call provides two levels of interactivity. GetMeta and the Operation itself. GetMeta outputs all the information about what data will be returned. This is then used in the table settings to allow the administrator to select properties for the collected table. The operation level defines how the system interacts with the target object(s), specifying whether to Read, Create, Update (Set), or Delete them.
Idm-<Class><Operation>
In the static definition approach, tables and operations are explicitly defined using the function name pattern Idm-<Class><Operation>. This method is more straightforward and is typically used when the operations are known in advance and remain consistent across the integration.
Naming Convention
Each operation is tied to a specific class, and the function name follows the format Idm-<Class><Operation>. For example:
Idm-UserCreate: A function that defines the user creation operation for the User class.
Idm-GroupDelete: A function that defines the group deletion operation for the Group class.
Advantages:
Clarity: Each operation is directly associated with a class and operation type.
Simplicity: Easy to implement and maintain when the set of operations is static and well-defined.
Predictability: Functions are explicitly defined, making the system easier to understand for developers.
Calls
Each IDM call provides two levels of interactivity.
GetMeta
The GetMeta function is a crucial component in the IDM connector that outputs all the metadata information about the class data that can be retrieved from an external system. This function is used to describe the structure of the data and provide a detailed map of the available fields. This information is then leveraged in the table settings to allow the NIM Administrator to selectively choose which fields should be collected from the external system.
Operation
The Operation Function is the core where the actual execution of actions takes place. It defines how specific tasks, such as Read, Create, Update, or Delete, are carried out within the context of the IDM connector and the external system.
Idm-Dispatcher
The Idm-Dispatcher function acts as a central handler that dynamically routes requests to the appropriate operation based on runtime conditions, such as input parameters or configuration. This allows the definition of operations without requiring each one to be explicitly named in advance.
Advantages:
Flexibility: Operations can be defined and invoked dynamically, reducing the need for a static function for every possible operation.
Scalability: Easily extendable to accommodate a large number of operations, especially when operations can be configured or modified at runtime.
Centralized Management: Simplifies the process of managing operations as all logic is contained within a single dispatcher function, which can conditionally call different operations.
Calls
Each IDM call provides two levels of interactivity:
GetMeta
The dispatcher method offers a more flexible, dynamic approach to handling GetMeta operations. Unlike the static method, where metadata retrieval is predefined and rigid, the dispatcher method breaks down the GetMeta process into two separate operations:
Retrieving Classes: Retrieves a list of available classes (system tables).
Retrieving Class Fields: Retrieves the fields for a specific class (the attributes or columns within a table).
This dynamic approach gives NIM Administrators more control over what data is collected and how the system is configured.
Operation
The Operation Function is the core where the actual execution of actions takes place. It defines how specific tasks, such as Read, Create, Update, or Delete, are carried out within the context of the IDM connector and the external system.
Logging
PowerShell connectors provide two methods to log information: Log and LogIO. Both methods allow for flexible logging depending on the operation level and context. These logs help provide insights into the connector’s operation, allowing system administrators to monitor a connector's execution and troubleshoot if necessary.
Log Levels
Both Log and LogIO functions require the Log Level parameter. The specified log level affects how the log is displayed inside the NIM interface.
Info
Provides general information about the operation.
Warn
Used for warnings or situations that might not be errors, but need attention.
Debug
Logs detailed information used for debugging, often showing internal processing or data.
Error
Logs error message, typically for issues that cause the operation to fail.
Method: log
The log method is used for general logging across an entire NIM connector. It captures messages related to the execution of various operations, helping administrators track the flow of actions and potential issues.
Parameters
Level
Type: enum
See log levels for more information.
Message
Type: string
Usage
log info "This is my message." log warn "This is something you should probably look at." log debug "Connecting to $($conectionInfo) at $(get-date)..." log error "Something went terribly wrong."
Output
Logs written with the log method are recorded in the system log. This log is used for general tracking and auditing, helping administrators monitor the overall behavior of the connector across all operations.
Method: logIO
The logIO method is specifically designed to log information during create, update, and delete operations, where data is being modified or changed in a target system. This logging method allows for more granular tracking and visibility within the mapping, job, or scheduler context.
Parameters
Level
Type: enum
See log levels for more information.
Context
Type: string
Note
While you are free to provide any string value for this argument, best practice is to provide a string that indicates the system name and the action that is being performed. E.g., "GoogleWorkspace_UserCreate"
Message
Type: string
Usage
logIO info "MySystem_UserCreate" "A new user was entered into the system." logIO warn "MySystem_UserUpdate" "Field 'Email' is being updated with a new value." logIO debug "MySystem_UserDelete" "User ID 12345 is being deleted from the system." logIO error "MySystem_UserUpdate" "Failed to update 'Email' due to invalid format."
Output
Logs written with the logIO method are specifically intended for create, update, and delete operations. These logs are displayed within the context of a mapping, job, or scheduler, providing insight into the operational flow during data manipulation.