Skip to end of metadata
Go to start of metadata

Introduction

If you already have a file available that contains the structure of data you want to use, you can use a sample file within a transformation. This option is effectively the same as providing the file schema during activity configuration, except that a schema defined within the transformation (as is described here) takes precedence over a schema defined as part of an activity.

Using a Sample File

To be able to define a file schema using a sample file, first add a transformation to an operation. If the operation also an activity located adjacent to the transformation on the side where you want to use a sample file in the transformation, it must not have a file schema provided in the activity configuration. That is, while configuring the activity, in the area where you can provide a request or response schema, make sure to select No so that the schema is not inherited by the transformation.

Provided this condition is met, the Define Schema button is displayed in mapping mode on each side of the transformation that does not already have a schema defined in an activity. Click Define Schema on the source or target side of the transformation and select Use Sample File:

Configuring a Sample File Schema

The sample file schema editor opens. Configuration depends on whether Use Saved Schema or Provide New Schema is selected.

Use a Saved Schema

Choose Use Saved Schema to select an existing file schema that has previously been defined in the current project. When this option is selected, these options become available:

  • Saved Schemas: Use the dropdown to select from an existing schema to reuse.

  • View/Edit Schema: After an existing schema is selected, you can view or edit it directly within the text area below the dropdown, or click the popout icon  to edit it in a larger area (once within that area, click the return icon  to come back to this screen).

    NOTE: This area is not applicable for saved schemas that were originally created as a custom flat schema or custom hierarchical schema.
  • Validation: As you edit a schema, validation information is provided below the text area, with any errors reported one line at a time. That is, after resolving an error on one line, additional syntax errors to resolve may be reported for subsequent lines. Validation is based on the file extension of the saved schema.

  • Preview Schema: A preview of the schema is displayed on the right. If you have made edits to the schema structure in the text area on the left, you must first click the Save Changes button for the changes to be reflected in the preview area. The schema is displayed using the standard interface elements described under Nodes and Fields.
  • Save Changes: Click to save changes to the schema and refresh the schema preview shown on the right side.

    WARNING: If you have edited a saved schema, a dialog asks you to acknowledge that the edits will affect other areas of the project where the saved schema is used. If you click Continue, the edits will take effect everywhere the schema is used in the project. If you don't want to affect other areas where the saved schema is used, click Cancel and provide a new schema instead.

  • Finish: Click to save the schema and close its configuration.
  • Cancel: Click to close the schema configuration. Note that if you have already used the Save Changes button, changes have already been saved and using Cancel simply closes the configuration. Using Cancel without Save Changes closes the configuration without saving.

Provide New Schema

Choose Provide New Schema to define a new schema by loading one from a URL, uploading a file, or manually entering one into the text area. When this option is selected, these options become available:

  • Schema Name: Enter a name for the schema into the upper text box, including the file extension (.json, .xml, .xsd, .csv, or .zip). If no file extension is provided, the file is treated as JSON by default. If you are loading the schema from a URL or uploading a file, you can leave this blank, as the name will be populated once the file is loaded. Once you upload a file in a selected format, manually changing the extension has no effect.

  • Load URL: Click to open a dialog where you can load a schema from a URL:

    • File Type: Use the dropdown to select from the supported file types, including JSONXMLXSDCSV, and ZIP. Take note:

      • XSD: An XSD provided by URL can import/include other XSD URLs by reference.

      • ZIP: A ZIP archive should contain a collection of XSDs, which may import/include each other by reference. Any non-XSD files in the archive are ignored. Multiple directory levels are supported.

    • URL: Enter a URL that is accessible without authentication. Files up to 5 MB in size can be uploaded.

    • Load: Click to load the schema from the URL. Note that the file is retrieved only a single time for schema generation. In addition, be aware that some data may be converted during processing as described in Schema Processing.

    • Cancel: Click to close the Upload Schema URL dialog without saving.

  • Upload File: Click to open a dialog where you can load a schema from a file that is accessible from the current machine:

    • File Type: Use the dropdown to select from the supported file types, including JSONXMLXSDCSV, and ZIP. Take note:

      • ZIP: A ZIP archive should contain a collection of XSDs, which may import/include each other by reference. Any non-XSD files in the archive are ignored. Multiple directory levels are supported.

    • File: Use the Browse button to the right to browse to a file that has not yet been used in the current project. Files up to 5 MB in size can be uploaded.

    • Load: Click to load the schema from the file. Note that some data may be converted during processing as described in Schema Processing.

    • Cancel: Click to close the Upload Schema File dialog without saving.

  • View/Edit Schema: After a schema is loaded, you can view or edit it directly within the text area below the Load URL and Upload File buttons, or click the popout icon  to edit it in a larger area (once within that area, click the return icon  to come back to this screen).

    Another option is to manually enter or paste a schema into this area without loading a schema from a URL or file.

  • Validation: As you edit a schema, validation information is provided below the text area, with any errors reported one line at a time. That is, after resolving an error on one line, additional syntax errors to resolve may be reported for subsequent lines. Validation is based on the file extension of the provided schema.

  • Preview Schema: A preview of the schema is displayed on the right. After loading a new schema or making edits in the text area on the left, you must first click the Save Changes button for the changes to be reflected in the preview area. The schema is displayed using the standard interface elements described under Nodes and Fields.
  • Save Changes: Click to save the schema and refresh the schema preview shown on the right side.

    WARNING: If you try to upload a file with the same name as an existing file already defined in the project, a dialog asks if you want to overwrite the existing file. If you click Continue, the file is replaced with the new file with the same name in all places where it is used in the project. If you don't want to overwrite the file, click Cancel and then manually modify the file so it has a name that is not already being used, then try to save it again.

    NOTE: When uploading an XSD file that contains multiple top-level elements, on clicking Save Changes, you are prompted to select the desired root node. Select the element and then click Finish to save:

  • Finish: Click to save the schema and close its configuration.
  • Cancel: Click to close the schema configuration. Note that if you have already used the Save Changes button, changes have already been saved and using Cancel simply closes the configuration. Using Cancel without Save Changes closes the configuration without saving.

Schema Actions Menu

After a schema from the sample file is created, you can access additional menu options that are available for all schemas.

These include deleting, renaming, viewing dependencies of, deploying, configurable deploying, and adding to a group, as well as editing a schema or clearing a schema from a transformation. For details on these actions, see Schema Actions Menu.

NOTE: When you edit a schema that was created from a sample file, the configuration screen for a custom flat schema or custom hierarchical schema opens for you to add or edit fields and/or nodes as required.
On This Page

Last updated:  Nov 19, 2020

  • No labels