WIP: CPS-896: CMHandle Registration Response structure

CPS-896: CM Handle Registration Process only partially completes when exception is thrownClosed

NCMP CMhandle registration endpoint receives multiple operations to create, update or delete cm-handles in a single request. As there are multiple operations, the endpoint response structure should be able to provide the status of all operations separately with consistent error-code to allow users to retrigger failed operations programmatically if possible.

Questions:

	Question	Agreed Solution	Remarks

	Question	Agreed Solution	Remarks
1	1	Are multiple operations for one cm-handle is considered invalid input?	No special validation, process as usual	2nd create will fail 2nd update will override previous 2nd delete will be ignored
2	2	Should system check which dmi-plugin 'owns' cm handle before deleting it? ie. is is the same service that registered the cm-handle	Just delete for now until Acces Control gets implemented	Agreed with stakeholder in meeting Mar 9, 2022
3	3	Preferred output format	Alternative B: only failed cm handles, no status code for each handle. Stakeholder expected that errors are rare and does not want to process data if successful ie. in most cases and empty response is expected (statuscode 200 code)	empty arrays will not appear in json at all. I.e. if there are no 'failed delete cm handles' the 'failedDeletedCmHandles' property will simply not appear in the response.
4	4	Order of processing	Change to: delete → create → update	It will help us to handle the case where the user wants to recreate the cm handle

Response Structure

HttpStatus

Scenario	Status Code	ResponseBody

Scenario	Status Code	ResponseBody
All operations were successful	200	Empty
All or few operations failed	500	With error details from each failed operation
Invalid Input	400	Error Details

Response Body

The response body should give enough information for each failed operation to retry them programmatically. For each failed operation we should send the below information

Name	Description	Mandatory?

Name	Description	Mandatory?
cmHandle	identifies the failed cm-handle	Mandatory
errorCode	Identify the error	Mandatory
errorText	Human-readable error text	Mandatory
status	Failure/Success; To be discussed with the team	Mandatory

The response body can be structured in two ways

Alternative A: Group by operation type, with status fields

The interface is generic and if we need to send the status of all operations in the future it can be achieved without any breaking change.

Response Structure incl status

{
    "createdCmHandles": [ 
		{
 			"cmHandle": "cmHandle-1",
    		"status": "FAILURE", // Extra field to indicate the status
    		"error-code": "01",
			"error-text" : "cmhandle already exist"
		}
	],
	"updatedCmHandles": [ 
		{
 			"cmHandle": "cmHandle-2",
    		"status": "FAILURE" ,
    		"error-code": "02" ,
			"error-text" : "cmhandle does not exist" 
		}
	],
	"deletedCmHandles": [ 
		{
 			"cmHandle": "cmHandle-3",
    		"status": "FAILURE" ,
    		"error-code": "02" ,
			"error-text" : "cmhandle does not exist"
		}
	]
}

Alternative B: Group by operation type but only for failed operations

This approach meets the current requirement and has a smaller payload size (no extra field for the status).

Response (only failed)

{
    "failedCreatedCmHandles": [ 
		{
 			"cmHandle": "cmHandle-1",
    		"error-code": "01",
			"error-text" : "cmhandle already exist"
		}
	],
	"failedUpdatedCmHandles": [ 
		{
 			"cmHandle": "cmHandle-2",
    		"error-code": "02" ,
			"error-text" : "cmhandle does not exist" 
		}
	],
 	"failedDeletedCmHandles": [ 
		{
 			"cmHandle": "cmHandle-3",
    		"error-code": "02" ,
			"error-text" : "cmhandle does not exist"
		}
	]
}

Error handling

The error can be due to client input and they should try not to

Input Issues

If the DMIService ( dmiModelPlugin or dmiService ) does not match with the DMIService of cm handle? update & delete scenario. We should not update these two field because it impacts modelSync, but dmiDataService can be updated
Multiple operations for a single cm-handle:
1. If not allowed: Throw the error; it enables us to process them parallelly for better performance.
2. If allowed:
  1. Which operation type has higher precedence
    1. create → update → delete:
    2. delete → create → update: It will help us to handle the case where the user wants to recreate the cm handle
  2. Multiple within the same operation type
    1. create → Take the last one and show success or take the first one and let others fail
    2. update → Process them sequentially because the update can be partial and order may matter here
    3. delete → Process only once
Input is not in the expected format: Reject the request

Create CMHandles

cm-handle already exist
multiple create operations for one cm-handle
unknown-error

Update CMHandles

cm-handle does not exist
DMIService name does not match with existing DMIService of cm handle
unknown-error

Remove CMHandles

cm-handle does not exist: No error
DMIService name does not match with existing DMIService of cm handle
unknown-error

Should we indicate if something can be fixed with retry?

Code	Slogan	Applicable to
Code	Slogan	Create	Update	Remove
00	unknown/other	Yes	Yes	Yes
01	cm-handle does not exist	No	Yes	No*
02	cm-handle already exist	Yes	No	No
03	not allowed**	?	Yes	Yes

Notes
^* remove will ignore non-existing cm handles (not an error, assume already deleted)
** suggested future error (for illustration purposes)