Skip to main content

using-mapi-workflow

MAPI Mapping Workflow​

This page describes how to define and work with mappings in MAPI using the /maps endpoints implemented in Mapi/WebAppExtensions.cs.

1. Create the mappable type in source code (via PR)​

  1. Add a new type that implements IMappable in the MAPI codebase.
  2. Submit a PR and deploy the changes so the new type becomes available to MAPI.
  3. Verify that the type is recognized as a mapping target by calling:
GET /maps/targets

If the new type appears in the response, it is available as a mapping target (and typically also as a source).

2. Create a new mapping definition (POST /maps)​

Create a mapping definition by providing a source type and a target type.

Example: PropertyClaim as source and ClaimSubmittedEvent as target when you want to define a map for SubmissionAPI.

POST /maps?sourceType=PropertyClaim&mappingTarget=PropertyClaim_ClaimSubmittedEvent
Content-Type: application/json

Map ID convention​

  • The map ID is generated as a combination of source_target_version, for example:
PropertyClaim_ClaimSubmittedEvent_v1
  • If you want to create another map for the same source/target pair, increase the version.
  • Currently only one active version per source_to_target is supported.

API implementation:

app.MapPost("/maps", async (string sourceType, string mappingTarget, MappingService mapper, CancellationToken cancellationToken) =>
{
    var mapResult = await mapper.CreateMappingLogicAsync(sourceType, mappingTarget, cancellationToken);
    return new CreateMapResponse(mapResult.mapId, mapResult.map);

}).WithOpenApi();

3. List all stored mappings (GET /maps)​

Use this endpoint to see all stored map IDs:

GET /maps

Example response:

["ConversationHistory_Claim_v1", "PropertyClaim_ClaimSubmittedEvent_v1"]

API implementation:

app.MapGet("/maps", async (MappingService mapper, CancellationToken cancellationToken) =>
{
    var mapIds = await mapper.GetMapIdsAsync(cancellationToken);
    return mapIds;

}).WithOpenApi();

4. Get a specific mapping definition (GET /maps/{id})​

Fetch the full mapping definition for a specific mapId:

GET /maps/{id}

Example response (simplified):

{
  "Source": "PropertyClaim",
  "Target": "ClaimSubmittedEvent",
  "Version": "v1",
  "ValueMaps": {
    "SubmissionId": null,
    "PolicyNumber": "[PolicyNumber]",
    "Country": "[Country]"
  },
  "ObjectMaps": {},
  "ListMaps": {}
}

API implementation:

app.MapGet("/maps/{id}", async (string id, MappingService mapper, CancellationToken cancellationToken) =>
{
    var map = await mapper.GetMappingLogicAsync(id, cancellationToken);
    return map;

}).WithOpenApi();

5. Update an existing mapping (PUT /maps/{id})​

Once a map is created (for example via POST /maps), you typically refine it (for example using Atlas Editor) and then persist the updated definition with:

PUT /maps/{id}
Content-Type: application/json

{
  "map": {
    "Source": "PropertyClaim",
    "Target": "ClaimSubmittedEvent",
    "Version": "v1",
    "ValueMaps": {
      "SubmissionId": null,
      "PolicyNumber": "[PolicyNumber]",
      "Country": "[Country]"
    },
    "ObjectMaps": {},
    "ListMaps": {}
  }
}

Where {id} is the map ID you received from POST /maps or discovered via GET /maps.

API implementation:

app.MapPut("/maps/{id}", async (string id, UpdateMapRequest request, MappingService mapper, CancellationToken cancellationToken) =>
{
    var mapResult = await mapper.SaveMappingLogicAsync(request.Map, cancellationToken);
    return new CreateMapResponse(mapResult.mapId, mapResult.map);

}).WithOpenApi();

6. Discover available mapping targets (GET /maps/targets)​

Use this endpoint to see which mapping targets are currently available (driven by the types known to MappingService):

GET /maps/targets

Example response:

[
  "ConversationHistory_Claim",
  "History_PropertyClaim",
  "PropertyClaim_ClaimSubmittedEvent"
]

API implementation:

app.MapGet("/maps/targets", (MappingService mapper) =>
{
    var targets = mapper.GetMappingTypes();
    return targets.Keys;

}).WithOpenApi();

Storage​

  • Mapping definitions are stored in an Azure Storage Account.
  • Each map is persisted as:
    • A blob object, where
    • The blob content is the mapping definition serialized as a JSON string.

This makes mappings durable and easy to inspect, back up, and restore.