Preview mode in transformations in Jitterbit Integration Studio

Introduction

Preview mode provides a read-only interface for using sample data to test how the transformation will process the data.

Preview mode builds on the display of mapping mode, where an overview of the transformation mapping is shown. In addition to displaying the elements of the mapping mode interface, preview mode includes an inline display of data on each source and target field as well as controls to interact with the preview mode interface, as described on this page.

In preview mode, it is not possible to edit the transformation configuration, such as by adding, editing, or deleting mappings. However, the same controls for making edits that are displayed in mapping mode are also displayed in preview mode.

When you attempt to edit the transformation, you automatically exit preview mode and enter mapping mode (if using an interface element where you would remain in mapping mode) or script mode (if opening a script on a target field).

For elements of the user interface that are shared by multiple display modes, see Common mode elements.

Transformation preview processing

When configuring a transformation preview, there are two methods by which sample data can be provided:

1. Sample data is provided by the user
   You upload the sample data to use for the transformation preview when you configure the transformation preview. This method is available in these scenarios:

   • When a transformation has a source schema defined within an adjacent activity, with the exception of a Database query activity.
   • When a transformation has a source schema defined within the transformation (either with or without an adjacent source activity).

   This option is described under Select sample data later on this page.

2. Sample data is provided by the operation
   The sample data is fetched from the operation for certain endpoints. This method is available in these scenarios:

   • When a transformation has an adjacent Database query activity. You have the option to apply an additional WHERE clause to limit the number of records retrieved for preview purposes. This option is described under Database query activity later on this page.

   • When a transformation has an adjacent NetSuite, Salesforce, Salesforce Service Cloud, or ServiceMax activity — either a source or target activity. These options are described under NetSuite activity and Salesforce, Salesforce Service Cloud, or ServiceMax activity later on this page.

Preview mode displays the sample data as it will be written to the target of the transformation 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. (As noted at the end of this section, when certain activities are the transformation target, sample data is written to the target.)

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

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

Availability of preview mode

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

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

Access preview mode

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

From either mapping mode or script mode, click the preview icon:

You then provide input to configure the transformation preview, as described next.

Configure a transformation preview

The transformation preview configuration process walks 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 below in Deploy dependencies.
• All previewable transformations, except for those with an adjacent Database query activity, show an area called Select Sample Data, described below 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 below in Database query activity.
• Transformations with an adjacent NetSuite activity (either as a source or as a target) provide the options to Preview Using Source Data or Preview Using Sample File, described below 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 below in NetSuite, Salesforce, Salesforce Service Cloud, or ServiceMax Target activity. 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 is dependent 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 looks similar to that displayed below:

• Required Components: Review the components that will be deployed on clicking 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 and/or a comment on deploying, a dialog is presented to enter the required tag and/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 (shown in the left image below) 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 (shown in the right image below).

• 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, etc.

  • 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 51200 bytes. These limits apply only for this preview testing.

    Tip

    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 on this page under 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 that 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. For examples of WHERE clauses, see Database-specific information.

• Finished: Click to load the sample data, retrieve the transformed data from Harmony, and continue on to the transformation preview screen, covered later on this page under 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 as a 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 on this page under Preview a transformation.
• Cancel: Click to close the preview configuration screen and return to the transformation without previewing data.

Salesforce, Salesforce Service Cloud, or Servicemax activity

When a transformation has an adjacent Salesforce, Salesforce Service Cloud, or ServiceMax activity (either as a source or as a 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 below under 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 below under Preview a transformation.
• Cancel: Click to close the preview configuration screen and return to the transformation without previewing data.

Preview a transformation

The transformation screen loads in preview mode. This mode is similar to mapping mode, except that it is read-only and has additional options related to testing the transformation with sample data. If you want to edit the transformation mapping, attempting to do so automatically opens mapping mode (if using an interface element where you would remain in mapping mode) or script mode (if opening a script on a target field).

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

In preview mode, the transformation toolbar provides a set of tools for interacting with the preview mode 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 under Clear or change sample data below.

  

• 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.

  Note

  Within the preview data, additional arrows are available on nodes that have multiple sub-records within a record to cycle through:

  

• 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 mode and return to the transformation configuration screen.

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 / Salesforce Service Cloud / ServiceMax Query: If using a Salesforce, Salesforce Service Cloud, or ServiceMax Query activity, this returns you to step 2 of the configuration of that activity a Salesforce query, Salesforce Service Cloud query, or ServiceMax Query activity to modify the query statement.