FeaturePreviews API

Scope of functions of the FeaturePreviews app

The FeaturePreviews app combines feature previews from other apps to provide an overview for technical administrators. The other apps must provide the feature previews in order to be queried by the FeaturePreviews app.

What are feature previews in the context of the FeaturePreviews app?

Feature previews are functions that are permanently activated compulsorily and therefore become a part of the normal scope of functions of the application. However, for a specific transition period, the technical administrator has the option of activating or deactivating the functions. For example, the following application scenarios are conceivable:

• A feature (e.g. a new user interface) changes how the software is used, which means that users first have to familiarize themselves with the new operating method or require training.
• A feature is not fully finished yet, but has to be given to the customer in advance so that they can test the new function.

Using the API functions

Below, you can learn how to use the programming interface of the FeaturePreviews app for your own developments. The FeaturePreviews app communicates with other apps via an interface that queries the respective feature previews. You can find information about how you have to structure this interface in the section Providing a feature preview.

Providing a feature preview

You can use this function to display feature previews together in the FeaturePreviews app. To provide feature previews, you must provide a featuretoggles link relation.

Get feature previews

The FeaturePreviews app queries all the registered apps. Each registered app is then queried with the call /<app name>/ at the base address (i.e.: https://<your base address>/<app name>/) and the request header "Accept: application/hal+json". The link relation featuretoggles is searched for. To find the link relation, the JSON must be structured as follows:

{
    "_links" : {
        ...
        "featuretoggles": {
            "href": "/<app name>/featuretoggles"
        }
        ...
    },
    ...
}

If a correctly structured link relation is available, the URI specified under it is called in the user context with the request method GET and the request header "Accept: application/hal+json" and the received JSON object is evaluated. The JSON responsible for staging apps to provide one or more feature previews must be structured based on the following schema:

{
    "featureToggles": [
        {
            "id": "<id of your feature toggle>",
            "context": "<context of your feature toggle>",
            "caption": "<caption of your feature toggle>",
            "description": "<description of your feature toggle>",
            "callbackUrl": "<callback url>",
            "tenantActivated": <state of your feature toggle>,
            "expiration": "<expiration of your feature toggle>",
            "feedbackMailAddress": "<feedback mail address>",
            "iconUrl": "<link to your icon>"
        }
    ]
}

Property	Type	Description	Required	Comment
id	string	Unique identifier for the feature preview.	Yes	Unique in relation to the context.
context	string	Used in the user interface to group feature previews. For instance, all d.velop inbound suite feature previews could use the context "d.velop inbound suite" and are then displayed grouped together.	Yes
caption	string	Localized header for the feature preview.	Yes
description	string	Localized description of the feature preview.	Yes	May contain links
callbackUrl	string	Callback that is called in the user context if the feature is activated or deactivated.	Yes	Relative URL
tenantActivated	bool	Indicates whether the feature preview for the current client is activated or deactivated.	Yes	The respective apps are responsible for data storage
expiration	string	Date on which the feature preview is expected to switch to the standard scope of functions.	Yes	ISO 8601-formatted string
iconUrl	string	URL for displaying an icon.	No
feedbackMailAddress	string	E-mail address that the user (technical administrator) can use to provide feedback about a feature to the app builder.	No

Receiving a callback

If a feature preview is activated or deactivated by the technical administrator, the FeaturePreviews app calls the URL defined in the callbackUrl property for this feature preview. The POST request in JSON format is executed in the user context. The request is structured as follows:

{
  "id": "<id of your feature toggle>",
  "tenantActivated": <state of your feature toggle>
}

Property	Type	Description
id	string	Unique identifier for the feature preview
tenantActivated	bool	Specification for the changed feature preview status