Overview
This document outlines the configuration for automatically synchronizing Gift Card records from the Magento Gift Card entity to the iPaaS Gift Card entity. The integration uses an API-based sync that triggers whenever a Gift Card record is created in Magento.
Mapping Collection Status
Mapping Status: Enabled.
Trigger Events: The sync is triggered by the creation of Gift Cards in Magento.
ID Format: When manually syncing, the Gift Card ID from iPaaS is used. This can be resolved via an external ID.
Conflicting Mappings: This mapping applies only to Gift Cards. Ensure no other mappings target the same Magento entity to prevent data from being overwritten.
System Caveats
Magento Caveats
Gift card balances must be initialized at the time of creation in Magento.
The mapping assumes all gift cards are active upon creation; deactivated or expired cards must be managed manually in iPaaS.
iPaaS Caveats
The destination system expects a unique gift card number for each record.
iPaaS does not allow updating gift card records once created through this “Add Only” mapping.
If the same GiftCode already exists, the sync will skip that record to prevent duplication.
Setup Requirements
Magento Configuration
Ensure each Gift Card record contains valid GiftCode and is active.
iPaaS Configuration
Each Gift Card in iPaaS must have a unique Gift Card Number.
Authentication & Security
Magento2 API UserName: Used to access iPaaS API for fetching Company and related data.
Magento2 API Key: Used to access iPaaS API for fetching Company and related data.
Integration Flow
Retrieve Data: Fetch newly created gift card records from Magento.
Map Fields: Apply mapping rules and formulas to transform Magento fields into the iPaaS Gift Card format.
Apply Static Values: Assign constant values for Type and Status fields.
Transfer Data: Push mapped records to iPaaS as new entries only.
Skip Existing Records: Duplicate GiftCode entries in iPaaS are ignored to prevent overwriting.
Mappings
Gift Card
Mapping Type | Source Field (Magento) | Destination Field (iPaaS) | Description |
Field | GiftCode | Number |
|
Field | Gift Card | Type |
|
Field | Balance | Balance |
|
Field | Active | Status |
|
Dynamic Formula |
| PurchaseDate | Gets the current date and time with timezone info, then extracts and returns only the date part (year, month, day) without the time. |
Field | RecipientName | ReceivingCustomer |
|
Field | RecipientEmail | ReceivingCustomerEmail |
|
Field | SpaceportSystemId | Originating_SystemId |
|
Field | Balance | OriginalAmount |
|
Error Handling
Missing Gift Code
GiftCode not found.
Description: The source record does not include a valid GiftCode.
Resolution: Ensure every Magento gift card includes a unique GiftCode before triggering the sync.
Duplicate Gift Card
Gift card with this Number already exists in iPaaS.
Description: iPaaS prevents overwriting existing records during “Add Only” sync.
Resolution: Skip the duplicate entry or use manual update if correction is needed.
Missing Required Fields
One or more mandatory fields (GiftCode, Balance, or RecipientEmail) are missing.
Description: The record is incomplete and cannot be processed.
Resolution: Ensure all required fields are populated in Magento before syncing.
Invalid Recipient Email
Invalid email format detected.
Description: The email field does not contain a valid email format.
Resolution: Correct the recipient’s email in Magento and reinitiate the sync.
Validation Rules & Testing
Validation Checklist
GiftCode is unique and successfully created in iPaaS.
Balance and OriginalAmount match the Magento record.
PurchaseDate reflects correct creation date.
Status set to “Active” upon import.
RecipientName and RecipientEmail mapped correctly.
Test Scenarios
New Gift Card Sync: Create a new gift card in Magento and verify that it appears in iPaaS with correct Number, Balance, and PurchaseDate.
Duplicate Prevention: Attempt syncing an already existing GiftCode and ensure the system skips it without overwriting.
Email Validation: Enter an invalid recipient email in Magento and confirm that sync fails gracefully with appropriate error logging.
Balance Verification: Confirm that both Balance and OriginalAmount match expected values in iPaaS.
Additional Notes
This mapping only supports gift card creation (Add Only). Updates or balance adjustments must be handled through separate iPaaS workflows or manual processes.