Exploring the data model
The data model demonstrates the relationships between the data objects used by the Intelligence Suite. The data that you load is used to populate the Control Tower dashboards and details pages. The Intelligence Suite data model contains the following top-level objects and their records. Each data object contains fields that fall under the following categories:
The data model is divided into two data warehouses: a data warehouse and an event warehouse. While there are data cross references across both warehouses, they are kept physically separated because objects and events have vastly different lifecycles, operations and query patterns. Thus there are two basic types of data represented in the data model: business objects and business events. There is also a metadata model, which includes types that act on or decorate the main data model. All processing of data inbound and outbound is predicated on operating on these three types.
- Business Objects - Business objects model data that is exchanged between businesses, systems, networks, applications and people. There are many types of business objects based on the context, and most of which are supply chain related. But the system is designed to model any kind of business object, supply chain related or not.
- Business Object Events- Business object events signify when something happens to a business object (create, update, delete, for instance). Almost every reason a business object is created or updated is due to a business object event, and so business object events form a way to track the history of what has happened to a business object and why. Unlike business objects, business object events can't be modified or deleted once created; they represent an indelible history for the effected business object.
- Business Rules - One of the suite's many strengths is its ability to pre-process data as it is being ingested, to make queries later against the outcomes of that processing much faster. A business rule is a combination of matching criteria and resulting action, which is applied to data on the way in. If the business rule's criteria matches a new business object or event upsert (update or insert), then the resulting action is played. That action could be the creation of another business object event, an upsert of another business object, or adding addition derived data to the business object affected.
The most basic building block data type in the data model is the Business Object. In most cases, business objects model business data exchanged between systems as part of a business transaction, but a business object could be used to model any business data. All business objects implement two interface definitions: BusinessObject and CursoredObject.
- BusinessObject - This interface models the metadata that all business objects must have, such as a unique identifier and timestamps for when the business object was created and last updated.
- CursoredObject - A cursor is a unique ID that points to a business object. Cursors are useful in listing or paginated queries to specify "after" which object the next page of objects should contain, for example. More information on GraphQL cursors can be found here.
Diagram 1: The business object data model
-
Download the data dictionary and review the types of business objects you can model out of the box. Understand each objects attributes in detail and the relationships between different objects.
-
Download a set of sample CSV files that you can review to help get more familiar with how to structure your data for import. Use the samples as a starting point for you initial imports.
-
Navigate through the live API and its data model explorer.
Business Object Events signify an action was taken on a business object and contains details of what that event did and the time that it happened.
The Business Object Event model type points to a Business Object Event Details type, which details the source of the event (such as from an EDI transaction document). The Business Object Event Details also points to the Business Object type, which includes what in the Business Object was actually changed.
Optionally, the Business Object Event Details could also point to a Business Rule type, when if present (not null) signifies the event originated from the firing of a business rule, and what rule that was.
NOTE: The business object data model can also be extended to support custom attributes specific to your organization's needs.
Business Rule Events are created by a Business Rule acting on ingested data. If a Business Rule matches to data being ingested in the suite, the action of the rule is executed, normally resulting in a new Business Event being created, and the Business Rule Event signifies that this happened.
A Business Rule Event points to a Business Rule Event Details type, which explain why the rule fired and what were the results, in terms of the dimensions of the business object it matched with and any resulting output values generated by the rule. The Business Rule Event Details also points to the actual Business Rule that matched the data.
Note that the details do not point to the Business Object acted upon. To find the resulting updated Business Object requires querying for Business Events using the ID of the rule in the Business Rule Event.
If an error occurs either ingesting or processing data, an Error Event is created with the details. Thus there are two types of Error Events: Ingestion and Processing. Users should query for Error Events regularly to determine if any errors exist processing their data.
An Error Event points to Error Event Details, which is actually an interface that is implemented by either Ingestion Error Event Details or Processing Error Event Details, depending on the nature of the error event. If the error is related to the ingestion of data, such as a data model violation, then the Ingestion Error Event Details points to the Business Event signifying the event and associated data where the error occurred. If the error is related to processing of data, then the resulting Processing Error Event Details points to the Business Event and optionally the Business Rule (if a rule was involved) that caused the error.
-
Recommended: Loading data by using CSV files
It is recommended that you use a flat file simple canonical CSV format for your data loads, so that your data is easy to build, consume, and initially load. CSV files are the recommended method because they can be used to efficiently set up demo data, daily data integration, and automated data loads for production data.
-
Loading data by using JSON files
As an alternative to using CSV files, you can load your data by using JSON files.
-
Extending the data model and creating custom attributes
The business object data model can also be extended to support custom attributes specific to your organization's needs.
-
Extending the business logic with custom data processing rules
Sample rules are provided as starting points. You can extend and customize the samples or create new data processing rules to pinpoint and address custom business needs.
-
Inspecting the graphql schema Tutorial
A step by step tutorial that will show you how to inspect the schema both through the UI and through APIs.