FS-CD Adapter

Customization Guide

Domain Service Customization

The FS-CD Adapter provides domain services in module de.faktorzehn.fscd-adapter:fscd-adapter-business:

Service Interface Purpose

Service Interface	Purpose
`FscdPostingService`	Post financial postings to FS-CD
`FscdAccountBalanceService`	Read account balance information
`FscdSepaMandateService`	Create and read SEPA mandates
`FscdDocumentService`	Read document information
`FscdDunningInfoService`	Read dunning information
`FscdInsuranceObjectService`	Create, update, and read insurance objects
`FscdBusinessLockService`	Create, update, delete, and read business locks
`FscdChangePolicyholderService`	Change the policyholder of a policy

FscdPostingService

Post financial postings to FS-CD

FscdAccountBalanceService

Read account balance information

FscdSepaMandateService

Create and read SEPA mandates

FscdDocumentService

Read document information

FscdDunningInfoService

Read dunning information

FscdInsuranceObjectService

Create, update, and read insurance objects

FscdBusinessLockService

Create, update, delete, and read business locks

FscdChangePolicyholderService

Change the policyholder of a policy

Each service interface has a default JCo-based implementation auto-configured by module de.faktorzehn.fscd-adapter:fscd-adapter-autoconfigure.

Service Architecture

The following is a class diagram showing the interfaces and classes involved in a service that reads data from FS-CD, using the account balance service as an example.

Service Interface: Defines the service contract (e.g., reading account balances for a partner and insurance object number).
Service Implementation: Retrieves or processes data using JCo (e.g., fetching account balance data from FS-CD).
Mapper Interface: Defines the generic mapping function from JCoTable to result type.
Mapper Implementation: Maps JCoTable data to Result<List<T>> (e.g., Result<List<AccountBalance>>).

For services that write data to FS-CD, such as the posting service, the architecture is similar but uses a different mapper interface:

The key difference is the ObjectToJcoFunctionMapper interface and its PostingMapper implementation. This mapper converts input data (e.g., a list of postings) to JCo function parameters. The mapper’s map(JCoFunction, O, Map) method takes JCoFunction as a parameter for this reason.

The diagrams are simplified representations. For the complete implementation details, refer to the source code in module fscd-adapter-business.

Customization Approaches

The services can be customized to accommodate project-specific requirements.

Approach	Use When	Complexity
Configuration Properties	Using custom SAP function modules with compatible signatures	Low
Custom Mapper	Need to handle additional RFC parameters or custom field mappings	Medium
Replace Service	Need to fundamentally change service behavior or use different technology (e.g., SOAP instead of JCo)	High

Approach

Use When

Complexity

Configuration Properties

Using custom SAP function modules with compatible signatures

Low

Custom Mapper

Need to handle additional RFC parameters or custom field mappings

Medium

Replace Service

Need to fundamentally change service behavior or use different technology (e.g., SOAP instead of JCo)

High

Configure Custom Function Modules

To use custom SAP function modules (e.g., Z-functions) with compatible signatures, configure the function module name via Spring properties.

Example: Custom function module for reading account balances

fscd-adapter:
  jco:
    functions:
      read-account-balances: Z_CUSTOM_FSCD_BALANCE

See JcoFunctionProperties for the full list of configurable function modules. Default function module names are defined as constants in the respective service implementation classes.

Configure No-Data Fields for Insurance Object Updates

On update, certain insurance object fields must be set to "/" to prevent SAP FS-CD from updating them. These fields are configurable via properties.

fscd-adapter:
  insurance-object-mapper:
    no-data-on-update:
      header:                (1)
        - INSOBJECTTYP
        - VALDT
      insurance-object:      (2)
        - INSOBEZ
      partner:               (3)
        - MVARI
        - IS_COVAR

1	IS_HEADER structure fields set to "/" on update
2	IS_IOB structure fields set to "/" on update
3	IS_IOBPAR structure fields set to "/" on update

See InsuranceObjectMapperProperties for default values.

Business Lock Type Configuration

The business lock types available in the web application to create business locks can be configured as follows.

fscd-adapter:
  jco:
    available-business-lock-types: 1,2,3,9    (1)

1	Comma-separated list of allowed business lock type IDs (default: 1,2,3,9). The corresponding texts are retrieved from the configured domain value texts.

Customize RFC Parameters & Calls

To handle custom SAP fields or parameters, replace the mapper implementations used by a service using Bean Replacement.

Domain objects provide a Map<String, Object> extensions attribute for arbitrary data. Custom mappers can use this to:

Transfer custom fields between RFCs and domain objects
Pass custom data through REST APIs to/from SAP FS-CD

Example: Read Custom RFC Field into Extensions (Read-Side Mapper)

The following example shows a custom AccountBalanceResultMapper that reads a non-standard RFC field and stores it in AccountBalance.extensions:

@Component
public class MyAccountBalanceResultMapper implements JcoTableMapper<AccountBalance> {

    @Override
    public Result<List<AccountBalance>> map(JCoTable table) {
        var result = new ArrayList<AccountBalance>();
        for (var row : JcoTableIterable.iterate(table)) {
            var read = new JcoRecordReader(row);
            var balance = AccountBalance.builder()
                    // ... standard field mappings ...
                    .build();
            balance.getExtensions().put("myCustomField", read.string("Z_CUSTOM_FIELD"));
            result.add(balance);
        }
        return Result.success(result);
    }
}

Example: Write Extensions Field to RFC (Write-Side Mapper)

The following example shows a custom PostingMapper that reads a value from Posting.extensions and passes it as a custom RFC parameter:

@Component
public class MyPostingMapper implements ObjectToJcoFunctionMapper<List<Posting>> {

    @Override
    public void map(JCoFunction function, List<Posting> postings, Map<String, Object> context) {
        var table = function.getTableParameterList().getTable("IT_POSTINGS");
        for (var posting : postings) {
            table.appendRow();
            var writer = new JcoRecordWriter(table);
            // ... standard field mappings ...
            var customValue = (String) posting.getExtensions().getOrDefault("myCustomField", "");
            writer.string("Z_CUSTOM_FIELD", customValue);
        }
    }
}

Replace a Service Implementation

To fundamentally change service behavior or use different technology (e.g., SOAP instead of JCo), replace the entire service implementation using Bean Replacement.