Service Description
Usage
In the setup phase of the Service Delivery process, the Fidesmo App receives a data structure containing information about the service to be delivered. This data structure is defined by the Service Provider, and can be served in two different ways:
- It can be stored at the Fidesmo Server, provisioned by the Service Provider as a Service Recipe.
- It can be sent “on the fly” by the Service Provider servers.
Whenever a mobile app requests a service, the Fidesmo App queries the Fidesmo Server for the service description, since the mobile phone is not considered a fully trusted environment. If the Fidesmo Server cannot provide that information itself (that would be the first case above), it contacts the Service Provider with a Service Description Request as described in the Fidesmo API.
Structure
The service description is composed of the following fields:
| Field | Type | Mandatory? | Example | Explanation |
|---|---|---|---|---|
| title | Multilanguage String | Mandatory | {“en”: “The Secret Service”, “es”: “El Servicio Secreto”}, |
The title is used to inform the end user about the service to be delivered. It should be short and exact, much like the product title in a web shop. Information about who is providing the service is given automatically by Fidesmo so it should not be provided here, i.e. don’t return “Monthly pass from Service Provider XYZ”. It is a multilanguage string, so the user will read the description in his/her phone’s language. |
| description | Multilanguage String, allowing markdown | Optional | {“en”: “This is a service so **secret** that we cannot tell you what it does”, “es”: “Este es un servicio tan **secreto** que no podemos decirte qué hace”} |
A short description of the service. It is also a multilanguage script, and it may contain basic markdown elements like bold, emphasis or links. |
| confirmationRequired | Boolean | Optional | true | If ‘true’, the Fidesmo App will display a confirmation screen so the user can accept the service delivery. If ‘false’, the confirmation screen will only be displayed if the service has a price. The default value (if not sent) is ‘false’. |
| fieldsRequired | Form defined as a list of fields. Each of them can be specified as follows: label: multilanguage string id: string type: the same field types used in UserInteraction, please see the detail description here. format: please see the User Interaction page. |
Optional | l”: {“en”: “Place of birth”, “es”: “Lugar de nacimiento”}, “id”: “birthplace”, “type”: “edit”}, {“label”: {“en”: “Date of birth”, “es”: “Fecha de nacimiento”}, “id”: “birthdate”, “type”: “date”}] |
Form built as a list of fields to gather any information from the user. The Service Provider can define the label, identifier and data type of each of them to gather data different from any of the predefined fields. See
the User Interaction page |
A full JSON example:
{
"title": {"en": "The Secret Service",
"es": "El Servicio Secreto"},
"description": {"en": "This is a service so **secret** that we cannot tell you what it does",
"es": "Este es un servicio tan **secreto** que no podemos decirte qué hace"},
"confirmationRequired": true,
"fieldsRequired": [{"label": {"en": "Place of birth", "es": "Lugar de nacimiento"},
"id": "birthplace",
"type": "edit"},
{"label": {"en": "Date of birth", "es": "Fecha de nacimiento"},
"id": "birthdate",
"type": "date"}],
}
The parameters of the Service Description used in the example would now be visible in a client:
- service title
- description, showing some markdown
A number of branding elements also appear on the image: the Feature Graphic on top, the logo on the left, and the Application Name under the service title.
Showing progress
Service delivery can be a very short process or a long one, depending on server-to-server interactions, loading and installing large applets on the secure element and other operations.
It is important to display the right information to end users, so they have accurate information about the status of the delivery process, and how long they are supposed to wait.
We have defined a rich set of metadata elements so that any touch point displaying a User Interface has enough information to display the process state. Progress is a structure, composed of the four fields below, which is sent as an optional parameter in API operations. It is composed of:
- Current step: informs the client of the point reached in delivering the service. If
progressis sent, this field is mandatory. - Total Steps: The total number of steps of the service delivery. Since during the delivery process it may change, the Service Provider needs to send the most up-to-date information has to be sent if the
progressstructure is used. - Message: It is possible to suggest the UI the message to be displayed during each step, e.g “Personalizing application”, “Downloading data”, etc. The message is sent as an optional multi-language string.
- Estimated duration: Time, in seconds, that the operation will take. It is also optional.
Example:
Let us configure an Access Control service that will store some access credentials in a Fidesmo-enabled device. The expected flow will have the following operations:
- Check if the applet storing the credentials is installed already
- If not, load and install the applet
- Obtain data from the user so the server can generate the new credentials
- Store the new credentials in the applet
- Activate the new credentials
Each API call will then provide the following progress information:
| Step | Total number of steps | Current step | Message | Estimated duration |
|---|---|---|---|---|
| Check if applet already stored | 5 | 1 | Checking if application exists | 1 |
| Load and install applet | 5 | 2 | Installing application… | 10 |
| Obtain data from user | 5 | 3 | Showing form | 5 |
| Personalize applet | 5 | 4 | Storing new credentials | 3 |
| Activate the new credentials | 5 | 5 | Activating new credentials | 2 |
If the Service Provider had detected that the applet was already installed, the Total number of steps for steps 3,4 and 5 would change to “4”, because step 2 would have been skipped.
