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, or if the Terms and Conditions URL is set. The default value (if not sent) is 'false'.
bankIdRequired Boolean Optional
true
If ‘true’, the Fidesmo App will request the user to authenticate with his/her BankId, the leading electronic identification system in Sweden. The authentication token will then be forwarded to the Service Provider. The default value (if not sent) is 'false'.
emailRequired Multilanguage String Optional
{"en": "We need your email to send you flowers",
 "es": "Necesitamos tu email para enviarte flores"}
If present, the user will be asked to enter his/her email address, which will be forwarded to the Service Provider. The multilanguage string shall explain the reason to request the email.
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. They are: "text", "edit", "date", "checkbox", "paymentcard", "option".
  • format: for types option and edit it is possible to specify the input format: radio buttons or buttons for option and text or number for edit.
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.
termsAndConditions URL Optional
http://myservice.com/terms
Provides a link to the Service Provider's Terms and Conditions on the confirmation screen.
totalSteps Integer Optional 6 Information that client software implementing a User Interface can use to show an accurate progress bar. See the Showing progress section at the end of this 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,
  "bankIdRequired": true,
  "emailRequired": {"en": "We need your email to send you flowers",
                    "es": "Necesitamos tu email para enviarte flores"},
  "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"}],
  "termsAndConditions": "http://myservice.com/fidesmo",
  "totalSteps": 6
}
        

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 link to the Service Provider's Terms and Conditions

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:

  • Total number of steps: sent in the totalSteps parameter of the Service Description (see above), it informs the UI client of the discrete steps that can be expected during a normal service delivery process.
  • Progress: this 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: During the delivery process, the total estimated number of steps may change. This 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

Since the service will be delivered in 5 steps, its Service Description will contain "totalSteps": 5. 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.