finesse_api

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 23, 2023 License: MIT Imports: 17 Imported by: 0

README

Finesse API

Utilities for work with the Unified Cisco Contact Center agents through Finesse API.

API allows actions per one agent or group of agents.

  • get agent status
  • login agent
  • set agent ready state
  • set agent not-ready state
  • logout agent

Connection

Program used connection to Finesse API and XMPP for notification.
Utilizes ports:

  • 8445 - HTTPS Finesse API
  • 7443 - WSS Finesse XMPP over HTTP notification (for secure)
  • 5222 - XMPP notification (non-secure - notice below)

Notice: Cisco Finesse, Release 12.5(1) onward, the 5222 port (non-secure connection) is disabled by default. Set the utils finesse set_property webservices enableInsecureOpenfirePort to true to enable this port. For more information, see Service Properties section in Cisco Finesse Administration Guide.

Certificate

Program need to add the Finesse Notification certificate to their respective trust stores.

Windows systems:
If you can use secure XMPP you must add valid server certificate to Trusted Root Certification Authorities.

  • right-click on the DER file and select Install certificate
  • select Current User
  • select Please all certificates in following store
  • click on Browse...
  • select Trusted Root Certification Authorities
  • finish

Ubuntu: If you can use secure XMPP you must add valid server certificate to Trusted Root Certification Authorities.

sudo apt install ca-certificates
sudo cp finesse.pem /usr/local/share/ca-certificates/finesse.crt
sudo update-ca-certificates
How to download the certificate:
  1. Sign in to the Cisco Unified Operating System Administration through the URL (https://FQDN:8443/cmplatform, where FQDN is the fully qualified domain name of the primary Finesse server and 8443 is the port number).
  2. Click Security > Certificate Management.
  3. Click Find to get the list of all the certificates.
  4. In the Certificate List screen, choose Certificate from the Find Certificate List where drop-down menu, enter tomcat in the begins with option and click Find.
  5. Click the FQDN link which appears in the Common Name column parallel to the listed tomcat certificate.
  6. In the pop-up that appears, click the option Download .PEM or .DER File to save the file on your desktop.

System support security XMPP over HTTP (WSS).
The current version does not support XMPP secure communication with the Finesse server. Program tested on version Finesse 12.5.

How use

For any operation is necessary to create a server structure with an address and port. It is necessary to register the agents with which the operations will take place on the server.

// import finesse_api library
import (
	api "github.com/pokornyIt/finesse-api"
)

// create Finesse server object
server := finesse_api.NewFinesseServer("finesse.server.fqdn", 8435)

// add agents to server
agent := api.NewAgentName("Name1", "Password", "1000")
server.AddAgent(agent)
agent := api.NewAgentName("Name2", "Password", "1001")
server.AddAgent(agent)
agent := api.NewAgentName("Name3", "Password", "1002")
server.AddAgent(agent)

// get status for all defined agent
states, err = server.GetStateAgentsParallel()

// login agent Name2 to system
state := server.LoginAgent("Name2")

// login all agents and set it to ready state
states, err = server.ReadyAgentsParallelWithStatus(true)

Program use logger library "github.com/sirupsen/logrus".

Documentation

Index

Constants

View Source 
const (
	XmppTimeout                 = 20
	TypeErrorNoError            = 0
	TypeErrorWrongState         = 1
	TypeErrorRequest            = 2
	TypeErrorResponse           = 3
	TypeErrorNotifyTimeout      = 4
	TypeErrorAnalyzeResponse    = 5
	TypeErrorUnknownBulkCommand = 6
	TypeErrorNoStatus           = 7
)
View Source 
const (
	AgentStateLogin        string = "LOGIN"
	AgentStateLogout              = "LOGOUT"
	AgentStateReady               = "READY"
	AgentStateNotReady            = "NOT_READY"
	AgentStateAvailable           = "AVAILABLE"
	AgentStateTalking             = "TALKING"
	AgentStateWorkNotReady        = "WORK_NOT_READY"
	AgentStateWorkReady           = "WORK_READY"
	AgentStateReserved            = "RESERVED"
	AgentStateUnknown             = "UNKNOWN"
	AgentStateHold                = "HOLD"
	AgentStateActive              = "ACTIVE"
	AgentStatePaused              = "PAUSED"
	AgentStateInterrupted         = "INTERRUPTED"
	AgentStateNotActive           = "NOT_ACTIVE"
)
View Source 
const (
	DefaultServerHttpsPort      = 8445 // DefaultServerHttpsPort standard Finesse API port
	DefaultServerXmppPort       = 7443 // DefaultServerXmppPort standard secure XMPP over WSS port (secure XMPP communication)
	DefaultServerDirectXmppPort = 5222 // DefaultServerDirectXmppPort insecure XMPP port for direct communication (by default disabled on Finesse server)
	DefaultServerTimeout        = 30   // DefaultServerTimeout define timeout for API and Notify communication in seconds
)
View Source 
const (
	XmppMessageBuffer = 10 // define channel buffer for collect message from Xmpp notify service
)

Variables

View Source 
var AgentLoginStates = map[string]string{AgentStateLogin: AgentStateLogin, AgentStateReady: AgentStateReady,
	AgentStateNotReady: AgentStateNotReady, AgentStateAvailable: AgentStateAvailable, AgentStateTalking: AgentStateTalking,
	AgentStateWorkNotReady: AgentStateWorkNotReady, AgentStateWorkReady: AgentStateWorkReady, AgentStateReserved: AgentStateReserved,
	AgentStateHold: AgentStateHold, AgentStateActive: AgentStateActive, AgentStatePaused: AgentStatePaused,
	AgentStateInterrupted: AgentStateInterrupted, AgentStateNotActive: AgentStateNotActive}

AgentLoginStates States when agent is logged in to the system

View Source 
var AgentLogoutState = map[string]string{AgentStateLogout: AgentStateLogout, AgentStateUnknown: AgentStateUnknown}

AgentLogoutState States when agent is not logged in to the system

View Source 
var AgentNotReadyStates = map[string]string{AgentStateNotReady: AgentStateNotReady, AgentStateWorkNotReady: AgentStateWorkNotReady}

AgentNotReadyStates States when agent is not-ready

View Source 
var AgentReadyStates = map[string]string{AgentStateReady: AgentStateReady, AgentStateAvailable: AgentStateAvailable,
	AgentStateTalking: AgentStateTalking, AgentStateWorkReady: AgentStateWorkReady, AgentStateReserved: AgentStateReserved,
	AgentStateHold: AgentStateHold, AgentStateActive: AgentStateActive}

AgentReadyStates States when agent is ready for work or work

View Source 
var AgentStates = []string{AgentStateLogin, AgentStateLogout, AgentStateReady, AgentStateNotReady, AgentStateAvailable,
	AgentStateTalking, AgentStateWorkNotReady, AgentStateWorkReady, AgentStateReserved, AgentStateUnknown, AgentStateHold,
	AgentStateActive, AgentStatePaused, AgentStateInterrupted, AgentStateNotActive}

AgentStates All valid agent states

Functions

func ValidServerNameIp 

func ValidServerNameIp(srv string) bool

ValidServerNameIp Validate if string is valid IPv4 address, hostname or FQDN

Types

type Agent added in v1.0.0 

type Agent struct {
	LoginName string // login name
	LoginId   string // login ID
	Password  string // password
	Line      string // phone line
	// contains filtered or unexported fields
}

func NewAgentNotify added in v1.0.0 

func NewAgentNotify(ctx context.Context, name string, pwd string, line string, server *Server) *Agent

NewAgentNotify create new agent object, but not create/start any additional service

Better way is use function Server.CreateAgent, this creates agent and start necessary function

func (*Agent) FullString added in v1.0.0 

func (a *Agent) FullString() string

func (*Agent) GetLastStatus added in v1.0.0 

func (a *Agent) GetLastStatus() *XmppUser

GetLastStatus get latest collected user status

func (*Agent) GetStatus added in v1.0.0 

func (a *Agent) GetStatus() (*XmppUser, error)

GetStatus geta actual agent status from finesse server

func (*Agent) Login added in v1.0.0 

func (a *Agent) Login() OperationError

func (*Agent) Logout added in v1.0.0 

func (a *Agent) Logout(forceLogout ...bool) OperationError

func (*Agent) NotReady added in v1.0.0 

func (a *Agent) NotReady() OperationError

func (*Agent) Ready added in v1.0.0 

func (a *Agent) Ready(forceReady ...bool) OperationError

func (*Agent) StartXmpp added in v1.0.0 

func (a *Agent) StartXmpp() error

func (*Agent) String added in v1.0.0 

func (a *Agent) String() string

type AgentGroup added in v1.0.0 

type AgentGroup struct {
	Agents []*Agent
	// contains filtered or unexported fields
}

func NewAgentGroup added in v1.0.0 

func NewAgentGroup() *AgentGroup

func (*AgentGroup) AddAgentToGroup added in v1.0.0 

func (group *AgentGroup) AddAgentToGroup(name string, pwd string, line string, server *Server) error

func (*AgentGroup) AddBulkAgents added in v1.0.0 

func (group *AgentGroup) AddBulkAgents(agents []BulkAgent, server *Server) []OperationError

func (*AgentGroup) CancelFunction added in v1.0.0 

func (group *AgentGroup) CancelFunction()

func (*AgentGroup) Login added in v1.0.0 

func (group *AgentGroup) Login() []OperationError

func (*AgentGroup) Logout added in v1.0.0 

func (group *AgentGroup) Logout(forceLogout ...bool) []OperationError

func (*AgentGroup) NotReady added in v1.0.0 

func (group *AgentGroup) NotReady() []OperationError

func (*AgentGroup) Ready added in v1.0.0 

func (group *AgentGroup) Ready(forceLogout ...bool) []OperationError

type AgentRequest added in v1.0.0 

type AgentRequest struct {
	// contains filtered or unexported fields
}

AgentRequest Structure for one API request

type AgentResponse added in v1.0.0 

type AgentResponse struct {
	// contains filtered or unexported fields
}

AgentResponse Structure for one API response

func (*AgentResponse) GetResponseBody added in v1.0.0 

func (f *AgentResponse) GetResponseBody() string

GetResponseBody Read API response body

type BulkAgent added in v1.0.0 

type BulkAgent struct {
	Name     string
	Password string
	Line     string
}

type OperationError added in v1.0.0 

type OperationError struct {
	Type  int
	Error error
}

type Server added in v1.0.0 

type Server struct {
	// contains filtered or unexported fields
}

Server Structure for finesse server data

func NewServer added in v1.0.0 

func NewServer(server string, ignoreCert bool, time ...int) *Server

NewServer Creating new Finesse server structure connect on standard ports and manage if ignore certificate problems

possible use repeat for different agents

func NewServerDetail added in v1.0.0 

func NewServerDetail(server string, port int, ignore bool, xmppPort int, insecureXmpp bool, timeOut int) *Server

NewServerDetail Create new Finesse server structure with required security and ports

possible use repeat for different agents

func (*Server) CreateAgent added in v1.0.0 

func (s *Server) CreateAgent(ctx context.Context, name string, pwd string, line string) (*Agent, error)

CreateAgent create new agent, read agent ID from Finesse server, start XMPP notify connection and return Agent or error if problem

  • ctx context.Context - used for graceful shutdown of XMPP connection

type XmppDevices added in v1.0.0 

type XmppDevices struct {
	Device []struct {
		DeviceId       string `xml:"deviceId"`
		DeviceType     string `xml:"deviceType"`
		DeviceTypeName string `xml:"deviceTypeName"`
	} `xml:"Device"`
}

type XmppDialog added in v1.0.0 

type XmppDialog struct {
	AssociatedDialogUri string `xml:"associatedDialogUri"`
	FromAddress         string `xml:"fromAddress"`
	ID                  string `xml:"id"`
	SecondaryId         string `xml:"secondaryId"`
	MediaProperties     struct {
		MediaId                string `xml:"mediaId"`
		DNIS                   string `xml:"DNIS"`
		CallType               string `xml:"callType"`
		DialedNumber           string `xml:"dialedNumber"`
		OutboundClassification string `xml:"outboundClassification"`
		CallVariables          struct {
			CallVariable []struct {
				Name  string `xml:"name"`
				Value string `xml:"value"`
			} `xml:"CallVariable"`
		} `xml:"callvariables"`
		QueueNumber        string `xml:"queueNumber"`
		QueueName          string `xml:"queueName"`
		CallKeyCallId      string `xml:"callKeyCallId"`
		CallKeySequenceNum string `xml:"callKeySequenceNum"`
		CallKeyPrefix      string `xml:"callKeyPrefix"`
	} `xml:"mediaProperties"`
	MediaType    string `xml:"mediaType"`
	Participants struct {
		Participant struct {
			Actions struct {
				Action []string `xml:"action"`
			} `xml:"actions"`
			MediaAddress     string `xml:"mediaAddress"`
			MediaAddressType string `xml:"mediaAddressType"`
			StartTime        string `xml:"startTime"`
			State            string `xml:"state"`
			StateCause       string `xml:"stateCause"`
			StateChangeTime  string `xml:"stateChangeTime"`
		} `xml:"Participant"`
	} `xml:"participants"`
	State     string `xml:"state"`
	ToAddress string `xml:"toAddress"`
	URI       string `xml:"uri"`
}

type XmppDialogs added in v1.0.0 

type XmppDialogs struct {
	Dialogs []XmppDialog `xml:"Dialog"`
}

type XmppError added in v1.0.0 

type XmppError struct {
	PeripheralErrorCode int    `xml:"peripheralErrorCode,omitempty"`
	ErrorType           string `xml:"errorType,omitempty"`
	ErrorMessage        string `xml:"errorMessage,omitempty"`
	PeripheralErrorText string `xml:"peripheralErrorText,omitempty"`
	PeripheralErrorMsg  string `xml:"peripheralErrorMsg,omitempty"`
	ErrorData           int    `xml:"errorData,omitempty"`
}

type XmppErrors added in v1.0.0 

type XmppErrors struct {
	ApiErrors []XmppError `xml:"apiError"`
}

type XmppQueue added in v1.0.0 

type XmppQueue struct {
	URI        string `xml:"uri"`
	Name       string `xml:"name"`
	Statistics struct {
		CallsInQueue                  string `xml:"callsInQueue"`
		StartTimeOfLongestCallInQueue string `xml:"startTimeOfLongestCallInQueue"`
		AgentsReady                   string `xml:"agentsReady"`
		AgentsNotReady                string `xml:"agentsNotReady"`
		AgentsBusyOther               string `xml:"agentsBusyOther"`
		AgentsLoggedOn                string `xml:"agentsLoggedOn"`
		AgentsTalkingInbound          string `xml:"agentsTalkingInbound"`
		AgentsTalkingOutbound         string `xml:"agentsTalkingOutbound"`
		AgentsTalkingInternal         string `xml:"agentsTalkingInternal"`
		AgentsWrapUpNotReady          string `xml:"agentsWrapUpNotReady"`
		AgentsWrapUpReady             string `xml:"agentsWrapUpReady"`
	} `xml:"statistics"`
}

type XmppTeam added in v1.0.0 

type XmppTeam struct {
	URI   string `xml:"uri"`
	ID    string `xml:"id"`
	Name  string `xml:"name"`
	Users struct {
		User []struct {
			URI             string `xml:"uri"`
			LoginId         string `xml:"loginId"`
			FirstName       string `xml:"firstName"`
			LastName        string `xml:"lastName"`
			Dialogs         string `xml:"dialogs"`
			Extension       string `xml:"extension"`
			PendingState    string `xml:"pendingState"`
			State           string `xml:"state"`
			StateChangeTime string `xml:"stateChangeTime"`
			ReasonCode      struct {
				Category string `xml:"category"`
				Code     string `xml:"code"`
				Label    string `xml:"label"`
				ID       string `xml:"id"`
				URI      string `xml:"uri"`
			} `xml:"reasonCode"`
		} `xml:"User"`
	} `xml:"users"`
}

type XmppTeamMessage added in v1.0.0 

type XmppTeamMessage struct {
	URI       string `xml:"uri"`
	ID        string `xml:"id"`
	CreatedBy struct {
		ID        string `xml:"id"`
		FirstName string `xml:"firstName"`
		LastName  string `xml:"lastName"`
	} `xml:"createdBy"`
	CreatedAt string `xml:"createdAt"`
	Duration  string `xml:"duration"`
	Content   string `xml:"content"`
	Teams     struct {
		Team []string `xml:"team"`
	} `xml:"teams"`
}

type XmppUpdate added in v1.0.0 

type XmppUpdate struct {
	Event     string `xml:"event"`
	RequestId string `xml:"requestId"`
	Source    string `xml:"source"`
	Data      struct {
		User        XmppUser        `xml:"user,omitempty"`
		Error       XmppErrors      `xml:"apiErrors,omitempty"`
		Dialogs     XmppDialogs     `xml:"Dialog,omitempty"`
		Devices     XmppDevices     `xml:"Devices,omitempty"`
		Queue       XmppQueue       `xml:"Queue,omitempty"`
		Team        XmppTeam        `xml:"Team,omitempty"`
		TeamMessage XmppTeamMessage `xml:"TeamMessage,omitempty"`
	} `xml:"data"`
}

type XmppUser added in v1.0.0 

type XmppUser struct {
	//XMLName      xml.Name `xml:"User"`
	Dialogs      string `xml:"dialogs"`
	Extension    string `xml:"extension"`
	FirstName    string `xml:"firstName"`
	LastName     string `xml:"lastName"`
	LoginId      string `xml:"loginId"`
	LoginName    string `xml:"loginName"`
	MediaType    string `xml:"mediaType"`
	ReasonCodeId string `xml:"reasonCodeId"`
	ReasonCode   struct {
		Category string `xml:"category"`
		URL      string `xml:"uri"`
		Code     string `xml:"code"`
		Label    string `xml:"label"`
		ForAll   bool   `xml:"forAll"`
		Id       int    `xml:"id"`
	} `xml:"ReasonCode"`
	Roles struct {
		Role []string `xml:"role"`
	} `xml:"roles"`
	Settings struct {
		WrapUpOnIncoming string `xml:"wrapUpOnIncoming"`
		WrapUpOnOutgoing string `xml:"wrapUpOnOutgoing"`
		DeviceSelection  string `xml:"deviceSelection"`
	} `xml:"settings"`
	State           string `xml:"state"`
	StateChangeTime string `xml:"stateChangeTime"`
	PendingState    string `xml:"pendingState"`
	TeamId          string `xml:"teamId"`
	TeamName        string `xml:"teamName"`
	SkillTargetId   string `xml:"skillTargetId"`
	URI             string `xml:"uri"`
	Teams           struct {
		Team []struct {
			Id   int    `xml:"id"`
			Name string `xml:"name"`
			URI  string `xml:"uri"`
		} `xml:"Team"`
	} `xml:"teams"`
	MobileAgent struct {
		Mode       string `xml:"mode"`
		DialNumber string `xml:"dialNumber"`
	} `xml:"mobileAgent"`
	ActiveDeviceId string `xml:"activeDeviceId"`
	Devices        struct {
		Device []struct {
			DeviceId       string `xml:"deviceId"`
			DeviceType     string `xml:"deviceType"`
			DeviceTypeName string `xml:"deviceTypeName"`
		} `xml:"device"`
	} `xml:"devices"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.