MODEXPW-635 - Expose template tokens in EDIFACT email export

[markusweigelt]

MODEXPW-635
- Expose template tokens in EDIFACT email export

Purpose

Make order, order-line, and vendor-organization data available as {{token}} placeholders in the email templates rendered for the EDIFACT email export. Before this change, SendToEmailTasklet invoked TemplateEngineClient.processTemplate with templateId + lang + outputFormat but no context payload, so templates couldn't reference any order data — only the static template body reached the recipient.

Approach

Ship the worker a structured context object that mod-template-engine substitutes against the configured template.

1. Context payload shape

  {
    "createdAt": "...",
    "organization": { name, primaryAddress: { addressLine1, city, zipCode, country } },
    "orders": [
      {
        "order": {
          poNumber, orderType,
          metadata: { createdByUser: { id, firstName, lastName, fullName } },
          shipTo: { id, address },
          billTo: { id, address }
        },
        "orderLines": [
          { "orderLine": { poLineNumber, titleOrPackage, publisher, publicationDate, edition, rush,
                           contributors: [ { contributor, contributorNameType: { id, name } } ],
                           details: { productIds: [ { productId, qualifier, productIdType: { id, name } } ] },
                           cost: { listUnitPrice, listUnitPriceElectronic,
                                   quantityPhysical, quantityElectronic,
                                   poLineEstimatedPrice, currency },
                           fundDistribution: [ { code } ],
                           vendorDetail: { instructions } } }
        ]
      }
    ]
  }

2. Token surface exposed to templates

• createdAt
• organization.*: name, primaryAddress.{addressLine1, city, zipCode, country}
• order.*: poNumber, orderType, metadata.createdByUser.{id, firstName, lastName, fullName}, shipTo.{id, address}, billTo.{id, address}
• orderLine.*: poLineNumber, titleOrPackage, publisher, publicationDate, edition, rush, contributors[].{contributor, contributorNameType.{id, name}}, details.productIds[].{productId, qualifier, productIdType.{id, name}}, cost.{listUnitPrice, listUnitPriceElectronic, quantityPhysical, quantityElectronic, poLineEstimatedPrice, currency}, fundDistribution[].code, vendorDetail.instructions

3. Resolutions performed by context mapper

OrderEmailContextMapper.buildContext(orders) is the single entry point. It walks each CompositePurchaseOrder, pairs each PoLine with its own parent order (so multi-order exports don't leak the first order's poNumber onto later lines), and resolves the following FOLIO lookups before handoff:

• createdAt — generated at build time in ISO-8601 UTC.
• order.metadata.createdByUser — resolved from metadata.createdByUserId via new UserService.getUserContext(...) into a UserContext {id, firstName, lastName, fullName}; fullName is "firstName lastName" trimmed, falling back to username.
• order.shipTo / order.billTo — address UUID resolved to a TenantAddressContext {id, address} via ConfigurationService.getTenantAddress(...).
• orderLine.contributors[].contributorNameType.name — UUID → type name (e.g. Personal name) via cached ContributorNameTypeService.getContributorNameTypeName(uuid).
• orderLine.details.productIds[].productIdType.name — UUID → type name (e.g. ISBN) via cached IdentifierTypeService.getIdentifierTypeName(uuid).
• orderLine.fundDistribution[] — exposes only the fund code, taken as-is from the PO line (fundId is not resolved; expenseClassId, distributionType, and value are not exposed).
• organization — resolved from the order vendor via OrganizationsService; primary address picked with a strict isPrimary == true filter.
• Null-safe throughout: missing leaf strings fall back to "", quantities to 0, lists to [], and unresolved sub-objects (Cost, VendorDetail, metadata, vendor, addresses) to empty contexts.

Additional information

Example plain-text template body of mod-template-engine exercising every token:

Created at: {{createdAt}}

Organization: {{organization.name}}
  {{organization.primaryAddress.addressLine1}}
  {{organization.primaryAddress.city}}, {{organization.primaryAddress.zipCode}}
  {{organization.primaryAddress.country}}

{{#orders}}
==================================================
PO Number:  {{order.poNumber}}
Order Type: {{order.orderType}}
Created by: {{order.metadata.createdByUser.fullName}} ({{order.metadata.createdByUser.firstName}} {{order.metadata.createdByUser.lastName}}, id={{order.metadata.createdByUser.id}})

Ship To: {{order.shipTo.address}}   (id={{order.shipTo.id}})
Bill To: {{order.billTo.address}}   (id={{order.billTo.id}})

Order Lines:
{{#orderLines}}
  --------------------------------------------------
  PO Line:        {{orderLine.poLineNumber}}
  Title/Package:  {{orderLine.titleOrPackage}}
  Publisher:      {{orderLine.publisher}}
  Publication:    {{orderLine.publicationDate}}
  Edition:        {{orderLine.edition}}
  Rush:           {{orderLine.rush}}

  Contributors:
  {{#orderLine.contributors}}
    - {{contributor}} [{{contributorNameType.name}} / {{contributorNameType.id}}]
  {{/orderLine.contributors}}

  Product IDs:
  {{#orderLine.details.productIds}}
    - {{productId}} {{qualifier}} [{{productIdType.name}} / {{productIdType.id}}]
  {{/orderLine.details.productIds}}

  Cost:
    List Unit Price:            {{orderLine.cost.listUnitPrice}}
    List Unit Price (Electr.):  {{orderLine.cost.listUnitPriceElectronic}}
    Quantity Physical:          {{orderLine.cost.quantityPhysical}}
    Quantity Electronic:        {{orderLine.cost.quantityElectronic}}
    PO Line Estimated Price:    {{orderLine.cost.poLineEstimatedPrice}}
    Currency:                   {{orderLine.cost.currency}}

  Fund Distribution:
  {{#orderLine.fundDistribution}}
    - {{code}}
  {{/orderLine.fundDistribution}}

  Vendor Instructions: {{orderLine.vendorDetail.instructions}}
{{/orderLines}}
{{/orders}}

Depends on

PR #732 - MODEXPW-625 - Enable Email Delivery for EDIFACT Export Jobs

[markusweigelt]

@markusweigelt please fix the merge conflicts first before we continue reviewing.

@SerhiiNosko I hope you're getting through the heat well. 🥵 Besides merging master, we also optimized the actual changes.

[markusweigelt]

@SerhiiNosko Thx for the review of this hugh PR and your approval! Can I merge this PR? There was still a question regarding caching. I would merge the Spring PR in the same step.

[SerhiiNosko]

@SerhiiNosko Thx for the review of this hugh PR and your approval! Can I merge this PR? There was still a question regarding caching. I would merge the Spring PR in the same step.

by the way, locally did you check functionality with eureka-cli?

[markusweigelt]

by the way, locally did you check functionality with eureka-cli?

Yes, we have a development system based on the Eureka CLI, and we have already tested the placeholder replacement there. We haven’t checked the permissions in the PR folio-org/mod-data-export-spring#380 yet - I’ll take care of that right away. But this should only be a formality.

[SerhiiNosko]

by the way, locally did you check functionality with eureka-cli?

Yes, we have a development system based on the Eureka CLI, and we have already tested the placeholder replacement there. We haven’t checked the permissions in the PR folio-org/mod-data-export-spring#380 yet - I’ll take care of that right away. But this should only be a formality.

lets merge then, also for future you can create story to cover this functionality wit karate tests, karate tests are executed every night and do real testing of services without any mocks and always help us to find new bugs. In this case we will make sure that this newly implemented functionality always work as expected.
Here is folder where our existing karate tests live: https://github.com/folio-org/folio-integration-tests/tree/master/acquisitions/src/main/resources/thunderjet/mod-data-export-spring

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
96.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud