Skip to main content

Set Up the Platform Link-up

This guide connects a running Smart Corridor to the Border Control Platform with the Data Exchange Module. You start the Data Synchronization Service first, so the corridor learns the expected travelers, and then the Corridor Event Aggregator, so their passages are reported back. Each service is one container next to the corridor stack, configured with an env file. The examples use Docker; on Kubernetes, put the same variables in a ConfigMap and a Secret.

Before you start​

  • A corridor deployed as in First Deployment, with Face Matcher's REST API (port 8098) and GraphQL API (port 8097) reachable from the DXM containers.
  • A Traveler Identity Service reachable from the corridor host, version 0.19.0 to 0.20.x, with authentication on.
  • Two OAuth 2.0 clients registered in the Traveler Identity Service by its administrator: corridor-dss and corridor-cea, each with its own secret. The token endpoint is <TIS>/traveler-identity-service/oauth2/token.
  • Travelers with a face photo and journeys whose scheduled arrival falls in the window you are going to configure.
  • For the CEA: a PostgreSQL database and the RabbitMQ broker the Hub publishes to.

1. Start the DSS​

Create dss.env. The values below are a working starting point for one corridor; every variable is described in the DSS manual.

TIS_BASE_URL=https://tis.example.org/traveler-identity-service
TIS_TOKEN_URL=https://tis.example.org/traveler-identity-service/oauth2/token
TIS_CLIENT_ID=corridor-dss
TIS_CLIENT_SECRET=<secret>
VPP_BASE_URL=http://<corridor-host>:8098
VPP_GRAPHQL_URL=http://<corridor-host>:8097/graphql
TZ=Europe/Vienna
DSS_DEPLOYMENT_ID=vie-t1
DSS_MAX_CANDIDATES_PER_RUN=5000
DSS_MAX_SNAPSHOT_ITEMS=100000
DISPLAY_LABELS=true
ROUTE_1_ID=r1
ROUTE_1_WINDOW=NEXT:24h
ROUTE_1_MAPPING=displayName=traveler.firstName+traveler.lastName,note=journey.conveyanceNumber
ROUTE_1_SIZE_BOUND=5000
ROUTE_1_SYNC_INTERVAL_MINUTES=5
ROUTE_1_DELETE_INTERVAL_MINUTES=15
ROUTE_1_DELETE_OLDER_THAN_MINUTES=180

Choose DSS_DEPLOYMENT_ID once and keep it: the DSS uses it to recognize its own members, and the CEA uses it to recognize synchronized travelers. Then start the container:

docker run -d --name corridor-dss --env-file dss.env -p 8660:8660 \
registry.dot.innovatrics.com/border-control/corridor-data-synchronization-service:0.2.0

If a value is missing or wrong, the container stops and its log names the variable. Once it runs, the first sync starts right away. Check it with GET http://<host>:8660/corridor-data-synchronization-service/status: lastSync.outcome should be succeeded and tisReachable and vppReachable true. In Station you now see one dxm.r1.flight.… watchlist per flight, with the travelers and their photos.

2. Prepare the broker and the database​

The CEA does not create anything on the broker, so a mistake in its configuration can never create an unbounded queue. Create these objects on the RabbitMQ the Hub publishes to before you switch the export on:

ObjectSettings
Exchange cea.exportTopic, durable. The Hub publishes here with routing key identification.match.v1
Exchange cea.dlxTopic, durable. Dead-letter exchange
Queue cea.identification.qQuorum queue bound to cea.export with identification.match.v1; x-dead-letter-exchange=cea.dlx, x-dead-letter-strategy=at-least-once, a x-max-length sized for at least an hour of traffic
Queue cea.identification.dlqQuorum queue bound to cea.dlx, x-max-length 10000, overflow reject-publish
User cearead on cea.identification.q only. The Hub's user needs write on cea.export

Create a PostgreSQL database and user for the CEA, for example both named cea. The CEA creates its one table at startup.

3. Start the CEA​

Create cea.env. CEA_DSS_DEPLOYMENT must be the DSS_DEPLOYMENT_ID from step 1, and CEA_SCOPES must list every Hub unit of the corridor. All variables are described in the CEA manual.

CEA_AMQP_URI=amqp://<broker-host>:5672
CEA_AMQP_USERNAME=cea
CEA_AMQP_PASSWORD=<secret>
CEA_QUEUE=cea.identification.q
CEA_DB_URL=jdbc:postgresql://<db-host>:5432/cea
CEA_DB_USERNAME=cea
CEA_DB_PASSWORD=<secret>
CEA_TIS_BASE_URL=https://tis.example.org/traveler-identity-service
CEA_TIS_TOKEN_URL=https://tis.example.org/traveler-identity-service/oauth2/token
CEA_TIS_CLIENT_ID=corridor-cea
CEA_TIS_CLIENT_SECRET=<secret>
CEA_DSS_DEPLOYMENT=vie-t1
CEA_SCOPES=vie-t1-arrivals=corridor-1@VIE T1 arrivals corridor
CEA_PURPOSE=BORDER_CHECK_ENTRY
CEA_PASSAGE_QUIET=PT10M
CEA_MATCH_THRESHOLD=40
CEA_MATCH_ALGORITHM_VERSION=<matcher version>
CEA_VISIT_RETENTION=P7D
CEA_PARKED_RETENTION=P30D
CEA_ADMIN_TOKEN=<at least 16 characters>
docker run -d --name corridor-cea --env-file cea.env -p 8670:8670 \
registry.dot.innovatrics.com/border-control/corridor-event-aggregation-service:0.2.0

GET http://<host>:8670/corridor-event-aggregation-service/ready answers 200 once the database and the broker are reachable.

4. Switch on the Hub export​

Add the export settings to .env.hub and recreate the Hub, as described in Configuration Basics:

CEA_EXPORT_ENABLED=true
CEA_EXPORT_EXCHANGE=cea.export

From now on every identification.match event is also published, as metadata only, to cea.export. If the broker is briefly unavailable, the Hub buffers up to 10,000 exports; beyond that it drops each new export and counts it, and the corridor itself is never slowed down.

5. Check the round trip​

Walk a synchronized traveler through the corridor. Within seconds GET /status on the CEA shows one more delivered visit, and the traveler's history in the Traveler Identity Service shows a CORRIDOR encounter with outcome PENDING. Walking through again within the quiet interval does not add a second encounter; walking through after it does. If nothing arrives, check the CEA's skip counters in /status: skipped_not_dss means the member was not created by the DSS with this deployment ID, and skipped_unmapped_unit means the unit is missing from CEA_SCOPES. Parked visits are listed at GET /parked with the reason.

Run it again​

A change in the platform reaches the corridor on the next sync. To apply it immediately, for example before a demonstration, queue a sync with POST /corridor-data-synchronization-service/routes/r1/resync. It returns 202 when queued and 409 when the route already has work pending. A re-sync reapplies what is in the platform; it does not empty the watchlists. Members leave them through the deletion job, once their flight is older than ROUTE_n_DELETE_OLDER_THAN_MINUTES.