Getting Started

Set up the Project

To implement a custom adapter, create a new Maven project and bundle a Spring Boot application using the adapter’s Maven dependencies as well as your custom Spring components.

Create Maven Project

The following is the minimal setup to run the Linkki-based adapter webapp and its REST services. It neither includes authentication nor does it bundle the fscd-adapter-kafka dependency, which requires a running Kafka broker.

See the fscd-adapter-sample git repository for a full implementation (available to Faktor Zehn users only), including

  • the selection of policy editing strategies and customizers via property fscd-adapter.policy-editing.strategy:

    • pnc for IPM P&C

    • shu for IPM SHUR

    • kf for IPM KF

  • mapping properties

    • fscd-adapter.policy-editing.mapping for policy editing mappings

    • fscd-adapter.reserve-change.mapping for reserve change mappings

project-root/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── FscdAdapterWebApp.java (1)
│   │   ├── resources/
│   │   │   └── application.yml (2)
├── pom.xml
1 Bundles the adapter app as SpringBootApplication. Requires an FS-CD system.
2 Configures Spring application properties.
FscdAdapterWebApp.java
@SpringBootApplication(scanBasePackages = {"de.faktorzehn.fscdadapter", "de.faktorzehn.jco" })
@EnableVaadin({ "de.faktorzehn.fscdadapter.web", "org.linkki.core" })
@Theme(F10ProductTheme.F10_PRODUCT_THEME)
public class FscdAdapterWebApp implements AppShellConfigurator {

    public static void main(String[] args) {
        SpringApplication.run(FscdAdapterWebApp.class, args);
    }
}
application.yml
jco:
  client:
    # replace with JCo destination properties
    ashost: ${hostname}
    r3name: ${r3name}
    sysnr: ${sysnr}
    lang: ${lang}
    client: ${client}
    passwd: ${password}
    user: ${username}

vaadin:
  urlMapping: /ui/*

# configure swagger-ui for the OAS documentation
# do not include this in the productive app
springdoc:
  swagger-ui:
    path: /swagger-ui
    showExtensions: true
pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>de.faktorzehn.commons</groupId>
        <artifactId>f10-suite-starter-spring</artifactId>
        <!-- replace with latest version-->
        <version>25.7.0</version>
    </parent>

    <groupId>my.group.id</groupId>
    <artifactId>my-fscd-adapter-webapp</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <!-- replace with latest versions-->
        <fscd-adapter.version>25.7.0</fscd-adapter.version>
        <pnc.version>25.7.0</pnc.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>de.faktorzehn.pnc</groupId>
            <artifactId>pnc-autoconfigure</artifactId>
            <version>${pnc.version}</version>
        </dependency>
        <dependency>
            <groupId>com.vaadin</groupId>
            <artifactId>vaadin-spring</artifactId>
        </dependency>
        <dependency>
            <groupId>de.faktorzehn.fscd-adapter</groupId>
            <artifactId>fscd-adapter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>de.faktorzehn.fscd-adapter</groupId>
            <artifactId>fscd-adapter-extservices</artifactId>
        </dependency>
        <dependency>
            <!-- provides Swagger UI. Do NOT bundle this into the productive app. -->
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>de.faktorzehn.fscd-adapter</groupId>
                <artifactId>fscd-adapter-bom</artifactId>
                <version>${fscd-adapter.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <build>
        <finalName>${project.artifactId}</finalName>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <id>repackage</id>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>com.vaadin</groupId>
                <artifactId>vaadin-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <id>prepare-frontend</id>
                        <goals>
                            <goal>prepare-frontend</goal>
                        </goals>
                        <phase>compile</phase>
                    </execution>
                    <execution>
                        <id>build-frontend</id>
                        <goals>
                            <goal>build-frontend</goal>
                        </goals>
                        <phase>compile</phase>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

Start the Adapter

To start the adapter locally, replace /path/to/sapjco3/ with the path pointing to your JCo binaries and run mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Djava.library.path=/path/to/sapjco3". The webapp will be available at http://localhost:8080/ui.

OpenAPI Documentation

The domain and REST services are documented with OpenAPI Specification 3 (OAS3) and can be inquired using Swagger UI at http://localhost:/8080/swagger-ui.

Authentication

The application can be secured with OAuth 2.0 using the Faktor Zehn Commons library.