Involves

Understanding the relationships between an event and the various entities that participate in it is fundamental to creating a rich, analytical data layer. In Context Suite, these relationships are captured through a combination of explicit and implicit structures, which together build a comprehensive graph for each event.

The involves Structure (Explicit Involvement)

The most direct way to define which entities participated in an event is through the involves array. This structure allows you to explicitly list every person, organization, product, or object that had a role in the event's story.

Treating entity references as first-class citizens in the involves array, rather than just burying IDs in a properties blob, is a core principle. An ID field like inventory_item_id: "54319739470149" is an indicator that a full Involved object should be used instead.

Role vs. Entity Type

A common point of confusion is the difference between an entity's role and its entity_type.

• Entity Type: Describes what the entity is (e.g., "Person", "Product", "Organization").
• Role: Describes how the entity participated in this specific event (e.g., "Driver", "Witness", "Buyer").

The role is rarely a simple repeat of the entity_type. For example, in a car crash event, you might have multiple entities of type "Person", but each with a different role: "Driver", "Pedestrian", "Witness".

involves Properties

Implicit & Enriched Involvement

Beyond the explicit involves array, entities can be linked to an event implicitly through other structures. The entity_linking and contextual_awareness arrays are powerful server-side enrichments that automatically build out the event's graph.

entity_linking

This structure is automatically populated by our servers using Named Entity Recognition (NER) on any text provided in the content object of an event. It identifies mentions of known entities and links them to their formal graph representation.

contextual_awareness

After an entity is identified via entity_linking or other means, the server can enrich the event further by looking up relevant external facts about that entity. This provides valuable context that was not present in the original event but is crucial for deeper analysis.

Other Implicit Structures

Entities are also involved implicitly through other dedicated structures, most notably the products array within a commerce event. Each object in this list represents a product's involvement in a commercial transaction, with its own rich set of properties.

Example: From Simple Event to Enriched Graph

Let's see how a simple user-provided event is transformed into a rich, interconnected graph object on the server.

1. User-Provided Jitsu Event

A user sends a simple feedback event. They only need to provide the content.

1jitsu.track("User Feedback Received", {
2    content: {
3        "subject": "My Trip",
4        "body": "I just got back from Paris and the weather near the Eiffel Tower was amazing!"
5    },
6    userId: "user-789"
7});

2. Enriched JSON Event (Server-Side)

After processing, the final JSON stored in Context Suite is significantly enriched. The server has performed NER to populate entity_linking and then looked up external facts to populate contextual_awareness.

1{
2  "type": "track",
3  "event": "User Feedback Received",
4  "userId": "user-789",
5  "content": {
6    "subject": "My Trip",
7    "body": "I just got back from Paris and the weather near the Eiffel Tower was amazing!"
8  },
9  "entity_linking": [
10    {
11      "content_key": "body",
12      "label": "Paris",
13      "starts_at": 22,
14      "ends_at": 27,
15      "entity_type": "City",
16      "entity_gid": "a1b2c3d4-e5f6-...",
17      "entity_wid": "Q90",
18      "certainty": 0.98
19    },
20    {
21      "content_key": "body",
22      "label": "Eiffel Tower",
23      "starts_at": 50,
24      "ends_at": 62,
25      "entity_type": "Landmark",
26      "entity_gid": "f1e2d3c4-b5a6-...",
27      "entity_wid": "Q243",
28      "certainty": 0.99
29    }
30  ],
31  "contextual_awareness": [
32    {
33      "type": "Description",
34      "entity_type": "City",
35      "entity_gid": "a1b2c3d4-e5f6-...",
36      "entity_wid": "Q90",
37      "context": "Paris is the capital and most populous city of France."
38    },
39    {
40      "type": "Fact",
41      "entity_type": "Landmark",
42      "entity_gid": "f1e2d3c4-b5a6-...",
43      "entity_wid": "Q243",
44      "context": "The Eiffel Tower was the main exhibition of the 1889 World's Fair."
45    }
46  ],
47  "involves": [
48    {
49      "role": "Source",
50      "entity_type": "User",
51      "id": "user-789",
52      "id_type": "InternalDB"
53    }
54  ]
55}