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="https://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 comma-separated 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.

NOTE (since v2.7.0): If ‘*’ is set as parameter value, then all tagged values will be loaded from the model.

addStereotypes

(since v2.9.0)

Default Value: <blank>

Explanation: A comma-separated list of additional stereotypes that should be included when reading the model into memory. ShapeChange recognizes a set of well-known stereotypes, but at runtime it may be desirable to include others, depending on the input model. If ‘*’ is set as parameter value, then all stereotypes will be loaded from the model.

NOTE:

• Any stereotype loaded from the model will first be normalized, i.e. mapped according to the stereotype aliases defined in the configuration.
• A well-known stereotype is typically converted to lower-case.

applyDescriptorSourcesWhenLoadingScxml

(since v2.9.0)

Default Value: false

Explanation: Set this parameter to “true” in order to apply descriptor sources defined in the input configuration, whenever SCXML is loaded (i.e. as input model, but also by transformations and targets).

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 / constraintLoading

Note: Alias “constraintLoading” available since v2.9.0.

Default Value: enabled

Explanation: (up until ShapeChange v2.8.0, 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: (up until ShapeChange v2.8.0, 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: (up until ShapeChange v2.8.0, 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’.

excludedPackages

Default Value: <blank>

Explanation: Comma-separated list of package names to exclude when loading the model. Direct and indirect subpackages will also be ignored. This can be useful to speed up loading the model (especially from EA repositories – not so much from SCXML), for example when excluding ISO packages.

More specifically, the behavior of this parameter (since ShapeChange v2.11) is as follows:

• If a class C belongs to an excluded package, it will not be loaded.
  • All attributes and navigable roles that belong to class C will not be loaded, either.
  • Any attribute whose value type is class C will internally receive type.id ‘unknown’.
  • An association between class C and a class D that is loaded (in other words, D does not belong to an excluded package) will be removed. However, if D has a navigable association role whose value type is C, then that role will be turned into an attribute (with type.id ‘unknown’).
  • If class C is an association class, and the according association is between classes that do not belong to excluded packages, then the association will be loaded as a simple association (not as an association class).
• Assoziations between classes from excluded packages will not be loaded.
  • The roles of the association will thus also not be loaded.
  • If such an association is an association class, i.e. there is a class that is linked to the association in an association class relationship, and that class does not belong to an excluded package, then the class will still be loaded.
• An inheritance relationship between a class E that is excluded and a class F that is not excluded will not be created (because E will not be present in the model once the loading process has been finished).

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

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: https://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
• GCSR: a GCSR 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: Since v2.9.0, it is also possible to provide the fully qualified name of a Java class that implements the Model interface (i.e. de.interactive_instruments.ShapeChange.Model.Model.java).

NOTE: Loading a model from an EA repository using the 32bit EA API and 32bit Java, or performing processing (input loading, a transformation, or a target) that accesses an EA repository using this 32bit setup (EA API and Java), 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 GCSR 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.

loadLinkedDocuments

(since v2.5.0)

Type: Boolean (true or false)

Default Value: false

Explanation: (valid only for EA7 input) Set to ‘true’ to load linked documents for classes in schemas selected for processing.

NOTE:

• ShapeChange will store the linked documents in subdirectory “linkedDocuments” of the directory defined via the input parameter tmpDirectory.
• A linked document is a .docx file that typically provides an extensive amount of formatted documentation. The creation of a database model is an example of where linked documentation plays a role.

mainAppSchema

(available since v2.4.0)

Type: String

Default Value: none

Explanation: During a single execution of ShapeChange, a single or multiple application schemas can be processed. The relevant input parameters for controlling which schemas are selected for processing by ShapeChange are: appSchemaName, appSchemaNameRegex, and appSchemaNamespaceRegex.

Some ShapeChange targets process one schema at a time, and generate a result for each schema. However, ShapeChange also has targets, so called SingleTargets, which gather information from all schemas selected for processing, and generate a combined result for all these schemas. Examples of SingleTargets are: the SQL DDL target and the ArcGIS Workspace target.

If multiple schemas have been selected for processing, ShapeChange may need to get information from a specific schema, like target namespace, XML namespace abbreviation, and version. For output processing, version information can be important. By adding the mainAppSchema parameter to the input configuration, with the name of one of the application schemas that were selected for processing as value, ShapeChange will get this information from that schema.

navigatingNonNavigableAssociationsWhenParsingOcl

(available since v2.10.0)

Type: Boolean

Default Value: false

Explanation: By default, the ShapeChange OCL parser does not support navigating across non-navigable association roles, which is an optional feature according to the OCL standard. By setting the value of this parameter to true, navigation across non-navigable association roles while loading the input model is enabled.

NOTE: Since by default non-navigable association roles are ignored when parsing OCL expressions, the parameter must be set on any process where OCL constraints are parsed, i.e. also when performing a transformation. Therefore, this parameter is also documented as a common transformation parameter.

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

Type: String (of comma-separated values)

Default Value: <blank>

Explanation: A list of additional tagged values that should not only be read into memory, but also output (if appropriate).

Applies to the following targets:

• XmlSchema: The tagged values are represented via <appInfo> annotations. This is a ShapeChange-specific extension to the standard encoding rules; see here.
• FeatureCatalogue (since v2.5.1): The tagged values of a model element will be represented. Applies to the following output formats: DOCX, HTML, FRAMEHTML. Note, however, that due to the specific representation of code lists in these formats, the tagged values of code lists and their codes are not represented.
• SqlDdl (since v2.6.0): Applies to the database UML model output. Requires that rule-sql-all-databaseModel and rule-sql-all-representTaggedValues are included in the encoding rule.
• ArcGIS Workspace (since v2.6.0): Requires that rule-arcgis-all-representTaggedValues is included in the encoding rule.

repositoryFileNameOrConnectionString

Default Value: none

Explanation: This parameter can be used instead of parameter ‘inputFile’ (if both are configured, ‘inputFile’ will be ignored). 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;

scxmlXsdLocation

(since 2.9.0)

Default Value: none

Explanation: This parameter can be used ot provide the location (as a URL or a file path) of an XML Schema to validate SCXML. If this parameter is not set, ShapeChange will parse SCXML without validating it.

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: true

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.

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:

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)

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

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:

NOTE: ShapeChange has a set of hard-coded tag names, which are commonly referred to as the set of well-known tagged values. That set can be extended via the input parameters addTaggedValues and representTaggedValues. The ‘wellknown’ tag of a <TagAlias> must be one of these tags. Multiple <TagAlias> elements can be defined to map different tags to the same 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:

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:

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: