Write operations

All document operations target the IndexWriteAlias of the configured IndexTypeVersion (e.g. jme_decree_document_v1_write). Using an alias rather than a physical index name allows ISM rollover to rotate physical indices transparently.

Operations

Operation	OpenSearch call	Description
`UPSERT`	`PUT /{indexWriteAlias}/{documentId}`	Creates or fully replaces the document.
`DELETE`	`DELETE /{indexWriteAlias}/{documentId}`	Removes the document by its ID.

The document ID is derived from each OriginReference returned by the configured ReferenceProvider. If the provider returns multiple references the operation executes once per reference, independently.

Document structure

Every document written to OpenSearch has the following top-level structure:

{
  "search_item": {
    "upserted_at":   "<ISO-8601 timestamp of the index write>",
    "major_version": 1,
    "minor_version": 1
  },
  "origin": {
    "id":         "<business object ID>",
    "version":    "<business object version>",
    "bp_id":      "<business partner ID>",
    "tenant":     "<tenant identifier, optional>",
    "created":    "<ISO-8601 creation timestamp>",
    "modified":   "<ISO-8601 last-modified timestamp>",
    "reference":  { "<provider-specific reference data>" }
  },
  "data": {
    "<snake_case_field>": "<value>"
  }
}

Field	Type	Description
`search_item`	object	Metadata added by the index writer service on every write.
`search_item.upserted_at`	date	Timestamp of the index write operation (ISO-8601).
`search_item.major_version`	integer	Major version of the `IndexType` mapping used at write time.
`search_item.minor_version`	integer	Minor version of the `IndexType` mapping used at write time.
`origin`	object	Reference back to the origin business object — populated by the resource service.
`origin.id`	keyword	Unique ID of the business object.
`origin.version`	keyword	Version string of the business object.
`origin.bp_id`	keyword	Business partner ID.
`origin.tenant`	keyword	Tenant identifier (optional, may be `null`).
`origin.created`	date	Creation timestamp of the business object.
`origin.modified`	date	Last-modified timestamp of the business object.
`origin.reference`	object	Provider-specific reference data (not indexed, `enabled: false`).
`data`	object	Business data — defined by the `IndexType` mapping, always snake_case field names.

Snake_case serialisation

The service relies on the typed data class generated by the IndexType registry Maven plugin to ensure correct snake_case field names in OpenSearch. During an upsert, the raw data received from the SearchItem provider is deserialized into the Class<T> returned by IndexType.dataClass(). The generated data class carries explicit @JsonProperty("snake_case_name") annotations on every field so the names written to OpenSearch always match the mapping definition.

SearchItem provider responsibility

The SearchItem provider must serialise the data payload using the same field names declared in the IndexType data class — the snake_case names from the @JsonProperty annotations. The recommended approach is to use the generated data class directly as the response type, or to annotate the provider's own DTO with matching @JsonProperty annotations:

// Option A — use the generated data class directly
public SearchItem<DecreeDocumentData> getSearchItem(...) { ... }

// Option B — annotate the provider DTO to match the generated class
public class DecreeDocumentDto {
    @JsonProperty("decree_document_id") String decreeDocumentId;
    @JsonProperty("decided_by")         String decidedBy;
}

Warning: If the provider serialises field names that do not match the @JsonProperty names in the IndexType data class (e.g. plain camelCase without annotations), Jackson will silently map all data fields to null in OpenSearch. No error is raised — the document is written with empty data. Always verify that the provider's serialised field names match the expected snake_case names.

Pre-write validation

Before writing, the service validates that the SearchItem fields are compatible with the cached mapping. Any field-level incompatibility is logged and causes the event to be forwarded to the jEAP error handling service instead of writing the document.

SearchItem Provider endpoint

Domain services that provide SearchItem data must expose a REST endpoint callable by the index writer service. This is provided by the jeap-opensearch-searchitem-api library — see that repository for setup and configuration details.

SearchItem read client

The authorization-aware search client for consuming documents indexed by this service is provided by the jeap-opensearch-client-starter library — see that repository for setup and usage.

Operations​

Document structure​

Snake_case serialisation​

SearchItem provider responsibility​

Pre-write validation​

SearchItem Provider endpoint​

SearchItem read client​

Related​