Understanding HMI

Hat Microserver Instructions

Reading or writing any data to those newly provisioned PDAs must be permitted by the user. In case one application requires data access to a namespace, it has to explicitly request permission from the user.

This mechanism of asking permission from the user is called a HAT Microserver Instructions (HMI). It forms a legally binding contract between you and your user. In particular, you are requesting data from user's PDA, through a data debit. DataSwift will ensure that the HMI, for your application, is shown and confirmed immediately after creating user’s PDA within your application, so you can then freely write and read from the PDA without creating any further additional burden for the user.

All applications, by default, have read and write access to the specified namespace. If you wish to access other data within the PDA but not within your namespace, an additional data debit/HMI would need to be confirmed with the user.

Different HMI Variants

There are two different services that you can use:

  • BaaS (Backend As A Service)

  • DaaS (Data As A Service)

Since these 2 services issue PDAs differently, there are some discrepancies in the HMI screens that the users will have to accept. Please note that in order for users to use your application, they have to agree to the HMI screen, regardless if the application is using BaaS or DaaS.

HMI with BaaS

There are 2 versions of the HMI screen of a new PDA using Baas:

  • Simple HMI

  • HMI with Data debit

The main difference is that the second HMI screen has a data debit embedded. This HMI screen will be used for the cases where the application does not require access to a different namespace, or a data debit. In case the app requires access to a different namespace, or includes a data debit, the following screen will be shown to the user.

HMI with DaaS

For applications using DaaS there is only one HMI screen.

Backend as a Service - BaaS

PDA creation gets automatically initialised with the supplied email address and autogenerated password

Once the PDA is up and running (2-3 seconds), the user gets automatically logged in and presented with the HMI Screen. HMI is the HAT Microserver Instructions that the PDA owner issues and represents the legal contract between the PDA owner and the application in order to enable the application to interact with the PDA.

Once HMI is confirmed, the user gets redirected through the OAuth process of each data plug provider (eg facebook) in order to setup data plug access into the PDA, if the data plug have not yet been set up. If it has been set up, only the application’s permissions would be required

Upon finishing data access setup for all required providers, the user will be redirected back to the redirect_uri

Instructions for Single Screen PDA creation

To create a PDA with BaaS collect user's email address and PDA username.

  1. Your web or mobile application collects the email address and PDA username of the user with precautionary measures against spam bots

  2. In order to register users via baas, the application or webpage needs to redirect users to the following URL:

    https://hatters.dataswift.io/services/baas/signup

    With the following query parameters:

    "hat_name"
    "email"
    "application_id"
    "redirect_uri"

    Please use the value of ​application ID​ in the kit summary to test

  3. The user is presented with the HMI Screen. The HMI is the legal contract between the PDA owner and the application to enable the application to interact with his/her PDA.

  4. The user will be redirected back to the callback URL from step 2 after accepting the HMI screen

  5. In case signup is successful the user will be redirected back to your application with query parameter token, the application token for that user. In case signup fails at any stage of the process, the user will be redirected back to your application with query parameters error and error_reason. It is left up to each individual application to decide how the failures should be communicated to the user. Currently error field will always have the value hat_provisioning. The error_reason field can have multiple values depending on the failure type:

    • out_of_capacity

    • duplicate_email

    • invalid_submission_data

    • user_cancelled

    • uncaught_error

  6. The token is generated using JWT standard and it carries additional information about the issuer, application and

    expiration date. The issuer parameter can be used to extract the domain name of the PDA.

Access data debit values

The data itself can be retrieved from the data debit endpoint on that PDA, the request details are documented here:

https://documenter.getpostman.com/view/110376/S1EH4ha8?version=latest#d04abe75-2a9f-429c-98b5-381a39498cbc

Note that HAT domain name will be different for each user and needs to be adjusted based on information encoded in the token. The token itself is used for authenticating the request and should be passed as a “X-Auth-Token” header.

https://{{userHatDomain}}/api/v2.6/data-debit/app-{{applicationId}}/values

Data as a Service - DaaS

PDA creation gets automatically initialised with the supplied email address and autogenerated password.

Once the PDA is up and running (2-3 seconds), the user gets automatically logged in and presented with the HMI Screen. The HMI is the legal contract between the PDA owner and the application in order to enable the application to interact with the PDA.

Once the HMI is confirmed, the user gets redirected through the OAuth process of each data plug provider (eg. facebook) in order to setup data plug access into the PDA, if the data plug have not yet been set up. If it has been set up, only the application’s permissions would be required.

Upon finishing data access setup for all required providers, the user will be redirected back to the redirect_uri

Instructions for Single Screen PDA creation

To create a PDA with DaaS collect the user's email address.

  1. Your web or mobile application collects the email address of the user with precautionary measures against spam bots

  2. To register users via daas, the application or webpage needs to redirect users to the following URL:

    https://hatters.dataswift.io/services/daas/signup

    With the following query parameters:

    "email"
    "application_id"
    "redirect_uri"

    Please use the value of application ID​ in the kit summary to test

  3. PDA creation gets automatically initialised with the supplied email address and autogenerated password

  4. Once the PDA is up and running (2-3 seconds), the user gets automatically logged in and presented with the HMI Screen. The HMI is the legal contract between the PDA owner and the application to enable the application to interact with his/her PDA.

  5. Once HMI is confirmed, the user gets redirected through the OAuth process of each data plug provider (eg facebook) to setup data plug access into the PDA if the data plug have not yet been set up — if it has been set up, only the application’s permissions would be required

  6. Upon finishing data access setup for all required providers, the user will be redirected back to the callback URL from step 2

  7. In case signup is successful the user will be redirected back to your application with query parameter token, the application token for that user.

In case signup fails at any stage of the process, the user will be redirected back to your application with query parameters error and error_reason. It is left up to each individual application to decide how the failures should be communicated to the user. Currently error field will always have the value hat_provisioning. The error_reason field can have multiple values depending on the failure type:

  • out_of_capacity

  • duplicate_email

  • invalid_submission_data

  • user_cancelled

  • uncaught_error

    1. The token is generated using JWT standard and it carries additional information about the issuer, application and

      expiration date. The issuer parameter can be used to extract the domain name of the PDA.

    2. The data itself can be retrieved from the data debit endpoint on the PDA (the request details are documented under "Get Data Debit Values" on the API documentation site.

      Note that PDA domain name will be different for each user and needs to be adjusted based on information encoded in the
      token.

      The token itself is used for authenticating the request and should be passed as a x-auth-token header.

      https://{{userHatDomain}}/api/v2.6/data-debit/app-{{applicationId}}/values

      Please use the value of A​application ID​ in the kit summary. The PDA owner will receive an email for him/her to claim his PDA within 7 days and a further email at the end of 7 days to inform him that the PDA will be deleted if unclaimed.

    3. If the PDA owner claims his/her PDA, they will be prompted to change the password and set up the PDA in accordance with Dataswift platform guidelines.

    4. In case signup fails at any stage of the process, the user will be redirected back to your application with query parameters “error” and “error_reason”. It is left up to each individual application to decide how the failures should be communicated to the user. Currently “error” field will always have the value “hat_provisioning”. The “error_reason” field can have multiple values depending on the failure type: “out_of_capacity”, “duplicate_email”, “invalid_submission_data”, “user_cancelled” and “uncaught_error”.