5.12 ECRControl API

29.1223GPPRelease 18T8 reference point for Northbound APIsTS

5.12.1 Overview

The ECRControl API is a custom API (RPC interaction) that allows the SCS/AS to query or configure the enhanced converage restriction over 3GPP networks. The ECRControl API defines a set of data models and related custom operation procedures for the enhanced coverage restriction control request. The corresponding JSON schema for the representation of the operations defined by the ECRControl API is provided in its complete form in Annex A.12.

5.12.2 Data model

5.12.2.1 Data types

5.12.2.1.1 Introduction

This clause defines data structures to be used in the request and response.

Table 5.12.2.1.1-1 specifies data types re-used by the ECRControl API from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the ECRControl API.

Table 5.12.2.1.1-1: ECRControl API re-used Data Types

Data type

Reference

Comments

EcRestrictionDataWb

3GPP TS 29.503 [63]

SupportedFeatures

3GPP TS 29.571 [45]

Used to negotiate the applicability of the optional features defined in table 5.12.4-1.

Table 5.12.2.1.1-2 specifies the data types defined for the ECRControl API.

Table 5.12.2.1.1-2: ECRControl API specific Data Types

Data type

Clause defined

Description

Applicability

ECRControl

5.12.2.1.2

Represents the parameters to request Enhanced Coverage Restriction control.

ECRData

5.12.2.1.3

Represents the current visited PLMN (if any) and the current settings of enhanced coverage restriction.

PlmnEcRestrictionDataWb

5.12.2.1.4

Indicates whether enhanced coverage mode is restricted or not for a PLMN ID.

ECR_WB_5G

5.12.2.1.2 Type: ECRControl

This type represents the Enhanced Coverage Restriction control request. The structure is used only for request.

Table 5.12.2.1.2-1: Definition of type ECRControl

Attribute name

Data type

Cardinality

Description

Applicability (NOTE 1)

supportedFeatures

SupportedFeatures

1

Used to negotiate the supported optional features of the API as described in clause 5.2.7.

mtcProviderId

string

0..1

Identifier the MTC Service Provider and/or MTC Application. (NOTE 4).

scsAsId

string

0..1

Identifier of the SCS/AS.

externalId

ExternalId

0..1

Identifies a user as defined in Clause 4.6.2 of 3GPP TS 23.682 [2].

(NOTE 2)

msisdn

Msisdn

0..1

Identifies the MS internal PSTN/ISDN number allocated for a UE.

(NOTE 2)

ecrDataWbs

array(PlmnEcRestrictionDataWb)

0..N

Identifies whether enhanced coverage mode are restricted or not. This attribute shall not be present for the query custom operation.

ECR_WB_5G

restrictedPlmnIds

array(PlmnId)

0..N

Indicates a complete list (and possibly empty) of serving PLMNs where Enhanced Coverage shall be restricted. This attribute shall not be present for the query custom operation. (NOTE 3)

allowedPlmnIds

array(PlmnId)

0..N

Indicates a complete list (and possibly empty) of serving PLMNs where Enhanced Coverage shall be allowed. This attribute shall not be present for the query custom operation. (NOTE 3)

NOTE 1: Properties marked with a feature as defined in clause 5.4.4 are applicable as described in clause 5.2.7. If no feature are indicated, the related property applies for all the features.

NOTE 2: One of the properties "externalId" or "msisdn" shall be included.

NOTE 3: "restrictedPlmnIds" and "allowedPlmnIds" shall be mutually exclusive.

NOTE 4: The SCEF should check received MTC provider identifier and then the SCEF may:
– override it with local configured value and send it to HSS;
– send it directly to the HSS; or
– reject the Enhanced Coverage Restriction control request

5.12.2.1.3 Type: ECRData

This data type represents the current visited PLMN (if any) and the current settings of enhanced coverage restriction. The structure is used only for response.

Table 5.12.2.1.3-1: Definition of type ECRData

Attribute name

Data type

Cardinality

Description

Applicability (NOTE 1)

supportedFeatures

SupportedFeatures

1

Used to negotiate the supported optional features of the API as described in clause 5.2.7.

visitedPlmnId

PlmnId

0..1

Indicates the current visited PLMN.

ecrDataWbs

array(PlmnEcRestrictionDataWb)

0..N

Identifies whether enhanced coverage mode are restricted or not.

ECR_WB_5G

restrictedPlmnIds

array(PlmnId)

0..N

Indicates a complete list (and possibly empty) of serving PLMNs where Enhanced Coverage shall be restricted.

(NOTE 2)

allowedPlmnIds

array(PlmnId)

0..N

Indicates a complete list (and possibly empty) of serving PLMNs where Enhanced Coverage shall be allowed.

(NOTE 2)

NOTE 1: Properties marked with a feature as defined in clause 5.4.4 are applicable as described in clause 5.2.7. If no feature are indicated, the related property applies for all the features.

NOTE 2: "restrictedPlmnIds" and "allowedPlmnIds" shall be mutually exclusive.

5.12.2.1.4 Type: PlmnEcRestrictionDataWb

Table 5.12.2.1.4-1: Definition of type PlmnEcRestrictionDataWb

Attribute name

Data type

Cardinality

Description

Applicability

plmnId

PlmnId

1

Indicates the PLMN where enhanced coverage mode shall be restricted or not.

plmnEcrDataWb

EcRestrictionDataWb

0..1

Identifies whether enhanced coverage mode are restricted or not.

5.12.3 Custom Operations without associated resources

5.12.3.1 Overview

Custom operations used for this API are summarized in table 5.12.3.1-1. "apiRoot" is set as described in clause 5.2.4.

Table 5.12.3.1-1: Custom operations without associated resources

Operation name

Custom operation URI

Mapped HTTP method

Description

query

/query

POST

Query the status of enhanced converage restriction for a UE

configure

/configure

POST

Configure the enhanced converage restriction for a UE

5.12.3.2 Operation: query

5.12.3.2.1 Description

This custom operation allows an SCS/AS to query the current status of enhanced converage restriction for a UE via the T8 interface as defined in 3GPP TS 23.682 [2].

5.12.3.2.2 Operation Definition

This operation shall support the URI query parameters, request and response data structures, and response codes, as specified in the table 5.12.3.2.2-1 and table 5.12.3.2.2-2.

Table 5.12.3.2.2-1: URI query parameters supported by the POST on this operation

Name

Data type

Cardinality

Remarks

none specified

Table 5.12.3.2.2-2: Data structures supported by the POST request/response on this operation

Request body

Data type

Cardinality

Remarks

ECRControl

1

Parameters to query the current status of Enhanced Coverage Restriction.

Response body

Data type

Cardinality

Response

codes

Remarks

ECRData

1

200 OK

The requested information was returned successfully.

none

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF.

Redirection handling is described in clause 5.2.10.

none

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF.

Redirection handling is described in clause 5.2.10.

ProblemDetails

0..1

403 Forbidden

(NOTE 2)

NOTE 1: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 also apply.

NOTE 2: Failure cases are described in clause 5.12.5.3.

Table 5.12.3.2.2-3: Headers supported by the 307 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located in an alternative SCEF.

Table 5.12.3.2.2-4: Headers supported by the 308 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located in an alternative SCEF.

5.12.3.3 Operation: configure

5.12.3.3.1 Description

This custom operation allows an SCS/AS to configure the current setting of enhanced converage restriction for a UE via the T8 interface as defined in 3GPP TS 23.682 [2].

5.12.3.3.2 Operation Definition

This operation shall support the request data structures specified in table 5.12.3.3.2-1 and the response data structure and response codes specified in table 5.12.3.3.2-2.

Table 5.12.3.3.2-1: URI query parameters supported by the POST on this operation

Name

Data type

Cardinality

Remarks

none specified

Table 5.12.3.3.2-2: Data structures supported by the POST request/response on this operation

Request body

Data type

Cardinality

Remarks

ECRControl

1

Parameters to configure the setting of Enhanced Coverage Restriction.

Response body

Data type

Cardinality

Response

codes

Remarks

ECRData

1

200 OK

The Enhanced Coverage Restriction setting was configured successfully

none

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF.

Redirection handling is described in clause 5.2.10.

none

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF.

Redirection handling is described in clause 5.2.10.

ProblemDetails

0..1

403 Forbidden

(NOTE 2)

NOTE 1: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 also apply.

NOTE 2: Failure cases are described in clause 5.12.5.3.

Table 5.12.3.3.2-3: Headers supported by the 307 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located in an alternative SCEF.

Table 5.12.3.3.2-4: Headers supported by the 308 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI of the resource located in an alternative SCEF.

5.12.4 Used Features

The table below defines the features applicable to the ECRControl API. Those features are negotiated as described in clause 5.2.7.

Table 5.12.4-1: Features used by ECRControl API

Feature Number

Feature

Description

1

ECR_WB_5G

The enhanced coverage restriction control information indicates whether the enhanced coverage modes are restricted or not for the WB UE. The feature is not applicable to the pre-5G.

Feature: A short name that can be used to refer to the bit and to the feature, e.g. "Notification".

Description: A clear textual description of the feature.

5.12.5 Error handling

5.12.5.1 General

HTTP error handling shall be supported as specified in clause 5.2.6.

In addition, the requirements in the following clauses shall apply.

5.12.5.2 Protocol Errors

In this release of the specification, there are no additional protocol errors applicable for the ECRControl API.

5.12.5.3 Application Errors

The application errors defined for the ECRControl API are listed in table 5.12.5.3-1.

Table 5.12.5.3-1: Application errors

Application Error

HTTP status code

Description

QUOTA_EXCEEDED

403 Forbidden

Not enough quota for SCS/AS.