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.
| Info |
|---|
<SMARTIDHOME>In this article, <SMARTIDHOME> refers to /home/nexus, but this can be different depending on the setup. |
| Expand |
Prerequisites:
The Smart ID version needs to be 22.10.x as a minimum.
Step-by-step instruction
| Note |
|---|
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 | Mandatory | 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 |
...
|
httpResponseBodyVariableName |
...
| httpResponseBody | The variable name used in a process afterwards to extract the image from the response body | |
markPosition | Default value:
Valid values:
| The position of the 2D-DOC mark | |
outputFormat | Default value:
Valid values:
| The format of the output | |
issueCountry | Default value:
| 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
| Code Block | |||||
|---|---|---|---|---|---|
| title | Example: Response||||
<?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 propertiesARIAD_NEXT_CONNECTOR_PORT=7077ARIAD_NEXT_CONNECTOR_CERT_RESOLVER=leARIAD_NEXT_CONNECTOR_PREFIX=ariad-next-connectorUpdate 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 Block |
|---|
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 Block |
|---|
http://{ariad-next-connector-host}:{ariad-next-connector-port}/api/card?param=value3. |
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.