Goal: Distribute External Tasks over LUCS among agents, communicating with external Systems
Complexity: Medium

Preconditions: 

  • LUCS is installed
  • API Usage Preconditions are met
  • Users (Agents) and Services are defined in the System targeted by the API so task assignment is possible

If you want to test the results: Agent Assistant needs to be running and you must be logged in as the receiving SfB user. 

Related DTOs:

Task States and Transitions

Task States and transitions via API

Usage example steps


Used FunctionsActionResults
1

POST Tasks

Requires info retreived via:

GET Services

GET Service Users


Note: to create the task, the following minimal information is required: Service ID, Required Capabilities, Distribute To Agent (true/false).
Preferred agents are optional to be defined. If left blank or no preferred Agent is selectable the agent distribution will be handled according to the services distribution policy.

Task DTO example

{
  "ExternalTaskId": "testingtask123",
  "Service": "7830678b-03b1-4e71-af33-a3987142519f",
  "Caller": "Johnny HasaProblem Again",
  "PreferredAgents": [
    "sip:smoky.aa@dev.local", 
	"sip:smoky.bb@dev.local", 
	"sip:smoky.cc@dev.local"
  ],
  "ConsiderPreferredAgentsOnly": true,
  "Required": {
    "Im": true,
    "Audio": true,
    "Video": true,
    "DesktopSharing": true,
    "ConversationContext": true
  },
  "DistributeToAgent": true,
  "DistributeToAgentRONATimeoutInSeconds": 50
}
CODE

Code 200 (OK)

New Task is created with a unique TaskID

e.g.: 

95c8a3be-8086-4e1a-bf19-3d4759b76dc8
2

GET Task TaskIdentifier 

Get Service Tasks

With this command, you can get the task information via the ID and check it's successful creation in the System. To find the Task you might want to go via the Service ID used in step 1 to list only relevant tasks. 

Also you can inspect the successful task creation directly in LUCS FrontEnd:

Task DTO after Creation

[
  {
    "Id": "488e2892-16c2-48a2-9040-f7f96157ad77",
    "ExternalTaskId": "testingtask123",
    "Type": "ExternalNonBlocking",
    "State": "InQueue",
    "CustomerIdentifier": "Johnny HasaProblem Again",
    "Created": "27.06.2019 11:58:35.4996911Z",
    "QueueStarted": "27.06.2019 11:58:35.4996911Z",
    "Connected": null,
    "InitialModalityType": "External",
    "OriginType": "Unknown",
    "OriginTypeCustom": null,
    "ContextParameters": [
      {
        "Name": "ServiceCulture",
        "Value": "en-GB"
      },
      {
        "Name": "InitialQueuePosition",
        "Value": "1"
      },
      {
        "Name": "ServiceSipUri",
        "Value": "sip:smoky.businesss@dev.local"
      },
      {
        "Name": "SessionAgentToken",
        "Value": "00000000-0000-0000-0000-000000000000"
      },
      {
        "Name": "CurrentSystemTime",
        "Value": "6/27/2019 2:11 PM"
      },
      {
        "Name": "ServiceTelNumber",
        "Value": "+41000000000"
      },
      {
        "Name": "ExternalTaskId",
        "Value": "testingtask123"
      },
      {
        "Name": "ServiceDisplayName",
        "Value": "Business Customer Care"
      },
      {
        "Name": "AgentSipUri",
        "Value": "sip:unknown@unknown"
      }
    ],
    "ReservedUserObject": null
  }
]
CODE
Code 200 (OK)
3POST Refresh Tasks

Uses taskIdentifier to set a TaskStatus back to Pending, can set an agent to RONA according to the "SetAgentOnRona" state.

When LUCS or any other handling instance has already assigned the task but the agent is not responding, the refresh checks if the task needs to be set to "Pending" again so it can be distributed to another agent. 

The LUCS API will perform this automatically after the "DistributeToAgentRONATimeoutInSeconds" criteria (specified in step 1) is met. The selected agent will have it's presence status set to RONA automatically via the API if a client-sided component such as Luware "Agent Assistant" is installed. 

Code 200 (OK) → Task returns to Queue and can be reassigned

Code 500 → If task is already assigned, RONA status may not be set remotely

4POST taskID Setestablished 

When LUCS assigned a task and it's confirmed by an Agent (or simulated via API using 3rd party components), the task is considered "established". Established tasks may not be re-assigned or refreshed, they can only be terminated (next step).

Code 200 (OK) 

Code 500 → If the task is already distributed to an Agent it cannot be set established again.

5POST terminate task

An established external task can be terminated, which in context of the API needs to be done by any connected external system that originally created the task. 

When handled by LUCS / TM, the task DTO will have additional information added to the task, such as the handling algorithm used, queue times and the agent that confirmed and established the task.

Task DTO after Creation

{
  "Id": "488e2892-16c2-48a2-9040-f7f96157ad77",
  "ExternalTaskId": "testingtask123",
  "Type": "ExternalNonBlocking",
  "State": "Terminated",
  "CustomerIdentifier": "Johnny HasaProblem Again",
  "Created": "27.06.2019 11:58:35.4996911Z",
  "QueueStarted": "27.06.2019 11:58:35.4996911Z",
  "Connected": null,
  "InitialModalityType": "External",
  "OriginType": "Unknown",
  "OriginTypeCustom": null,
  "ContextParameters": [
    {
      "Name": "ServiceCulture",
      "Value": "en-GB"
    },
    {
      "Name": "InitialQueuePosition",
      "Value": "1"
    },
    {
      "Name": "ServiceSipUri",
      "Value": "sip:smoky.businesss@dev.local"
    },
    {
      "Name": "SessionAgentToken",
      "Value": "0406e2d8-92ec-4017-b3d6-caf2848c68c5"
    },
    {
      "Name": "CurrentSystemTime",
      "Value": "6/27/2019 2:22 PM"
    },
    {
      "Name": "ServiceTelNumber",
      "Value": "+41000000000"
    },
    {
      "Name": "ExternalTaskId",
      "Value": "testingtask123"
    },
    {
      "Name": "ServiceDisplayName",
      "Value": "Business Customer Care"
    },
    {
      "Name": "AgentSipUri",
      "Value": "sip:smoky.aa@dev.local"
    }
  ],
  "ReservedUserObject": {
    "Id": "275cb3e3-4d73-4012-9033-c58daa50ad4e",
    "DisplayName": "Alisa Abbot",
    "OrganizationUnitName": "Insurance Services",
    "SipUri": "sip:smoky.aa@dev.local",
    "UserPrincipalName": "smoky.aa@dev.local",
    "SecurityIdentifier": "S-1-5-21-870184815-4058679007-2540742146-76261",
    "SamAccountName": "smoky.aa",
    "AgentProfileName": "Eastern Division",
    "ResponsibleSinceLevel": 1,
    "SelectionAlgorithm": "BestQualifiedMostResponsibleAgent"
  }
}
CODE

Code 200 (OK) 

Code 404 If task wasn't found (anymore)

UCIDUC  LUCS API 004