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 |