Set up AriadNext connector

This article describes how to set up an AriadNext connector. The connector generates a Two-Dimensional Document (2D-DOC) (a specific French barcode format) using the AriadNext external system. The purpose is to allow inclusion of data and ensure the authenticity of the document through digital signatures.

<SMARTIDHOME>

In this article, <SMARTIDHOME> refers to /home/nexus, but this can be different depending on the setup.

Prerequisites

The Smart ID version needs to be 22.10.x as a minimum.

Step-by-step instruction

Ensure that you have the required authorization and certificate for accessing the AriadNext SOAP service before using this connector. See "Set up AriadNext" below for more information.

The AriadNext connector provides a REST endpoint for generating barcodes in unitary mode. The AriadNext connector acts as a proxy and supports a data structure similar as the one used by the Identity Manager Rest Process API. See "Rest call" in Miscellaneous standard service tasks in Identity Manager for more information.

Generate a barcode

To generate a barcode:

Add a new service task called MISC: Execute REST client call to your process.
Add the following parameters. The values are arbitrary and need to be updated:

Parameter	Value	Description
URL	http://{ariad-next-connector-host}:{ariad-next-connector-port}/api/barcode	The URL endpoint where the data will be sent (must end with /api/barcode)
username	Any value to bypass the validation
password	Any value to bypass the validation
includeHttpResponseBodyInProcessMap	true	If the value is set to `true`, this parameter defines if the HTTP response body should be added to the process map
httpResponseBodyVariableName	httpResponseBody	The variable name used in a process afterwards to extract the image from the response body
markPosition	Default value: NONE Valid values: TOP, BOTTOM, LEFT, RIGHT, NONE	The position of the 2D-DOC mark
outputFormat	Default value: PNG Valid values: PNG, JPG, TIFF, GIF, BMP, TEXT, FONT_DMTX, FONT_ALPHA	The format of the output
issueCountry	Default value: FR	The issue country of the document
firstnames	${Person_Firstname} (to send multiple first names, use the comma separator)	The first name(s)
lastname	${Person_Lastname}	The last name
registrationNumber	${Person_RegistrationNumber}	The registration number of the card owner
organization	${Person_Organization}	The organization
documentId	${Person_DocumentId}	The internal unique identifier of the document

See a response example below:

Example: Response

XML

<?xml version="1.0" encoding="UTF-8"?>
<data>
    <field name="image">image encoded as base 64</field>
    <field name="width">21.599999999999998</field> <!-- width in millimeters -->
    <field name="height">21.599999999999998</field> <!-- height in millimeters -->
</data>

Use the groovy script below to de-serialize the data and decode the image if applicable in another task of your process:
def data = new de.nexus.utils.operators.XmlConverter(new StringReader(httpResponseBody)).asJaxBObject(de.nexus.data.xml.Data.class)
def imageAsBase64 = data.toMap().get("image")
def image = java.util.Base64.getDecoder().decode(imageAsBase64)

Card_2DDOC = image

Set up AriadNext

The AriadNext system is configurable using the config/ariad-next.yaml file. You can configure host, security, and image polish settings in the configuration file.

Docker

Open the environment file <SMARTIDHOME>/compose/smartid.env for editing.
Set the properties for the following three variables to fit your deployment:
PRIME_CONNECTORS_VERSION=2305.0.0
# -- AriadNext properties
ARIAD_NEXT_CONNECTOR_PORT=7077
ARIAD_NEXT_CONNECTOR_CERT_RESOLVER=le
ARIAD_NEXT_CONNECTOR_PREFIX=ariad-next-connector
Update the docker/compose/identitymanager/ariad-next-connector/docker-compose.yml

Tomcat (stand-alone)

Adapt the config files in the WEB-INF/classes/config folder.

Retrieve card information

The AriadNext connector also provides an endpoint to retrieve card information (for example an endpoint that is used by INverify). When called, it starts a card process in Identity Manager Operator to provide the requested information. Optionally, the response from Identity Manager, in the form of a data map used by the process, can be converted into a custom JSON format.

Configure the card endpoint in config/idm-operator.yaml. There you will also find a detailed description of all settings.

The settings cover:

The URL that will start an Identity Manager Operator process, for example:

CODE

ws/processes/<processId>/startGetDataAndExecute/<taskId>?tenantId=1&maxAttempts=10&interval=2000

To get card information, use the Identity Manager REST API request "startGetDataAndExecute" since it starts the process and waits until the task "taskId" is executed and retrieves the data map. See Identity Manager Process REST API for more information.

The list of parameters that will be passed to the process.
A custom transformation of the process data from XML to custom JSON format.
A mapping of process execution API responses into custom http response codes.

ReST call configuration:

The HTTP method must be GET.
URL:

CODE

http://{ariad-next-connector-host}:{ariad-next-connector-port}/api/card?param=value

Query parameters: An optional list of parameters will be passed to Identity Manager Operator and added to the process map when the process is started.
Authentication as described in config/idm-operator.yaml
Define the JSON Format to transform the response body. See config/idm-operator.yaml for details.
Define a mapping of responses to custom response codes. See config/idm-operator.yaml for details.