Place, DNs, and Media

Media are resources that services use to perform actions such as making a call, sending an e-mail, and so on. This chapter covers how media work in an agent’s place with the Agent Interaction Service API, how to monitor them, and how to deal with specific voice media, that is DNs.

Introduction

Places, media, and DNs are objects defined in the Configuration Layer. These objects offer important information that your application might have to take into account.

What Are Places?

A place defines a set of media and DNs that can all be used together by a single agent at a given time. Media types are EMAIL and CHAT, whereas DNs are voice media resources that offer phone-call features. The following figure presents an example of a place defined for the agent Agent0.
 

A Place for Agent0

A place can be associated with a single chat media type and a single e-mail media type but with several DNs.
The place service is designed to provide your application with information about the places defined in the Configuration Layer, and also with information about media and DNs associated with these places.
The place service provides the following features:

• List a place’s DN identifiers and media types with their status.
  
• Retrieve the identifier of an agent logged into a place.
  
• Retrieve the possible workmodes for a place’s DNs.
  
• Events for place modification:
  
• Media added or removed.
  
• DNs added or removed.
  
• Changes of place identifier.
  

Place and Other Services

The place has an important role in other services. The agent has first to log into a place, and this logged-in agent can use interaction services only if the requested media are logged in on this place.
Once this requirements are met, the place can help your application perform some management. For example, the IInteractionService interface lets your application retrieve all current interactions on a place. Another example is the IInteractionMailService interface, which uses the place to pull interactions.


DNs-Voice Specifics

DNs are resources that handle voice interactions. Depending on the underlying switches, DNs have some specific features, for example, the Do Not Disturb feature.
The DN service, IDnService, deals with all DNs configured in the Configuration Layer. A DN has a string identifier dnId, and a callable number that is readable with the dn:callableNumber attribute of the DN service. DN identifiers are mandatory in any call to the DN service’s methods.
The DN service’s features are the following:


• Activate/Deactivate the Do Not Disturb feature.
  
• Activate/Deactivate the Forward feature.
  
• Retrieve the preceding features’ statuses (activated or deactivated).
  
• Retrieve the possible workmodes of a DN.
  
• Retrieve DN information with DTOs.
  
• Fine-tune your application with switch specific information.
  
Important
To use the DN service features on a DN, your application must have an agent logged into the DN.

Understanding Place, DNs, and Media

The place service does not let your application perform actions on places. The place service is designed to provide your application with information about places’ media and DNs.
Your application may use the place service in scenarios like the following:

• Display whether a place is used by an agent.
  
• Display the available media and DN for a logged place.
  
• Inform the agent when new media are added to his or her place.
  

The following subsections specify the relationships amongst place, media, and DN.

Place, Agent, and Statuses

The place service can provide the statuses of places’ logged media and DNs. These statuses of media and voice media (DNs) are the statuses of an agent on these media.

Place and Login

When your application logs in an agent with the agent service, the application specifies the place and media on which the agent will log in. For details, see Agent Login.
While the agent is logged into one of the place’s media types (or DNs), the place and its media are associated with the agent, as shown in A Place for Agent0.
To start working, the agent must log into the place’s media types or DNs which are defined in the Configuration Layer. As long as the agent is logged into one of the place’s media types or DNs, the agent is also logged into the place, and the place, its DNs, and its media are associated with the agent.
To get the place’s media types, your application takes a login action on at least one of the place’s media types. When your application requests a login action on media types, media types are added to the place, and the ones specified in the request are logged in. If the agent logs out of the media types, your application no longer accesses them, as shown in the figure below.
 

Agent Actions on the Media of a Place

The above figure shows the place PLACE_0 where agent agent0 has first logged in on a DN DN_0 and e-mail media of the place.
At runtime, the media only exist in the Interaction Server. To get the media of a place, your application must call the IAgentService.login() method and pass in argument a MediaForm instance which contains at least one media type.
As a result, the available media are added to the place, and the ones specified in the request are logged in. If your application logs out media per media, the Interaction Server considers that the place is still logged in.
To definitly logout of the place, your application must call the IAgentService.logoutMultimedia() method, that will logout all medias at once, including in the Interaction Server, if you set the MediaForm.mediaNames field to null for the mediaForm passed in parameters, of if you pass an empty MediaForm instance as shown in the following code snippet.

 
myAgentService.logout("agent0", "place0", null, new MediaForm()); 

Important

When an agent is logged into one of the place’s media types, the agent is logged into the place.

VoiceMediaStatus and MediaStatus

The VoiceMediaStatus and MediaStatus enumerated types are part of the com.genesyslab.ail.ws.place namespace.

VoiceMediaStatus

The VoiceMediaStatus type is an enumerated type describing the agent status on a DN when an agent is logged in.
When no agent is logged into the DN, the voice media status is LOGGED_OUT, or else OUT_OF_SERVICE if there is an issue with the DN. For details, see Agent Status for Voice Media.

MediaStatus

The MediaStatus type is an enumerated type describing the agent status on a media type when an agent is logged into a place.
When the agent is not logged into any media type of a place, no media type is available on this place, and your application cannot get any media status for this place.
When the agent is logged into at least one of the place’s media types, all media types are available on this place, and your application can get media status for any media type. For logged-out media types, the media status is LOGGED_OUT, or else OUT_OF_SERVICE if there is an issue with the media type. For details, see Agent Status for Other Media.

Media and Voice-Media Information

The com.genesyslab.ail.ws.place namespace offers the VoiceMediaInfo and the MediaInfo classes to deal with essential information about the media associated with a place.
The place service lets your application retrieve this information using two attributes:

• place:medias—An array of VoiceMediaInfo, containing information about media of type MediaType associated with a place.
  
• place:dns—An array of MediaInfo, containing information about the DNs associated with a place.
  

VoiceMediaInfo

The VoiceMediaInfo class is a simple container for the main data of the voice media (DNs) belonging to a place. The attributes of this class are:

• dnId—The identifier of the relevant DN.
  
• status—The VoiceMediaStatus of the DN.
  

MediaInfo

The MediaInfo class represents an information container for a media type belonging to a place.
The attributes of this class are

• type—The MediaType of the media type.
  
• status—The MediaStatus of the media type.
  
• name—The string to display for this media type.
  
Important
Each place can contain zero to one media of each type MediaType. Therefore, the type of the media identifies the media.

Place and DNs Consolidation

Switch DNs’ types—for example, ACD position or extension—are mostly switch-specific. They affect the use of features provided by the agent service, such as login, logout, and ready actions.
The underlying AIL library provides consolidation of the DN objects in its model. In all cases, the services expose a single DN, even if a place’s configuration requires more DNs in the Configuration Layer for compliance with the underlying switch.
To find the required configuration for each switch, and to thus find which DN identifier is visible, refer to the Interaction SDK Java Deployment Guide.

Warning

You must respect this DN consolidation model for your applications to handle DNs properly.

For example, to work in regular mode with an A4400 switch, the server-side application:

• Registers the ACDPosition and Extension.
  
• Exposes a single Dn object.
  

The Agent Interaction Service API presents a single DN, and transparently manages the requests to hidden ACDPosition and Extensions. The DN ID exposed in the API is the ACDPosition.
To work in substitute mode on an A4400 switch, your application must manage an Extension’s activities on a place, as well as an ACDPosition’s activities on that place.
When an agent logs in successfully, the event service receives two place events:

• dnRemoved carries notification that the Extension is no longer visible.
  
• dnAdded carries notification that a DN of type ACDPosition is now visible.
  

Successful agent login generates a voice media event. All subsequent voice media events and request activities occur with respect to the ACDPosition DN, not the Extension.
When the agent logs out, logout is performed through the ACDPosition DN, and upon successful logout, the event service receives four place events:

• An event carrying notification of successful logout.
  
• A dnRemoved event carrying notification that the ACDPosition DN is no longer visible.
  
• A dnAdded event with notification that the Extension is now visible.
  
• An event carrying notification of the Extension’s status.
  

While no agent is logged in, the extension is visible and the ACDPosition DN is not visible. While an agent is logged in, the ACDPosition DN is visible in the place.

DN Callable Number

A DN has an identifier (or ID) and a callable number. The ID is used to access the corresponding DN’s data through the services. To avoid any ambiguity and ensure unique DN IDs, a DN ID is now defined in accordance with the following rule:<DN_CME_Name>@<switch_name>
The callable number is the number that your application must use to reach a DN. Depending on the switch, the DN number declared in the configuration layer might not be the number to dial in call operations, such as make call, transfer, or conference. For example, you must remove some leading numbers to reach a Nortel DMS 100’s DN.
The number to dial can also depend on the DN status. For example, if an agent is logged into the DN, you have to dial the agent ID.
Finally, because of the switch abstraction, some DNs can be hidden, but still be the real ones to dial instead of their visible counterpart. Once again, the callable number of a visible DN properly returns the hidden's one.
It is recommended to use callable numbers to access CTI features.

Using the Place Service

The place service is designed to provide your application with information about media and DNs associated with a place. The place service does not offer any direct actions on places.
The following subsections detail how to use the place service.

Getting Place DTOs

To retrieve the attribute values of the place service, use the PlaceDTO class of the namespace and the getPlacesDTO() method of the IPlaceService interface, as shown in the following code snippet.

 
/// Retrieving the DTOs
PlaceDTO[] myPlacesDTO = myPlaceService.getPlacesDTO(new string[]{"Place0"}, //Place ids new string[]{ "place:medias" }); //Attributes to retrieve
 
/// displaying the DTO content for each Place
foreach(PlaceDTO myPlace in myPlacesDTO)
{
   // Displaying the id of the place associated with the DTO content System.Console.WriteLine("Place : "+myPlace.placeId+"\n");
 
   // Displaying the DTO content
   foreach(KeyValue data in myPlace.data)
   {
       //Displaying media info only
       if(data.key == "place:medias")
       {
          MediaInfo[] myMedias = (MediaInfo[]) data.value as MediaInfo[];
          foreach(MediaInfo media in myMedias)
          {
              System.Console.WriteLine("Medium name: "+media.name + " Type: " + media.type.ToString() + " Status:" + media.status.ToString()+"\n");
          }
       }
    }
}

The above code snippet retrieves the place:medias and place:dns attributes of a place and displays the content of the corresponding information objects.

PlaceEvents

The place service defines PlaceEvent, which is triggered when modifications on a place occur. To handle PlaceEvent, two important attributes are propagated:

• place:placeId—String identifier of the place concerned by the PlaceEvent.
  
• place:eventReason—Reason for this PlaceEvent.
  

The following table lists the existing PlaceEventReasons and the associated attributes to take into consideration.

PlaceEventReason and Associated Attributes

PlaceEventReason	Associated Attribute	Attribute Value
DN_ADDED	place:dn_added	Identifier of the added DN
DN_REMOVED	place:dn_removed	Identifier of the removed DN
MEDIA_ADDED	place:media_added	Identifier of the added media type
MEDIA_REMOVED	place:media_removed	Identifier of the removed media type

For further information on events and subscription, see The Event Service.

Using the DN Service

The DN service is specific to voice media management. A DN is an access point for phone calls identified by a callable number, which is the dn:callableNumber attribute of the IDnService interface.
The following subsections detail how to use the DN service.

Features and Possible Actions

Like many other services, the DN service can provide your application with the possible actions associated with features at a certain point in time. The com.genesyslab.ail.ws.dn.DnAction enumeration lists the DN service’s actions.
The dn:actionsPossible attribute allows your application to retrieve the list of available DnAction for a DN at a certain time. DnEvent propagates this attribute when the possible DN actions are modified due to DN actions already performed.
The following table shows correspondence between DN actions and methods of the DN service.

DN Actions and Methods

DnAction	IDnService Method	Feature
SET_FORWARD	setForward()	Activate the Forward to another number.
CANCEL_FORWARD	cancelForward()	Cancel the Forward feature.
SET_DND_ON	setDNDOn()	Activate theDo Not Disturb feature.
SET_DND_OFF	setDNDOff()	Deactivate theDo Not Disturb feature.

The following subsections details how to implement the Forward and Do Not Disturb features.

Do Not Disturb (DND)

While the Do Not Disturb feature is activated, the DN does not accept calls.
Use thedn:dndStatus attribute value of the DN service to test whether the DND feature is activated:

• DnStatus.OFF—The DND feature is not activated.
  
• DnStatus.ON—The DND feature is activated.
  
• DnStatus.UNSPECIFIED—The switch cannot provide information.
  

Test the dn:actionsPossible attribute to determine which DND actions are possible.
The following code snippet shows how to activate and deactivate this feature for a DN identified by the string myDnId.

// Activating the Do Not Disturb feature for myDnId
myDnService.setDNDOn(myDnId,
   null, // tReasons 
   null); // tExtensions
//.....
// Deactivating the Do Not Disturb feature for myDnId
myDnService.setDNDOff(myDnId, null, // tReasons 
                              null); // tExtensions

Important

TExtensions and TReasons are switch-specific. Refer to your T-Server documentation for further information. See also Switch-Specific.

Forward
When the Forward feature is activated, the DN transfers any call received to a number that is specified when the feature is activated.
Use the dn:forwardStatus attribute value of the DN service to test whether the feature is activated:

• DnStatus.OFF—The Forward feature is not activated; dn:forwardNumber is null.
  
• DnStatus.ON—The Forward feature is activated; dn:forwardNumber contains the number receiving the forwarded calls.
  
• DnStatus.UNSPECIFIED—The switch can not provide information.
  

Test the dn:actionsPossible attribute to determine which Forward actions are possible.
The following code snippet shows how to activate and deactivate this feature for a DN identified by the string myDnId.

// Forwarding calls of myDnId to myDestinationNumber
myDnService.setForward(myDnId,
            myDestinationNumber,//string number receiving the transfer
            null,// tReasons
            null);// tExtensions
///....
// Cancelling the forward for myDnId
myDnService.cancelForward(myDnId,
           null, // tReasons
           null); //tExtensions

Important

TExtensions and TReasons are switch-specific. Refer to your T-Server documentation for further information. See also Switch-Specific.

Events of the DN Service

The DN service provides your application with two types of events, DnEvent and DnUserEvent, which are detailed below.

DnEvent

The DN service defines DnEvent for common events occurring on DN. To handle PlaceEvent, two important attributes are propagated:

• dn:dnId—String identifier of the DN involved.
  
• dn:eventReason—DnEventReason specifying the reason for the DnEvent.
  

The following table lists the existing DnEventReason and the associated attributes of the IDnService interface to take into consideration.

DnEventReason and Associated Attributes

DnEventReason	Associated Attribute	Attribute values
STATUS_CHANGED	dn:status	The current VoiceMediaStatus of the DN.
INFO_CHANGED	dn:TEventExtensions dn:TEventReasons	Switch specific-TEvent information.
DND_ON	dn:dndStatus	The DND feature has been turned on
DND_OFF	dn:dndStatus	The DND feature has been turned off.
ON_HOOK	dn:hookStatus	Telephone headset has been placed on-hook.
OFF_HOOK	dn:hookStatus	Telephone headset has been taken off-hook.
FORWARD_SET	dn:forwardStatus dn:forwardNumber	Updated status and number for the Forward feature.
FORWARD_CANCELED	dn:forwardStatus dn:forwardNumber	Updated status and number for the Forward feature.

DnUserEvent

The IDnService interface provides you with a sendUserEvent() method that enables your application to directly send information to the user registered on a DN.
The DN is used as a pipe, and the user application registered on the DN receives a DnUserEvent. The propagated dn.user-data:userData attribute contains the information in a key-value array.
The following code snippet sends a DnUserEvent to the dnId0; the information sent is contained in the myUserData key-value array.

// Writing information in a KeyValue array
KeyValue[] myUserData = new KeyValue[1];
myUserData[0]=new KeyValue();
myUserData[0].key= "myKeyString";
myUserData[0].value= "my message to send via dnId0";
// Sending the dn user event
myDnService.sendUserEvent(dnId0,myUserData);

Switch-Specific

DNs depend on the underlying switch. Your application might require some switch-specific features that are detailed below.

Warning

Managing some switch-specific features implies a dependency on this particular switch.

Workmodes

Agent actions use workmodes to provide more detailed information about the agent’s current state.

Workmode Types

The com.genesyslab.ail.ws.agent.WorkmodeType enumeration lists the available workmodes. Refer to the Agent Interaction SDK 7.6 Services API Reference to get this list. For example, the WorkmodeType.MANUAL_IN workmode indicates that the agent has to validate the action manually on the phone, and the WorkmodeType.AFTERCALLWORK workmode indicates the agent is still working on the last call.
Workmodes can be specified in forms that the agent service uses to perform some of the following agent actions: login, logout, ready, and notready. Forms for Voice Media.

Supported Workmodes

Switches do not always provide all the workmodes defined by the com.genesyslab.ail.ws.agent.WorkmodeType enumeration. See Switch Information.
The DN Service offers the dn:workmodesPossible attribute to retrieve the list of available workmodes for a DN at a certain time. The possible workmodes in this list take into account the DN status and the switch capability. During runtime, changes in DN status may affect this list.

Important

Use the dn:workmodesPossible attribute to enable and disable workmodes, and to refresh your application when a DnEvent occurs.

The following code snippet shows how to read the workmode for the dnId0 DN.

// Retrieving possible workmodes in a DTO for dnId0
DnDTO[] myDnDTOs = myDnService.getDnsDTO( new string[]{dnId0}, new string[]{"dn:workmodesPossible"});
 
// Displaying the DTO Content
foreach(DnDTO dto in myDnDTOs)
{
   System.Console.WriteLine(" Possible workmodes for "+dto.dnId);
   // Reading attributes retrieved in the DTO
   foreach(KeyValue pair in dto.data)
   {
      // Displaying the possible workmodes
      if(pair.key == "dn:workmodesPossible")
      {
         WorkmodeType[] myPossibleWorkmodes = (WorkmodeType[]) pair.value as WorkmodeType [];
         foreach(WorkmodeType type in myPossibleWorkmodes)
         {
            System.Console.WriteLine((type.ToString());
         }
      }
   }
}

T-Extensions and T-Reasons

T-Extensions and T-Reasons are switch-specific key-value pairs that you can use to fine-tune your application. Your application can pass T-Extensions and T-Reasons in arguments to method calls or get them from T-Server Events (if any).

Methods Call

The server-side application maps agent and DN services’ methods that take T-Extensions and T-Reasons in parameters with the T-Library. For T-Library users, the mapping of the T-Library features is straightforward, because the naming convention is similar to T-Library functions.
To determine which T-Extensions and T-Reasons to use, refer to your T-Server documentation.

T-Server Events

The server-side application can propagate T-Events with DnEvent. T-Extensions and T-Reasons can be optional in T-Events, so the server-side application copies them in the published dn:TEventExtensions and dn:TEventReasons attributes of the DN service only if they exist. Refer to your T-Server documentation for further information.

Switch Information

The dn:switchInfo attribute of the IDnService interface lets your application retrieve a SwitchInfo object.
The SwitchInfo class provides information about the switch associated with a DN:

• SwitchInfo.name—The identifier of the switch associated with this DN.
  
• SwitchInfo.switchType—The switch type.
  
• SwitchInfo.workmodeCapables—Array of workmode types that this switch supports.
  
• SwitchInfo.actionCapables—Array of InteractionVoiceAction that this switch supports.
  
Important
InteractionVoiceActions are actions of the voice interaction service applied to phone calls. See Voice Interactions.

The XxxCapables attributes list the switch’s supported features. These feature lists do not change during runtime. For example, if a workmode does not appear in the SwitchInfo.actionCapables attribute, the workmode is not supported. Therefore, this workmode will never appear in the list of possible workmodes and should not be visible for the agent using the DN.

Important

The list of DN’s possible workmodes (dn:workmodesPossible) takes into consideration the current DN’s status and the DN’s capable workmodes.