NCache Event Hooks

NCache event hooks let administrators attach a PowerShell script to specific NCache lifecycle events. When one of these events occurs (for instance, start/stop service, start/stop cache, etc.), NCache automatically invokes the configured script and passes contextual information (cache name, node IP, client info, etc.) as parameters, allowing the script to perform custom actions based on the event.

NCache uses this capability internally to maintain cluster health in dynamic environments such as Kubernetes and other cloud platforms, where server nodes and clients are frequently added or removed. It also helps keep external systems, such as load balancers, DNS, service registries, and monitoring tools synchronized with the current state of the cluster.

Note

This file (post-actions.ncconf) is installed with NCache and is located at %NCHOME%\config in Windows and /opt/ncache/config in Linux.

How NCache Event Hooks Work

• An event occurs (e.g., a new cache is created, a node joins the cluster).
• NCache checks whether a script is enabled and configured for that event.
• If so, NCache invokes the script and passes a JSON object describing the event, plus any user-defined extra arguments.
• The script runs with full control to perform whatever automation the user has written, e.g., update a registry, warm up a cache, clean up resources, send an alert, write an audit log, etc.

Supported Events

NCache provides 10 predefined operations that can trigger a script. Before NCache invokes a script for any operation, you must explicitly enable the operation and specify the path to the script.

Important

No cache-lifecycle event is fired until the cache is completely started.

Event	Triggered When
start-service	NCache service starts on a node.
stop-service	NCache service stops on a node.
start-cache	A cache is started on a node.
stop-cache	A cache is stopped on a node.
create-cache	A new cache is created.
remove-cache	A cache is removed.
add-node	A server node joins the cluster.
remove-node	A server node leaves the cluster.
add-client-node	A client connects to the cache.
remove-client-node	A client disconnects from the cache.

Important

start-service and stop-service do not carry any cache-related information, because they fire at the service level, before any cache-specific context exists. Their payload is limited to timestamp and event type.

Script Location and Access Requirements

NCache executes the configured script, so the script must be accessible from the machine where the NCache service is running.

• The script path must point to a location NCache can discover and access.
• The OS user account that the NCache service runs under must have sufficient permissions to read and execute the script.

Important

If NCache cannot locate the script, or lacks permission to invoke it, this is treated as a failure and is logged in the NCache service logs (%NCHOME%\log-files\ServiceLogs) for troubleshooting.

Invocation and Parameters

When an enabled event fires, NCache invokes the script and always passes one fixed argument first, followed by any user-defined arguments:

• Argument 1 (always present): A JSON object, generated by NCache, describing the event, for example, which action occurred, which cache was involved, its topology, and information about the relevant cache node(s).
• Argument 2 or more (optional, user-defined): Any additional arguments configured in the <arguments value="..." /> element of the action block (e.g., -Force). These are appended after the JSON object, in the order configured for the sample below.

<action name="stop-cache" enabled="true">
    <process type="ps1" path="C:\Scripts\StopCacheNotification.ps1" />
    <arguments value="C:\Scripts\MailSettings.json" />
</action>

Note

Only PowerShell scripts (.ps1) are supported as the process type.

Script execution is asynchronous with respect to the NCache operation. NCache does not enforce a timeout, wait for the script to finish, or check its exit code. This fire-and-forget design ensures that slow or unresponsive scripts do not block or delay NCache operations or impact cluster performance.

Sample Script (stop-cache)

This example demonstrates the monitoring and alerting use case, sending an email notification whenever a cache stops. For the event stop-cache, first you need to enable the event stop-cache as true in the post-actions.ncconf file

<action name="stop-cache" enabled="true">
    <process type="ps1" path="C:\Scripts\StopCacheNotification.ps1" />
    <arguments value="C:\Scripts\MailSettings.json" />
</action>

The path attribute specifies the PowerShell script that NCache invokes when the stop-cache event occurs. The arguments attribute passes the path to a JSON configuration file containing the SMTP settings. NCache automatically passes its JSON event payload as the first argument, followed by the configured file path as the second argument.

The script defines two parameters that map directly to the arguments provided by NCache:

• $NCacheEventJson receives the JSON event payload passed as the first argument.
• $ConfigFile receives the path to MailSettings.json passed through the <arguments value="..." /> configuration.

param(
    [Parameter(Mandatory = $true, Position = 0)]
    [string]$NCacheEventJson,

    [Parameter(Mandatory = $false, Position = 1)]
    [string]$ConfigFile
)

if (-not (Test-Path $ConfigFile)) {
    throw "Config file not found: $ConfigFile"
}

$event  = $NCacheEventJson | ConvertFrom-Json
$config = Get-Content $ConfigFile -Raw | ConvertFrom-Json

$credential = New-Object System.Management.Automation.PSCredential(
    $config.Username,
    (ConvertTo-SecureString $config.Password -AsPlainText -Force)
)

$nodes = $event.Nodes -join ", "

Send-MailMessage `
    -SmtpServer $config.SmtpServer `
    -Port $config.Port `
    -UseSsl:([bool]$config.UseSsl) `
    -Credential $credential `
    -From $config.From `
    -To $config.To `
    -Subject "[NCache] Cache '$($event.CacheName)' stopped" `
    -Body "Cache '$($event.CacheName)' stopped on node(s): $nodes at $($event.Timestamp)."

The script then:

• Parses the JSON event payload into $event and loads the mail configuration from $ConfigFile into $config.
• Creates a PSCredential object using the username and password from the configuration file.
• Combines the affected cache nodes into a comma-separated list.
• Sends an email notification using Send-MailMessage, populating the subject and body with the cache name, node list, and event timestamp.

Storing the SMTP settings in a separate configuration file keeps the script reusable across environments. To use different mail settings, simply update the path specified in <arguments value="..." /> without modifying the script itself.

Script Failure Behavior

If the script fails, throws an exception, or hangs, this has no effect on the underlying NCache operation:

• The triggering operation (e.g., cache creation, node join) always completes, i.e., script failure never blocks or rolls it back.
• The event is fired exactly once. NCache makes a single invocation attempt per occurrence, with no automatic retry.
• Any exceptions or errors from script invocation are logged (NCache service logs), so failures are discoverable even though they don't interrupt cluster operation.

Use Cases

The following table lists common scenarios where you can use event hooks to automate administrative tasks and sync NCache with your environment:

Use Case	How the Hook Is Used
Cloud and Kubernetes Sync	On add-node or remove-node, a script notifies the cloud provider (Azure/AWS) or an orchestrator so external infrastructure state stays in sync with the cluster.
Automatic DNS Updates	On add-node, the script receives the new node's IP from the JSON payload and updates DNS records or a service registry automatically, removing the need for manual DNS configuration when a node comes up.
Cache preload	On start-cache, the script preloads data into the cache immediately after it becomes available.
Resource Cleanup	On remove-node or remove-cache, the script automatically deletes temporary files, cleans up configurations, or stops leftover processes.
Monitoring and Alerts	On stop-cache (or other lifecycle events), the script raises an alert or notification so monitoring systems know a cache/node changed state.
Auditing and Logging	Any event can log event details to an external audit trail for tracking cluster activity.

See Also

Cache Settings
Post Actions Config