API custom format

The Opinum API allows for custom data push. The mechanism consists in a standard API POST using a dedicated GUID identifier linked to a custom data mapper to a pre-defined Data Hub data source type. The following sections present the steps to use this custom data push.

Dedicated data push GUID

Upon request, Opinum will provide a dedicated GUID for a single data format.

The POST will take the form :

Parameter Value
URL https://push.opinum.com/api/generic/*dedicated_guid*/
Header Authorization = datahub_token
Content-Type = "application/json" or "application/xml" or "text/plain"
Body Custom data format consistent with specified Content-Type

Data mapping definition

The Opinum ETL process will map your custom data file to the OpisenseStandardDataFile.csv and integrate your data in Data Hub database. The Opinum ETL process consists of identifying these elements in the sent data content:

  • source based on either
    • SourceId, the technical identifier set by Data Hub upon the creation of the source,
    • SerialNumber, a user specified field set by the user in the source properties, or by any potential automated source creation process in Opinum (e.g. a master data synchronization).
    • MeterNumber, a user specified field set by the user in the source properties,
    • EanNumber, a user specified field set by the user in the source properties;
  • variable based on the MappingConfig parameter;
  • timestamp
  • value
Note

Unit of the value and time zone of the timestamp will be assumed to match with the definition of the source and the variable in Data Hub.

Data mapper

Once defined, Opinum data mapping is generated in a file allowing converting the original data format to the Data Hub standard data structure.

Data trigger

Using the above generated data mapper file, a trigger needs to be created on the Data Hub data storage. This trigger is similar to those created to process data files uploaded on the Data Hub FTP except for the fact that the dedicated GUID generated in Step 1 must be specified as the trigger token .

Source creation

Except for very specific cases where dedicated mechanisms were implemented in Opinum to identify and create new data sources from the data feeds, Data Hub data sources and variables must pre-exist in Opinum to store received data. Unless such dedicated mechanisms were prepared by the Data Hub team for the custom data pushed over the API, it is required that sources and variables should be created, along with a setting of the fields used in the data mapping process, either

  • manually through the Data Hub interface,
  • using the Data Hub API for data sources and variables creation or
  • a custom master data synchronization configuration.

Sample R custom XML data push

datahubToken <- getoAuthToken(user, password)
xml <- readChar(paste0(path0,fileName), file.info(paste0(path0,fileName))$size) 
result<-POST('https://push.opinum.com/api/generic/dedicated_guid',
               add_headers(	"Accept" = "application/xml",
"Authorization" = datahubToken, 
"Api-Version" = "1.0", 
"Content-Type" = "application/xml"),
               body = xml)

Alternatively, you can use the JSON format.

Tip

Learn more about the standard format