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 recognized for the <input> element include the following:
|Parameter Name||Default Value||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’.
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).
True, if xxxEncodingRule tagged values shall be ignored (because the model is wrong and needs cleanup), else false.
|inputModelType||XMI10||A string describing the format of the application schema to be transformed. The current options are:
The path to the input file, relative to the working directory. For XMI 1.0 models, URLs are supported, too.
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:
|username and password||none||
If required to access the model (typically an EA repository), provide your username and password.
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).
|appSchemaName||<blank>||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||<blank>||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||<blank>||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.|
|publicOnly||true||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.|
|skipSemanticValidationOfShapeChangeConfiguration (since 2.2.0)
||false||If ‘true’, semantic validation of the ShapeChange configuration will not be performed (further details can be found here).|
|sortedOutput||false||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>”.|
|checkingConstraints||enabled||(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.|
|false||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.|
|classTypesToCreateConstraintsFor||if the parameter is not configured, constraints are considered for all class categories||(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||true||(Valid for EA7 input only) If the parameter is “false”, constraints defined for properties (attributes and association roles) will not be created.|
|addTaggedValues||<blank>||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.|
|representTaggedValues||<blank>||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.|
|gsipEnumLiteralOrderBy||alpha||(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:
Note: This should be moved to a <TargetXmlSchema> option, since it is really more properly target-related.
|gsipSuppressDatatypes||false||(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.|
|gsipSuppressAttributes||false||(Valid for GSIP input only) A string representing a Boolean value; if “true”, attributes will not be read/transformed.|
|kmlReferenceType||alternate||(Valid for GSIP input only) A text string that indicates how KML reference strings should be represented. (Add more information.)|
|oclConstraintTypeRegex||(OCL|Invariant)||(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.|
|folConstraintTypeRegex||(SBVR)||(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
|tmpDirectory||temp||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||<blank>||(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.|
|constraintExcelFile||<blank>||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.|
|taggedValueImplementation||<blank>||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.|
|useStringInterning||false||If set to “true”, ShapeChange will use string interning to reduce the memory footprint.|
|language (since 2.0.2)||en||The language to use in case descriptors for model elements like definitions or aliases are multilingual. Use two letter language codes.|
|extractSeparator (since 2.0.2)||—||The start and end part of any separator used to split the documentation of a model element. See “Descriptor sources” below for additional information.|
|onlyDeferrableOutputWrite||false||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.
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.|
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 name of the well-known stereotype, from the list given in the description of the UML profile."|
|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.
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:
|The name of the well-known tag.|
|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.
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:
|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|
|all text from the documentation until the first separator||the normative specification of the model element|
|none||additional informative information about the model element|
|tag 'example'||an example illustrating the model element|
|the alias field in EA7 models, otherwise tag 'alias'||an alternative, human-readable name for the model element|
|tag 'legalBasis'||the legal basis for the model element|
|tag 'dataCaptureStatement'||a statement describing how to capture instances of this model element from the real-world|
|tag 'primaryCode'||the primary code for this model element|
|tag 'language'||the default language, if no language information is provided in definitions, descriptions, examples, etc.|
<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 name of the well-known descriptor, see the list above. This attribute is required.|
|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.|
|The tag to use. This attribute is requried for source='tag'.|
|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.
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:
|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.|