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:

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>



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