The Integration Management Engine provides a set of attachment processing functions that allow you to work with file attachments in your integration mappings. These functions handle both simple attachment objects and attachments within repeater/array structures.
These functions work with single attachment objects that are direct properties in your payload.
generateAttachmentURL(fieldName)Generates a secure, time-limited download URL for an attachment.
generateAttachmentURL(fieldName)
fieldName: The name of the attachment field in your payloadA secure download URL string that can be used to download the file.
Payload Structure:
{
"applicationId": "APP123456",
"CRIMINAL_RECORD_CERTIFICATE.fileDownloadName": "C250411080713ZPMWVD_criminal_record.pdf",
"CRIMINAL_RECORD_CERTIFICATE.fileType": "application/pdf",
"CRIMINAL_RECORD_CERTIFICATE.source": "DEVICE",
"CRIMINAL_RECORD_CERTIFICATE.fileName": "criminal_record.pdf",
"CRIMINAL_RECORD_CERTIFICATE.content": "",
"CRIMINAL_RECORD_CERTIFICATE.fileSize": 45197
}
Mapping Configuration:
{
"documentUrl": "generateAttachmentURL(CRIMINAL_RECORD_CERTIFICATE)"
}
Result:
{
"documentUrl": "https://attachments.irembo.gov.rw/download/APP123456/C250411080713ZPMWVD_criminal_record.pdf?key=xyz123..."
}
Payload Structure:
{
"applicationId": "APP123456"
}
Mapping Configuration:
{
"documentUrl": "generateAttachmentURL(C250411080713ZPMWVD_criminal_record.pdf)"
}
Result:
{
"documentUrl": "https://attachments.irembo.gov.rw/download/APP123456/C250411080713ZPMWVD_criminal_record.pdf?key=xyz123..."
}
getAttachmentContent(fieldName)Retrieves the base64-encoded content of an attachment file.
getAttachmentContent(fieldName)
fieldName: The name of the attachment field in your payloadA base64-encoded string representing the file content.
Payload Structure:
{
"applicationId": "APP123456",
"PAYMENT_RECEIPT.fileDownloadName": "C250411080713ZPMWVD_receipt.pdf",
"PAYMENT_RECEIPT.fileType": "application/pdf",
"PAYMENT_RECEIPT.source": "DEVICE",
"PAYMENT_RECEIPT.fileName": "receipt.pdf",
"PAYMENT_RECEIPT.content": "",
"PAYMENT_RECEIPT.fileSize": 48584
}
Mapping Configuration:
{
"documentContent": "getAttachmentContent(PAYMENT_RECEIPT)"
}
Result:
{
"documentContent": "JVBERi0xLjQKJeLjz9MKMy..."
}
Mapping Configuration:
{
"documentContent": "getAttachmentContent(C250411080713ZPMWVD_receipt.pdf)"
}
These functions work with attachments that are nested within arrays/repeaters in your payload. They are especially useful when processing multiple attachments in a loop.
getAttachmentContentFromrepeater(repeaterName, fieldName)Retrieves the base64-encoded content of an attachment from a specific iteration of a repeater.
getAttachmentContentFromrepeater(repeaterName, fieldName)
repeaterName: The name of the array/repeater field in your payloadfieldName: The name of the attachment object within each repeater itemA base64-encoded string representing the file content for the current iteration.
CURRENT_ITERATION field indicating which array index to processPayload Structure:
{
"applicationId": "APP123456",
"CURRENT_ITERATION": 0,
"BENEFICIAL_OWNER_DETAILS": [
{
"ownerName": "John Doe",
"idDocument": {
"fileDownloadName": "C250411080713ZPMWVD_id_john.pdf",
"fileType": "application/pdf",
"source": "DEVICE",
"fileName": "id_john.pdf",
"fileSize": 45197
}
},
{
"ownerName": "Jane Smith",
"idDocument": {
"fileDownloadName": "C250411080713ZPMWVD_id_jane.pdf",
"fileType": "application/pdf",
"source": "DEVICE",
"fileName": "id_jane.pdf",
"fileSize": 38920
}
}
]
}
Mapping Configuration:
{
"beneficiaryIdContent": "getAttachmentContentFromrepeater(BENEFICIAL_OWNER_DETAILS, idDocument)"
}
Result (when CURRENT_ITERATION = 0):
{
"beneficiaryIdContent": "JVBERi0xLjQKJeLjz9MKMy..."
}
Result (when CURRENT_ITERATION = 1):
{
"beneficiaryIdContent": "JVBERi0xLjQKJe8oPzABCy..."
}
Payload Structure:
{
"applicationId": "APP123456",
"CURRENT_ITERATION": 0,
"SUPPORTING_DOCUMENTS": [
{
"documentType": "Passport",
"attachment": {
"fileDownloadName": "C250411080713ZPMWVD_passport.pdf",
"fileType": "application/pdf",
"source": "DEVICE",
"fileName": "passport.pdf",
"fileSize": 120456
}
},
{
"documentType": "Certificate",
"attachment": {
"fileDownloadName": "C250411080713ZPMWVD_cert.pdf",
"fileType": "application/pdf",
"source": "DEVICE",
"fileName": "certificate.pdf",
"fileSize": 89234
}
}
]
}
Mapping Configuration:
{
"documents": [
{
"content": "getAttachmentContentFromrepeater(SUPPORTING_DOCUMENTS, attachment)",
"type": "SUPPORTING_DOCUMENT"
}
]
}
generateAttachmentURLFromrepeater(repeaterName, fieldName)Generates a secure download URL for an attachment from a specific iteration of a repeater.
generateAttachmentURLFromrepeater(repeaterName, fieldName)
repeaterName: The name of the array/repeater field in your payloadfieldName: The name of the attachment object within each repeater itemA secure download URL string for the attachment at the current iteration.
Same as getAttachmentContentFromrepeater - requires CURRENT_ITERATION in payload.
Payload Structure:
{
"applicationId": "APP123456",
"CURRENT_ITERATION": 1,
"EMPLOYEE_DOCUMENTS": [
{
"employeeId": "EMP001",
"contract": {
"fileDownloadName": "C250411080713ZPMWVD_contract_emp001.pdf",
"fileType": "application/pdf",
"source": "DEVICE",
"fileName": "contract_emp001.pdf",
"fileSize": 156789
}
},
{
"employeeId": "EMP002",
"contract": {
"fileDownloadName": "C250411080713ZPMWVD_contract_emp002.pdf",
"fileType": "application/pdf",
"source": "DEVICE",
"fileName": "contract_emp002.pdf",
"fileSize": 145623
}
}
]
}
Mapping Configuration:
{
"contractUrl": "generateAttachmentURLFromrepeater(EMPLOYEE_DOCUMENTS, contract)"
}
Result (when CURRENT_ITERATION = 1):
{
"contractUrl": "https://attachments.irembo.gov.rw/download/APP123456/C250411080713ZPMWVD_contract_emp002.pdf?key=abc789..."
}
When using field references with generateAttachmentURL() or getAttachmentContent(), your payload must include these fields:
{fieldName}.fileDownloadName - The system-generated download filename (required, must follow pattern){fieldName}.fileType - The MIME type (e.g., "application/pdf"){fieldName}.source - The source of the file (e.g., "DEVICE"){fieldName}.fileName - The original filename{fieldName}.content - The file content (can be empty string if not using){fieldName}.fileSize - The file size in bytesWhen using getAttachmentContentFromrepeater() or generateAttachmentURLFromrepeater(), each attachment object must include:
fileDownloadName - The system-generated download filename (required, must follow pattern)fileType - The MIME typesource - The source of the filefileName - The original filenamefileSize - The file size in bytesThe attachment processor implements intelligent caching to improve performance:
attachment:url:{applicationId}:{fileDownloadName}attachment:content:{applicationId}:{fileDownloadName}Benefit: Significantly reduces processing time and external API calls when processing the same attachments multiple times.
Error Message:
Missing required attachment field fileDownloadName for DOCUMENT_FIELD
Cause: One or more required fields are missing from your payload.
Solution: Ensure all required fields are present in your payload:
{
"DOCUMENT_FIELD.fileDownloadName": "C250411080713ZPMWVD_doc.pdf",
"DOCUMENT_FIELD.fileType": "application/pdf",
"DOCUMENT_FIELD.source": "DEVICE",
"DOCUMENT_FIELD.fileName": "doc.pdf",
"DOCUMENT_FIELD.content": "",
"DOCUMENT_FIELD.fileSize": 45197
}
Error Message:
Repeater field 'ALL_ATTACHMENTS' is not a list or does not exist
Cause: The repeater field is not an array or doesn't exist in the payload.
Solution: Ensure your repeater field is an array:
{
"ALL_ATTACHMENTS": [
{ "attachment": {...} },
{ "attachment": {...} }
]
}
NOT:
{
"ALL_ATTACHMENTS": { "attachment": {...} }
}
Error Message:
Index 2 is out of bounds for repeater 'DOCUMENTS' with size 2
Cause: The CURRENT_ITERATION value exceeds the array length.
Solution: Ensure CURRENT_ITERATION is within valid range (0 to array.length - 1):
{
"CURRENT_ITERATION": 0, // Valid: 0 or 1 for array of size 2
"DOCUMENTS": [
{...},
{...}
]
}
Error Message:
Attachment field 'document' is not found or not a map in repeater item at index 0
Cause: The specified field doesn't exist in the repeater item or is not an object.
Solution: Ensure the attachment field exists as a nested object:
{
"REPEATER": [
{
"document": { // This must be an object
"fileDownloadName": "...",
"fileType": "..."
}
}
]
}
Use Case: Submit a single criminal record certificate with its content.
Payload:
{
"applicationId": "APP123456",
"applicantName": "John Doe",
"CRIMINAL_RECORD.fileDownloadName": "C250411080713ZPMWVD_criminal_record.pdf",
"CRIMINAL_RECORD.fileType": "application/pdf",
"CRIMINAL_RECORD.source": "DEVICE",
"CRIMINAL_RECORD.fileName": "criminal_record.pdf",
"CRIMINAL_RECORD.content": "",
"CRIMINAL_RECORD.fileSize": 45197
}
Mapping:
{
"applicantName": "applicantName",
"documentUrl": "generateAttachmentURL(CRIMINAL_RECORD)",
"documentContent": "getAttachmentContent(CRIMINAL_RECORD)"
}
Output:
{
"applicantName": "John Doe",
"documentUrl": "https://host/download/APP123456/C250411080713ZPMWVD_criminal_record.pdf?key=xyz...",
"documentContent": "JVBERi0xLjQKJeLjz9MKMy..."
}
Use Case: Submit multiple payment receipts from a repeater.
Original Payload Structure (Your Case):
{
"applicationId": "APP123456",
"ALL_ATTACHMENTS": [
{
"source": "DEVICE",
"content": "",
"fileName": "B250804180655F2BZXX_payment_receipt.pdf",
"fileSize": 45197,
"fileType": "application/pdf",
"uploadResponse": {
"data": {
"fileDownloadName": "B250804180655F2BZXX_payment_receipt_1764783219509_64366.pdf"
}
},
"fileDownloadName": "B250804180655F2BZXX_payment_receipt_1764783219509_64366.pdf"
},
{
"source": "DEVICE",
"content": "",
"fileName": "B250804220529NFC8XX_payment_receipt.pdf",
"fileSize": 48584,
"fileType": "application/pdf",
"uploadResponse": {
"data": {
"fileDownloadName": "B250804220529NFC8XX_payment_receipt_1764783238069_57115.pdf"
}
},
"fileDownloadName": "B250804220529NFC8XX_payment_receipt_1764783238069_57115.pdf"
}
]
}
Problem: The attachment data is at the root level of each array item, not nested.
Solution 1: Restructure the Payload (Recommended)
{
"applicationId": "APP123456",
"CURRENT_ITERATION": 0,
"ALL_ATTACHMENTS": [
{
"attachment": {
"source": "DEVICE",
"fileName": "B250804180655F2BZXX_payment_receipt.pdf",
"fileSize": 45197,
"fileType": "application/pdf",
"fileDownloadName": "B250804180655F2BZXX_payment_receipt_1764783219509_64366.pdf"
}
},
{
"attachment": {
"source": "DEVICE",
"fileName": "B250804220529NFC8XX_payment_receipt.pdf",
"fileSize": 48584,
"fileType": "application/pdf",
"fileDownloadName": "B250804220529NFC8XX_payment_receipt_1764783238069_57115.pdf"
}
}
]
}
Mapping:
{
"receipts": [
{
"receiptUrl": "generateAttachmentURLFromrepeater(ALL_ATTACHMENTS, attachment)",
"receiptContent": "getAttachmentContentFromrepeater(ALL_ATTACHMENTS, attachment)"
}
]
}
Use Case: Submit company beneficial owners, each with ID and proof of address.
Payload:
{
"applicationId": "APP123456",
"CURRENT_ITERATION": 0,
"BENEFICIAL_OWNERS": [
{
"ownerName": "John Doe",
"idDocument": {
"fileDownloadName": "C250411080713ZPMWVD_id_john.pdf",
"fileType": "application/pdf",
"source": "DEVICE",
"fileName": "id_john.pdf",
"fileSize": 45197
},
"proofOfAddress": {
"fileDownloadName": "C250411080713ZPMWVD_address_john.pdf",
"fileType": "application/pdf",
"source": "DEVICE",
"fileName": "address_john.pdf",
"fileSize": 38920
}
},
{
"ownerName": "Jane Smith",
"idDocument": {
"fileDownloadName": "C250411080713ZPMWVD_id_jane.pdf",
"fileType": "application/pdf",
"source": "DEVICE",
"fileName": "id_jane.pdf",
"fileSize": 42315
},
"proofOfAddress": {
"fileDownloadName": "C250411080713ZPMWVD_address_jane.pdf",
"fileType": "application/pdf",
"source": "DEVICE",
"fileName": "address_jane.pdf",
"fileSize": 51204
}
}
]
}
Mapping:
{
"beneficialOwners": [
{
"name": "ownerName",
"documents": {
"identityCard": "getAttachmentContentFromrepeater(BENEFICIAL_OWNERS, idDocument)",
"proofOfAddress": "getAttachmentContentFromrepeater(BENEFICIAL_OWNERS, proofOfAddress)",
"idCardUrl": "generateAttachmentURLFromrepeater(BENEFICIAL_OWNERS, idDocument)",
"addressProofUrl": "generateAttachmentURLFromrepeater(BENEFICIAL_OWNERS, proofOfAddress)"
}
}
]
}
Output (when CURRENT_ITERATION = 0):
{
"beneficialOwners": [
{
"name": "John Doe",
"documents": {
"identityCard": "JVBERi0xLjQKJeLjz9MKMy...",
"proofOfAddress": "JVBERi0xLjQKJe8oPzABCy...",
"idCardUrl": "https://attachments.irembo.gov.rw/download/APP123456/C250411080713ZPMWVD_id_john.pdf?key=...",
"addressProofUrl": "https://attachments.irembo.gov.rw/download/APP123456/C250411080713ZPMWVD_address_john.pdf?key=..."
}
}
]
}
If an attachment function fails, it throws a ServerErrorException with one of these error codes:
ATTACHMENT_URL_GENERATION_FAILEDATTACHMENT_CONTENT_RETRIEVAL_FAILEDATTACHMENT_MISSING_REQUIRED_FIELD_ERRORATTACHMENT_PROCESSING_ERRORMonitor logs for detailed error messages.
For large files:
generateAttachmentURL() instead of getAttachmentContent() when possible| Function | Purpose | Works With | Requires CURRENT_ITERATION |
|---|---|---|---|
generateAttachmentURL(field) |
Generate download URL | Simple attachments | No |
getAttachmentContent(field) |
Get base64 content | Simple attachments | No |
generateAttachmentURLFromrepeater(repeater, field) |
Generate URL from array | Repeater attachments | Yes |
getAttachmentContentFromrepeater(repeater, field) |
Get content from array | Repeater attachments | Yes |