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 will be 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 will open. Configuration is covered as follows:

  • Name: In the text entry box at the top of the screen, enter a name to use to identify the new file schema.

    NOTE: There are two areas within this configuration screen to provide the schema name. The second area where the name can be provided is under either Saved Schemas or Schema Name, depending on whether Use Saved Schema or Provide New Schema is selected. It is recommended to enter the same name into both areas.
  • Save Status: To the right of the schema name are the date and time that the transformation that this schema is associated with was last saved. This information is not associated with the schema itself, which is saved using the Save Changes or Finish buttons located at the bottom of the configuration.

  • Provide Schema File: Within this section, select one of two options for providing a schema:

    • Use Saved Schema: Choose this option to select an existing file schema that has previously been defined in the current project. When this option is selected, this section becomes 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.

        As you edit a schema, validation information will be 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.

        WARNING: If you edit a saved schema but do not change its name, when uploading the schema a popup will ask 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 in all of these areas. If you don't want to affect other areas where the saved schema is used, click Cancel and then edit the schema name, then try to upload it again.

      • Preview Schema: A preview of the schema is displayed on the right. If you have made edits to the schema 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.
    • Provide New Schema: Choose this option 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, this section becomes 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 will be treated as JSON by default. If you will be 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.

      • Load URL: Click this button to open a window 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. Cyclical references are not supported.

          • 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 will be ignored. Multiple directory levels are supported.

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

        • Load: Click this button 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.

          NOTE: When uploading an XSD file that contains multiple top-level elements, you will be prompted to select the desired root node. Select the element and then click Finish to upload the file:

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

      • Upload File: Click this button to open a window 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:

          • XSD: Cyclical references are not supported.

          • 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 will be 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 10 MB in size can be uploaded.

          WARNING: If you try to upload a file with the same name as an existing file already defined in the project, a popup will ask if you want to overwrite the existing file. If you click Continue, the file will be 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 upload it again.

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

          NOTE: When uploading an XSD file that contains multiple top-level elements, you will be prompted to select the desired root node. Select the element and then click Finish to upload the file:

        • Cancel: Click Cancel to close the Upload Schema File window 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.

      As you edit a schema, validation information will be 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.

    • Preview Schema: A preview of the schema is displayed on the right. If you have made edits to the schema 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 Save Changes to save the schema and refresh the schema preview shown on the right side.
  • Finish: Click Finish to save the schema and associate it with the transformation, and close the schema configuration.
  • Cancel: Click Cancel to close the schema configuration. Note that if you have already used the Save Changes button, changes have already been saved and using Cancel will simply close the configuration. Using Cancel without Save Changes closes the configuration without saving.

Accessing Menu Actions

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

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

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:  Aug 06, 2019

  • No labels