The agent script

The agent script runs in the background in the Agent on every workstation. It reacts to events — a conversation rings, is connected or ends, the agent switches to wrap-up or logs in — and then triggers something itself. Typical tasks:

• open the customer screen of your CRM in the Browser module as soon as a call is connected, with the phone number or a customer number from the attached data;
• start another program on the workstation or call a web service;
• show a window of your own;
• trigger wrap-up, an activity or logoff, or control a status light.

There is one script for the whole system. It runs in the Agent program with the permissions of the logged-in Windows user and can do anything that a .NET program on the workstation can do.

Requirements

• The effective agent profile allows Agent side scripts — Features tab, on by default; see Profile settings.
• At login, the agent receives an Agent: Execute agent side scripts license. It is included in the Professional, Premium and Premium+ packages and in every license profile, see Features. Without the license, no script runs for this agent.
• To edit the script, you need the Script configuration permission.

Setting up the script

1. Open the server configuration and switch to the Script tab.
2. Write the script in the code editor. The editor marks errors as you type.
3. Click Save.

After saving, all logged-in agents receive the new script immediately, all others at their next login. Each Agent compiles the script itself and starts it. A script with errors is saved as well — but it then does not run in the Agent.

Structure

An agent script is exactly one class:

• It is named AgentScript and derives from MyCCAgentScript.
• It is in the namespace ilogixx.Agent or in none.
• It has a public constructor without parameters — or none at all. In the constructor, Agent, Conversations and the commands cannot be used yet.
• It overrides the events it should react to with public override void ….
• It brings its own using lines, including using System;.

The Administration installs a template with all events as %ProgramData%\ilogixx GmbH\myContactCenter\Script Templates\AgentScript.cs. Take only the events you need from it.

How the script runs

• One after another: The Agent calls the events one after the other, in the background. If an action takes a long time — such as calling a web service — all subsequent events arrive correspondingly later.
• State at the time of the event: By the time it is the script’s turn, a conversation may already have moved on. So evaluate the parameters of the event, such as state in My_ConversationStateChanged, not conversation.State.
• Windows: You show your own windows with Show(form); the Agent opens them above its main window.
• Lifetime: The script runs until the Agent is closed or a changed script arrives.

Finding errors

The Agent does not display errors of the script. So catch all exceptions in every event and write them to the log:

try
{
    // …
}
catch (Exception ex)
{
    Trace.Error(ex);
}

You switch on the log of the script in the server configuration, on the Tracing Settings tab, Agent subtab:

1. On the right, select the agents whose log you need.
2. Set the Script area to Information or Detailed.
3. Click Save.

The lines of the script begin with Script: and the name of the agent. If compilation fails in the Agent, the errors are written there as well.

Example: Opening customer data in the Browser module

The script opens the customer screen of a CRM in the Browser module as soon as an incoming call is connected. A flow has previously stored the customer number with Attach data under the key “CustomerNumber”.

using System;
using ilogixx.SharedFiles.GeneralDefinitions;
using ilogixx.SharedFiles.GeneralEnums;

namespace ilogixx.Agent;

public class AgentScript : MyCCAgentScript
{
    private string lastOpenedConversationId = string.Empty;

    public override void My_ConversationStateChanged(Struct_Conversation conversation, ConversationState previousState, ConversationState state)
    {
        try
        {
            if (state != ConversationState.Connected || !conversation.IsInboundCall) return;

            if (conversation.Id == lastOpenedConversationId) return;

            lastOpenedConversationId = conversation.Id;
            string customerNumber = conversation.AttachedData.StringValue("CustomerNumber");
            BrowseTo("https://crm.example.com/customer?number=" + Uri.EscapeDataString(customerNumber), true);
        }
        catch (Exception ex)
        {
            Trace.Error(ex);
        }
    }
}

The comparison with the conversation opened last prevents the screen from opening a second time when the agent puts the call on hold and retrieves it. If the page should open in the default browser instead of in the Agent, replace the line with BrowseTo with:

string url = "https://crm.example.com/customer?number=" + Uri.EscapeDataString(customerNumber);
System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo { FileName = url, UseShellExecute = true });