Internet Engineering Task Force IPTEL WG Internet Draft Lennox/Schulzrinne ietf-iptel-cpl-00.txt Columbia University February 26, 1999 Expires: September 1999 CPL: A Language for User Control of Internet Telephony Services STATUS OF THIS MEMO This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress". To view the list Internet-Draft Shadow Directories, see http://www.ietf.org/shadow.html. Abstract The Call Processing Language (CPL) is a language that can be used to describe and control Internet telephony services. It is designed to be implementable on either network servers or user agent servers. It is meant to be simple, extensible, easily edited by graphical clients, and independent of operating system or signalling protocol. It is suitable for running on a server where users may not be allowed to execute arbitrary programs, as it has no variables, loops, or ability to run external programs. This document is a product of the IP Telephony (IPTEL) working group of the Internet Engineering Task Force. Comments are solicited and should be addressed to the working group's mailing list at iptel@lists.research.bell-labs.com and/or the authors. 1 Introduction The Call Processing Language (CPL) is a language that can be used to Lennox/Schulzrinne [Page 1] Internet Draft CPL February 26, 1999 describe and control Internet telephony services. It is not tied to any particular signalling architecture or protocol; it is anticipated that it will be used with both SIP [1] and H.323 [2]. The CPL is powerful enough to describe a large number of services and features, but it is limited in power so that it can run safely in Internet telephony servers. The intention is to make it impossible for users to do anything more complex (and dangerous) than describing Internet telephony services. The language is not Turing-complete, and provides no way to write a loop or a function. The CPL is also designed to be easily created and edited by graphical tools. It is based on XML [3], so parsing it is easy and many parsers for it are publicly available. The structure of the language maps closely to its behavior, so an editor can understand any valid script, even ones written by hand. The language is also designed so that a server can easily confirm scripts' validity at the time they are delivered to it, rather that discovering them while a call is being processed. Implementations of the CPL are expected to take place both in Internet telephony servers and in advanced clients; both can usefully process and direct users' calls. In the former case, a mechanism will be needed to transport scripts between clients and servers; this document does not describe such a mechanism, but related documents will. 1.1 Conventions Of This Document In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [4] and indicate requirement levels for compliant CPL implementations. In examples, non-XML strings such as -action1- , -action2- , and so forth, are sometimes used. These represent further parts of the script which are not relevant to the example in question. Some paragraphs are indented, like this; they give motivations of design choices, or questions for future discussion in the development of the CPL, and are not essential to the specification of the language. 2 Structure of CPL scripts 2.1 Abstract structure Lennox/Schulzrinne [Page 2] Internet Draft CPL February 26, 1999 Abstractly, a CPL script is described by a collection of nodes, which describe actions that can be performed or choices which can be made. A node may have several parameters, which specify the precise behavior of the node; they usually also have outputs, which depend on the result of the condition or action. For a graphical representation of a CPL script, see figure 1. Nodes and outputs can be thought of informally as boxes and arrows; the CPL is designed so that it can be conveniently edited graphically using this representation. Nodes are arranged in a directed acyclic graph, starting at a single root node; outputs of nodes are connected to additional nodes. When a CPL script is run, the action or condition described by the root node is performed; based on the result of that node, the server follows one of the node's outputs, and that action or condition is performed; this process continues until a node with no specified outputs is reached. Because the graph is acyclic, this will occur after a bounded and predictable number of nodes are visited. If an output to a node is not specified, it indicates that the CPL server should perform a node- or protocol-specific action. Some nodes have specific default actions associated with them; for others, the default action is implicit in the underlying signalling protocol, or can be configured by the administrator of the server. _________________ ___________________ _______ Call --->| String-switch | | location | | proxy |---------\ | field: from | ->| url: sip:jones@ |--->| | busy | |-----------------| / | example.com | | |---------| | match: |/ |___________________| | | timeout | | *@example.com | |_______|---------| |-----------------| failure | | otherwise | ____________________________________________/ | |\ / ____________________ __________ |_________________| \| | location | | redirect | ->| url: sip:jones@ |--->| | | voicemail. | |__________| | example.com | | merge: clear | |____________________| Figure 1: Sample CPL Script: Graphical Version Lennox/Schulzrinne [Page 3] Internet Draft CPL February 26, 1999 2.2 XML Structure Syntactically, CPL scripts are represented by XML documents. XML is thoroughly specified by [3], and implementors of this specification should be familiar with that document, but as a brief overview, XML consists of a hierarchical structure of tags; each tag can have a number of attributes. It is visually and structurally very similar to HTML [5], as both languages are simplifications of the earlier and larger standard SGML [6]. See figure 2 for the XML document corresponding to the graphical representation of a CPL script in figure 1. Both nodes and outputs in the CPL are represented by XML tags; parameters are represented by XML tag attributes. Typically, node tags contain output tags, and vice-versa (with one exception; see section 4.1). The connection between the output of a node and another node is represented by enclosing the tag representing the pointed-to node inside the tag for the outer node's output. Convergence (several outputs pointing to a single node) is represented by links, discussed further in section 7. The top-level node is enclosed in the special tag call; this is therefore the outermost tag of the XML. A complete Document Type Declaration for the CPL is provided in Appendix A. The remainder of the main sections of this document describe the semantics of the CPL; for its syntax, please see the appendix. 3 Switches Switches represent choices the CPL script can make, based on either attributes of the original call request or items independent of the call. All switches are arranged as a list of conditions that can match a variable, each with one output pointing to the next node to execute if that condition is matched. The conditions specified are tried in the order they are presented in the script; the output corresponding to the first node to match is taken. Switches also have an optional otherwise output, following all the other outputs, that matches if no previous node matched. If a switch does not have an otherwise output, and no condition matched, the server should take a default action, just as for any other un-attached node output, as discussed in section 2.1. The variable to match is specified in the initial switch tag, as a field parameter. What variables are legal depends on which switch Lennox/Schulzrinne [Page 4] Internet Draft CPL February 26, 1999 Figure 2: Sample CPL Script: XML Version type is specified; some variables are optional, and CPL servers MAY define additional variables for each switch type. Because some variables may not be supported by a server, CPL servers SHOULD verify, at the time a script is submitted, that they support all the variables specified in the script. 3.1 String Switch String-switch is a condition which allows string matching on a string variable. The node tag is named string-switch, and takes one argument, field, as discussed above. The output tags are named string, and take one mandatory and one optional argument. The mandatory argument's name is one of is, contains, or matches, indicating exact string match, substring match, or glob match of the variable respectively. The optional argument of string output tags is comparator, which allows for internationalization of string matching. Strings to be matched are always considered as strings of UTF-8 characters. CPL servers MUST support the two comparators i;octet, indicating literal Lennox/Schulzrinne [Page 5] Internet Draft CPL February 26, 1999 comparison of UTF-8 octets, and i;ascii-casemap, which indicates that alphabetic characters in the US-ASCII range should have their upper and lower cases compared the same. If no comparitor is specified, i;ascii-casemap is assumed. Comparators are defined by ACAP [7]; for more information, see that specification. CPL servers SHOULD verify at script submission time that all requested comparators are supported by the server. The naming scheme of comparators is as defined by ACAP; the motivation of the "i;" prefix of the comparators is unclear, but it seems to be some sort of namespace for future use. Question: should comparator be an attribute of the whole string-switch as opposed to an attribute of each comparison? There are arguments for either behavior. All CPL servers MUST define the fields to and from for string matching, containing URIs referring to the called and calling addresses, respectively. CPL servers which run on SIP SHOULD also define request-uri, subject, organization, priority, containing the contents of the equivalent SIP headers, if present, and also display-to, and display-from, containing the display names corresponding to the called and calling addresses. CPL servers which run on H.323 SHOULD define XXX. Question: what are the appropriate string fields for H.323? In this example, action1 is performed if the URL representation of the caller's address exactly matches "sip:lennox@cs.columbia.edu," action2 is performed for any string which matches any user at any host in the cs.columbia.edu domain, and action3 is taken in all other cases. -action1- -action2- -action3- Lennox/Schulzrinne [Page 6] Internet Draft CPL February 26, 1999 3.2 Time Switch Time-switch is a condition which allows matching on the time and/or date the triggering call was placed. Times are matched in the server's time zone. The node tag is named time-switch, and takes no arguments; the output tags are named time. Note: while it would be nice to allow clients to specify their own time zone, there doesn't currently appear to be any standard registry of time zone names, and we don't want to have to define one just for the CPL. Leveraging off of the iCalendar standard [8] would be nice, but their time zone specification seems excessively heavyweight -- it defines time zone rules explicitly (and very verbosely) in its own syntax. Just specifying time zones as UTC offsets would be possible, but this doesn't cover daylight-savings time rules. Thus, we currently ignore the problem. The time outputs can take the following optional arguments: year, month, date, day, and timeofday. Each argument is syntactically expressed as a list of numeric ranges. Ranges are delimited as value-value; lists elements are separated by commas. Months are specified in the range 1-12; date as 1-31, day as 0-6 (where 0 is Sunday), and times of day as 24-hour times in the range 0000-2359; years are unlimited in range, though only positive values are allowed. An output node matches if the time the triggering call was placed falls within one of the ranges in all of the specified arguments. The following examples show sample time nodes, and descriptions of the corresponding time periods they indicate: