Zoomed Image
USA
800 691 9120
UK
01225 704844

Transformations Overview

xAssets Configuration Guide
Integration and Data Operations with Transformations

Transformations Overview

Transformations are the primary mechanism for moving, processing, and transforming data in xAssets. They connect a data source to a data destination, with optional mapping and scripting logic in between. Nearly every integration, import, export, notification, and automated task in xAssets is implemented as a transformation.

This page introduces the transformation concept and explains when and how transformations are used. Subsequent pages in this chapter cover each aspect in detail.

Prerequisites

Before working with transformations, you should be familiar with:

You need Configuration-level access or membership of a user group with transformation editing permissions to create or modify transformations.

Common Uses

Transformations serve a wide range of purposes:

Use Case Description
Data import Import records from external databases, web services, CSV files, uploaded files, or pasted data into xAssets tables
Data export Export data to files, external databases, or email recipients
Integration Synchronise with Active Directory, Azure, Intune, JAMF, OKTA, and other applications (see Integration to Specific Applications)
Data cleaning Recognise and normalise incoming data using data mapping rules and lookup tables
Business rules Validate data and enforce rules when records are saved, using database triggers
Notifications Send email notifications based on data conditions, including email merge with per-recipient content
Reports Generate a PDF report when a record is saved and display it in the browser
Form scripts Prepare data for forms before they are displayed, populating calculated fields or loading reference data
Scheduled tasks Run maintenance, synchronisation, or reporting on a schedule via the Batch Service

How Transformations Run

A transformation can be invoked in several ways, and the method of invocation determines whether the user waits for it to complete:

Method Description User Experience
Foreground Runs immediately while the user waits for completion The browser displays a progress indicator until the transformation finishes
Background (queued) Runs via the batch processor so the user can continue working The user sees a "queued" confirmation and can check progress later
Scheduled Runs automatically at a configured time via the Batch Service No user involvement; results are logged to the batch history tab
Called Invoked by the system or by another transformation (e.g., a parent AMSX script calling RunTransform) Depends on the parent context
Form load Runs automatically when a form with an associated transformation is displayed The form fields are populated before the user sees the screen
Trigger Runs automatically when a record is saved to a specific table (database trigger) Runs transparently as part of the save operation

When a transformation runs in the background, check its status at Admin > Transformations > Recent and Running Batch Jobs.

Transformation Components

Every transformation has up to six configurable areas, managed through tabs in the Transformation Editor:

  1. Data Source -- where the incoming data comes from (see Transformation Data Sources)
  2. Data Destination -- where the outgoing data goes (see Transformation Data Destinations)
  3. Data Mapping -- how source fields map to destination fields (see Source to Destination Data Mapping)
  4. Schedule -- when the transformation runs automatically
  5. Batch History -- a log of previous executions
  6. Menus -- menu items that run this transformation

Not all tabs are relevant for every transformation. For example, an AMSX script that writes data directly does not need a data destination tab, and a one-off manual import does not need a schedule.

Transformations vs. Direct API Calls

Many tasks can be achieved either through transformations or through direct REST API programming (see REST API Overview). Transformations are generally preferred because they:

  • Require no external programming environment
  • Can run on a schedule, a trigger, or from a menu item
  • Are version-controlled through the layering system
  • Include built-in error handling and batch history logging

Use the REST API when you need real-time request/response interaction from an external application, or when the calling system needs to process the response before deciding what to do next.

Tip: If you are new to transformations, start by browsing the built-in system transformations at Admin > Transformations. Many common integration patterns are already implemented and can be cloned or overridden for your specific needs.