User

Class finesse.restservices.User

Represents an agent or supervisor and includes information about the user, such as roles, state, teams, dialogs, and so on. The User object is the representation of the Finesse REST API User object.

When the User object is initialized (for example, var _user = new finesse.restservices.User()), a GET REST API request is made to /finesse/api/User/<userid>, and its response is used to populate the User object.

When a User change event is received, the User object's values are updated accordingly. For example, if the agent state changes, the respective User object's getState() method reflects the change, and returns the latest state of the agent when invoked.

Example

Copyvar _user = new finesse.restservices.User({
    id: _id,
    onLoad: _handleUserLoad,
    onChange: _handleUserChange
});

For additional parameters and methods, see RestBase Common Parameters.

Methods

getActiveDeviceId()

Retrieves the current active device ID of the agent.

Example

Copy
var _user = new finesse.restservices.User({
    id: _id,
    onLoad: _handleUserLoad,
    onChange: _handleUserChange
});
_user.getActiveDeviceId();

Returns

{String} The active device ID for that agent.

getDevices()

Retrieves the list of devices associated with a particular extension.

Example

Copy
var _user = new finesse.restservices.User({
    id: _id,
    onLoad: _handleUserLoad,
    onChange: _handleUserChange
});
_user.getDevices();

Returns

{Object} The collection object of the devices that is associated with a particular extension. The contents of a device include the following:

• deviceId—A unique ID of the device.

• deviceType—The device type as defined in the CiscoTerminal.getType() in JTAPI specifications.

• deviceTypeName—The display name of the device type as defined in the CiscoTerminal.getTypeName() in JTAPI specifications.

For more information about JTAPI specifications, refer to Cisco Unified JTAPI Developers Guide.

getDialogs(handlers)

Retrieves the collection of voice dialogs associated with the current user. This includes the dialogs that the user is currently active on, being alerted, along with the held dialogs. The terminated dialogs are not part of the list.

The dialog list is retrieved by making a GET REST API request to the /finesse/api/User/<id>/Dialogs/ endpoint. The getDialogs are queried only once from the server that is, when the object is created.

Copy_dialogs = _user.getDialogs({
    onCollectionAdd: handleNewDialog,
    onCollectionDelete: handleEndDialog
});

Parameters

Returns

{finesse.restservices.Dialogs} The Dialogs collection object.

getDialogsNoCache(handlers)

Retrieves the collection of dialogs (calls) associated with the current user. This includes the dialogs that the user is currently active on, being alerted, along with the held dialogs. The terminated dialogs are not part of the list. The difference between the getDialogsNoCache and getDialogs methods is that the GET REST API request is always made for this method.

Copy_user.getDialogsNoCache({
    onLoad: handleDialogsLoadedCallDetails,
    onCollectionAdd: handleDialogsAddedCallDetails,
    onCollectionDelete: handleDialogsDeletedCallDetails,
    onError: handleDialogsErrorCallDetails
});

Parameters

Returns

{finesse.restservices.Dialogs} The Dialogs collection object.

getExtension()

Retrieves the extension that is associated with the user.

Returns

{String} The extension of the user.

getFirstName()

Retrieves the first name of the user.

Returns

{String} The first name of the user.

getFullName()

Retrieves the full name of the user. The full name format is FirstName LastName (for example, John Doe).

Returns

{String} The full name of the user.

getLastName()

Retrieves the last name of the user.

Returns

{String} The last name of the user.

getMediaList(handlers)

Retrieves the media list that is associated with the user. It retrieves the media dialog collection object.

Copyvar mediaList = _user.getMediaList({
    onCollectionAdd: _handleMediaAdd,
    onCollectionDelete: _handleMediaDelete,
    onLoad: _handleMediaListLoaded
});

Parameters

Returns

{finesse.restservices.MediaList} The MediaList collection object.

getMediaPropertiesLayout(handlers)

Retrieves the layout that is associated with the user. Teams are configured with custom layouts by the administrator. Users are associated to custom call variable layouts (MediaPropertyLayout) due to their association with a team.

Copyvar _mediaPropertiesLayout = _user.getMediaPropertiesLayout({
    onLoad: _handleMediaPropertiesLayoutLoaded,
    onError: _handleMediaPropertiesLayoutError
});

Parameters

Returns

{finesse.restservices.UserMediaPropertiesLayout} The UserMediaPropertiesLayout object.

getMediaPropertiesLayouts(handlers)

Retrieves the layouts that is associated with the user. Teams are configured with custom layouts by the administrator. Users are associated to custom call variable layouts (MediaPropertyLayouts) due to their association with a team.

Copyvar _mediaPropertiesLayouts = _user.getMediaPropertiesLayouts({
    onLoad: _handleMediaPropertiesLayoutsLoaded,
    onError: _handleMediaPropertiesLayoutsError
});

Parameters

Returns

{finesse.restservices.UserMediaPropertiesLayout} The UserMediaPropertiesLayout object.

getMediaState()

Retrieves the media state of the user. This is applicable only in Unified CCX deployments.

Returns

{String} The current (or last fetched) media state of the user. When the agent is talking on a manual outbound call, or when the agent in not signed-in, the getMediaState returns busy. In all other cases getMediaState returns null.

getMobileAgentDialNumber()

Retrieves the mobile agent dial number.

Returns

{String} If available, returns the mobile agent dial number, otherwise null.

getMobileAgentMode()

Retrieves the mobile agent work mode. In Unified CCE, when an agent has logged in as a mobile agent (by selecting Sign in as a Mobile Agent checkbox in the Cisco Finesse login page), then it returns mobile agent mode. If an agent has not selected the checkbox, then it returns null.

Returns

{finesse.restservices.User.WorkMode} The WorkMode object. If available, then the mobile agent work mode, otherwise null. For more information, see User.WorkMode.

getNotReadyReasonCodeId()

Retrieves the user's Not Ready reasonCodeId.

Returns

{String} The reasonCodeId, or undefined if the ID is not set or indeterminate.

getNotReadyReasonCodes(handlers)

Retrieves all the custom Not Ready reason codes configured globally and the team level reason codes applicable to the user.

Copy_user.getNotReadyReasonCodes({
    success: handleNotReadyReasonCodesSuccess,
    error: handleNotReadyReasonCodesError
});

Parameters

getPendingStateReasonCode()

Retrieves the pending state reasonCode of the user.

Returns

{Object} The reasonCode for the pending state of the user. The contents include the following:

• uri—The URI for the reasonCode object.

• Id—The unique ID for the reasonCode.

• category—The category can either be NOT_READY or LOGOUT.

• code—The numeric reasonCode value.

• label—The label for the reasonCode.

• forAll—The boolean flag that denotes the global status for the reasonCode.

• systemCode—The boolean flag which denotes whether the reasonCode is system-generated or customized.

getPhoneBooks(handlers)

Retrieves the PhoneBooks collection object that is associated with the user.

Parameters

Returns

{finesse.restservices.PhoneBooks} The PhoneBooks collection object.

getQueues(handlers)

Retrieves the Queues collection object that is associated with the user.

Parameters

Returns

{finesse.restservices.Queues} The Queues collection object.

getReasonCode()

Retrieves the reason code object corresponding to the user's current state.

Returns

{Object} The reasonCode for the pending state of the user. The contents include the following:

• uri—The URI for the reasonCode object.

• id—The unique ID for the reasonCode.

• category—The category and it can be either NOT_READY or LOGOUT.

• code—The numeric reasonCode value.

• label—The label for the reasonCode.

• forAll—Boolean flag that denotes the global status for the reasonCode.

• systemCode—Boolean flag which denotes whether the reasonCode is system-generated or customized.

getReasonCodeById(handlers, reasonCodeId)

Retrieves the reason code object that is associated with the reasonCodeId.

Parameters

getReasonCodeLabel()

Retrieves the user's reasonCode label for both Not Ready and Logout reasonCodes.

Returns

{String} The reasonCode label, or an empty string if none.

getServices()

Retrieves the list of services configured for the user.

The following service can be configured for the user.

Agent Answers: A real time presentation of suggestions for the agent to consider based on the live conversation between the end customer and agent.

This is applicable only in Unified CCE deployments.

Example

var services = user.getServices();

Returns

{Object} The array list of services.

getSignoutReasonCodes(handlers)

Retrieves all the Signout reason codes that is associated with the user.

Copy_user.getSignoutReasonCodes({
    success: handleSignoutReasonCodesSuccess,
    error: handleSignoutReasonCodesError
});

Parameters

getSkillTargetId()

Retrieves the ID for the skill target assigned to the user in the Unified CCE database. It is supported from Cisco Finesse, Release 12.5(1) ES2 onwards.

Returns

{String} The ID for the skill target assigned to the user.

getState()

Retrieve the state of the user.

Returns

{String} The current (or last fetched) state of the user.

getStateChangeTime()

Retrieves the state change time (UTC) of the user.

Returns

{String} The state change time of the user in UTC.

getSupervisedTeams()

Retrieves the teams that are managed by the user (supervisor). Applicable for users that are supervisors.

Returns

{Array} The array of objects containing Id, name, and URI of the teams managed by the user (supervisor).

The object content includes the following:

• id—The unique ID for the team.

• name—The team name for the team.

• uri—The URI for the team.

getTeamId()

Retrieves the ID of the team that is associated with the user.

Returns

{String} The current (or last fetched) ID of the team that is associated with the user.

getTeamName()

Retrieves the name of the team that is associated with the user.

Returns

{String} The current (or last fetched) name of the team that is associated with the user.

getWrapUpOnIncoming()

Retrieves the wrap-up mode of the user. For more information, see User.WrapUpMode.

Returns

{String} The wrap-up mode of the user.

getWrapUpOnOutgoing()

Retrieves the wrap-up mode of the user. For more information, see User.WrapUpMode.

Returns

{String} The wrap-up mode of the user.

getWrapUpReasons(handlers)

Retrieves the WrapUpReasons collection object that is associated with the user.

Parameters

Returns

{finesse.restservices.WrapUpReasons} The WrapUpReasons collection object.

getWrapUpTimer()

Retrieves the maximum amount of time the user can be in Wrap Up state (in seconds).

Returns

{String} The WrapUp time configured for the user. For example, 3600 (1 hour).

hasAgentRole()

Checks whether the user is an agent.

Returns

{Boolean} True if the user has the role of an agent, else false.

hasSupervisorRole()

Checks whether the user is a supervisor.

Returns

{Boolean} True if the user has the role of the supervisor, else false.

isDeviceSelectionEnabled()

Retrieves whether the device selection is enabled for the user.

Example

Copy /**
   * Retrieves whether the device selection is enabled for the user.
   * If device selection is enabled, the login request for the user should
   * contain active device Id, if the extension chosen by the agent is
   * shared between multiple devices.
   * @see finesse.restservices.User.loginWithActiveDeviceId
   * @returns {Boolean} True if the device selection is enabled and false
   *          if device selection is disabled.
   */
  isDeviceSelectionEnabled: function() {
      this.isLoaded();
      if (this.getData().settings) {
          return this.getData().settings.deviceSelection === 'enabled';
      }
      return false;
  }

isMobileAgent()

Checks whether the user is a mobile agent.

Returns

{Boolean} True if this agent is a mobile agent, else false.

isPendingStateChange()

Checks whether there is a pending state change. A pending state change is a request to change state that does not result in an immediate state change. For example, if an agent in the TALKING state attempts to change to the NOT_READY state, the state is not changed until the call ends. Pending state change occurs when the agent is in the following states:

• TALKING

• HOLD

• RESERVED

• OUTBOUND

• PREVIEW

Returns

{Boolean} True if there is a pending state change.

isReasonCodeReserved()

Checks whether the reasonCode of the user is a system-generated reasonCode.

Returns

{Boolean} True if the reasonCode for the state of the user is a system-generated reasonCode.

isWrapUp()

Checks whether the user's current state is WORK or WORK_READY. This is used to ensure that a pending state is not cleared when moving into wrap-up (work) mode. We do not add this as a pending state, as the changes (while in wrap-up) occur immediately.

Returns

{Boolean} True if user is in wrap-up mode.

isWrapUpRequired()

Checks whether the user is required to go into wrap-up mode.

Returns

{Boolean} True if the user is required to go in to wrap-up mode.

login(extension, handlers)

Performs an agent login for the user and associates the agent with the specified extension.

Parameters

Returns

{finesse.restservices.User} The User object.

loginMobileAgent(extension, mode, extension, handlers, reasonCode)

Performs an agent login for the user and associates the agent with the specified extension. This marks the agent as a mobile agent and associates an external dial number.

Parameters

Returns

{finesse.restservices.User} The User object.

loginWithActiveDeviceId(extension, activeDeviceId, handlers)

Performs an agent login for a user and associates the agent with the specified extension and device.

Example

Copy
var _user = new finesse.restservices.User({
    id: _id,
    onLoad: _handleUserLoad,
    onChange: _handleUserChange
});
_user.loginWithActiveDeviceId(extension, activeDeviceId, handlers);


var handlers = {
     success: function() {
        // handler for success response
     },
     error: function() {
        //handler for error response
     }
}

Parameters

Returns

{finesse.restservices.User} The User object.

logout(reasonCode, handlers)

Performs an agent logout for the user.

Parameters

Returns

{finesse.restservices.User} The User object.

makeBargeCall(number, dialogUri, handlers)

Makes a silent monitor call to a particular agent's phone number. Barge in to call, which is silently monitored by the supervisor.

Parameters

Returns

{finesse.restservices.User} The User object.

makeCall(number, handlers)

Makes a call to the specified phone number.

Parameters

Returns

{finesse.restservices.User} The User object.

makeSMCall(number, handlers)

Makes a silent monitor call for the specified agent's extension.

Parameters

Returns

{finesse.restservices.User} The User object.

setState(newState, reasonCode, handlers)

Sets the state of the user.

Parameters

Returns

{finesse.restservices.User} The User object.

updateToMobileAgent(mode, dialNumber, handlers)

Updates the user object with the agent's mobile login information.

Parameters

Returns

{finesse.restservices.User} The User object.