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: Optional
          			[{"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"}]
          		
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 for details.

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 confirmation screen generated by the example above will look as this screenshot:

We can see some of the parameters of the Service Description used as example:

  • 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. They are described in the Branding page.

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 client software displaying a User Interface (such as the Fidesmo app) 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 progress is 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 progress structure 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:

  1. Check if the applet storing the credentials is installed already
  2. If not, load and install the applet
  3. Obtain data from the user so the server can generate the new credentials
  4. Store the new credentials in the applet
  5. 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.