Overview
The Context service provides a REST interface to store and read input data and events in SAP Hybris Profile.
API Reference
/{tenant}/data
/{tenant}/data
Creates a new resource and returns it location. Requires scope hybris.profile_context_manage.
/{tenant}/data/{id}
Returns data for given tenant, uri and id. Requires scope hybris.profile_context_view.
Deletes context data for given id. Requires scope hybris.profile_context_manage.
/{tenant}/consentReferences/{consentReference}/data
/{tenant}/consentReferences/{consentReference}/data
Gets all event identifiers for given consent reference. hybris.profile_context_view scope is required
Context
Context adapters use the Context service to pass information to the SAP Hybris Profile solution. This information should come from systems that are using SAP Hybris Profile. The data that is passed can contain a wide variety of information. Information about user activity on the storefront is just one example.
The Context service stores events in an internal database. The service then passes a link to each stored event to the SAP Hybris Profile solution's internal service, which then sends the link to the proper enrichers. Using the link, enrichers fetch the real event from the Context service and analyze the information in it. The enrichers can then store the data, enriched or as is, to the profile database.
The events stored by the Context service are not the final data that can be used for analysis. Only data stored by enrichers can be used for this purpose.
Other types of events that can be stored by the Context service are information about the creation and deletion of nodes or relationships in the profile database (changes done by enrichers).
Every event must have its own unique schema. You can only store an event if the relevant consent to the event's schema is granted in a consent reference (a set of consents used to store the event). The stored data is encrypted and can be read only if the consent to the event's schema is still granted (was not changed). If the end user revokes consent for one schema, then all events stored with this schema will be inaccessible and unreadable. The consent reference is stored together with the event, so it is not required to read data from the Context service.
Context events
Customer activities in the storefront result in context events. Context adapters, such as the Piwik service, pass those events to the Context service.
Because the Context service accepts all messages in JSON format, the content of the message depends on the adapter logic. This example shows a sample event that the Piwik service delivers to the Context service:
{
"res": "1920x1200",
"res_height": 1200,
"_pkc": "Phones",
"_profile_custom": {},
"ipAddress": "10.36.2.143",
"source": {
"action_name": "ProductDetailPageViewEvent",
"idsite": "1",
"rec": "1",
"r": "469869",
"h": "13",
"m": "1",
"s": "51",
"url": "http://somestore.yaas.io/#!/products/550179c138ae86edc6725ef7/",
"_id": "93337f761afbab86",
"_idts": "1425374194",
"_idvc": "18",
"_idn": "0",
"_refts": "0",
"_viewts": "1426090398",
"_ects": "1425390712",
"pdf": "1",
"qt": "0",
"realp": "0",
"wma": "0",
"dir": "0",
"fla": "1",
"java": "1",
"gears": "0",
"ag": "1",
"cookie": "1",
"res": "1920x1200",
"cvar": "{\"2\":[\"_pkp\",110],\"3\":[\"_pks\",\"lumia920\"],\"4\":[\"_pkn\",\"Nokia Lumia 920\"],\"5\":[\"_pkc\",\"Phones\"]}",
"gt_ms": "13"
},
"sessionId": "93337f761afbab86",
"url": "http://somestore.yaas.io/#!/products/550179c138ae86edc6725ef7/",
"res_width": 1920,
"_pks": "lumia920",
"_pkn": "Nokia Lumia 920",
"action": "viewproduct",
"_pkp": 110,
"user": "mustermann@hybris.com"
}
The Context service does not pass the received event to the SAP Hybris Profile system. Instead, it stores the event in the database, and generates a new message that includes the link to the stored event. The Context service then passes that message to SAP Hybris Profile, which, in turn, delivers it to enrichers. Enrichers use that link to fetch basic event data of the source event, sent by an adapter, from the Context service.
This example shows a sample message that an enricher gets from PubSub:
{
"createdAt": 1480344414945,
"metadata": {
"schema": "https://api.us.yaas.io/hybris/schema/v1/core/dispatcher-payload"
},
"tenant": "profiletestproj",
"payload": "{\"context\":{\"consentRefId\":\"ae3ade81-052f-4f36-8825-f1617180ed5e\",\"location\":\"https://api.us.yaas.io/hybris/profile-context/profiletestproj/data/57709830-be52-11e4-9370-edc4d47be75d\",\"id\":\"57709830-be52-11e4-9370-edc4d47be75d\"},\"schema\":\"context/commerce/ProductView\",\"operation\":\"CREATE\",\"message\":{\"payload\":\"{\\\"consentRefId\\\":\\\"ae3ade81-052f-4f36-8825-f1617180ed5e\\\",\\\"location\\\":\\\"https://api.us.yaas.io/hybris/profile-context/profiletestproj/data/57709830-be52-11e4-9370-edc4d47be75d\\\",\\\"id\\\":\\\"57709830-be52-11e4-9370-edc4d47be75d\\\"}\"}}",
}
Event attributes
- createdAt: Indicates when the event was created; the information is provided in the Unix Epoch format
- schema: Defines the JSON message format
- tenant: Defines the tenant for whom the event took place
- payload: The payload of the event
The value of the payload attribute is JSON stored as a string value. For clarity, see the payload value in JSON format:
{
"context":{
"location":"https://api.us.yaas.io/hybris/profile-context/profiletestproj/data/57709830-be52-11e4-9370-edc4d47be75d",
"consentRefId":"ae3ade81-052f-4f36-8825-f1617180ed5e",
"id":"57709830-be52-11e4-9370-edc4d47be75d"
},
"schema":"context/commerce/ProductView",
"operation":"STORE"
}
Properties
- location: The link defining where the event is stored
- consentRefId: The consent reference used for storing the event
- id: The unique identifier of the event
- schema: Defines the type of event
- operation: The type of operation defined by a context adapter
After fetching the events from the Context service, enrichers process the event data to enrich the profile database.
Customers can also request the tenant to update their context events if the provided information is incorrect. To rectify your customer data, you must first delete the incorrect event and then replace it with the updated one. See how to delete and store events, accordingly, in the Tutorial section.
Context trace ID
The contextTraceId is a unique identifier for an event. The identifier is constant across the entire SAP Hybris Profile system. The system returns the contextTraceId as id in the payload of events sent to the PubSub service.
The contextTraceId is used internally to monitor data flow. If you encounter any problems with event processing, include the contextTraceId in your support request.
For further details about event tracking, see the Track data in the Trace Explorer section.
Introduction to Tutorial
This tutorial uses the Context service API Console to:
- Store a single event
- Read a stored event
- Delete a stored event
Prerequisites
In order to store and read events using the Context service, you must have:
- Access to the Context service API Console.
- A valid Bearer access token. For more information about how to get an access token, see the
/tokenendpoint section of the OAuth 2.0 service documentation. - A valid consent reference with granted consent to schemas of the events to be stored or read. For more information, see the Consent service documentation.
Store single event
The steps shown in this example demonstrate how to pass a single event to the SAP Hybris Profile system.
Request
- Headers
- Authorization - Provide a valid Bearer access token.
- consent-reference - Provide the valid consent reference to which the data should belong.
- operation - Provide the proper operation type. For a context adapter, use the value
STORE. - schema - Provide the valid schema of the event.
- hybris-ttl - This header is optional. To comply with the provisions of the General Data Protection Regulation, the system allows you to determine when to delete a context event. You can provide an event's time to live, or TTL value. Ensure the time format is ISO 8601-compliant, and presented either as a combination of date and time, such as 2016-12-10T19:06:17.234+01:00, or as a duration, such as P2DT2H30M5S. For duration, the system supports only days, hours, minutes, and seconds. The default TTL is 72 hours, that is three days, and the maximum TTL is 4440 hours, or approximately half a year.
- URI parameters
- {tenant} - Provide your tenant name.
- Body
- Provide the proper JSON object.
- Example
curl -X POST -H "Authorization: Bearer access_token" -H "consent-reference: consent-reference" -H "operation: operation" -H "schema: eventSchema" -H "hybris-ttl: eventTTL" -H "Content-Type: application/json" -d '{ "property1" : "value1", "property2" : "value2" } ' "https://api.us.yaas.io/hybris/profile-context/v1/{tenant}/data"
Example of a POST request with real data
curl -X POST -H "Authorization: Bearer 019-23c46dcd-0499-4c3d-9873-37f612ef2d9c" -H "consent-reference: consent-reference" -H "operation: STORE" -H "schema: context/commerce/FrontendEntered" -H "hybris-ttl: P2DT2H30M5S" -H "Content-Type: application/json" -d '{
"res_width": 1920,
"res": "1920x1200",
"res_height": 1200,
"_pks": "lumia920",
"_pkc": "Phones",
"_pkn": "Nokia Lumia 920",
"action": "viewproduct",
"_pkp": 110,
"source": {
"action_name": "ProductDetailPageViewEvent",
"idsite": "1",
"rec": "1",
"r": "469869",
"h": "13",
"m": "1",
"s": "51",
"url": "http://somestore.yaas.io/#!/products/550179c138ae86edc6725ef7/",
"_id": "93337f761afbab86",
"_idts": "1425374194",
"_idvc": "18",
"_idn": "0",
"_refts": "0",
"_viewts": "1426090398",
"_ects": "1425390712",
"pdf": "1",
"qt": "0",
"realp": "0",
"wma": "0",
"dir": "0",
"fla": "1",
"java": "1",
"gears": "0",
"ag": "1",
"cookie": "1",
"res": "1920x1200",
"cvar": "{\"2\":[\"_pkp\",110],\"3\":[\"_pks\",\"lumia920\"],\"4\":[\"_pkn\",\"Nokia Lumia 920\"],\"5\":[\"_pkc\",\"Phones\"]}",
"gt_ms": "13"
},
"sessionId": "93337f761afbab86",
"user": "mustermann@hybris.com",
"url": "http://somestore.yaas.io/#!/products/550179c138ae86edc6725ef7/"
}' "https://api.us.yaas.io/hybris/profile-context/v1/mycomicsshop/data"
Response
A successful response returns:
- The ID of the stored event
- A link to read the stored event
- The value of the consent reference used to store the data
{
"id": "939063d0-ec15-11e5-b3ea-ff853839ad56",
"link": "https://api.us.yaas.io/hybris/profile-context/v1/mycomicsshop/data/939063d0-ec15-11e5-b3ea-ff853839ad56",
"consentRefId": "consent-reference"
}
The response also includes a hybris-ttl header which provides information on the event's time to live. If you do not include this header in your request, the context event's TTL takes the default value. If you provide an incorrect TTL, the system additionally returns a warning header.
If you provide:
- a TTL value longer than the maximum TTL, the system sets the maximum TTL value and adds a warning header, for example
warning : 199 - "ttl value PT8000H is too big. Using max ttl PT4440H instead." - an invalid TTL value, that is one that does not match the ISO 8601 format, the system sets the default TTL value and adds a warning header, for example
warning : 199 - "ttl value invalidTtlValue is invalid. Using default ttl PT72H instead." - a negative TTL value, the system sets the default TTL value and adds a warning header, for example
warning: 199 - "ttl is value PT-7694H-1M-22.756S is negative. Using default ttl PT72H instead."
Read single event
Read a single event
The steps shown in this example demonstrate how to read a stored event from the Context service. You do not have to pass the value of the consent reference used to store the event. You must define the ID of the stored data and have permissions to it.
Request
- Headers
- Authorization - Provide a valid Bearer access token with the proper scope.
- URI parameters
- {tenant} - Provide your tenant name.
- {id} - Provide a valid stored event identifier.
- Example
curl -X GET -H "Authorization: Bearer access_token" "https://api.us.yaas.io/hybris/profile-context/v1/{tenant}/data/{id}"
Example of a GET request with real data
curl -X GET -H "Authorization: Bearer 019-23c46dcd-0499-4c3d-9873-37f612ef2d9c" "https://api.us.yaas.io/hybris/profile-context/v1/mycomicsshop/data/fb22c890-ec14-11e5-b3ea-ff853839ad56"
Response
A successful response returns stored data, as shown.
{
"res_width": 1920,
"res": "1920x1200",
"res_height": 1200,
"_pks": "lumia920",
"_pkc": "Phones",
"_pkn": "Nokia Lumia 920",
"action": "viewproduct",
"_pkp": 110,
"source": {
"action_name": "ProductDetailPageViewEvent",
"idsite": "1",
"rec": "1",
"r": "469869",
"h": "13",
"m": "1",
"s": "51",
"url": "http://somestore.yaas.io/#!/products/550179c138ae86edc6725ef7/",
"_id": "93337f761afbab86",
"_idts": "1425374194",
"_idvc": "18",
"_idn": "0",
"_refts": "0",
"_viewts": "1426090398",
"_ects": "1425390712",
"pdf": "1",
"qt": "0",
"realp": "0",
"wma": "0",
"dir": "0",
"fla": "1",
"java": "1",
"gears": "0",
"ag": "1",
"cookie": "1",
"res": "1920x1200",
"cvar": "{\"2\":[\"_pkp\",110],\"3\":[\"_pks\",\"lumia920\"],\"4\":[\"_pkn\",\"Nokia Lumia 920\"],\"5\":[\"_pkc\",\"Phones\"]}",
"gt_ms": "13"
},
"sessionId": "93337f761afbab86",
"user": "mustermann@hybris.com",
"url": "http://somestore.yaas.io/#!/products/550179c138ae86edc6725ef7/"
}
Delete single event
Delete a single event
The steps shown in this example demonstrate how to delete a stored event from the Context service. You do not have to pass the value of the consent reference used to store the event. You must define the ID of the stored data and have permissions to it.
cURL command example
curl -X DELETE -H "Authorization: Bearer access_token" 'https://api.us.yaas.io/hybris/profile-context/v1/{tenant}/data/{id}'
Parameters
- Headers
- Authorization - Provide a valid bearer access token with the scope hybris.profile_context_manage
- URI parameters
- {tenant} - Provide your tenant name
- {id} - Provide a valid identifier of the stored event
Example of a DELETE request with real data
curl -X DELETE -H "Authorization: 019-23c46dcd-0499-4c3d-9873-37f612ef2d9c" 'https://api.us.yaas.io/hybris/profile-context/v1/mycomicsshop/data/33c20320-c475-11e7-8319-a526da02da37' -i
Response
A response with the status code of 204 indicates that the service successfully deleted an event.
Glossary
| Term | Description |
|---|---|
| authorization | The process of determining whether a given microservice has permission to gain consent. |
| consent | Permission to access (read, write) specific profile data, for example, permission to read/write age estimation or physical address. A consumer and a tenant can grant and revoke consent for subsets of their respective data. |
| consent class | A string alias, defined by developers, that references a set of profile data (also called "schemas") for which consent can be granted and revoked. This string is exposed to users (consumers and tenants) as a reference through which they control consent. For example, the consent class "Purchases" might reference a set of data that includes items purchased, purchase dates, and purchase prices. Toggling consent for "Purchase" would enable and disable consent for that entire set of data. |
| consent reference | A unique, randomized string that serves as a passcode to decrypt data associated with one or more schemas. Various service calls require a consent reference. |
| consumer | The end user whose actions yield profile data in the graph. A profile describes a single consumer. |
| context | Data that affects the state of the graph. This data can be collected from consumer-triggered events or from third-party sources such as weather stations. |
| Context Adapter | A microservice that receives data and, optionally, adapts it for entry into the graph. For example, a context adapter can adapt address data by adding a ZIP code and normalizing the street labels (for example, changing "St" to "Street"). The context adapter then passes the data through the Context service, which caches it so that enrichers can subsequently persist the data in the graph. |
| context repository | A temporary cache for adapted context data, before it is further processed by enrichers and persisted in the graph. |
| context service | An internal microservice that manages the insertion of, and the retrieval of, context data in the Context Repository. |
| encryption key | A unique, randomized string used to encrypt and decrypt specific data in the graph. Each data element is encrypted with a different encryption key. Decryption, using this key, is required to access, view, and alter the data. |
| enricher | A microservice that retrieves data from the Context Repository and/or Graph, possibly alters or extends it, and then persists data in the graph. An enricher can interpret data points, or sets of data points, to yield new data to persist. For example, an enricher can interpret purchasing data and contemporaneous weather station data to yield new data indicating that the consumer is a rainy-day shopper. |
| graph | The database that stores profile data as nodes, edges, and properties, and allows semantic queries. |
| identity | One of many independent units of data used to identify a unique profile, such as an email address, browser type, or version. |
| profile | Data about a single consumer, collected and derived from events that are triggered by, or are logically associated, with that consumer. |
| schema | A string representation of a path in the graph that represents an abstraction, rather than a concrete instance, of a particular data structure. |
| tenant | A registered entity with a shared commercial goal that subscribes to SAP Hybris Profile services and packages to reach that goal. A tenant can also develop and contribute enrichers and context adapters to the SAP Hybris Profile suite. Within YaaS, a tenant is a project. |
If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Use our private help channel. Receive updates over email and contact our specialists directly.
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.