ESP Protocol

(Router – 3-rd Party Server Protocol)

1       Abstract

This document describes primitives and logic for protocol “3rd-Party Server” used by server “MS-TServer” and client “Router”.

2       Overview

2.1    Protocol Purpose

Occasionally during strategy execution Router needs to interact with 3rd-party server. For example, on e-mail interaction, strategy is able to make decision based on Content Analysis server’s work. To do this, router needs to send request through MST to Content Analysis server, waits for response and process received results. In this process, MST works as transport bus.

 

Description: T:\icswc_source\Work\MessagingServer\Messaging_Server_802\src\com\genesyslab\mcr\smserver\channel\doc-files\Pic-1.png

 

Actually, it looks like general purpose RPC. Hence, as every RPC, we should define:

  1. How to find server;
  2. How to define ‘entry point’ – desired function on server side;
  3. How to encode/decode in/out parameters;
  4. How to supply information about errors

(We should accomplish all those tasks using Genesys framework).

2.2    Finding Server

There are many possible ways to find server, we are going to use first two feasible:

  1. 3-rd party server defined by AppName: Application Name field in Configuration Server;
  2. 3-rd party server defined by AppType: ‘CfgAppType’ (e.g. CFGContentAnalyzer). In this case it’s MST job to select appropriate server from connections list and provide load balancing.

2.3    Entry Point

We are going to use common well-known (DCE RPC, CORBA, DCOM, SOAP) object-oriented taxonomy: Server-Service-Method.

Physical server (executable) may provide one or more services. Service is a logically connected collection of methods. Method has a set of input/output parameters.

 

Description: T:\icswc_source\Work\MessagingServer\Messaging_Server_802\src\com\genesyslab\mcr\smserver\channel\doc-files\Pic-2.png

 

So, to define ‘entry point’ we should provide:

  1. Server identification: physical server ID or type of the server;
  2. Service name. If server supports only one service we can omit this attribute.
  3. Method name (in service namespace).  If service provides only one method we can omit this attribute.

2.4    Encoding/Decoding

All 3rd-party server’s attributes and parameters are packed into separate TKVList entry in Extensions: ‘Envelope3rdServer’.

Doing this way we avoid possible name collisions and minimize search time in a linear list. All method’s parameters are packed into next level TKVList: ‘Parameters’.

There are two types of packages: request and response. Response package should contain enough information to allow match request.  And also, response package may supply error information.

2.5    Error Information

In the case or error response package contain fields ‘FaultCode’ and ‘FaultString’ in the output parameters list.

2.6    Miscellaneous Details

2.6.1Versioning

For the purpose of future changes message should contain ‘Version’ filed. This field define protocol version as text string. The beginning of G7 version starts from “1.0’.

2.6.2Update User Data

User data field in the event contains context of interaction. Sometimes, 3-rd party server needs update this data. For this purpose response message should contain ‘UserData’ with new or updated fields. Router should check presence of this field and send appropriate ‘RequestUpdateUserData’ to T-Server.

3       List of messages

 

##

Name or request/Event

Direction

Comment

 

Request3rdServer

from Router to MST

Send to MST request for 3rd-party server operation

 

Event3rdServerResponse

from MST to Router

Returns results of 3rd-party server operation

 

Event3rdServerFault

from MST to Router

Supply error information about 3rd-party server operation failure

 

4       Description of messages

4.1    Required Common Fields

Two Tlib messages are used to support protocol RequestPrivateService and EventPrivateInfo.

TprivateService parameters

Value

TPrivateMsgType

Request3rdServer

TDirectoryNumber

The VRP to which the interaction was submitted.

TConnectionID

The interaction’s T-Server connection id.

extensions

A KVList with the details of the specific event.  See below for details.

user_data

A KVList with the details of the specific event.  See below for details.

 

EventPrivateInfo content

Value

TPrivateMsgType

 Event3rdServerResponse or Event3rdServerFault

TDirectoryNumber

The VRP to which the interaction was submitted.

TConnectionID

The interaction’s T-Server connection id.

ReferenceID

 

extensions

A KVList with the details of the specific event.  See below for details.

user_data

A KVList with the details of the specific event.  See below for details.

 

 

To differentiate these messages from others, not related to third-party protocol between Router and MS-Tserver,  TEvent field PrivateEvent (int) is used. It may have following values: Request3rdServer, Event3rdServerResponse, Event3rdServerFault.

Every message should contain commonly required field - ReferenceID.

4.2    Request3rdServer: Request for operation on 3rd-Party Server

Direction:          from Router to MST

Request Name: Request3rdServer

Parameters:

Parameter name

Type

Mandatory

Comment

Extensions. Envelope3rdServer

TKVList

yes

Key-value list contains all needed info to find 3rd-party server and execute operation

Extensions. Envelope3rdServer.Version

char

yes

Protocol version. Should be “1.0” for beginning of G7.

Extensions. Envelope3rdServer.AppName

char

no

Application Name field in Configuration Server for called 3rd-party server.

Extensions. Envelope3rdServer.AppType

int

no

Application type for called 3rd-party server. MST should find appropriate physical server to complete this request.

Extensions. Envelope3rdServer.Service

char

no

Called service name. Each 3rd-party server may contain more than one service. Service is a collection of methods. This parameter may be omitted if there is only one service in given server.

Extensions. Envelope3rdServer.Method

char

no

Called method name. May be omitted only if there is only one method in given service namespace.

Extensions. Envelope3rdServer.Parameters

TKVList

no

Parameters list. Optional if method doesn’t have any input parameters.

UserData

TKVList

no

Interaction data.

 

 

 

 

 

Comments:

4.3    Event3rdServerResponse: Return results of operation on 3rd-Party Server

Direction:          from MST to Router

Request Name: Event3rdServerResponse

Parameters:

Parameter name

Type

Mandatory

Comment

Extensions. Envelope3rdServer

TKVList

yes

Key-value list contains out-parameters

Extensions. Envelope3rdServer.Version

char

yes

Protocol version. Should be “1.0” for beginning of G7.

Extensions. Envelope3rdServer.AppName

char

no

Application Name field in Configuration Server for called 3rd-party server.

Extensions. Envelope3rdServer.AppType

int

no

Application type for called 3rd-party server.

Extensions. Envelope3rdServer.Service

char

no

Called service name.

Extensions. Envelope3rdServer.Method

char

no

Called method name.

Extensions. Envelope3rdServer.Parameters

TKVList

no

Output result and parameters list. Optional if method doesn’t have any output parameters.

UserData

TKVList

no

New or updated interaction data.

 

Comments:

4.4    Event3rdServerFault: Supply error information about operation failure

Direction:          from MST to Router

Request Name: Event3rdServerFault

Parameters:

Parameter name

Type

Mandatory

Comment

Extensions. Envelope3rdServer

TKVList

yes

Key-value list contains out-parameters

Extensions. Envelope3rdServer.Version

char

yes

Protocol version. Should be “1.0” for beginning of G7.

Extensions. Envelope3rdServer.AppName

char

no

Application Name field in Configuration Server for called 3rd-party server.

Extensions. Envelope3rdServer.AppType

int

no

Application type for called 3rd-party server.

Extensions. Envelope3rdServer.Service

char

no

Called service name.

Extensions. Envelope3rdServer.Method

char

no

Called method name.

Extensions. Envelope3rdServer.Parameters

TKVList

yes

Output result and parameters list.

Extensions. Envelope3rdServer.Parameters.
FaultCode

char

yes

String containing error code.

Extensions. Envelope3rdServer.Parameters.
FaultString

char

no

Human-readable description of error.

 

Comments:

 

5       Mapping to protocol MS-TServer – 3rd Party Server

Mapping all requests of 3rd-Party Server protocol to segment MS-TServer -- 3rd-Party Server is almost trivial: TKVList’s that represent request and User Data are send without changing. The only attribute that added is ReferenceID to accommodate asynchronous mode used by MS-TServer.

5.1    Request3rdServer

Direction:          from MS-TServer to 3rd Party Server

Element name   “Request3rdServer”

Parameters:

Parameter name

Type

Mandatory

Comment

ReferenceID

Integer

Yes

Request reference identifier

Envelope3rdServer

KVList

Yes

KVList that correspond Extensions. Envelope3rdServer KVList

UserData

KVList

No

User data from request

Responses:

-          Event3rdServerResponse if operation is executed successfully

-          Event3rdServerFault if unknown client type or invalid parameters

Comments: N/A

 

5.2    Event3rdServerResponse

Direction:          from 3rd Party Server to MS-TServer

Element name   “Event3rdServerResponse”

Parameters:

Parameter name

Type

Mandatory

Comment

ReferenceID

Integer

Yes

Event reference identifier same as was send in request Request3rdServer which this event is response for

Envelope3rdServer

KVList

Yes

KVList that correspond Extensions. Envelope3rdServer KVList that will be send in Event3rdServerResponse message to Router

UserData

KVList

No

User data – only properties that needs to be updated should be included here; if 3rd part server has nothing to update/attach, then the attribute should not present in the message

 

Comments: N/A

 

5.3    Event3rdServerFault

Direction:          from 3rd Party Server to MS-TServer

Element name   “Event3rdServerFault”

Parameters:

Parameter name

Type

Mandatory

Comment

ReferenceID

Integer

Yes

Event reference identifier same as was send in request Request3rdServer which this event is response for

Envelope3rdServer

KVList

Yes

KVList that correspond Extensions. Envelope3rdServer KVList that will be send in Event3rdServerFault message to Router

 

Comments: N/A

 

6       Appendix A. Example

Request:

Event = Request3rdServer;

ReferenceID = 1000000;

ConnID = 0x18c900e9bc7d7001;

Extensions = list of

{

Envelope3rdServer = list of

{

AppName = “Content_ Analysis_Woodland”; // Identify application using Configuration Server preconfigured application

Service = “ContentAnalysis”;

Method = “AnalyzeThis”;

Parameters = list of

{

UserEMail = “babay@ babay.net”;

Subject = “Order status”;

Content = “Could you please …”;

};

};

};

 

Response/Result:

Event = Event3rdServerResponse;

ReferenceID = 1000000

ConnID = 0x18c900e9bc7d7001

UserData = list of

{

NeededResponse=”mamay@babay.net”;

ResponseContent=”Dear Mamay, your request is …”

};

Extensions = list of

{

Envelope3rdServer = list of

{

AppName = “Content_ Analysis_Woodland”;

Service = “ContentAnalysis”;

Method = “AnalyzeThis”;

Parameters = list of

{

NeedsAction = “Send reply”;

UserEMail = “babay@ babay.net”;

Subject = “Order status”;

Content = “We are happy to provide …”;

};

};

};

 

Response/Fault:

Event = Event3rdServerFault;

ReferenceID = 1000000;

ConnID = 0x18c900e9bc7d7001;

Extensions = list of

{

Envelope3rdServer = list of

{

AppName = “Content_ Analysis_Woodland”;

Service = “ContentAnalysis”;

Method = “AnalyzeThis”;

Parameters = list of

{

FaultCode = “Server error”;

FaultString = “Internal error occurred at …”;

};

};

};