Broadband Forum

    DATA MODEL DEFINITION


Component Objects for CWMP
tr-157-1-6-0.xml

License

Copyright (c) 2009-2017, Broadband Forum

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The above license is used as a license under copyright only. Please reference the Forum IPR Policy for patent licensing terms <https://www.broadband-forum.org/ipr-policy>.

Any moral rights which are necessary to exercise under the above license grant are also deemed granted under this license.

Summary

TR-157 Amendment 6 (define BulkDataCollection component)

Table of Contents

Data Types

The Parameters defined in this specification make use of a limited subset of the default SOAP data types [SOAP1.1]. These data types and the named data types used by this specification are described below.

Note: A Parameter that is defined to be one of the named data types is reported as such at the beginning of the Parameter's description via a reference back to the associated data type definition (e.g. [MacAddress]). However, such parameters still indicate their SOAP data type.

Data Type Base Type Description
boolean - Boolean, where the allowed values are 0 or 1 (or equivalently, true or false).
dateTime - The subset of the ISO 8601 date-time format defined by the SOAP dateTime type.
int -

Integer in the range -2147483648 to +2147483647, inclusive.

For some int types, a value range is given using the form int[Min:Max] or int[Min:Max step Step] where the Min and Max values are inclusive. If either Min or Max are missing, this indicates no limit. If Step is missing, this indicates a step of 1. Multiple comma-separated ranges can be specified, in which case the value will be in one of the ranges.

string - For strings, a minimum and maximum allowed length can be indicated using the form string(Min:Max), where Min and Max are the minimum and maximum string length in characters. If either Min or Max are missing, this indicates no limit, and if Min is missing the colon can also be omitted, as in string(Max). Multiple comma-separated ranges can be specified, in which case the string length will be in one of the ranges.
unsignedInt -

Unsigned integer in the range 0 to 4294967295, inclusive.

For some unsignedInt types, a value range is given using the form unsignedInt[Min:Max] or unsigned[Min:Max step Step], where the Min and Max values are inclusive. If either Min or Max are missing, this indicates no limit. If Step is missing, this indicates a step of 1. Multiple comma-separated ranges can be specified, in which case the value will be in one of the ranges.

Alias string(64)

A non-volatile handle used to reference this instance. Alias provides a mechanism for an ACS to label this instance for future reference.

If the CPE supports the Alias-based Addressing feature as defined in [Section 3.6.1/TR-069] and described in [Appendix II/TR-069], the following mandatory constraints MUST be enforced:

  • Its value MUST NOT be empty.
  • Its value MUST start with a letter.
  • If its value is not assigned by the ACS, it MUST start with a "cpe-" prefix.
  • The CPE MUST NOT change the parameter value.

References

[IPDR-FTP] IPDR File Transfer Protocol, IPDR/File Transfer Protocol, TM Forum.
[IPDR-SP] IPDR Streaming Protocol, IPDR Streaming Protocol (IPDR/SP) Specification, TM Forum.
[IPDR-XDR] IPDR XDR Encoding Format, IPDR/XDR Encoding Format, TM Forum.
[IPDR-XML] IPDR XML File Encoding Format, IPDR/XML File Encoding Format, TM Forum.
[SOAP1.1] Simple Object Access Protocol (SOAP) 1.1, W3C.
[TR-069] TR-069 Amendment 6, CPE WAN Management Protocol, Broadband Forum, April 2018.
[TR-106a2] TR-106 Amendment 2, Data Model Template for TR-069-Enabled Devices, Broadband Forum, November 2008.
[TR-232] TR-232, Bulk Data Collection, Broadband Forum, May 2012.

TR-1:5.7 Data Model

For a given implementation of this data model, the Agent MUST indicate support for the highest version number of any object or parameter that it supports. For example, even if the Agent supports only a single parameter that was introduced in version 5.7, then it will indicate support for version 5.7. The version number associated with each object and parameter is shown in the Version column.

Name Type Write Description Object Default Version
BulkData. object -

Bulk Data collection utilizes the IPDR solution to collect data from devices based on a service specification described in [TR-232].

Bulk Data Collection Profiles are measured over a reporting interval (which can be aligned with absolute time) and are made available to the collection server.

This object provides bulk data collection capabilities and global collection settings that affect the entire device.

- 5.7
Enable boolean W

Enables or disables all collection profiles.

If false, bulk data will not be collected or reported.

- 5.7
Status string -

Indicates the status of the Bulk Data Collection mechanism. Enumeration of:

  • Enabled (Bulk Data Collection is enabled and working as intended)
  • Disabled (Bulk Data Collection is disabled)
  • Error (Bulk Data Collection is enabled, but there is an error condition preventing the successful collection of bulk data, OPTIONAL)
- 5.7
MinReportingInterval unsignedInt -

Minimum reporting interval in seconds that the CPE is capable of supporting.

A value of 0 indicates no minimum reporting interval.

- 5.7
Protocols string -

Comma-separated list of strings. Represents the IPDR Protocols that this device is capable of supporting. Each list item is an enumeration of:

- 5.7
EncodingTypes string -

Comma-separated list of strings. Represents the IPDR Encoding Types that this device is capable of supporting. Each list item is an enumeration of:

- 5.7
MaxNumberOfProfiles int­[-1:] -

The maximum number of profiles that can exist at any given time. Specifically, the maximum number of Profile.{i}. instances that the ACS can create.

If the value of this parameter is -1, then it means that the CPE doesn't have a limit to the number of profiles that can exist.

- 5.7
MaxNumberOfParameterReferences int­[-1:] -

The maximum number of parameters that can be referenced via the bulk data collection mechanism. Specifically, the maximum number of parameters that can be referenced via Profile.{i}.Parameter.{i}.Reference across all Profile and Parameter instances (including the expansion of partial paths within the Reference parameter).

If the value of this parameter is -1, then it means that the CPE doesn't have a limit to the number of parameter that can be referenced via the bulk data collection mechanism.

- 5.7
ProfileNumberOfEntries unsignedInt - The number of entries in the Profile table. - 5.7
BulkData.Profile.{i}. object W

A set of Bulk Data Collection profiles.

Each profile represents a bulk data report, including its own timing configuration, communications configuration, and set of parameters. This allows the ACS to configure multiple reports to be generated at different times for different sets of data.

At most one entry in this table (regardless of whether or not it is enabled) can exist with a given value for Alias. On creation of a new table entry, the Agent MUST choose an initial value for Alias such that the new entry does not conflict with any existing entries.

- 5.7
Enable boolean W

Enables or disables this specific bulk data profile.

If false, this profile will not be collected or reported.

false 5.7
Alias string­(64) W

[Alias] A non-volatile handle used to reference this instance. Alias provides a mechanism for an ACS to label this instance for future reference.

If the CPE supports the Alias-based Addressing feature as defined in [Section 3.6.1/TR-069] and described in [Appendix II/TR-069], the following mandatory constraints MUST be enforced:

  • Its value MUST NOT be empty.
  • Its value MUST start with a letter.
  • If its value is not assigned by the ACS, it MUST start with a "cpe-" prefix.
  • The CPE MUST NOT change the parameter value.
- 5.7
Protocol string W The value MUST be a member of the list reported by the Protocols parameter. The IPDR Protocol being used for this collection profile. - 5.7
EncodingType string W The value MUST be a member of the list reported by the EncodingTypes parameter. The IPDR Encoding Type being used for this collection profile. - 5.7
ReportingInterval unsignedInt­[1:] W

The reporting interval in seconds. Each report is generated based on this interval and TimeReference.

The CPE MAY reject a request to set ReportingInterval to less than MinReportingInterval.

Reporting intervals MUST begin every ReportingInterval seconds.

If ReportingInterval is changed while collection is enabled, the first reporting interval begins immediately.

For example, if ReportingInterval is 86400 (a day) and if TimeReference is set to UTC midnight on some day (in the past, present, or future) then the CPE will generate (and transmit, if the Protocol parameter is set to Streaming) its report at midnight every 24 hours.

86400 5.7
TimeReference dateTime W

An absolute time reference in UTC to determine when will be transmitted. Each reporting interval MUST complete at this reference time plus or minus an integer multiple of ReportingInterval, unless unable to due to higher prioritized operations.

TimeReference is used only to set the "phase" of the reporting intervals. The actual value of TimeReference can be arbitrarily far into the past or future.

If TimeReference is changed while collection of bulk data is enabled, the first reporting interval begins immediately.

The Unknown Time value as defined in [TR-106a2] indicates that no particular time reference is specified. That is, the CPE MAY locally choose the time reference, and is required only to adhere to the specified reporting intervals.

If absolute time is not available to the CPE, its reporting interval behavior MUST be the same as if the TimeReference parameter was set to the Unknown Time value.

For example, if ReportingInterval is 86400 (a day) and if TimeReference is set to UTC midnight on some day (in the past, present, or future) then the CPE will generate (and transmit, if in a "ITPush" mode) its report at midnight every 24 hours.

Note that, if TimeReference is set to a time other than the Unknown Time, the first reporting interval (which has to begin immediately) will almost certainly be shorter than ReportingInterval). This is why TimeReference is defined in terms of when reporting intervals complete rather than start.

0001-01-01T00:00:00Z 5.7
StreamingHost string­(256) W This is the host name or IP Address of the IPDR Collector to be used by the CPE to stream bulk data records if this collection profile is configured for the IPDR Streaming Protocol [IPDR-SP] (the Protocol parameter has a value of Streaming). - 5.7
StreamingPort unsignedInt­[0:65535] W This is the port number of the IPDR Collector to be used by the CPE to stream bulk data records if this collection profile is configured for the IPDR Streaming Protocol [IPDR-SP] (the Protocol parameter has a value of Streaming). 4737 5.7
StreamingSessionID unsignedInt­[48:57, 65:90] W

This is the unique identification of an IPDR Session to be used when this collection profile is configured for the IPDR Streaming Protocol [IPDR-SP] (the Protocol parameter has a value of Streaming).

An ACS MUST NOT configure multiple IPDR Streaming Protocol collection profiles with the same StreamingSessionID. Doing so MUST cause the CPE to fail the SetParameterValues.

Within the IPDR Streaming Protocol specification the Session ID has a type of a single 'char', but we are restricting the range even further (ASCII values of '0' - '9' and 'A' - 'Z'.

- 5.7
FileTransferURL string­(256) W This is the URL within the CPE that is used by an IPDR Collector to retrieve the IPDRDocs when this collection profile is configured for the IPDR File Transfer Protocol [IPDR-FTP] (the Protocol parameter has a value of File). - 5.7
FileTransferUsername string­(64) W

Username used for authentication of the FileTransferURL.

This is the FileTransferUsername that the IPDR Collector uses to access the CPE when this collection profile is configured for the IPDR File Transfer Protocol [IPDR-FTP] (the Protocol parameter has a value of File).

- 5.7
FileTransferPassword string­(64) W

Password used for authentication of the FileTransferURL.

This is the FileTransferPassword that the IPDR Collector uses to access the CPE when this collection profile is configured for the IPDR File Transfer Protocol [IPDR-FTP] (the Protocol parameter has a value of File).

When read, this parameter returns an empty string, regardless of the actual value.

- 5.7
ControlFileFormat string­(128) W

If this collection profile is configured for the IPDR File Transfer Protocol [IPDR-FTP] (the Protocol parameter has a value of File) then the control file names will be of the following format:

<ControlFilePrefix>_<ControlFilePolicy>.<ControlFileSuffix>

Where the following rules apply:

  • ControlFilePrefix MUST NOT contain an underscore '_' or any other character not suitable for a file name.
  • ControlFilePolicy MUST contain one or more ‘N’ characters, where the number of ‘N’ characters denotes the number of digits in the sequence number, including leading zeros as necessary to match the number of ‘N’ characters.
  • ControlFileSuffix is a file extension.

For example, BulkData_NNNN.log where "BulkData" would be the prefix, "NNNN" would be the policy, and "log" would be the suffix. Files adhering to this file format would look like: BulkData_0000.log, BulkData_0001.log, etc.

- 5.7
ParameterNumberOfEntries unsignedInt - The number of entries in the Parameter table. - 5.7
BulkData.Profile.{i}.Parameter.{i}. object W

Bulk data parameter table.

Each entry in this table represents a parameter (or set of parameters if a partial path is provided) to be collected and reported.

- 5.7
Reference string­(256) W

The value MUST be the Path Name of a parameter or object. Represents the parameter(s) that are part of this Bulk Data collection profile.

In the case where a partial parameter path is specified all sub-objects and contained parameters will be part of the bulk data collected and reported. If the path name refers to an object then it MUST end with a '.'.

<Empty> 5.7

Inform and Notification Requirements

Forced Inform Parameters

Parameter

Forced Active Notification Parameters

Parameter

Default Active Notification Parameters

Parameter

Parameters for which Active Notification MAY be Denied

Parameter

Profile Definitions

Notation

The following abbreviations are used to specify profile requirements:

Abbreviation Description
R Read support is REQUIRED.
W Both Read and Write support is REQUIRED. This MUST NOT be specified for a parameter that is defined as read-only.
P The object is REQUIRED to be present.
C Creation and deletion of instances of the object is REQUIRED.
A Creation of instances of the object is REQUIRED, but deletion is not REQUIRED.
D Deletion of instances of the object is REQUIRED, but creation is not REQUIRED.

BulkDataColl:1 Profile

This table defines the BulkDataColl:1 profile for the TR-1:5 data model. The minimum REQUIRED version for this profile is TR-1:5.7.

Name Requirement
BulkData. P
Enable W
Status R
MinReportingInterval R
Protocols R
EncodingTypes R
ProfileNumberOfEntries R
BulkData.­Profile.­{i}. C
Enable W
Alias W
Protocol W
EncodingType W
ReportingInterval W
TimeReference W
ParameterNumberOfEntries R
BulkData.­Profile.­{i}.­Parameter.­{i}. C
Reference W

BulkDataStreaming:1 Profile

The BulkDataStreaming:1 profile for the TR-1:5 data model is defined as the union of the BulkDataColl:1 profile and the additional requirements defined in this table. The minimum REQUIRED version for this profile is TR-1:5.7.

Name Requirement
BulkData.­Profile.­{i}. C
StreamingHost W
StreamingPort W
StreamingSessionID W

BulkDataFileTransfer:1 Profile

The BulkDataFileTransfer:1 profile for the TR-1:5 data model is defined as the union of the BulkDataColl:1 profile and the additional requirements defined in this table. The minimum REQUIRED version for this profile is TR-1:5.7.

Name Requirement
BulkData.­Profile.­{i}. C
FileTransferURL W
FileTransferUsername W
FileTransferPassword W
ControlFileFormat W


Generated by Broadband Forum report.pl#425 (2020-03-23 version) on 2020/04/03 at 13:10:04.
report.pl --exitcode=fatals --cwmpindex=.. --nofontstyles --nowarnreport --quiet --nomodels --automodel --report=html --outfile=tr-157-1-6-0.html tr-157-1-6-0.xml