| Table of Contents |
|---|
Issues & Decisions
| # | Issue | Notes | Decision |
|---|---|---|---|
| 1 | Is the requestId in the southbound request equal to the dataJobId coming in from the northound interfaces? (see writeJob for example) |
Csaba Kocsis and Toine Siebelink agreed that requestId should be renamed to jobId on all interfaces |
NCMP → DMI
As part of the overall datajob solution there must be an interface for data flow between the NCMP-lib in DCM and the DMI Plugin.
...
- Define new REST interface :
- Method: POST
- Path: /dmi/v1/writeJobcmwriteJob/{requestId}
Only writeJob required for MVP. Read, Status, Result will be completed in a later iteration.
...
- New Interface DMI-I-02 with document and diagram updates. Both Wiki and RTD
- Define swagger for request/response (additional info for forwarding data job request : moduleSetTag, privateProperties, dataProducerId, requestId dataJobId)
- Agree and implement yaml for this interface
- Stakeholder acceptance of yaml
| Code Block | ||||
|---|---|---|---|---|
| ||||
| ||||
openapi: 3.0.3
info:
title: NCMP Data Subjob API
description: Support datajobs through one or more subjob for each DMI and Data Producer Identifier combination
version: 1.0.0
servers:
- url: /dmi
tags:
- description: DMI plugin rest apis
name: dmi-datajob
paths:
/v1/readJob/{requestId}:
post:
description: Create a read request
operationId: readDataJob
parameters:
- $ref: '#/components/parameters/requestIdInPath'
requestBody:
description: Operation body
content:
application/3gpp-json-patch+json:
schema:
$ref: '#/components/schemas/SubjobReadRequest'
tags:
- dmi-datajob
responses:
"200":
description: Response for subjob
content:
application/json:
schema:
type: object
properties:
dataProducerJobId:
type: string
description: The data job ID.
/v1/writeJob/{requestId}:
post:
description: Create a write request
operationId: writeDataJob
parameters:
- $ref: '#/components/parameters/requestIdInPath'
requestBody:
description: Operation body
content:
application/3gpp-json-patch+json:
schema:
$ref: '#/components/schemas/SubjobWriteRequest'
tags:
- dmi-datajob
responses:
"200":
description: Response for subjob
content:
application/json:
schema:
type: object
properties:
dataProducerJobId:
type: string
description: The data job ID.
components:
parameters:
requestIdInPath:
description: Identifier for the overall Datajob
in: path
name: requestId
required: true
schema:
example: some-identifier
type: string
schemas:
SubjobReadRequest:
type: object
required:
- dataProducerId
- data
properties:
dataAcceptType:
description: Defines the data response accept type
example: application/vnd.3gpp.object-tree-hierarchical+json
type: string
dataContentType:
description: Defines the data request content type
example: application/3gpp-json-patch+json
type: string
dataProducerId:
description: ID of the producer registered by DMI for the paths in the operations in this request
example: my-data-producer-identifier
type: string
data:
example:
op: read
operationId: 1
path: SubNetwork=Europe/SubNetwork=Ireland/MeContext=NR03gNodeBRadio00003/ManagedElement=NR03gNodeBRadio00003/GNBCUCPFunction=2
attributes: userLabel
scope:
scopeTyp: BASE_ONLY
type: array
items:
type: object
required:
- path
- op
properties:
path:
description: Defines the resource on which operation is executed
example: SubNetwork=Europe/SubNetwork=Ireland/MeContext=NR03gNodeBRadio00003/ManagedElement=NR03gNodeBRadio00003
type: string
op:
description: Describes the operation to execute
example: read
type: string
operationId:
description: Unique identifier for the operation within the request
example: 1
type: string
attributes:
description: This parameter specifies the attributes of the scoped resources that are returned
type: array
items:
example: cellId
type: string
fields:
description: This parameter specifies the attribute fields of the scoped resources that are returned
type: array
items:
type: string
filter:
description: This parameter is used to filter the scoped Managed Objects. Only Managed Objects passing the filter criteria will be fetched
example: NRCellDU/attributes/administrativeState==LOCKED
type: string
scopeType:
description: ScopeType selects MOs depending on relationships with Base Managed Object
example: BASE_ONLY
type: string
scopeLevel:
description: Only used when the scope type is BASE_NTH_LEVEL to specify amount of levels to search
example: 0
type: integer
moduleSetTag:
description: Module set identifier
example: my-module-set-tag
type: string
cmHandleProperties:
description: Private properties of the cm handle for the given path
$ref: '#/components/schemas/CmHandleProperties'
SubjobWriteRequest:
type: object
required:
- dataProducerId
- data
properties:
dataAcceptType:
description: Defines the data response accept type
example: application/vnd.3gpp.object-tree-hierarchical+json
type: string
dataContentType:
description: Defines the data request content type
example: application/3gpp-json-patch+json
type: string
dataProducerId:
description: ID of the producer registered by DMI for the paths in the operations in this request
example: my-data-producer-identifier
type: string
data:
example:
op: add
path: SubNetwork=Europe/SubNetwork=Ireland/MeContext=NR03gNodeBRadio00003/ManagedElement=NR03gNodeBRadio00003/GNBCUCPFunction=1/EUtraNetwork=1/EUtranFrequency=12
value:
id: 12
attributes:
userLabel: label12
type: array
items:
type: object
required:
- path
- op
properties:
path:
description: Defines the resource on which operation is executed
example: SubNetwork=Europe/SubNetwork=Ireland/MeContext=NR03gNodeBRadio00003/ManagedElement=NR03gNodeBRadio00003
type: string
op:
description: Describes the operation to execute
example: add
type: string
operationId:
description: Unique identifier for the operation within the request
example: 1
type: string
moduleSetTag:
description: Module set identifier
example: my-module-set-tag
type: string
cmHandleProperties:
description: Private properties of the cm handle for the given path
$ref: '#/components/schemas/CmHandleProperties'
value:
description: Value dependent on the op specified. Resource for an add. Object for a replace. ActionParameters for an action.
type: object
oneOf:
- $ref: '#/components/schemas/Resource'
- $ref: '#/components/schemas/ActionParameters'
- $ref: '#/components/schemas/Object'
CmHandleProperties:
description: Private properties of the cm handle for the given path
type: object
Resource:
type: object
properties:
id:
description: Identifier of the resource object
example: resource-identifier
type: string
attributes:
description: Key value map representing the objects class attributes and values
type: object
additionalProperties:
example: 'userLabel: label11'
type: string
ActionParameters:
description: The input of the action in the form of key value pairs
type: object
additionalProperties:
type: string
Object:
type: object
|
...
Method: POST
Path: /dmi/v1/dataJob/{requestId}cmreadJob
DMI Data SubJob read READ request
Name | Description | Location | Type | Mandatory |
|---|---|---|---|---|
destination | The destination of the results. ( e.g. S3 Bucket) | Query | string | N |
dataaccepttype | Define the data response accept type. Passible values: · application/vnd.3gpp.object-tree-hierarchical+json (default) · application/vnd.3gpp.object-tree-flat+json | request body | enum | N |
datacontenttype | Define the data request content type. Passible values: · application/3gpp-json-patch+json (default) | request body | enum | N |
dataProducerId | ID of the producer registered by DMI for the alernateIDs in the operations in this request. | request body | String | Y |
requestIddataJobId | Identifier for the overall Datajob | Pathrequest body | String | Y |
data | List of operations to be executed. | request body | List of DMI3gppReadOperation | Y |
...
Name | Description | Type | Mandatory |
|---|---|---|---|
| path | It is a unique identifier of a managed object (MO) on a network element. | String | Y |
| op | Describes the operation to execute. The value can be: "read" | String | Y |
| operationId | Unique identifier of the operation within the request | Integer | N |
| attributes | This parameter specifies the attributes of the scoped resources that are returned. | List of String | N |
| fields | This parameter specifies the attribute fields of the scoped resources that are returned. This should be used if an attribute is a struct and only a subset of its fields should be returned. | List of String | N |
| filter | The parameter is used to filter the scoped Managed Objects. Only Managed Objects passing the filter criteria will be fetched. | List of String | N |
| scopeType | ScopeType selects MOs depending on relationships with Base Managed Object. | enum[BASE_ONLY, BASE_ALL, BASE_NTH_LEVEL, BASE_SUBTREE] | N |
| scopeLevel | Only used when the scope type is BASE_NTH_LEVEL | Integer | N |
| moduleSetTag | Module set identifier | String | YN |
| privateProperties | CMHandle private properties for the alternateID in the path. | Map | YN |
Response
Status code: 200 - OK
Name | Description | Location | Type | Mandatory |
|---|---|---|---|---|
| dataProducerJobId | The ID of the created job by the data producer. | response body | String | Y |
| dmiPluginName | The target DMI that the job was performed on | response body | String | Y |
| subjobIddataProducerJobID | ID of the specific subjobjob created by the data producer | response body | String | Y |
DMI Data SubJob write requestWRITE request
Method: POST
Path: /dmi/v1/cmwriteJob
Name | Description | Location | Type | Mandatory |
|---|---|---|---|---|
destination | The destination of the results. ( e.g. S3 Bucket) | Query | string | N |
dataaccepttype | Define the data response accept type. Passible values: · application/vnd.3gpp.object-tree-hierarchical+json (default) · application/vnd.3gpp.object-tree-flat+json | request body | enum | N |
datacontenttype | Define the data request content type. Passible values: · application/3gpp-json-patch+json (default) | request body | enum | N |
dataProducerId | ID of the producer registered by DMI for the alernateIDs in the operations in this request. | request body | String | Y |
requestIddataJobId | Identifier for the overall Datajob | Pathrequest body | String | Y |
data | List of operations to be executed. | request body | List of DMI3gppWriteOperation | Y |
DMI3gppWriteOperation
Name | Description | Type | Mandatory |
|---|---|---|---|
| path | It is a unique identifier of a managed object (MO) on a network element. | String | Y |
| op | Describes the operation to execute. The value can be: "add": creates a new MO with the id and attributes given in the value | String | Y |
| operationId | Unique identifier of the operation within the request | Integer | N |
| value | NA if op == remove Resource if op == add Object if op == replace ActionParameters if op == action | Object | N |
| moduleSetTag | Module set identifier | String | YN |
| privateProperties | CMHandle private properties for the alternateID in the path. | Map | YN |
Response
Status code: 200 - OK
Name | Description | Location | Type | Mandatory |
|---|---|---|---|---|
| dataProducerJobId | The ID of the created job by the data producer. | response body | String | Y |
| dmiPluginName | The target DMI that the job was performed on | response body | String | Y |
| subjobIddataProducerJobId | ID of the specific subjobthe job created by the data producer | response body | String | Y |
Data subjob status check (NCMP → DMI)
...
Method: GET
Path: /dmi/v1/dataJobcmwriteJob/dataProducer/{requestIddataProducerd}/dataProducerJob/{dataProducerJobIddataProducerdJobId}/status
| Name | Description | Location | Type | Mandatory | |||||
|---|---|---|---|---|---|---|---|---|---|
dataProducerId | ID of the producer registered by DMI for the alernateIDs in the operations in this request. | Query | String | Y | requestId | Identifier for the overall Datajob | Path | String | Y |
dataProducerJobId | Identifier of the job created by the data producer. | Path | String | Y |
...
Request:
Method: GET
Path: /dmi/v1/cmwriteJob/dataJobdataProducer/{requestIddataProducerd}/dataProducerJob/{dataProducerJobIddataProducerdJobId}/result?destination={destination}
Parameters:
| Name | Description | Location | Type | Mandatory | |||||
|---|---|---|---|---|---|---|---|---|---|
dataProducerId | ID of the producer registered by DMI for the alernateIDs alternateIDs in the operations in this request. | Query | String | Y | requestId | Identifier for the overall Datajob | Path | String | Y |
dataProducerJobId | Identifier of the job created by the data producer. (not globally unique) | Path | String | Y | |||||
destination | The destination of the results: Kafka topic name or s3 bucket name. This shall be put into the Kafka message headers returned to NCMP | Query | String | Y |
...