Transactions

In this section, we will learn about creating and displaying consent transactions.

Consents are sent to the end-user using our Consent Form. To generate a Consent Form, you first need to generate a consent transaction using a ConsentContext object.

Step 1 : Creating a transaction

The first step of a transaction is to generate a consent context to hold all the information needed to generate a consent form.

Subject

The subject of a transaction is a unique identifier used to represent an individual. It can be anything from an internal id, a name, a phone number, an email address, a social security number, a passport number, etc. It is used to identify the end-user and to link the consent to them.

When you create another transaction with the same subject, the Consent Manager will be able to retrieve this subject's previous consents and display them in the consent form.

info

See the Subject documentation for more information.

Layout

A layout is a set of options that will tell the Consent Manager how to display the consent form and which data models to display. It is used to customize the look and feel of the consent form.

In the ConsentContext, you can specify the layout field. It must be the id of a custom layout. You can create custom layouts using the Consent Manager GUI and save them through the API.

tip

If you don't want to create a custom layout, you can specify the layout you want in the layoutData field of the ConsentContext.

caution

You must set either the layout or the layoutData field. Not both.

Creating the transaction

To create the transaction, you must send your ConsentContext to the /consents endpoint using a POST request. The response will contain the id of the transaction.

curl

curl -d "CONSENT_CONTEXT" -H "Authorization: Bearer TOKEN" -X POST https://localhost:4287/consents

Consent.js

import { ConsentsResource } from '@fairandsmart/consents-ce';

const consentContext = { ... };

ConsentsResource.createTransactionJson(consentContext)
    .subscribe((transactionId) => {
        // Do something with the transaction
    });

Java

info

For the API Reference, check the /consents resource.

Step 2 : Displaying the Consent Form

Once you have the transaction id, you can display the consent form to the end-user. The Consent Form is a web page that you can embed in your application.

The url to this form is location in the Location header of the response from the Creating the transaction request.

tip

You can also reconstruct the url using the transaction id like so : GET /consents/{txid}/submit.

Optional : Manually sending the consent values

In some cases, you will want to update values for a consent without displaying the built-in form. To do this, you can use the POST /consents/{txid}/submit endpoint (see reference).

How to use Peer elements

You can use models from Consent Manager instances which recognize you as a peer in your Consent Contexts. These models will be rendered in the form viewed by the subject, but you will not get access to the subject's consents and answers to peer elements. Indeed, since you do not own these models, the associated consents are fully handled and stored in their owners' Consent Manager instances to ensure adequate privacy.