4.4. Audit Elements
The audit elements defined in this section allow the MS to be audited for package capabilities as well as dialogs managed by the package. Auditing is particularly important for two use cases. First, it enables discovery of package capabilities supported on an MS before an AS starts a dialog on connection or conference. The AS can then use this information to create request elements using supported capabilities and, in the case of codecs, to negotiate an appropriate SDP for a User Agent's connection. Second, auditing enables discovery of the existence and status of dialogs currently managed by the package on the MS. This could be used when one AS takes over management of the dialogs if the AS that initiated the dialogs fails or is no longer available (see Security Considerations described in Section 7).4.4.1. <audit>
The <audit> request element is sent to the MS to request information about the capabilities of, and dialogs currently managed with, this Control Package. Capabilities include supported dialog languages, grammar formats, record and media types, as well as codecs. Dialog information includes the status of managed dialogs as well as codecs. The <audit> element has the following attributes:
capabilities: indicates whether package capabilities are to be audited. A valid value is a boolean (see Section 4.6.1). A value of true indicates that capability information is to be reported. A value of false indicates that capability information is not to be reported. The attribute is optional. The default value is true. dialogs: indicates whether dialogs currently managed by the package are to be audited. A valid value is a boolean (see Section 4.6.1). A value of true indicates that dialog information is to be reported. A value of false indicates that dialog information is not to be reported. The attribute is optional. The default value is true. dialogid: string identifying a specific dialog to audit. The MS sends a response with a 406 status code (Section 4.5) if the specified dialog identifier is invalid. The attribute is optional. There is no default value. If the dialogs attribute has the value true and dialogid attribute is specified, then only audit information about the specified dialog is reported. If the dialogs attribute has the value false, then no dialog audit information is reported even if a dialogid attribute is specified. The <audit> element has no child elements. When the MS receives an <audit> request, it MUST reply with an <auditresponse> element (Section 4.4.2), which includes a mandatory attribute describing the status in terms of a numeric code. Response status codes are defined in Section 4.5. If the request is successful, the <auditresponse> contains (depending on attribute values) a <capabilities> element (Section 4.4.2.2) reporting package capabilities and a <dialogs> element (Section 4.4.2.3) reporting managed dialog information. If the MS is not able to process the request and carry out the audit operation, the audit request has failed and the MS MUST indicate the class of failure using an appropriate 4xx response code. Unless an error response code is specified for a class of error within this section, implementations follow Section 4.5 in determining the appropriate status code for the response. For example, a request to audit capabilities and dialogs managed by the package: <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr"> <audit/> </mscivr>
In this example, only capabilities are to be audited: <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr"> <audit dialogs="false"/> </mscivr> With this example, only a specific dialog is to be audited: <mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr"> <audit capabilities="false" dialogid="d4"/> </mscivr>4.4.2. <auditresponse>
The <auditresponse> element describes a response to an <audit> request. The <auditresponse> element has the following attributes: status: numeric code indicating the audit response status. The attribute is mandatory. Valid values are defined in Section 4.5. reason: string specifying a reason for the status. The attribute is optional. desclang: specifies the language used in the value of the reason attribute. A valid value is a language identifier (Section 4.6.11). The attribute is optional. If not specified, the value of the desclang attribute on <mscivr> (Section 4.1) applies. The <auditresponse> element has the following sequence of child elements: <capabilities> element (Section 4.4.2.2) describing capabilities of the package. The element is optional. <dialogs> element (Section 4.4.2.3) describing information about managed dialogs. The element is optional. For example, a successful response to an <audit> request requesting capabilities and dialogs information:
<mscivr version="1.0" xmlns="urn:ietf:params:xml:ns:msc-ivr"> <auditresponse status="200"> <capabilities> <dialoglanguages> <mimetype>application/voicexml+xml</mimetype> </dialoglanguages> <grammartypes/> <recordtypes> <mimetype>audio/x-wav</mimetype> <mimetype>video/3gpp</mimetype> </recordtypes> <prompttypes> <mimetype>audio/x-wav</mimetype> <mimetype>video/3gpp</mimetype> </prompttypes> <variables> <variabletype type="date" desc="value formatted as YYYYMMDD"> <format desc="month year day">mdy</format> <format desc="year month day">ymd</format> <format desc="day month year">dmy</format> <format desc="day month">dm</format> </variabletype> </variables> <maxpreparedduration>600s</maxpreparedduration> <maxrecordduration>1800s</maxrecordduration> <codecs> <codec name="video"> <subtype>H263</subtype> </codec> <codec name="video"> <subtype>H264</subtype> </codec> <codec name="audio"> <subtype>PCMU</subtype> </codec> <codec name="audio"> <subtype>PCMA</subtype> </codec> <codec name="audio"> <subtype>telephone-event</subtype> </codec> </codecs> </capabilities> <dialogs> <dialogaudit dialogid="4532" state="preparing"/> <dialogaudit dialogid="4599" state="prepared"/> <dialogaudit dialogid="1234" state="started" conferenceid="conf1"> <codecs>
<codec name="audio"> <subtype>PCMA</subtype> </codec> <codec name="audio"> <subtype>telephone-event</subtype> </codec> </codecs> </dialogaudit> </dialogs> </auditresponse> </mscivr>4.4.2.1. <codecs>
The <codecs> provides audit information about codecs. The <codecs> element has no attributes. The <codecs> element has the following sequence of child elements (0 or more occurrences): <codec>: audit information for a codec (Section 4.4.2.1.1). The element is optional. For example, a fragment describing two codecs: <codecs> <codec name="audio"> <subtype>PCMA</subtype> </codec> <codec name="audio"> <subtype>telephone-event</subtype> </codec> </codecs>4.4.2.1.1. <codec>
The <codec> element describes a codec on the MS. The element is modeled on the <codec> element in the XCON conference information data model [XCON-DATA-MODEL] but allows addition information (e.g., rate, speed, etc.) to be specified. The <codec> element has the following attributes: name: indicates the type name of the codec's media format as defined in [IANA]. A valid value is a "type-name" as defined in Section 4.2 of [RFC4288]. The attribute is mandatory.
The <codec> element has the following sequence of child elements: <subtype>: element whose content model describes the subtype of the codec's media format as defined in [IANA]. A valid value is a "subtype-name" as defined in Section 4.2 of [RFC4288]. The element is mandatory. <params>: element (Section 4.2.6) describing additional information about the codec. This package is agnostic to the names and values of the codec parameters supported by an implementation. The element is optional. For example, a fragment with a <codec> element describing the H263 video codec: <codec name="video"> <subtype>H263</subtype> </codec>4.4.2.2. <capabilities>
The <capabilities> element provides audit information about package capabilities. The <capabilities> element has no attributes. The <capabilities> element has the following sequence of child elements: <dialoglanguages>: element (Section 4.4.2.2.1) describing additional dialog languages supported by the MS. The element is mandatory. <grammartypes>: element (Section 4.4.2.2.2) describing supported <grammar> (Section 4.3.1.3.1) format types. The element is mandatory. <recordtypes>: element (Section 4.4.2.2.3) describing <media> (Section 4.3.1.5) format types supported for <record> (Section 4.3.1.4). The element is mandatory. <prompttypes>: element (Section 4.4.2.2.4) describing supported <media> (Section 4.3.1.5) format types for playback within a <prompt> (Section 4.3.1.1). The element is mandatory. <variables>: element (Section 4.4.2.2.5) describing supported types and formats for the <variable> element (Section 4.3.1.1.1). The element is mandatory.
<maxpreparedduration>: element (Section 4.4.2.2.6) describing the supported maximum duration for a prepared dialog following a <dialogprepare> (Section 4.2.1) request. The element is mandatory. <maxrecordduration>: element (Section 4.4.2.2.7) describing the supported maximum duration for a recording <record> (Section 4.3.1.4) request. The element is mandatory. <codecs>: element (Section 4.4.2.1) describing codecs available to the package. The element is mandatory. For example, a fragment describing capabilities: <capabilities> <dialoglanguages> <mimetype>application/voicexml+xml</mimetype> </dialoglanguages> <grammartypes/> <recordtypes> <mimetype>audio/x-wav</mimetype> <mimetype>video/3gpp</mimetype> </recordtypes> <prompttypes> <mimetype>audio/x-wav</mimetype> <mimetype>video/3gpp</mimetype> </prompttypes> <variables/> <maxpreparedduration>30s</maxpreparedduration> <maxrecordduration>60s</maxrecordduration> <codecs> <codec name="video"> <subtype>H263</subtype> </codec> <codec name="video"> <subtype>H264</subtype> </codec> <codec name="audio"> <subtype>PCMU</subtype> </codec> <codec name="audio"> <subtype>PCMA</subtype> </codec> <codec name="audio"> <subtype>telephone-event</subtype> </codec> </codecs> </capabilities>
4.4.2.2.1. <dialoglanguages>
The <dialoglanguages> element provides information about additional dialog languages supported by the package. Dialog languages are identified by their associated MIME media types. The MS MUST NOT include the mandatory dialog language for this package (Section 4.3). The <dialoglanguages> element has no attributes. The <dialoglanguages> element has the following sequence of child elements (0 or more occurrences): <mimetype>: element whose content model describes a MIME media type (Section 4.6.10) associated with a supported dialog language. The element is optional.4.4.2.2.2. <grammartypes>
The <grammartypes> element provides information about <grammar> format types supported by the package. The MS MUST NOT include the mandatory SRGS format type, "application/srgs+xml" (Section 4.3.1.3.1). The <grammartypes> element has no attributes. The <grammartypes> element has the following sequence of child elements (0 or more occurrences): <mimetype>: element whose content model describes a mime type (Section 4.6.10). The element is optional.4.4.2.2.3. <recordtypes>
The <recordtypes> element provides information about media resource format types of <record> supported by the package (Section 4.3.1.4). The <recordtypes> element has no attributes. The <recordtypes> element has the following sequence of child elements (0 or more occurrences): <mimetype>: element whose content model describes a mime type (Section 4.6.10). The element is optional.4.4.2.2.4. <prompttypes>
The <prompttypes> element provides information about media resource format types of <prompt> supported by the package (Section 4.3.1.1).
The <prompttypes> element has no attributes. The <prompttypes> element has the following sequence of child elements (0 or more occurrences): <mimetype>: element whose content model describes a mime type (Section 4.6.10). The element is optional.4.4.2.2.5. <variables>
The <variables> element provides information about types and formats for the <variable> element (Section 4.3.1.1.1) supported by the package. The <variables> element has no attributes. The <variables> element has the following sequence of child elements (0 or more occurrences): <variabletype>: element describing the formats support for a given type (Section 4.4.2.2.5.1). The element is optional. For example, a fragment describing support for <variable> with a "date" type according to the formats specified in Section 4.3.1.1.1.1. <variables> <variabletype type="date" desc="value formatted as YYYYMMDD"> <format desc="month year day">mdy</format> <format desc="year month day">ymd</format> <format desc="day month year">dmy</format> <format desc="day month">dm</format> </variabletype> </variables>4.4.2.2.5.1. <variabletype> The <variabletype> element describes the formats supported for <variable> supported type. The <variabletype> element has the following attributes: type: indicates a supported value associated with the type attribute of the <variable> element. The attribute is mandatory. desc: a string providing some textual description of the type and format. The attribute is optional.
desclang: specifies the language used in the value of the desc attribute. A valid value is a language identifier (Section 4.6.11). The attribute is optional. If not specified, the value of the desclang attribute on <mscivr> (Section 4.1) applies. The <variabletype> element has the following sequence of child elements (0 or more occurrences): <format>: element with a desc attribute (optional description), desclang (optional language identifier for the description), and a content model describing a supported format in the <variable> format attribute. The element is optional.4.4.2.2.6. <maxpreparedduration>
The <maxpreparedduration> element describes the maximum duration for a dialog to remain in the prepared state (Section 4.2) following a <dialogprepare> (Section 4.2.1) request. The <maxpreparedduration> element has no attributes. The <maxpreparedduration> element has a content model describing the maximum prepared dialog duration as a time designation (Section 4.6.7).4.4.2.2.7. <maxrecordduration>
The <maxrecordduration> element describes the maximum recording duration for <record> Section 4.3.1.4) request supported by the MS. The <maxrecordduration> element has no attributes. The <maxrecordduration> element has a content model describing the maximum duration of recording as a time designation (Section 4.6.7).4.4.2.3. <dialogs>
The <dialogs> element provides audit information about dialogs. The <dialogs> element has no attributes. The <dialogs> element has the following sequence of child elements (0 or more occurrences): <dialogaudit>: audit information for a dialog (Section 4.4.2.3.1). The element is optional.
4.4.2.3.1. <dialogaudit>
The <dialogaudit> element has the following attributes: dialogid: string identifying the dialog. The attribute is mandatory. state: string indicating the state of the dialog. Valid values are preparing, prepared, starting, and started. The attribute is mandatory. connectionid: string identifying the SIP dialog connection associated with the dialog (see Appendix A.1 of [RFC6230]). The attribute is optional. There is no default value. conferenceid: string identifying the conference associated with the dialog (see Appendix A.1 of [RFC6230]). The attribute is optional. There is no default value. The <dialogaudit> element has the following child element: <codecs> element describing codecs used in the dialog. See Section 4.4.2.1. The element is optional. For example, a fragment describing a started dialog that is using PCMU and telephony-event audio codecs: <dialogaudit dialogid="1234" state="started" conferenceid="conf1"> <codecs> <codec name="audio"> <subtype>PCMU</subtype> </codec> <codec name="audio"> <subtype>telephone-event</subtype> </codec> </codecs> </dialogaudit>4.5. Response Status Codes
This section describes the response codes in Table 1 for the status attribute of dialog management <response> (Section 4.2.4) and audit <auditresponse> (Section 4.4.2) responses. The MS MUST support the status response codes defined here. All other valid but undefined values are reserved for future use, where new status codes are assigned using the Standards Action process defined in [RFC5226]. The AS MUST treat any responses it does not recognize as being equivalent to the x00 response code for all classes. For example, if
an AS receives an unrecognized response code of 499, it can safely assume that there was something wrong with its request and treat the response as if it had received a 400 (Syntax error) response code. 4xx responses are definite failure responses from a particular MS. The reason attribute in the response SHOULD identify the failure in more detail, for example, "Mandatory attribute missing: src in media element" for a 400 (Syntax error) response code. The AS SHOULD NOT retry the same request without modification (for example, correcting a syntax error or changing the connectionid to use one available on the MS). However, the same request to a different MS might be successful, for example, if another MS supports a capability required in the request. 4xx failure responses can be grouped into three classes: failure due to a syntax error in the request (400); failure due to an error executing the request on the MS (405-419); and failure due to the request requiring a capability not supported by the MS (420-439). In cases where more than one request code could be reported for a failure, the MS SHOULD use the most specific error code of the failure class for the detected error. For example, if the MS detects that the dialogid in the request is invalid, then it uses a 406 status code. However, if the MS merely detects that an execution error occurred, then 419 is used.
+------+---------------+-----------------------+--------------------+
| Code | Summary | Description | Informational: AS |
| | | | Possible Recovery |
| | | | Action |
+------+---------------+-----------------------+--------------------+
| 200 | OK | request has | |
| | | succeeded. | |
| 400 | Syntax error | request is | Change the request |
| | | syntactically | so that it is |
| | | invalid: it is not | syntactically |
| | | valid with respect to | valid. |
| | | the XML schema | |
| | | specified in | |
| | | Section 5 or it | |
| | | violates a | |
| | | co-occurrence | |
| | | constraint for a | |
| | | request element | |
| | | defined in Section 4. | |
| 405 | dialogid | request uses a | Send a request for |
| | already | dialogid identifier | a new dialog |
| | exists | for a new dialog that | without specifying |
| | | is already used by | the dialogid and |
| | | another dialog on the | let the MS |
| | | MS (see Section 4.2). | generate a unique |
| | | | dialogid in the |
| | | | response. |
| 406 | dialogid does | request uses a | Send an <audit> |
| | not exist | dialogid identifier | request |
| | | for an dialog that | (Section 4.4.1) |
| | | does not exist on the | requesting the |
| | | MS (see Section 4.2). | list of dialog |
| | | | identifiers |
| | | | already used by |
| | | | the MS and then |
| | | | use one of the |
| | | | listed dialog |
| | | | identifiers. |
| 407 | connectionid | request uses a | Use another method |
| | does not | connectionid | to determine which |
| | exist | identifier for a | connections are |
| | | connection that does | available on the |
| | | not exist on the MS. | MS. |
| 408 | conferenceid | request uses a | Use another method |
| | does not | conferenceid | to determine which |
| | exist | identifier for a | conferences are |
| | | conference that does | available on the |
| | | not exist on the MS. | MS. |
| 409 | Resource | request uses a URI to | Check that the |
| | cannot be | reference an external | resource URI is |
| | retrieved | resource (e.g., | valid, can be |
| | | dialog, media, or | reached from the |
| | | grammar) that cannot | MS, and that the |
| | | be retrieved within | appropriate |
| | | the timeout interval. | authentication is |
| | | | used. |
| 410 | Dialog | request to prepare or | |
| | execution | start a dialog that | |
| | canceled | has been terminated | |
| | | by a | |
| | | <dialogterminate/> | |
| | | request (see | |
| | | Section 4.2). | |
| 411 | Incompatible | request specifies a | Change the media |
| | stream | media stream | stream |
| | configuration | configuration that is | configuration to |
| | | in conflict with | match the |
| | | itself, or the | capabilities of |
| | | connection or | the connection or |
| | | conference | conference. |
| | | capabilities (see | |
| | | Section 4.2.2). | |
| 412 | Media stream | request specifies an | Check the media |
| | not available | operation for which a | stream capability |
| | | media stream is not | of the connection |
| | | available. For | or conference and |
| | | example, playing a | use an operation |
| | | video media resource | that only uses |
| | | on an connection or | these |
| | | conference without | capabilities. |
| | | video streams. | |
| 413 | Control keys | request contains a | Use different keys |
| | with same | <control> element | for the different |
| | value | (Section 4.3.1.2) | control |
| | | where some keys have | operations. |
| | | the same value. | |
| 419 | Other | requested operation | |
| | execution | cannot be executed by | |
| | error | the MS. | |
| 420 | Unsupported | request specifies a | Use a URI scheme |
| | URI scheme | URI whose scheme is | that is supported. |
| | | not supported by the | |
| | | MS. | |
| 421 | Unsupported | request references an | Send an <audit> |
| | dialog | external dialog | request |
| | language | language not | (Section 4.4.1) |
| | | supported by the MS. | requesting the MS |
| | | | capabilities and |
| | | | then use one of |
| | | | the listed dialog |
| | | | languages. |
| 422 | Unsupported | request references a | Send an <audit> |
| | playback | media resource for | request |
| | format | playback whose format | (Section 4.4.1) |
| | | is not supported by | requesting the MS |
| | | the MS. | capabilities and |
| | | | then use one of |
| | | | the listed |
| | | | playback media |
| | | | formats. |
| 423 | Unsupported | request references a | Send an <audit> |
| | record format | media resource for | request |
| | | recording whose | (Section 4.4.1) |
| | | format is not | requesting the MS |
| | | supported by the MS. | capabilities and |
| | | | then use one of |
| | | | the listed record |
| | | | media formats. |
| 424 | Unsupported | request references a | Send an <audit> |
| | grammar | grammar whose format | request |
| | format | is not supported by | (Section 4.4.1) |
| | | the MS. | requesting the MS |
| | | | capabilities and |
| | | | then use one of |
| | | | the listed grammar |
| | | | types. |
| 425 | Unsupported | request contains a | Send an <audit> |
| | variable | prompt <variable> | request |
| | configuration | element | (Section 4.4.1) |
| | | (Section 4.3.1.1.1) | requesting the MS |
| | | not supported by the | capabilities and |
| | | MS. | then use one of |
| | | | the listed |
| | | | variable types. |
| 426 | Unsupported | request contains a | |
| | DTMF | prompt <dtmf> element | |
| | configuration | (Section 4.3.1.1.2) | |
| | | not supported by the | |
| | | MS. | |
| 427 | Unsupported | request contains a | |
| | parameter | <param> element | |
| | | (Section 4.2.6.1) not | |
| | | supported by the MS. | |
| 428 | Unsupported | request contains a | |
| | media stream | <stream> element | |
| | configuration | (Section 4.2.2.2) | |
| | | whose configuration | |
| | | is not supported by | |
| | | the MS. | |
| 429 | Unsupported | request contains a | |
| | playback | <prompt> element | |
| | configuration | (Section 4.3.1.1) | |
| | | that the MS is unable | |
| | | to play on the | |
| | | available output | |
| | | media streams. | |
| 430 | Unsupported | request contains a | |
| | record | <record> element | |
| | configuration | (Section 4.3.1.4) | |
| | | that the MS is unable | |
| | | to record with on the | |
| | | available input media | |
| | | streams. | |
| 431 | Unsupported | request contains | |
| | foreign | attributes or | |
| | namespace | elements from another | |
| | attribute or | namespace that the MS | |
| | element | does not support. | |
| 432 | Unsupported | request tries to | |
| | multiple | start another dialog | |
| | dialog | on the same | |
| | capability | conference or | |
| | | connection where a | |
| | | dialog is already | |
| | | running. | |
| 433 | Unsupported | request contains | |
| | collect and | <collect> and | |
| | record | <record> elements and | |
| | capability | the MS does support | |
| | | these operations | |
| | | simultaneously. | |
| 434 | Unsupported | request contains a | |
| | VAD | <record> element | |
| | capability | where Voice Activity | |
| | | Detection (VAD) is | |
| | | required, but the MS | |
| | | does not support VAD. | |
| 435 | Unsupported | request contains a | | | | parallel | prompt <par> element | | | | playback | whose configuration | | | | | is not supported by | | | | | the MS. | | | 439 | Other | request requires | | | | unsupported | another capability | | | | capability | not supported by the | | | | | MS. | | +------+---------------+-----------------------+--------------------+ Table 1: Status Codes4.6. Type Definitions
This section defines types referenced in attribute and element definitions.4.6.1. Boolean
The value space of boolean is the set {true, false, 1, 0} as defined in Section 3.2.2 of [XMLSchema:Part2]. In accordance with this definition, the concept of false can be lexically represented by the strings "0" and "false" and the concept of true by the strings "1" and "true"; implementations MUST support both styles of lexical representation.4.6.2. DTMFChar
A DTMF character. The value space is the set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *, A, B, C, D}.4.6.3. DTMFString
A string composed of one or more DTMFChars.4.6.4. Non-Negative Integer
The value space of non-negative integer is the infinite set {0,1,2,...} as defined in Section 3.3.20 of [XMLSchema:Part2]. Implementation Note: It is RECOMMENDED that implementations at least support a maximum value of a 32-bit integer (2,147,483,647).4.6.5. Positive Integer
The value space of positive integer is the infinite set {1,2,...} as defined in Section 3.3.25 of [XMLSchema:Part2].
Implementation Note: It is RECOMMENDED that implementations at least support a maximum value of a 32-bit integer (2,147,483,647).4.6.6. String
A string in the character encoding associated with the XML element as defined in Section 3.2.1 of [XMLSchema:Part2].4.6.7. Time Designation
A time designation consists of a non-negative real number followed by a time unit identifier. The time unit identifiers are "ms" (milliseconds) and "s" (seconds). Examples include: "3s", "850ms", "0.7s", ".5s", and "+1.5s".4.6.8. Percentage
A percentage consists of a positive integer followed by "%". Examples include: "100%", "500%", and "10%".4.6.9. URI
Uniform Resource Indicator as defined in [RFC3986].4.6.10. MIME Media Type
A string formatted as an IANA MIME media type [MIME.mediatypes]. The ABNF [RFC5234] production for the string is: type = type-name "/" subtype-name *(";" parameter) parameter = parameter-name "=" value where "type-name" and "subtype-name" are defined in Section 4.2 of [RFC4288], "parameter-name" is defined in Section 4.3 of [RFC4288], and "value" is defined in Section 5.1 of [RFC2045].4.6.11. Language Identifier
A language identifier labels information content as being of a particular human language variant. Following the XML specification for language identification [XML], a legal language identifier is identified by a [RFC5646] code and matched according to [RFC4647].
4.6.12. DateTime
A string formatted according to the XML schema definition of a dateTime type [XMLSchema:Part2].