ENetUC_Agent.asn1

UC-Server-Access-Protocol-Agent
	{ iso(1) identified-organization(3) dod(6) internet(1) private(4) enterprise(1) estos(10924) uc-server-access-protocol-v2(2) agent(17) }

-- @category Agent
-- @brief Agent/AgentGroup/ACD interface.
-- @long
-- 
-- 
-- ## Module description
-- This module describes the functions for agents for ACD and contact portal functionalities.
--
-- A client represents a user who can be an member in any number of agent groups.<br />
-- An agent is described by the ContactURI of the user (SIP address incl. "sip:" before) or a LineURI (Cti line, format "tel:xyz@pbx text").
-- To login to a group, for example, you usually need the AgencyURI and the GroupURI. This allows the UCServer to identify exactly which agent should be used in which group.<br />
-- The client receives the necessary values when it gets them back as a result of asnAgentMonitorStart.
-- 
-- ### Requirements for using the interface
-- A user gets access to the agent interface:
-- - If the user has activated the service "Business card for anonymous users" via his own or global profile in the UCServer administration.
-- - If he is a member of one or more groups that have been activated in the UCServer administration as an "agent group".
-- - If (identified by line ID) he has a line known to be part of an ACD group at the corresponding ECSTA.
-- 
-- ### Functions
-- A user can set the following status on the interface:
-- - "login"/"logout"
-- - "Working after call"
-- - "ready"/"not ready" (still a "work in progress")
-- 
-- ProCall 5.1 supports ACD functionality only for Panasonic telephone systems.<br />
-- As of ProCall 6, the agent interface is used for the contact portal and business card. Further PBX's are in development.
--
-- ## Simple procedure if the agent groups are to be used ##
-- 1. The user must only call asnAgentMonitorStart; this registers the agent's events and supplies the list of groups in which the user is agent.
-- 2. From this point on, the UCServer sends events if the status of the user in these groups changes.
-- 3. Change the state of the agent:
-- 3.1. asnAgentLogin - Sets the status of the user to "login". Note: replaces asnAgentSetState(not ready).
--      More parameters may be required for the login. These can be found in the AgentGroupInfos
-- 3.2. asnAgentLogoff - Sets the status of the user to "logoff". Note: replaces asAgentSetState(noagent).
-- 3.3. asnAgentSetState - With this you can set the status to "ready", "not ready" and "working after call". Which states can be set is provided by the server in the result of asnAgentMonitorStart. See also AsnAgentGroupInfo.
-- 4. Log off events with asnAgentMonitorStop.
--
-- With these five functions it is possible to operate the ACD/presence groups on the UCServer.
-- 
-- ## AsnAgentGroupInfo
-- AsnAgentGroupInfo structures are usually exchanged in the analysis and results. This structure contains the description of an agent/ACD group.<br />
-- AsnAgentGroupInfo contains the data about an agent group. The following are important:
-- - iGroupCapabilities: This shows which status changes are supported. See also AsnAgentGroupCapabilitiesEnum. If the highest bit is set (0x80000000), this group is a PBX/ACD group. If the bit is not set, the group is managed by the UCServer.
-- - iAgentState: The current status of the agent, i.e. the user in this group.
-- - optionalParams,key "AgentLoginRequiredParameters": In the case of a PBX/ACD group, this integer contains information about which parameters are required for logging on to the ACD group. The values (bit field) are described in AsnAgentLoginRequiredParametersEnum.
--
-- 
-- ## Events
-- For any changes to the agent groups and agent status, two events are sent by the UCServer to the registered clients:
-- - asnAgentNotifyGroupsChanged - There have been some changes in the user's available groups
-- - asnAgentNotifyStateChanged - The user's status in a group has changed.
--
-- ## Comment
-- The API is user centered. This means if the server is asked for the AgentGroupInfos, 
-- the server displays the information concerning its group membership in a simple list.
-- The most simple for the normal user.
--
-- ## Supervisor Interface
-- Not implemented yet.
--
-- ## Anonymous users
-- Anonymous users can query which groups are available, including users, and then display the corresponding presence and login/logoff status based on the use case.
--

DEFINITIONS
IMPLICIT TAGS ::=
BEGIN

IMPORTS
AsnOptionalParameters, AsnRequestError, UTF8StringList FROM UC-Server-Access-Protocol-Common
AsnAgentACDLoginData FROM UC-Server-Access-Protocol-AgentServices
;

-- @brief AsnAgentGroupInfo encapsulates the data for an agent (ACD) group from the agent's point of view.
--
-- @long 
-- An AsnAgentGroupInfo can only be uniquely identified with the combination of u8sAgentURI and u8sGroupURI.
--
-- ## OptionalParameters - Subsequent Enhancements to the data structure ## 
-- - "PhoneNumber" String phone number to be displayed in the client; only server to client.
-- - "AgentLoginRequiredParameters" DWORD bit flags that indicate which data the PBX requires for the user/line logon. Only sent server to client. Not filled for contact portal/business card. See AsnAgentLoginRequiredParametersEnum.
-- - "SupportedAgentStates" DWORD bit flags indicating which agents status values can be used in this group. Only sent server to client. See also AsnSupportedAgentStatesEnum.
--
AsnAgentGroupInfo ::= SEQUENCE
{
	-- URI of the group agent (LineURI or ContactURI) e.g. "tel:+4912345678;phys=678@ECSTA for OpenScape Business" or "sip:test.tester@test.de"
	u8sAgentURI						UTF8String, 

	-- URI of the group (e.g. "pbxg:601@ECSTA for Panasonic" or "sip:mygroup@estos.de").
	u8sGroupURI						UTF8String, 
	
	-- Display name of the group.
	u8sDisplayName					UTF8String, 
	
	-- This shows which status changes are supported. See also AsnAgentGroupCapabilitiesEnum.
	-- If the highest bit is set (0x80000000), this group is a PBX/ACD group. 
	-- If the bit is not set, the group is managed by the UCServer.
	-- See AsnAgentGroupCapabilitiesEnum.
	iGroupCapabilities				INTEGER,    
	
	-- Agent status of the agent within the group as defined in AsnAgentStateEnum.
	-- See AsnAgentStateEnum.
	iAgentState						INTEGER,    
												
	-- OptionalParameters - Subsequent extensions to the data structure 
	-- - "PhoneNumber" String phone number for display in client; only server to client.
	-- - "AgentLoginRequiredParameters" DWORD bit flags that indicate which data the PBX requires for the user/line logon. Only sent server to client. Not filled for contact portal/business card. See AsnAgentLoginRequiredParametersEnum.
	-- - "SupportedAgentStates" DWORD bit flags indicating which agents status values can be used in this group. Only sent server to client. See AsnSupportedAgentStatesEnum.
	optionalParams					[0] AsnOptionalParameters OPTIONAL,
	...
}

-- @brief Bit field values for the OptionalParameter "AgentLoginRequiredParameters" in AsnAgentGroupInfo.
-- @long 
-- Defines the bits that a PBX can set to request specific credentials from the user.
AsnAgentLoginRequiredParametersEnum ::= ENUMERATED
{
	eAGENTLOGINREQUIRESAGENTID(1),	-- AgentID Required (for example, the PIN)
	eAGENTLOGINREQUIRESGROUPID(2),	-- GroupID Required
	eAGENTLOGINREQUIRESPASSWORD(4), -- Password Required
	eAGENTLOGINREQUIRESDEVICEID(8)	-- DeviceID Required
}

-- @brief Bit field values for the optional parameter "SupportedAgentStates" in AsnAgentGroupInfo.
-- @long 
-- These bits indicate which states are supported for agents in the group.
-- If others are set, it is up to the PBX/ACD/UCServer to decide what the result will be, or whether it is rejected with an error.
-- To set or read the current value for an agent, use the values in the AsnAgentStateEnum.
AsnSupportedAgentStatesEnum ::= ENUMERATED
{
	eAGENTSTATELOGGEDOUT(1),				-- "logout" / "no agent"
	eAGENTSTATELOGGEDINNOTREADY(2),			-- "not ready"
	eAGENTSTATELOGGEDINREADY(4),			-- "ready"
	eAGENTSTATELOGGEDINBUSY(8),				-- "busy"
	eAGENTSTATELOGGEDINWORKINGAFTERCALL(16) -- "working after call"
}

-- @brief The possible states the agent can have.
-- @long 
-- This is the state of the agent; hence it is an integer and not a bit field.
-- This value is to be used for server messages as well as for setting these states.
AsnAgentStateEnum ::= ENUMERATED
{
	eAGENTSTATENOAGENT(0),			-- Agent logged out from group - (is set implicitly at AgentLogoff() by the server)
	eAGENTSTATENOTREADY(1),			-- Agent unavailable
	eAGENTSTATEREADY(2),			-- Agent available in group - (is initially set at AgentLogin() by the server)
	eAGENTSTATEBUSY(3),				-- Agent is busy
	eAGENTSTATEWORKINGAFTERCALL(4)	-- Agent is working after a call
}

-- The agent group supports a combination of the following agent states.
--
-- The highest DWORD bit indicates whether it is a PBX ACD group or not.
--
-- eAGENTCAPISPBXACDGROUP(2147483648, 0x80000000) This agent group is an ACD group in a PBX; unfortunately there is a problem with the tool which prevents the conversion of this ENUM value into .Net.
AsnAgentGroupCapabilitiesEnum ::= ENUMERATED
{
	-- (0x01) "login" is supported
	eAGENTCAPSUPPORTEDAGENTREQUESTSLOGIN(1),
	
	-- (0x02) "logout" is supported / same as state eAGENTSTATENOAGENT
	eAGENTCAPSUPPORTEDAGENTREQUESTSLOGOUT(2),
	
	-- (0x04) "not ready" is supported
	eAGENTCAPSUPPORTEDAGENTREQUESTSNOTREADY(4),
	
	-- (0x08) "ready" is supported
	eAGENTCAPSUPPORTEDAGENTREQUESTSREADY(8),
	
	-- (0x10) "busy" is supported
	eAGENTCAPSUPPORTEDAGENTREQUESTSBUSY(16),
	
	-- (0x20) "working after call" is supported
	eAGENTCAPSUPPORTEDAGENTREQUESTSWORKINGAFTERCALL(32),
	
	-- (0xff) (currently not supported)
	eAGENTCAPSUPPORTEDAGENTREQUESTSMASK(255),
	
	-- (0x20000000) The group is a (Contact)Portal Group
	eAGENTCAPISPORTALGROUP(536870912),

	-- (0x40000000) The agents in this group can handle PUBLIC-CHATs
	-- See AsnConversationType.
	eAGENTCAPISPUBLICCHATGROUP(1073741824) 					

	-- (0x80000000) This agent group is an ACD group in a PBX;
	-- Unfortunately, there is a problem with the tool that prevents the conversion of this ENUM value into .Net.
	-- (hence commented out)
	-- eAGENTCAPISPBXACDGROUP(2147483648) 					
}


-- @brief List of Agent Groups
AsnAgentGroupInfoList ::= SEQUENCE OF AsnAgentGroupInfo

-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- ~~~~~~~~~~~~~~~~~~~~~~~ asnAgentMonitorStart ~~~~~~~~~~~~~~~~~~~~~~~
-- 
AsnAgentMonitorStartArgument ::= SEQUENCE
{
	-- Agent URI e.g. "sip:xyz@domain.de". An empty string is supplemented by the UCServer with the ID of the logged on user.
	u8sAgentURI				UTF8String,
	...
}

-- 
AsnAgentMonitorStartResult ::= SEQUENCE
{
	u8sMonitorCrossRefID		UTF8String,				-- CrossrefID for the associated events
	listGroups					AsnAgentGroupInfoList,
	...
}

-- @brief Agent Monitor Start
-- @long 
-- This function starts monitoring for all groups of a client.
-- The individual lines (for PBX ACD groups) and the individual user and group configurations are taken into account (for business card/contact portal).
asnAgentMonitorStart OPERATION
	ARGUMENT	arg AsnAgentMonitorStartArgument
	RESULT		res AsnAgentMonitorStartResult
	ERRORS		{AsnRequestError}
::= 1902

-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- ~~~~~~~~~~~~~~~~~~~~~~~ asnAgentMonitorStop ~~~~~~~~~~~~~~~~~~~~~~~
-- The CrossRefID that was returned by the server at asnAgentMonitorStart.
AsnAgentMonitorStopArgument ::= SEQUENCE
{
	u8sMonitorCrossRefID				UTF8String,
	...
}

-- This structure is only restored if successful. If the call is unsuccessful, it will return an AsnRequestError.
AsnAgentMonitorStopResult ::= SEQUENCE
{
	...
}

-- @brief Agent Monitor Stop
-- @long 
-- End monitoring for the specified CrossRefID
asnAgentMonitorStop OPERATION
	ARGUMENT	arg AsnAgentMonitorStopArgument
	RESULT		res AsnAgentMonitorStopResult
	ERRORS		{AsnRequestError}
::= 1903

-- @brief Parameters for Agent Login
-- @long 
-- Parameters for logging in to the agent/ACD functionality of the PC server (business card, contact portal) or the telephone system.
AsnAgentLoginArgument ::= SEQUENCE
{
	-- Group agent URI (LineURI or ContactURI) e.g. "tel:" or "sip:".
	-- If the URI starts with "tel:", the login is transferred to the specified line and then to the telephone system.
	-- "sip:" indicates that the user is logging in for the contact portal/business card.
	-- The information can be obtained from the AsnGroupInfo
	u8sAgentURI						UTF8String, 

	-- Group URI (e.g. "pbxg:601@ECSTA for Panasonic" or "sip:mygroup@estos.de").
	-- This identifies the group to which the user is to be logged in to.
	-- The information can be obtained from the AsnGroupInfo.
	u8sGroupURI						UTF8String, 

	-- For PBX ACD, additional data may be required for login. See AsnAgentACDLoginData for details.
	acdLoginData					[0] AsnAgentACDLoginData OPTIONAL,

	...
}

-- @brief Result for agent login
-- @long 
-- If the server returns the result, the login was successful.
-- If the login fails, the AsnRequestError is returned as the result.
-- This contains more details about the error.<br />
-- This structure is only returned if successful. If the call is unsuccessful, AsnRequestError is returned.
AsnAgentLoginResult ::= SEQUENCE
{
	...
}

-- @brief Login for the agent/ACD functionality on a line or group.
-- @long 
-- This function ensures that the user is logged in to the agent or ACD group.
asnAgentLogin OPERATION
	ARGUMENT	arg AsnAgentLoginArgument
	RESULT		res AsnAgentLoginResult
	ERRORS		{AsnRequestError}
::= 1904

-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- ~~~~~~~~~~~~~~~~~~~~~~~ asnAgentLogoff ~~~~~~~~~~~~~~~~~~~~~~~
-- @brief Argument for agent logoff(Automatic Call Distribution)
AsnAgentLogoffArgument ::= SEQUENCE
{
	u8sAgentURI						UTF8String, -- Group agent URI (LineURI or ContactURI) e.g. "tel:" or "sip:"
	u8sGroupURI						UTF8String, -- Group URI (e.g. "pbxg:601@ECSTA for Panasonic" or "sip:mygroup@estos.de").
	...
}

-- @brief Result for agent logoff 
-- This structure is only returned if successful. If the call is unsuccessful, an AsnRequestError is returned.
AsnAgentLogoffResult ::= SEQUENCE
{
	...
}
-- @brief Logoff agent for ACD(Automatic Call Distribution)
-- @long 
asnAgentLogoff OPERATION
	ARGUMENT	arg AsnAgentLogoffArgument
	RESULT		res AsnAgentLogoffResult
	ERRORS		{AsnRequestError}
::= 1905

-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- ~~~~~~~~~~~~~~~~~~~~~~~ asnAgentSetState ~~~~~~~~~~~~~~~~~~~~~~~

-- @brief Set new Agent State
AsnAgentSetStateArgument ::= SEQUENCE
{
	-- Group agent URI (LineURI or ContactURI) e.g. "tel:" or "sip:"
	u8sAgentURI						UTF8String, 
	
	-- Group URI (e.g. "pbxg:601@ECSTA for Panasonic" or "sip:mygroup@estos.de").
	-- The information can be obtained from the AsnGroupInfo.
	u8sGroupURI					[0] UTF8String OPTIONAL, 
	
	-- Agent status of the agent to be set as defined in AsnAgentStateEnum.
	iAgentState						INTEGER,    
	...
}
-- @brief Result for AsnAgentSetState
-- This structure is only returned if successful. If the call is unsuccessful, an AsnRequestError is returned.
AsnAgentSetStateResult ::= SEQUENCE
{
	...
}

-- @brief Agent for setting the ACD status (call distribution)
-- @long
-- ACD means Automatic Call Distribution and is a system for the automated control of incoming and outgoing customer interactions, 
-- such as calls, faxes and e-mails
asnAgentSetState OPERATION
	ARGUMENT	arg AsnAgentSetStateArgument
	RESULT		res AsnAgentSetStateResult
	ERRORS		{AsnRequestError}
::= 1906

-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- ~~~~~~~~~ asnAgentNotifyGroupsChanged ~~~~~~~~~~~~~~~~~~~~~~~

-- @brief Argument contains the CrossRefID for which the event is sent and the list of the user's agent groups.
AsnAgentNotifyGroupsChangedArgument ::= SEQUENCE
{
	u8sMonitorCrossRefID			UTF8String,
	listGroups						AsnAgentGroupInfoList,		-- complete List of groups
	...
}

-- @brief The event for changes to the user's agent groups.
-- @long
-- The entire list of the user's agent groups is always transmitted.
-- Groups may have been removed or added, or the properties of a group may have changed.
-- This event is not used for AgentState changes
asnAgentNotifyGroupsChanged OPERATION
	ARGUMENT	arg AsnAgentNotifyGroupsChangedArgument
::= 1950

-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- ~~~~~~~~~ asnAgentNotifyStateChanged ~~~~~~~~~~~~~~~~~~~~~~~
-- @brief Argument for AgentNotifyStateChanged. Included is the CrossRefID for which the event is transmitted, the AgencyURI and GroupURI (unique agent group assignment) and the new agent state.
AsnAgentNotifyStateChangedArgument ::= SEQUENCE
{
	u8sMonitorCrossRefID			UTF8String, -- CrossrefID for associated events
	u8sAgentURI						UTF8String, -- Agent group URI (LineURI or ContactURI)
	u8sGroupURI						UTF8String, -- Group URI- must be unique in the UCServer
	iAgentState						INTEGER,    -- AgentState of the agent in the group
	...
}
-- @brief Event when the state of the agent in a group has changed.
asnAgentNotifyStateChanged OPERATION
	ARGUMENT	arg AsnAgentNotifyStateChangedArgument
::= 1951


-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- ~~~~~~~~~ asnAgentNotifyAnonymousBlockedChanged ~~~~~~~~~~~~~~~~~~~~~~~
-- @brief Argument for AgentNotifyAnonymousBlockedChanged.
AsnAgentNotifyBlockedRTCChangedArgument ::= SEQUENCE
{
	-- list of all blocked users
    listu8sBlockedUserURIs    	UTF8StringList,     
	...
}
-- @brief Event dispatched if blocked state was changed for anonymous user
-- The argument contains all anonymous user URIs which are currently blocked for the notified agent
asnAgentNotifyBlockedRTCChanged OPERATION
	ARGUMENT	arg AsnAgentNotifyBlockedRTCChangedArgument
::= 1961

END