Professional Documents
Culture Documents
SCXML Based AD
SCXML Based AD
SCXML Based AD
1 (17)
Prepared by No.
12/01/2015 1a
Release: 1.0
22222222 MAVENIR INTERNAL
2 (17)
Prepared by No.
12/01/2015 1a
CONTENTS
RELEASE: 1.0...................................................................................................................1
REVISION HISTORY.........................................................................................................4
1 INTRODUCTION..........................................................................................................5
1.1 Target Audience......................................................................................................................................................5
1.2 Purpose....................................................................................................................................................................5
1.3 Acronyms................................................................................................................................................................5
1.4 References...............................................................................................................................................................5
3 SME PACKAGES.........................................................................................................9
5 SCXML SERVICE.......................................................................................................11
5.1 Initializing SME....................................................................................................................................................11
12/01/2015 1a
8 EXAMPLE SCXML.....................................................................................................15
12/01/2015 1a
Revision History
12/01/2015 1a
1 Introduction
1.1 Target Audience
This document is intended to be a reference guide for developers implementing SCXML based
applications.
1.2 Purpose
SCXML or State Chart XML is an XML-based markup language that provides a generic state-
machine based execution environment. Mavenir’s State Machine Engine (SME) framework
interprets and executes application logic written using SCXML.
This document provides an introduction to the SME framework and shows how to implement new
application packages and commands based on SME. The list of currently supported packages and
commands are also listed. Additionally, the deviations of the SME implementation w.r.t the SCXML
standard and the non-standard extensions to SCXML that have been adopted are mentioned in this
document.
1.3 Acronyms
SCXML – State Chart Extensible Markup Language
SME – State Machine Engine
1.4 References
[1] http://www.w3.org/TR/scxml/
[2] http://en.wikipedia.org/wiki/SCXML
[3] Reference code can be found at – mmx/sme, vendor/expreval, appCommon/smepkgs,
tas/vmAsMgr/vmAsApp/services/scxmlsvc
12/01/2015 1a
Application SMEStateMachineEngine
initialize
registerPackage
registerPackage
registerDefintions
parseStateMachine
2. As part of application startup, it will read the SCXML buffers from DB and input them to
SME through parseStateMachine API. SME parses them and creates a state machine
structure. Parsed output will look like below.
77777777 MAVENIR INTERNAL
7 (17)
Prepared by No.
12/01/2015 1a
Each of the scxml buffer will translate to one StateMachine structure, which contains one or
more States. Each state in turn contains optional onentry, optional onexit blocks and a set of
transitions and a set of invokescxml commands.
Onentry and Onexit blocks are executable contents containing one or more commands to
execute. Transitions specify an event on which transition should occur and an executable
content block to be executed before transition. Invokescxml command is used to start
executing another statemachine. Parameters can be passed to invoke a scxml.
All expressions present in conditional statements, assign, log, invokescxml are parsed and
executed using a 3rd party expression evaluation library (present in the following cvs path
vendor/expreval).
3. SME RunTime:
Following flow represents the interaction b/w application and SME at run time.
88888888 MAVENIR INTERNAL
8 (17)
Prepared by No.
12/01/2015 1a
1: create
2: createContext(ISMEAppContext)
3: createContext
4: create
5: ISMEStateMachineContext
6: ISMEStateMachine, ISMEStateMachineContext
7: begin(ISMEStateMachineContext)
9: return (StateMachineStateEn)
12: return(StateMachineStateEn)
on getting
STATEMACHINE_END
13: releaseContext(ISMEStateMachineContext)
14: delete
12/01/2015 1a
4. Package commands:
SME allows various packages to plugin their functionality by providing command objects which are
parsed and executed along with SME basic commands. These extension commands are provided by
registered packages.
3 SME Packages
A package is a set of SCXML executables or commands which work together to implement a
specific functionality. Each package has a unique namespace associated with it.
A package can be generic enough to be reused across many applications or may be specific to an
application. All generic packages are implemented and placed under appCommon/smepkgs in the
branch APPCMN-R6. All application specific packages can be placed under the application’s code
hierarchy.
For example, a set of commands can be created for database interaction and grouped under the
database package. Some examples of commands under the database package –
<database:loadprocedure procname="$ProcedureName"/>
As shown in above example, all commands belonging to the database package have the “database:”
prefix or namespace.
12/01/2015 1a
Whenever SME encounters a package command when parsing the SCXML, it calls
createPackageCommandHandle() on the registered package implementation class to create a
command object. Please note that each package implementation class provides its own
implementation for createPackageCommandHandle() to create all the command objects supported by
the package. Once the command object is created by the package and returned to SME, preProcess()
is called by the SME on the command object.
The function execute() SME calls execute() on the command object at runtime when the
corresponding SCXML command is encountered.
getEventName() is called by SME to get the name of the event. getEventParam() is called by SME
whenever SCXML accesses event data (using syntax of the form $_event.xxxx).
5 SCXML Service
In VMAS application, the SCXML service module is responsible for initializing SME at startup and
for driving the execution of the SME at runtime for every call/session. SCXML service delivers
1111111111111111 MAVENIR INTERNAL
11 (17)
Prepared by No.
12/01/2015 1a
events from the application to SME and vice versa. Reference code can be found at
tas/vmAsMgr/vmAsApp/services/scxmlsvc in branches VMAS-R1, VMAS-C-1_0.
SCXML service also handles all the events that have to be posted towards SME. The implementation
of the same can be found in ScxmlSvcMgr::OnEvent().
SME requires that each event be represented by an event object. Each package is responsible for
creating the event objects for the events it handles. SCXML service acts as a broker and gets the
appropriate event object from the package chosen based on the input event type as shown in the
below code snippet –
The created event object is then posted to the SME using ISMEStateMachine::handleEvent().
1212121212121212 MAVENIR INTERNAL
12 (17)
Prepared by No.
12/01/2015 1a
Apart from the above there is a ‘time’ package included by default with the SME. VMAS has also
defined 2 packages specific to itself – vmas and vmasdb.
The commands supported under the generic appCommon packages and time package are listed
below.
Database Package: This package can be used for executing Oracle stored procedures from SCXML.
Command name Parameters Description
loadprocedure To choose a specified stored
procedure to be executed
assignparameter To assign input and output
parameters to the stored
procedure loaded
executeprocedure To execute a given stored
procedure
getrecordcount To get the number of records
1313131313131313 MAVENIR INTERNAL
13 (17)
Prepared by No.
12/01/2015 1a
MAP Package: This package provides for performing few MAP requests.
Command name Parameters Description
registerss Sends RegisterSS MAP
command to HLR
activatess Sends ActivateSS MAP
command to HLR
erasess Sends EraseSS MAP
command to HLR
srism Sends SRISM to HLR
MSML Package: This package can be used to send MSML requests over SIP INFO message to the
MRF.
Command name Parameters Description
loadtemplate To load a specified MSML
template
assignparameter To assign values to the ‘$’
variables in the template
sendmessage To send out the MSML request
REST Package: This package supports sending REST requests over HTTP to entities like MStore.
Command name Parameters Description
loadtemplate To load a specified REST
template
assignparameter To assign values to the ‘$’
variables in the template
sendmessage To send out the REST request
getfolderdata To retrieve data from a folder
getobjectindex To get the index of a specific
object in the object list
getobjectdata To get the data corresponding
to a specific object
sortobject To sort an object list
SMPP Package: This package supports few SMPP operations like submit_sm.
Command name Parameters Description
loadtemplate To choose the SMPP request
to be submitted
assignparameter To assign values to the
variables in the request loaded
1414141414141414 MAVENIR INTERNAL
14 (17)
Prepared by No.
12/01/2015 1a
TMM Package: This package can be used for pegging counters from SCXML.
Command name Parameters Description
setcounter To peg a specified counter
Translation Package: This package can be used for applying translation from SCXML.
Command name Parameters Description
applytranslation To apply translation based on
profile name
Time Package: This package provides few Date/Time utility functions and also supports creation /
deletion of timers.
Command name Parameters Description
getgmt To get the current time in UTC
12/01/2015 1a
8 Example SCXML
The SCXML files corresponding to VMAS and MCA services can be found at cust/scripts/vha and
cust/scripts/mca in CUST-R6 branch.
An example SCXML file from MCA application is given below. This file defines the entry point for
MCA application. Based on the incoming session-creating events like new INVITE received or
SMPP deliver_sm received, the file invokes the corresponding SCXMLs - RegisterMCA.scxml
(which handles the INVITE received event), NotifyUser.scxml(which implements sending
MCA/NotifyMe SMS on receiving the deliver_sm) etc.
<?xml version="1.0" encoding="UTF-8"?>
<scxml initial="initial" version="1.0" xmlns="http://www.w3.org/2005/07/scxml"
xmlns:mrf="www.mavenir.com/packages/mrf" xmlns:mstore="www.mavenir.com/packages/mstore"
xmlns:trn="www.mavenir.com/packages/trn" xmlns:vmas="www.mavenir.com/packages/vmas"
xmlns:vmasdb="www.mavenir.com/packages/vmasdb" xmlns:tmm="www.mavenir.com/packages/tmm"
xmlns:time="www.mavenir.com/packages/time" xmlns:smpp="www.mavenir.com/packages/smpp"
xmlns:database="www.mavenir.com/packages/database" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance">
<datamodel>
<data expr="9999" type="string" id="SequenceNum"/>
<data expr="" type="string" id="SubscriberNum"/>
<data expr="" id="MessageID" type="string"/>
<data expr="smsc8215" id="SmscID" type="string"/>
</datamodel>
<state id="initial">
<onentry>
<assign location="$vmas:ueprofile.COS"
expr="$vmasdb:ServiceParameters.MCA_DEFAULT_COS"/>
<assign location="$SmscID" expr="$vmasdb:ServiceParameters.smscID"/>
</onentry>
<transition event="vmas.invite.received" target="CheckFeatureEnabled"/>
<transition event="smpp.deliver_sm.success" cond="$_event.command_status ==
'DELIVERED'" target="InvokeNotifyUser">
<assign location="$SequenceNum" expr="$_event.sequence_number"/>
<assign location="$MessageID" expr="$_event.message_id"/>
<assign location="$SubscriberNum" expr="$_event.dest_addr"/>
</transition>
<transition event="smpp.deliver_sm.failure" target="InvokeRetrySilentSM">
<assign location="$SequenceNum" expr="$_event.sequence_number"/>
<assign location="$SubscriberNum" expr="$_event.dest_addr"/>
</transition>
</state>
<state id="CheckFeatureEnabled">
<transition cond="$vmasdb:cos.MCA_FEATURE_FLAG != 'Yes' &&
$vmasdb:cos.NOTIFY_FEATURE_FLAG != 'Yes'" target="final">
<vmas:setinternalcausecode id="CC_MCA_AS_DEPOSIT_FAIL"/>
<vmas:sendsipresponse method="INVITE"/>
</transition>
<transition target="CheckIfMCACall"/>
1616161616161616 MAVENIR INTERNAL
16 (17)
Prepared by No.
12/01/2015 1a
</state>
<state id="CheckIfMCACall">
<onentry>
<trn:applytranslation trnname="PRTCT"/>
<trn:applytranslation trnname="TRN"/>
</onentry>
<transition cond="$trn:SVCCAUSE == 'MCA_APP' && $trn:CLIAVLBL == true"
target="InvokeRegisterMCA"/>
<transition cond="$trn:SVCCAUSE != 'MCA_APP'" target="final"/>
<transition cond="$trn:CLIAVLBL == false" target="final">
<vmas:setinternalcausecode id="CC_MCA_AS_DEPOSIT_FAIL"/>
<vmas:sendsipresponse method="INVITE"/>
</transition>
</state>
<state id="InvokeRegisterMCA">
<invokescxml event="RegisterMCA" target="RegisterMCA.scxml"/>
<transition event="RegisterMCA.success" target="final"/>
<transition event="RegisterMCA.failure" target="final"/>
</state>
<state id="InvokeNotifyUser">
<invokescxml event="NotifyUser" target="NotifyUser.scxml">
<param name="sequence_number" expr="$SequenceNum"/>
<param name="message_id" expr="$MessageID"/>
<param name="dest_addr" expr="$SubscriberNum"/>
</invokescxml>
<transition event="NotifyUser.success" target="final"/>
<transition event="NotifyUser.failure" target="final"/>
</state>
<state id="InvokeRetrySilentSM">
<invokescxml event="RetrySilentSM" target="RetrySilentSM.scxml">
<param name="sequence_number" expr="$SequenceNum"/>
<param name="dest_addr" expr="$SubscriberNum"/>
</invokescxml>
<transition event="RetrySilentSM.success" target="final"/>
<transition event="RetrySilentSM.failure" target="final"/>
</state>
<state id="final">
<onentry>
<done/>
</onentry>
</state>
</scxml>
12/01/2015 1a