Skip to content

Jafly. Common Backoffice Library

Common Backoffice Library

Extend application-layer contexts for internal portals, impersonation, and backoffice resource controllers.

Use BackofficeContext and its resolver at the portal boundary. Keep impersonation metadata and security context explicit, and extend the abstract resource controller only for the operations your portal exposes.

Maven artifact Packaging Source project
org.fireflyframework:fireflyframework-backoffice jar modules/backoffice

Part of Team-wide architecture.

In the onboarding service

A reviewer portal can use backoffice contexts and controller bases to expose internal application-review operations. Define reviewer permissions and any impersonation policy in the host service.

Add the component

Installation and version availability explains source builds and published releases.

<dependency>
    <groupId>org.fireflyframework</groupId>
    <artifactId>fireflyframework-backoffice</artifactId>
    <version>26.10.20-SNAPSHOT</version>
</dependency>

Quick start

The Java examples in this section are API fragments for application code. Use the stated imports and supply the application-owned collaborators described alongside them.

import org.fireflyframework.common.backoffice.controller.AbstractBackofficeController;
import org.fireflyframework.common.backoffice.context.BackofficeContext;

@RestController
@RequestMapping("/api/backoffice/customers")
public class CustomerBackofficeController extends AbstractBackofficeController {

    @GetMapping("/{customerId}")
    public Mono<CustomerDetails> getCustomer(
            @PathVariable String customerId,
            BackofficeContext context) {
        // context provides operator identity and impersonation info
        return customerService.findById(customerId, context);
    }
}

Configuration and wiring

This module declares no @ConfigurationProperties class of its own. Use the constructor/port contracts above and the configuration of the host or related core module.

Public API and extension points

Type Contract and responsibility
BackofficeContext Immutable, product-agnostic backoffice context container for internal portal/backoffice requests.
BackofficeSecurityContext Immutable, product-agnostic security context for backoffice requests.
BackofficeContextResolver Interface for resolving the BackofficeContext from incoming requests.
AbstractBackofficeResourceController Thin, product-agnostic base for backoffice resource controllers.
AbstractBackofficeController Abstract Base Controller for Backoffice Administrative Endpoints This base class is for controllers that operate on administrative resources without requiring customer impersonation.
Related component Why it belongs nearby
Observability Provide a common metrics, tracing, health, and context-propagation foundation for framework components.
Starter Core Assemble core infrastructure conventions for WebClient, actuator, logging, configuration, and service discovery.
Starter Domain Assemble the framework dependencies used by domain services.
Starter Data Build data enrichment, job orchestration, quality, lineage, and provider operation services.
Common Client Library Call REST, SOAP, and gRPC services through reactive client builders with shared resilience and observability facilities.
Common Cache Library Use a common cache API with a local Caffeine default and pluggable distributed providers.
Common CQRS Library Separate commands and queries with reactive dispatch, execution context, validation, and authorization hooks.
Common EDA Library Publish and consume events through a common envelope and transport-independent APIs.
Starter Application Build application-layer request contexts and business process coordination.

Build and test

Use Java 25. From the repository root, build this component with its required dependencies:

git clone https://github.com/fireflyframework/fireflyframework-jafly.git
cd fireflyframework-jafly
./mvnw -pl :fireflyframework-backoffice -am verify
./mvnw -pl :fireflyframework-backoffice -am install

verify runs the selected projects' tests. install makes the current build available in your local Maven repository.

Representative test sources:

Test fixture

The impersonationIsGenericSubject test demonstrates one concrete behavior. Excerpt from BackofficeContextTest.java. The test class supplies its fixtures and imports.

@Test
void impersonationIsGenericSubject() {
    BackofficeContext notImpersonating = BackofficeContext.builder()
            .backofficeUserId(UUID.randomUUID()).build();
    assertThat(notImpersonating.isImpersonating()).isFalse();

    BackofficeContext impersonating = BackofficeContext.builder()
            .backofficeUserId(UUID.randomUUID())
            .impersonatedSubject("user-123")
            .impersonatedSubjectRoles(Set.of("customer"))
            .impersonationReason("Support ticket #42")
            .build();
    assertThat(impersonating.isImpersonating()).isTrue();
    assertThat(impersonating.getImpersonatedSubject()).isEqualTo("user-123");
    assertThat(impersonating.impersonatedSubjectHasRole("customer")).isTrue();
    assertThat(impersonating.getImpersonationReason()).isEqualTo("Support ticket #42");
}

Detailed reference

Configuration

firefly:
  backoffice:
    context:
      operator-header: X-Operator-Id
      impersonation-header: X-Impersonated-Customer

Continue the application

Use the Security Method Policy guide for the next part of this integration. The runnable submission/query service is in Getting started.

Source and further reading