Introduction to CPL

2. Introduction to CPL Jonathan Rosenberg Chief Scientist

3. CPL Problem Statement • Would like to allow end users to • Define new services • GUI tools or web • Hand edit • Back and forth • Customize vanilla services • Have their services be enabled instantly • Service providers require • Platform independence • Decouple service creation tool from execution • Decouple service from signaling protocol • Assurances on safety

4. What are the Options? • Web interfaces populate customer profile data • Not cross platform • Not flexible • End users write Java applications and upload • Moving between GUI tools and hand editing is impossible • Safety issue still exists; sandboxing helps but not completely • BIG IDEA - Define an XML based Call Processing Language (CPL)

5. Advantages of XML for call services • Easily edited by hand or by GUI tools • Cross platform • Allows us to define our own language primitives • Can engineer language to be safe • Can make it easy to build many common services • Can be manipulated by off the shelf XML tools • Readily transported in HTTP, SIP, FTP, other means • Small in size (compared to Java) • Fast operation

6. Concept originated as end user uploading of service logic in SIP REGISTER JDR and HGS, 1997 Proposed as one of main work items for new IP Telephony (iptel) working group when it was formed in Nov 1997 Jonathan Lennox, Columbia U. took role as primary driver and author Framework and Requirements done first RFC2824 issued May 2000 CPL specification First draft April 1999 Submitted for consideration as RFC Dec. 2000 Implementations First one by JDR, mid 1999 at Bell Labs Second by dynamicsoft Numerous ones exist or are in progress now Indigo Software Ubiquity Netcentrex History of CPL

7. Where do CPLs get executed? In network elements SIP Proxies SIP Application Servers H.323 Gatekeepers Can be used in clients, not designed for it Who writes CPLs? Engineered for end users to write Can be written by administrators and third parties as well How do CPLs get into the network? Uploaded in REGISTER (next slide) Uploaded in http POST Sent through any other means Direct database writes FTP etc. What kinds of services are best suited for CPL? Call routing services Call screening services Call logging services CPL FAQ

8. Include CPL in body of REGISTER message MIME type application/cpl+xml Content-Disposition Header Indicates purpose of bodies Indicates that content contains call logic Content-Action indicates what is desired Add the CPL to the server Delete CPL CPLs DO NOT get refreshed Uploading CPL in REGISTER REGISTER sip:sip.example.com SIP/2.0 From: Joe User <sip:joe@example.com> To: "J. User" <sip:joe@example.com> CSeq: 18 REGISTER Expires: 1800 Call-ID: 39485832@joespc.example.com Contact: sip:joe@joespc.example.com Accept: application/cpl+xml Authorization: Basic am9lOnBhc3N3b3JkAFBX Content-Type: application/cpl+xml Content-Length: 137 Content-Disposition: script Content-Action: add <cpl> <incoming> <reject status=“400”/> </incoming> </cpl>

9. CPL Execution starts on arrival of INVITE message at a proxy Governs operation of proxy for INVITE transaction ONLY When final response is sent, CPL execution terminates Does not stay “in the call” This is why CPL is good at pre-call services like routing and screening CPL Lifecycle INV INV 300 ACK INV 600 ACK 600 CPL Lifecycle Proxy UA1 UA2

10. SIP call setups traverse many paths Which ones does a user need to put their CPL on? CPL guides behavior of a single proxy Incoming calls, CPL is generally on proxy that accesses registrations for that user Outgoing calls, CPL is generally on local outbound proxy CPLs can be put anywhere else Up to user/system to decide where they need to go Proxies and CPL CPLs for called user CPLs for caller

11. CPL represents a tree Trees have nodes and links Each corresponds to a tag in CPL Nodes Specify actions to take or decisions to make Links Specify results of actions Specify which decision was made CPL contains subroutines, each of which is a tree Incoming - tree to execute for incoming calls Outgoing - tree to execute for outgoing calls Subroutines - can be used by either incoming or outgoing CPL Structure <?xml version="1.0" ?> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <cpl> <subaction id="voicemail"> SOME STUFF HERE </subaction> <subaction id=“email”> SOME STUFF HERE </subaction> <incoming> SOME STUFF HERE </incoming> <outgoing> SOME STUFF HERE </outgoing> </cpl>

12. First line Specifies XML version Next line Specifies DTD to be used for validation All CPLs then followed by CPL tag Within CPL tag, you can have subactions zero or one incoming zero or one outgoing Beginning a CPL <?xml version="1.0" ?> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <cpl> <subaction id="voicemail"> SOME STUFF HERE </subaction> <subaction id=“email”> SOME STUFF HERE </subaction> <incoming> SOME STUFF HERE </incoming> <outgoing> SOME STUFF HERE </outgoing> </cpl>

13. Mapping Trees to CPLs <lookup source=“registration”> <success> <proxy/> </success> <otherwise> <time-switch> <time dtstart=20001001T000000” duration=“24H” freq=“weekly” byday=“MO”> <reject status=“400”/> </time> <otherwise> <redirect/> </otherwise> </time-switch> </otherwise> </lookup> lookup otherwise success What is the date? proxy Monday otherwise Reject Redirect

14. CPL Execution Model • Processing begins at incoming or outgoing tag • Depends on system • Server traverses tree, making decisions or performing actions • Implicit global variable - the list of locations • Certain tags modify the location list • location, lookup, location-filter • Other tags use the location list • proxy, redirect

15. Signaling Actions proxy redirect reject Decisions address-switch string-switch time-switch priority-switch Other actions mail log Location modifiers location lookup remove-location Subroutine calls subaction sub Available tags

16. Node Proxies to current location list Outputs are result of proxy busy (486) noanswer (408 or timeout) redirection (3xx) failure (4xx,5xx,6xx) Attributes timeout: how long to try before giving up recurse: whether to recurse or not ordering: sequential, parallel, first-only Proxy tag <proxy recurse=“yes”> <busy> <reject/> </busy> <noanswer> <reject/> </noanswer> </proxy>

17. Tried elements are removed from global location list for parallel and sequential, that’s all sip URLs for first only, that’s the top sip URL Default timeout 20s if a no-answer tag is present system defined otherwise why? If there is a no-answer, there is something else to do Default recurse is yes Default ordering is parallel Recursing Contacts from 3xx are adding to implicit global location list List is always kept in sorted order based on q value Proxy tag Details

18. Node Redirects to the current location list Placed in Contact headers OK if there are no locations No outputs allowed; script execution terminates Single attribute: permanent yes or no Indicates whether redirection is a permanent or temporary condition For SIP, 301 in one case, 302 in other Redirect tag <location url=“sip:foo@bar”> <redirect/> </location>

19. Node Rejects the call Status code to use is provided as an attribute busy,notfound, reject, error SIP servers can also allow numeric codes optional reason phrase can also be used CPL processing terminates Reject tag <reject status=“busy”/>

20. Switch statements are the primary decision making components in CPL They support a common structure Start with X-switch, where X is the element to check Subtags are all called X, and each of them represents a link with a specific value of the element otherwise is defined as an allowed subtag of X-switch not-present as well - when element is not in the message Switch Statements <foo-switch> <foo is=“hello”> <reject/> </foo> <foo is=“goodbye”> <redirect/> </foo> <otherwise> <proxy/> </otherwise> <not-present> <log/> </not-present> </foo-switch>

21. Used to make decisions based on the value of address fields in the message Defines two attributes, field and subfield Field is origin (From field) original-destination (To field) destination (Request URI) Subfield defines component of the URI in the field address-type (scheme of URL) user Host port tel If it’s a tel URL, or a sip URL with a telephone number, this element is defined display display name; undefined for request URI password Address-Switch

22. Outputs of address-switch are address tags Singe attribute, which can be one of is, contains, subdomain-of is used for exact match case sensitivity depends on subfield contains substring match case sensitivity depends on subfield Subdomain-of only defined for tel and for host for host, it matches if the domain in the subfield is a subdomain of the listed domain for tel, it matches if the telephone number contains the listed number as a prefix Address

23. The given address tags to the right all match Assume the request is Examples <address-switch field=“origin” subfield=“user”> <address is=“ruser”/> </address-switch> <address-switch field=“destination” subfield=“port”> <address is=“5060”/> </address-switch> <address-switch field=“original-destination” subfield=“host”> <address subdomain-of=“com”/> </address-switch> <address-switch field=“origin” subfield=“display”> <address contains=“FDisp”/> </address-switch> INVITE sip:ruser@rdomain.com SIP/2.0 From: FDisplay <sip:fuser@fdomain.com> To: TDisplay <sip:tuser@tdomain.com>

24. Address-Switch motivations • Older CPL drafts used string-switch for this • Motivations for change • Hard to match on specific fields through glob matching • Glob matching was hard to implement • Take advantage of inherent structure • Didn’t work for H.323

25. String matching on textual fields in request Mandatory attribute “field” indicates whats being matched subject user-agent organization language Subtags of string-switch are string String contains either “is” or “contains” for exact or substring matching String-Switch <string-switch field=“subject”> <string is=“Sales”> <location url=“sip:sales@foo.com”> <proxy/> </location> </string> <string contains=“marketing”> <location url=“sip:marketing@foo.com”> <proxy/> </location> </string> <otherwise> <location url=“sip:random@foo.com”> <proxy/> </location> </otherwise> </string-switch>

26. String Switch Details • Matching Issue • Want case insensitive • These fields are freeform UTF-8! • Case insensitivity depends on language and locale • Nearly impossible to do • Solution is a new Compatibility Composition form defined for Unicode • Language is Accept-Language header in SIP • Good for routing to operator based on language of caller • Only substring matching is useful • Accept language has parameters, commas, etc.

27. Allows matching based on priority of request Subtags are priority tags, which have attribute less, equal, greater Comparisons are against defined SIP values of emergency, urgent, normal, non-urgent If nothing is in request, priority is normal unknown priorities mapped to normal for greater, less comparisons Priority-Switch <priority-switch> <priority equals=“newpriority”> <location url=“sip:new@foo.com”> <proxy/> </location> </priority> <priority less=“normal”> <location url=“sip:whocares@foo.com”> <proxy/> </location> </priority> <priority greater=“urgent”> <location url=“sip:emergency@foo.com”> <proxy/> </location> </priority> </priority-switch>

28. Time Switch • Significantly different and more complex than initial version • Initially crontab based • Now iCal based • Why iCal? • Makes integration with calendaring programs easier • More complete, more modern • -03 based on an iCal subset proven to be implementable in O(1) time! • Powerful representation of repeating events • Every third Tuesday in February and March • First Monday of the month • etc.

29. Handling Timezones • User and server may be in different timezone • CPL times should refer to timezone of user • How to indicate timezone of user? • Offset from GMT not sufficient • Want scripts to be valid for years • Offset varies as DST comes and goes!! • Solution • time-switch contains either tzurl or tzid • tzurl refers to an object that defines the timezone • tzid refers to either a to-be-established registry, or a server specific name • names are things like EST and CST • Java has a standard set of names

30. Time tags contain many attributes that define repeating events Basic event description dtstart: event start date and time dtend: event end time duration: instead of dtend Defining repititions through periodicity freq: frequency of occurrence daily, weekly, monthly, yearly interval: how often recurrence repeats Limiting repititions until: date/time when repititions end Defining exceptions byday List of days of the week bymonthday List of days of the month byyearday List of days of the year byweekno List of weeks of the year bymonth List of months of the year Time tags

31. Exceptions • Expansion • If frequency is a greater unit than largest exception • Adds more events • Example: freq=“yearly” bymonth=“jan,feb” defines an event that repeats twice a year - once in jan, once in feb • Contraction • If frequency is a smaller unit than largest exception • Reduces number of events • Example: freq=“daily” byday=“MO,WE” defines only Mondays and Wednesdays

32. Time of day forwarding/screening application Proxy calls to work during 9-5 during the week Proxy calls to home during the evening of the week Reject calls on weekends Example time-switch <time-switch tzid="America/New-York”> <time dtstart="20000703T090000" duration="8H" freq="weekly" byday="MO,TU,WE,TH,FR"> <location url=“sip:work@foo.com”> <proxy/> </location> </time> <time dtstart=“20000703T170000” dtend=“20000703T210000” freq=“weekly” byday=“MO,TU,WE,TH,FR”> <location url=“sip:home-eve@foo.com”> <proxy/> </location> </time> <time dtstart=“20000703T000000” duration=“24H” freq=“weekly” byday=“SA,SU”> <reject reason=“it’s the weekend”/> </time> </time-switch>

33. Location Defines a location to be added to the global location list Single attribute, URL, contains the URL to add to the list Lookup Obtains the URI to add through indirection source attribute specifies place to go to registration looks in registration DB if source is a URL, fetches the URL and that contains a document with just a URL to add success, failure, notfound outputs Location Addition <location url=“sip:foo@bar”> <redirect/> </location> <lookup source=“registration”> <success> <proxy/> </success> </lookup>

34. Allows for removal of locations from global location list Based on caller preferences specification Caller prefs Associates parameters with contacts Example: mobile=fixed, media=video INVITEs contain headers that ask to reach specific contacts by parameter Parameter filtering two main attributes, param and value both are comma separated lists param contains the name of a parameter (e.g., mobile) value contains the value for that parameter (e.g., fixed) same number of elements in param and value lists causes matching contacts to be removed Address filtering location attribute contains a URL pattern to match remove-location

35. Sip:user@foo;mobility=“fixed” sip:joe@bar;feature=“voicemail” <remove-location field=“mobility,feature” value=“mobile,voicemail”> Sip:user@foo;mobility=“fixed” Example Parameter filtering

36. Allows CPL to send email Single parameter, url, contains mailto URL to use CPL server will Set the From field to its own address Set the body to contain information about the call, unless a body is specified by CPL Set the Subject to something useful, unless subject is specified by CPL Caveats Ampersand must be with an entity! Mail tag <mail url=“mailto:user@host?subject=foo &amp;body=hello%20there”>

37. Allows CPL to generate log output How output is logged is system dependent Two parameters name: specifies name of log to use interpretation of name is system dependent comment: text to place in log CPL should also generate time of day and other params in log Log tag <log comment=“rejected call”>

38. CPL can call a subroutine defined by subaction Subactions have an id To call subroutine, use sub tag with that Id as the value of ref attribute Subroutines can only be called if they are physically above in the CPL Avoids loops! Subroutines <subaction id=“vmail”> <location url=“sip:vmail@foo.com”> <proxy/> </location> </subaction> <incoming> <lookup source=“registration”> <success> <proxy> <notfound> <sub ref=“vmail”/> </notfound> </proxy> </success> <otherwise> <sub ref=“vmail”/> </otherwise> </lookup> </incoming>

39. What happens if a script reaches a point where there are no more tags? Default Action is taken Default action depends on how far script has gotten No signaling actions, no locations defined, location set empty lookup in database, proxy or redirect as normal No signaling actions, no locations, location set non-empty Happens for outgoing calls Proxy to location set locations or lookups performed, no signaling proxy or redirect there proxy action invoked, noanswer output not present let phone ring forever, or until system defined timeout proxy performed, responses received forward best response upstream Default Actions

40. Uses XML namespaces Each extension defines its own namespace Will render DTD validation useless! General problem with namespaces CPL Extensions <incoming> <lookup source=“registration”> <success> <proxy xmlns:foo=“http://bar”> <foo:screwup> <sub ref=“vmail”/> </foo:screwup> </proxy> </success> <otherwise> <sub ref=“vmail”/> </otherwise> </lookup> </incoming>

41. Information Resource • Jonathan Rosenberg • jdrosen@dynamicsoft.com • +1 973.952.5000