Mapping Evidence Repository

Persists SOAP/REST traffic pairs as evidence for API mapping. Provides methods to create, retrieve, and delete evidence records for specific service

Overview

The Mapping Evidence Repository is a persistence component responsible for storing and managing MappingEvidenceRecord objects. These records represent captured SOAP/REST transaction pairs, which serve as evidence for defining transformations between a legacy SOAP service and a modern REST API.

This repository interacts directly with the s2r_mapping_evidence database table. It provides a data access layer for creating, retrieving, and deleting evidence records. Its primary function is to support API mapping workflows, including automated mapping suggestions and readiness-gate checks for API consumption.

Callers of this repository include:

An automated traffic analysis flow that uses bulkCreate() to insert batches of suggested mappings.
A "Consume wizard" readiness gate and a mapping synthesis process that use countByOperation() to determine if an operation has sufficient evidence for mapping.
An administrative API controller that uses validation methods like serviceVersionChainExists() and operationBelongsToVersion() to ensure data integrity before persisting new evidence.

How it Works

The repository uses plain JDBC for all database operations, managing the lifecycle of evidence records in the s2r_mapping_evidence table.

Data Creation and Tenancy

When a new MappingEvidenceRecord is created, the repository executes an INSERT statement. A key aspect of this operation is multi-tenancy enforcement.

IMPORTANT

All write operations are strictly scoped to the current tenant. The tenant_id for a new record is not taken from the input object but is derived from the session's app.tenant_id setting using the current_setting('app.tenant_id', true) function. This ensures that an API consumer cannot create evidence records in another tenant's scope, even if they provide a different tenant ID in the request.

The following diagram illustrates the sequence for creating a single evidence record, including the mandatory pre-flight validation checks performed by the calling service.

sequenceDiagram
    participant C as API Consumer
    participant S as Service Layer
    participant R as Mapping Evidence Repository
    participant DB as Database

    C->>S: Submit Mapping Evidence
    S->>R: serviceVersionChainExists(serviceId, versionId)
    R->>DB: Query s2r_service_version
    DB-->>R: Count
    R-->>S: true / false
    S->>R: operationBelongsToVersion(versionId, operationId)
    R->>DB: Query s2r_operation
    DB-->>R: Count
    R-->>S: true / false
    
    alt Valid associations
        S->>R: create(MappingEvidenceRecord)
        R->>DB: INSERT INTO s2r_mapping_evidence
        DB-->>R: Success
        R-->>S: New Record UUID
        S-->>C: 201 Created (with UUID)
    else Invalid associations
        S-->>C: 404 Not Found
    end

Data Retrieval

The repository provides several methods to retrieve evidence records:

By a single record's id.
By the parent service_version_id.
By a combination of service_version_id and operation_id.
By service_version_id with optional filters for operation_id and source.

All list-based retrieval methods return records sorted by creation date in descending order (created_at desc).

Validation

Before creating or associating evidence, calling services use the repository's validation methods to prevent orphaned records:

serviceVersionChainExists(): Confirms that a given service_id and service_version_id pair corresponds to an existing service version within the current tenant's scope.
operationBelongsToVersion(): Confirms that a given operation_id is a child of the specified service_version_id. This check passes if operation_id is null, as evidence can be created before it is assigned to a specific operation.

MappingEvidenceRecord Data Model

A MappingEvidenceRecord represents a single captured transaction pair. The fields are persisted in the s2r_mapping_evidence table.

Field	Type	Description
`id`	`UUID`	The primary key for the evidence record. If not provided on creation, a random UUID is generated.
`service_version_id`	`UUID`	Foreign key linking the evidence to a specific service version (`s2r_service_version.id`).
`operation_id`	`UUID`	Foreign key linking the evidence to a specific service operation (`s2r_operation.id`). Can be `null` if the evidence is not yet mapped to an operation.
`direction`	`String`	The direction of the traffic flow (e.g., "inbound", "outbound"). The source does not define specific values.
`source`	`String`	The origin of the evidence data (e.g., "F5", "manual"). The source does not define a specific set of values.
`soap_request`	`byte[]`	The raw byte content of the captured SOAP request.
`soap_response`	`byte[]`	The raw byte content of the captured SOAP response.
`rest_request`	`String` (JSON)	The captured REST request body, stored as a JSONB string.
`rest_response`	`String` (JSON)	The captured REST response body, stored as a JSONB string.
`rest_method`	`String`	The HTTP method of the REST request (e.g., "GET", "POST").

| | rest_path | String | The path of the REST request. | | --- | --- | --- | | correlation_id | String | An identifier used to correlate the SOAP and REST transactions. | | captured_at | OffsetDateTime | The timestamp when the transaction was captured. | | notes | String | Free-text notes about the evidence record. | | created_at | OffsetDateTime | The timestamp when the record was inserted into the database. Defaults to the current time if not provided. | | created_by | String | The identifier of the user or process that created the record. |

API Reference

The repository exposes the following public methods for managing evidence records.

Method	Return Type	Description
`create(MappingEvidenceRecord record)`	`UUID`	Persists a single evidence record and returns its generated or provided ID.
`bulkCreate(List<MappingEvidenceRecord> records)`	`int`	Persists a list of evidence records in a single transaction. Returns the number of records inserted. Returns 0 if the input list is null or empty.
`findById(UUID id)`	`Optional<MappingEvidenceRecord>`	Retrieves a single evidence record by its primary key. Returns an empty `Optional` if not found.
`findByVersion(UUID serviceVersionId)`	`List<MappingEvidenceRecord>`	Retrieves all evidence records for a given `serviceVersionId`, sorted by creation date descending.
`findByOperation(UUID serviceVersionId, UUID operationId)`	`List<MappingEvidenceRecord>`	Retrieves all evidence records for a specific `serviceVersionId` and `operationId`, sorted by creation date descending.
`findByVersionFiltered(UUID serviceVersionId, UUID operationIdFilter, String sourceFilter)`	`List<MappingEvidenceRecord>`	Retrieves evidence for a `serviceVersionId` with optional filters for `operationId` and `source`. Both filters are optional.
`countByOperation(UUID serviceVersionId)`	`Map<UUID, Long>`	Counts evidence records for each operation within a service version. Returns a map where keys are `operation_id`s and values are the counts. Excludes records where `operation_id` is null.

Tagsoverview

All SOAP-to-REST docs

Loading…