Register an outcome programmatically

Abstract

How to register or trigger outcomes in code

As a contact moves from being an anonymous visitor to a known contact and customer, you can track events triggered and goals converted during their journey. Outcomes are business significant events that can be registered in the Sitecore Experience Database (xDB) as a result of one or more interactions between a contact and a brand. They can be either monetary or non-monetary.

Outcomes provide you with an insight into how your contacts interact with your website or external sources, as well as the relative financial value they have for your organization. An example of a website-based outcome could be when a customer buys a product from your website.

In the Sitecore marketing platform, you can act on outcomes by creating personalization, engagement automation, or by analyzing activity using applications such as Experience Analytics and the Experience Profile.

You create and define outcomes in the Marketing Control panel, which also contains several predefined outcome types and definitions. To register any outcome, whether predefined or custom, you must use the API to register the outcome event in the xDB when it is triggered by a visitor on your website. Registering an outcome ensures that the outcome is attached to an existing contact in the xDB.

There are two API classes you can use to register outcomes:

TrackerExtensions - extension methods on the Tracker abstract class that enable you to register outcomes in visitor sessions on a Sitecore website.
OutcomeManager - enables you to register outcomes from external data sources and save them directly to your database.

This topic outlines how to:

Register an outcome during a web session

The standard way to register outcomes is to use the TrackerExtensions API to register an outcome during a web session.

The TrackerExtensions API introduces extension methods on the Tracker class that enable you to manage outcomes that take place during a web session.

When you register an outcome using the TrackerExtensions API the outcome is not saved directly to the xDB collection database, instead it is stored in the session. This means that while the session is active it is still possible to cancel or modify the outcome, for example, if a contact changes their delivery address during the purchase process. The outcome is only registered and written to the collection database when the session ends.

There are two main advantages of using the TrackerExtensions API to register outcomes:

Performance - the outcome is stored in the session, which means there is less network traffic. When the session ends, the outcome is saved in the xDB.
Data consistency - the outcome is only stored in the collection database after the contact has been saved to the xDB. This ensures that all outcomes are attached to a corresponding contact. For example, if the contact is a robot, the contact is not saved and therefore neither is the outcome.

To register an outcome during a web session:

To use the TrackerExtensions API, import the following namespace into your C# source file: using Sitecore.Analytics.Outcome.Extensions;

Set parameters for the outcome as shown in the following code sample and described in the table below:

// Register an outcome in the session. It will only be saved to the database on session end
// and only in case the contact itself is saved.
var outcome = new ContactOutcome(outcomeId, outcomeDefinitionId, contactId);
Tracker.Current.RegisterContactOutcome(outcome);

The ContactOutcome constructor takes the following parameters:

Parameter	Description
`outcomeId`	The unique ID of the outcome in Sitecore.
`outcomeDefinitionId`	The Item ID of the outcome definition item in the Marketing Control Panel.
`contactId`	The unique ID of the contact stored in the collection database.

Use the following code to register an outcome. This method sets the contact ID internally.
```
Tracker.Current.RegisterContactOutcome(outcome);
```

Cancel an outcome (web session)

To cancel an outcome during the current web session use the DeleteContactOutcome method as shown in the following code sample:

// Unregister an outcome that was previously registered in the current session.
Tracker.Current.DeleteContactOutcome(outcomeId);

Get all outcomes

To retrieve all outcomes registered during the current web session use the Tracker.Current.GetContactOutcomes method as shown in the following code sample:

// Get all outcomes registered during the current session.
IList<IOutcome> outcomes = Tracker.Current.GetContactOutcomes();

Register an outcome from an external source

You use the OutcomeManager API to register outcomes that are not necessarily website or session related. The Outcome Manager API can be used to register all types of outcomes, particularly if they come from other external sources or if they are web sessions from other non-Sitecore websites. It enables you to register and save these outcomes directly to a database without storing them in a session first.

For example, this can be useful if you have an external CRM system or want to collect outcomes registered during offline interactions.

Note

Using the OutcomeManager API does not ensure data consistency or improve performance.

When you register an outcome using the OutcomeManager, it is saved directly to the xDB collection database. The outcome is still saved even if the contact ID you use does not correspond to a known contact in the xDB.

To register an outcome from an external source:

To access an instance of an OutcomeManager, use the following factory call:

// Instantiate the outcome manager.
var manager = Factory.CreateObject("outcome/outcomeManager", true) as OutcomeManager;

Use the following code to register an outcome:
```
// Register an outcome.
var outcome = new ContactOutcome(outcomeId, outcomeDefinitionId, contactId);
manager.Save(outcome);
```
Note
You can use a random identifier, such as ID.NewID, to generate a random outcomeId.

The ContactOutcome constructor takes the following parameters:

Parameter	Description
`outcomeId`	The unique ID of the outcome in Sitecore.
`outcomeDefinitionId`	The ItemID of the outcome definition item in the Marketing Control Panel.
`contactId`	The unique ID of the contact stored in the collection database.

Get all outcomes

To get all outcomes for a contact, use the following method:

// Get all outcomes of a contact.
IReadOnlyCollection<IOutcome> outcomes = manager.GetForEntity<IOutcome>(contactId);