Overview

The Profile service provides a REST interface to store and consume data associated with the customer profiles.

The service stores customer profiles as documents. Each profile document consists of JSON subdocuments related to specific profile aspects. The profile documents are consumed in the same form in which they are stored.

The Profile service allows you to retrieve all customer profile data with a single request.


API Reference

/{tenant}/profiles

/{tenant}/profiles

head

Returns number of profiles for the specified tenant. Requires scope hybris.profile_view.

/{tenant}/profiles/{profileId}

put

Creates or replaces the entire profile document. Requires scope hybris.profile_manage.

patch

Creates or updates part of the profile document. A maximum of 10 properties can be created or updated in one call. Beyond that, the service returns a bad request. Requires scope hybris.profile_manage.

get

Get a given profile document. Requires scope hybris.profile_view.

delete

Deletes a given profile document. Requires scope hybris.profile_manage.

/{tenant}/profiles/{profileId}/{propertyPath}

put

Overrides a profile property or creates a profile document if it does not exist. Requires scope hybris.profile_manage.

get

Get a given property value from a profile document. Requires scope hybris.profile_view.

delete

Deletes a given property from a profile document. Requires scope hybris.profile_manage.


Profile Explorer

The Profile Explorer is a debugging tool that displays the profile data stored in the document. Use this tool to browse the data stored in the profile, and to verify that the system stores the data within the expected document.

For more details about the Profile Explorer, and instructions how to use it, see the Profile Explorer documentation.


Profile document

Profile metadata

Every profile document contains a section named metadata. The metadata section includes two properties:

  • consentReference: The consent reference used for handling consents for the particular profile
  • lastUpdatedAt: This value displays the date and time of the last profile update in the ISO 8601 format

The system also updates the metadata.lastUpdatedAt field with every change introduced to the profile document.


Consent definition

Before the Profile service can store and consume profile information, you must first define consents for the collection of data related to, for example, the customer's storefront activity. Consent definition requires these actions:

  1. Create a relevant profile schema in the Enricher Authorization service.
    For more information about how to create or modify a schema, see the Schema management section in the Enricher Authorization service documentation.
  2. When the customer grants consent to the created schema, the service starts to collect relevant data.
    For more information about how to grant and revoke consents, see the Tutorial section in the Consent service documentation.


Consent handling

The Profile service stores and consumes customer profile data organized in the form of JSON documents. In accordance with the applicable data protection regulations, customers have the right to access their data and manage their privacy settings at any time. The Profile service receives information about a user's consents from the Consent service and, within a single document, displays only the data for which the user grants consent.

The Profile service respects consents, which you can manage in the Consent service.

The Profile service allows you to write data to a user's profile document and read such data. Depending on the user's privacy settings, the resulting JSON document contains only the relevant subdocuments, which reflect the user's consents. The service verifies consents only on the first and second document nesting levels. Writing to further sub-levels of the document depends upon the first-level and second-level privacy settings.

First-level consents

To start writing any data, initially, there must exist a consent for a property on the first nesting level of the document. Failing to define a consent of the first level prevents writing to further sub-levels of the document. Also, revoking consent on the first level prevents adding information on lower levels. Define a consent for a first-level property to write to this property and to further subdocuments.

Further-level consents

Subdocuments nested on the second and lower levels of the profile document do not require defined consents at all. However, if you decide to define such consents in order to manage privacy settings in greater granularity, the service respects them up to the second level only. If you define a consent on both the first and the second levels, the user must grant both consents to allow writing to the second level and further sub-levels of the document. If the user revokes consent on a selected level, writing to a property nested on this level and to its further sub-levels is not possible.

Example

  1. You intend to save the following document in the user's profile:
    {
    "a1Level":{
      "a2Level":{
         "a3Level":"value",
         "b3Level":"value"
      },
      "b2Level":"value",
      "c2Level":{
         "a3Level":"value"
       }
    },
    "b1Level":"value",
    "c1Level":"value"
    }
    
  2. You configure the system with the following consents. The symbol represents a granted consent, the symbol represents a revoked consent, while the - symbol means no defined consent. When you write the document from the example to the Profile service, the system allows and forbids the following parts of the document:

    PropertyConsents on levelsCommentRead/Write
    1st2nd3rd
    a1Level---allow
    a1Level.a2Level--allow
    a1Level.a2Level.a3Level-service respects the user's consents up to the second level only, consent granted on the second levelallow
    a1Level.a2Level.b3Levelservice respects the user's consents up to the second level only, consent granted on the second levelallow
    a1Level.b2Level--consent granted on the first levelallow
    a1Level.c2Level-consent granted on the first level but revoked on the second levelforbid
    a1Level.c2Level.a3Level-consent granted on the first level but revoked on the second levelforbid
    b1Level---forbid
    c1Level---consent not defined on the first levelforbid
  3. The resulting profile document looks like this:

{
  "a1Level":{
     "a2Level":{
        "a3Level":"value",
        "b3Level":"value"
     },
     "b2Level":"value"
   }
}
The service displays a profile document that respects all of the user's consents. When you try to store some properties, the response may also include a hybris-missing-consents header. The hybris-missing-consents header displays schemas to which the service fails to write, either due to a revoked consent or a schema not defined in the metamodel. The response does not include this header if the service saves all data properly.

The hybris-missing-consents header for the preceding sample request looks as follows:

hybris-missing-consents: https://api.beta.yaas.io/metamodel/v1/profiles/a1Level/c2Level,https://api.beta.yaas.io/metamodel/v1/profiles/b1Level,https://api.beta.yaas.io/metamodel/v1/profiles/c1Level

Block and unblock processing of profile data

A tenant can block the processing of user personal data at any time. In this case, the Profile service can no longer collect new data or access the existing data for this user. Unlike revoking a consent, blocking a profile does not result in data deletion. Once the tenant lifts this block, the user's data reappears and can be processed again, based on the user's consents.

Data deletion

Revoking a consent entails deleting particular data. This section describes what happens when you delete a consent reference or revoke a consent.

When you opt out in the Consent service by deleting the consent reference, the service also deletes the entire profile associated with that consent reference. Upon the deletion, the Profile service no longer stores any data regarding the user.

You can remove consent to particular profile data in the visual interface for the Consent service known as the Consent Manager. When you remove your consent for a particular schema, for example, profiles/insights/affinities, the service deletes the entire subdocument with the path insights.affinities and writing to the subdocument is no longer possible, unless you regrant the consent.

You must enable the Profile service extension in your Extension Browser for the data deletion on opt-out, or the revoke consent options to work.
When you revoke your consent to collect specific data, and later regrant consent, you can write to the subdocument again. However, the previously-deleted document does not reappear.


Profile service events

The Profile service sends notifications about the created, updated, or deleted profile documents.

Profile document creation event

When you enrich a profile, and there is no profile document for the selected profileId yet, the Profile service stores the event in the Context service with these values:

  • operation: The type of operation, in this case CREATE
  • schema: The schema defining the created profile document, https://api.beta.yaas.io/metamodel/v1/profiles
  • payload:
    {
    "profileId": "yourProfileId"
    }
    

The message contains the identifier for the created profile document.

Profile document update event

When you add new properties to a profile document or update existing properties, the Profile service prepares a list of events to send to the Context service. When you update a profile but there is no profile document for the selected profileId yet, the system also sends an event about the creation of a document. The profile document update event contains the following values:

  • operation: The type of operation, in this case UPDATE
  • schema: Because the service only allows the definition of event schemas up to the second level of the profile document, this value provides the most specific schema for changed or added property paths.
  • payload:
{
  "profileId": "yourProfileId",
  "updatedProperties": ["path.to.property1", "path.to.property2"]
}

Properties

  • profileId: The identifier for the updated profile document
  • updatedProperties: This value lists the changed or added property paths that belong to the notification schema. If you change multiple properties under one schema, the system groups them in the payload, and sends a single notification for the found schema group.

Example

This example presents how the Profile service creates notifications.

When you make a PUT or PATCH request on the /mycomicsshop/profiles/123-456 endpoint, with the following data:

{  
   "insights":{  
      "affinities":{  
         "products":{  
            "hulk":{  
               "score":5.0
            }
         },
         "categories":{  
            "marvel":{  
               "score":5.7
            }
         }
      }
   },
   "identities":{  
      "devices":{  
         "device12345":{  
            "deviceType":"gameboy"
         }
      }
   }
}

And the following schemas defined in SAP Hybris Profile:

  • profiles/insights
  • profiles/identities/devices

Your request triggers the following notifications:

  • Notification 1:
    • operation: UPDATE
    • schema: profiles/insights
    • payload:
      {
      "profileId": "123-456",
      "updatedProperties": ["insights.affinities.products.hulk.score", "insights.affinities.categories.marvel.score"]
      }
      

  • Notification 2:
    • operation: UPDATE
    • schema: profiles/identities/devices
    • payload:
      {
      "profileId": "123-456",
      "updatedProperties": ["identities.devices.device12345.deviceType"]
      }
      
Both the PUT and the PATCH methods update the profile document, and cause the service to send a notification, yet the results of each call are different. For more information, refer to the Create or replace a profile document section.
Be aware that your enricher receives notifications not only for the property path you are interested in, but for all properties that belong to the enricher-triggering schema. Therefore, your enricher must verify whether the updatedProperties attribute contains the property path your enricher listens to. This is particularly important to avoid infinite event loops. You could create this unwanted infinite loop, for example, if you write an enricher that updates the property under the insights.affinities.product.hulk.score property based on the insights.affinities.product.hulk.recentScore property, both of which belong to the same enricher-triggering schema. If you fail to verify the property path in the updatedProperties attribute, your enricher reacts to its own changes, in this case, the modification of the property under the insights.affinities.product.hulk.score path.

Profile document deletion event

Upon deletion of a profile document, the Profile service stores the event in the Context service with these values:

  • operation: The type of operation, in this case DELETE
  • schema: The schema defining the deleted profile document, https://api.beta.yaas.io/metamodel/v1/profiles
  • payload:
    {
    "profileId": "yourProfileId"
    }
    

The message contains the identifier for the deleted profile document.


Scheduled events in the Profile service

Apart from regular notifications sent upon a profile update, the Profile service may also send previously-scheduled events. However, the system offers this functionality only if you provide the value of the hybris-schedule-event-at header. Optionally, you can also provide the additional hybris-schedule-event-parameter header in your request.

Scheduled event

This section provides an example of notifications that the Profile service sends when you set the scheduled event delivery time, as described in the Event scheduling section.

At a specified hybris-schedule-event-at time, the system sends one or more scheduled events with these values:

  • operation: The type of operation, in this case SCHEDULED
  • schema: The schema that defines the scheduled event. If, for example, you update one property under the profiles/insights schema and another one under profiles/identities/devices, the Profile service sends a notification for these schemas, and two separate scheduled events.
  • payload:
{
  "profileId" : "999",
  "scheduleParameter" : "affinity=1,23",
}

Properties:

  • profileId: The identifier for the updated profile
  • scheduleParameter: Data delivered in the scheduled event. The caller provides the value of this attribute in the hybris-schedule-event-parameter parameter.


Metadata-based routing

The metadata-based routing functionality gives you greater control over the behavior of the SAP Hybris Profile system. Thanks to sending events that contain metadata, you can decide on the pattern of enricher triggering and event routing.

To reduce the number of events that reach your enricher, you can define filters applicable to the event schema or metadata. Only events meeting these additional conditions can trigger a particular enricher.

If you would like your enricher to react on a profile update, you can define a filter on event metadata.

A single notification can inform you about changes to more than one property. Also, two notifications with the same schema may inform you about changes to different properties. Therefore, define a filter for selected properties to limit events received by your enricher.

The Profile service passes the updatedProperties in the event metadata.

To select filters for each triggering schema, follow these steps:

  1. Click the selected schema box which appears below the schema browser.
  2. Click the CLICK TO ADD FILTERS caption.
  3. In the pop-up window, define your triggering filters.
  4. In the Operations field, insert the desired type of operation, for example, STORE. This field is not required. However, defining it allows you to narrow down the event filtering to a greater extent.
  5. In the Custom Filter field, insert a valid JSONPath expression.

    Example

    $.updatedProperties[?(@ =~ /.*observations.web.*.predominanttimezone.*/i)]

    This filter only allows further events that have the operation parameter set to UPDATE, and the updated properties include properties stored under the observations.web.*.predominanttimezone path. The enricher listens to this particular property, irrespective of the session ID. As a result, only updates of the predominant time zone would trigger this enricher.

  6. Click SAVE to confirm your choice and close the window.

  7. To verify your filter, go to the Monitoring & Tracing tab, and define the value of the Metadata field.

The system applies the Custom Filter to the provided metadata that follows this pattern:

{"updatedProperties": ["path.to.property1", "path.to.property2"]}

Example of metadata with real data

{"updatedProperties": ["observations.web.79e86d61-2d5d-4754-990d-8d656bee9010.predominanttimezone", "observations.web.79e86d61-2d5d-4754-990d-8d656bee9010.predominantactivitytime", "observations.web.523dd1d0-de4d-11e6-99a8-d9bb373dc57d.predominanttimezone"]}

Only if the metadata, which the Profile service adds, meets the filter criteria, does the dispatcher pass the event to trigger target enrichers. In the sample filter, the metadata matches the filter, so the event triggers the desired enricher.


GDPR compliance

To comply with the GDPR provisions, SAP Hybris Profile allows you to export and remove tenant customer data, as well as export and rectify data of a single customer. Below you can read more about the process of requesting profile data, as well as to see sample files.

Export all tenant customer data

SAP Hybris Profile allows you to export tenant customer data collected in a JSON file.

Example of the exported profile data

Click to see the sample exported tenant customer data

To request the file, the tenant must contact the support team and then specify the preferred delivery method.

Export data of a single customer

To exercise the GDPR right to access their data, customers should contact their tenants. To export the data for a single customer, the tenants can use the Profile service API.

Example of the exported profile data

Click to see the sample exported tenant customer data

Remove all tenant customer data

Upon the tenant's request, the support team can remove all the tenant's customer profile data. After the deletion, the Profile service no longer stores any data regarding tenant's customers. If the tenant requests a data export before the deletion, the support team can later restore the deleted data.

Rectify data of a single customer

In line with the GDPR provisions, SAP Hybris Profile allows customers to rectify their personal data in case it is inaccurate. Tenants can manually correct their customers' data using the Profile service API.


Operations on profile documents

The Profile service provides an endpoint that allows you to perform operations on the profile documents.

Create or replace a profile document

The service allows you to create a profile document. A profile document includes all data associated with a given customer's profile.

If you run the command in the example, the service creates a profile document that replaces the existing document. An update replaces all data with the information included in the new document. To update the selected data only, run the command provided in this example.

To create a new profile document, run the following command:

cURL command example

curl -X PUT -H "Authorization: Bearer access_token" -H "hybris-consent-reference: consent-reference" -H "Content-Type: application/json" -d '{
  "insights": {
    "affinities": {
      "products": {
        "productName": {"someProperty": "some property value"}
      }
    }
  },
  "identities": {
      "devices": {
        "deviceId": {"someProperty": "some property value"}
      }
  }
}' 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles/{profileId}' -i

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_manage
    • hybris-consent-reference: Your consent reference
  • URI parameters
    • {tenant}: Your tenant name
    • {profileId}: The identifier of a given profile

Example of a PUT request with real data

curl -X PUT -H "Authorization: Bearer 001-65115c05-f2a2-4413-8d60-45349d103208" -H "hybris-consent-reference: 965dcef9-da77-40bf-9e9b-65fd735df113" -H "Content-Type: application/json" -d '{
  "insights": {
    "affinities": {
      "products": {
        "product123": {"score": 1234}
      }
    }
  },
  "identities": {
    "devices": {
      "device1": {"deviceType": "notebook"}
    }
  }
}' 'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles/965dcef9-da77-40bf-9e9b-65fd735df113' -i

Response

If the service successfully creates or replaces an entire profile document, it sends a response with a status code of 204. However, if the system does not store some of the data you intend to save, despite the successful status code, it means that there are no consents granted to the collection of that data, or that the schemas for this data are not defined in the metamodel. In this case, the response includes a hybris-missing-consents header with a comma-delimited list of schemas to which writing is forbidden. A response with a status code of 403 indicates that the consent reference does not exist.

Create or update part of a profile document

The service allows you to create or update part of a document, as opposed to the entire document. To update the selected data only, or create part of a document, use the following command.

cURL command example

curl -X PATCH -H "Authorization: Bearer access_token" -H "hybris-consent-reference: consent-reference" -H "Content-Type: application/json" -d '{
  "someProperty": "some property value"
}' 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles/{profileId}' -i

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_manage
    • hybris-consent-reference: Your consent reference
  • URI parameters

    • {tenant}: Your tenant name
    • {profileId}: The identifier of a given profile
    When you perform a PATCH request, you can update or create up to 10 properties. Beyond that, the service returns a bad request.

Example of a PATCH request with real data

curl -X PATCH -H "Authorization: Bearer 001-65115c05-f2a2-4413-8d60-45349d103208" -H "hybris-consent-reference: 965dcef9-da77-40bf-9e9b-65fd735df113" -H "Content-Type: application/json" -d '{
  "insights": {
    "affinities": {
      "products": {
        "product123": {"score": 125}
      }
    }
  },
  "identities": {
    "devices": {
      "device2": {"deviceType": "smartphone"}
    }
  }
},' 'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles/965dcef9-da77-40bf-9e9b-65fd735df113' -i

When you send that request, the previously-created sample profile document included in the Create a profile document section updates as shown:

{
  "insights": {
    "affinities": {
      "products": {
        "product123": {"score": 125}
      }
    }
  },
  "identities": {
    "devices": {
      "device1": {"deviceType": "notebook"},
      "device2": {"deviceType": "smartphone"}
    }
  }
}

Response

If the service successfully creates or updates a part of a profile document, it sends a response with a status code of 204. However, if the system does not store some of the data you intend to save, despite the successful status code, it means that there are no consents granted to the collection of that data, or that the schemas for this data are not defined in the metamodel. In this case, the response includes a hybris-missing-consents header with a list of comma-delimited schemas to which writing is forbidden. A response with a status code of 403 indicates that the consent reference does not exist.

Get a profile document

To get a given profile document, run the command in this example.

cURL command example

curl -X GET -H "Authorization: Bearer access_token" 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles/{profileId}'

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_view
  • URI parameters
    • {tenant}: Your tenant name
    • {profileId}: The identifier of a given profile

Example of a GET request with real data

curl -X GET -H "Authorization: Bearer 001-65115c05-f2a2-4413-8d60-45349d103208" 'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles/965dcef9-da77-40bf-9e9b-65fd735df113'

Responses

A response with the status code of 200 indicates that a service successfully retrieved the specified profile document.
If your call returns a response with a status code of 404, the service could not find the requested profile document.

Get a selected field

To get a selected field, or fields, from a given profile document, run the command in this example.

cURL command example

curl -X GET -H "Authorization: Bearer access_token" 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles/{profileId}?fields={property1},{property2}'

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_view
  • URI parameters
    • {tenant}: Your tenant name
    • {profileId}: The identifier of a given profile
  • Query parameters

    • properties: When you provide a properties query parameter, the service returns only the fields that include the specified property? You can filter your results by multiple properties. Use ',' as a separator.
    When you provide a property query parameter in your request, you can filter up to 10 properties. Beyond that, the Profile service returns a bad request.

Example of a GET request with real data

curl -X GET -H "Authorization: Bearer 001-65115c05-f2a2-4413-8d60-45349d103208" 'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles/965dcef9-da77-40bf-9e9b-65fd735df113?fields=insights.affinities.products,identities.devices'

Responses

A response with the status code of 200 indicates that the service returned the requested fields.

Delete a profile document

You can delete the previously-created profile document by running the command provided in this example.

cURL command example

curl -X DELETE -H "Authorization: Bearer access_token" 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles/{profileId}'

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_manage
  • URI parameters
    • {tenant}: Your tenant name
    • {profileId}: The identifier of a given profile

Example of a DELETE request with real data

curl -X DELETE -H "Authorization: Bearer 001-65115c05-f2a2-4413-8d60-45349d103208" 'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles/965dcef9-da77-40bf-9e9b-65fd735df113'

Response

The response with a status code of 204 indicates that the service deleted a given profile document. The response with a status code of 404 indicates that the service could not find the requested profile document.

Get the number of all profiles owned by a tenant

To get the number of all profiles owned by a given tenant, run the command in this example.

cURL command example

curl -X HEAD -H "Authorization: Bearer access_token" -I 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles'

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_view
  • URI parameters
    • {tenant}: Your tenant name

Example of a HEAD request with real data

curl -X HEAD -H "Authorization: Bearer 001-65115c05-f2a2-4413-8d60-45349d103208" -I 'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles'

Response

A response with the status code of 204 indicates that a service successfully retrieved the number of profiles owned by a specified tenant.
The system returns this number as the hybris-count header.

Get the number of known and unknown profiles owned by a tenant

Apart from getting the number of all profiles owned by a tenant, you can also find out the number of known profiles, such as registered or logged-in users, and the number of unknown profiles, such as anonymous users. Add the insights.knownCustomer query parameter to the request to get the total count of profiles, and set the value to either true or false, accordingly. Run the commands in this example to retrieve the number of known or unknown profiles:

cURL command example

curl -X HEAD -H "Authorization: Bearer access_token" -I 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles?insights.knownCustomer=true'

curl -X HEAD -H "Authorization: Bearer access_token" -I 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles?insights.knownCustomer=false'

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_view
  • URI parameters
    • {tenant}: Your tenant name

Example of a HEAD request with real data

curl -X HEAD -H "Authorization: Bearer 001-65115c05-f2a2-4413-8d60-45349d103208" -I 'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles?insights.knownCustomer=true'

curl -X HEAD -H "Authorization: Bearer 001-65115c05-f2a2-4413-8d60-45349d103208" -I 'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles?insights.knownCustomer=false'

Response

A response with the status code of 204 indicates that a service successfully retrieved the number of profiles owned by a specified tenant.
The system returns this number as the hybris-count header, however, it does not indicate if the count applies to known or unknown profiles.


Operations on profile properties

The Profile service provides an endpoint that allows you to perform operations on the profile document properties.

Supported property notations

The Profile service supports special characters in the property names. The propertyPath parameter is a path that uses a subset of JSONPath notation to indicate one particular element. In the propertyPath parameter, the Profile service:

  • supports only definite paths, that is paths pointing to a single document element
  • does not allow $. characters at the beginning of the path, contrary to the original JSONPath notation
  • does not support references to array elements

Because there are certain differences between the notation accepted in the Profile service and the original JSONPath standard, follow the examples to build valid paths for properties that contain special characters.

Sample property namepropertyPath
{
  "observations": {
    "web": {
      "sessions": {
        "abc-123": 5
      }
    }
  }
}
observations.web.sessions.abc-123

observations.web.sessions['abc-123']

observations.web.sessions["abc-123"]
{
  "observations": {
    "web": {
      "sessions": {
        "sessionId": {
          "products": {
            "canon.50d": 5
          }
        }
      }
    }
  }
}
observations.web.sessions.sessionId.products['canon.50d']

observations.web.sessions.sessionId.products["canon.50d"]
{
  "observations": {
    "web": {
      "sessions": {
        "sessionId": {
          "category": {
            "b&w photography": 5
          }
        }
      }
    }
  }
}
observations.web.sessions.sessionId.category['b&w photography']

observations.web.sessions.sessionId.category["b&w photography"]

JSONpath uses both dots and square brackets as nesting marks. If you do not put the property name in square brackets and quotation marks, the content following the . character points to a lower level.

Unsupported notations:

Sample propertyPathComments
$.observations.web.sessions.abc-123The service does not accept the $. characters at the beginning.
observations.web.sessions[0]The character in the brackets is not a property name, but a reference to an array element.
observations.web.sessions.*The * character indicates that the path is not definite and may resolve to multiple properties.
observations..sessionsThe double dots indicate that the path is not definite and may point to multiple properties.

cURL command example with propertyPath parameter containing special characters

curl -X GET -H "Authorization: Bearer 001-65115c05-f2a2-4413-8d60-45349d103208" 'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles/123/observations.web.sessions.123.products["captain.america 100"]

Create or replace a property

By running the command in the example, you can create a new property or replace the existing property.

cURL command example

curl -X PUT -H "Authorization: Bearer access_token" -H "hybris-consent-reference: consent-reference" -H "Content-Type: application/json" -d '"some property value"'
'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles/{profileId}/{propertyPath}'

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_manage
    • hybris-consent-reference: Your consent reference
  • URI parameters
    • {tenant}: Your tenant name
    • {profileId}: The identifier of a given profile
    • {propertyPath}: The profile property path. Use . or [] as nesting marks.

Example of a PUT request with real data

curl -X PUT -H "Authorization: Bearer 001-65115c05-f2a2-4413-8d60-45349d103208" -H "hybris-consent-reference: 965dcef9-da77-40bf-9e9b-65fd735df113" -H "Content-Type: application/json" -d '20'
'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles/965dcef9-da77-40bf-9e9b-65fd735df113/insights.affinities.products.product123.score'

Response

A response with a status code of 204 indicates that the service successfully created or replaced a given property. However, if the system does not store some of the data you intend to save, despite the successful status code, it means that there are no consents granted to the collection of that data, or that the schemas for this data are not defined in the metamodel. In this case, the response includes a hybris-missing-consents header with a comma-delimited list of schemas to which writing is forbidden. A response with a status code of 403 indicates that the consent reference does not exist.

Get a property

You can retrieve a given property value from a profile document by running the following command.

cURL command example

curl -X GET -H "Authorization: Bearer access_token" 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles/{profileId}/{propertyPath}'

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_view
  • URI parameters
    • {tenant}: Your tenant name
    • {profileId}: The identifier of a given profile
    • {propertyPath}: The profile property path. Use . as a nesting mark.

Responses

A response with the status code of 200 indicates that the service returned the requested property value. The consent reference value associated with a given profile is returned in the hybris-consent-reference header. If you receive a response with the status code of 404, the service could not find the requested property.

Delete a property

If you run the following command, the service deletes a given profile property.

cURL command example

curl -X DELETE -H "Authorization: Bearer access_token" 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles/{profileId}/{propertyPath}'

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_manage
  • URI parameters
    • {tenant}: Your tenant name
    • {profileId}: The identifier of a given profile
    • {propertyPath}: The profile property path. Use . as a nesting mark.

Responses

The response with a status code of 204 indicates that the service deleted a given profile property. The response with a status code of 404 indicates that the service could not find the requested property.


Event scheduling

Set the event delivery time for a profile document

This example shows how to create or update a profile document, while also defining when to send a scheduled event to the system. A single request to the Profile service can result in the system releasing more than one scheduled events.

cURL command pattern

curl -X PUT -H "Authorization: Bearer access_token" -H "hybris-consent-reference: consent-reference" -H "hybris-schedule-event-at: time-date-format" -H "hybris-schedule-event-parameter: schedule_event_parameter" -H "Content-Type: application/json" -d '{
  "some" : "custom property"
}' 'https://api.beta.yaas.io/hybris/profile/v1/{tenant}/profiles/{profileId}/{propertyPath}' -i

Parameters

  • Headers
    • Authorization: Provide a valid Bearer access token with the scope hybris.profile_manage
    • hybris-consent-reference: Your consent reference
    • hybris-schedule-event-at: Provide the time when the scheduled event, associated with the created or updated element, should be sent to the system. 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 system sends a scheduled event or events only when you define the schedule time value.
    • hybris-schedule-event-parameter: This header is optional. A string that defines additional data, sent with the scheduled event. For example set affinity to 1,23.
  • URI parameters
    • {tenant}: Your tenant name
    • {profileId}: The identifier of a given profile

Example of a PUT request with real data

 curl -X PUT -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" -H "consent-reference: 965dcef9-da77-40bf-9e9b-65fd735df113" -H "hybris-schedule-event-at: 2016-12-10T18:06:17.234Z" -H "hybris-schedule-event-parameter: affinity=1,23" -H "Content-Type: application/json" -d '{
   "name" : "Asterix and Obelix", "description" : "Adventures of Asterix and Obelix", "price" : "$10"
   }' 'https://api.beta.yaas.io/hybris/profile/v1/mycomicsshop/profiles/965dcef9-da77-40bf-9e9b-65fd735df113/insights.affinities.products.product123' -i
If you set a past date, the Scheduled Event service releases the event right away. To avoid this situation, use relative schedule time, or duration, in the scheduleAt parameter.


Glossary

TermDescription
authorizationThe process of determining whether a given microservice has permission to gain consent.
consentPermission to access (read, write) specific profile data, for example, permission to read or write an age estimation or physical address. A consumer and a tenant can grant and revoke consent for subsets of their respective data.
consent classA developer-defined string alias that references a set of profile data, or "schemas", for which to grant and revoke consent.
consent referenceA unique, randomized string that serves as a passcode to decrypt data associated with one or more schemas.
consumerThe end user whose actions yield profile data. A profile describes a single consumer.
contextData that triggers enrichers. You can collect this data from consumer-triggered events or from third-party sources such as weather stations.
Context serviceAn internal microservice that manages the insertion of, and the retrieval of, context data in the Context Repository.
enricherA microservice that retrieves personal data from the Context service and other services, possibly alters or extends it, and then persists enriched data in a profile document. 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.
identityOne of many independent units of data used to identify a unique profile, such as an email address, browser type, or version.
profileData about a single consumer, collected and derived from events that the consumer triggers, or events that are logically associated with that consumer.
schemaA string representation of a particular data structure, used to define read and write permissions for SAP Hybris Profile microservices.
tenantA tenant is a group of users on a project sharing common access, with specific privileges to a service.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.