Run the patient onboarding sample app

In this tutorial, you’ll run a working patient onboarding application against your own GBG Go journey. The source for this sample app is on GitHub:

go-sample-frontend: the React front end, shared by all three sample apps.
go-sample-backend-java: the Java backends.
go-sample-backend-typescript: the TypeScript backends.

Each backend repository holds two implementations of the same service, in separate folders:

api-implementation/ calls the Journey API with hand-written HTTP requests.
sdk-implementation/ calls the Journey API through the Core SDK.

You need the front end and one backend. Every backend exposes the same HTTP API, so the front end works with any of them.

What this tutorial covers

By the end, you’ll have a patient onboarding application that:

Starts a verification journey through the Journey API v2, either directly or through the Core SDK.
Renders each screen from the journey’s own configuration, rather than from hardcoded forms.
Collects consent, identity details, an address, a photo ID, and a selfie.
Polls for the outcome and shows the decision, including a referral to manual review.

When a journey finishes, you can see it in the Investigation portal.

This tutorial covers the developer-first integration, through the Journey API or the Core SDK. It doesn’t cover hosted journeys or the Bridge SDKs. For how the sample apps are built and what they share, see the Sample applications overview.

Prerequisites

Access to the Go dashboard, with permission to create and publish journeys.
Licences for the modules this tutorial uses. Licences are assigned to your department by GBG, and an unlicensed module shows a warning icon in the Journey builder.
An API client. See Manage API clients for how to create one and get your client ID and secret.
Node.js v18 or higher, for the front end and the TypeScript backend.
JDK 21 and Maven, only if you choose the Java backend.
Git, to clone the sample repositories.

The TypeScript SDK backend needs Node.js 18.17 or later. The modules this journey uses are Document Classification v2, Document Extraction v2, Document Authentication v2, Facematch Verification, Data Verification, and Consent Collection.

Part 1: Build the journey

The application renders its screens from whatever your journey collects, so the journey comes first. The finished journey looks like this. Six modules run in sequence, then one evaluation node routes the patient to accept, reject, or manual review.

The patient onboarding journey in the Journey builder, showing six verification modules followed by an evaluation node with three decision branches — The healthcare patient onboarding journey

Add the modules

In the Journey builder, add these modules in order:

Module	What it does
Document Classification (Document Classification V2)	Identifies the document and confirms it is a type you accept
Document Extraction (Document Extraction V2)	Reads the data fields off the document
Document Authentication (Document Authentication V2)	Checks the document is genuine
Facematch Verification (Facematch Verification - NIST)	Compares the selfie against the document photo
Data Verification (UK: Single match all sources)	Matches the patient’s details against trusted data sources
Consent Collection (Consent Collection)	Records the patient’s agreement to share their record

Select the v2 variant of each document module, for example Document Classification v2 rather than Document Classification. The v2 variants are built for this API.

For instructions, see Configure modules.

Add the evaluation

Add an Evaluation node after the modules and configure these three decisions. For how to add and configure one, see Set up evaluation.

Decision	Classification	Match	Conditions
Reject	Negative	Any Match	Document Authentication is High Risk, or Consent Collection is Consent Not Given
Manual review	Neutral	All Match	Document Authentication is Medium Risk, and Data Verification is Partial Match
Accept	Positive	Any Match	Document Extraction is Extraction Successful, Document Authentication is Low Risk, or Consent Collection is Consent Given

Set the classification on each decision as shown. The application reads it to choose a result screen, where positive renders an approval, negative a decline, and neutral a referral to manual review.Give each decision branch an End of journey node.

Publish to Preview

Click Publish to Preview. You’ll see the confirmation message Delivery deployed successfully.Use Preview while you build and test. Publish to Production when you’re ready for real patients. The application works the same against either, and only the resource ID changes.

Copy the resource ID and version

Go to Dashboard in the Journey builder and copy the Resource ID and Version number.You’ll combine them as <resourceId>@<version>, for example:

b3d149562ec927dedcd76f3a6b7b0f82bbf7de818aebad3b3f7baa4c14940b6b@2cygaii9

Pin the exact version rather than using @latest. Every republish creates a new version, and a pinned application keeps running the version you tested until you change it deliberately.

Part 2: Set up the backend

Choose a backend. Each one exposes the same HTTP API, so the front end works with any of them.

Backend	Calls GBG Go with	Folder	Port
Java API	Hand-written HTTP requests	`go-sample-backend-java/api-implementation`	8082
TypeScript API	Hand-written HTTP requests	`go-sample-backend-typescript/api-implementation`	8082
Java SDK	The Core SDK, `com.gbg:go-core-sdk`	`go-sample-backend-java/sdk-implementation`	8092
TypeScript SDK	The Core SDK, `@gbg/go-core`	`go-sample-backend-typescript/sdk-implementation`	8092

Java API
TypeScript API
Java SDK
TypeScript SDK

git clone https://github.com/gbgplc/go-sample-backend-java.git
cd go-sample-backend-java/api-implementation

.env.local is listed in .gitignore, so Git doesn’t track it. Never commit your client secret, and never put it in application-*.yml.

Copy the example environment file:

cp .env.example .env.local

Open .env.local and set your client credentials:

GBG_CLIENT_ID=your-client-id
GBG_CLIENT_SECRET=your-client-secret

Open src/main/resources/application-meridian-health.yml and set your journey:

app:
  resource-id: your-resource-id@your-version

Start the service in live mode:

./run.sh meridian-health live

It listens on http://localhost:8082. The script finds JDK 21, loads .env.local, and starts the right profile.

git clone https://github.com/gbgplc/go-sample-backend-typescript.git
cd go-sample-backend-typescript/api-implementation
npm install

.env.local is listed in .gitignore, so Git doesn’t track it. Never commit your client secret, and never put it in a market config.

Copy the example environment file:

cp .env.example .env.local

Open .env.local and set your client credentials:

GBG_CLIENT_ID=your-client-id
GBG_CLIENT_SECRET=your-client-secret

Open lib/config/markets/meridianHealth.ts and set your journey:

resourceId: 'your-resource-id@your-version',

Start the service in live mode:

npm run dev:meridian-health:live

It listens on http://localhost:8082.

git clone https://github.com/gbgplc/go-sample-backend-java.git
cd go-sample-backend-java/sdk-implementation

.env.local is listed in .gitignore, so Git doesn’t track it. Never commit your client secret, and never put it in application-*.yml.

Copy the example environment file:

cp .env.example .env.local

Open .env.local and set your client credentials:

GBG_CLIENT_ID=your-client-id
GBG_CLIENT_SECRET=your-client-secret

Open src/main/resources/application-meridian-health.yml and set your journey:

app:
  resource-id: your-resource-id@your-version

Start the service in live mode:

./run.sh meridian-health live

It listens on http://localhost:8092. The script finds JDK 21, loads .env.local, and starts the right profile.

git clone https://github.com/gbgplc/go-sample-backend-typescript.git
cd go-sample-backend-typescript/sdk-implementation
npm install

.env.local is listed in .gitignore, so Git doesn’t track it. Never commit your client secret, and never put it in a market config.

Copy the example environment file:

cp .env.example .env.local

Open .env.local and set your client credentials:

GBG_CLIENT_ID=your-client-id
GBG_CLIENT_SECRET=your-client-secret

Open lib/config/markets/meridianHealth.ts and set your journey:

resourceId: 'your-resource-id@your-version',

Start the service in live mode:

npm run dev:meridian-health:live

It listens on http://localhost:8092.

Run one backend at a time. The Java and TypeScript versions of each backend use the same port. Every backend also has a mock mode that needs no credentials. Run ./run.sh meridian-health mock or npm run dev:meridian-health to use it.

Set your region

The samples default to the EU platform. If your tenant is in another region, then change the base URL and the region together, in the folder you chose:

Change both values. Authentication succeeds regardless of region, so a mismatch shows up later as journey calls failing against the wrong host.

Java
TypeScript

In src/main/resources/application-meridian-health.yml:

go:
  region: us
  base-url: https://us.platform.go.gbgplc.com/v2/captain/

In lib/config/markets/meridianHealth.ts:

go: {
  region: 'us',
  baseUrl: 'https://us.platform.go.gbgplc.com/v2/captain/',
},

Part 3: Set up the front end

The front end is one repository holding three applications. This tutorial uses the healthcare one.

git clone https://github.com/gbgplc/go-sample-frontend.git
cd go-sample-frontend
npm install

Create apps/meridian-health/.env.local, pointing at the backend you chose:

API backend
SDK backend

NEXT_PUBLIC_ONBOARDING_TRANSPORT=rest
NEXT_PUBLIC_API_BASE_URL=http://localhost:8082

NEXT_PUBLIC_ONBOARDING_TRANSPORT=rest
NEXT_PUBLIC_API_BASE_URL=http://localhost:8092

The front end compiles NEXT_PUBLIC_* values into the browser bundle when it starts. Never put credentials here, and restart the front end after you change them.

Start the front end:

npm run dev:meridian-health

Open http://localhost:3001. With the backend already running, you’ll land on the consent screen of your own journey.

If you see the consent screen, then the whole chain is working, from the browser through the front end and backend to GBG Go.

To understand the request flow the app uses, see How the applications are built. For the calls each backend makes, see How the API backends call GBG Go and How the SDK backends call GBG Go.

Troubleshooting

The app shows a generic 'A few more details' form

The screen plan doesn’t recognise something the journey collects, so the app falls back to a plain form rather than stalling.This usually means the journey changed after the plan was written. Check the backend log for No screen mapped for outstanding elements, which names the unmapped elements, then add them to the screen plan.

A screen asks for details the customer already entered

The journey’s required fields changed under the same resource ID. A republish can add required elements, so an address that needed three components can come back needing six, and a screen plan written against the old shape submits an incomplete element.Re-read collects after every republish rather than assuming the shape holds.

Every request fails with an expired session

The backend keeps sessions in memory, so restarting it invalidates every session in progress. Start a new journey.For the same reason, the samples run one journey per browser tab. The session ID lives in sessionStorage, so reloading resumes the journey, but a new tab starts a fresh one.

Authentication succeeds but journey calls fail

The region is mismatched. The token endpoint is global, so authentication works regardless, but journey calls go to a regional host. Check that region and base-url name the same region.

A module returns an error rather than a decision

A module that errors is different from one that declines, because nothing was decided about the customer.Open the journey in the Investigation portal and look at the failing step. It carries an error code, a problem description, a suggested action, and a correlation ID. Quote the correlation ID when contacting support, because it identifies the exact execution.

The backend logs 'No SDK submit mapping for field'

The front end submitted a field that the SDK backend can’t map onto the SDK’s types, so the backend didn’t send it. The journey might then ask for the same details again.Add the field to the submit mapping. In Java, that’s FieldMapping.KNOWN in SdkInteractionMapper.java. In TypeScript, it’s buildSdkSubmitRequest.ts.

The front end still talks to the backend you used before

The front end reads NEXT_PUBLIC_API_BASE_URL when it starts. Set it to the port of the backend you’re running now, then stop and restart the front end.

The backend won't start because the port is in use

Another backend is using the port. The Java and TypeScript SDK backends share ports 8091 to 8093, so stop the other one first.

ConnectionError: fetch failed, or UNABLE_TO_GET_ISSUER_CERT_LOCALLY

This applies to the TypeScript backend only. Node.js uses its own list of trusted certificate authorities, so behind a TLS-inspecting proxy every call to GBG Go fails.On Node.js 22.15 or later, run export NODE_OPTIONS=--use-system-ca before you start the backend. On older versions, set NODE_EXTRA_CA_CERTS to the path of your proxy’s root certificate.

Next steps

Review the outcome

See the journeys you ran, module by module, in the Investigation portal.

Configure outcomes

Change what each module reports, and how your evaluation turns those into decisions.

Publish to Production

Move from Preview to Production when you’re ready for real customers.

Explore the API

The full Journey API v2 reference.

Get Started

Platform

API-first integration

Hosted journey

Resources

Run the patient onboarding sample app

What this tutorial covers

Prerequisites

Part 1: Build the journey

Part 2: Set up the backend

Set your region

Part 3: Set up the front end

Troubleshooting

Next steps

Review the outcome

Configure outcomes

Publish to Production

Explore the API