Skip to main content

Getting started

DataMart purpose​

DataMart is storing data fetched from Visma Net database. It stores a copy of the data which is kept fresh with a series of ETL (Extract, Transform, Load) processes.

  • Data cannot be changed through DataMart API
  • DataMart primarily usage is for reporting and Business Intelligence solutions
  • DataMart is meant to be used as an intermediate storage from where data can be extracted fast and stored on a consumer database for further processing

Activating an ETL​

Before data can be fetched from DataMart, for each entity you want to consume the ETL must be enabled. This operation is done only once.

mutation {
  activateEtl(input: { etlName: ETL_NAME }) {
    etlStatus {
      importDone
      active
    }
  }
}
  • ETL_NAME can be any of the ETLs available. Navigate the schema to find out what are the currently available ones
  • etlStatus specifies what response fields from DataMart you require. importDone is important for the activation. As long as the importDone is false in the response the ETL is still importing data from Visma Net to DataMart DB. Only when importDone becomes true data should be fetched from DataMart API.

This method/mutation can be called any number of times, with no effect after the first call, but it will return the current state of the ETL.

Anatomy of a query in DataMart GraphQL API​

Query:​

entities(lastId, updatedInDataMart, pageSize)

  • lastId - (optional) used for pagination (see: Pagination). It instructs DataMart to return only documents with a strictly higher ID that the one provided
  • updatedInDataMart - (optional) used to fetch changes (see: Fetching Updated Data) . The maximum value of the documents fetched should be persisted on the consumer side to remember when this data was last fetched.
  • pageSize - (optional) used to limit the result size. There is a maximum limit enforced by the API

Response:​

 {
    id
    updatedInDataMartDateTime
    ... other fields ...
  }
  • id - internal id used by DataMart. Used for pagination
  • updatedInDataMartDateTime - internal DateTime generated by DataMart. Used for fetching updated data

Fetching Updated Data​

Always use the updatedInDataMart query parameter when fetching data. Store the most recent date received in the updatedInDataMartDateTime field and use it for subsequent fetches. The updatedInDataMart query parameter is not required for the initial data import. This will ensure you always receive the most up-to-date data, regardless of the reason for the update in DataMart.

Pagination​

Use the lastId attribute in your query exclusively for pagination purposes. The initial call should not include the lastId attribute. With each subsequent request, send the last id value received in the response to retrieve the next set of data.

Do not use the id field to identify entities. In rare instances, this id may change, resulting in duplicate data. The id field will always be ascending, which makes it suitable for pagination.

Identifying Entities​

Always use the natural key of the entity you are syncing to uniquely identify the correct record. Do not rely on the internal id field from DataMart for entity identification. The internal id should only be used for pagination.