LogoLogo
Give FeedbackGovStack Home
25Q2
25Q2
  • GovStack
  • Contributing
  • Architecture and Nonfunctional Requirements
    • 2 Introduction
    • 3 GovStack Architecture
    • 4 Building Block Design Principles and Considerations
    • 5 Cross-Cutting Requirements
    • 6 Onboarding Products
    • 7 Standards
    • 8 UX Switching and Handover
    • 9 Other Resources
  • Security Requirements
    • 2 Description
    • 3 Terminology
    • 4 Security Management
    • 5 Cross-Cutting Requirements
    • 6 Standards
    • 7 Authorization Services
    • 8 Additional Security Modules
    • 9 Other Resources
  • GovStack UI/UX Guidelines
    • 1 Version History
    • 2 Description
    • 3 Service design good practice guidelines
      • 3.1 User-centred design
        • 3.1.1.1 Understand needs and requirements
        • 3.1.1.2 Involve others in the design process
        • 3.1.2.1 Test with users
        • 3.1.3.1 Share findings
        • 3.1.3.2 Monitor performance
          • 3.1.3.3 Set up analytics
      • 3.2 Accessibility and inclusion
        • 3.2.1.1 Test for accessibility
        • 3.2.2.1 Involve a diverse user group in the design
        • 3.2.2.2 Support multiple languages
        • 3.2.2.3 Foster a culture of inclusion
      • 3.3 Consistency
        • 3.3.1.1 Use simple language
        • 3.3.2.1 Implement a consistent style guide
        • 3.3.2.2 Use design patterns
        • 3.3.2.3 Use a frontend framework
        • 3.3.3.1 Interoperability
        • 3.3.3.2 Use integrations
        • 3.3.4.1 Work in the open
      • 3.4 Technology choices
        • 3.4.1.1 Choose the right level of security
        • 3.4.1.2 Design for privacy
        • 3.4.2.1 Optimise load times
        • 3.4.2.2 Account for connectivity issues
        • 3.4.3.1 Test across platforms
        • 3.4.3.2 Design cross-channel
    • 4 Design patterns
      • 4.1 Service patterns
      • 4.2 User flows
        • 4.2.1 Register
        • 4.2.2 Authenticate
        • 4.2.3 Asking users for feedback
        • 4.2.4 Find a service
        • 4.2.5 Check a users eligibility
        • 4.2.6 Make an application
      • 4.3 Page templates
        • 4.3.1 Feedback
        • 4.3.2 Perception survey
        • 4.3.3 Satisfaction
        • 4.3.4 Before you start
        • 4.3.5 Service sheet
        • 4.3.6 Asking users for consent
        • 4.3.7 Task list
        • 4.3.8 Asking users for information
        • 4.3.9 Check answers
        • 4.3.10 Outcome
    • 5 Use-case examples
    • 6 References
    • 7 Other Resources
  • Building Blocks
    • About Building Blocks
    • Cloud Infrastructure
    • Consent
    • Digital Registries
    • E-Marketplace
    • E-Signature
    • Geographic Information System (GIS)
    • Identity
    • Information Mediation
    • Messaging
    • Payments
    • Registration
    • Scheduler
    • Workflow
    • Wallet
  • Use Cases
    • Reference Use Cases
  • Public Administration Ecosystem Reference Architecture (PAERA)
    • PAERA
  • Tools
    • Sandbox
  • Release Notes
    • 23Q4
Powered by GitBook

Apache-2.0 license

On this page
  • 6.1 Adaptors
  • 6.2 Native GovStack Implementation
  • 6.3 GovStack Testing Harness

Was this helpful?

Export as PDF
  1. Architecture and Nonfunctional Requirements

6 Onboarding Products

Was this helpful?

It is vital that GovStack be able to connect to existing applications. Likewise, existing applications should be able to connect to and utilize GovStack resources as they see fit. This must be done without compromising the easy and secure interoperability provided by the GovStack system.

GovStack has defined a process for an existing product to become compliant with GovStack. This process is outlined in . Note that there are various levels of compliance that are defined. Any product owners or maintainers that are interested in the compliance process can use the GovStack testing platform to begin:

This section contains resources can be used by existing platforms to integrate into the GovStack ecosystem. The first section describes 'Adaptors' which can be used to translate an existing API into a GovStack-conformant API. The second section describes Native GovStack implementation. Finally we describe the GovStack Testing Harness which allows products to run automated tests that have been developed by the GovStack team to determine how closely an application conforms to the specifications and expected behaviors described by the Building Block specifications.

6.1 Adaptors

Adaptors are used to map existing APIs and functionality in a Digital Public Good into a format and scheme that is compatible with the GovStack API specifications.

Adaptors may transform data formats (ie. XML to json), may transform URLs/protocols, or may be used to map GovStack APIs and data structures into sector-specific standards (ie. FHIR patient records).

6.1.1 Key Components and Definitions

Adaptor: An adaptor provides both URL and payload mapping between an existing API developed by a DPG and the GovStack API definitions for the Building Block that the DPG provides functionality for.

Workflow: The workflow Building Block is used to manage more complex transactions where multiple Building Blocks must be called to complete a request (multi-part requests) or where retry/rollback/compensating transactions must be implemented.

Information Mediator: The Information Mediator is used transfer information securely between Building Blocks where communication occurs across the internet.

6.1.2 Adaptor Requirements

  1. Adaptors should not be used for outbound requests.

    1. In general it is the application which manages interactions and requests from various Building Blocks

    2. In the event that a Building Block needs to make a direct request from another Building Block, it is recommended to use the Workflow Building Block to manage and URL and data mapping

  2. Adaptors should always be tied to specific products. We will not have universal adaptors. Adaptors will be used to transform data based on specific APIs that have been defined by GovStack.

    1. Adaptor technologies may be re-used for different adaptors or we may have a paradigm where a generic adaptor can be configured via config files

  3. Adaptors Perform 3 distinct functions (all synchronous):

    1. Class 1 - URL rewriting (mapping a GovStack URL to a URL from a native API)

    2. Class 2 - Payload mapping (transforming data payloads between GovStack and native formats)

    3. Class 3 - Synchronous 1:many calls and composition of responses into a single response

      Note: async and/or complex transactions would require the use of the Workflow Building Block

6.2 Native GovStack Implementation

The highest level of integration involves existing products implementing APIs that can be directly consumed by other GovStack Building Blocks. This means that the application will provide APIs that are in alignment with the API specifications for the Building Blocks that they are supporting.

The following diagram shows a complete GovStack deployment with API gateways for citizen access via web or mobile and for existing applications to be able to call GovStack APIs on demand. The workflow building block is used as an adapter, exposing existing applications as GovStack resources via OpenAPI:

Here, citizens and existing applications are provided API access for requests into GovStack via a common API Gateway, while the workflow Building Block adapter provides outgoing API access to existing applications from GovStack Building Blocks.

6.3 GovStack Testing Harness

The GovStack team has created a testing platform that allows existing products to validate their APIs against the GovStack specifications. The testing platform consists of a set of tests (written in Gherkin) that can be run against one or more candidate products. These tests are run on a Continuous Integration (CI) platform and are executed automatically whenever changes are made to the GitHub repository for the Building Block.

The test platform will provide a detailed output of the test results, showing which tests are passing and failing for each candidate product.

6.3.1 Adding a new test to the Harness

New tests will automatically be run when a test cycle is started for a Building Block.

6.3.2 Adding a new product to the Test Harness

The 'examples' folder provides configuration files that will launch the product in the test (CI) environment using docker and docker compose. Testing a new product requires the addition of a new Dockerfile (or set of Dockerfiles) that will build the product, and a docker-compose file and docker-entrypoint.sh file that will launch and configure the product in the test environment so that it is ready to receive the test requests.

Please refer to for additional context/information and example scenarios for adaptors. \

The testing platform can be accessed at

New tests may be created for a Building Block. These tests are stored in the 'test' directory of the Building Block GitHub repository (GitHub repositories for the various Building Blocks can be found ). A new tests can be added by creating a .feature file in the features directory. All tests are written using Gherkin. Note that supporting code to run these tests should be stored in the 'support' folder under features.

A new candidate product can be integrated into the test harness by adding a new folder to the 'examples' directory of the Building Block GitHub repository (GitHub repositories for the various Building Blocks can be found ).

For more detailed information on how to create new tests or integrate new products into the test harness, please refer to , which is geared toward developers and technical teams.

this document
https://testing.govstack.global
this document
https://testing.govstack.global
here
here
this document
(open in https://app.diagrams.net/)