7.5.3. Custom File Formats

Engineering Knowledge Manager

Administration Guide | Chapter 7: Defining Custom Types | 7.5. Custom Type Examples |

7.5.2. Custom Analysis Projects |  | 7.6. Extending Built-in Types
Prev |  | Next

### 7.5.3. Custom File Formats

In addition to handling and storing files of any type, EKM provides you with the capability to create custom file formats.

You can create custom file formats to:

- Extract metadata, images, or reports from a format that EKM does not support.

- Define user-defined properties for a file format that users will be prompted to enter values for, whenever files of this format are uploaded.

Let's look at how you can define a custom file format by means of an example.

Suppose you have an in-house solver that requires an input file in a proprietary format and you want EKM to automatically extract key metadata from this file after it is uploaded. You also want users to enter some additional property values after the upload process. Finally you want users to create a Simulation Details Report from the file. The custom type definition for this file format is shown below.

Example 7.10: Custom File Definition

    <type name="AcmeSimulationFile" extends="CaeModelFile" label="Acme Simulation File"
            version="1.0.0">
            <properties>
                <property name="version" type="String" specifiedBy="extractor" label="Version" />
                <property name="iterations" type="Long" specifiedBy="extractor" label="Iterations"/>
                <property name="physicalModels" label="Physical Models" type="String"
                        specifiedBy="extractor" multivalued="true">
                    <enumeration>Stress</enumeration>
                    <enumeration>Thermal</enumeration>
                    <enumeration>Vibration</enumeration>
                    <enumeration>Magnetostatic</enumeration>
                </property>
            </properties>
            <mixins>
            	<mixin>ModelAttributes</mixin>
            </mixins>
            <typeAttributes>
                <typeAttribute name="extension" value="acm"/>
                <typeAttribute name="metaDataApplication" value="simExtract"/>
                <typeAttribute name="reportApplication" value="simReport" />
            </typeAttributes>
        </type>

In Example 7.10: Custom File Definition, the new type is named `AcmeSimulationFile` and is given the label Acme Simulation File that will appear in the user interface. If you just need to extract metadata from the file, then you can extend the new custom file format from the `File` type. However, if you want to extract image or simulation details from the file (for a Simulation Details Report), then you will need to extend it from the `CaeModelFile` type. This allows the Simulation Details Report action menu to be visible in the user interface for this file.

This custom data type defines three properties that are automatically extracted by the metadata extraction application: `version`, `iterations`, and `physicalModels`. It also defines some `type` attributes. As previously explained, `type` attributes are used to specify settings that apply to all instances of that type. Type attributes require a `name` and a `value` to be specified. The valid options for `name` depend on the base type that you are extending. See Defining Type Attributes for a Custom Type for more details.

In our example, the extension of the `AcmeSimulationFile` type is `acm`. This means that any file with the extension `.acm` (for example, `my-simulation-file.acm`) will be treated as an `AcmeSimulationFile` file type by EKM. The type also specifies applications for extracting metadata and reports.

Finally, the `AcmeSimulationFile` type also specifies a `mixin` named `ModelAttributes`. Mixins are used to define sharable groups of properties or children. The `ModelAttributes` `mixin` is shown in the following listing (Figure 7.11: ModelAttribute mixin Example). This `mixin` defines two user-defined properties: `revisionStatus` and `reviewedBy`. Because the `AcmeSimulationFile` type definition includes this `mixin`, it will also include these properties. Therefore, when a file of this type is uploaded, a user will be asked to enter values for these properties.

Figure 7.11: ModelAttribute mixin Example

    <mixin name="ModelAttributes" version="1.0.0">
            <properties>
                <property name="revisionStatus" label="Revision Status"  type="String" required="true">
                    <enumeration>Draft</enumeration>
                    <enumeration>Released</enumeration>
                    <enumeration>Obsolete</enumeration>
                </property>
                <property name="reviewedBy" label="Reviewed By" type="String" required="true"
                   multivalued="true"/>
            </properties>
    </mixin>

#### 7.5.3.1. Extracting Metadata from Custom File Formats

The application for extracting metadata from custom file formats is an external program that is executed by EKM whenever a file of the associated format is uploaded. It can be written in any language and must fulfill the following requirements:

- accept the file name as a command line parameter

- read the input file from the current working directory

- write the metadata in a file named `ekm-meta-data.xml` to the current working directory

- support only metadata files that adhere to the format specified in the `meta-data.xsd` schema file

The schema definition for metadata files is simple and the code listing is shown in Figure 7.12: meta-data.xsd Schema Definition Listing. The complete listing is included in the `EKM_HOME/schema` folder.

Figure 7.12: meta-data.xsd Schema Definition Listing

    <?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    	targetNamespace="http://www.ansys.com/ekm/metaData"
    	xmlns:ekmMetaData="http://www.ansys.com/ekm/metaData">

    	<xsd:complexType name="MetaData">
    		<xsd:attribute name="name" type="xsd:string" use="required" />
    		<xsd:attribute name="value" type="xsd:string" use="required" />
    	</xsd:complexType>

    	<xsd:complexType name="ChildMetaDataList">
    		<xsd:sequence>
    			<xsd:element name="data" type="ekmMetaData:MetaData" minOccurs="0" maxOccurs="unbounded"/>
    			<xsd:element name="child" type="ekmMetaData:ChildMetaDataList" minOccurs="0"
                  maxOccurs="unbounded"/>
    		</xsd:sequence>
    		<xsd:attribute name="name" type="xsd:string" use="required"/>
    		<xsd:attribute name="type" type="xsd:string" use="required"/>
    	</xsd:complexType>

    	<xsd:complexType name="MetaDataList">
    		<xsd:sequence>
    			<xsd:element name="data" type="ekmMetaData:MetaData" minOccurs="0" maxOccurs="unbounded"/>
    			<xsd:element name="child" type="ekmMetaData:ChildMetaDataList" minOccurs="0"
                   maxOccurs="unbounded"/>
    		</xsd:sequence>
    	</xsd:complexType>

    	<xsd:element name="meta-data" type="ekmMetaData:MetaDataList" />

    </xsd:schema>

The schema definition shows that a metadata file should have a `root` element named `meta-data` that can have any number of elements named `data`. Each `data` element has two attributes: `name` and `value`. The `name` should correspond to a property whose `specifiedBy` attribute is set to `extractor`. The `value` is the extracted value of that property. Multi-valued properties can be specified in a comma-separated manner.

Figure 7.13: Sample Metadata File for Custom AcmeSimulationFile Type shows the listing for a sample metadata file of type `AcmeSimulationFile` that was defined above. The `ekmMetaData` namespace is used for validating the file before it is read by EKM.

Important: The first two lines and the last line of this listing should be present in ALL metadata files.

Figure 7.13: Sample Metadata File for Custom AcmeSimulationFile Type

    <ekmMetaData:meta-data
    	xmlns:ekmMetaData="http://www.ansys.com/ekm/metaData">
    	   <data name="iterations" value="23"/>
    	   <data name="version" value="mysim-1.0"/>
          <data name="physicalModels" value="Stress,Magnetostatic"/>
    </ekmMetaData:meta-data>

#### 7.5.3.2. Extracting Reports from Custom File Formats

You can write custom applications for extracting a Simulation Details Report and images from a format that EKM does not support.

The application for extracting a Simulation Details Report can be written in any programming language and must fulfill the following requirements:

- accept the file name as a command line parameter

- read the input file from the current working directory

- write the report in a file named ekm-report.xml to the current working directory

- support only report files that adhere to the format specified in the report.xsd schema file

A listing of the schema definition for a custom extraction report is shown in Figure 7.14: Listing of report.xsd Schema Definition. The complete listing is included in the EKM_HOME/schema folder.

Figure 7.14: Listing of report.xsd Schema Definition

    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    	targetNamespace="http://www.ansys.com/ekm/report"
    	xmlns:ekmReport="http://www.ansys.com/ekm/report">

    	<xsd:complexType name="Image">
    		<xsd:attribute name="name" type="xsd:string" use="required" />
    		<xsd:attribute name="src" type="xsd:string" use="required" />
    	</xsd:complexType>

    	<xsd:complexType name="Link">
    		<xsd:attribute name="name" type="xsd:string" use="required" />
    		<xsd:attribute name="src" type="xsd:string" use="required" />
    	</xsd:complexType>

    	<xsd:complexType name="Text">
    		<xsd:simpleContent>
    			<xsd:extension base="xsd:string">
    				<xsd:attribute name="name" type="xsd:string"
    					use="required" />
    				<xsd:attribute name="showFormattedContent"
    					type="xsd:string" use="optional" />
    			</xsd:extension>
    		</xsd:simpleContent>
    	</xsd:complexType>

    	<xsd:complexType name="Column">
    		<xsd:attribute name="name" type="xsd:string" use="required" />
    		<xsd:attribute name="id" type="xsd:string" use="optional" />
    	</xsd:complexType>

    	<xsd:complexType name="Row">
    		<xsd:sequence>
    			<xsd:element name="value" type="xsd:string" minOccurs="0"
    				maxOccurs="unbounded">
    			</xsd:element>
    		</xsd:sequence>
    	</xsd:complexType>

    	<xsd:complexType name="Table">
    		<xsd:sequence>
    			<xsd:element name="column" type="ekmReport:Column"
    				minOccurs="0" maxOccurs="unbounded" />
    			<xsd:element name="row" type="ekmReport:Row" minOccurs="0"
    				maxOccurs="unbounded" />
    		</xsd:sequence>
    		<xsd:attribute name="name" type="xsd:string" use="required" />
    		<xsd:attribute name="caption" type="xsd:string" use="optional" />
    		<xsd:attribute name="showHeaders" type="xsd:boolean"
    			use="optional" />
    		<xsd:attribute name="showBorder" type="xsd:boolean"
    			use="optional" />
    	</xsd:complexType>

    	<xsd:complexType name="Section">
    		<xsd:choice minOccurs="0" maxOccurs="unbounded">
    			<xsd:element name="section" type="ekmReport:Section"/>
    			<xsd:element name="image" type="ekmReport:Image"/>
    			<xsd:element name="link" type="ekmReport:Link"/>
    			<xsd:element name="text" type="ekmReport:Text"/>
    			<xsd:element name="table" type="ekmReport:Table"/>
    		</xsd:choice>
    		<xsd:attribute name="name" type="xsd:string" use="required" />
    	</xsd:complexType>

    	<xsd:element name="section" type="ekmReport:Section" />
    </xsd:schema>

Figure 7.14: Listing of report.xsd Schema Definition shows that the `root` element of the report file is named `section`. A `section` can have any number of `section`, `image`, `link`, `text`, and `table` child elements.

The `image` element has an `src` attribute for pointing to the image file. All images that need to be included in the report should be placed in a folder called `ekm-report-files` in the current working directory of the report application. The `src` attribute of the image element should reference the image file using `reportFiles</image-name>`. For example, if the report application generates an image named `plot.gif`, then it needs to be included in the report. Furthermore, this image file should be placed in the `ekm-report-files` sub-folder in the current working directory, and the image element defined with the code shown below.

Figure 7.15: Report Image Element

    <image name="Plot Name' src="reportFiles/plot.gif"/>

The `table` element can have any number of `column` and `row` child elements. The format of the table can be controlled by `showBorder` and `showHeaders` attributes. The column element has a `name` attribute that is shown in the column header. The `row` element has a number of child elements named `value`. Each `value` element specifies the value for a particular row and column. The number of value elements must be the same as the number of columns in the table.

Figure 7.16: Sample Report File for AcmeSimulationFile Type shows the listing for a sample report file for the `AcmeSimulationFile` type previously defined. A table named `info` is defined with two columns: `condition` and `value` and four rows. Each row has two `value` elements for the condition and value columns.

Figure 7.16: Sample Report File for AcmeSimulationFile Type

    <ekmReport:section xmlns:ekmReport="http://www.ansys.com/ekm/report" name="Summary
       report for file-1.acm">
          <table name="info">
            <column name="condition"/>
            <column name="value"/>
            <row><value>iterations</value><value>23</value></row>
            <row><value>version</value><value>mysim-1.0</value></row>
            <row><value>tolerance</value><value>0.02</value></row>
            <row><value>physicalModels</value><value>Stress, Magnetostatic</value></row>
          </table>
    </ekmReport:section>

Contains proprietary and confidential information of ANSYS, Inc. and its subsidiaries and affiliates.

Prev | Up / Contents | Next

Release 18.2 - © ANSYS, Inc. All rights reserved.