Test and validate transformations in Jitterbit Integration Studio

Introduction

Testing and validating transformations helps ensure that your data mappings work correctly before deploying them in production. Jitterbit Integration Studio provides several methods to test transformations:

• Preview: Test transformations with sample data in a read-only interface.
• Validation checks: Identify and resolve mapping errors before deployment.
• Sample data testing: Upload files or use live data to verify transformation logic.

Preview

Preview provides a read-only interface for testing how transformations process data. This includes inline data display on source and target fields and controls for interacting with the preview interface.

In Preview, you cannot edit transformation configurations such as adding, editing, or deleting mappings. When you attempt to edit a transformation in Preview, you automatically return to the transformation configuration.

Transformation preview processing

When configuring a transformation preview, you can provide sample data in two ways:

1. User-provided sample data
2. Operation-provided sample data

User-provided sample data

You upload sample data to use for the transformation preview when you configure it. This method is available in these scenarios:

• A transformation has a source schema defined within an adjacent activity, except for a Database Query activity
• A transformation has a source schema defined within the transformation (with or without an adjacent source activity)

This option is described in Select sample data.

Operation-provided sample data

The sample data is fetched from the operation for certain endpoints. This method is available when:

• A transformation has an adjacent Database Query activity. You can apply an additional WHERE clause to limit the number of records retrieved for preview purposes. This option is described in Database Query activity.
• A transformation has an adjacent NetSuite, Salesforce, Salesforce Service Cloud, or ServiceMax activity as either a source or target activity. These options are described in NetSuite activity and Salesforce activities.

Preview displays sample data as it will be written to the transformation target using any scripts specified within the transformation. In general, downstream steps in the same operation or downstream operations themselves are not executed unless they are called within a transformation script.

For example, operations, scripts, email notifications, or plugins called in a transformation using functions such as RunOperation(), RunScript(), SendEmailMessage(), or RunPlugin() are executed because they are part of the transformation. Plugins that are applied on activities are not executed during a transformation preview because they are not part of the transformation.

The limit on individual record size while previewing a transformation is 384 KB compressed, or approximately 512 KB uncompressed. There is no limit on record sizes at operation runtime.

Important: There is an exception to the execution of steps downstream of a transformation. This exception applies only if you are previewing a transformation that has a target schema defined from a NetSuite, Salesforce, Salesforce Service Cloud, or ServiceMax target activity. In this scenario, regardless of where the source data originates, sample data is written to the target.

Availability of Preview

Preview is available only when the transformation has both a source and target schema specified. The source and target schemas may be defined by an adjacent activity of any endpoint type or defined in a transformation.

Preview cannot be used on source files or data in XSD or ZIP format because values are not present in these file types. An XML file that implements XSD can be used.

Access Preview

When Preview is available, a Preview icon is displayed within the transformation toolbar.

You then provide input to configure the transformation preview, as described in the following sections.

Configure a transformation preview

The transformation preview configuration process guides you through setting up a transformation to preview. The specific areas shown in the preview configuration depend on these criteria:

• Transformations that depend on components that have not yet been deployed show Required Components as the first configuration step, described in Deploy dependencies.
• All previewable transformations, except for those with an adjacent Database Query activity, show an area called Select Sample Data, described in Select sample data. The Select Sample Data area may be shown in a step by itself or, if the transformation has an adjacent NetSuite, Salesforce, Salesforce Service Cloud, or ServiceMax activity, the option Preview Using Sample File must first be selected to show this area.
• Transformations with an adjacent Database Query activity show Define the WHERE Clause as the next step, described in Database Query activity.
• Transformations with an adjacent NetSuite activity (either as a source or target) provide the options to Preview Using Source Data or Preview Using Sample File, described in NetSuite activity. When the target of the transformation is a NetSuite activity, sample data is written to the target.
• Transformations with an adjacent Salesforce, Salesforce Service Cloud, or ServiceMax activity (either as a source or target) provide the options to Preview Using Source Data or Preview Using Sample File, described in Salesforce activities. When the target of the transformation is a Salesforce, Salesforce Service Cloud, or ServiceMax activity, sample data is written to the target.

Deploy dependencies

The Required Components step is present only if you have not yet deployed all operations that the transformation is dependent on. If you have already deployed all operations that the transformation depends on, the first step is based on the other criteria listed at the beginning of this section.

When the transformation and all dependencies are valid, this step appears as shown below:

• Required Components: Review the components that will be deployed when you click Next.

• Next: Click to deploy the components in the list and continue to the next step.

  Note

  Under certain circumstances, additional screens may be presented. Refer to Operation deployment for a description of these screens: - Select Schedules and Project Variables: If there are any project variables or schedules being deployed that have already been deployed in the Harmony cloud, a screen presents you with options for selecting which values to use. - Add Tags and Comments: If project-level deployment settings have been configured to require a tag or comment on deploying, a dialog is presented to enter the required tag or comment.

• Cancel: Click to close the preview configuration screen and return to the transformation without previewing data.

If the transformation or any dependencies are invalid, they are identified in the list and the Next button is disabled. Cancel or close out of the preview configuration screen to correct the validity of any invalid components before attempting to preview the transformation again. For information on validity, see Transformation mapping validity and Component validity.

Select sample data

All previewable transformations, except for those with an adjacent Database Query activity, show an area called Select Sample Data. The Select Sample Data area may be shown in a step by itself or, if the transformation has an adjacent NetSuite, Salesforce, Salesforce Service Cloud, or ServiceMax activity, the option Preview Using Sample File must first be selected to show this area.

• Select Sample Data: Select one of the options to provide sample data to preview in the transformation. The contents and file format of the sample file should be compatible with the source schema (XSD and ZIP files are not supported).

  Note

  If the file is in an invalid format, a generic error message indicates a "sampleDataLoadFailure". Potential causes of an invalid format include a CSV file missing the header, a JSON file missing a closing quote, an XML file missing a closing tag, and so on.

  • Upload New File to Test: Use the Browse button to the right of the field below to browse to a file that has not yet been used for transformation testing in the current project. Though files up to 1.2 MB can be uploaded, note that the sample data used for transformation preview processing has a size limitation of 51,200 bytes. These limits apply only for this preview testing.

    To generate a valid sample file for a transformation that uses a NetSuite, Salesforce, Salesforce Service Cloud, or ServiceMax activity:

    1. Use Create Mock Data from Source Structure to generate a sample record.
    2. Change the view of the transformation by clicking the sample file icon to view the sample source data and the target file with sample data that would be generated if the transformation were to run. This view includes additional tags that are not generated by mirroring a schema.
    3. Copy and paste the content from the source or target side (as appropriate) to a new file.
    4. Make any edits to the new file as necessary, such as editing particular fields or adding or removing records.
    5. Provide the new file using Upload New File to Test.

  • Select Previously Loaded File to Test: Use the dropdown in the field below to select from an existing file that has previously been used for transformation testing in the current project.

  • Create Mock Data from Source Structure: Select to generate random data based on the structure of the source schema.

• Finished: Click to load the sample data, retrieve the transformed data from Harmony, and continue on to the transformation preview screen, covered later in Preview a transformation.

  Caution: Uploaded source files used for previewing a transformation are periodically removed from Harmony. In this case, you may receive an error indicating that no source file is available for testing or the source file may have expired. To resolve, reupload the file and try again.

• Cancel: Click to close the preview configuration screen and return to the transformation without previewing data.

Database Query activity

The Define the WHERE Clause step is displayed when the transformation uses a source with a schema defined from a Database Query activity.

• Define the WHERE Clause: The existing query is used to provide the sample data for the preview. In this step, you can further limit what sample data is loaded by providing a WHERE clause.

  • Original SQL: If created from a single-object query using the wizard or a manual query, the original SQL statement used within the source activity is listed for reference. The Original SQL will not be displayed for a multiple-object query using the wizard.
  • Original WHERE Clause: The original WHERE clause, if present, is listed for reference.

  • WHERE Clause to Be Used in This Preview (Optional): If desired, enter a WHERE clause to be applied for purposes of previewing the transformation. This can be used to limit the number of records retrieved for preview purposes. If you have an original WHERE clause, then another WHERE clause provided here is used in addition to the original clause, which is not overwritten.

    Note

    The syntax used for the WHERE clause is case-sensitive, and must use the appropriate quote identifier of the specific database type. There are examples of WHERE clauses in the how-to pages describing how to connect to commonly-used databases.

• Finished: Click to load the sample data, retrieve the transformed data from Harmony, and continue on to the transformation preview screen, covered later in Preview a transformation.

• Cancel: Click to close the preview configuration screen and return to the transformation without previewing data.

NetSuite activity

When a transformation has an adjacent NetSuite activity (either as a source or target), the step provides the options to Preview Using Source Data or Preview Using Sample File. The option Preview Using Sample File shows the area Select Sample Data, described in Select sample data earlier on this page.

When Preview Using Source Data is selected, the text Please Click on Finish to Run the Operation and Get Preview Data is displayed.

• Finished: Click to fetch sample data directly from the source, retrieve the transformed data from Harmony, and continue on to the transformation preview screen, covered later in Preview a transformation.
• Cancel: Click to close the preview configuration screen and return to the transformation without previewing data.

Salesforce activities

When a transformation has an adjacent Salesforce, Salesforce Service Cloud, or ServiceMax activity (either as a source or target), the step provides the options to Preview Using Source Data or Preview Using Sample File. The option Preview Using Sample File shows the area Select Sample Data, described in Select sample data earlier on this page.

What is shown for the option Preview Using Source Data depends on whether the activity is a source or target activity for the transformation.

Source activity

If the Salesforce, Salesforce Service Cloud, or ServiceMax activity is a Query activity and is used as the source for the transformation, the SOQL statement and original WHERE clause are displayed.

• SOQL: Review the existing query statement from the activity, which is used to provide the sample data for the preview.

  • Original WHERE Clause: Review the existing WHERE clause, if present, which is used to limit the sample data to preview in the transformation.

  Note

  This step is for informational purposes only. The original SOQL and WHERE clause cannot be edited or further restricted.

• Finished: Click to fetch sample data directly from the source, retrieve the transformed data from Harmony, and continue on to the transformation preview screen, covered in Preview a transformation.

• Cancel: Click to close the preview configuration screen and return to the transformation without previewing data.

Target activity

If the Salesforce, Salesforce Service Cloud, or ServiceMax activity is an activity other than a Query activity and is used as the target of the transformation, the text Please Click on Finish to Run the Operation and Get Preview Data is displayed.

• Finished: Click to fetch sample data directly from the source, retrieve the transformed data from Harmony, and continue on to the transformation preview screen, covered in Preview a transformation.
• Cancel: Click to close the preview configuration screen and return to the transformation without previewing data.

Preview a transformation

A read-only transformation screen loads in Preview.

Preview displays data from the provided sample file or query inline next to each source field and each mapped target field:

In Preview, the transformation toolbar provides a set of tools for interacting with the preview interface:

• Sample Data: The name of the currently loaded sample file or query activity is displayed. Click the sample file or query activity to show options to clear or change the sample data, described in Clear or change sample data.

• Record Cycle: Click the left and right arrows to cycle through records within the sample data file or query data, updating the preview data readout. The first number indicates which record data is currently displayed in the transformation preview, out of the total number of records available in the sample file or query.

• Undo: Click the undo icon to reverse your last action (see Undo and redo in Integration Studio permissions, collaboration, and saving).

• Redo: Click the redo icon to reverse your last Undo action (see Undo and redo in Integration Studio permissions, collaboration, and saving).

• Inline Data: Click the inline data icon to view the inline preview of data. This is the default view.

• Sample Files: Click the sample files icon to view the sample source data and the target file with sample data that would be generated if the transformation were to run.

• Close: Click the close icon to exit out of Preview and return to the transformation configuration screen.

Visual indicators of mapped fields

When you view mapped objects in the Source or Variables tabs, a number indicates how many times each object is referenced on the target side of the transformation. Click the number to see the target path in a tooltip.

In addition, when you hover over a source object, lines appear that connect the source field to any target fields it is mapped to or nodes it is referenced within.

When you view mapped objects within the Target structure, hovering over the field shows a line that connects the mapped target field to its origins in the Source or Variables tabs, if applicable. Click the mapped source object to automatically go to the object in the tab.

Clicking the name of a mapped target object collapses it so that its mapped objects are not visible.

Tip: If a collapsed node contains target field mappings, that node is shown in bold to indicate it contains mappings.

Clear or change sample data

Click the name of the sample file or query activity to show options to clear or change the sample data:

• Clear: Click to remove the sample file data or query data and return to the transformation configuration screen.

• Change: Click to replace the sample file data or query data. The behavior depends on how the sample data has been defined:

  • Sample File: If using a sample file, this returns you to the sample data selection step to select another file.

  • Database Query: If using a Database Query activity, this returns you to the WHERE clause definition step to modify the WHERE clause.

  • Salesforce Query: If using a Salesforce, Salesforce Service Cloud, or ServiceMax Query activity, this returns you to step 2 of the configuration of that activity to modify the query statement. See Salesforce query, Salesforce Service Cloud query, or ServiceMax Query activity.

Validation and troubleshooting

Common validation errors

When testing transformations, you may encounter these common issues:

• Invalid file format: Ensure your sample file matches the expected schema format (CSV, JSON, XML).

• Missing required fields: Check that all required target fields have mappings.

• Data type mismatches: Verify that source and target field data types are compatible.

• Expired sample files: Reupload sample files if you receive expiration errors.

For detailed validation rules and error resolution, see Resolve transformation mapping conflicts and errors.

Best practices for testing

• Test with realistic sample data that represents your production data.

• Include edge cases such as null values, empty fields, and maximum field lengths.

• Verify that loop nodes process multiple records correctly.

• Test with both minimum and maximum expected data volumes.

• Validate that conditional mappings work as expected with different data scenarios.

For more information on transformation validation, see Transformation mapping validity.