LUCS API

In the following we provide a description about the data models and functions used within LUCS and in automated interaction with other applications. Separate API Use Cases will explain how to apply those concepts in specific scenarios.

The Luware API allows customers to manage external system tasks in their own systems and block specific agents. The new Luware API component is divided into the following three parts to support three different usage areas:

Provisioning API: Configure and provision users and services in the system
Reporting API: Get system information and reporting data
Control API: Add and manage callback and external system tasks

Target audience

This Document is written for System Administrators and Developers of 3rd party products using LUCS functionality externally. If you are in need of additional support or want to provide feedback, don’t hesitate to contact us.

Preconditions & System Requirements

LUCS needs to be installed and fully configured respectively using the API. Please refer to the "Precondition" Documents of your respective Luware Product and Version.

API and Luware Version compatibility

The API functionality described in this documentation is only supported for LUCS Versions 3.1 or newer.

Version mismatches between LUCS base components and the installed API can lead to erratic system behavior, errors and potential loss of database content!

→ Make sure to only install the corresponding API setup matching and delivered alongside your Luware product.

API Checklist - Before you start

LUCS and API Component is installed → See chapter below and API - Advanced Programming Interface
1. AC, AM, CI and CIC Services must be running as well in order to operate the system overall → See Architecture
2. IIS is running to operate the Web FrontEnd User Interface
Check in "Home" Tab in LUCS Configurator or Web Configurator and check if the API service is running.
Generate a new API Key → See chapter below
Configure Access rights for the key → See chapter below

If malfunctions occur after setting changes (e.g. in the API Component, Network Ports or IIS) a quick restart of API Services is recommended.

Ensure that the API port used is also exempt from any Anti-Virus and Firewall tools

API Ports

Since the LUCS API uses the functionality of LUCS, ports need to be forwarded.

Source	Destination	Protocol	Destination Server Port (Default)	Comment
Agent PC (LUCS-API)	LUCS Server 01	TCP	4444	LUCS Web API
Agent PC (LUCS-API)	LUCS Server 02	TCP	4444	LUCS Web API
Server	LUCS Server 01	TCP	19413	How How Luware-API connects to other Luware components through WCF channel

Also see

Installation

When installing the API as individual setup (e.g. on a Client PC), the port and server instance can be individually configured during setup.

For an external use of the API, consider that outgoing ports need to be forwarded as well.

API Setup Port configuration

Authorization Configuration / API Key

Luware API is an active – active component and may be installed on any machine that has IIS configured. To allow access the API you need to generate unique API tokens from within WebConfigurator.

Open Settings -> Topology -> Authentication Tokens
Click "Add" and name / describe your token as needed

API Key configuration
Optionally you can set an expiry date for the token.
The API should now be ready to use. Check in "Home" Tab if the API service is running.
If malfunctions occur after setting changes (e.g. in the API Component, Ports or IIS) a quick restart of API Services is recommended.

API Roles

Starting with LUCS 3.3 it's now possible to limit single API key access only certain areas via role assignment.

Precondition

You need System Administrator or at least the "Topology" Permission given to your account via Role Based Access - RBAC to use this feature. Otherwise you will only be able to inspect API keys or not see the entry at all.

After generating a new API key entry you now have access to the roles tab:

API Roles tab

Role	Description	API commands that can be executed
TasksManage	Allows to fully manage and manipulate tasks in the system. (GET, POST)	Manage Callbacks POST /v1.0/callbacks - Creates a new callback request GET /v1.0/callbacks - Get callback using the ExternalTaskId that provided on creation request. GET /v1.0/callbacks/{id} - Get callback using callbackId POST /v1.0/callbacks/{id}/cancel - Cancel the Callback, identified by a CallbackId. POST /v1.0/callbacks/cancel - Cancel the Callback, identified by an ExternalTaskId. POST /v1.0/callbacks/search - Flexible API to search through the Callbacks in the system by different criteria. Manage Tasks GET /v1.0/tasks/{taskIdentifier} - Get the particular task's data referenced by taskIdentifier. GET/v1.0/services/{service}/tasks - Retrieves a list of tasks for the particular service (identified by ServiceId or Service SipUri) GET/v1.0/services/{service}/longestwaitingtask - Retrieves a longest waiting task for the particular service POST/v1.0/tasks - Create new task in the system. POST/v1.0/tasks/{taskIdentifier}/setestablished - Notify LUCS system that the external task is established. POST/v1.0/tasks/{taskIdentifier}/terminate - Remove the task. Applicable only for the external tasks. POST/v1.0/tasks/{taskIdentifier}/refresh - Reset an external task to pending and trigger the process to search for agent again. POST /v1.0/tasks/outboundCall/start - Starts an outbound call GET/v1.0/users/{userIdentifier}/tasks - Retrieves a list of tasks for the particular user (identified by userIdentifier) POST/v1.0/tasks/{taskIdentifier}/transfer - Transfer the task. Applicable only for the incoming call tasks. Read Users GET/v1.0/services/{serviceId}/users - Get existing users for the specified service. GET/v1.0/users - Get All users in the system. GET/v1.0/users/{userIdentifier} - Get a particular User by a specified user's identifier (case insensitive). Read Services GET/v1.0/services - Get all the existing Services/ContactObjects in the system. GET/v1.0/services/{serviceIdentifier} - Get particular service by its identifier or sipUri GET/v1.0/services/count - Retrieve overall count of Services in the system.
TasksReadonly	Allows only tasks details to be read via the API (GET)	Read Callbacks GET /v1.0/callbacks - Get callback using the ExternalTaskId that provided on creation request. GET /v1.0/callbacks/{id} - Get callback using callbackId POST /v1.0/callbacks/search - Flexible API to search through the Callbacks in the system by different criteria. Read Tasks GET /v1.0/tasks/{taskIdentifier} - Get the particular task's data referenced by taskIdentifier. GET/v1.0/services/{service}/tasks - Retrieves a list of tasks for the particular service (identified by ServiceId or Service SipUri) GET/v1.0/services/{service}/longestwaitingtask - Retrieves a longest waiting task for the particular service GET/v1.0/users/{userIdentifier}/tasks Retrieves a list of tasks for the particular user (identified by userIdentifier) Read Users GET/v1.0/services/{serviceId}/users - Get existing users for the specified service. GET/v1.0/users - Get All users in the system. GET/v1.0/users/{userIdentifier} - Get a particular User by a specified user's identifier (case insensitive). Read Services GET/v1.0/services - Get all the existing Services/ContactObjects in the system. GET/v1.0/services/{serviceIdentifier} - Get particular service by its identifier or sipUri. GET/v1.0/services/count - Retrieve overall count of Services in the system.
ServicesReadonly	Allows only Services details to be read via the API (GET)	Read Services GET/v1.0/services - Get all the existing Services/ContactObjects in the system. GET/v1.0/services/{serviceIdentifier} - Get particular service by its identifier or sipUri. GET/v1.0/organizationunits/{ouIdentifier}/services - Search services in a specific OrganizationUnit. GET/v1.0/services/count - Retrieve overall count of Services in the system. Read OrganizationUnits GET/v1.0/organizationunits/{ouIdentifier} - Get details of the particular OrganizationUnit. GET/v1.0/organizationunits - Get All the OrganizationUnits in the system.
OU Readonly	Allows only Organization units to be read via the API (GET)	Read OrganizationUnits GET/v1.0/organizationunits/{ouIdentifier} - Get details of the particular OrganizationUnit. GET/v1.0/organizationunits - Get All the OrganizationUnits in the system.
UsersProvision	Allows full access to user provisioning (GET, POST, DELETE)	Manage Users GET/v1.0/services/{serviceId}/users - Get existing users for the specified service. GET/v1.0/organizationunits/{ouIdentifier}/users - Get users from the particular Organization Unit. POST/v1.0/users - Create new User in the system. GET/v1.0/users - Get All users in the system. POST/v1.0/users/{userIdentifier}/copy - Create new user based on existing one. DELETE/v1.0/users/{userIdentifier} - Remove existing user by userIdentifier GET/v1.0/users/{userIdentifier} - Get a particular User by a specified user's identifier (case insensitive). POST/v1.0/users/{userIdentifier}/applytemplate/{templateUserIdentifier} - Copy fields, provided by "fieldsToUpdate" from the template user identified by "templateUserId" into User, identified by "userIdentifier". POST /v1.0/users/{userIdentifier} - Update existing user configurations by providing updated paramaters through the API. Read Services GET/v1.0/services - Get all the existing Services/ContactObjects in the system. GET/v1.0/services/{serviceIdentifier} - Get particular service by its identifier or sipUri. GET/v1.0/organizationunits/{ouIdentifier}/services - Search services in a specific OrganizationUnit. GET/v1.0/services/count - Retrieve overall count of Services in the system. Read OrganizationUnits GET/v1.0/organizationunits/{ouIdentifier} - Get details of the particular OrganizationUnit. GET/v1.0/organizationunits - Get All the OrganizationUnits in the system.
UsersControl	Allows to manage user presence, block / unblock from task distribution (GET, POST)	Control Users GET/v1.0/users - Get All users in the system. GET/v1.0/users/{userIdentifier} - Get a particular User by a specified user's identifier (case insensitive). POST/v1.0/users/{userIdentifier}/block - Block a defined agent (agent won't be selectable for tasks anymore). POST/v1.0/users/{userIdentifier}/unblock - Unblock the agent. POST/v1.0/users/{userIdentifier}/setpresence - Sets particular presence for an agent.
UsersReadonly	Allows only to retrieve user details (GET)	Read Users GET/v1.0/services/{serviceId}/users - Get existing users for the specified service. GET/v1.0/organizationunits/{ouIdentifier}/users - Get users from the particular Organization Unit. GET/v1.0/users - Get All users in the system. GET/v1.0/users/{userIdentifier} - Get a particular User by a specified user's identifier (case insensitive). Read Services GET/v1.0/services - Get all the existing Services/ContactObjects in the system. GET/v1.0/services/{serviceIdentifier} - Get particular service by its identifier or sipUri. GET/v1.0/organizationunits/{ouIdentifier}/services - Search services in a specific OrganizationUnit. GET/v1.0/services/count - Retrieve overall count of Services in the system. Read OrganizationUnits GET/v1.0/organizationunits/{ouIdentifier} - Get details of the particular OrganizationUnit. GET/v1.0/organizationunits - Get All the OrganizationUnits in the system.

For a full list on API command functionality regarding Tasks, Callbacks, OU, Services and User management, refer to our → API Swagger documentation.
Existing API-Keys from previous LUCS installations will be given full access by default to avoid access conflicts. You can edit them to narrow down the permissions to the needed amount.

API usage / API Endpoints

The following content is embedded from our Live-API documentation (Swagger UI). You can also open this window directly.

API related errors

The API returns default → HTML Error status codes. The most common one is not passing the api_key along with a request:

During all HTTP Requests the generated API Key has to be included in the HTTP Header. Otherwise an error will be thrown:


  "Error": {
    "Code": "Unauthorized",
    "Message": "Header 'api_key' not found."
  }

The info below is left as legacy API documentation content. Newest API definitions can be found in our Swagger UI documentation above.

In this section: