Named Pipes for Custom Connector

Overview

This diagram illustrates the flow of messages between the Custom Connector and the Launcher using Named Pipes:

Pipe Channel Characteristics

• Bidirectional: Both the Launcher and the Connector can send and receive messages.

• Isolated: Each pipe is unique per user session.

• Fast and reliable: Memory-based transport ensures efficient data exchange.

• Schema-driven: Messages use JSON for consistency and validation.

Benefits of Named Pipes

Prerequisites

• Windows environment

• A Launcher version that supports Named Pipes

• Custom Connector configured to leverage a data pipe

How Named Pipes Work

• Named Pipes are automatically created when a Custom Connector process starts.

• The Launcher stores the pipe name in an environment variable that’s available to the entire user session, not to a specific process. Any process running in that session can use the pipe name if it has access to it, so the connection works on a first-come, first-served basis. After the connection is established, the two endpoints remain fixed and can’t be changed.

• Messages transmitted through the pipe are structured (JSON) and handled internally by the Launcher.

• No command-line arguments are required, reducing exposure of sensitive information.

Custom Events and Session Information

Custom Connectors can send custom events to the Launcher via Named Pipes. These events allow the Launcher to track the state of a user session or report informational updates from the Connector.

Key points:

• Events are informational and generally do not require action.

• Custom Connectors can report errors or session drops immediately without waiting for the Launcher or the Engine.

• Events are tied to the user session, allowing you to trace which account, test, or attempt raised each event.

SDK Support

A Custom Connector can implement Named Pipe communication manually or use the CustomConnector SDK included with the Launcher.

• The SDK is provided as a DLL in the extracted Launcher package.

• It exposes methods for sending Launcher events directly, without requiring custom pipe-handling code.

• The SDK can be used from PowerShell, C#, or other languages that can load the DLL.

For more information, see the Custom Connector SDK (Named Pipe).

From the Launcher Perspective (Named Pipe)

When Starting a New Session

When the Launcher starts a new session, it performs the following actions:

1. Starts SessionTracker (if configured) and PipeServer

2. Adds the PipeName to the environment variables of the connector process (environment variable name: VSI_IPC_PIPE_NAME)

3. Starts the custom connector process

The Launcher also starts background threads to manage the communication channel:

• SessionTracker thread starts looking for the session window

• Another thread waits until the client connects to the pipe

  • When the client connects, it sends ConnectionConfiguration to the client

• PipeServer thread waits for messages from the connector

When an Event Message is Received from the Connector Process

When the Launcher receives an event message from the connector process, it processes it based on the event type.

When the Custom Connector Doesn't Use the Pipe

Using the pipe is optional. If the custom connector doesn’t interact with the pipe, the workflow continues to operate as it does.

• If SessionTracker is configured, the Launcher still attempts to track the session window using the existing mechanism.

• If the Launcher can’t track the window, it falls back to the legacy behavior:

  • The Launcher waits for the configured timeout after the session ends.

  • The Launcher then sends the “connection closed” signal to the Appliance.

This ensures backward compatibility and prevents breaking existing custom connector implementations.

From the Connector Perspective (Named Pipe)

When the Launcher Starts the Connector Process

It adds PipeName to the connector’s environment variables.

When the Custom Connector Starts

It should:

• Read the pipe name from the VSI_IPC_PIPE_NAME environment variable.

• Connect to the named pipe.

• (Optional) Read the connection configuration from the pipe.

  • Parameters can still be passed through the command line if preferred.

When the Remote Session Window is Created

The custom connector can report progress to the Launcher by sending a RemoteConnectionWindowCreated event. The event must include a string message with additional information about the event.

The event object also supports an optional ProcessId property, which represents the process ID of the created remote session window. The Launcher uses this process ID to track the window, even if the connector settings do not include session tracking configurations.

When the Remote Window is Closed by the Connector

It can send a RemoteConnectionWindowClosed event to the Launcher to indicate the end of the connection. The event must include a string message with additional information.

If the Launcher did not detect the window closure (i.e., it wasn't able to track it in the first place), this will generate a ConnectionEnded event in LoginEnterprise and move the session to its final state.

If the launcher is not tracking the window and the connector never sends this event, the system falls back to legacy behavior: it waits for the configured timeout and then sends the event.

When a Connection Fails

If something goes wrong during the connection process, the connector can send a RemoteConnectionFailure event with an error message. This notifies the Launcher that the connection has failed and generates a ConnectionFailed event in LoginEnterprise, moving the session to its final state.

If the failure occurs before the remote window is created and the connector does not send this event, the system falls back to legacy behavior: the user session will eventually be timed out by LoginEnterprise.

Sending Custom Events

At any time, the connector can send custom events to the launcher by sending a CustomConnectorEvent event with the type Custom and a string message. This generates a custom user-session event in LoginEnterprise, which is visible on the All Events page, Dashboard, etc.

From the User Session Perspective (Named Pipe)

When the Launcher receives a new session request, it posts a ConnectionStarted event to the session. This moves the session login state to InProgress. Next, the Launcher initializes the PipeServer and SessionTracker, and then starts the custom connector process. At this point, it begins listening for event messages from the connector.

Connector Sends RemoteConnectionWindowCreated

This event does not produce any user-session events or state changes, but it signals the launcher that the window has been created and updates its internal state.

If the event includes a process ID for tracking, the Launcher starts a new, or restarts an existing, SessionTracker to monitor the remote window.

Connector Sends RemoteConnectionWindowClosed

This event signals the Launcher that the connection window has closed. If the Launcher was not already tracking the window, the event generates a ConnectionEnded user-session event. Based on the current session state, this moves the session to one of its final states:

If the connector does not send the event, but the Launcher is tracking the window, the Launcher raises the ConnectionEnded event when the tracked process closes.

If the connector does not send the event and the Launcher was unable to track the window, the ConnectionEnded event is sent only after the configurable timeout following the session’s end, failure, or timeout.

Connector Sends RemoteConnectionFailure

This event signals the Launcher that a failure occurred during the connection process, so no remote window is created. The Launcher posts a ConnectionFailed event in LoginEnterprise, moving the session to its final state.

If the connector does not send this event, the Launcher cannot detect the failure. In this case, LoginEnterprise times out the session (as it will stay too long in LoginState.InProgress). After the configured delay, the Launcher sends a ConnectionEnded event, which moves the session to the final faulted state.

Using this event allows a custom connector to notify the Launcher of a failure immediately, invalidating the session without waiting for a timeout.

Connector Sends a Custom Event

This event forwards a user-session custom event to LoginEnterprise without requiring the custom connector to post it manually through the Public API. The event is visible in Test results, Dashboards, Event pages, and the Event APIs.

Connector Named Pipe Schema

ConnectionConfiguration

After the Launcher detects a new client connection, it sends the following message containing all the information required to launch the remote connection:

{
  "sessionId": "<GUID>",
  "host": "<string>",
  "resource": "<string>",
  "username": "<string>",
  "password": "<string>",
  "domain": "<string>",
  "accountCustomFields": {
    "<string>": "<string>"
  },
  "accountSecureFields": {
    "<string>": "<string>"
  }
}

CustomConnectorEvent

The connector can send messages back to the Launcher through the named pipe.
Each message uses the following schema:

{
  "eventType": "<CustomConnectorEventType>",
  "message": "<string>",
  "processId": <int|null>
}

CustomConnectorEventType enum

The connector can send messages back to the Launcher through the named pipe.
Each message uses the following schema:

[
  "Custom",
  "RemoteConnectionWindowCreated",
  "RemoteConnectionFailure",
  "RemoteConnectionWindowClosed"
]

Minimal End-To-End Flow

Here’s a simplified example demonstrating basic communication between the Launcher and the Connector using the named pipe.

A connector implemented in any language should roughly:

1. Read pipe name from environment variable VSI_IPC_PIPE_NAME

2. Connect to the named pipe as a client

3. Wrap the pipe in a UTF-8 text reader/writer (newline-based)

4. Read first line from the pipe > parse as ConnectionConfiguration

5. Use ConnectionConfiguration to start the remote client process

6. When the remote window is created, send:

CustomConnectorEvent { 
  eventType: "RemoteConnectionWindowCreated", 
  message: "...", 
  processId: 1234 
}

7. On connection failure, send:

CustomConnectorEvent { 
  eventType: "RemoteConnectionFailure", 
  message: "error details" 
}

8. When the remote client process exits, send:

CustomConnectorEvent { 
  eventType: "RemoteConnectionWindowClosed", 
  message: "optional reason" 
}

9. Close the pipe and exit.