|
Genesys 8.1 SCXML Technical Reference |
||
< Application Server Relationship |
The orchestration platform and SDK will have a RESTful API which exposes the necessary interfaces to allow 3rd party applications to integrate with the orchestration application. The orchestration platform will support a set of RESTFul Web 2.0 Web Services APIs. These APIs allow an external application to do the following interaction with SCXML sessions:
<response>
element. These external interfaces have equivalent functionality in SCXML and the associated functional modules. The following table reflects the mapping between the two.
External RESTful APIs |
SCXML or Functional Module Function |
---|---|
http://<server:port>/scxml/session/start |
<session:start> |
http://<server:port>/scxml/session/<session id>/terminate |
<session:terminate> |
http://<server:port>/scxml/session/<session id>/event/<name>[?<parameters>] |
<scxml:send> |
http://<server:port>/scxml/session/<session id>/request/<name>[?<parameters>] |
<session:fetch> |
http://<server:port>/scxml/session/<session id>/query |
none |
This API starts a new SCXML session for a specific application. The "src" parameter is mandatory. All of the other parameters are optional.
http://<server:port>/scxml/session/start[?<parameters>] |
||
---|---|---|
HTTP Verbs |
PUT |
Not used |
POST |
Used to start a given session. (supported Content-Type - application/x-www-form-urlencoded) |
|
DELETE |
Not used |
|
URI-Variable Elements |
none |
|
Request-URI Parameters |
src |
URL of the SCXML document to use for the new session. |
idealtime |
A dateTime value which will represent the date and time that this session is to be started. This value should be the time as returned by the ECMAScript Date(...).getTime() function, which is given in the number of milliseconds since 00:00:00 UTC on January 1, 1970. |
|
request-specific |
These are request-specific parameters. These parameters will be put in the appropriate session data items ( |
|
results |
A URI value which will represent a callback URL that accepts the results of a scheduled session start, whether it has positive or negative results. This URL will be invoked with the HTTP POST method. The content of the document body will be the following:
|
|
Document Body |
application/x-www-form-urlencoded |
The same as for the Request-URI parameters |
Positive Response (200 Response) |
ID |
The identifier of the newly created session. |
Negative Response |
HTTP Error Code |
HTTP 4xx |
Example |
GET http://<server:port>/scxml/session/start?src=http://appserver/appname.scxml |
This API terminates a SCXML session.
http://<server:port>/scxml/session/<session id>/terminate[?<parameters>] |
||
---|---|---|
HTTP Verbs |
PUT |
Not used |
POST |
Stops an existing session. |
|
DELETE |
Not used |
|
URI-Variable Elements |
session id |
This identifies the session which is to be stopped. |
Document Body |
none |
none |
Positive Response (200 Response) |
OK |
OK |
Negative Response |
HTTP error code |
HTTP 4xx |
Example |
POST http://<server:port>/scxml/session/1234567/terminate |
This API queries a given SCXML session's data.
http://<server:port>/scxml/session/<session ids>/query |
||
---|---|---|
HTTP Verbs |
PUT |
Not used |
POST |
Query a set of existing sessions. |
|
DELETE |
Not used |
|
URI-Variable Elements |
session ids |
This identifies the set of sessions which are to be queried. The session ids are separated by a "," For example, |
Request-URI Parameters |
none |
|
Document Body |
none |
none |
Positive Response (200 Response) |
sessionData |
This is a list of sessions and their associated data. The following is the JSON-formatted set of session data which will be returned for each session in the list:
|
Negative Response |
HTTP error code |
404 Not found |
Example |
POST http://<server:port>/scxml/session/1234567/query |
This API sends a request to the SCXML session to process.
http://<server:port>/scxml/session/<session id>/request/<name>[?<parameters>] |
||
---|---|---|
HTTP Verbs |
PUT |
Not used |
POST |
Send a request to an existing session. |
|
DELETE |
Not used |
|
URI-Variable Elements |
session id |
This is the session which the request is targeted for. |
name |
This is the name of the request which is to be performed by the SCXML session when it receives the corresponding request event. This value will be the name of the SCXML event which the SCXML session will process. |
|
Request-URI Parameters |
request-specific |
These are request-specific parameters. These parameters will be put into the SCXML event at the following location: _event.data.param.xxx. For example, if you have the following URI parameters, ?p1=12355&p2=abcd, then the following will be the structure in the event: _event.data.param.p1 and _event.data.param.p2. In addition, there will be a parameter which specifies the content type for the parameters and it will be set to "application/x-www-form-urlencoded". The use of these parameters is mutually exclusive with the use of the document body parameters. |
Special Parameters |
request identifier |
This API-related parameter is generated by the orchestration platform when it gets the HTTP request. It is used to correlate the requests and the corresponding responses for a given session. This identifier is put in the sendid property of the request's SCXML event (that is, _event.sendid) when sent to the application. This identifier must be used in the corresponding |
Document Body |
application/x-www-form-urlencoded application/json text/xml |
In addition to specifying parameters in the URL, they can alternatively be put into the document body. The use of these parameters is mutually exclusive with the use of the URI-based parameters. For details see the API Parameter passing section. |
Positive Response (200 Response) |
results |
This is a set of data, based on the results of the request. It is request-specific in its content. The SCXML session sends this data via the |
Negative Response |
HTTP error code |
HTTP 4xx |
Example |
POST http://<server:port>/scxml/session/1234567/request/getxData?parm1=john The SCXML session must have the following SCXML snippet somewhere in its definition. This type of request processing SCXML snippet is probably best placed as a global document event handler. <transition event="getxData" cond="_event.data.param.parm1 = ''" > <ws:response requestid="_event.sendid" type="negative" resultcode="invalidparameter"/> </transition> <transition event="getxData" cond="_event.data.param.parm1 != ''" > <script> var rdata = _getdata(_event.data.param.parm1); </script> <ws:response requestid="_event.sendid" > <param name="results" expr="rdata"/> </ws:response> </transition> |
|
Special Considerations |
It is recommended that the orchestration logic for processing this event should be processed within the executable content of the |
This API sends an event to an existing session.
http://<server:port>/scxml/session/<session id>/event/<name>[?<parameters>] |
||
---|---|---|
HTTP Verbs |
PUT |
Not used |
POST |
Send an event to an existing session. |
|
DELETE |
Not used |
|
URI-Variable Elements |
session id |
This is the session which the event is targeted for. |
name |
This is the name of the event which is to be sent to the SCXML session. This value will be the name of the SCXML event which the SCXML session will process. |
|
Request-URI Parameters |
request-specific |
These are event-specific parameters. These parameters will be put into the SCXML event at the following location: _event.data.param.xxx. For example, if you have the following URI parameters, ?p1=12355&p2=abcd, then the following will be the structure in the event: _event.data.param.p1 and _event.data.param.p2. In addition, there will be a parameter which specifies the content type for the parameters and it will be set to "application/x-www-form-urlencoded". The use of these parameters is mutually exclusive with the use of the document body parameters. |
Document Body |
application/x-www-form-urlencoded application/json text/xml |
In addition to specifying parameters in the URL, they can alternatively be put into the document body. The use of these parameters is mutually exclusive with the use of the URI-based parameters. For details see the API Parameter passing section. |
Positive Response (200 Response) |
none |
Note: Returned immediately. |
Negative Response |
HTTP error code |
HTTP 4xx |
Example |
POST http://<server:port>/scxml/session/1234567/event/xisDone?parm1=john The SCXML session must have the following SCXML snippet somewhere in its definition. This type of request-processing SCXML snippet is probably best placed as a global document event handler. <transition event="xisDone" target="continuewithY" > <! — Do some processing here ..../> </transition> |
SCXML sessions are able to send an arbitrary Web 2.0 request to an external Web 2.0 service using <fetch>
. See the <fetch>
SCXML sessions are able to send an arbitrary Web 2.0 event to an external Web 2.0 service using <send>
. See the
<send>
section for details.
The major difference between <fetch>
and <send>
is that in the case of <send>
no SCXML response event is expected after it has been invoked.
The status of the orchestration platform can be obtained simply by using a GET HTTP request. The following are the URLs for different types of platform status. The results from the request are in XML.
URL |
Type |
Results |
---|---|---|
<Orch platform server>:<port> |
Basic data |
|
<Orch platform server>:<port>/server?cfgStatistics |
Configuration data |
|
<Orch platform server>:<port>/server?activeCalls |
Interaction data |
|
<Orch platform server>:<port>/server?scxmlStat |
SCXML engine data |
|
<Orch platform server>:<port>/serverx?activeApplications |
SCXML Application data |
For each active application, the following information is provided:
|
Parameters are passed from the Web 2.0 APIs to the SCXML session using two basic mechanisms. These mechanisms are mutually exclusive:
GET http://<server:port>/scxml/session/<session id>/event/<name>?param1=1¶m2=2
Or in the document body:
POST http://<server:port>/scxml/session/<session id>/event/<name> .. . . Content-type: application/x-www-form-urlencoded . . . param1=1¶m2=2
In both cases, URL encoded parameters will be translated to properties of the SCXML event:
_event.data.param.param1 = 1 _event.data.param.param2 = 2
The _event.data.paramtype will be set to application/x-www-form-urlencoded.
In the case of the http://<server:port>/scxml/session/start
API (Start Session), the following processing will be done:
<data>
element in the data model of the started session, then the value of the parameter will replace the value of the corresponding <data>
element. POST http://<server:port>/scxml/session/<session id>/event/<name> ... Content-Type=application/json Content-Length=xx ...param="{ "firstName": "John", "lastName": "Smith", "address": { "streetAddress": "21 2nd Street", "city": "New York", "state": "NY", "postalCode": 10021 }, "phoneNumbers": [ "212 555-1234", "646 555-4567" ] }"
An SCXML application may process these parameters by evaluating JSON text to ECMAScript objects.
In the case of the http://<server:port>/scxml/session/start
API (Start Session), the following processing will be done:
<data>
element in the data model of the started session, then the value of the parameter will replace the value of the corresponding <data>
element. POST http://<server:port>/scxml/session/<session id>/request/<name> ... Content-Type=text/xml Content-Length=xx ...param=" <findCar> <make>Dodge</make> <model>Daytona</model> </findCar> "
An SCXML application may process this parameter using ECMAScript XML capabilities.
In the case of the http://<server:port>/scxml/session/start
API (Start Session), the following processing will be done:
<data>
element in the data model of the started session, then the value of the parameter will replace the value of the corresponding <data>
element.
|
Genesys 8.1 SCXML Technical Reference |
||
< Application Server Relationship |