User documentation for the Alignment Editor

Please note that this page is outdated as it only targets HALE up to version 2.1.2. For current versions, have a look at the online help instead.

Note that this documentation is largely the same as in the manual distributed with HALE.

The HUMBOLDT Alignment Editor, short HALE, is an application for defining mappings between concepts in conceptual schemas (application schemas created with the HUMBOLDT Model Editor or other modelling applications), as well as for defining transformations between attributes of these concepts. These mappings are expressed in a high-level language called Ontology Mapping Language (OML) and can later be used by the Conceptual Schema Transformer processing component to generate an executable form of transformation.

To make the mapping process more accessible to a domain expert and to increase the quality of transformations, HALE allows working with sample source geodata for interactive visualization and validation. Furthermore, a task-based system as it is often used in programming supports users in the creation of a mapping. HALE also provides other innovative capabilities, such as the real-time evaluation of the mappings you create in terms of their quality. Finally, HALE also contains a system that can be used to document the validity of mappings, called Mismatch Description Language (MDL).

The general workflow for HALE is as follows:

  1. Open the schema of the source data you want to map
  2. Open the target schema
  3. Open a source data set (optional)
  4. Configure the source and target Styled Layer Descriptors (optional) to get interactive feedback on the progress of your mapping project in the map viewer
  5. Go through the created task list until the mapping is of sufficient quality for your application
  6. If no problems pop up, save/publish created mapping.
  7. If you loaded source data you can save the transformed data to a GML file (optional)


  • Schema (or Ontology, Application Schema, Conceptual Schema): A Collection of types, with simple and complex attributes assigned to them.
  • Type: a type (or concept, class, feature type, spatial object type) represents a model of a given class of objects. It has a name and can be part of an inheritance hierarchy, i.e. there can be more general and more specialized types. A type inherits all the attributes of a more general type, and will inherit all it's attributes to the more specialized types. A type can always have only one supertype (no multiple inheritance allowed).
  • Attribute: These are always aggregated by a type. There are simplex attributes, like strings, ints and geometries, and complex attributes which are essentially other types.

Configuring your HALE Workbench

When you start HALE the first time, it will present you with a user interface that contains several different parts. These parts, called views, each have a specific purpose. In the current release, the following views are included:

  • Schema Explorer: The Schema Explorer allows you to view the structure of the source (left) and the target (right) schema in various ways and enables the definition of mappings between the elements of the schemas.
  • Mapping View: The mapping view provides information on the schema mappings you have defined on the elements currently selected in the Schema Explorer.
  • Map View: This view provides you with a cartographic representation of the reference data for the source schema and the transformed data alongside each other, when you have loaded such data. It can be styled and navigated interactively.
  • SourceData: This view provides a tabular representation of the reference data for the source schema when you have loaded any.
  • Transformed Data: Like the Reference Data view, this view provides you with the possibility to inspect transformed data.
  • Tasks: The Task View provides you with information on tasks that have to be completed to create a complete and correct mapping.
  • Mapping Graph View: This view gives you a graphical overview of the mapping created so far.
  • Error Log: Gives you insight into the program's log messages. They can be exported as log files to submit with a bug report.

Each of these views can be resized by grabbing its border and then dragging the mouse cursor. Furthermore, every view can be maximized by double clicking on the “Folder” part of the view on top or by clicking the bigger window icon on the right side of the view's top. To set a view back to normal, you can again double-click on its tab or click on the small window icon.

It is also possible to rearrange views. Just click on the tab and drag the mouse cursor to the place where you would like the view to be. You will see that it is possible to stack views over each other, but also to arrange them next to each other. In addition, you can also open and close views, To close a view, just click the “X” next to it's tab. To open it again, go to the “Configure” menu, pick “Views”->”Other” and then select the view you would like to see again.

When you find a view configuration that you like particularly well, you can save that configuration. Again, go to the Configure menu, pick “Save Perspective as”, and enter the name under which you want to store your configuration. The configuration's name will now appear in the upper right corner to indicate it is active and stored.

By default, there are two perspectives already preconfigured for you. One is called the “Default” perspective and includes the Schema Explorer, the Map View, the Mapping View and the Task View, the other one is called the “Data” perspective and contains the Mapping View, the Map view, the Reference Data view and the Transformed Data view.

Loading Schemas

A first step to map schemas is to load them. In the current version of HALE, you can load any XML Schema, including metadata schemas, GML Application Schemas and others. However, the schema import is optimized for GML Application Schemas and supports the following versions:

  • GML 2.1
  • GML 3.1
  • GML 3.2

You can also load a schema from a shapefile (*.shp). Schemas can either be loaded from a file or from a Web Feature Service's GetCapabilities and DescribeFeatureType operations. Please note that using GML Application Schemas with types extending AbstractFeatureType is the recommended method for HALE in the current version. Only when doing so, all transformation functions can be used. Such schemas can be created in multiple ways, e.g. from UML models by using Shapechange or from databases and shape files using Geoserver. It is also possible to use Safe's FME for this purpose.

To load a schema, go to the “File” menu and click “Open Schema”. In the dialogue that appears now, choose whether you want to import a schema to use as a source or as a target schema. Then, choose from which source to import by clicking the radio buttons in front of the “... file” and “...WFS” options.

Importing a Schema from a Web Feature Service

When you chose to import from a file, click the Button labelled “Browse...” and select the file you would like to import. Please note that only files with an extension that is either *.xsd, *.xml or *.gml will be shown. After doing so, press “Open” and then “Finish”.
Importing from a WFS works in a similar way. Press the “Change...” button and enter your server's GetCapabilities request URL into the text field at the top of the appearing window. The correctness of the URL is automatically validated. If the validation is successful, you can contrinue by pressing the “Finish” button. All types will now be loaded and shown in a new wizard page. If your WFS offers FeatureTypes from more than one namespace, you are now also required to pick one of the namespaces – HALE can always just work with one “main” namespace for the schema. Press “Use this WFS” and then again “Finish”.

When everything worked as it should have, you will now see the namespace of your schema in the left part of the Schema Explorer if you loaded a source schema, or in the right part if you selected to load a target schema.

Using multiple source schemas

HALE allows you to load exactly one source and one target schema. However, the schemas that you load are actually allowed to have multiple imported schemas. So, if you have to use multiple source schemas in your mapping, using joins between these, you can create a new schema file and import the schemas you want to join. Importing schemas is done following this pattern:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="" xmlns:import1="" xmlns:import2="" 
 elementFormDefault="qualified" targetNamespace="">
  <import namespace="" schemaLocation=""/>
  <import namespace="" schemaLocation=""/>

Troubleshooting Schema Loading

In case an error message pops up during schema loading or a schema doesn't appear after loading, some problem occurred in parsing it. Most of the time, these issues are due to referenced schemas not being accessible. This is e.g. the case when your schema references online resources, e.g. from, but you currently don't have a connection. Also, you might have relative paths in the schema locations used that are not valid on your machine.

Another issue that frequently prevents loading of schemas is the presence of a proxy server. If your network requires the usage of one, please configure the proxy server setting by going to the Configure Menu and clicking “Other Settings”. Then select the “Proxy Settings” page. Enter your HTTP proxy host and port and click “Ok”. If needed you can also define credentials for the authentication to the proxy.

Exploring a loaded schema

HALE comes with a powerful schema explorer view. This view presents the content of the loaded schemas in a tree view. In the default representation, the schema elements that have been loaded are organized by their extension (or inheritance) hierarchy. In the case of a GML Application Schema, this means that directly under the namespace element, an entry for AbstractGmlObject and/or AbstractFeatureType is created, depending on the GML version you are using. Below this entry, you'll find your types extending AbstractFeatureType.
If your schema contains complex element declarations that do not extend AbstractFeatureType, these are interpreted as so-called PropertyTypes.

When you expand a Feature or Property Type by clicking on the + or arrow (depending on your operating system) in front of its name, its subtypes and attributes will be shown to you. For the attributes additionally to the property name also their type name is shown, e.g. <string>. A type name that includes a question mark (e.g. or ) states that this is an anonymous type declared especially for the given attribute.

Some attributes represented in the schema tree are marked with a special sign in addition to their classification symbol. The default geometry of a feature type is marked with a green triangle, items that represent attributes in XML (in contrast to elements) are marked with a brown arrow and mandatory attributes are marked with a red asterisk.

You can also deactivate the organisation by inheritance by clicking the first icon on the top of the respective schema explorer. Your types will then be shown in a list instead of a tree. Pressing the button again will restore the tree presentation.
There are two additional ways of extending the tree or the list:

  • Expand complex properties: In the case of complex application schemas, attributes are often complex types themselves. Enabling this option will expand these properties, so that you can inspect their structure.
  • Repeat inherited properties: With this option enabled, all properties that a type inherits are also displayed under it again, not just under the type that declared the properties. This is a helpful option if you want to define specific mapping rules for each subtype instead of defining them on the supertype.

In addition to extending the representation, there are also several filters you can apply to limit the information presented to you. The most obvious one is the filtering by element name. Just enter a string corresponding to the name of the element you are looking for, and the tree will be updated to show only the elements matching your query. To remove this filter, press the eraser icon on the right side of the filter text field.

Furthermore, you can filter the properties that are displayed by their type:

  • Hide Abstract Types: This will hide types that are declared as abstract.
  • Hide Property Types: This will hide/show types that are no FeatureTypes.
  • Hide String Types: This will hide/show any property with a String binding.
  • Hide Numeric Types: This will hide/show any property with a numeric (integer, floating point) type of binding.
  • Hide Geometry Types: This will hide/show any property that has a Geometry binding.

You can also get detailed information about any element of a schema by right-clicking on it in the schema explorer and then selecting “Properties”. The dialogue appearing then contains any annotations that have been defined on the type, provides information on the binding and also on other properties, such as its cardinality. It also lists allowed values in case of an enumeration type of property.
All options above can also be combined. As an example, selecting the “List” organisation mode together with “repeat inherited properties” and “Hide Property types” will give you a list of the abstract and concrete FeatureTypes, each one with their full attribute set. Use Hide Abstract Types in addition and you'll get a list of only the concrete types, each one with all its properties.

Using the Schema Explorer to learn about the imported schemas

Mapping Schemas and Attributes in the Alignment View

  1. To map types or attributes from the source schema to type or attributes, you first have to select them in the Schema Explorer. Types selected in the Source Schema Explorer will be shown in the Source Alignment View, and types/attributes selected in the Target Schema Explorer will be shown in the Target Alignment View. You can do any complex selection in the Schema Explorer, which allows you to filter the elements displayed in the attribute view to exactly the ones you need.
  2. After selecting source and target, you can press the Arrow button in between Source and Target Schema and then select an appropriate function.
    1. If you want to connect one type to another, use "Rename", which effectively allows to assign values from one type or attribute to one in the target schema. In addition, you can define so-called instance splits and merges in this function.
    2. After defining a Rename mapping, you can also apply a filter to it. Without changing the selection to which you applied a transformation, click on the "Mapping" button again and choose the CQL Filter Wizard. Configure the expression as you would like to have it, click "Finish", and you will now see a Filter added in the Attribute View.
    3. Other functions that are available perform transformations on properties. These include the following:
      1. a simple Attribute Rename Function that can copy any alphanumeric attribute,
      2. a simple Spatial Type Conversion function that can map the following geometric types: LineString <-> MultiPoint, Polygon <-> MultiPoint, MultiPolygon <-> MultiPoint, MultiLineString <-> MultiPoint, Polygon <-> LineString, Polygon <-> MultiLineString, MultiPolygon <-> LineString
      3. a Generic Math Function where you can use source attributes as variables in an arbitrary mathematical expression,
      4. a Bounding Box Function and a Centroid Function to derive additional geometric attributes,
      5. a Network Expansion Function that will buffer and fuse a network of Line Strings,
      6. a Classification Mapping Function that allows to transform code lists and classification values.
    4. There are also Augmentation functions that will be applied only on the target feature but don't use data in source features. An example for this is the "NilReason Function".

Clicking the Mapping Button to see available functions on the current selection

Defining the instance split and merge condition on a feature type

Defining a Filter on a _Rename mapping created beforehand_

The Mapping View after the Feature Types have been mapped and a Filter has been assigned

Working with instance data

The term "instance data" always refers to an actual geographic data set whose entries represent objects and are modelled using one of the loaded schemas, be it target or source.

  1. To load an instance data set (currently only possible for the source model), got to "File" -> "Open Instance Data".
  2. In the wizard which opens, you can again choose whether to import data from a WFS or from a local GML file (*.shp support will be added soon).
    1. If you would like to load from a local GML file, click on "... file" and press the "Browse..." button. Select the file you want to use, press "Open" and then "Finish". Loading the file might take several seconds (typically around 3-6 per Megabyte).
    2. Please note that the "... WFS GetFeature" is not fully implemented yet.
    3. If the system cannot clearly identify the used SRS from the data, it will request the user to provide either the EPSG code or the Well-Known Text for the used SRS.
  3. The content of the file will now be displayed in the Map Viewer.
    1. In the Map Viewer, you can pan and zoom in this map view using the mouse and mouse wheel. Furthermore, you can select one of several overlay modes between the reference data and the transformed data, including horizontal and vertical splitting, diagonal splitting and a direct overlay.
    2. On the top left corner of the Map View you can find the settings for controlling the map rendering. Specifically, you can configure so-called Styled Layer Descriptors there, using a rich GUI.
  4. Another option for analysing the instance data is using the "Reference Data" and "Transformed Data" view
    1. They display the attribute values of sample features that are picked from the instance data. The features in the "Transformed Data" view are already transformed using the alignment mapping. To select sample features of a certain type you have to select the corresponding feature type in the list. Additionally you can define a filter in the text field. The buttons next to the filter field on the right provide support for defining your filter (Inserting attribute names/Create filter using a form).
    2. To analyse features and their transformed counterparts you can synchronize both views. Simply activate the button in the top left corner of the "Transformed Data" view. If the views are synchronized, in the "Transformed Data" only the transformed features of the features displayed in the "Reference Data" view will be available. You can filter the transformed features by their feature type.

Making mismatches in a mapping obvious using instance data visualisation

Tables showing sample features - reference (top) and transformed data (bottom). The reference data is filtered, the views are synchronized

Exporting your Mapping

  1. Exporting your created Mapping is very straightforward: Go to the Menu File, pick "Save Mapping" and chose a location and filename.

Part of an exported gOML file

Saving and Loading of Alignment Projects

  1. To save your entire project configuration, go to Menu File, and pick "Save Alignment Project as...". You have to pick a location where to save the project to, and can optionally also provide some metadata on the project. This will create two files: A project configuration file and a alignment file with the same filename and an additional extension (*.goml).
  2. To load a project, just go to Menu File, and pick "Open Alignment Project". Pick the project file and click "Finish". Schemas, the mapping and instances will then be loaded.

hale-tableview.jpg - Table View (196.6 kB) Simon Templer, 02/01/2010 05:42 pm

hale-screen-2.0.0-nl-kataster-midsize.jpg (64.8 kB) Thorsten Reitz, 05/13/2011 06:13 pm