:DISCONNECT

Use the :DISCONNECT script statement to terminate an active connection to the AE system. You can use this statement to disconnect specific Users, User Groups, Agents, or Agent Groups. When disconnecting Users or User Groups, the specified connection must belong to the same Client as the executable object containing the script.

When a User is disconnected, an Automic Web Interface message notifies them that the connection has been interrupted and prompts them to log in again. If you execute this statement when there are no active connections matching the definition, the system ignores it without throwing an error. However, if you specify an invalid User or User Group, script processing aborts and generates an error message.

When targeting Agents, you can specify an Agent Group instead of individual Agents. In this case, the disconnection applies to all active Agents within that group.

Note: The executing User or Agent requires the privilege to cancel processes; otherwise, the script statement fails to execute.

Syntax

:DISCONNECT Connection, Name

Parameters

Parameter	Description	Format
Connection	Type of connection. Allowed values: USER: Connection of a User or a User Group HOST: Connection of an Agent HOSTGROUP: Connection of Agents that belong to an Agent Group Notes: Using :DISCONNECT with HOST or HOSTGROUP temporarily drops the connection but does not shut down the Agent. The Agent automatically reconnects to the system during the next periodic Agent check. This behavior is particularly useful when starting a new communication process (CP), as it forces Agents to disconnect and rebalance across the available CPs. To permanently shut down an Agent, use the :TERMINATE script statement.	Script literal, script variable, or number
Name	Name of the specific User, User Group, Agent, or Agent Group to disconnect.	Script literal, script variable, or number

Parameter

Description

Format

Connection

Type of connection.

Allowed values:

USER: Connection of a User or a User Group
HOST: Connection of an Agent
HOSTGROUP: Connection of Agents that belong to an Agent Group

Notes:

Using :DISCONNECT with HOST or HOSTGROUP temporarily drops the connection but does not shut down the Agent. The Agent automatically reconnects to the system during the next periodic Agent check. This behavior is particularly useful when starting a new communication process (CP), as it forces Agents to disconnect and rebalance across the available CPs.
To permanently shut down an Agent, use the :TERMINATE script statement.

Script literal, script variable, or number

Name

Name of the specific User, User Group, Agent, or Agent Group to disconnect.

Script literal, script variable, or number

Examples

The following example disconnects the User SMITH/AE from the AE system.

:DISCONNECT "USER", "SMITH/AE"

The Agent WIN01 is disconnected from the AE system.

:DISCONNECT "HOST", "WIN01"

The next example disconnects all database Agents.

:DISCONNECT "HOSTGROUP", "HOSTG_DB_UNIX"