Getting started

This developer portal guides organisations in joining the DSGO. The intended audience of this portal are developers, architects, or product owners responsible for the technical implementation. The information on this portal has been gathered from multiple sources to provide you with a clear overview of the required steps to implement the DSGO.

Under construction

The DSGO developer portal is still under construction. Do you have suggestions to improve the contents, please send an e-mail to [e-mail].

How to: model your digital collaboration and implement your role(s)

The DSGO is a generic framework that enables data exchanges with parties you can trust and in which data rights are controlled by the data rights holder. Your implementation effort heavily relies on the role your are going to fulfil within a data exchange.

Do you develop software?

This developer portal is aimed at organisations that implement either the data service provider or the data service consumer role. Their solution technically engages in a data transaction.

As an alternative an organisation could use software where the data service is already implemented. In that case, the organisation either acts as the data rights holder or the data service user and you do not have to implement software.

For more information, see Transaction roles and patterns.

The steps below help you to implement the DSGO within your IT landscape.

1

Learn the basics

Before you start, learn the basics on data sharing in a decentralised setting and within a trust framework. You should be familiar with the following concepts:

• Transaction roles and patterns

• Component diagram

• Public Key Infrastructure

• Authentication flow

• Policy Based Access

2

Model your digital collaboration

The GEBORA gives an overview of collaborations in which data transactions between parties are required. A collaboration is modeled into a motivation, organisations process, information, application, and network layer. The steps to model a digital collaboration are:

1. Context and scenario analysis

2. Interaction and information analysis

3. Technology choice, message and interface specification

The digital collaboration model is input for your DSGO implementation of either the Data service consumer or Data service provider role.

Example

Context and scenario: maintenance work is shared efficient and effective reducing administration and failure cost.

Data exchange: Contractor and Business owner exchange maintenance orders.

You act as a business actor: Contractor.

Your information and data transaction role: request maintenance orders from a Building owner.

3

Extract your DSGO data exchange role

Based on your choices in the previous two steps, you can determine the data exchange roles you need to implement. Are you going to act as a:

1. Data service consumer (DSC) implementing a Client to access a data service

2. Data service provider (DSP) offering a data service

Other roles you could choose are:

• Data rights holder (DRH) authorizing the exchange of data from a data service provider under your control to a data service consumer;

• Data service user (DSU) utilizing a software company to access a data service on your behalf.

The Data rights holder or the Data service user roles are not part of this developer portal.

Example

In the example the Data rights holder role is fulfilled by the Building owner. The Building owner can choose to offer a data service with maintenance orders and also fulfilled the Data service provider role (2). The Building owner could also ask a software company to offer this data service on their behalf. The software company than acts as the Data service provider.

In the example you choose to be the Contractor. You are then either a Data service user or a Data service consumer (1). Your choice of implementing a Client yourself or hire a solution offered by a Software company depends on the digital maturity level of your organisation and the availability of products that offer the clients.

This Developer Portal is aimed at companies implementing the transaction roles within their own software solutions. We therefore assume you act as the transaction role Data service consumer.

4

Select all relevant guides and implement your DSGO role(s)

Your implementation effort depends on the role you have chosen in the in the previous steps. The table below shows for each of these roles which guides apply as MUST, SHOULD or COULD implementation.

Guide	Name	Service consumer	Service provider
1	Acquire certificates	MUST	MUST
2	Implement Client	MUST	MUST
3	Request participant evidence	SHOULD	SHOULD
4	Configure authorization server	NOT APPLICABLE	MUST
5	Configure resource server	NOT APPLICABLE	MUST
6	Define data service	NOT APPLICABLE	MUST
7	Implement data service	NOT APPLICABLE	MUST
8	Implement non-repudiation	COULD	COULD
9	Request delegation evidence	COULD	COULD
10	Configure PDP engine	NOT APPLICABLE	COULD
11	Implement events	COULD	COULD

In this example we assume you are going to act as a Data Service Consumer (3). This means you have to implement guides 2 and 3 and optionally implement guides 4 and 5.

5

Test your implementation with Postman and Sandbox registries

The iSHARE foundation developed Postman collections to test your implementation as a data service provider or data service consumer. Furthermore, you can use sandbox environments of the Test Participant Registry and/or Test Authorization Registry to perform a chain test with multiple parties in a data exchange use case.

6

Join the DSGO and become a participant

In this final step you join the DSGO as a participant. The DSGO therefore follows an admission process. During admission your software solution is tested with the iSHARE Conformance Test Tool. You could already request a login for this tool in order to validate your software solution yourself. This tutorial explains how to apply the iSHARE CTT-tool.

We would kindly want to ask you to fill in the following tempates as a preparation for your admission:

292KB

Template_administratieve_gegevens.docx

Data service consumer and Data service provider

304KB

Template_datadienstspecificatie.docx

Data service provider only

Please send the templates to [e-mail] and we will start your admission as soon as possible.

---

Further reading

Source	Description	Author	Language
DSGO Admission process	The admission process of the DSGO trust framework.	digiGO	Dutch
DSGO Rulebook	A complete description of the DSGO trust framework including all rules and regulations that apply to participants.	digiGO	Dutch
GEBORA	Reference Architecture for the Built environment.	digiGO	Dutch
iSHARE Trust Framework	The DSGO is based upon the iShare Trust Framework. All rules in this framework are embedded in the DSGO rulebook.	iSHARE	English
iSHARE Knowledge Base	Explains the basics of the iShare framework and includes instruction videos.	iSHARE	English
iSHARE Developer portal	A similar setup as this portal including mainly examples from logistics.	iSHARE	English
iSHARE Code snippets	Github repository with code snippets for implementing iSHARE functionality.	iSHARE	English
iSHARE Conformance Test Tool	Test tool used during admission to validate if your software solution meets all technical requirements.	iSHARE	English
iSHARE CTT-tool Tutorial	Tutorial explaining how to apply the iSHARE Conformance Test Tool	iSHARE	English
iSHARE.NET	Reference implementation of a data service consumer.	iSHARE	English
iSHARE Postman collections	A set of Postman collections to test your implementation.	iSHARE	English
iSHARE Service Provider	Reference implementation of a data service producer.	iSHARE	English