RECEIVE action guide
“RECEIVE” Action - Incoming signaling (MEGACO/SIP) from a remote endpoint (Remote VoIP Client endpoint, softphone etc.).
Endpoint’s identifiers (Such as: Physical/Ephemeral Id , SDP Variables etc.) are needed to be learned by VoIPEmulator for a later response (“Reply”, “Notify”,200OK ..etc.).
Identifiers are learned as ” variables ”:
- During script run time.
- Manually, by the user, via “Variable information table”
Endpoint’s identifiers (Such as: Physical/Ephemeral Id , SDP Variables etc.) are needed to be learned by VoIPEmulator for a later response (“Reply”, “Notify”,200OK ..etc.).
Identifiers are learned as ” variables ”:
- During script run time.
- Manually, by the user, via “Variable information table”
Saving RECEIVE Action identifiers (in Run Time):
When creating scripts, we need to decide which “identifiers” (strings) should be saved (as “Variables”) for later "SEND" Actions.
The ‘~’ symbol defines where Variable’s name Begins/Ends:
Syntax: [Prefix] ~ [Variable Name] ~ {Suffix}
Note:
Scenario example 1 (MEGACO):
Endpoint (Physical-Id: "Line/1") Off-hooks and sends Notify.
VoIPEmulator receives the Notify (as “RECEIVE” Action) and Reply with learned Physical-Id (variable value):
Endpoint -> VoIPEmulator(MGC):
MEGACO/1 [190.100.40.22]:2944
Transaction = 1000 { Context = - {
Notify = Line/1 {ObservedEvents =12345 {2034502T10000000:al/of
}}}
VoIPEmulator needs to learn endpoint's Physical-Id (“Line/1”) for a later ("SEND" Action ) “Reply” .
If we examine closely the RECEIVE message:
The ‘~’ symbol defines where Variable’s name Begins/Ends:
Syntax: [Prefix] ~ [Variable Name] ~ {Suffix}
Note:
- Prefix is mandatory.
- Suffix is not mandatory.
- Variable Name can be a set of [a-z,A-Z,0-1,_] characters.
Scenario example 1 (MEGACO):
Endpoint (Physical-Id: "Line/1") Off-hooks and sends Notify.
VoIPEmulator receives the Notify (as “RECEIVE” Action) and Reply with learned Physical-Id (variable value):
Endpoint -> VoIPEmulator(MGC):
MEGACO/1 [190.100.40.22]:2944
Transaction = 1000 { Context = - {
Notify = Line/1 {ObservedEvents =12345 {2034502T10000000:al/of
}}}
VoIPEmulator needs to learn endpoint's Physical-Id (“Line/1”) for a later ("SEND" Action ) “Reply” .
If we examine closely the RECEIVE message:
For saving Identifier "Line/1 " as Variable named "MY_PAR":
Simply write (In RECEIVE Action’s text):
Notify = ~MY_PAR~
Simply write (In RECEIVE Action’s text):
Notify = ~MY_PAR~
Note: We could have also used suffix:
Notify = ~MY_PAR~ {
Explanation:
At "run time", when VoIPEmulator receives incoming message,
Value (string) right after Prefix “Notify =” , is saved as :
Variable named “MY_PAR” (Meaning: MY_PAR = “Line/1”).
Note: you could also verify this in the “Variable information table”
Notify = ~MY_PAR~ {
Explanation:
At "run time", when VoIPEmulator receives incoming message,
Value (string) right after Prefix “Notify =” , is saved as :
Variable named “MY_PAR” (Meaning: MY_PAR = “Line/1”).
Note: you could also verify this in the “Variable information table”
When we later write in SEND Action:
(Note: Action’s destination should be EndPoint’s IP:Port )
(Note: Action’s destination should be EndPoint’s IP:Port )
The VoIPEmulator will replace all Variables for their learned values, and send the Reply Action back to the endpoints as followed:
MEGACO/1 [190.100.40.22]:2944
Reply = 1000 {Context = - {Notify = Line/1
}}
MEGACO/1 [190.100.40.22]:2944
Reply = 1000 {Context = - {Notify = Line/1
}}
Special Parsing Character
Note: As default settings (MEGACO), we expect to save data value (string) which contains the characters: { A-Z , a-z , 0-9 , : , @ , - , . , / , _ }
(Settings Tab)
(Settings Tab)
This means that if we receive (In example 1):
MEGACO/1 [190.100.40.22]:2944
Transaction = 1000 {
Context = - {
Notify = C2/1<AAA {
ObservedEvents =12345 {2034502T10000000:al/of}
}}
MY_PAR's value will be saved as “C2/1”.
This is because “<“ was not set as one of the "Special Parsing Character" (See Settings Tab)
Scenario example 2 (MEGACO):
Endpoint -> VoIPEmulator(MGC):
MEGACO/1 [190.100.40.22]:2944
Transaction = 1000 {
Context = - {
Notify = TermA { ObservedEvents = 12345 {2034502T10000000:al/of}
}}
To save “12345” as Variable named “MyPARAM” :
We write (In the RECEIVE Action’s text):
MEGACO/1 [190.100.40.22]:2944
Transaction = 1000 {
Context = - {
Notify = C2/1<AAA {
ObservedEvents =12345 {2034502T10000000:al/of}
}}
MY_PAR's value will be saved as “C2/1”.
This is because “<“ was not set as one of the "Special Parsing Character" (See Settings Tab)
Scenario example 2 (MEGACO):
Endpoint -> VoIPEmulator(MGC):
MEGACO/1 [190.100.40.22]:2944
Transaction = 1000 {
Context = - {
Notify = TermA { ObservedEvents = 12345 {2034502T10000000:al/of}
}}
To save “12345” as Variable named “MyPARAM” :
We write (In the RECEIVE Action’s text):
Scenario example 3 (MEGACO):
How to save Variables when suffix is “non one-one correspondence” ?
(2 available methods)
Endpoint -> VoIPEmulator(MGC):
MEGACO/1 [109.111.29.24]: 2944
Reply = 1236 {
Context = 1 {
Add = TermA,
Add = EphA{
Media {
Local {
v=0
o=- 2890222526 2822242807 IN IP4 109.222.29.24
s=-
t= 00
c=IN IP4 109.222.29.24 }}}}}
Method 1 :
To save both: TermA and EphA .
We use a '#' followed by “occurrence-number” :
Saving TermA as Variable named “MyAddParam#1”
We simply write (In the RECEIVE Action’s text):
Add = ~MyAddParam#1~
Saving EphA as the Variable named “MyAddParam#2”
We simply write (In the RECEIVE Action’s text):
Add = ~MyAddParam#2~
Variable will be saved as:
MyAddParam#1 = “TermA”
MyAddParam#2 = “EphA”
Note: If we only need to save EphA, then we can write :
”Add = ~MyAddParam#2~”
Meaning: save Identifier (string) which comes after the second occurrence of the prefix: “Add =” as Variable named: “MyAddParam#2” .
Method 2:
“…
Add = TermA,
Add = EphA{
…”
Because the suffix is different and is not part of the "Advanced Character parser" default parser is { A-Z , a-z , 0-9 , : , @ , - , . , / , _ } .
We can use the suffix to tell apart between the two lines:
Add = TermA, -> In this case the Suffix is ' , '
Add = EphA{ -> In this case the Suffix is ' { '
We simply write (In the RECEIVE Action’s text):
How to save Variables when suffix is “non one-one correspondence” ?
(2 available methods)
Endpoint -> VoIPEmulator(MGC):
MEGACO/1 [109.111.29.24]: 2944
Reply = 1236 {
Context = 1 {
Add = TermA,
Add = EphA{
Media {
Local {
v=0
o=- 2890222526 2822242807 IN IP4 109.222.29.24
s=-
t= 00
c=IN IP4 109.222.29.24 }}}}}
Method 1 :
To save both: TermA and EphA .
We use a '#' followed by “occurrence-number” :
Saving TermA as Variable named “MyAddParam#1”
We simply write (In the RECEIVE Action’s text):
Add = ~MyAddParam#1~
Saving EphA as the Variable named “MyAddParam#2”
We simply write (In the RECEIVE Action’s text):
Add = ~MyAddParam#2~
Variable will be saved as:
MyAddParam#1 = “TermA”
MyAddParam#2 = “EphA”
Note: If we only need to save EphA, then we can write :
”Add = ~MyAddParam#2~”
Meaning: save Identifier (string) which comes after the second occurrence of the prefix: “Add =” as Variable named: “MyAddParam#2” .
Method 2:
“…
Add = TermA,
Add = EphA{
…”
Because the suffix is different and is not part of the "Advanced Character parser" default parser is { A-Z , a-z , 0-9 , : , @ , - , . , / , _ } .
We can use the suffix to tell apart between the two lines:
Add = TermA, -> In this case the Suffix is ' , '
Add = EphA{ -> In this case the Suffix is ' { '
We simply write (In the RECEIVE Action’s text):
(PHYVariable = “TermA” , EPHVariable = “EphA”)
Note: In case both prefix & suffix are the equal:
Add = TermA{
Add = EphA{
We have no other choice but to use the method-1 (char '#' followed by “occurrence number”).
Note: In case both prefix & suffix are the equal:
Add = TermA{
Add = EphA{
We have no other choice but to use the method-1 (char '#' followed by “occurrence number”).
Introduction to “Must Words”
“Must Words” are a set of strings, VoIPEmulator expects to find in incoming messages (From endpoint).
In run time, when VoIPEmulator gets in the script to a RECEIVE Action:
1) VoIPEmulator processes the Action’s commands, reading line by line, looking for “Must-Words” or Variables :
2) VoIPEmulator waits for incoming message (MEGACO/SIP) from remote endpoint.
3) VoIPEmulator processes incoming message (MEGACO/SIP) and if "Must Words" are expected to be found :
When a messages is received by VoIPEmulator (MGC).
In order to assure we received the exact expected message, we use “Must Words”.
Example:
The proper way to receive: “ObservedEvent Off Hook” message
and save the Termination's name as “MY_PAR” :
In run time, when VoIPEmulator gets in the script to a RECEIVE Action:
1) VoIPEmulator processes the Action’s commands, reading line by line, looking for “Must-Words” or Variables :
- If line contains ‘~’ symbol: It is processed as a Variable definition line type.
- If line does not contain any ‘~’ symbol: It is processed as a “Must Words” line type.
2) VoIPEmulator waits for incoming message (MEGACO/SIP) from remote endpoint.
3) VoIPEmulator processes incoming message (MEGACO/SIP) and if "Must Words" are expected to be found :
- Only if there is a Full Match for all “Must Words” , VoIPEmulator will learn/update Variables (from received message), and proceed to next Action.
- If Full Match is not found (for all “Must Words“) VoIPEmulator will try to run one of the “Automatic rules” (Advanced Scripting Tab) and try to find matching AUTO rule.
If no such rule is found, the script will stop and exit.
- Each “Must Words”, is case sensitive and should be written as a new line.
- “Must Words” are optional.
When a messages is received by VoIPEmulator (MGC).
In order to assure we received the exact expected message, we use “Must Words”.
Example:
The proper way to receive: “ObservedEvent Off Hook” message
and save the Termination's name as “MY_PAR” :
In this example there are 3 lines:
The first 2 lines (which don't contain any ‘~’ symbol) are “Must Words” lines.
This means: “ObservedEvents” , “al/of” must be found in the received message (If not AUTO rule will be called).
Note each "Must Word" is written as a new line.
The third line is a “Variable definition” line.
(line contains ‘~’ symbol for Variable indication)
The first 2 lines (which don't contain any ‘~’ symbol) are “Must Words” lines.
This means: “ObservedEvents” , “al/of” must be found in the received message (If not AUTO rule will be called).
Note each "Must Word" is written as a new line.
The third line is a “Variable definition” line.
(line contains ‘~’ symbol for Variable indication)