CPS-2155 Java API: The Data Structure for DataJob Request

References

CPS-2155 - Getting issue details... STATUS

Assumptions

#	Assumption	Notes
1

Issues & Decisions

	Issue	Notes	Decision
1	`dataaccepttype` Do we need to consider this parameter in our NCMP internal Java interface?	The controller should accept/reject `dataaccepttype. From the client application`	The Controller will validate and set the Default as necessary 14 Mar 2024 kieran mccarthy Sourabh Sourabh Kolawole Adebisi-Adeolokun Toine Siebelink
2	`datacontenttype` Do we need to consider this parameter in our NCMP internal Java interface?	NCMP should maintain the content type as received and not modify datacontenttype.	NCMP should maintain what content type as received and not modify 14 Mar 2024 kieran mccarthy Sourabh Sourabh Kolawole Adebisi-Adeolokun Toine Siebelink
3	`attributes` This has plural but all examples contain a single String, why?	kieran mccarthy & Rafael to come back with a 'definition' and 'example	Kolawole Adebisi-Adeolokun to follow up with stakeholders on decision by 19/03/2024
4	The study mentions '`fields` and `attributes`". None of the examples use '`fields`'. We can see only '`value'` Objects (in the write use cases)	kieran mccarthy & Rafael to come back with a 'definition' and 'example	Read and Write data jobs are 2 deff. objects. 14 Mar 2024 Kolawole Adebisi-Adeolokun to follow up with stakeholders on decision by 19/03/2024
5	Combine all java api parameters into 1 parameter object?	There is a limit (sonar quality check) of 7 parameter max for a method	13 Mar 2024 Team follow common practice and have a few parameters ie. dataJobId is NOT part of the client request but generated in DCM so it seems logical to keep this separates

Data Structures

Proposed Method signature

processDataJob

void processReadDataJob(String dataAcceptType,  String dataContentType, String dataJobId, List<ReadOperation> readOperations)
void processWriteDataJob(String dataAcceptType,  String dataContentType, String dataJobId, List<WriteOperation> writeOperations, Map<String,String> metadata)

Notes

The order of Operations is important and needs to be maintained hence the use of 'List'
The output is 'void' for the scope in this user story, it will be defined later
dataaccepttype and datacontenttype might be needed too, see issue #1 and #2. If required we could combine them to reduce the number of parameter in an object like RestProtocolParameters

Datajob 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
data	List of operations to be executed.	request body	List of 3gppReadOperation	Y

3gppReadOperation

Name	Description	Type	Mandatory
path	It is a unique identifier of a managed object (MO) on a network element. Defines the resource on which operation is executed. Typically could be Fully Distinguished Name (FDN).	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.	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

Datajob write 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
data	List of operations to be executed.	request body	List of 3gppPatchOperation	Y

3gppPatchOperation

Name	Description	Type	Mandatory
path	It is a unique identifier of a managed object (MO) on a network element. Defines the resource on which operation is executed. Typically could be Fully Distinguished Name (FDN).	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 "replace": replaces the value of an attribute specified in the path (attribute is separated with a # from the MO path) with the object in the value "remove": removes the MO given in the path, value is not applicable "action": executes an MO action in the path (action is separated with a # from the MO path) with the input parameters 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

Resource

Name

Description

Type

Mandatory

id

Identifier of the resource object

String

N

attributes

Attributes object whose members are the class attributes and values. The object contains key/value map where:

key is the attribute name
value is the attribute value

Object

N

ActionParameters

Name	Description	Type	Mandatory
input	The input of the action. Key value pairs.	Object	N

Response

Name	Description	Type	Mandatory
jobId	The id of the data job	string	Y
status	The status of the jobid	enum: [ NOT_STARTED, RUNNING, FINSHED, FAILED, PARTIALLY_FAILED, CANCELLING, CANCELLED ]	Y
statusuri	Status uri for the jobid. Example: {apiRoot}/ranoam/cm/v1/dataJob/{jobId}	uri	Y
resultsuri	Result uri for the jobid. Example: {apiRoot}/s3-bucket/{bucketId}	uri	Y

Data SubJob create (NCMP → DMI)

This is a mirror of the Datajob read/write request with the added details needed for the DMI plugins. Below you can see the changes for the READ but the same changes are applicable for the WRITE too.

Method: POST

Path: /dmi/v1/dataJob/{requestId}

DMI Data SubJob 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
requestId	Identifier for the overall Datajob	Path	String	Y
data	List of operations to be executed.	request body	List of DMI3gppReadOperation	Y

DMI3gppReadOperation

Name	Description	Type	Mandatory
path	It is a unique identifier of a managed object (MO) on a network element. Defines the resource on which operation is executed. Typically could be Fully Distinguished Name (FDN).	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	Y
privateProperties	CMHandle private properties for the alternateID in the path.	Map	Y

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

Data subjob status check (NCMP → DMI)

Request:

Method: GET

Path: /dmi/v1/dataJob/{requestId}/dataProducerJob/{dataProducerJobId}/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

Response:

Status code: 200 - OK

Name	Description	Location	Type	Mandatory
status	enum that represents the status of the subjob. Possible values:	response body	enum: [ NOT_STARTED, RUNNING, FINSHED, FAILED, PARTIALLY_FAILED, CANCELLING, CANCELLED ]	Y

Data subjob retrieve result (NCMP → DMI)

Request:

Method: GET

Path: /dmi/v1/dataJob/{requestId}/dataProducerJob/{dataProducerJobId}/result

Parameters:

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
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

Response:

WRITE

Status Code: 200 - Ok

Data part of the message

READ