Testing a transformation change before you save it

Run a transformation change against an example payload and review the diff before it goes live.

When to use this

Use this guide when you are changing a transformation — the logic that maps data from a source system to a destination — and want to know what your change does before it reaches live data. A saved transformation applies to the next event that runs through the stream, so a mistake shows up in your destination system rather than on screen.

The transformation editor gives you two ways to check a change first: Preview output runs it against an example payload, and Review changes shows what you have altered against what is currently saved.

Before you start

  • You need the Owner role. Operators and Viewers cannot edit configuration. See Managing users and permissions.

  • Have an example payload ready. The most realistic one is the payload in from an event that has already run through the stream — see "Getting an example payload" below.

  • For what the transformation JSON itself can do, see Write a custom transformation.

Steps

Getting an example payload

  1. Go to Events and open an event that ran through the stream you are changing.

  2. Scroll to File storage.

  3. Use the copy icon next to payload_in.json, or Download it.

These files are kept for a default of 30 days, so pick a recent event.

Testing the change

  1. Go to Transformations, find the transformation and click the edit icon.

  2. Make your change under Advanced (JSON).

  3. Open the Preview output tab.

  4. Paste your example into Example payload in.

  5. Click Run. The result appears under Payload out. This is a test run only: nothing is saved and nothing is sent to the destination system.

  6. Compare the output with what the destination expects. Adjust the JSON and run it again as many times as you need.

Checking what you have changed

  1. Open the Review changes tab. It shows Saved beside Your changes.

  2. Confirm that the only differences are the ones you meant to make. If it reports no changes, nothing you have done has altered the content.

Saving

  1. Click Update Transformation to save and close, or Update & Continue Editing to save and carry on working.

  2. To abandon the change, click Cancel. Nothing you typed is kept.

What you should see

  • A successful test run fills Payload out with the transformed payload. Until you run one it reads "Run the transformation to see the output here."

  • After saving, the change applies to events that run through the stream from that point on. Events that have already been processed are unaffected.

  • The save is recorded on the Actions page, with your name against it. See Reviewing account activity in Actions.

If it did not work

The test run returns an error or nothing useful. Check that the example is valid JSON and that it is a source payload rather than a payload out. A payload copied from the wrong stream will not have the fields the transformation expects.

Review changes reports no changes. Your edit was not applied to the content — check you are on the Advanced (JSON) tab and that the change is still there.

You can see Advanced (JSON) but not the visual builder. The builder is limited to HC administrators for now. The JSON editor is the supported route, and both test tabs work the same way with it.

You cannot edit the transformation. Only Owners can change configuration. Ask the Owner for your organisation, or raise it with HC: see Requesting a mapping change.

How it works

A test run happens in isolation. The transformation is applied to the example you pasted and the result is shown back to you; no event is created, nothing is written to a destination system, and the saved transformation is untouched until you click Update Transformation.

Saving does not reprocess anything. If you want events that already failed or ran under the old logic to go through the new version, replicate them.

If the change is one you would rather HC made — a complex mapping, a change with financial consequences, or anything you are not confident testing yourself — raise it instead of editing. See Requesting a mapping change.