Aam Digital Services (aam-backend-service)

Collection of aam-digital services and tools

A modularize Spring Boot application that contains API modules for Aam Digital's case management platform.

API Modules

• Reporting: Calculate aggregated reports and run queries on all data, accessible for external services for API integrations of systems
• Export: Template based file export API. Uses carbone.io as templating engine.
• Skill: Integration with external system (SkillLab) to link and pull data into Aam Digital.
• Notification: Push Notification system, triggering events based on custom rules for each user.
• Third-Party-Authentication: "Single-Sign-On" integration with other platforms.

Modules have to be enabled via a feature flag in the environment config and may need additional environment variables as described in their module docs.

Checking availability of a feature module

You can make a request to the API to check if a certain feature is currently enabled and available:

> GET /actuator/features

// response:
{
  "notification": { "enabled": true },
  "export": { "enabled": true },
  "skill": { "enabled": true },
  "third-party-authentication": { "enabled": true }
}

The response lists feature modules with their status ("enabled"). If the aam-services backend is not deployed at all, such a request will usually return a HTTP 504 error. You should also account for that possibility.

---

Setup & Configuration

This API is part of the larger Aam Digital platform and usually deployed together with additional services via docker. See the ndb-setup repository for tools and guidance how to run this in a production environment.

For instructions to enable the backend in an overall system: ndb-setup README

The individual modules like "Reporting" require some setup and environment variables. Please refer to the respective READMEs in the "API Modules" list above for instructions about each API Module.

To run the system locally for development, refer to the docs/developer/README.md and sample docker files there. These allow you to run required additional services like databases and queues on your machine.

---

Development

The developer README provides detailed instructions how to set up a local testing environment: docs/developer/README.md

This backend is developed as independent modules that share some common services (e.g. for database access).

Frameworks & Tools

• Spring + Kotlin
• Spring Boot (see intro)
• Gradle (see intro)
• RabbitMQ (AMQP) for message queues (see Tutorial)

Folder structure

Each feature module is separated into its own package. Additionally, there is a common package that contains shared code. This includes services to work with the CouchDB, get a feed of DB changes and other common functionality. The "common" package also holds base functionality for authentication and security.

Configuration through environment variables

Using Spring Boot's system our configurable values are represented in the application.yaml.

We define environment variables to set / overwrite the configuration to real values for production or testing. Variables in the yaml hierarchy can be set in env variables using "snake case" variable names (refer to the documentation of Spring Boot's Externalized Configuration docs).

Feature Flags

Modules (usually) have to be explicitly enabled through a feature flag configuration. For example, FEATURES_EXPORTAPI_ENABLED=true in .env can toggle the feature flag

@ConditionalOnProperty(
    prefix = "features.export-api",
    name = ["enabled"],
    havingValue = "true",
    matchIfMissing = false
)

Message Queues

Most modules use RabbitMQ to decouple processing and allow for asynchronous processing of tasks. Refer to the official documentation (the tutorials are quite good) if you are not familiar with the concept or the framework specifically.