MODEXPW-635 - Expose template tokens in EDIFACT email export

README.md

@@ -60,4 +60,161 @@ This value should be `true` if AWS S3 is used as storage.
 | CHUNKS                                            | 100                           | Number of items being passed to write at once                                                                                                                                                         |
 | CORE_POOL_SIZE                                    | 10                            | Maximum number of threads being created for each task before the queue is utilized                                                                                                                    |
 | MAX_POOL_SIZE                                     | 10                            | Maximum number of threads that can be created after the queue is full and before rejecting the new tasks                                                                                              |
-| BUCKET_SIZE                                       | 50                            | Size of the bucket used in partitioning parameters                                                                                                                                                    |
+| BUCKET_SIZE                                       | 50                            | Size of the bucket used in partitioning parameters                                                                                                                                                   |
+
+### Order Email — Template Context Payload
+
+This is the `context` payload sent to **mod-template-engine** when an `EDIFACT_ORDERS_EXPORT` job is transmitted by **Email**.
+
+#### Structure overview
+
+```
+OrderEmailContext
+├── createdAt                                # context build time, ISO-8601 UTC with millis (e.g. 2026-03-30T16:22:13.284Z)
+├── organization
+│   ├── name
+│   └── primaryAddress                       # address flagged isPrimary
+│       ├── addressLine1
+│       ├── city
+│       ├── zipCode
+│       └── country
+└── orders[]                                 # multiple entries
+    ├── order
+    │   ├── poNumber
+    │   ├── orderType
+    │   ├── metadata
+    │   │   └── createdByUser                # resolved from metadata.createdByUserId via mod-users
+    │   │       ├── id
+    │   │       ├── firstName
+    │   │       ├── lastName
+    │   │       └── fullName
+    │   ├── shipTo                           # resolved from shipTo UUID via tenant-addresses
+    │   │   ├── id
+    │   │   └── address
+    │   └── billTo                           # resolved from billTo UUID via tenant-addresses
+    │       ├── id
+    │       └── address
+    └── orderLines[]                         # multiple entries
+        └── orderLine
+            ├── poLineNumber
+            ├── titleOrPackage
+            ├── publisher
+            ├── publicationDate
+            ├── edition
+            ├── rush
+            ├── contributors[]               # multiple entries
+            │   ├── contributor
+            │   └── contributorNameType      # resolved type name (e.g. Personal name, Corporate name)
+            │       ├── id
+            │       └── name                 
+            ├── details
+            │   └── productIds[]             # multiple entries
+            │       ├── productId
+            │       ├── qualifier
+            │       └── productIdType        # resolved type name (e.g. ISBN, ASIN)
+            │           ├── id
+            │           └── name
+            ├── cost
+            │   ├── listUnitPrice
+            │   ├── listUnitPriceElectronic
+            │   ├── quantityPhysical
+            │   ├── quantityElectronic
+            │   ├── poLineEstimatedPrice
+            │   └── currency
+            ├── fundDistribution[]           # multiple entries
+            │   └── code                     # code taken as-is from the PO line; fundId is not resolved
+            └── vendorDetail 
+                └── instructions             # vendor instructions
+```
+> **Null/empty policy:** missing values are rendered as safe defaults rather than
+> `null`, so templates can reference any field without null checks.
+
+#### Example payload
+
+```json
+{
+  "createdAt": "2026-03-30T16:22:13.284Z",
+  "organization": {
+    "name": "GOBI Library Solutions",
+    "primaryAddress": {
+      "addressLine1": "1 Innovation Way",
+      "city": "Contoocook",
+      "zipCode": "03229",
+      "country": "USA"
+    }
+  },
+  "orders": [
+    {
+      "order": {
+        "poNumber": "10000",
+        "orderType": "One-Time",
+        "metadata": {
+          "createdByUser": {
+            "id": "7a626480-284e-5b55-9cf2-db32f93956cf",
+            "firstName": "John",
+            "lastName": "Doe",
+            "fullName": "John Doe"
+          }
+        },
+        "shipTo": {
+          "id": "11111111-1111-1111-1111-111111111111",
+          "address": "SLUB Dresden, Zellescher Weg 18, 01069 Dresden"
+        },
+        "billTo": {
+          "id": "22222222-2222-2222-2222-222222222222",
+          "address": "Accounts Payable, PO Box 42, Springfield IL"
+        }
+      },
+      "orderLines": [
+        {
+          "orderLine": {
+            "poLineNumber": "10000-1",
+            "titleOrPackage": "Introduction to FOLIO",
+            "publisher": "FOLIO Press",
+            "publicationDate": "2020",
+            "edition": "2nd",
+            "rush": false,
+            "contributors": [
+              {
+                "contributor": "Jane Author",
+                "contributorNameType": {
+                  "id": "2b94c631-fca9-4892-a730-03ee529ffe2a",
+                  "name": "Personal name"
+                }
+              }
+            ],
+            "details": {
+              "productIds": [
+                {
+                  "productId": "978-3-16-148410-0",
+                  "qualifier": "",
+                  "productIdType": {
+                    "id": "8261054f-be78-422d-bd51-4ed9f33c3422",
+                    "name": "ISBN"
+                  }
+                }
+              ]
+            },
+            "cost": {
+              "listUnitPrice": "49.99",
+              "listUnitPriceElectronic": "0.00",
+              "quantityPhysical": 2,
+              "quantityElectronic": 0,
+              "poLineEstimatedPrice": "99.98",
+              "currency": "USD"
+            },
+            "fundDistribution": [
+              {
+                "code": "USHIST"
+              }
+            ],
+            "vendorDetail": {
+              "instructions": "Deliver to loading dock, ring bell on arrival"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```       

descriptors/ModuleDescriptor-template.json

@@ -54,6 +54,10 @@
       "id": "identifier-types",
       "version": "1.2"
     },
+    {
+      "id": "contributor-name-types",
+      "version": "1.2"
+    },
     {
       "id": "ill-policies",
       "version": "1.0"

src/main/java/org/folio/dew/batch/acquisitions/jobs/MapToEdifactTasklet.java

@@ -12,6 +12,7 @@
 import static org.folio.dew.batch.acquisitions.utils.ExportUtils.validateFtpFields;
 import static org.folio.dew.domain.dto.JobParameterNames.ACQ_EXPORT_FILE;
 import static org.folio.dew.domain.dto.JobParameterNames.ACQ_EXPORT_FILE_NAME;
+import static org.folio.dew.domain.dto.JobParameterNames.ACQ_EXPORT_ORDERS;
 import static org.folio.dew.domain.dto.JobParameterNames.EDIFACT_ORDERS_EXPORT;
 import static org.folio.dew.domain.dto.VendorEdiOrdersExportConfig.TransmissionMethodEnum.EMAIL;
 
@@ -66,10 +67,10 @@ public RepeatStatus execute(StepContribution contribution, ChunkContext chunkCon
     String jobName = jobParameters.get(JobParameterNames.JOB_NAME).toString();
     var edifactStringResult = getExportResourceMapper(ediExportConfig).convertForExport(holder.orders(), holder.pieces(), ediExportConfig, jobName);
 
-    // save edifact file content and name in memory
     var stepExecution = chunkContext.getStepContext().getStepExecution();
     ExecutionContextUtils.addToJobExecutionContext(stepExecution, ACQ_EXPORT_FILE, edifactStringResult, "");
     ExecutionContextUtils.addToJobExecutionContext(stepExecution, ACQ_EXPORT_FILE_NAME, getFileName(ediExportConfig), "");
+    ExecutionContextUtils.addToJobExecutionContext(stepExecution, ACQ_EXPORT_ORDERS, ediObjectMapper.writeValueAsString(holder.orders()), "");
     return RepeatStatus.FINISHED;
   }
 

src/main/java/org/folio/dew/batch/acquisitions/jobs/SendToEmailTasklet.java

@@ -1,14 +1,17 @@
 package org.folio.dew.batch.acquisitions.jobs;
 
+import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import lombok.RequiredArgsConstructor;
 
 import lombok.SneakyThrows;
 import lombok.extern.log4j.Log4j2;
 import org.folio.dew.batch.ExecutionContextUtils;
 import org.folio.dew.batch.acquisitions.exceptions.EdifactException;
+import org.folio.dew.batch.acquisitions.mapper.OrderEmailContextMapper;
 import org.folio.dew.client.EmailClient;
 import org.folio.dew.client.TemplateEngineClient;
+import org.folio.dew.domain.dto.CompositePurchaseOrder;
 import org.folio.dew.domain.dto.EdiEmail;
 import org.folio.dew.domain.dto.VendorEdiOrdersExportConfig;
 import org.folio.dew.domain.dto.email.Attachment;
@@ -38,11 +41,13 @@ public class SendToEmailTasklet implements Tasklet {
 
   private static final String EMAIL_ERROR_MESSAGE = "Failed to send the email";
   private static final String TEMPLATE_ENGINE_ERROR_MESSAGE = "Failed to retrieve the email template";
+  private static final String EMAIL_NOT_CONFIGURED_ERROR_MESSAGE = "Failed because no email configuration has been provided";
   private static final String TEMPLATE_NOT_CONFIGURED_ERROR_MESSAGE = "Failed because no email template has been configured";
 
   private final ObjectMapper ediObjectMapper;
   private final EmailClient emailClient;
   private final TemplateEngineClient templateEngineClient;
+  private final OrderEmailContextMapper orderEmailContextMapper;
 
   @Override
   @SneakyThrows
@@ -55,13 +60,21 @@ public RepeatStatus execute(StepContribution contribution, ChunkContext chunkCon
     var stepExecution = chunkContext.getStepContext().getStepExecution();
     var fileName = (String) ExecutionContextUtils.getExecutionVariable(stepExecution, ACQ_EXPORT_FILE_NAME);
     var edifactOrderAsString = (String) ExecutionContextUtils.getExecutionVariable(stepExecution, ACQ_EXPORT_FILE);
+    var ordersJson = (String) ExecutionContextUtils.getExecutionVariable(stepExecution, ACQ_EXPORT_ORDERS);
+    var orders = ediObjectMapper.readValue(ordersJson, new TypeReference<List<CompositePurchaseOrder>>() {});
+
+    var ediEmail = Optional.ofNullable(exportConfig.getEdiEmail())
+      .orElseThrow(() -> {
+        log.error(EMAIL_NOT_CONFIGURED_ERROR_MESSAGE);
+        return new EdifactException(EMAIL_NOT_CONFIGURED_ERROR_MESSAGE);
+      });
 
     var emailEntity = new EmailEntity();
     emailEntity.setNotificationId(jobId);
-    emailEntity.setFrom(exportConfig.getEdiEmail().getEmailFrom());
-    emailEntity.setTo(exportConfig.getEdiEmail().getEmailTo());
+    emailEntity.setFrom(ediEmail.getEmailFrom());
+    emailEntity.setTo(ediEmail.getEmailTo());
 
-    var templateResult = resolveTemplate(exportConfig);
+    var templateResult = resolveTemplate(ediEmail, orders);
     emailEntity.setHeader(templateResult[0]);
     emailEntity.setBody(templateResult[1]);
     emailEntity.setOutputFormat(templateResult[2]);
@@ -72,9 +85,8 @@ public RepeatStatus execute(StepContribution contribution, ChunkContext chunkCon
     return RepeatStatus.FINISHED;
   }
 
-  private String[] resolveTemplate(VendorEdiOrdersExportConfig exportConfig) {
-    UUID templateId = Optional.ofNullable(exportConfig.getEdiEmail())
-      .map(EdiEmail::getEmailTemplate)
+  private String[] resolveTemplate(EdiEmail ediEmail, List<CompositePurchaseOrder> orders) {
+    UUID templateId = Optional.ofNullable(ediEmail.getEmailTemplate())
       .orElseThrow(() -> {
         log.error(TEMPLATE_NOT_CONFIGURED_ERROR_MESSAGE);
         return new EdifactException(TEMPLATE_NOT_CONFIGURED_ERROR_MESSAGE);
@@ -83,6 +95,7 @@ private String[] resolveTemplate(VendorEdiOrdersExportConfig exportConfig) {
     var request = TemplateProcessingRequest.builder()
       .templateId(templateId)
       .build();
+    request.setContext(orderEmailContextMapper.buildContext(orders));
 
     try {
       TemplateProcessingResponse response = templateEngineClient.processTemplate(request);