Skip to main content

Getting started

This page shows how to create an OpenSearch index writer service instance by depending on this template, adding index type and message configuration. For the bigger picture see Architecture.

1. Add the dependency​

A service instance depends on the thin BOM provided by this template:

<dependency>
    <groupId>ch.admin.bit.jeap</groupId>
    <artifactId>jeap-opensearch-index-writer-service-instance</artifactId>
</dependency>

The version is managed by the jEAP Spring Boot parent. This single artifact transitively pulls in the full jeap-opensearch-index-writer-web module with all adapters and auto-configuration.

2. Add an IndexType dependency​

An index writer service must have at least one IndexType registered. Index types are defined in separate Maven artifacts (one per business object) and consumed as normal dependencies:

<dependency>
    <groupId>ch.admin.bit.jme.indextype</groupId>
    <artifactId>jme-decree-document-index-type</artifactId>
    <version>1.0.0</version>
</dependency>

Index type artifacts are generated by the jeap-opensearch-index-type-registry-maven-plugin and published by each owning domain service. See Index Types for naming conventions and the artifact structure.

3. Configure message-to-operation mappings​

Place a file /opensearch/messages.json on the classpath. Each entry maps a Kafka message type and topic to one or more index operations:

{
  "messages": [
    {
      "messageName": "JmeDecreeDocumentCreatedEvent",
      "topicName": "jme-decree-document-created",
      "operations": [
        {
          "indexType": "DecreeDocument",
          "indexOperation": "UPSERT",
          "uri": "${jme.resource.base-uri}",
          "oauthClientId": "jme-client-id",
          "referenceProvider": "ch.admin.bit.jme.indexwriter.DecreeDocumentReferenceProvider"
        }
      ]
    },
    {
      "messageName": "JmeDecreeDocumentDeletedEvent",
      "topicName": "jme-decree-document-deleted",
      "operations": [
        {
          "indexType": "DecreeDocument",
          "indexOperation": "DELETE",
          "uri": "${jme.resource.base-uri}",
          "referenceProvider": "ch.admin.bit.jme.indexwriter.DecreeDocumentReferenceProvider"
        }
      ]
    }
  ]
}

See Message configuration for all available fields.

4. Implement a ReferenceProvider​

Each operation requires a Spring bean implementing ReferenceProvider<M> that extracts one or more OriginReference objects from the incoming Kafka message:

@Component
class DecreeDocumentReferenceProvider implements ReferenceProvider<JmeDecreeDocumentCreatedEvent> {

    @Override
    public List<OriginReference> extractReference(JmeDecreeDocumentCreatedEvent event) {
        return List.of(
            OriginReference.builder()
                .id(event.getPayload().getDecreeDocumentId())
                .version(event.getPayload().getVersion())
                .build()
        );
    }
}

The service calls the provider for every incoming message and processes each returned reference independently — if the provider returns multiple references, the index operation executes once per reference.

5. Configure application properties​

Configure the OpenSearch connection and index template settings in application.yml:

jeap:
  opensearch:
    indexwriter:
      connection:
        url: https://my-domain.eu-central-2.es.amazonaws.com
        signing-region: eu-central-2
      index-templates:
        default:
          number-of-shards: 1
          number-of-replicas: 1
          refresh-interval: "1s"

See the Configuration reference for all available properties.

6. Declare consumer contracts​

Place the @JeapMessageConsumerContractsByTemplates annotation on the application class. The annotation processor reads messages.json at compile time and generates one consumer contract per configured message type:

@JeapMessageConsumerContractsByTemplates(
    appName = "my-opensearch-index-writer"
)
@SpringBootApplication
public class MyOpenSearchIndexWriterApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyOpenSearchIndexWriterApplication.class, args);
    }
}

The service refuses to start if the annotation is missing or if appName does not match spring.application.name. See Consumer contracts.