ESP Protocol
(Router – 3-rd Party Server Protocol)
This document describes primitives and logic for protocol “3rd-Party Server” used by server “MS-TServer” and client “Router”.
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.
Actually, it looks like general purpose RPC. Hence, as every RPC, we should define:
(We should accomplish all those tasks using Genesys framework).
There are many possible ways to find server, we are going to use first two feasible:
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.
So, to define ‘entry point’ we should provide:
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.
In the case or error response package contain fields ‘FaultCode’ and ‘FaultString’ in the output parameters list.
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’.
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.
## |
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 |
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.
Direction: from Router to MST
Request Name: Request3rdServer
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:
Direction: from MST to Router
Request Name: Event3rdServerResponse
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:
Direction: from MST to Router
Request Name: Event3rdServerFault
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. |
char |
yes |
String containing error code. |
Extensions. Envelope3rdServer.Parameters. |
char |
no |
Human-readable description of error. |
Comments:
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.
Direction: from MS-TServer to 3rd Party Server
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
Direction: from 3rd Party Server to MS-TServer
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
Direction: from 3rd Party Server to MS-TServer
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
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 …”;
};
};
};