README.md

About the FIT-Connect Java SDK

The Java SDK for FIT-Connect enables to build clients for senders and subscribers without directly interacting with any REST-Endpoints. It provides a simple fluent API that guides through the creation and sending of a submission, as well as receiving submissions as a subscriber.

For further information, check out the official docs: FIT-Connect Documentation as well as the:

• Self-Service-Portal (Testing Environment)
• FITKO project website

Outline

• About the FIT-Connect Java SDK
• Outline
• Getting Started
  • Build Dependencies
  • Prerequisites
  • Add FIT-Connect SDK to your build
• Modules
• Setup
• API Usage for Routing
  • Finding Areas
  • Finding Destinations
    • Find destination by service identifier and areaId
    • Find destination by service identifier and region key (ARS/AGS)
• API Usage for Sender
  • Hand in already encrypted submission (e.g. from frontend)
    • 1. Retrieve public encryption key:
    • 2. Send encrypted data
  • Hand in a new submission with unencrypted data
  • Read the latest status of a submission
  • Validating callbacks
• API Usage for Subscriber
  • Retrieving submissions
    • List with pagination
    • List without pagination
    • Receive single submission
  • Sending events to the event-log
    • Accepting a submission
    • Rejecting a submission
    • Rejecting a submission via subscriber client directly
  • Read the latest status of a submission
  • Validating callbacks
• Submission Data Validation
• Error Handling
  • Exceptions
  • Auto-Reject
• Integration Tests
• Roadmap
• Contact
• License

Getting Started

How to set up the SDK project locally.

Build Dependencies

This section lists major frameworks/libraries used in the SDK.

• Java 11 (LTS)
• Maven 3.x
• Junit 5

FIT-Connect dependencies:

• JWKValidator 1.5.0

Further 3rd party dependencies:

• Nimbus-Jose JWT
• Jackson FasterXMl
• JCommander
• Snakeyaml
• OpenCSV
• OkHttp

Prerequisites

• Java Runtime >= 11, check your current setup in your commandline

  java --version 

(back to top)

Add FIT-Connect SDK to your build

To add a dependency on FIT-Connect using Maven, use the following:

<dependency>
  <groupId>dev.fitko.fitconnect.sdk</groupId>
  <artifactId>client</artifactId>
  <version>[Latest Version]</version>
</dependency>

With [Latest Version] of the last stable build or snapshot.

If you use a snapshot version, please add the maven snapshot repo to your pom.

<distributionManagement>
  <snapshotRepository>
  <id>ossrh</id>
  <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
  </snapshotRepository>
</distributionManagement>

(back to top)

Modules

See the projects' module documentation for more specific information:

• API Module
• Core Module
• Client Module
• Integration-Test Module

Setup

The following steps show how to get the SDK running

1. Create and account on the self-service portal

2. Get your sender/subscriber API-key credentials

3. Clone the sdk repo

   git clone https://git.fitko.de/fit-connect/sdk-java

4. Build the project with the included maven wrapper (no separate maven installation needed)

   ./mvnw clean install -DskipTests

5. Configure your config.yml (see template)

   • add Sender OAuth credentials from the self-service portal to SENDER section
   • add Subscriber OAuth credentials from the self-service portal to SUBSCRIBER section
   • add reference to private decryption key (JWK) to SUBSCRIBER section
   • add reference to private signature key (JWK) to SUBSCRIBER section

6. Load a configuration via:

     final ApplicationConfig config = ApplicationConfigLoader.loadConfigFromPath(Path.of("path/to/config.yml"));

7. Afterwards the config is used to initialize clients with the ClientFactory that offer clients for sender, subscriber and routing:

     final SenderClient senderClient = ClientFactory.getSenderClient(config);
       //
     final SubscriberClient subscriberClient = ClientFactory.getSubscriberClient(config);
       //
     final RouterClient routerClient = ClientFactory.getRouterClient(config);

(back to top)

API Usage for Routing

The Router-Client allows to retrieve data about areas and services as well as their service destination. A typical workflow using the RouterClient and SenderClient would be:

1. Find the areaId for an area via routing
2. Find the destination for a leikaKey and an areaId via routing
3. Submit a new submission to the destination using the SenderClient

Finding Areas

Areas can be searched with one or more search criteria:

final RouterClient routerClient = ClientFactory.getRouterClient(config);

final var citySearchCriterion = "Leip*";
final var zipCodeSearchCriterion = "04229";

// get first 5 area results
final List<Area> areas = routerClient.findAreas(List.of(citySearchCriterion, zipCodeSearchCriterion), 0, 5);

LOGGER.info("Found {} areas", areas.size());
for (final Area area : areas){
    LOGGER.info("Area {} with id {} found", area.getName(), area.getId());
}

Finding Destinations

For searching a destination the DestinationSearch.Builder is used pass a search request to the routing client. The leikaKey is mandatory, as well as (max.) one other search criterion for the area/region, like one of:

• areaId = identifier of an area that can be retrieved via findAreas(...) of the routing client
• ARS = amtlicher Regionalschlüssel
• AGS = amtlicher Gemeindeschlüssel

Note: Both, the leikaKey service-identifier and the region keys ars/agscannot be retrieved via the routing client, but can be found here:

• https://fimportal.de/ catalog for finding leikaKey service identifier
• https://opengovtech.de/ for looking up regional keys

Find destination by service identifier and areaId

final RouterClient routerClient = ClientFactory.getRouterClient(config);

final DestinationSearch search = DestinationSearch.Builder()
        .withLeikaKey("99123456760610")
        .withAreaId("48566") // areaId of "Leipzig"
        .withLimit(3)
        .build();

// get first 3 route results
final List<Route> routes = routerClient.findDestinations(search);

LOGGER.info("Found {} routes for service identifier {}", routes.size(), leikaKey);
for (final Route route : routes){
    LOGGER.info("Route {} with destinationId {} found", route.getName(), route.getDestinationId());
}

Find destination by service identifier and region key (ARS/AGS)