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.

For various reasons an ETL might appear in the documentation but not be yet enabled. When activation is called for these ETLs an error message is returned: The ETL_NAME ETL is disabled..

Deactivating an ETL​

It is good practice to deactivate an ETL once the data is not used anymore by your application. This will decrease the load on DataMart as a whole and can potentially improve the overall freshness of data.

mutation {
  deactivateEtl(input: { etlName: ETL_NAME }) {
    etlStatus {
      importDone
      active
    }
  }
}

DataMart remembers all the activations from all the clients. As long as there is a client that has NOT deactivated an ETL for a company the 'active' attribute will be true. Only if all the clients, that activated the ETL, deactivate the ETL for a company the active attribute will be false.

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.

Deletion support​

Within the Enterprise Resource Planning (ERP) system, the deletion of data is a process that can be tracked for specific entities, referred to as Objects within the GraphQL schema. Support for tracking data deletion varies across these entities. Documentation for each Object explicitly indicates whether deletion tracking is currently supported. It's important to note that certain entities within the ERP system do not permit data deletion.

Consequently, this limitation influences the structure of GraphQL queries. Some queries incorporate filters to accommodate the tracking of deleted data, while others, corresponding to entities where deletion tracking is not supported, do not include such filters.