POMBA Context Builders and Data Sources

Owned by Sharon Chisholm
Last updated: Feb 04, 2019
3 min read

A Context Builder is a Microservice that supports the POMBA Context Builder 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

Note the Data Dictionary (see Integration with Data Dictionary)  is not a context builder as it integrates directly with the validation service, but conceptually is similar



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

Parameter

Mandatory?

Description

ServiceInstanceId

Y

Instance id of the service being audited

ModelVersionId

N (except SDC)

Model UUID as published in service model metadata

ModelInvariantId

N (except SDC)

SDC generated invariant id as published in   service model metadata



Header Name

Mandatory?

Description

Header Name

Mandatory?

Description

X-ONAP-RequestID

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. See also POMBA Casablanca Model





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

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

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

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

  3. Must be able to report errors at the following levels

    1. Service instance

    2. Service component

    3. Attribute

See also LOG-392: POMBA: Improved Error HandlingClosed



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.

  • error text

    • String providing additional detail, if available