Getting Started

This section walkes you through the steps required to setup linker services and document types on datalinker. Apart from this, you will get to know the details of datalinker such as the different types of linker services and how to efficiently encrypt your documents for a maximum of privacy.

Creating a user account

This guide shows you how to register for datalinker.

  1. Open the datalinker console in a new browser window.
  2. The home page shows links to the documentation. Documentation will follow in the future, as well as news about new features and the contact form. Use developer@datalinker.io for any questions or requests for now.
_images/home.png
  1. Click on “Account”, then “Register” to open the registration page.
_images/registration.png
  1. After creating your user account, you will receive an e-mail to verify your e-mail address.
  2. Finally, you can login using your login name and password.
_images/login.png

Note

We are currently working on our backend infrastructure. This means that the datalinker console may sometimes feel a bit slow. This should improve over time as we are learning how much load our servers need to support.

Creating an organization

This guide shows you how to create your first organization.

  1. Login to your datalinker account in the datalinker console.
  2. Click on Entities and then on Organization.
_images/no_organizations.png
  1. Click on Create a new Organization.
  2. In the dialog, you can specify all the properties of your organization. Let’s look at them one by one:
    • The organization ID is used to reference the organization on datalinker. Use a reversed URL-style format such as com.myorg. The organization ID can not be changed. Please contact us if you made a mistake and need to have it changed.
    • The name will be displayed in the datalinker console and potentially to your users.
    • You may add a logo for your organization. Select a JPEG or PNG file.
    • The description can help potential other users of datalinker to discover your organization to share data.
    • The URL should point to your website and include the leading protocol (http or better https).
    • Type the e-mail address of another datalinker user to give her or him access to your organization. This is not required for sharing data so better only add people from your organization.
    • By default, you’re the only user of your organization. If there are more, you can remove them by selecting them. You can’t remove yourself however, even if there are other users in the list.
_images/new_organization.png
  1. Click the save button to persist your changes.
_images/my_organization.png

Creating a linker service

Let’s quickly digress into the operation modes of datalinker before we’re prepared to create our first linker service. Linker services are the entities between which data is shared. This means we have linker services for sending and for receiving data. As you learned in the Overview, you need one of each to send data on datalinker. What we didn’t tell you is that there are three kinds of receiving linker services. They cover the following use cases.

Sending data once

The datalinker web app is an example of a so called AD_HOC_RECEIVER. This means it is used to send data once. To do so, the datalinker web app will create a new linker session when you open the web page. It shows you the ID of this session along with a randomly created AES128 key as a QR code. You can then scan this code, encrypt your documents and send them to this linker session. After you finish, you close the linker session. datalinker web app will then decrypt the data in the browser and display it. When you close the browser window, the datalinker web app will forget everything and the data transfer is complete.

Attention

Using symmetric encryption such as AES128 for AD_HOC_RECEIVER services is convenient and fast. However, it also means that if one of the clients (the web app or the app) become compromised, the attacker can use the key to decrypt all data. This is the reason you may not use AD_HOC_RECEIVER services if you plan yo reuse the linker session.

Sending data continuously

If you want to keep sending data to the same linker session continuously, for example to share your health data with your doctor, you should use a RECEIVER_INITIATED_RECEIVER service. While this sounds complicated, it really just means that this receiver will create its own linker sessions. In this case, the client of the receiving linker service must provide a public key to datalinker. After creating the session, it should show a QR code containing the session ID and a fingerprint of the QR code. The client of the sending service then scans the QR code, retrieves the public key from the service and verifies it using the fingerprint. It should then create a random AES128 key to encrypt the data. The AES key is encrypted with the public key and added as a parameter to each document.

Note

You are free to decide how often you want to use a fresh AES key. It is a good idea to change it often, for example every time every time a user sends a bunch of documents.

Sending data anonymously

There is a third operation mode and this is where the fourth linker service type comes in: SENDER_INITIATED_RECEIVER. Again, this linker service type is used for continuous data transfer. In contrast to RECEIVER_INITIATED_RECEIVER services, the public key is configured on the linker service and shared by all clients of this receiving linker service. In this operation mode, the sender creates the linker session. It will not verify the authenticity of the public key. Apart from this, the sender encrypts the documents as it would for a RECEIVER_INITIATED_RECEIVER.

Note

datalinker analytics is an example of a SENDER_INITIATED_RECEIVER service. This means the sender can start sending data without any interaction with the receiver service. Use this linker service type only if the user of an app for example will not explicitly opt-in to a service.

Creating a sender linker service

Now, you know everything needed to go forward and create your first linker service.

  1. Login to your datalinker account in the datalinker console.

  2. Click on Entities and then on Linker Service.

  3. Click on Create a new Linker Service.

  4. In the dialog, you can specify all the properties of your linker service. Let’s look at them one by one:

    • Select your organization from the list.
    • The service ID is used to specify the linker service in the clients. Use a reversed URL-style format such as com.myorg.sender. The service ID can not be changed. Please contact us if you made a mistake and need to have it changed.
    • The name will be displayed in the datalinker console and potentially to your users.
    • You may add a logo for your linker service. Select a JPEG or PNG file.
    • The description can help potential other users of datalinker to discover your linker service to recceive data from.
    • The URL should point to your service’s (e. g. app) website and include the leading protocol (http or better https).
    • Select Sender as your linker service type.
    • Linker services can be active. This should only be activated once your linker service is ready for production. Don’t check it now. Once active, this cannot be undone. Please contact us if you made a mistake and need to have it changed.
    • Active linker services can be marked as public. This makes a service visible to users of other organizations to enable cross-organizational data exchange. This cannot be undone in order to prevent breaking existing setups.
_images/new_sender_service.png
  1. Click the save button to persist your changes.

Creating an ad-hoc linker service

Before you can receive data, you need to create a receiver service. We will create an AD_HOC_RECEIVER service now. If you want to create another service type, feel free to skip this section.

  1. Login to your datalinker account in the datalinker console.

  2. Click on Entities and then on Linker Service.

  3. Click on Create a new Linker Service.

  4. In the dialog, you can specify all the properties of your linker service. Let’s look at them one by one:

    • Specify the organization, service ID and logo similar to creating a sender linker service.
    • The name will be shown to users that may want to use your service.
    • The description will be shown to users that may want to use your service.
    • The URL will be shown to users that may want to use your service.
    • Select Ad-hoc receiver as your linker service type.
    • Linker services can be active. This should only be activated once your linker service is ready for production. Don’t check it now. Once active, this cannot be undone. Please contact us if you made a mistake and need to have it changed.
    • Active linker services can be marked as public. This makes a service visible to users of other organizations to enable cross-organizational data exchange. This cannot be undone in order to prevent breaking existing setups.

Note

Currently, linker services that are not public are visible only to clients of sender services of the same organization. This will change in an upcoming release. We will introduce white lists for services, where you can add all receiver services compatible with your sender service. Public services can then be discovered by users of other organizations to be added to their whitelist. Contact us if you are unsure about how to setup your specific requirements.

  1. Click the save button to persist your changes.
_images/my_two_services.png

Creating a document type

We now have two services setup and need to create a document type.

  1. Login to your datalinker account in the datalinker console.

  2. Click on Entities and then on Document Type.

  3. Click on Create a new Document Type.

  4. In the dialog, you can specify all the properties of your document type. Let’s look at them one by one:

    • Select your organization from the list.
    • The document type ID is used to specify the document type in the document. Use a reversed URL-style format such as com.myorg.my-document-type. The document type ID can not be changed. Please contact us if you made a mistake and need to have it changed.
    • The name will be displayed in the datalinker console and potentially to other users of datalinker.
    • The description will be displayed in the datalinker console and potentially to other users of datalinker.
    • Document types can be active. This should only be activated once your document type is ready for production. Don’t check it now. Once active, this cannot be undone and the document type can no longer be changed.
    • Active document types can be marked as public. This makes a document type visible to users of other organizations to enable cross-organizational data exchange. This cannot be undone in order to prevent breaking existing setups.
    • The mapping field may contain information about how receivers should process or render the document type. This is required if you are sending documents to the datalinker web app. We will leave it blank for now
  5. Click the save button to persist your changes.

_images/new_document_type.png

Creating a client

As explained earlier, clients are the instances of linker services. This could be an app that uses a sender service or a simple script for a receiver services that retrieves documents and stores them in your database. We will not create a client in this example but will quickly cover the available properties.

  1. Login to your datalinker account in the datalinker console.

  2. Click on Entities and then on Client.

  3. Click on Create a new Client.

  4. In the dialog, you can specify the properties of your client:

    • Clients authenticate using a password. Use a strong password as clients are usually software applications or scripts that log in autonomously.
    • Clients belong to a specific linker service.
    • If you specify a client for a RECEIVER_INITIATED_RECEIVER service, you also have to provide a public key.
  5. Click the cancel button.

_images/new_empty_client.png

Creating a linker session

Linker sessions are connections between to services and may contain documents. We will not create a linker session in this example but will quickly cover the available properties.

  1. Login to your datalinker account in the datalinker console.

  2. Click on Entities and then on Linker Session.

  3. Click on Create a new Linker Session.

  4. In the dialog, you can specify the properties of your document:

    • The parameter field may contain a chunk of JSON. You can use it to store any information that should not be encrypted.
    • If you are creating a linker session as a sending client, select the client from the From Client list. The second dropdown will now change to show all available SENDER_INITIATED_RECEIVER services.
    • If you are creating a linker session as a receiving client (beloging to an AD_HOC_RECEIVER or RECEIVER_INITIATED_RECEIVER), select the client from the To Client list. The first dropdown will now disappear.
  5. Click the cancel button.

Note

When creating a linker session from a sending client, you can only specify the receiver service. All clients belonging to this receiver service can retrieve documents. In this case, the sending client will use the public key specified in the SENDER_INITIATED_RECEIVER service for encrypting documents. When creating a linker session from a receiving client, the linker session is only partially initialized. As a next step, you can edit the linker session and specify a sending client. The reason is that in practice, the recieving service will not know which client will connect to the linker session when creating the linker session.

_images/new_empty_session.png

Creating a document

Documents are the objects that actually contain your data. We will not create a document in this example but will quickly cover the available properties.

  1. Login to your datalinker account in the datalinker console.

  2. Click on Entities and then on Document.

  3. Click on Create a new Document.

  4. In the dialog, you can specify the properties of your document:

    • The parameter field may contain a chunk of JSON. This is used for example to store the encrypted AES128 key and the associated initialization vector. Don’t worry if you don’t know what this is, we will create that later.
    • Data holds the encrypted data.
    • Documents belong to a specific linker session.
    • Specify the document type for the document you want to create.
  5. Click the cancel button.

_images/new_empty_document.png

Submitting a bug report

If you think you’ve found a bug, please contact us at developer@datalinker.io. Please include the version of the datalinker console as displayed on the bottom right. It has the format 1.1.0 (169). We appreciate it and will hunt it down as soon as possible.

Note

datalinker is being worked on actively. So if you detect some unexpected behavior, don’t hesitate to shoot us an e-mail immediately.