Heart Beat

Overview

The Heart Beat service is responsible for checking the SAP Hybris Profile's alive state.

The Heart Beat service uses the Piwik service to send check event. This event should change the graph. After the duration defined in the configuration, the Heart Beat service checks whether the event is stored and the graph has been changed.

The Heart Beat service repeats the verification at predetermined time intervals as defined in the configuration.

API Reference

/status/{projectTenant}/{enricherId}/triggeredBy/{schema}

/status/{projectTenant}/{enricherId}/triggeredBy/{schema}

get

Endpoint that answers question "why my enricher doesn't work". Hearbeat will check all places when possible misconfiguration could be made. When successful response is returned, this mean that event for received schema can be send to desired enricher. Requires scope hybris.profile_heartbeat_view.

Endpoint that answers question "why my enricher doesn't work". Hearbeat will check all places when possible misconfiguration could be made. When successful response is returned, this mean that event for received schema can be send to desired enricher. Requires scope hybris.profile_heartbeat_view.

URI Parameters

  • projectTenant: required (string)

    tenant that will be used to perform checks, e.g whether tenant is subscribed to packed with received enricherId

  • enricherId: required (string)

    enricherId that will be used in checks. That means, you want to check why this enricher doesn't receive event.

  • schema: required (string)

    schema that will be used in checks. That means that you want to check why enricher doesn't receive event represented by this schema.

Headers

  • hybris-scopes: (string - pattern: ^([a-zA-Z0-9._=]{1,128}( [a-zA-Z0-9._=]{1,128})*)?$)

    List of scopes assigned for authenticated caller extracted from incoming request. The scopes are separated by a white space. Each scope will have a maximum length of 128 characters, and will typically will be in the form <team_id>.<service_name>_<scope>. This header might also be empty i.e. in case of anonymous user context. Please note that the scopes are case sensitive.

    Example:

    myTeam.myService_view myTeam.myService_manage
  • consent-reference: (string)

    consent-reference which is used to perform enricher checks

  • hybris-tenant: (string)

    enricher owner.

HTTP status code 200

Return report about enricher's status.

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "invocationParameters": {
      "type": "object",
      "properties": {
        "projectTenant": {
          "type": "string",
          "description": "tenant that will be used to perform checks, e.g whether tenant is subscribed to packed with received enricherId"
        },
        "teamTenant": {
          "type": "string",
          "description": "enricher owner."
        },
        "enricherId": {
          "type": "string",
          "description": "enricherId that will be used in checks. That means, you want to check why this enricher doesn't receive event."
        },
        "schema": {
          "type": "string",
          "description": "schema that will be used in checks. That means that you want to check why enricher doesn't receive event represented by this schema."
        },
        "consentReference": {
          "type": "string",
          "description": "consent-reference which is used to perform enricher checks"
        },
        "required": [
          "projectTenant",
          "teamTenant",
          "enricherId",
          "schema",
          "consentReference"
        ]
      }
    },
    "results": {
      "additionalProperties": {
        "type": "object",
        "properties": {
          "status": {
            "enum": [
              "OK",
              "FAILED",
              "SKIPPED",
              "INTERNAL_SERVER_ERROR"
            ],
            "type": "string",
            "description": "Status of verification"
          },
          "message": {
            "type": "string",
            "description": "Message describing result of check. For failing checks, it describes the reason of failure."
          },
          "details": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional information that can be attached to step section"
          }
        },
        "required": [
          "status"
        ]
      }
    },
    "required": [
      "invocationParameters",
      "results"
    ]
  }
}

Example:

{
  "invocationParameters": {
    "projectTenant": "profile",
    "teamTenant": "profile",
    "enricherId": "hybris.client",
    "schema": "node/superTeam/Product",
    "consentReference": "test-consent-reference"
  },
  "results": {
    "TRIGGERING_SCHEMA_TECHNICAL_PROPERTIES": {
      "status": "OK"
    },
    "SCHEMA_HAS_CORRECT_CONSENT": {
      "status": "OK"
    },
    "ENRICHER_IS_TRIGGERED_BY_SCHEMA": {
      "status": "OK"
    },
    "TENANT_SUBSCRIBED_TO_ENRICHER": {
      "status": "OK"
    },
    "CONSENT_REFERENCE_EXISTS": {
      "status": "OK"
    },
    "ENRICHER_IS_REGISTERED": {
      "status": "OK"
    },
    "ENRICHER_ID_FORMAT": {
      "status": "OK"
    }
  }
}

HTTP status code 403

At least one check during verification failed. Report is returned as in successful one.

Body

Type: application/json

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "invocationParameters": {
      "type": "object",
      "properties": {
        "projectTenant": {
          "type": "string",
          "description": "tenant that will be used to perform checks, e.g whether tenant is subscribed to packed with received enricherId"
        },
        "teamTenant": {
          "type": "string",
          "description": "enricher owner."
        },
        "enricherId": {
          "type": "string",
          "description": "enricherId that will be used in checks. That means, you want to check why this enricher doesn't receive event."
        },
        "schema": {
          "type": "string",
          "description": "schema that will be used in checks. That means that you want to check why enricher doesn't receive event represented by this schema."
        },
        "consentReference": {
          "type": "string",
          "description": "consent-reference which is used to perform enricher checks"
        },
        "required": [
          "projectTenant",
          "teamTenant",
          "enricherId",
          "schema",
          "consentReference"
        ]
      }
    },
    "results": {
      "additionalProperties": {
        "type": "object",
        "properties": {
          "status": {
            "enum": [
              "OK",
              "FAILED",
              "SKIPPED",
              "INTERNAL_SERVER_ERROR"
            ],
            "type": "string",
            "description": "Status of verification"
          },
          "message": {
            "type": "string",
            "description": "Message describing result of check. For failing checks, it describes the reason of failure."
          },
          "details": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional information that can be attached to step section"
          }
        },
        "required": [
          "status"
        ]
      }
    },
    "required": [
      "invocationParameters",
      "results"
    ]
  }
}

Example:

{
  "invocationParameters": {
    "projectTenant": "test",
    "teamTenant": "profile",
    "enricherId": "hybris.client",
    "schema": "yProfile/superTeam/Product",
    "consentReference": "test-consent-reference"
  },
  "results": {
    "TRIGGERING_SCHEMA_TECHNICAL_PROPERTIES": {
      "status": "OK"
    },
    "SCHEMA_HAS_CORRECT_CONSENT": {
      "message": "In Enricher Authorization Service, could not find encryption type of the schema https://api.beta.yaas.io/metamodel/v1/node/superTeam/Product.",
      "status": "FAILED"
    },
    "ENRICHER_IS_TRIGGERED_BY_SCHEMA": {
      "status": "OK"
    },
    "TENANT_SUBSCRIBED_TO_ENRICHER": {
      "message": "Tenant test is not subscribed to Enricher hybris.client - please subscribe to package which contain this enricher.",
      "status": "FAILED"
    },
    "CONSENT_REFERENCE_EXISTS": {
      "message": "Error calling consent service for url https://consent-service-v1.us-east.internal.yaas.io/test/consents/test-consent-reference. Got status 403",
      "status": "INTERNAL_SERVER_ERROR"
    },
    "ENRICHER_IS_REGISTERED": {
      "status": "OK"
    },
    "ENRICHER_ID_FORMAT": {
      "status": "OK"
    }
  }
}

HTTP status code 500

Unexpected error occurred

Profile Troubleshooting

This document explains what to check in case of events not received by the enricher.

In documentation for Enricher configuration checks we use two tenant values. One corresponds to an enricher owner, this value is set up automatically based on your Bearer Access_token. Other tenant corresponds to data owner, tenant who wants to use your enricher.

Manual check

At the moment if your enricher does not receive any events, please manually check builder to eliminate any inaccuracy in builder module.

EnricherId is registered in builder

Check default.properties file from your local Enricher project and see if proper tenant value is set. Next from Builder click on your Team name and from your service check YaaS Client field. Value should be identical to the one from default.properties file.

If Enricher with given EnricherId is not registered, please see Enricher registration tutorial.

Hybris-tenant subscribes yprofile core package

Please make sure that hybris-tenant is subscribed to yprofile core package.

For more detail on how to subscribe to the service packages click here.

projectTenant is subscribed to package which contains EnricherId

Please check with Enricher Authorization service API console if projectTenant is subscribed to your enricher. You can also execute:

curl -X GET -H "Authorization: Bearer Access_token" 'https://api.beta.yaas.io/hybris/profile-enr-auth/v1/enrichers/{enricherId}/{version}'

This will tell you which tenants are subscribed to your enricher.

Enricher owner (hybris-tenant) is registered to events package

Please verify in Builder if you are registered to events package. Under your team go to Subscriptions section and verify if events package is listed there.

If not, please subscribe to Events Package.

Introduction to tutorial

The Heart Beat service tutorial describes in detail how to perform both automatic and manual checks of your service.

Prerequisites

  1. Valid Bearer Access_token
    For details on how to receive an access token, see the documentation for the /token endpoint of the OAuth2 service.

Enricher configuration checks

Configuration checks validate whether your service is set up properly. The steps in this topic describe how to check why an enricher is not triggered by a given schema.

Before you start your checks, it is highly recommended that you familiarize yourself with the Enricher registration tutorial.

In documentation for Enricher configuration checks, we use two tenant values. One corresponds to an enricher owner. This value is set up automatically based on your Bearer Access_token. The other tenant value corresponds to the data owner, or the tenant who wants to use your enricher.

Checks

Checks are automatic, but some manual verification steps are required. See the Run configuration checks section.

Configuration checks use the following "check keys." Click on the link for any check key to view more details about the check key and what to do when a check fails.

  1. ENRICHER_ID_FORMAT - checks whether the EnricherId is properly formatted
  2. ENRICHER_IS_REGISTERED - checks whether an enricher with a given EnricherId is registered in SAP Hybris Profile
  3. TENANT_ASSIGNED_TO_ENRICHER - checks whether the projectTenant is subscribed to a package with an enricher of the given EnricherId
  4. ENRICHER_IS_TRIGGERED_BY_SCHEMA - checks whether the enricher has a proper triggering schema
  5. TRIGGERING_SCHEMA_TECHNICAL_PROPERTIES - checks whether a triggering technical schema exists in the metamodel
  6. CONSENT_REFERENCE_EXISTS - checks whether a consent reference exists
  7. SCHEMA_HAS_CORRECT_CONSENT - checks whether a consent reference contains consent for a given triggering schema

A check can return any of these statuses:

  1. OK means the check was successful.
  2. FAILED means something went wrong. Use the "check key" links in the previous topic to navigate to the failed check.
  3. SKIP means a check can't be performed because of the failure of one or more other checks. See the rest of the results and correct the configuration.
  4. Internal Error indicates you should run the enricher configuration checks again. If the issue recurs, create a support ticket for the administrator. Click here for more details.

Run configuration checks

To start your enricher configuration checks, execute the following command:

curl -X GET -H "Authorization: bearer Access_token" -H "consent-reference: {consent-reference}"'https://api.beta.yaas.io/hybris/profile-heartbeat/v1/status/{projectTenant}/{enricherId}/triggeredBy/{schema}'

Command parameters

  1. HEADERS
    • Authorization: Provide a valid Bearer Access_token.
    • consent-reference: Provide a consent-reference.
      For information about how to generate a consent reference, see the Creating a consent reference tutorial.
  2. URI parameters
    • {projectTenant}: Provide the name of a tenant that is subscribed to the enricher.
    • {enricherId}: Provide the enricher ID you want to check.
    • {schema}: Provide the enricher's triggering schema.
      For more details about schemas, see the Schema parts document.

Example of a GET request with real data

curl -X GET -H "Authorization: Bearer 001-fa77890a-5d85-4b92-b29a-62ed8d469384" -H "consent-reference: baa8a056-8b71-417e-9ad6-1c5069c66096"'https://api.beta.yaas.io/hybris/profile-heartbeat/v1/status/mycomicsshop/comicbookview/triggeredBy/context/comics/seeComicBook'

ENRICHER_ID_FORMAT

Use ENRICHER_ID_FORMAT to check whether the EnricherId is formatted properly and conforms to the naming convention.

ENRICHER_ID_FORMAT = Failed

If the ENRICHER_ID_FORMAT check fails, verify that you have the correct EnricherId and that the EnricherId meets the naming requirements.

If you created your enricher from the Jersey Archetype, go to your enricher project folder and find the default.properties file. It should be located in project's folder /src/main/resources.

  1. Locate the line enricher.hybris.client and make sure it has the same value as the YaaS Client field in the Builder.
  2. Correct name in the enricher.hybris.client line, if necessary.
  3. Run the configuration checks again.

ENRICHER_IS_REGISTERED

Use ENRICHER_IS_REGISTRERED to check whether an enricher with the given EnricherId is registered in yProfile.

ENRICHER_IS_REGISTERED = FAILED

If the ENRICHER_IS_REGISTERED check fails, check the verified Enricher. If the EnricherId is not registered in yProfile, you must register it in yProfile.

For more details about how to register an Enricher, see the Enricher registration tutorial.

TENANT_ASSIGNED_TO_ENRICHER

TENANT_ASSIGNED_TO_ENRICHER checks whether the projectTenant is subscribed to a package with an enricher of the given EnricherId.

TENANT_ASSIGNED_TO_ENRICHER = FAILED

If the TENANT_ASSIGNED_TO_ENRICHER check fails, check the verified enricher. If the projectTenant is not subscribed to a package with an enricher of the given EnricherId, contact and advise the projectTenant to subscribe to the package with your enricher.

ENRICHER_IS_TRIGGERED_BY_SCHEMA

ENRICHER_IS_TRIGGERED_BY_SCHEMA checks whether the triggering schema defined for a given enricher exists in the metamodel and triggers that enricher.

For more details about schemas, see the Find useful data for enricher registration section.

ENRICHER_IS_TRIGGERED_BY_SCHEMA = FAILED

If the ENRICHER_IS_TRIGGERED_BY_SCHEMA check fails, check the verified enricher and ensure that the triggering schema is properly configured to trigger it. See the Enricher registration tutorial for more details.

TRIGGERING_SCHEMA_TECHNICAL_PROPERTIES

If the triggering schema consists of nodes or a relationship schema (for example, /nodes/commerce/Product or /relations/commerce/Session/commerce/BrowserType/HAS), the TRIGGERING_SCHEMA_TECHNICAL_PROPERTIES check endpoint verifies whether the given schema has the correct technical properties. If the given schema is property-related (for example, /nodes/commerce/Product/id), the mechanism tries to verify the technical schema against the parent of the node or relation's property schema.

TRIGGERING_SCHEMA_TECHNICAL_PROPERTIES = FAILED

If the TRIGGERING_SCHEMA_TECHNICAL_PROPERTIES check fails, it means one or more technical schemas does not exist in the metamodel. When this happens, create a support ticket for the administrator. Click here for more details.

CONSENT_REFERENCE_EXISTS verifies whether the consent-reference exists.

If the CONSENT_REFERENCE_EXISTS check fails, the consent reference likely does not exist. Verify that the consent reference does not exist, then generate a new consent reference, and try the check again.

For more details on how to generate a consent reference, see the Creating a consent reference tutorial.

SCHEMA_HAS_CORRECT_CONSENT checks the consent reference to verify whether the triggering schema has granted consent.

If the SCHEMA_HAS_CORRECT_CONSENT check fails, verify a given consent reference. The consents could be revoked for the defined schema. In this case, advise the consent reference owner to grant consents for that schema.

For more details on how to grant consents, see the Grant a single consent tutorial.

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/write age estimation or physical address. A consumer and a tenant can grant and revoke consent for subsets of their respective data.
consent classA 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 referenceA unique, randomized string that serves as a passcode to decrypt data associated with one or more schemas. Various service calls require a consent reference.
consumerThe end user whose actions yield profile data in the graph. A profile describes a single consumer.
contextData 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 AdapterA 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 repositoryA temporary cache for adapted context data, before it is further processed by enrichers and persisted in the graph.
context serviceAn internal microservice that manages the insertion of, and the retrieval of, context data in the Context Repository.
encryption keyA 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.
enricherA 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.
graphThe database that stores profile data as nodes, edges, and properties, and allows semantic queries.
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 are triggered by, or are logically associated, with that consumer.
schemaA string representation of a path in the graph that represents an abstraction, rather than a concrete instance, of a particular data structure.
tenantA 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.

  • 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.