The element “input”

Overview

The <input> element contains parameters and other information relating to the input model.  For example, the following snippet is an <input> element referencing a model in XMI 1.0 format:

<input>
    <parameter name="inputModelType" value="XMI10"/>
    <parameter name="inputFile" value="NAS_v1.3.xmi"/>
    <parameter name="appSchemaName" value="My Schema"/>
    <parameter name="publicOnly" value="true"/>
    <parameter name="addTaggedValues" value="size"/>
    <xi:include href="http://shapechange.net/resources/config/StandardAliases.xml"/>
</input>

Parameters

The following subsections document the parameters recognized for the <input> element.

addTaggedValues

Default Value: <blank>

Explanation: A list of additional tagged values that should be included when reading the model into memory. ShapeChange recognizes a set of well-known tagged values, but at runtime it may be desirable to include others, depending on the input model.

appSchemaName

Default Value: <blank>

Explanation: A string containing the name of the application schema to be transformed (if there is more than one in the input model, and only one output is desired). The default value of <blank> will result in all incoming application schemas being transformed.

appSchemaNameRegex

Default Value: <blank>

Explanation: A regular expression used to limit the schemas to be processed. A schema will only be processed if its name matches the pattern contained in this parameter.

appSchemaNamespaceRegex

Default Value: <blank>

Explanation: A regular expression used to limit the schemas to be processed. A schema will only be processed if its namespace matches the pattern contained in this parameter.

checkingConstraints

Default Value: enabled

Explanation: (Valid for EA7 input only) If the parameter is not “disabled”, the OCL constraints in the model are analyzed and tested, regardless of whether they are used in the further execution.

classTypesToCreateConstraintsFor

Default Value: if the parameter is not configured, constraints are considered for all class categories

Explanation: (Valid for EA7 input only) If this optional parameter is used in the configuration, constraints are only created for the class types/categories identified by this parameter (in a comma-separated list of class stereotypes, for example “featuretype,type” – the list of class stereotypes is available here).

constraintCreationForProperties

Default Value: true

Explanation: (Valid for EA7 input only) If the parameter is “false”, constraints defined for properties (attributes and association roles) will not be created.

constraintExcelFile

Default Value: <blank>

Explanation: Location of an excel file with First Order Logic constraints of source type ‘SBVR’ that shall be loaded into the input model before postprocessing it.

dontConstructAssociationNames

(since v2.2.0)

Default Value: false

Explanation: If an association has no name, ShapeChange generates a name for it while loading the model. The default name is constructed by concatenating the names of the classes at both ends of the association. In some cases, missing association names should not automatically be generated. For these cases, set this parameter to ‘true’.

extractSeparator

(since 2.0.2)

Default Value: —

Explanation: The start and end part of any separator used to split the documentation of a model element. See “Descriptor sources” below for additional information.

folConstraintTypeRegex

Default Value: (SBVR)

Explanation: (Valid for EA7 input only) The EA constraint types that are treated as First Order Logic (FOL) constraints. A value of “” will ensure that constraints are not recognized as FOL constraints. Constraints whose type is not recognized will be converted to text constraints without parsing. NOTE: processing of First Order Logic constraints is in beta status

gsipEnumLiteralOrderBy

Default Value: alpha

Explanation: (Valid for GSIP input only) A text string indicating how enumeration literals are to be sorted/ordered in the output GML. The possible values are as follows:

  • alpha: Order literals alphabetically, by their primaryCode tag.
  • integer: Order literals numerically, by their secondaryCode tag.

Note: This should be moved to a <TargetXmlSchema> option, since it is really more properly target-related.

gsipSuppressAttributes

Default Value: false

Explanation: (Valid for GSIP input only) A string representing a Boolean value; if “true”, attributes will not be read/transformed.

gsipSuppressDatatypes

Default Value: false

Explanation: (Valid for GSIP input only) A string representing a Boolean value; if this parameter is set to “true”, data types will not be read/transformed.

id

Default Value: INPUT

Explanation: This optional parameter (configured via an XML attribute) determines how transformers and especially targets can reference the input model (in the transformer’s “input” / target’s “inputs” parameter).

ignoreEncodingRuleTaggedValues

Default Value: false

Explanation: True, if xxxEncodingRule tagged values shall be ignored (because the model is wrong and needs cleanup), else false.

inputFile

Default Value: http://shapechange.net/resources/test/test.xmi

Explanation: The path to the input file, relative to the working directory. For XMI 1.0 models, URLs are supported, too.

inputModelType

Default Value: XMI10

Explanation: A string describing the format of the application schema to be transformed. The current options are:

  • XMI10: a UML model in XMI 1.0 format
  • EA7: an Enterprise Architect project file, supported are versions 7.5 and later
  • GSIP: a GSIP model contained in a Microsoft Access Database (MDB)
  • SCXML: a model in a ShapeChange specific XML format. The Model Export target can create SCXML from any model that was loaded by ShapeChange. Loading a model from (SC)XML is fast. It is significantly faster than reading the model from an EA repository. This is useful when processing the same model multiple times.

NOTE: Loading a model from an EA repository requires execution with 32bit Java, due to the dependency on the 32bit EA API. For all other input model types, 64bit Java can be used – unless processing (a transformation or a target) requires accessing an EA repository via the EA API (then 32bit Java must be used). 32bit Java processes can only be executed with a limited amount of main memory (one or two gigabytes). Typically, this is not an issue. However, for very large models with hundreds of classes, and a processing workflow that greatly increases the size of the model (e.g. through copies of models created while flattening the model), this limitation can be significant. In such a case, a workaround is to load the model with 32bit Java from the EA repository, export it to SCXML, and then execute ShapeChange again using 64bit Java and loading the model from SCXML.

isAIXM

Default Value: false

Explanation: A boolean value indicating if AIXM schemas are being processed, which requires special treatment (due to the AIXM extension mechanism and because AIXM feature types are dynamic features).

kmlReferenceType

Default Value: alternate

Explanation: (Valid for GSIP input only) A text string that indicates how KML reference strings should be represented. (Add more information.)

language

(since 2.0.2)

Default Value: en

Explanation: The language to use in case descriptors for model elements like definitions or aliases are multilingual. Use two letter language codes.

loadConstraintsForSelectedSchemasOnly

(since 2.0.2)

Default Value: false

Explanation: Set this input parameter to ‘true’ if constraints shall only be loaded for classes and properties from the schemas selected for processing (and ignoring all constraints from other packages).Don’t make use of this parameter if one of the classes from the selected schema packages extends another class from an external package (e.g. an ISO package) and needs to inherit constraints from that class!This parameter is primarily a convenience mechanism to avoid loading and parsing constraints from external packages (especially ISO packages) that are irrelevant for processing. So on the one hand this can speed up model loading. On the other hand, it can prevent messages about constraints that were parsed from the elements of an external package from appearing in the log.

oclConstraintTypeRegex

Default Value: (OCL|Invariant)

Explanation: (Valid for EA7 input only) The EA constraint types that are treated as OCL constraints. A value of “” will ensure that constraints are not recognized as OCL constraints. Constraints whose type is not recognized will be converted to text constraints without parsing.

onlyDeferrableOutputWrite

Default Value: false

Explanation: If set to ‘true’ (ignoring case), ShapeChange will only execute the output writing routine of targets that implement the DeferrableOutputWriter interface, like the FeatureCatalogue target. This can be used to only transform the temporary XML with feature catalogue information in a separate ShapeChange run. That run does no longer need to read the UML model and can thus be executed using 64bit Java, which supports bigger heap sizes that may be required to transform large XML files.

NOTE: This is an expert setting that is primarily used for debugging.

prohibitLoadingClassesWithStatusTaggedValue

(since v2.4.0)

Default Value: notValid, retired, superseded

NOTE: The default only applies if the parameter is configured with empty value. If the parameter is missing in the configuration, it is ignored and the default does not apply (in that case, non-valid model elements would be loaded). This behavior has been implemented to support loading of other models that use tagged value status, but with different meaning.

Explanation: Comma separated list of values that, if one of them is being set as the ‘status’ tagged value of a class, will lead to the class not being loaded.

publicOnly

Default Value: true

Explanation: A Boolean value indicating whether or not only those elements with public visibility are to be mapped to GML, which is appropriate for application schemas that will be used for data encodings that are shared across application boundaries. If “false”, all elements will be mapped.

representTaggedValues

Default Value: <blank>

Explanation: A list of additional tagged values that should not only be read into memory, but also output (if appropriate) via the <appInfo> element within an annotation. This is a ShapeChange-specific extension to the standard encoding rules; see here.

repositoryFileNameOrConnectionString

Default Value: none

Explanation: This parameter can be used instead of parameter ‘inputFile’ (if both are configure, ‘inputFile’ is given higher priority). It has been introduced to take into account that ShapeChange can also connect to EA repositories that are not available via an EA project file (.eap) but via a direct connection to a database server or Cloud Service.

The parameter either provides the path to the input file (works for all model types) or it provides the connection string to an EA repository (database server or Cloud Service). In order to create such a connection string, open EA and go to “Open Project…”. There you will find a list of recently opened projects. Right-click the repository you wish to process with ShapeChange, then “Edit connection string”, copy the value and set it as the parameter value.

NOTE: If you are using an encrypted connection string, certain characters with special meaning in XML must be escaped in the string before setting it in the ShapeChange configuration:

  • ampersand (&) is escaped to &amp;
  • double quotes (“) are escaped to &quot;
    • No need to escape double quotes if the quotes around the XML attribute value are single quotes.
  • single quotes (‘) are escaped to &apos;
    • No need to escape single quotes if the quotes around the XML attribute value are double quotes.
  • less than (<) is escaped to &lt;
  • greater than (>) is escaped to &gt;

skipSemanticValidationOfShapeChangeConfiguration

(since 2.2.0)

Default Value: false

Explanation: If ‘true’, semantic validation of the ShapeChange configuration will not be performed (further details can be found here).

sortedOutput

Default Value: false

Explanation: If “false”, the types in a schema will be processed in random order. If “true”, the types will be processed alphabetically. If “taggedValue=<tag>”, the types will be processed in the order of the values of the tagged value with name “<tag>”.

taggedValueImplementation

Default Value: <blank>

Explanation: If set to “array”, ShapeChange will use a memory optimized implementation of tagged values when processing the model.Use this option when processing very large models. ShapeChange can process 100+MB sized models without problem. However, if processing involves many transformations and target derivations you may hit a memory limit, which is determined by the maximum amount of memory you can assign to the Java process in which ShapeChange is running. On Windows machines that were used for development, that limit was near 1.1GB.

tmpDirectory

Default Value: temp

Explanation: Path to the temporary directory to store temporary files (like diagram images), as necessary to execute a ShapeChange configuration. The path is either relative to the folder where ShapeChange is executed in, or absolute. NOTE: this folder is NOT deleted when the ShapeChange run is complete.

transformer

Default Value: <blank>

Explanation: (valid for EA7 input only) The full, qualified name of a class that will be used to transform the input model in some user-defined way, before the transformation into the target format occurs.This class must implement the de.interactive_instruments.ShapeChange.Model.Transformer interface.

username and password

Default Value: none

Explanation: If required to access the model (typically an EA repository), provide your username and password.

  • If you do not set these parameters in the configuration, or if you did not set them correctly, you will be prompted by EA to provide the correct values via a dialog.
  • If the connection is to a Cloud Service, you may also need to explicitly set the username and password in the connection string (replace the “*” with the correct value(s)).

useStringInterning

Default Value: false

Explanation: If set to “true”, ShapeChange will use string interning to reduce the memory footprint.

Diagram Image Loading

The following parameters are used to control if and how diagram images are loaded from the input model.

NOTE: at the moment this feature is only supported for EA input models, and only for package and logical diagrams for selected application schema.

Parameter Name Required / Optional Type Default Value Explanation
loadDiagrams Optional Boolean false Set to ‘true’ to load diagram images.
sortDiagramsByName Optional Boolean true Set to ‘false’ (or something other than ‘true’) to prevent diagrams from being sorted by their name. If sorting by name is disabled then the order of diagrams will be the order in which they were loaded (e.g. the order in which they appear in the project browser of Enterprise Architect).
packageDiagramRegex Optional String NAME(the reserved keyword that will be replaced by the package name) Regular expression to control which package (or logical – i.e. class) diagrams get assigned to a package. If the name of such a diagram contained in a package matches the expression (with the occurrence(s) of ‘NAME’ having been replaced with the name of that package) then the diagram will be assigned to the package.
classDiagramRegex Optional String NAME(the reserved keyword that will be replaced by the class name) Regular expression to control which logical (i.e. class) diagrams get assigned to a class. For each logical diagram contained in a package, the expression is evaluated for each class that is also contained in that package. If the name of the logical diagram matches the expression (with the occurrence(s) of ‘NAME’ having been replaced with the name of a given class) then the diagram will be assigned to that class.

Stereotype aliases

ShapeChange relies on a set of well-known stereotypes in order to understand and be able to manipulate incoming application schemas. The page on the UML profile supported by ShapeChange contains more information about this topic.

A given application schema may not use these exact stereotypes.  In this case, a <StereotypeAlias> element can be used to map the incoming application schema’s stereotypes to their well-known equivalents.  Example:

<StereotypeAlias wellknown="FeatureType" alias="Feature" />

The <StereotypeAlias> element contains two required attributes, as above:

Attribute name Explanation

wellknown

The name of the well-known stereotype, from the list given in the description of the UML profile."

alias

String specifying the alias for the well-known stereotype.

The file StandardAliases.xml contains a set of standard <StereotypeAlias> elements, and is typically included in each configuration file via XInclude.  Additional <StereotypeAlias> elements can be added as needed, directly to the configuration file or in a separate module.

Tag aliases

(since 2.0.2)

To simplify configuration of ShapeChange can be configured to treat multiple tags related to the description of model elements e.g. for use in feature catalogues (descriptors) as equivalent.

The <TagAlias> element can be used to map the incoming application schema’s tags to their equivalents that are referenced elsewhere (e.g. in targets or the definition of the descriptor sources).  Example:

<TagAlias wellknown="example" alias="eksempel"/>
<TagAlias wellknown="description" alias="note"/>
<TagAlias wellknown="legalBasis" alias="lovgrundlag"/>
<TagAlias wellknown="alias" alias="alternativtNavn"/>

Like the <StereotypeAlias>, the <TagAlias> element contains two required attributes, as above:

Attribute name Explanation

wellknown

The name of the well-known tag.

alias

String specifying the alias for the well-known tag.

The file StandardTagAliases.xml contains a set of standard <TagAlias> elements, and is typically included in each configuration file via XInclude. Additional <TagAlias> elements can be added as needed, directly to the configuration file or in a separate module.

Descriptor sources

(since 2.0.2)

It is common practice to include various descriptive information about each model element in the UML model. For example, aliases, codes, definitions, descriptions, etc. are often distinguished and various output need to treat each of these descriptors separately. UML tools typically provide a single documentation/notes field for this. Enterprise Architect is no different, except that it has a specific field for an alias.

In practice, communities have addressed this in different ways. One option is to use a tag for each descriptor. Another is to put all descriptors in the notes field and use fixed separator strings to distinguish the different descriptors. To support the different approaches, ShapeChange supports a set of well-known descriptors and allows to configure where this information is stored in the model.

The list of well-known descriptors is:

Descriptor Default source Explanation

alias

the alias field in EA7 models, otherwise tag 'alias' an alternative, human-readable name for the model element

dataCaptureStatement

tag 'dataCaptureStatement' a statement describing how to capture instances of this model element from the real-world

definition

all text from the documentation until the first separator the normative specification of the model element

description

none additional informative information about the model element

documentation

the notes field in EA7 models, otherwise tag 'documentation' or tag 'description' a documentation field per model element that includes one or more descriptors, typically the notes field of the UML tool

example

tag 'example' an example illustrating the model element

globalIdentifier

ea:guidtoxml the globally unique identifier of the model element; that is, unique across models

language

tag 'language' the default language, if no language information is provided in definitions, descriptions, examples, etc.

legalBasis

tag 'legalBasis' the legal basis for the model element

primaryCode

tag 'primaryCode' the primary code for this model element

Examples:

<DescriptorSource descriptor="documentation" source="ea:notes"/>
<DescriptorSource descriptor="primaryCode" source="ea:alias"/>
<DescriptorSource descriptor="example" source="tag" tag="example"/>
<DescriptorSource descriptor="definition" source="sc:extract" token="PROLOG"/>
<DescriptorSource descriptor="description" source="sc:extract" token="Description"/>

A <DescriptorSource> element contains two required attributes and two conditional attributes, as above:

Attribute name Explanation

descriptor

The name of the well-known descriptor, see the list above. This attribute is required.

source

String specifying the source for the descriptor. Valid values are: 'ea:notes' for the notes field in EA7 models, 'ea:alias' for the alias field in EA7 models, 'tag' for a tagged value, 'none' for unused descriptors, 'sc:extract' for extracting the descriptor from the documentation. This attribute is required.

tag

The tag to use. This attribute is requried for source='tag'.

token

The token part of the separator that marks the start of the descriptor in the documentation. Separators are constructed as a concatenation of the extract separator (see the list of parameters above), whitespace, the token, whitespace and the extract separator. For example, the extract separator '–' and the token 'Description' specify the following separator string: '– Description –'. The value 'PROLOG' is a special value that extracts everthing from the start of the documentation field until the first separator. This attribute is requried for source='sc:extract'.

The file DescriptorSourcesINSPIRE.xml contains as an example the standard <DescriptorSource> elements as used in INSPIRE application schemas. It may be included in a configuration file via XInclude.

PackageInfo definitions

ShapeChange allows for two ways to specify that an incoming UML package should be understood to represent (or correspond to) an application schema in GML.  The first is via the “targetNamespace” tagged value, which will be discussed later.  The second is via a <PackageInfo> element under the <input> portion of the configuration file. This is useful, if for some reason the source model cannot be amended to include additional tagged values as required by the encoding rules.

The <PackageInfo> element specifies the namespace (and abbreviation), XSD document, and version for a package corresponding to a GML application schema (which ShapeChange will output as an XML Schema document). It is a single element with attributes:

<packages>
  <PackageInfo packageName=”My Application Schema” ns=”http://example.com/app” nsabr=”app” xsdDocument=”app.xsd” version=”1.0”/>
</packages>

The attributes for the <PackageInfo> element as as follows:

Attribute name Explanation
packageName (Required) The name of the package/schema.  This must correspond to the name of the package within the UML model.
ns The namespace URL of the schema. This attribute corresponds to the tagged value 'targetNamespace' of an application schema package.
nsabr The namespace abbreviation. This attribute corresponds to the tagged value 'xmlns' of an application schema package.
xsdDocument The desired filename of the output XML Schema document. This attribute corresponds to the tagged value 'xsdDocument' of an application schema package.
version The version of the application schema. This attribute corresponds to the tagged value 'version' of an application schema package.