Introduction

A hierarchical file schema is a complex file structure that contains multiple file row types such as header or summary rows. This page covers creating a custom hierarchical schema within a transformation.

Creating a Hierarchical Schema

To be able to create a hierarchical file schema, 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 hierarchical schema 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 Create Hierarchical:

Configuring a Hierarchical Schema

Configuration of a file schema using the hierarchical file schema editor is covered as follows:

  • Schema Name: In the text entry box at the top of the screen, enter a name to use to identify the hierarchical file schema.
  • 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 button located at the bottom of the configuration.
  • Type: Select among the available types for a custom hierarchical schema:

    • XML: The schema will be created in XML format.
    • Fixed Width: The schema will be created in CSV format using length to delineate fields.
    • Character Delimited: The schema will be created in CSV format using character(s) to delineate fields.
    NOTE: Creating a hierarchical schema in JSON format is not supported. 
  • Options: When Character Delimited is selected, these options become available:

    • Delimiter: Enter the character(s) to use as field delimiter(s) that specify the boundary between data fields. The default is a comma. You can also use multiple-character delimiters, such as a double pipe ||.
    • Line breaks for end of records: Select this checkbox to use line breaks to separate records. This option is selected by default. When this option is selected, end of records are denoted by line breaks so that each record exists on one line (unless using a qualifier). When disabled, line breaks are ignored and new records begin after the total number of fields are reached.

      NOTE: This option is relevant only for schemas used on the source side of a transformation. For schemas used on the target side of a transformation, line breaks are always used to denote end of records.
    • String Qualifier: Enter a character to use as wrapper to indicate a string of words to be treated as a data unit. The default is a double quote. In addition, select a corresponding business rule, Always or When needed, to indicate when the qualifier should be used. The default When needed is recommended.

    • Convert escape sequences: Select this checkbox to convert or ignore escape sequences as indicated by a backslash \. By default, escape sequences are converted in accordance with Java standards. When disabled, text conversion occurs with no interpretation of escape sequences.

      NOTE: This option is relevant only for schemas used on the source side of a transformation.
    • EDIFACT: Select this checkbox if the data follows the EDIFACT standard of syntax rules.
  • Add Node: Click the Add Node button to add new nodes one at a time to the table. These columns are available for each node row:

    • #: Each node row will automatically be assigned a number in the order the row appears. Once you have at least two rows with the same parent in the tree, hover over the number and click the up  or down  arrow. The node serving as the root node (without a parent) cannot be reordered, nor can nodes be reordered to a different level in the tree structure (instead, this can be done by changing the parent of the node).
    • Node: Enter a name for the node. The node name cannot contain whitespace characters or symbols such as these: @ $ % & / + ( ) : ; ,.  In addition, the field name cannot begin with a number, period (.), or hyphen (-).

      TIP: For reference on all unallowed characters, see NCName as defined by W3C.
    • Parent: Use the dropdown to select the parent of the node.

    • Occurrence: Use the dropdown to select how the node will occur in the complex document:
      • Zero or More: Select this option if this node may not occur, but if it does, it can occur one or more times. 
      • Zero or One: Select this option if this node may not occur, but if it does, it can only occur once.
      • One or More: Select this option if this node must occur at least once, but can also be repeated.
      • Exactly Once: Select this option if this node must occur once but only once in the document.
    • Fields: The number of fields defined for the node will be listed. To define the node's fields, click the edit icon  to the right of the number of fields. This will open a field editor for the specific node, as follows.

      NOTE: Nodes should contain at least one field in order to be able to map to them when completing a transformation mapping.

      • Node Cycle: Click the left or right arrows to cycle through nodes in the hierarchical schema to show the field table for the selected node.

        • Back: Click the close icon  to return to the node table.

          Node Navigator: Along the top of the table is an expanded gray button that allows you to change the table display by navigating to another node:

      • Add Field: Click the Add Field button to add new field rows one at a time to the table. These columns are available for each field row:
        • #: Each field row will automatically be assigned a number in the order the row appears. Once you have at least two rows, to reorder them, either drag and drop to another position within the table, or hover over the number and click the up  or down  arrow.
        • Field: Enter a name for the field. The field name cannot contain whitespace characters or symbols such as these: @ $ % & / + ( ) : ; ,.  In addition, the field name cannot begin with a number, period (.), or hyphen (-).

          TIP: For reference on all unallowed characters, see NCName as defined by W3C.
        • Type: Use the dropdown to select a data type. Options for new custom schemas include stringintegerlongdatefloatdouble, and boolean. If a custom schema was created by mirroring a schema from a server-based activity, additional data types may be listed.

        • Actions: For actions you can take on an existing field row, hover over this field and click the copy icon  to duplicate the field row, or click the trash icon  to delete the field row.

      • Review Schema: As you manually define each field within the schema, a preview of the schema is displayed on the right side. The schema is displayed using the standard interface elements described under Nodes and Fields.
      • Save Changes: Click this button to save and close the file schema.
      • Discard Changes: Click Discard Changes to close the file schema without saving changes.
    • Actions: For actions you can take on an existing node row, hover over the field on the far right under the actions menu icon . Then click the copy icon  to duplicate the node row, or click the trash icon  to delete the node row.

  • Review Schema: As you manually define each node within the schema, a preview of the schema is displayed on the right side. The schema is displayed using the standard interface elements described under Nodes and Fields.

    CAUTION: If you have created nodes that do not have any fields, then you will not be able to map to any fields within these nodes when completing a transformation mapping.
  • Save Changes: Click this button to save and close the file schema.
  • Discard Changes: Click Discard Changes to close the file schema without saving changes.

Accessing Menu Actions

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

These include deleting, renaming, viewing dependencies of, deploying, configurable deploying of, 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 Menu Actions.