A Context Builder is a Microservice that supports that POMBA Context Buidler API and provides access to data from a particular ONAP data source or from a particular type of data (network/primary source, for example), outside of ONAP. Context builders are standalone pieces of software that expose the context builder API. Flavours of Context Builders
- Data Model
- Data Instance
This page captures requirements for POMBA context builders to follow so they can plug into the POMBA framework and enable audit reports from new data sources.
API
All context builders must support a REST API with the following features. If the request is not well-formed or is missing mandatory parameters, the request shall return an error, as appropriate.
For a more formal definition of this API, see the POMBA Context Builder Swagger
Versioning
The API shall be compliant to the ONAP API versioning strategy
Note that a url path without a version number shall always run the latest version of the API.
Request
GET http://<host>:<port>/<server.contextPath>/service/context?<parameters>
| Parameter | Mandatory? | Description |
|---|---|---|
| ServiceInstanceId | Y | Instance id of the service being audited |
| ModelVersionId | N | Model UUID as published in service model metadata |
| ModelInvariantId | N | SDC generated invariant id as published in service model metadata |
| Header Name | Mandatory? | Description |
|---|---|---|
| X-TransactionId | N | Unique transaction ID. If it is not sent it will be automatically generated by on a request receipt. |
| X-FromAppId | Y | For auditing purpose each component calling API should identify itself by sending its identity. If this header with non-null value is not supplied the HTTP Request will be rejected with '400 Bad Syntax’ response code. |
| Accept | N | Determines the format of the body of the response. Valid values are : “application/json” |
Response
JSON compliant to the following data model. This Data Model shall migrate to the ONAP Common Model, when ready. The versioning strategy will help facilitate this migration.
POMBA Common Model in Java
auditcommon.zip
Mapping between component data and common model
Context Builders Mapping to Common Model
Error Handling
Query Parameter Handling
Note that in the formal definition of the Context Builder API, all parameters are optional, but specific Context Builders will define each of those parameters as either mandatory, optional or not supported as appropriate. The following table defines the expected behaviour across all context builders.
| Condition | Handling |
|---|---|
| All mandatory parameters are present with no optional parmater | Proceed with processing |
| Missing mandatory parameters | Return an error |
| All mandatory present with some or all optional parametesrq | Proceed with processing |
| All mandatory present with some unsupported parameters | Either Ignore or reject. Need to agree and clarify here. |
High-level Requirements
The following are requirements against the error reporting solution
- Must be possible to return a mixture of results and errors to handle the case, for example, where for a given service, some service components provided information while others did not.
- Must be able to differentiate between information missing because the context builder does not support it and information missing because the information was not there as expected
- Must be able to report errors at the following levels
- Service instance
- Service component
- Attribute
See also LOG-392 - Getting issue details... STATUS
Note the Context Builders are not aware of what additional information could be provided that don't know how to provide. The key to the error handing is to never fail silently, so the consumer of information can interpret missing information as only missing, and not an error.
Data Quality Indicator
Each resource and attribute shall contain a data quality indicator to indicate the validity of each piece of data
- status
- ok
- data successfully retrieved and well-formed
- error
- any other conditions. Note does not include data that was not intended to be made available. These would just not exist.
- ok
- error text
- String providing additional detail, if available