Migration Guide: From 6.x To 7.x

From v6.9 To v7.1

ENV VARS to YAML

The configuration of the most from the Web Service settings is moved from environment variables to the YAML file. This type of the configuration gives an ability to keep all the product-specific parameters in one place and change any of them (or all at once) without cluttering the global variables' workspace.

This section describes a relation between the deprecated environment variables and their YAML counterpart parameters to perform the proper transfer of the configuration.

Enable YAML Configuration

To start using the YAML configuration, define the global environment variable:

DOCREADER_CONFIG_PATH="/path/to/config.yaml"

For more details, see the dedicated section of the Configuration page.

System Info

Environment variable	YAML parameter
`REGULA_RETURN_SYSTEMINFO`	`sdk` → `systemInfo` → `returnSystemInfo`
`REGULA_LICENSE`	`sdk` → `systemInfo` → `license`

For more details, see the dedicated System Info YAML Configuration section.

General Settings

Environment variable	YAML parameter
`DOCREADER_LIC_URL`	deprecated, should not be used
`DOCREADER_BIND`	`service` → `webServer` → `port`
`DOCREADER_WORKERS`	`service` → `webServer` → `workers`
`DOCREADER_TIMEOUT`	`service` → `webServer` → `timeout`
`DOCREADER_ENABLE_DEMO_WEB_APP`	`service` → `webServer` → `demoApp`

For more details about the environment variables' meaning, see the corresponding section of the Environment Variables Configuration page.

HTTPS and CORS

Environment variable	YAML parameter
`DOCREADER_CORS_ORIGINS`	`service` → `webServer` → `cors` → `origins`
`DOCREADER_CORS_METHODS`	`service` → `webServer` → `cors` → `methods`
`DOCREADER_CORS_HEADERS`	`service` → `webServer` → `cors` → `headers`
`DOCREADER_HTTPS`	`service` → `webServer` → `ssl` → `enabled`
`DOCREADER_CERT_FILE`	`service` → `webServer` → `ssl` → `cert`
`DOCREADER_KEY_FILE`	`service` → `webServer` → `ssl` → `key`
`DOCREADER_TLS_VERSION`	`service` → `webServer` → `ssl` → `tlsVersion`

For details about the parameters' meaning, see the corresponding section of the Environment Variables Configuration and CORS Configuration and SSL Configuration pages.

Monitoring and Metrics Collection

Environment variable	YAML parameter
`ENABLE_PROMETHEUS_METRICS`	`service` → `webServer` → `metrics` → `enabled`
`PROMETHEUS_MULTIPROC_DIR`	`service` → `webServer` → `metrics` → `path`

For details about parameters' meaning, see the corresponding section of the Environment Variables Configuration and Metrics Monitoring pages.

Logging

For details about setting the parameters via environment variables, see the Environment Variables Configuration page.

Access logs are configured in the service → webServer → logging → access section.
Application logs are configured in service → webServer → logging → app section.
Processing results logs are configured in service → webServer → processing section.

See more details about the YAML logging configuration on the Logging Configuration page.

Database

Prior to the release 7.1, Document Reader SDK has not been configured to use a database via environment variables. But in the release 7.1 the YAML parameter has been introduced: service.database.connectionString. See details in the dedicated Database Configuration section.

Face API Integration

Environment variable	YAML parameter
`REGULA_USEFACEAPI`	Not used anymore
`REGULA_FACEAPI_URL`	`sdk` → `processParam` → `faceApi` → `url`
`REGULA_FACEAPI_MODE`	`sdk` → `processParam` → `faceApi` → `mode`
`REGULA_FACEAPI_SEARCH`	`sdk` → `processParam` → `faceApi` → `search`
`REGULA_FACEAPI_PROXY`	`sdk` → `processParam` → `faceApi` → `proxy`
`REGULA_FACEAPI_PROXY_USERPWD`	`sdk` → `processParam` → `faceApi` → `proxy_userpwd`
`REGULA_FACEAPI_PROXY_TYPE`	`sdk` → `processParam` → `faceApi` → `proxy_type`
`REGULA_FACEAPI_THRESHOLD`	`sdk` → `processParam` → `faceApi` → `threshold`
`REGULA_FACEAPI_SERVICETIMEOUT`	`sdk` → `processParam` → `faceApi` → `serviceTimeout`
`REGULA_FACEAPI_CHILDAGETHRESHOLD`	`sdk` → `processParam` → `faceApi` → `childAgeThreshold`
`REGULA_FACEAPI_CHILDDOCVALIDITYYEARS`	`sdk` → `processParam` → `faceApi` → `childDocValidityYears`

See the detailed information about the Face API integration on the Integration with Face API page.

Web Service API v1

The Web Service API v1 is not supported via the YAML parameters.

However, if the entire Web Service setup is configured via the environment variables only, all the parameters, specific to API v1, are still supported. See the full their list below:

DOCREADER_JWT_SECRET
DOCREADER_STATE_STORAGE_SIZE_LIMIT
DOCREADER_AWS_USER_DYNAMO_TABLE_NAME
DOCREADER_SUBMIT_TRANSACTION_RESPONSE_IN_QUOTES
DOCREADER_STATE_AWS_BUCKET_NAME
DOCREADER_STATE_PATH

RFID Migration

This section describes how to migrate your previous existing RFID setup to the 7.1 Document Reader SDK Web Service release, preserving the functionality, depending on different preconditions.

Not Used RFID Previously

If your previous Web Service configuration didn't use RFID functionality, you don't need to change anything in release 7.1.

Used RFID PA Previously

If your previous Web Service configuration used RFID passive authentication checks (no matter via environment variables or configured critical error codes via the JSON parameters), now all the RFID PA parameters must be defined in YAML. The environment variables' values in this case will be ignored.

sdk:
  rfid:
    PKD_PA: <path_to_public_key_directory>
    paSensitiveCodes:
      - -1879048190
      - -1879048189

For more details, see RFID PA configuration via YAML.

Used RFID CA

If your previous Web Service configuration used RFID chip authentication checks, now this feature must be defined in YAML.

sdk:
  rfid:
    chipVerification:
      enabled: true

For details, see RFID CA configuration.

In this case, the Web Service also needs to employ a database.

service:
  database:
    connectionString: <database_connection_string>

For details and examples, see the Database Configuration page.

Unix Resources Paths

In all reference paths to external resources in Unix-like OS (Linux, macOS) the unix_x64 part is changed to just unix.

For example, if previously the path to the license file for the newly installed Document Reader Web Service was /app/extBin/unix_x64/regula.license now it's expected to be /app/extBin/unix/regula.license

If you have the existing Web Service installation, check the correctness of the paths to external resources accordingly.

Hologram Liveness Checks

Previously, the results of hologram-related document liveness checks were represented by the dedicated response type 524288 "Hologram detection and validation" of AuthenticityResultType enumeration.

Starting from release 7.1, the results of hologram checks (static, dynamic) are represented in scope of the same Type "Document liveness check" 2097152 of AuthenticityResultType enumeration, but by different Element Types of SecurityFeatureType enumeration:

5 — simple check of hologram presence
6 — hologram static check (single image)
7 — hologram static check (multiple images)
8 — hologram dynamic check

For better understanding, see the tree diagrams below.

Hologram check results — Version 6.9Hologram check results — Version 7.1

└── Type: AuthenticityResultType [524288]

└── Type: AuthenticityResultType [2097152]
|   └── ElementType: SecurityFeatureType [5, or 6, or 7, or 8]

For more details, see the Open API Authenticity Model of the Web Service response.