The call flow diagram is similar to a UML sequence diagram. The call flow diagram displays the sequence of messages that are sent between agents and servers. The SIP Modeling Toolkit provides some base classes that specify all the messages and responses specified in RFC 3261. The base classes can be user agents Session Initiation Protocols (SIPs), and so on. You can specify additional functionality in subclasses that you create.
Most of the useful information in a call flow request or response is captured in the headers. The toolkit provides an SIP page in the Properties view that shows the request URI, headers, SIP version, and body of the message.
You can implement services to establish traceability links to specific lifelines in call flow diagrams. The traceability links indicate that the functionality of a specific participant in the call flow is implemented.
Call flow diagram transformations
- PCAP to call flow transformation: creates a new call flow diagram from the traffic that a packet capture (pcap) file captures.
- SIPp to call flow transformation: creates a call flow diagram
from a SIPp file.
A SIPp file is an XML file that validates against sipp.dtd. It contains a root node called <scenario> with a name attribute. The SIPp child elements define the flow of the scenario. The importer only recognizes <send>, <recv> and <pause> elements. All other elements are ignored. The <send> elements contain full headers, which can contain special SIPp defined keywords designed to be replaced with real values during execution. The SIPp defined keywords can be replaced by values defined in the transformation configuration. The transform can also optionally remove SIP tag and branch parameters from headers as well as Call-ID headers, which are often specific to a particular run of the scenario and not useful in a UML Call Flow diagram.
- For each <send> element in the file, a UML message is created from a Lifeline called Test Agent to another Lifeline. If the option to only create two participants is checked, the other Lifeline is named User Agent (UA). If the option is not checked, the target of the message is determined by the address in the request URI.
- For each <recv> element in the file, a UML message is created from the User Agent lifeline to the Test Agent lifeline. Since SIPp has little information associated with the <recv> elements, all messages are sent from the default lifeline. If the option to add To and From headers to <recv> messages is checked, each message has a To and From header added. This is required by the transformation of call flows to Rational® Performance Tester SIP test cases.
Note: The transformation requires a folder of SIPp .xml files or a single SIPp file. If the source is a folder, each file with the .xml extension is loaded and processed. If the file fails validation or is not a SIPp file, the import skips over that file. The transformation requires an UML model or UML package as the target. All imported files are placed under this model or package.The transform options are:- Create only two participants in a call flow: The transformation ensures that each Call Flow diagram that is created has only two lifelines. If this option is not checked, then each <send> command in the file with a unique request URI results in a new lifeline.
- Add headers to <recv> messages: SIPp does not specify any header content on <recv> messages, however Rational Performance Tester expects at a minimum To and From headers. If this option is checked, each <recv> message has the default To and From header added.
- Filter out Call-ID: All Call-ID headers are removed from the imported call flow.
- Filter out Tag Parameters: SIP headers with the tag parameter, for example From: Bob <sips:bob@biloxi.example.com>;tag=a73kszlfl >, are removed.
- Filter out Branch Parameters: SIP headers with the branch parameter, for example Via: SIP/2.0/TLS client.biloxi.example.com:5061;branch=z9hG4bKnashds7, are removed.
- Variable Substitutions: Variable names appearing between square brackets in the SIPp file that match variables in this list are replaced by the value next to it. For example, any occurrence of [local_ip] in a SIPp file are replaced with localhost in the Call Flow.
- SIP call flows to Rational Performance Tester test cases transformation: exports call flow
diagrams to Rational Performance
Tester as Session Initiation Protocol (SIP) test cases.
Transforming SIP messages into Rational Performance Tester test cases requires a few headers to be defined for each request and response. The To, From, Via and CSeq headers are required by the SIP specification, and required by Rational Performance Tester on each message. For the Via header it is useful to use the performance tester defined keyword <<local-host>> to insert the IP address of the local host. For the call flow diagrams that describe a scenario between multiple participants, stereotype all the lifelines that must have a test case with the <<Tester>> stereotype.
Note: The toolkit import action does not import all SIPp commands and expressions. The import does not attempt to interpret actions, or work with media streams. It does import <pause> commands, but SIP call flows to Rational Performance Tester SIP test cases transform ignores these. The import can provide a useful visualization of SIPp scripts, and helps with the migration of test cases into Rational Performance Tester.You can use the SIP tools context menu, available by right-clicking on messages, to copy and paste the entire SIP message contents.
The single line header or the first line of a multiple line header must not begin with whitespace. Each header can be specified in a single line, or on multiple lines. The format of the message must be as follows:<single line header> or <multiple line header line 1> <whitespace><multiple line header line 2> <whitespace><multiple line header line 3> ...
Merge call flow diagrams
You can merge different call flow diagrams to produce a single state machine that represents the expected behavior of one of the lifelines in each of the call flow diagrams. This utility can be useful to understand the combined behaviors of multiple, discrete scenarios. The algorithm for merging the call flows does use some domain-specific semantics. While it can be applied to generic sequence diagrams, it has been optimized to work with the modeling toolkit defined Call Flow diagrams. It uses the additional semantic content in SIP message headers to help distinguish event identity.
To merge call flows into a state machine, you must first add a common keyword to the lifeline of the participant whose state behavior you want to combine. Select the lifeline in a diagram, then select the Stereotypes tab and enter in a keyword, for example the keyword "SipApp". You must enter a keyword for all the lifelines in all the sequence diagrams you want to use in the merge.
The resultant state machine is not optimized, and is not indented to be used in any custom code generation transforms without careful examination and reworking. It does however provide a starting point by which a SIP service engineer can design the overall behavior of a specific service given a number of discrete call flow scenarios.
The following three call flow diagrams are merged. The keyword "SipApp" is used to identify the lifeline that is going to be modeled in the state machine. These three call flows represent the behavior of a simple call blocking service with text notification. When a call is blocked the service sends a SIP message or text notification to the intended callee, indicating that a call attempt was made. The first call flow shows what happens when a call is blocked. The following two show what happens when the call is carried out normally, with two variations depending on which user agent originates the BYE.
The resultant state machine is shown below. State transitions are modeled with CallEvent triggers associated with the SIP operations as part of the SIP reference model. A UML guard is created for each transition and specifies the name of the lifeline that is sending the message.
If you select the trigger in the diagram or in the Project Explorer, you can see the details of the SIP message as they are in the original call flow diagram. If you change the values of the headers, the changes are also reflected in the messages of the original call flow message.
In the generated machine above it is possible for a state to have two outgoing transitions triggered by the same SIP message. While it may be the same message the payload, or headers are different. When comparing messages in call flows and converting them to events in the machine the strategy of identity is to compare both the message name, its origin (the lifeline sending it) and the CSeq header value (if present). In the diagram above, the 200 OK message on the left has a CSeq value of "1 MESSAGE", while the one on the right has "1 INVITE".
If you select the entry action of a state, the type of action will be an Opaque Behavior, with its value being the sum of all the outgoing messages from the service lifeline that are expected to happen when this state is reached. Each action is prefixed with the name of the scenario (call flow name) that it came from. If the message was marked as optional this is also mentioned in parenthesis.
If an incoming message is marked as optional via the SIP extensions, note that this does not work with the UML optional fragment notation, then the resultant state machine includes another transition that bypasses the state. For example, the 180 Ringing response call flows are marked as optional, and an additional transition bypasses state S4.
The CompressStates option on the dialog to create the state machine allows you to enable or prevent the merging of common states in the machine. Common states are states that have an identical path to a final state. For example, the state S3 is the result of compressing two states.
If the compress option was not set there would be two states, S3 and S10 that both have the same path to final.
