Outputs: None (No node may follow)
Next node: None
Parameters: "status" Status code to return
"reason" Reason phrase to return
Figure 14: Syntax of the "reject" node
A reject node immediately terminates the execution of a CPL script,
so this node has no outputs and no next node.
This node has two arguments: "status" and "reason". The "status"
argument is required, and can take one of the values "busy",
"notfound", "reject", "error", or a signalling-protocol-defined
status.
The "reason" argument optionally allows the script to specify a
reason for the rejection.
6.3.1. Usage of "reject" with SIP
Servers which implement SIP SHOULD also allow the "status" field to
be a numeric argument corresponding to a SIP status in the 4xx, 5xx,
or 6xx range.
They SHOULD send the "reason" parameter in the SIP reason phrase.
A suggested mapping of the named statuses is as follows. Servers MAY
use a different mapping, though similar semantics SHOULD be
preserved.
"busy": 486 Busy Here
"notfound": 404 Not Found
"reject": 603 Decline
"error": 500 Internal Server Error
7. Non-signalling Operations
In addition to the signalling operations, CPL defines several
operations which do not affect and are not dependent on the telephony
signalling protocol.
7.1. Mail
The mail node causes the server to notify a user of the status of the
CPL script through electronic mail. Its syntax is given in Figure
15.
Node: "mail"
Outputs: None (Next node follows directly)
Next node: Any node
Parameters: "url" Mailto url to which the mail should be sent
Figure 15: Syntax of the "mail" node
The "mail" node takes one argument: a "mailto" URL giving the
address, and any additional desired parameters, of the mail to be
sent. The server sends the message containing the content to the
given url; it SHOULD also include other status information about the
original call request and the CPL script at the time of the
notification.
Using a full "mailto" URL rather than just an e-mail address
allows additional e-mail headers to be specified, such as
<mail url="mailto:jones@example.com?subject=Lookup%20failed" />.
A mail node has only one possible result, since failure of e-mail
delivery cannot reliably be known in real time. Therefore, its XML
representation does not have output tags: the <mail> tag directly
contains another node tag.
Note that the syntax of XML requires that ampersand characters, "&",
which are used as parameter separators in "mailto" URLs, be quoted as
"&" inside parameter values (see Section C.12 of the XML
specification [2]).
7.1.1. Suggested Content of Mailed Information
This section presents suggested guidelines for the mail sent as a
result of the "mail" node, for requests triggered by SIP. The
message mailed (triggered by any protocol) SHOULD contain all this
information, but servers MAY elect to use a different format.
1. If the "mailto" URI did not specify a subject header, the
subject of the e-mail is "[CPL]", followed by the subject
header of the SIP request. If the URI specified a subject
header, it is used instead.
2. The "From" field of the e-mail is set to a CPL server
configured address, overriding any "From" field in the "mailto"
URI.
3. Any "Reply-To" header in the URI is honored. If none is given,
then an e-mail-ized version of the origin field of the request
is used, if possible (e.g., a SIP "From" header with a sip: URI
would be converted to an e-mail address by stripping the URI
scheme).
4. If the "mailto" URI specifies a body, it is used. If none was
specified, the body SHOULD contain at least the identity of the
caller (both the caller’s display name and address), the date
and time of day, the call subject, and if available, the call
priority.
The server SHOULD honor the user’s requested languages, and send the
mail notification using an appropriate language and character set.
7.2. Log
The Log node causes the server to log information about the call to
non-volatile storage. Its syntax is specified in Figure 16.
Node: "log"
Outputs: None (Next node follows directly)
Next node: Any node
Parameters: "name" Name of the log file to use
"comment" Comment to be placed in log file
Figure 16: Syntax of the "log" node
Log takes two arguments, both optional: "name", which specifies the
name of the log, and "comment", which gives a comment about the
information being logged. Servers SHOULD also include other
information in the log, such as the time of the logged event,
information that triggered the call to be logged, and so forth. Logs
are specific to the owner of the script which logged the event. If
the "name" parameter is not given, the event is logged to a standard,
server-defined log file for the script owner. This specification
does not define how users may retrieve their logs from the server.
The name of a log is a logical name only, and does not necessarily
correspond to any physical file on the server. The interpretation of
the log file name is server defined, as is a mechanism to access
these logs. The CPL server SHOULD NOT directly map log names
uninterpreted onto local file names, for security reasons, lest a
security-critical file be overwritten.
A correctly operating CPL server SHOULD NOT ever allow the "log"
event to fail. As such, log nodes can have only one possible result,
and their XML representation does not have explicit output tags. A
CPL <log> tag directly contains another node tag.
8. Subactions
XML syntax defines a tree. To allow more general call flow diagrams,
and to allow script re-use and modularity, we define subactions.
Two tags are defined for subactions: subaction definitions and
subaction references. Their syntax is given in Figure 17.
Tag: "subaction"
Subtags: Any node
Parameters: "id" Name of this subaction
Pseudo-node: "sub"
Outputs: None in XML tree
Parameters: "ref" Name of subaction to execute
Figure 17: Syntax of subactions and "sub" pseudo-nodes
Subactions are defined through "subaction" tags. These tags are
placed in the CPL script after any ancillary information (see Section
9), but before any top-level tags. They take one argument: "id", a
token indicating a script-chosen name for the subaction. The "id"
value for every "subaction" tag in a script MUST be unique within
that script.
Subactions are called from "sub" tags. The "sub" tag is a "pseudo-
node", and can be used anyplace in a CPL action that a true node
could be used. It takes one parameter, "ref", the name of the
subaction to be called. The "sub" tag contains no outputs of its
own, instead control passes to the subaction.
References to subactions MUST refer to subactions defined before the
current action. A "sub" tag MUST NOT refer to the action it appears
in, or to any action defined later in the CPL script. Top-level
actions cannot be called from "sub" tags, or through any other means.
Script servers MUST verify at the time the script is submitted that
no "sub" node refers to any subaction that is not its proper
predecessor.
Allowing only back-references of subs forbids any sort of
recursion. Recursion would introduce the possibility of non-
terminating or non-decidable CPL scripts, a possibility our
requirements specifically excluded.
Every sub MUST refer to a subaction ID defined within the same CPL
script. No external links are permitted.
Subaction IDs are case sensitive.
If any subsequent version or extension defines external linkages,
it should probably use a different tag, perhaps XLink [21].
Ensuring termination in the presence of external links is a
difficult problem.
9. Ancillary Information
No ancillary information is defined in the base CPL specification.
If ancillary information, not part of any operation, is found to be
necessary for a CPL extension, it SHOULD be placed within this tag.
The (trivial) definition of the ancillary information tag is given in
Figure 18.
It may be useful to include timezone definitions inside CPL
scripts directly, rather than referencing them externally with
"tzid" and "tzurl" parameters. If it is, an extension could be
defined to include them here.
Tag: "ancillary"
Parameters: None
Subtags: None
Figure 18: Syntax of the "ancillary" tag
10. Default Behavior
When a CPL node reaches an unspecified output, either because the
output tag is not present, or because the tag is present but does not
contain a node, the CPL server’s behavior is dependent on the current
state of script execution. This section gives the operations that
should be taken in each case.
no location modifications or signalling operations performed,
location set empty: Look up the user’s location through
whatever mechanism the server would use if no CPL script were
in effect. Proxy, redirect, or send a rejection message,
using whatever policy the server would use in the absence of
a CPL script.
no location modifications or signalling operations performed,
location set non-empty: (This can only happen for outgoing
calls.) Proxy the call to the addresses in the location set.
location modifications performed, no signalling operations: Proxy
or redirect the call, whichever is the server’s standard
policy, to the addresses in the current location set. If the
location set is empty, return a "notfound" rejection.
noanswer output of proxy, no timeout given: (This is a special
case.) If the "noanswer" output of a proxy node is
unspecified, and no timeout parameter was given to the proxy
node, the call should be allowed to ring for the maximum
length of time allowed by the server (or the request, if the
request specified a timeout).
proxy operation previously taken: Return whatever the "best"
response is of all accumulated responses to the call to this
point, according to the rules of the underlying signalling
protocol.
11. CPL Extensions
Servers MAY support additional CPL features beyond those listed in
this document. Some of the extensions which have been suggested are
a means of querying how a call has been authenticated, richer control
over H.323 addressing, end-system or administrator-specific features,
regular-expression matching for strings and addresses, and mid-call
or end-of-call controls.
CPL extensions are indicated by XML namespaces [11]. Every extension
MUST have an appropriate XML namespace assigned to it. The XML
namespace of the extension MUST be different from the XML namespace
defined in Section 14. The extension MUST NOT change the syntax or
semantics of the CPL schema defined in this document. All XML tags
and attributes that are part of the extension MUST be appropriately
qualified so as to place them within that namespace.
Tags or attributes in a CPL script which are in the global namespace
(i.e., not associated with any namespace) are equivalent to tags and
attributes in the CPL namespace "urn:ietf:params:xml:ns:cpl".
A CPL script SHOULD NOT specify any namespaces it does not use. For
compatibility with non-namespace-aware parsers, a CPL script MAY omit
the base CPL namespace for a script which does not use any
extensions.
A CPL server MUST reject any script containing a reference to a
namespace it does not understand. It MUST reject any script
containing an extension tag or attribute that is not qualified to be
in an appropriate namespace.
A syntax such as
<extension-switch>
<extension has="http://www.example.com/foo">
[extended things]
</extension>
<otherwise>
[non-extended things]
</otherwise>
</extension-switch>
was suggested as an alternate way of handling extensions. This
would allow scripts to be uploaded to a server without requiring a
script author to somehow determine which extensions a server
supports. However, experience developing other languages, notably
Sieve [22], was that this added excessive complexity to languages.
The "extension-switch" tag could, of course, itself be defined in
a CPL extension.
In the XML schema of CPL, we introduce three abstract elements,
namely ’toplevelaction’, ’switch’, and ’action’, which accordingly
have the abstract type ’TopLevelActionType’, ’SwitchType’, and
’ActionType’. Any top-level action in a CPL extension MUST be
defined as the substitutionGroup of the abstract ’toplevelaction’
element, and have the type extended from the ’TopLevelActionType’.
Any switch in a CPL extension MUST be defined as the
substitutionGroup of the abstract ’switch’ element, and have the type
extended from the ’SwitchType’. Any action in a CPL extension MUST
be defined as the substitutionGroup of the abstract ’action’ element,
and have the type extended from the ’ActionType’.
12. Examples
12.1. Example: Call Redirect Unconditional
The script in Figure 19 is a simple script that redirects all calls
to a single fixed location.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<incoming>
<location url="sip:smith@phone.example.com">
<redirect/>
</location>
</incoming>
</cpl>
Figure 19: Example Script: Call Redirect Unconditional
12.2. Example: Call Forward Busy/No Answer
The script in Figure 20 illustrates some more complex behavior. We
see an initial proxy attempt to one address, with further operations
if that fails. We also see how several outputs take the same action
subtree, through the use of subactions.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<subaction id="voicemail">
<location url="sip:jones@voicemail.example.com">
<proxy/>
</location>
</subaction>
<incoming>
<location url="sip:jones@jonespc.example.com">
<proxy timeout="8">
<busy>
<sub ref="voicemail"/>
</busy>
<noanswer>
<sub ref="voicemail"/>
</noanswer>
</proxy>
</location>
</incoming>
</cpl>
Figure 20: Example Script: Call Forward Busy/No Answer
12.3. Example: Call Forward: Redirect and Default
The script in Figure 21 illustrates further proxy behavior. The
server initially tries to proxy to a single address. If this attempt
is redirected, a new redirection is generated using the locations
returned. In all other failure cases for the proxy node, a default
operation -- forwarding to voicemail -- is performed.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<incoming>
<location url="sip:jones@jonespc.example.com">
<proxy>
<redirection>
<redirect/>
</redirection>
<default>
<location url="sip:jones@voicemail.example.com">
<proxy/>
</location>
</default>
</proxy>
</location>
</incoming>
</cpl>
Figure 21: Example Script: Call Forward: Redirect and Default
12.4. Example: Call Screening
The script in Figure 22 illustrates address switches and call
rejection, in the form of a call screening script. Note also that
because the address-switch lacks an "otherwise" clause, if the
initial pattern does not match, the script does not define any
operations. The server therefore proceeds with its default behavior,
which would presumably be to contact the user.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<incoming>
<address-switch field="origin" subfield="user">
<address is="anonymous">
<reject status="reject" reason="I reject anonymous calls"/>
</address>
</address-switch>
</incoming>
</cpl>
Figure 22: Example Script: Call Screening
12.5. Example: Priority and Language Routing
The script in Figure 23 illustrates service selection based on a
call’s priority value and language settings. If the call request had
a priority of "urgent" or higher, the default script behavior is
performed. Otherwise, the language field is checked for the language
"es" (Spanish). If it is present, the call is proxied to a Spanish-
speaking operator; other calls are proxied to an English-speaking
operator.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<incoming>
<priority-switch>
<priority greater="urgent"/>
<otherwise>
<language-switch>
<language matches="es">
<location url="sip:spanish@operator.example.com">
<proxy/>
</location>
</language>
<otherwise>
<location url="sip:english@operator.example.com">
<proxy/>
</location>
</otherwise>
</language-switch>
</otherwise>
</priority-switch>
</incoming>
</cpl>
Figure 23: Example Script: Priority and Language Routing
12.6. Example: Outgoing Call Screening
The script in Figure 24 illustrates a script filtering outgoing
calls, in the form of a script which prevent 1-900 (premium) calls
from being placed. This script also illustrates subdomain matching.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<outgoing>
<address-switch field="original-destination" subfield="tel">
<address subdomain-of="1900">
<reject status="reject"
reason="Not allowed to make 1-900 calls."/>
</address>
</address-switch>
</outgoing>
</cpl>
Figure 24: Example Script: Outgoing Call Screening
12.7. Example: Time-of-day Routing
Figure 25 illustrates time-based conditions and timezones.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<incoming>
<time-switch tzid="America/New_York"
tzurl="http://zones.example.com/tz/America/New_York">
<time dtstart="20000703T090000" duration="PT8H" freq="weekly"
byday="MO,TU,WE,TH,FR">
<lookup source="registration">
<success>
<proxy/>
</success>
</lookup>
</time>
<otherwise>
<location url="sip:jones@voicemail.example.com">
<proxy/>
</location>
</otherwise>
</time-switch>
</incoming>
</cpl>
Figure 25: Example Script: Time-of-day Routing
12.8. Example: Location Filtering
Figure 26 illustrates filtering operations on the location set. In
this example, we assume that version 0.9beta2 of the "Inadequate
Software SIP User Agent" mis-implements some features, and so we must
work around its problems. We know that it cannot talk successfully
to one particular mobile device we may have registered, so we remove
that location from the location set. Once this operation has been
completed, call setup is allowed to proceed normally.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<incoming>
<string-switch field="user-agent">
<string is="Inadequate Software SIP User Agent/0.9beta2">
<lookup source="registration">
<success>
<remove-location location="sip:me@mobile.provider.net">
<proxy/>
</remove-location>
</success>
</lookup>
</string>
</string-switch>
</incoming>
</cpl>
Figure 26: Example Script: Location Filtering
12.9. Example: Non-signalling Operations
Figure 27 illustrates non-signalling operations; in particular,
alerting a user by electronic mail if the lookup server failed. The
primary motivation for having the "mail" node is to allow this sort
of out-of-band notification of error conditions, as the user might
otherwise be unaware of any problem.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<incoming>
<lookup
source="http://www.example.com/cgi-bin/locate.cgi?user=mary"
timeout="8">
<success>
<proxy/>