---
title: "Events"
slug: "events"
abstract: "Overview of events with an example of how to add a goal and a search event to an interaction using the xConnect Client API."
---
# Events
An event is anything significant that occurs within the context of an interaction, such viewing a web page or making a purchase in a physical store.
Events ultimately inherit the `Sitecore.XConnect.Event` class and are represented by the `Events` collection on the `Interaction` class. Interactions must have at least one event. All events are triggered with an event model, an event definition ID, and a timestamp. The following example demonstrates how to add a `Goal` and a `SearchEvent` to an interaction using the xConnect Client API:
```csharp
using Sitecore.XConnect;
using Sitecore.XConnect.Collection.Model;
using System;
namespace Documentation
{
public class AddMultipleEvents
{
public async void ExampleAsync()
{
using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var newContact = new Sitecore.XConnect.Contact();
client.AddContact(newContact);
Guid channelId = Guid.Parse("dee6a101-a5d7-4111-9dd0-c3ac18d78295");
var interaction = new Sitecore.XConnect.Interaction(newContact, InteractionInitiator.Brand, channelId, "Mozilla/5.0 (Nintendo Switch; ShareApplet) AppleWebKit/601.6 (KHTML, like Gecko) NF/4.0.0.5.9 NintendoBrowser/5.1.0.13341");
// Search event has built-in definition GUID as there is
// only one search event
SearchEvent searchEvent = new SearchEvent(DateTime.UtcNow)
{
Keywords = "sitecore" // Event-specific property
};
// Goal instantiated with goal definition GUID as there are
// multiple goals
Guid goalId = Guid.Parse("2ee6a101-45d7-a111-9dd0-c3ac18d78295");
Goal goal = new Goal(goalId, DateTime.UtcNow);
interaction.Events.Add(searchEvent);
interaction.Events.Add(goal);
client.AddInteraction(interaction);
await client.SubmitAsync();
}
catch (XdbExecutionException ex)
{
// Handle exception
}
}
}
}
}
```
Refer to the following topics for information about how to use the xConnect Client API to work with events:
- [Adding events to an interaction](https://doc.sitecore.com/xp/en/developers/93/sitecore-experience-platform/add-interaction-events.html "Add interaction events")
- [Get interaction events](https://doc.sitecore.com/xp/en/developers/93/sitecore-experience-platform/get-interaction-events.html "Get interaction events")
- [Searching interactions by events](https://doc.sitecore.com/xp/en/developers/93/sitecore-experience-platform/search-interactions.html "Search interactions")
Event definitions
When an event is triggered, an event definition ID is passed into the constructor. Event definition ID come from items in Sitecore that give contextual meaning to an event in a reporting context. Event definitions are managed by marketers, who define properties such as the event name, description, and classification. The following table lists the types of events that are available and their location in the Sitecore tree:
| Definition | Event models used | Path |
| --- | --- | --- |
| Goals | `Goal` | /sitecore/system/Marketing Control Panel/Goals |
| Outcomes | `Outcome` | /sitecore/system/Marketing Control Panel/Outcomes |
| Generic events | `Event``PageViewEvent` (system) `MVTestTriggered` (system) `PersonalizationEvent` (system) | /sitecore/system/Marketing Control Panel/Events |
| Page events | `Event` `DownloadEvent` `SearchEvent` `CampaignEvent` | /sitecore/system/Settings/Analytics/Page Events |
> [!important]
> It is your responsibility to make sure that the correct event definition ID is used with the correct model. Although you can use the `Goal` model with an outcome definition ID, doing so will adversely affect you reporting data.
### Events with fixed definitions
The following events have a fixed definition item, which means that there is a one-to-one relationship between the event model and a definition item in Sitecore.
- `PageViewEvent:Event`
- `CampaignEvent:Event`
- `DownloadEvent:Event`
- `SearchEvent:Event`
In the following example, the `SearchEvent` defines a fixed `EventDefinitionId` that is passed into the base `Event` model. There is no public constructor that allows you to pass in a different definition ID.
```csharp
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
namespace Sitecore.XConnect.Collection.Model
{
public class SearchEvent : Event
{
public static readonly Guid EventDefinitionId = new Guid("0C179613-2073-41AB-992E-027D03D523BF");
public string Keywords { get; set; }
public SearchEvent(DateTime timestamp) : base(EventDefinitionId, timestamp)
{
}
}
}
```
See the [custom outcome](https://doc.sitecore.com/xp/en/developers/93/sitecore-experience-platform/create-a-custom-outcome-model.html "Create a custom outcome model") for an example of how to create an event with a fixed definition item.
Event models
Event models determine what is be collected when an event is triggered. For example, the `SearchEvent` model represents the search terms that were used as the `Keywords` property. xConnect ships with the following default event models:
- `Event`
- `Goal:Event`
- `Outcome:Event`
- `CampaignEvent:Event`
- `DownloadEvent:Event`
- `SearchEvent:Event`
- `PageViewEvent:Event` (System event)
- `PersonalizationEvent:Event` (System event)
- `MVTestTriggered` (System event)
> [!note]
> Not all goals, outcome, and page events have a model. Use the base `Goal`, `Outcome`, or `Event` classes to trigger the events that do not have a specialized model.
Keep the following recommended practices in mind when working with event models:
- Goals and outcomes must be triggered using the `Goal` and `Outcome` models, or an inheriting type.
- If an event definition ID is associated with a specialized model, such as `SearchEvent`, do not use that definition ID with another model.
- If you want to capture any custom data or enforce a particular constructor parameter, you must create your own event model. Your event model can inherit `Event`, `Goal`, or `Outcome`.
Use custom event models with meaningful names wherever possible, particularly if you plan to export interaction data to a third party. For example, `CarPurchaseOutcome` has more contextual meaning than `Outcome`.
> [!important]
> Do not rely on the `Data`, `DataKey`, `Text`, and `CustomValues` properties on the `Event` class to store custom data. These properties are only available for legacy purposes.
Event attributes
Events or individual event properties can be decorated with the following attribute:
- `[DONOTINDEX]`: Events or event properties decorated with this attribute are not indexed and are therefore not searchable. Use this for data that you are not interested in searching - such as binary data.
Triggering events
In the context of the tracker, you must use the tracker API to trigger an event. On session end, event data is mapped to xConnect event models and submitted to xConnect as an interaction. In any other context, use the xConnect Client API directly. Refer to the following topics for more information about triggering events:
- [Trigger an event using the xConnect Client API](https://doc.sitecore.com/xp/en/developers/93/sitecore-experience-platform/add-interaction-events.html "Add interaction events")
- [Trigger an event using the Tracker API](https://doc.sitecore.com/xp/en/developers/93/sitecore-experience-platform/triggering-built-in-events.html "Triggering built-in events")