Data Exchange Formats

Files.com can receive a supplier's CSV orders and map them to JSON for your application, or prepare X12 purchase orders for a partner. Moving the file is only part of that job: the records inside it need the structure, field names, and values the receiving system understands.

In Files.com, TransformScript reads structured data, maps its fields and values, and writes the output the receiving system requires. Automations v2 places that transformation within the exchange, controlling when it runs, where the result goes, and how rejected files are handled.

Format Choice and the Data Agreement

When a partner or receiving application specifies a format, use it. When you can choose, match the format to the records: CSV suits flat tables, JSON suits nested application data, and XML or EDI fits systems with an established requirement for those representations.

Agreeing on a format is the beginning of the data specification. Two CSV files can have incompatible columns, just as two JSON files can represent the same order with different nesting. Even within one EDI standard, partners can need different mappings to give the records the meaning their systems expect.

The mapping defines which source value becomes each destination value and any conversion along the way. For example, identifiers may need to stay as text to preserve leading zeros, while quantities need conversion to numbers. Dates, time zones, currencies, and units also need agreed meanings. Changing CSV to JSON alone cannot tell the receiving system that the supplier's PartNumber belongs in its part_number field; that relationship is part of the mapping.

Transformations on Files.com

Our recommendation is to perform the mapping in Files.com when it belongs to the file exchange. A TransformScript can rename fields, normalize values, filter rows, build nested records, or flatten them for another system. The input and output format settings handle reading and writing CSV, JSON, XML, EDI, and other supported representations.

A representative input and the receiving system's expected output give you a basis for developing and checking the mapping. The one-off Transform File action lets you try it on a sample, and the TransformScript editor provides syntax checking and an AI Assistant to help write or revise the script. Before using it in a recurring workflow, compare the resulting fields and values with the receiving specification.

For an automated exchange, build a v2 Automation with these stages:

1. A File Action trigger runs in file mode on the intake folder. For a completed upload, choose Create. For a final rename to the ready filename, choose Move and a matching filename pattern. Match the trigger to the agreed readiness signal.
2. A Copy File node preserves the received original in an archive folder. Use archive paths that distinguish deliveries. The next node receives that archive copy.
3. A Transform node runs the TransformScript. Set its Destination Path to a filename in the processing-output folder so it writes a new file in the script's output format.
4. Later nodes deliver that output file, apply any required GPG encryption, or route it for further processing. For example, Copy File can deliver it to an application's folder through a Remote Server Mount.

Setting a destination makes Transform write a new file and pass it to the next node, leaving the archived input available. Without a destination, it passes data instead: a script returning an array of row objects produces one data item per row for an If or Switch node to route individually. The next step's needs determine whether to produce a file or work with individual records.

Choose the connection method separately from the data format. A shared Files.com folder and a partner's SFTP inbox can require the same CSV-to-JSON mapping. CSV, JSON, XML, and EDI do not determine the transfer protocol.

A CSV-to-JSON Mapping

Suppose a supplier uploads orders.csv with this content:

OrderID,PartNumber,Quantity
PO-1042,00127,3

Your order system needs an array of JSON records with different property names and a numeric quantity. Put this script in the Transform node:

%files 1.0
input csv
output json pretty=true
---
payload map (row) -> {
  order_id: row.OrderID,
  part_number: row.PartNumber,
  quantity: row.Quantity as Number
}

Set Destination Path to /orders/normalized/{{ attributes.name }}.json. For this input, the node writes /orders/normalized/orders.csv.json:

[
  {
    "order_id": "PO-1042",
    "part_number": "00127",
    "quantity": 3
  }
]

Because CSV fields are read as strings, the mapping explicitly converts the quantity to a number. It leaves the part number as text to preserve its leading zeros and supplies the field names the receiving system expects. These choices make the output usable by that system, beyond simply representing it as JSON.

For a recurring exchange, choose output names that distinguish deliveries, or deliberately enable overwriting when the receiver expects a fixed filename.

The same approach can read JSON and write CSV, or map an XML hierarchy into the receiving application's JSON structure. For XML, agree how elements, attributes, namespaces, and repeated records map to the destination. The TransformScript Cookbook provides further mappings to adapt.

EDI Standards and Partner Profiles

X12 and UN/EDIFACT define transaction structures. X12 uses transaction-set numbers such as 850 for a purchase order, 810 for an invoice, and 856 for a ship notice. EDIFACT uses message names such as ORDERS and INVOIC. The partner's implementation guide specifies the exact version, segments, fields, codes, and business requirements.

EDI organizes the exchange into structures that the mapping needs to account for. An interchange can contain sender and receiver envelopes, groups, and individual transactions, with ordered fields inside each segment. Control numbers connect messages with their responses, so the mapping needs to preserve them or deliberately replace them according to the agreement.

Files.com parses EDI with TransformScript. Your script can navigate X12 or EDIFACT segments and their named fields, then build JSON, CSV, XML, or another supported output. It can also produce EDI by returning the required segment structure and choosing the corresponding output format. Healthcare exchanges using HL7 v2 follow the same structured-processing approach.

For example, an Automation can receive an X12 order in an AS2 inbox, route it by partner, archive the original, and run a Transform with input x12 and output json for the order system. The X12-to-JSON workflow example shows the Files.com nodes and how the files pass between them. Partners can also exchange EDI through Connected Sites, SFTP, or another agreed transport; AS2 is a separate connection choice.

Validation and Rejected Data

Parsing makes records available to the script, but an order that parses can still be missing an identifier the receiving application requires. TransformScript's EDI definitions supply structure and field names. Checks for required values and other strict partner requirements need to be part of the workflow.

Use an If node to check required values and route a file to delivery or review. For example, require an order identifier on every CSV row before sending the file onward. Use the Transform node's Error Handling rules with Continue and a connected Error path to move files that cannot be parsed or transformed to a review folder and notify the responsible team.

Expectation Content Validation uses TransformScript to evaluate whether a delivery's contents meet your rules. It records the delivery outcome; the Automation's branches determine how files are routed during processing. Use the two together when you need both delivery monitoring and a processing decision.

Test accepted and rejected samples, including missing fields, invalid numbers, repeated identifiers, corrections, and the largest expected input. Retain the original and inspect the Automation's run detail to distinguish a failed mapping from a failed delivery. TransformScript reads files into memory and has input and output size limits, so include expected file sizes in the design.

Acknowledgments at Different Layers

Agree what each response confirms and how it relates to the original records. Files arriving, data passing validation, and an application accepting an order are separate results.

When the exchange requires an EDI acknowledgment, the workflow needs to create it, deliver it, and correlate it with the original message. The partners also need a deadline and an agreed response to rejection. An AS2 MDN reports an earlier stage and cannot replace that acknowledgment or the order system's acceptance. These responsibilities belong in the trading partner agreement.

Existing VAN Arrangements

A Value-Added Network (VAN) is an intermediary service for EDI exchange. It can provide mailboxes, routing, partner connectivity, tracking, mapping, validation, and archival services according to the provider's agreement. Businesses using the same VAN can exchange through it instead of maintaining direct connections to each other.

When moving that exchange to Files.com, identify which functions the existing service supplies. TransformScript and Automations v2 can perform the mapping and workflow you configure, while the agreed connection delivers the files. Plan the partner relationship, validation, responses, and retained records alongside that transport change. If a partner continues to require a VAN, use the provider's supported connection and service arrangement.