More About Magic xpi

Single vs. Complex Elements

The Data Mapper classifies every element it sees into one of two camps:

You can map:

• One source complex element to one destination complex element — the destination iterates the same number of times as the source.
• Multiple source simple elements to one destination simple element (XML or Template only).
• A source complex element to a flow-variable complex element.
• Most siblings — with caveats covered below.

Simple data mapping is automatic — no expression required.

Automatic Parent Mapping

When you connect simple elements without first connecting their parents, Magic xpi auto-connects the nearest parent compound on each side whose Max occurrences is greater than 1. You've relied on this all course long.

When the immediate parent's Max occurrences equals 1, Magic xpi keeps walking up the tree until it finds a parent with Max occurrences > 1. That's the auto-connected parent — you'll see it as a connection drawn one or two levels above where you expected.

Complex Element Mapping

Complex mappings are driven by:

• The destination element's data expression — flow variables, functions, and connected simple source elements.
• External code via the Expression Editor — Java, uniPaaS, or DLL calls.

Cross mapping is when an existing complex-element line forces a sibling source element to map across it to a different destination parent. Magic xpi handles it automatically — you'll see the line cross visually and the auto-connected parent shift.

Sibling mapping is more constrained: connecting two simple sibling sources to two different destination parents fails, because the Data Mapper can't tell how many iterations to execute on the sibling. The fix is to add a Single Instance Filter expression on one of the source compounds (e.g. 'TRUE'LOG) to mark it as effectively single — or to change the schema so Max occurrences is 1.

Data Mapper Best Practices

The Data Mapper is powerful but not free. Use it when you need the mapping; reach for lighter tools when you don't:

• Use the Flow Data utility, not the Data Mapper, when you only need to update a variable.
• Use the Data Mapper's Call Flow only when iterating over many records. For a single call, the Invoke Flow utility is cheaper.
• For temporary data, prefer a BLOB variable over the ODS — the ODS persists to a database table and pays for that durability with overhead.

Runtime considerations

• If a compound node has both a condition and an update expression, the update expression runs regardless of the condition. Side-effects on variables in that expression always happen.
• The Data Mapper executes destinations in a defined order:
  • Same-time: Database, Flat File, Variable, ODS, Call Flow, UDS.
  • Individual: XML, JSON, Template.
  Reordering destinations can change the execution order, which can matter when one destination depends on another.

Email Component XML Configuration

Most components are configured via Direct Access Method. Some — or some scenarios — need the XML interface instead. A typical case: send a single email step's content to a list of addresses kept in a flat file.

To configure the Email component via XML:

1. On the Process Request flow, add an Email child of Add Delivery Details; name it Send Confirmation emails.
2. Set Processing Mode to Parallel.
3. Set Interface to XML.
4. Open the configuration. In the Destination Tree, an IFC_Email entry appears automatically — that's the XML schema for the component.

Now feed it a flat-file source:

1. Drag a Flat File source named FetchMailList; Source Type File; File Path EnvVal ('currentprojectdir') & 'course_data\Files\emails.txt'; Include Delimiter Yes.
2. Define the columns: FirstName Alpha 30, LastName Alpha 30, email Alpha 255 — comma delimited.
3. In the destination tree, open the QuickSend node; connect email → To; set OrderIndex to 1; set Subject to a literal; set Body to 'Good day ' & Src.S1/Record/FirstName & ',' & ASCIIChr (10) & 'Please follow up on Request ' & Str (F.RequestNum,'5').

User Defined Storage (UDS)

The ODS has two limitations: its structure is fixed, and it lives in a database table with all the overhead that implies. UDS — User Defined Storage — addresses both. You define the structure yourself, and the data lives in memory inside a BLOB.

To define a UDS structure:

1. Open the Repositories section of the Solution Explorer and double-click UDS (or press Shift+F10).
2. On the left, click Add and name the structure AuditTrail.
3. On the right, click Add three times to define columns:
   • TimeStamp — Alpha 20, Index ticked.
   • CustomerId — Numeric 5.
   • RequestNum — Numeric 5.

UDS structures show up as flow variable types:

1. In a flow, double-click Flow Variables and add a variable named Audit_trail.
2. Open the Type dropdown — pick U.AuditTrail.

You can now drag a UDS destination into a Data Mapper, point its Variable at F.Audit_Trail, and connect the columns. Use DStr (Date (), 'DD/MM/YYYY') & ' ' & TStr (Time (), 'HH:MM:SS') as the calculated value for TimeStamp.

Exercise

Summary

You should now be able to:

• Tell single from complex elements in the Data Mapper, and predict how parents will be auto-mapped.
• Use cross-mapping and sibling-mapping correctly — including the Single Instance Filter trick.
• Choose the right tool for the job: Flow Data, Invoke Flow, or Data Mapper; BLOB, ODS, or UDS.
• Configure a component via its XML interface and feed it from a flat-file source.
• Define a UDS structure, base a flow variable on it, and read/write it from the Data Mapper.

That's the end of the course. Welcome to Magic xpi 4.14.1 — you have everything you need to start building real integration projects.