In the following we provide a description about the data models and functions used within TM and in automated interaction with other applications. 

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:

  • Task API: Add and manage service tasks
  • Team API: Identify team and organization unit structures
  • User API: Retrieve user information and team affiliation

Target audience

This Document is written for System Administrators and Developers of 3rd party productusing TM functionality externally or via custom-developed tools. If you are in need of additional support or want to provide feedback, don’t hesitate to contact us.


Trained Administrators only!

The following procedure is to be performed by Luware-trained system administrators only. When uncertain about certain steps, don't hesitate to contact us

CWS Interface Specification Document

(warning) Note that this interface will be discontinued in future. Future updates of the new TeamManager API aim to cover the needs of the CWS Interface.

Preconditions & System Requirements

TM and the API component 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 TM 3.2 or newer.

Version mismatches between 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

  1. TM and API Component is installed (info) See chapter below
    1. AC, AM, CI and CIC Services must be running as well in order to operate the system overall → (info) See Architecture and Components
    2. IIS is running to operate the FrontEnd User Interface
  2. Check in "Home" Tab in TM Configurator if the API service is running.

  3. Generate a new API Key → (info) See chapter below
  4. Configure Access rights for the key → (info) See chapter below

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

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

API specific port configuration

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 Server to Server outgoing ports need to be considered as well. 

Source

Destination

Protocol

Destination Server Port (Default)

Comment

Agent PC (TM-API)

TM Server 01

TCP

6444

TM Web API

Agent PC (TM-API)

TM Server 02

TCP

6444

TM Web API

ServerTM Server 01TCP21413How How Luware-API connects to other Luware components through WCF channel

(info) Also see: Network Ports

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.

(warning) 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. 

  1. Open TM Configurator > Topology > Authentication Tokens

  2. Click "Add" and name / describe your token as needed

    API Key configuration
  3. (lightbulb) Optionally you can set an expiry date for the token. 
  4. The API should now be ready to use.

API Roles

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

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

API Role Based Access Tab
RoleDescriptionAPI commands that can be executed
TasksManageAllows to fully manage and manipulate tasks in the system. (GET, POST)

Read Teams
GET​ /v1.0​/teams - Get all the existing Teams in the system
GET /v1.0/teams/{teamIdentifier} - Get particular team by its identifier or internal TeamId (Guid), Sid or Sam
GET /v1.0/teams/bymember/{userIdentifier} - Retrieves all the teams where user is a member

Manage Tasks
GET /v1.0/teams/{teamIdentifier}/tasks Retrieves a list of team tasks
GET /v1.0/teams/{teamIdentifier}/longestwaitingtask Retrieves a longest waiting task for the particular Team
GET​ /v1.0​/users​/{userIdentifier}​/tasks Retrieves a list of tasks for the particular user (identified by userIdentifier)
GET /v1.0/tasks/byteamsmember/{userIdentifier} - Get all tasks for a specific team member
POST ​/v1.0​/tasks​/{taskIdentifier}​/transfer Transfer the task - Applicable only for the incoming call tasks
POST /v1.0/tasks/{taskIdentifier}/terminate - Remove the task. Applicable only for the external tasks.
POST /v1.0/tasks/outboundCall/start - Starts an outbound call

Read Users
GET /v1.0/teams/{teamIdentifier}/users - Get the members of the particular team
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)

Tasks ReadonlyAllows only tasks details to be read via the API (GET)

Read Teams
GET​/v1.0​/teams - Get all the existing Teams in the system
GET /v1.0/teams/{teamIdentifier} - Get particular team by its identifier or internal TeamId (Guid), Sid or Sam
GET /v1.0/teams/bymember/{userIdentifier} - Retrieves all the teams where user is a member

Read Tasks
GET /v1.0/teams/{teamIdentifier}/tasks Retrieves a list of team tasks
GET /v1.0/teams/{teamIdentifier}/longestwaitingtask Retrieves a longest waiting task for the particular Team
GET​/v1.0​/users​/{userIdentifier}​/tasks Retrieves a list of tasks for the particular user (identified by userIdentifier)
GET /v1.0/tasks/byteamsmember/{userIdentifier} - Get all tasks for a specific team member

Read Users
GET /v1.0/teams/{teamIdentifier}/users - Get the members of the particular team
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)

TeamsReadonlyAllows only Team details to be read via the API (GET)

Read Teams
GET​/v1.0​/teams - Get all the existing Teams in the system
GET /v1.0/teams/{teamIdentifier} - Get particular team by its identifier or internal TeamId (Guid), Sid or Sam
GET /v1.0/organizationunits/{ouIdentifier}/teams - Retrieves all the teams belonging to the defined organization units and it's child
GET /v1.0/teams/bymember/{userIdentifier} - Retrieves all the teams where user is a member

Read Users
GET /v1.0/teams/{teamIdentifier}/users - Get the members of the particular team
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)

UsersReadonlyAllows only user details to read via the API (GET)

Read Teams
GET​/v1.0​/teams - Get all the existing Teams in the system
GET /v1.0/teams/{teamIdentifier} - Get particular team by its identifier or internal TeamId (Guid), Sid or Sam
GET /v1.0/teams/bymember/{userIdentifier} - Retrieves all the teams where user is a member

Read Users
GET /v1.0/teams/{teamIdentifier}/users - Get the members of the particular team
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)

UsersControlAllows to set users active / inactive to block / unblock them from from task distribution (GET, POST) 

Control Users
GET /v1.0/teams/{teamIdentifier}/users - Get the members of the particular team
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/teams/{teamIdentifier}/users/{userIdentifier}/active - Get the members of the particular team (identified by provided Id)

Read Teams
GET​/v1.0​/teams - Get all the existing Teams in the system
GET /v1.0/teams/{teamIdentifier} - Get particular team by its identifier or internal TeamId (Guid), Sid or Sam
GET /v1.0/teams/bymember/{userIdentifier} - Retrieves all the teams where user is a member

  • For a full list on API command functionality regarding Tasks, OU, Services and User management, refer to our → API Swagger documentation.
  • API-Keys from previous TM 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 like the following will be thrown: 


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