Agents External Stubs is the primary stub you need to run and test Agent Services locally and in other stubbed environments. It replaces gg-stubs and agents-stubs together with auth, company-auth-frontend, enrolment-store-proxy, tax-enrolments, users-groups-search, citizen-details, DES and datastream.

You will have to run UI stubs as well in order to be able to sign-in seamlessly into your application.

Support channel: #event-agents-external-stubs

This service SHOULD NOT be run on PRODUCTION environment.

• dynamic (data can be changed, no initial data included)
• persistent (data are persisted until modified or removed)
• programmable (data can be created and retrieved entirely through the custom API)
• smart (only minimal input needed, sensibly auto-generates missing values)
• complete (feels and behaves like real API would)
• multi-tenant (test data are sandboxed into planets, multiple data planets can co-exist)
• self-contained (does not need any other services to run)
• easy-to-use (through ergonomic API and complementary UI frontend)

• Stubbed APIs
  • Auth
  • User Details
  • Citizen Details
  • User Groups Search
  • Enrolment Store Proxy
  • Tax Enrolments
  • NI Exemption Registration
  • DES and IF
  • Datastream
  • File Upload
  • Companies House API Proxy
  • Enterprise Integration System
• Custom API
  • Authentication
  • Users Management
  • Master Records (DES)
  • Known Facts
  • Special Cases (Exceptions)
  • Test Planets

• user and enrolment model
• ETMP/DES records model
• auth and other services drop-in replacement
• generic proxy with pre-defined responses (special cases)
• agent-access-control support
• external auth and api-platform-test-user link

Every stubbed user and other data types live in some test sandbox (planet). You have to declare existing or a new planet whenever you sign-in. Each authenticated session have planetId information. Stubbed and custom UIs will consider only users and data assigned to the current planet.

User authentication expires after 15 minutes and so does the bearer token.

We handle local requests gracefully and do not require existing applications to reconfigure, i.e. we provide necessary TCP proxies:

• listening on 8500 for auth requests
• listening on 9978 for user-details requests
• listening on 9337 for citizen-details requests
• listening on 9984 for users-groups-search requests
• listening on 7775 for enrolment-store-proxy requests
• listening on 9111 for ni-exemption-registration requests
• listening on 9904 for des and if requests
• listening on 8100 for datastream events
• listening on 9974 for sso requests
• listening on 8898 for file-upload requests
• listening on 9991 for companies-house-api-proxy

You can switch this behaviour off by setting features.proxies config property to false.

This service can handle arbitrary requests and proxy them to the target service if possible or return pre-defined response. Target service name is determined based on the URL path prefix and its location looked up in the configuration:

• protocol: microservice.services.{service-name}.protocol
• host: microservice.services.{service-name}.host
• port: microservice.services.{service-name}.port

Any stubbed or proxied APIs request can return pre-defined response defined using Special Cases.

To achieve high volume throughput and low latency required for performance testing you may consider deploy only single stubs instance and switch on few optimisations options:

• features.authCache - to aggressively cache all auth authorisations in memory,
• features.preloadRecordsForDefaultUserIds - to preload record template caches with entities generated for the default user ids pool, this will work well with userIdFromPool query parameter attached to the sign-in and create user requests,
• features.clearOldMongoDbDocumentsDaily - to clear stubs database daily at 12:30 AM UTC.

Data can be generated for multiple agents, each with multiple clients and team members.

This datagen is triggered by POSTing a JSON payload at URLs like:

• Local: http://localhost:9009/agents-external-stubs/test/gran-perms/generate-perf-data
• Staging (using Orchestrator Curl): https://agents-external-stubs.protected.mdtp/agents-external-stubs/test/gran-perms/generate-perf-data

An example of the JSON payload looks like:

{
  "agencies": [
    {
      "clients": 300,
      "teamMembers": 20,
      "times": 4
    },
    {
      "clients": 1000,
      "teamMembers": 15,
      "times": 3
    }
  ],
  "populateFriendlyNames": false
}

The above example will create 7 agencies in total:

• 4 agencies, each with 300 clients and 20 team members
• 3 agencies, each with 1000 clients and 15 team members

The populateFriendlyNames field determines whether to populate friendly names for the generated clients, used in Granular Permissions.

The above example will create the 7 agencies having:

• their own planets named p-001 through p-007 respectively
• the main agent user named perf-test-agent-001 through perf-test-agent-007 respectively

Writes received events to the output stream.

This endpoint checks UTR and postcode against Business Partner Record and eventually return EORI if defined there.

Creates an envelope and routes and envelope.

Fetches company and officers information.

Used in country by country reporting (CbC)

Authenticate an user.

Returns Location header with a link to the authentication details and Authorization header containing bearer token and X-Session-ID header containing session ID.

Payload

{
    "userId": "your_test_user", 
    "providerType": "GovernmentGateway", 
    "planetId":"your_test_planet",
    "syncToAuthLoginApi": true | false
}

All parameters are optional. Sensible random values will be generated if missing.

Add ?userIdFromPool query parameter to automatically select user id from the default pool

If syncToAuthLoginApi set to true, and enviromnent property features.syncToAuthLoginApi = true, then the user will additionally be authenticated in auth-login-stub with credId set as userId@planetId.

Example (using httpie):

http POST localhost:9009/agents-external-stubs/sign-in userId=Alf planetId=Melmac
HTTP/1.1 202 Accepted
Location: /agents-external-stubs/session?authToken=8321db03-ba01-4115-838a-49daab5c6679
Authorization: Bearer 8321db03-ba01-4115-838a-49daab5c6679
X-Session-ID: 7323-872-873872    

or

curl -v -X POST http://localhost:9009/agents-external-stubs/sign-in
curl -v -X POST http://localhost:9009/agents-external-stubs/sign-in --data '{"userId":"Alf"}'
curl -v -X POST http://localhost:9009/agents-external-stubs/sign-in --data '{"planetId":"Melmac"}'
curl -v -X POST http://localhost:9009/agents-external-stubs/sign-in --data '{"userId":"Alf","planetId":"Melmac"}'

Get authentication details

Example (using httpie):

http GET localhost:9009/agents-external-stubs/session?authToken=8321db03-ba01-4115-838a-49daab5c6679
HTTP/1.1 200 OK
{
    "_links": [
        {
            "href": "/agents-external-stubs/sign-out",
            "rel": "delete"
        }
    ],
    "authToken": "8321db03-ba01-4115-838a-49daab5c6679",
    "planetId": "Melmac",
    "providerType": "GovernmentGateway",
    "sessionId": "e47f1b42-9616-43da-91f0-734eb958e88d",
    "userId": "Alf"
}

or

curl -v http://localhost:9009/agents-external-stubs/session?authToken=da7a42f1-7c31-4c0b-b8cb-c9f325457275

Get current authentication details

Terminate current authentication and invalidate bearer token.

Get all users available at the current planet (requires valid bearer token)

Optional params:

• affinityGroup: only return users with this affinity
• agentCode: only return agents with this agentCode
• limit: max number of users returned, default to 100

Get current user details. (requires valid bearer token)

Update current authenticated user. (requires valid bearer token)

WARNING Payload's userId field will not be used to find nor update!

Payload

User entity

Update an existing user. (requires valid bearer token)

WARNING Payload's userId field will not be used to find nor update!

Payload

User entity

Create a new user. (requires valid bearer token)

Add ?userIdFromPool query parameter to automatically select user id from the default pool

Payload

User entity

Examples (using httpie):

http POST localhost:9009/agents-external-stubs/users/ Authorization:"Bearer 7f53d0bb-f15c-4c83-9a0c-057a33caba0a" affinityGroup=Agent
HTTP/1.1 201 Created
Location: /agents-external-stubs/users/User239

http POST localhost:9009/agents-external-stubs/users/ Authorization:"Bearer 7f53d0bb-f15c-4c83-9a0c-057a33caba0a" userId=Alf affinityGroup=Agent
HTTP/1.1 201 Created
Location: /agents-external-stubs/users/Alf

or

curl -v -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer 7f53d0bb-f15c-4c83-9a0c-057a33caba0a' --data '{"userId":"Alf","affinityGroup":"Individual"}'

Delete user. (requires valid bearer token)

Create a new user from api-platform test user.

Payload

API Platform test user

Specific records have two endpoints:

Takes payload of that record and stores it in our records collection.

Generates a payload for that record type and calls the POST endpoint to store it

Get known facts (enrolment) information

Creates new known facts (enrolment)

Payload: KnownFacts entity

{   
    "enrolmentKey": "HMRC-MTD-IT~MTDITID~XC1234567890987", 
    "verifiers": [ 
        { "key": "NINO", "value": "AB087054B" }
    ] 
}

Upserts known facts (enrolment)

Upserts single known fact verifier

Payload: KnownFact

{ "key": "NINO", "value": "AB087054B" }

Remove known facts (enrolment), do not removes users allocations and assignments

Payload and response examples

List all special cases defined on the planet

Get special case by id

Create special case (or update)

Update special case

Delete special case

Destroy the test planet and all the data there

sbt test it:test

sbt clean coverageOn test it:test coverageReport

sm --start AGENTS_STUBS -r

or

sbt run

It should then be listening on port 9009 and others

browse http://localhost:9009/

This code is open source software licensed under the Apache 2.0 License