ANSYS EKM Administration Guide

ANSYS EKM Administration Guide
ANSYS, Inc.
Southpointe
275 Technology Drive
Canonsburg, PA 15317
ansysinfo@ansys.com
http://www.ansys.com
(T) 724-746-3304
(F) 724-514-9494
Release 15.0
November 2013
ANSYS, Inc. is
certified to ISO
9001:2008.
Copyright and Trademark Information

2013 SAS IP, Inc. All rights reserved. Unauthorized use, distribution or duplication is prohibited.
ANSYS, ANSYS Workbench, Ansoft, AUTODYN, EKM, Engineering Knowledge Manager, CFX, FLUENT, HFSS and any
and all ANSYS, Inc. brand, product, service and feature names, logos and slogans are registered trademarks or
trademarks of ANSYS, Inc. or its subsidiaries in the United States or other countries. ICEM CFD is a trademark used
by ANSYS, Inc. under license. CFX is a trademark of Sony Corporation in Japan. All other brand, product, service
and feature names or trademarks are the property of their respective owners.
Disclaimer Notice
THIS ANSYS SOFTWARE PRODUCT AND PROGRAM DOCUMENTATION INCLUDE TRADE SECRETS AND ARE CONFIDENTIAL AND PROPRIETARY PRODUCTS OF ANSYS, INC., ITS SUBSIDIARIES, OR LICENSORS. The software products
and documentation are furnished by ANSYS, Inc., its subsidiaries, or affiliates under a software license agreement
that contains provisions concerning non-disclosure, copying, length and nature of use, compliance with exporting
laws, warranties, disclaimers, limitations of liability, and remedies, and other provisions. The software products
and documentation may be used, disclosed, transferred, or copied only in accordance with the terms and conditions
of that software license agreement.
ANSYS, Inc. is certified to ISO 9001:2008.
U.S. Government Rights

For U.S. Government users, except as specifically granted by the ANSYS, Inc. software license agreement, the use,
duplication, or disclosure by the United States Government is subject to restrictions stated in the ANSYS, Inc.
software license agreement and FAR 12.212 (for non-DOD licenses).
Third-Party Software
See the legal information in the product help files for the complete Legal Notice for ANSYS proprietary software
and third-party software. If you are unable to access the Legal Notice, please contact ANSYS, Inc.
Published in the U.S.A.
Table of Contents
1. Using This Guide ..................................................................................................................................... 1
2. Overview of Servers and Workspaces ..................................................................................................... 3
2.1. Distributed Servers and Caching ....................................................................................................... 4
2.1.1. Cache Architecture ................................................................................................................... 5
2.1.2. Cache Configuration ................................................................................................................ 5
3. Setting Up Users and Groups .................................................................................................................. 7
3.1. Introduction to Users and Groups ..................................................................................................... 7
3.2. Adding and Modifying Users ............................................................................................................. 8
3.2.1. Adding a New User .................................................................................................................. 8
3.2.2. Editing a Users Profile ............................................................................................................ 11
3.3. Forcing the Logout of a User ........................................................................................................... 11
3.4. Adding and Modifying Groups ........................................................................................................ 11
3.4.1. Adding a New Group .............................................................................................................. 11
3.4.2. Editing Group Membership .................................................................................................... 12
4. Creating and Managing Workspaces From the Administration Interface ............................................ 15
4.1. Logging In and Out of the EKM Server Administration ..................................................................... 15
4.2. Changing the Superuser Password .................................................................................................. 17
4.3. Resetting a Lost Superuser Password ............................................................................................... 17
4.4. Cleaning Up Unused Files ................................................................................................................ 18
4.5. Creating a New, Empty Workspace ................................................................................................... 19
4.6. Creating a New Workspace from an Exported Workspace ................................................................. 21
4.7. Renaming Workspaces .................................................................................................................... 23
4.8. Deleting Workspaces ...................................................................................................................... 23
4.8.1. Deleting Workspaces from Evaluation Servers ......................................................................... 24
4.8.2. Deleting Workspaces for Production Servers ........................................................................... 26
4.9. Migrating Workspaces ..................................................................................................................... 27
5. Restricted and Unrestricted Configuration of Workspaces .................................................................. 31
5.1. Restricted Configuration ................................................................................................................. 31
5.1.1. Starting Restricted Configuration ........................................................................................... 32
5.1.2. Applying the Configuration .................................................................................................... 33
5.1.3. Reverting to a Previous Configuration ..................................................................................... 34
5.1.4. Accepting the Configuration .................................................................................................. 34
5.2. Unrestricted Configuration .............................................................................................................. 36
5.3. Configuring Workspace Settings ...................................................................................................... 37
5.3.1. Schema Definition .................................................................................................................. 38
5.3.2. Configuration Settings in WorkspaceConfig.xml ...................................................................... 38
6. Configuring EKM Server Settings ......................................................................................................... 45
6.1. Schema Definition for an EKM Server ............................................................................................... 45
6.2. General Server Settings ................................................................................................................... 46
6.3. Optional Settings ............................................................................................................................ 59
7. Defining Custom Types ......................................................................................................................... 63
7.1. Overview of Custom Types .............................................................................................................. 63
7.1.1. About Built-in Types ............................................................................................................... 64
7.2. Suggested Steps for Defining Custom Types .................................................................................... 65
7.3. Defining Custom Types Directly in EKM ........................................................................................... 66
7.3.1. Defining a New Custom Type .................................................................................................. 66
7.3.1.1. Defining Properties for a Custom Type ........................................................................... 68
7.3.1.2. Defining Children for a Custom Type .............................................................................. 70
7.3.1.3. Defining Mixins for a Custom Type ................................................................................. 71
7.3.1.4. Defining Type Attributes for a Custom Type .................................................................... 72
Release 15.0 - ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates.
iii
Administration Guide
7.3.1.5. Defining Actions for a Custom Type ................................................................................ 80
7.3.2. Editing a Custom Type ............................................................................................................ 83
7.4. Defining Custom Types Using XML .................................................................................................. 83
7.4.1. Schema Definition for Custom Types ....................................................................................... 84
7.4.2. Defining Properties Using XML ............................................................................................... 85
7.4.3. Defining Actions Using XML ................................................................................................... 89
7.5. Custom Type Examples ................................................................................................................... 91
7.5.1. Custom Folder Structures ....................................................................................................... 91
7.5.2. Custom Analysis Projects ........................................................................................................ 93
7.5.3. Custom File Formats ............................................................................................................... 94
7.5.3.1. Extracting Metadata from Custom File Formats .............................................................. 96
7.5.3.2. Extracting Reports from Custom File Formats ................................................................. 97
7.6. Extending Built-in Types .................................................................................................................. 99
7.6.1. Migrating Built-in extensions or Custom Types ........................................................................ 99
8. Defining EKM Servers, Queues, and External Applications ................................................................ 101
8.1. Adding EKM Servers ...................................................................................................................... 102
8.2. Defining EKM Cache Servers .......................................................................................................... 102
8.2.1. Creating a New EKM Cache Server ........................................................................................ 102
8.2.2. Editing an Existing EKM Cache Server .................................................................................... 103
8.2.3. Types of Queues ................................................................................................................... 104
8.2.4. Managing Queues ................................................................................................................ 105
8.2.4.1. Synchronizing Job Submission Queues ........................................................................ 106
8.2.4.2. Defining Job Submission Queue Settings ..................................................................... 107
8.3. Defining External Applications ...................................................................................................... 110
8.3.1. Predefined External Applications .......................................................................................... 110
8.3.2. Defining External Applications Directly in EKM ...................................................................... 112
8.3.2.1. Creating a New External Application ............................................................................ 112
8.3.2.2. Editing an External Application Definition .................................................................... 114
8.3.2.3. Editing an External Application Using XML ................................................................... 115
8.3.3. Defining External Applications Using XML ............................................................................ 116
8.3.3.1. Schema Definition for Applications .............................................................................. 116
8.3.3.2. Defining External Applications Using XML .................................................................... 118
8.4. Running Batch Jobs in EKM ........................................................................................................... 118
8.4.1. Running RSM Jobs in EKM .................................................................................................... 119
8.4.2. Using Other Batch Systems with RSM .................................................................................... 120
8.5. Installing and Configuring RSM ..................................................................................................... 120
8.5.1. Windows RSM Installation/Configuration .............................................................................. 121
8.5.2. Linux RSM Installation/Configuration .................................................................................... 122
8.6. Running Interactive Jobs in EKM .................................................................................................... 124
8.6.1. Running Remote Desktop Sessions ....................................................................................... 125
9. Configuring EKM Mobile ..................................................................................................................... 127
9.1. Running the Mobile Connector on the Same Host as the EKM Server .............................................. 127
9.2. Running the Mobile Connector on a Host Other than the EKM Server ............................................. 128
10. Defining and Configuring Lifecycles ................................................................................................. 131
10.1. Introduction to Lifecycles ............................................................................................................ 131
10.2. Lifecycle Terminology .................................................................................................................. 132
10.3. Basic Steps for Creating, Configuring, and Managing Lifecycles ..................................................... 133
10.4. Launching EKM Studio ................................................................................................................ 133
10.5. Defining Lifecycles in EKM Studio ................................................................................................ 134
10.5.1. Steps for Defining New Lifecycles ....................................................................................... 135
10.5.2. Defining and Editing Lifecycle Stages .................................................................................. 136
10.5.2.1. Inserting New Stages ................................................................................................. 136
iv
10.5.2.2. Editing Stages ............................................................................................................ 137
10.5.2.3. Renaming Stages ....................................................................................................... 138
10.5.2.4. Deleting Stages ......................................................................................................... 138
10.5.3. Defining and Editing Lifecycle Transitions ........................................................................... 139
10.5.3.1. Inserting New Transitions ........................................................................................... 139
10.5.3.2. Editing Transitions ..................................................................................................... 139
10.5.3.3. Using Macros in Lifecycle Definitions .......................................................................... 141
10.5.3.4. Deleting Transitions ................................................................................................... 142
10.5.4. Saving Lifecycle Files .......................................................................................................... 143
10.5.5. Opening Lifecycle Files ....................................................................................................... 143
10.5.6. Editing Lifecycle Attributes ................................................................................................. 144
10.6. Enabling Lifecycles ...................................................................................................................... 146
10.7. Displaying Lifecycles ................................................................................................................... 147
10.8. Promoting a Lifecycle Stage ........................................................................................................ 149
10.9. Demoting a Lifecycle Stage ......................................................................................................... 150
10.10. Managing Lifecycle Signoff Requests ......................................................................................... 150
10.10.1. Approving a Lifecycle Signoff Request .............................................................................. 153
10.10.2. Rejecting a Lifecycle Signoff Request ................................................................................ 153
10.10.3. Cancelling a Lifecycle Signoff Request ............................................................................... 154
10.11. Setting a Lifecycle Stage ............................................................................................................ 155
10.12. Configuring Lifecycles for a Workspace ...................................................................................... 155
11. Scripts and Journals .......................................................................................................................... 157
11.1. Introduction to Scripts and Journals ............................................................................................ 157
11.2. Defining Scripts Using a Supported Scripting Language ............................................................... 158
11.3. Using EKM's Scripting Interface ................................................................................................... 159
11.4. Using Sample Scripts Supplied by EKM ........................................................................................ 160
11.4.1. Python Scripts .................................................................................................................... 161
11.5. Scripting Actions ......................................................................................................................... 162
11.6. Recording Journal Scripts ............................................................................................................ 162
11.6.1. Start Recording a Journal Script .......................................................................................... 165
11.6.2. Stop Recording a Journal Script .......................................................................................... 166
11.7. Running Journal Scripts ............................................................................................................... 166
11.8. Example of Journal Recording and Execution ............................................................................... 166
11.9. Running Python and BeanShell Scripts From a Command Window ............................................... 167
12. Defining Custom Dialogs, Wizards and Applications ........................................................................ 169
12.1. Defining Custom Dialog Boxes .................................................................................................... 169
12.1.1. Defining a Custom User Interface ........................................................................................ 169
12.1.1.1. XHTML Files ............................................................................................................... 171
12.1.1.2. Sample XHTML Code for a Custom Dialog Box ............................................................ 172
12.1.1.3. User Interface Components ........................................................................................ 174
12.1.1.3.1. Layout and Style ............................................................................................... 174
12.1.1.3.2. Embedded Images ............................................................................................ 174
12.1.1.3.3. User Inputs ....................................................................................................... 174
12.1.1.3.4. Check Boxes ...................................................................................................... 176
12.1.1.3.5. Radio Buttons ................................................................................................... 176
12.1.1.3.6. Selection Menu ................................................................................................. 176
12.1.1.3.7. List Box ............................................................................................................. 177
12.1.2. Defining Dialog Box Steps and Variables ............................................................................. 177
12.2. Steps for Creating and Using Custom Applications ....................................................................... 179
12.3. Creating a Custom Application .................................................................................................... 180
12.4. Executing a Custom Application .................................................................................................. 181
12.5. Modifying an EKM Application .................................................................................................... 184
13. Units: Defining and Configuring Using XML ..................................................................................... 187
13.1. Schema Definition for Units ......................................................................................................... 188
13.2. Adding a New Unit ...................................................................................................................... 189
13.3. Adding a New Quantity ............................................................................................................... 190
13.4. Adding a New Unit System .......................................................................................................... 190
14. Transferring a Workspace Between EKM Servers .............................................................................. 191
14.1. Exporting a Workspace ................................................................................................................ 191
14.2. Importing a Workspace ............................................................................................................... 192
15. Miscellaneous Tasks .......................................................................................................................... 193
15.1. Configuring a Common Scripts Library ........................................................................................ 193
15.2. Gathering Usage Statistics ........................................................................................................... 193
15.3. Remote File Servers ..................................................................................................................... 194
15.3.1. Defining a New Remote File Server ..................................................................................... 194
15.3.2. Built-in Remote File Servers ................................................................................................ 196
15.4. Managing Logs ........................................................................................................................... 196
15.5. Installing VCollab and Configuring EKM for 3D Visualization ......................................................... 197
15.6. Using the EKM Server Diagnostics Tool ........................................................................................ 198
15.7. Lifecycle Approval Process for Workflows ..................................................................................... 198
16. Backing Up and Restoring EKM ......................................................................................................... 199
16.1. Data Stored by EKM ..................................................................................................................... 199
16.1.1. The EKM Database .............................................................................................................. 199
16.1.2. The EKM Data Directory ...................................................................................................... 199
16.1.3. The EKM Base Directory ...................................................................................................... 199
16.2. Backing Up EKM .......................................................................................................................... 200
16.2.1. Backup Procedure .............................................................................................................. 200
16.2.1.1. Garbage Collection .................................................................................................... 201
16.2.1.2. Backing up the EKM Database .................................................................................... 202
16.2.1.3. Backing up the EKM Data, EKM Base, Job Data and Repository Directories ................... 202
16.3. Restoring EKM ............................................................................................................................ 202
16.3.1. Restoring Procedure ........................................................................................................... 202
16.3.1.1. Restoring the EKM Database ...................................................................................... 203
16.3.1.2. Restoring the EKM Data, EKM Base, Job Data and Repository Directories ...................... 203
16.3.1.3. Clearing the Search Indices ........................................................................................ 203
A. Java Security Manager and EKM Scripting .............................................................................................. 205
B. Built-in Types - Reference ....................................................................................................................... 207
B.1. Abaqus Input (AbaqusInput) ......................................................................................................... 207
B.2. Abaqus Output Database (AbaqusOutputDatabase) ...................................................................... 207
B.3. Abaqus Result (AbaqusResult) ....................................................................................................... 207
B.4. Adobe Acrobat Document (AdobePdfFile) ..................................................................................... 207
B.5. Analysis Project (AnalysisContainer) .............................................................................................. 207
B.6. Ansoft Designer File (AnsoftDesigner) ........................................................................................... 208
B.7. ANSYS Database/Mechanical APDL Database (AnsysDatabase) ...................................................... 209
B.8. ANSYS Input/Mechanical APDL Input (AnsysInput) ........................................................................ 209
B.9. ANSYS Output/Mechanical APDL Output (AnsysOutput) ................................................................ 210
B.10. ANSYS Result/Mechanical APDL Result (AnsysResult) ................................................................... 210
B.11. Applications Grid (ApplicationsGrid) ............................................................................................ 210
B.12. Approval Work item (ApprovalWorkItem) ..................................................................................... 210
B.13. Archive (Archive) ......................................................................................................................... 210
B.14. AUTODYN Database (AutodynDatabase) ...................................................................................... 210
B.15. Base Job (BaseJob) ...................................................................................................................... 210
B.16. Batch Job Submission Queue (BatchQueue) ................................................................................. 211
B.17. Batch Work Item (BatchWorkItem) ............................................................................................... 211
vi
B.18. BladeGen Database (BladeGenDatabase) ..................................................................................... 211
B.19. CAE Model File (CaeModelFile) .................................................................................................... 211
B.20. Cache Server (CacheServer) ......................................................................................................... 212
B.21. Catalog (Catalog) ........................................................................................................................ 212
B.22. CFX Definition (CfxDefinition) ...................................................................................................... 212
B.23. CFX Result (CfxResult) ................................................................................................................. 212
B.24. CFX Session File (CfxSessionFile) .................................................................................................. 212
B.25. CFX State File (CfxStateFile) ......................................................................................................... 213
B.26. Comparison Report (ComparisonReport) ..................................................................................... 213
B.27. Container (Container) .................................................................................................................. 213
B.28. Data Extraction Monitor (DataExtractionMonitor) ........................................................................ 213
B.29. Data Extraction Monitor Container (DataExtractionMonitorContainer) ......................................... 213
B.30. Data Extraction Queue (DataExtractionQueue) ............................................................................ 213
B.31. DesignXplorer Database (R11) (DesignXplorerDatabase) .............................................................. 213
B.32. DesignModeler Database (WorkBenchDesignModelerFile) ........................................................... 213
B.33. EKM Application (Application) ..................................................................................................... 214
B.34. EKM Journal File (ScriptFile) ......................................................................................................... 214
B.35. EKM Object (Model) .................................................................................................................... 214
B.36. EKM Server (Server) ..................................................................................................................... 215
B.37. EKM Type (Type) ......................................................................................................................... 215
B.38. EKM Workflow (Workflow) ........................................................................................................... 215
B.39. Engineering Data Database (R11) (WorkBenchEngineeringData) .................................................. 215
B.40. ePhysics File (AnsoftEPhysics) ...................................................................................................... 215
B.41. External Application (ExternalApplication) ................................................................................... 215
B.42. FE Model (FeModelInput) ............................................................................................................ 216
B.43. FE Modeler Database (FeModelerDatabase) ................................................................................. 216
B.44. File (File) ..................................................................................................................................... 216
B.45. File Server (ExternalResourceFs) .................................................................................................. 217
B.46. Fluent Case (FluentCase) ............................................................................................................. 217
B.47. Fluent Data (FluentData) ............................................................................................................. 218
B.48. Fluent Plot (FluentPlot) ................................................................................................................ 218
B.49. Folder (Folder) ............................................................................................................................ 218
B.50. Group (Group) ............................................................................................................................ 218
B.51. HFSS File (HfssProject) ................................................................................................................. 218
B.52. Image (Image) ............................................................................................................................. 219
B.53. Imported Report (ImportedReport) ............................................................................................. 219
B.54. Interactive Job (InteractiveJob) .................................................................................................... 219
B.55. Interactive Job Submission Queue (InteractiveQueue) ................................................................. 219
B.56. Job (Job) ..................................................................................................................................... 219
B.57. Job Submission Queue (JobSubmissionQueue) ........................................................................... 220
B.58. Job Submission Server (JobSubmissionServer) ............................................................................ 220
B.59. Job Template (JobTemplate) ........................................................................................................ 220
B.60. Job Template Container (JobTemplateContainer) ......................................................................... 220
B.61. Lifecycle (Lifecycle) ..................................................................................................................... 220
B.62. Maxwell File (AnsoftMaxwell) ...................................................................................................... 220
B.63. Meshing Database (MeshingDatabase) ........................................................................................ 222
B.64. Message Board (MessageBoard) .................................................................................................. 222
B.65. Microsoft Excel Worksheet (MSOfficeExcelFile) ............................................................................. 222
B.66. Microsoft Powerpoint Presentation (MSOfficePowerpointFile) ...................................................... 222
B.67. Microsoft Word Document (MSOfficeDocumentFile) .................................................................... 222
B.68. My Data (MyData) ....................................................................................................................... 222
B.69. NASTRAN Bulk Data (NastranBulkData) ........................................................................................ 222
vii
B.70. NASTRAN Result (NastranResult) ................................................................................................. 222
B.71. Polyflow Data (PolyflowData) ...................................................................................................... 222
B.72. Polyflow Export (UNS) (PolyflowExportFile) .................................................................................. 223
B.73. Process Container (ProcessContainer) .......................................................................................... 223
B.74. Public Saved Query (PublicSavedQueryContainer) ....................................................................... 223
B.75. Q3D File (AnsoftQ3D) .................................................................................................................. 223
B.76. Queue (Queue) ........................................................................................................................... 223
B.77. Remote Folder (RemoteFolder) .................................................................................................... 223
B.78. Report (Report) ........................................................................................................................... 223
B.79. Saved Query (SavedQuery) .......................................................................................................... 224
B.80. Saved Query Container (SavedQueryContainer) ........................................................................... 224
B.81. Search Results Report (SearchResultsReport) ............................................................................... 224
B.82. Shortcut (Link) ............................................................................................................................ 224
B.83. Simplorer File (AnsoftSimplorer) .................................................................................................. 224
B.84. Simulation Details Report (CaeModelSummaryReport) ................................................................ 224
B.85. Siwave File (AnsoftSiwave) .......................................................................................................... 224
B.86. Update Analysis Project Work Item (UpdateAnalysisProjectWorkItem) .......................................... 225
B.87. URL (Url) ..................................................................................................................................... 225
B.88. User (User) .................................................................................................................................. 225
B.89. VCollab File (VcollabCompressedFile) .......................................................................................... 225
B.90. Workbench Journal File (WorkBenchJournalFile) .......................................................................... 225
B.91. Workbench Design Point File (WorkBenchDesignPointFile) .......................................................... 225
B.92. Workbench Project Archive File (WorkBenchProjectArchiveFile) ................................................... 225
B.93. Workbench Project File (WorkBenchProjectFile) ........................................................................... 226
B.94. Workbench Project File R11 (WorkBenchProjectFileR11) ............................................................... 226
B.95. Workbench Simulation/Mechanical Database (WorkBenchSimulation) ......................................... 226
B.96. Workflow Process (Process) .......................................................................................................... 227
B.97. Work Item (WorkItem) ................................................................................................................. 227
C. Lifecycles: Defining and Configuring Using XML ..................................................................................... 229
C.1. Defining Lifecycles Using XML ....................................................................................................... 229
C.1.1. Schema Definition for Lifecycles ........................................................................................... 229
C.1.2. Defining a Lifecycle XML File ................................................................................................ 231
C.1.2.1. Types .......................................................................................................................... 231
C.1.2.2. Stages ......................................................................................................................... 231
C.1.2.3. Transitions ................................................................................................................... 233
viii
Chapter 1: Using This Guide

This guide covers administrative actions that the root user, superuser, or members of the admin
group perform on an EKM server. This guide assumes that an EKM server has already been installed
and set up following the instructions that are outlined in the Installation Guide.
If you are a non-admin user of EKM, refer to the User's Guide for topics relevant to you. For a general
overview of EKM and how to get started, refer to the Getting Started Guide.
Topics covered in this guide include:
Overview of Servers and Workspaces (p. 3)
Setting Up Users and Groups (p. 7)
Creating and Managing Workspaces From the Administration Interface (p. 15)
Restricted and Unrestricted Configuration of Workspaces (p. 31)
Configuring EKM Server Settings (p. 45)
Defining EKM Servers, Queues, and External Applications (p. 101)
Defining Custom Types (p. 63)
Defining and Configuring Lifecycles (p. 131)
Scripts and Journals (p. 157)
Defining Custom Dialogs, Wizards and Applications (p. 169)
Units: Defining and Configuring Using XML (p. 187)
Transferring a Workspace Between EKM Servers (p. 191)
Miscellaneous tasks (configuring a commons scripts library, gathering usage statistics, remote file
servers, managing logs, installing VCollab and configuring EKM for 3D visualization, using EKM server
diagnostics tool)
Backing Up and Restoring EKM (p. 199)
Some administrative tasks may require editing XML files. This guide assumes that you have a basic understanding of XML constructs and syntax (schema definition). If you are unfamiliar with these technologies, it is recommended that you review them before proceeding. http://www.w3.org offers extensive
tutorials and documentation. In particular, you should review the documentation on XML schemas
found at: http://www.w3.org/TR/xmlschema-0. While creating or editing XML files, it is recommended
that you use schema-aware XML editors. This will enable you to easily create configuration files that
are syntactically correct and reduce the likelihood of errors.
Chapter 2: Overview of Servers and Workspaces

EKM provides many ways to structure your information and manage multiple workgroups that are
spread across multiple locations. Two concepts are defined in EKM for this purpose:
EKM Server: A server that is a single installation of EKM whether it is clustered or not. For a clustered
installation, all nodes are considered as a single server.
Workspace: A partition of an EKM server that can contain its own data model, users, and groups.
Planning Server Installations

A single EKM server is sufficient if all users are located close to each other in the same region. But if a
substantial number of users are accessing EKM from remote offices over a WAN and the connection
speed between the offices is significantly impacting the data transfer rate, then multiple EKM servers
can be installed. The recommended architecture in this case is to use a master server, that will contain
globally shared data, and to have a number of regional servers. You could have one regional server for
each remote office or share a regional server with several closely located remote offices. Regional
servers provide the following benefits:
Data Cache: Any file uploaded to, or downloaded from, the master server from a remote office will
be cached in the regional server. If the file does not change on the master server, then any subsequent
download of that file from the remote office can be processed by the regional server without requiring
a data transfer from the master. If the file is changed, then it is downloaded and cached again in the
regional server.
Asynchronous Uploads: When a user in a remote office uploads data to the master server, it is first
stored in the regional server, which then uploads the data to the master server on the users behalf.
This enables users to quickly and asynchronously transfer large amount of data to the local server
and log out or disconnect from their machine, without waiting for the full transfer to be complete.
Regional Workspaces: If users in a remote office want to use EKM to collaborate amongst themselves
without incurring the latency of transferring data to or from the master server, they can create a
workspace in the regional server. These users can then directly log in to the regional server, bypassing
the master server altogether. This feature should be used with caution because it can cause data to
be isolated and impede the sharing of data between users and groups belonging to other offices or
regions. Therefore, these workspaces should be used only if the data being stored in regional servers
is only relevant to the local users and will not be generally used by others in the company. For more
information about workspaces, see How Workspaces are Used (p. 3).
A detailed overview of regional servers and how they can be used for caching is provided in Distributed
Servers and Caching (p. 4).
How Workspaces are Used

Workspaces are primarily used as independent data partitions that can be configured independently
of each other and that contain their own set of users and groups. Data from one workspace is not visible
to, and cannot be accessed from, another workspace. This way, workspaces can be viewed as independent
Overview of Servers and Workspaces

islands of data. Each server will have at least one production workspace that contains the primary data
and user accounts, but additional workspaces can be created as explained in Creating and Managing
Workspaces From the Administration Interface (p. 15). Some of the reasons for creating additional
workspaces are highlighted below:
Sandbox: Users and groups that are new to EKM may want to get acquainted with the system through
a dummy workspace. This workspace provides a sandbox for such users to experiment with usage,
data entry and other features of EKM without worrying about the constraints imposed by a production
workspace.
Test: Configuration changes, such as edits to object lifecycles and custom data types, can be made
dynamically in a workspace. But such changes usually require some iteration and review. Having a
separate test workspace for this purpose enables administrators and other stakeholders to experiment
with configuration changes without disturbing the production workspace.
In general, workspaces should not be used as a security mechanism to provide different groups in a
company with their own private space. Data isolation can be achieved in a single workspace through
the use of groups and object-level permissions. Multiple workspaces increase management overhead
and impede the sharing of data between users and groups belonging to different workspaces. Even if
data sharing is not a short-term requirement, it may become an issue in the long term.
2.1. Distributed Servers and Caching

A company may have multiple EKM servers to improve the transfer of data across remote offices or to
provide regional workspaces. For simplicity you may designate one of these servers as master, but
there is no difference in functionality or installed components between a master and a regional server.
Each EKM server can have its own set of workspaces and can cache data belonging to multiple remote
servers. Sometimes you may want to use an EKM server only for caching. In this case, the server will
not contain any workspaces of its own, so users cannot log in directly to such a server. For example, in
Figure 2.1: Cache Architecture (p. 4), an EKM user working on a LAN in London accesses EKM servers
in New York and Tokyo. To improve file transfer performance, they use an EKM server on the LAN in
London to handle all file transfers to/from New York and Tokyo. So, the EKM server in London contains
cached data from two different locations, New York and Tokyo, but has no workspaces of its own.
Figure 2.1: Cache Architecture
Distributed Servers and Caching

You can also have a hybrid model in which an EKM server not only caches data belonging to remote
servers but also has its own workspaces. In the previous example, the EKM server in London could have
a workspace that is set up for users in the London office to share data locally.
2.1.1. Cache Architecture

In a simple caching configuration, there are two EKM servers: one that has data in its repository that
users access, and another EKM server that caches the file content to improve performance for file
downloads. We refer to these two servers as the EKM Master Server and EKM Cache Server, respectively.
As explained previously, there is no difference between a cache and a master server in that a cache
server can also act as a master for workspaces contained within it.
The EKM Cache Server stores all the files it caches in a hidden workspace. Whenever you request a file
to be downloaded from the remote EKM Master Server, that request is handled by the EKM Cache
Server. The EKM Cache Server will first ensure that it has the latest copy of the file from the remote
EKM server; if it does not, the file is first downloaded from the remote server to get the cache up-todate and is then sent back to you. The performance improvements occur when the cache server determines it has an up-to-date file and does not have to download the file from the remote server.
Similarly, when you upload a file in this configuration, the file is first uploaded to the EKM Cache Server.
The EKM Cache Server then uploads the file to the remote EKM Master Server. Once the file has been
successfully uploaded and imported into the repository of the EKM Master Server, the EKM Cache
Server then adds the file to its cache repository.
While there is technically no improvement in actual overall file transfer time for uploads, because the
upload of the file is only over the LAN to the EKM Cache Server, there is a perceived performance gain.
Once the file is uploaded to the EKM Cache Server, you do not have to wait for the EKM Cache Server
to upload the file to the EKM Master Server and you may perform other actions. This essentially enables
the set up of a queue pending uploads (to the EKM Master Server) that the EKM Cache Server will handle
later. You can even log out once the files have been transferred to the EKM Cache Server.
2.1.2. Cache Configuration

You must create a server definition in the EKM Master Server that represents the EKM Cache Server that
will cache the data. Refer to Adding EKM Servers (p. 102).
When creating the Cache Server definition, you will specify which EKM users will use it. You may also
assign a cache server to a user when setting up or modifying their user account. Refer to Adding a New
User (p. 8).
Chapter 3: Setting Up Users and Groups

Any person who wants to access EKM must have a separate user account. This account, and the groups
that the user belongs to, determine the permissions that are available to the user, and the actions that
the user can perform in EKM. This chapter describes the definition and management of users and groups
in EKM. Topics include:
3.1. Introduction to Users and Groups
3.2. Adding and Modifying Users
3.3. Forcing the Logout of a User
3.4. Adding and Modifying Groups
3.1. Introduction to Users and Groups

The following predefined users are defined in all EKM workspaces and cannot be deleted by any user.
root: The system administrator for the workspace.
ekm_lifecycle_user: The user account that is used to lock an object associated with a lifecycle
while it is under review. This is done so that no other user can modify the object while it is under
review.
ekm_cache_user: The user account that is used by a cache service to find objects that have been
deleted or modified, and to purge obsolete items from the cache.
ekm_datalink_user: The user account used to transfer files to/from PDM systems.
The following predefined groups are defined in all workspaces and cannot be deleted by any user.
all: The default group that all users in EKM belong to, regardless of whether or not they have been
explicitly assigned to it. Users in this group do not have administrative privileges unless they are also
part of the admin group.
admin: The group that the root user and other system administrators belong to. Users in this group
have all permissions available and can perform almost any action within EKM.
Users and groups are defined in the /System/User Accounts folder in EKM.
Setting Up Users and Groups

Figure 3.1: User Accounts Folder
3.2. Adding and Modifying Users

You can add and modify users from the /System/User Accounts/Users folder. New users that
are created are typed as User objects in EKM.
Refer to the following topics:
Adding a New User (p. 8)
Editing a Users Profile (p. 11)
3.2.1. Adding a New User

Any user with admin privileges can create new user accounts.
To add a new user:
1.
In the navigation pane, go to the /System/User Accounts/Users folder, then right-click and
select New > User from the context menu. The New User dialog box opens.
Adding and Modifying Users

Figure 3.2: New User Dialog Box
2.
Enter a user name. This is the user name that the user will be required to enter when they log into EKM.
3.
Optionally specify other details such as First name, Last name, Title, and Phone.
4.
Specify the users email address. This address is used by EKM to send any alerts or notifications to the
user.
5.
If the user belongs to a remote office and a remote EKM server has been configured as a cache server
for that office, then select that server in the Cache server drop-down list. If a cache server does not
need to be assigned for this user, then keep the default value (No Cache Server) for this field.
6.
If the user will only be running applications and executing workflows, you can tailor the EKM interface
for this purpose by setting the Usage Mode to Application Execution. This removes unnecessary
components from the interface, creating a simple, streamlined environment that is specific to application
execution. For details see Running EKM in Application Execution Mode in the EKM Users Guide.

Figure 3.3: EKM Interface in Application Execution Mode
If the Usage Mode is set to Default, the user will see the full EKM interface and have access to all
features.
7.
Select Enabled to enable the user for login. If you do not select this, the user will not be able to log in
to EKM.
8.
If the user needs to be granted access for a limited time only, select Temporary and enter the Expiration
date when prompted.
9.
The default password for a user is <username>123. For example, if the user name is john, the default
password is john123. To provide a different password, select Change password. The dialog box will
expand to show more options. Enter the new password twice.
10. To assign the user to available groups, select the groups in the Available groups column and click the
Add> button to add it to the Selected groups list. To remove the user from a group, select the group
in the Selected groups column and click the < Remove button.
11. Once you have specified all the settings, you can click Create & Close to create the user and close the
dialog. If you want to create more users, then click Create & New. This will create the current user and
reopen the dialog so that you can create another user. All new users will be added to the /System/User Accounts/Users folder.
12. Once you create a new user, you can edit their profile at any point in the future to make changes to it.
See Editing a Users Profile (p. 11) for more details.
10
Adding and Modifying Groups
3.2.2. Editing a Users Profile

If you are an admin user, you can edit a users password, group membership, usage mode, and other
personal information. The easiest way to do this is to double-click the user in the /System/User
Accounts/Users folder. Or, you can select Edit > Profile from the toolbar or context menu. The Edit
User dialog that opens is essentially the same as the New User dialog with the following differences:
The user name field is not editable. To change the name of an existing user, right-click on the user in the
/System/User Accounts/Users folder and select Edit > Rename from the context menu.
Because you are editing a user instead of creating one, the Edit User dialog contains the OK button instead
of Create & Close and Create & New buttons.
See Adding a New User (p. 8) for details on how to fill out the New User dialog.
3.3. Forcing the Logout of a User

A system administrator can force the logout of concurrent users who are logged on to the EKM server.
When viewing the list of users in the /System/User Accounts/Users folder, users who are currently
logged into EKM have a green icon
next to their name.
To log off a user who is currently logged in, select the user and then click
on the toolbar.
The user will immediately be logged out of EKM, and the icon next to their name will change to white
.
3.4. Adding and Modifying Groups

You can create and modify groups from the /System/User Accounts/Groups folder. New groups
that are created are typed as Group objects in EKM.
Refer to the following topics:
Adding a New Group (p. 11)
Editing Group Membership (p. 12)
3.4.1. Adding a New Group

To add a new group:
1.
In the navigation pane, go to the /System/User Accounts/Groups folder, and then right-click
and select New > Group from the context menu. The New Group dialog box appears, as shown below.
11

Figure 3.4: New Group Dialog Box
2.
Enter a name for the new group.
3.
If you want other groups to be part of this group, select the desired groups in the Available groups
list and click the Add> button to add them to the Selected groups list. To remove a group, select the
group in the Selected groups list and click the < Remove button. All permissions that are available
for the current group will be applied to all users who are members of the selected groups.
4.
To assign users to the group, select the desired users in the Available users list and click the Add >
button. To remove a user, select the user in the Selected users list and click the < Remove button. All
permissions that are available to the current group will be applied to all selected users.
5.
Once you have specified all the settings you can click Create & Close to create the group and close
the dialog box. If you want to create more groups, click Create & New. This will create the current
group and reopen the dialog box again so that you can create a new group. All new groups will be
added to the /System/User Accounts/Groups folder.
3.4.2. Editing Group Membership

Once a group has been defined, you can modify it by double-clicking on it in the /System/User
Accounts/Groups folder. The Edit Group Membership dialog box that opens is essentially the same
as the New Group dialog box with the following differences:
12
Adding and Modifying Groups

1. The group name field is not editable. To change the name of an existing group, right click on the
group in the Groups folder and select Edit > Rename from the context menu.
2. Because you are editing a group instead of creating one, the Edit Group Membership dialog box
contains the OK button instead of Create & Close and Create & New buttons.
See Adding a New Group (p. 11) for details on how to fill out the New Group dialog.
13
14
Chapter 4: Creating and Managing Workspaces From the

Administration Interface
This chapter presents information on how a superuser can utilize the EKM Server Administration
interface to perform workspace management tasks in EKM.
Topics include:
4.1. Logging In and Out of the EKM Server Administration
4.2. Changing the Superuser Password
4.3. Resetting a Lost Superuser Password
4.4. Cleaning Up Unused Files
4.5. Creating a New, Empty Workspace
4.6. Creating a New Workspace from an Exported Workspace
4.7. Renaming Workspaces
4.8. Deleting Workspaces
4.9. Migrating Workspaces
4.1. Logging In and Out of the EKM Server Administration

EKM has a special Administration interface for managing workspaces that the superuser can log into
from the EKM login screen.
To log into the Administration interface:
1.
On the EKM login screen, check the Log into EKM Server Administration box. The user name superuser will be automatically pre-filled.
2.
Enter the password. The default password is superuser123.
3.
Click Log In. The EKM Server Administration window opens.
15
Creating and Managing Workspaces From the Administration Interface

Figure 4.1: EKM Server Administration Window
4.
The EKM Server Administration window contains a list of Workspaces, and these commands:
Add Workspace lets you add a new empty workspace or an exported workspace.
Migrate Workspace lets you migrate a workspace that is in configuration mode.
Download Migration Log lets you download a log file detailing the last executed migration.
5.
To change the password to the EKM Server Administration site, click the Change Password command
link. See Changing the Superuser Password (p. 17) for details.
6.
To clean the EKM data directory, click Clean Up Unused Files.... See Cleaning Up Unused Files (p. 18)
for details.
7.
When server administration is complete, click the Log Out link at the bottom of the window to log out
of the site and return to the EKM login window.
Once you are logged out, you can also reset a lost password, rename a workspace and delete a workspace.
16
Resetting a Lost Superuser Password
4.2. Changing the Superuser Password

You can change the superuser password from the EKM Server Administration window.
To change the superuser password:
1.
Log into the EKM Server Administration. See Logging In and Out of the EKM Server Administration (p. 15) for details.
2.
Click the Change Password link at the bottom of the EKM Server Administration window.
3.
In the Change Superuser Password dialog, enter a new password in the New Password field.
Figure 4.2: Change Superuser Password Dialog Box
4.
Enter the same password in the Confirm Password field.
5.
Click OK.
4.3. Resetting a Lost Superuser Password

If your superuser password has been lost or forgotten, you can reset it by following the steps below.
1.
Open the ekm.xml file in a text editor.
2.
Replace the text in the superUser element with the following text:
<superUser>
<name>superuser</name>
<password>9a85a0cc0a56febcf46690a6ab1a5803</password>
</superUser>
3.
Restart EKM.
The superuser password is stored as an md5 key in this file. Therefore, you can create a new key using
any md5 generation tool, and store the new password there.
17
4.4. Cleaning Up Unused Files

The EKM Data Directory stores all the files that are uploaded to EKM. When files are deleted from EKM,
they are not immediately removed from disk, but instead are marked for garbage collection. Garbage
collection is a process that you can run to remove these files from disk.
Important
In order to control the size of the EKM Data Directory, you should periodically run the garbage
collection process to delete files that are no longer needed. This is referred to as "cleaning"
the EKM data directory. Note that the dataStoreGc scheduled task (see Scheduling Automatic
Tasks (<scheduledTasks>)) performs this same operation. If dataStoreGc is running on a
regular schedule, you may not need to run the cleanup from this interface.
To clean the EKM data directory:
1.
Log into the EKM Server Administration interface. See Logging In and Out of the EKM Server Administration (p. 15) for details.
2.
Click the Clean Up Unused Files... button in the EKM Server Administration window. The Clean Up
Unused Files dialog box appears.
This dialog has two display modes. What is displayed depends on whether or not garbage collection
is already in progress.
If garbage collection is not currently running, the dialog displays information about the last time
you cleaned the EKM data directory. It shows the time that the garbage collection started, when
it finished, and the number of unreferenced files it deleted.
Figure 4.3: Clean Up Unused Files Dialog Box
3.
18
To start garbage collection, click Start Cleanup. This starts a garbage collection task on the EKM Server
and closes the dialog box. The task runs in the background so that you can continue to work in EKM
or log out. To monitor the progress of the garbage collection, click the Clean Up Unused Files... button
at the bottom of the EKM Server Administration window. This opens the dialog box again. If garbage
collection is still running, a snapshot of its current status is displayed in the Garbage Collection dialog
box, as shown below.
Creating a New, Empty Workspace

Figure 4.4: Garbage Collection in Progress
You will see two possible status messages depending on what stage the garbage collection is in:
Scanning files. n nodes completed.
Deleting unreferenced files.
In the first stage, the garbage collection scans through all the nodes in the database. The Garbage
Collection dialog reports the number of nodes that have been scanned so far. After the scanning
stage is complete, it begins a final stage where it deletes all unreferenced files from the EKM data
directory.
Note
To ensure consistency during restore, and to prevent accidental deletion of files that have
not yet been committed, an unreferenced file may not be deleted if it was added or accessed
recently. See the description of the dataStoreGC setting in Scheduling Automatic Tasks
(<scheduledTasks>) (p. 53) for more details.
4.5. Creating a New, Empty Workspace

Workspaces are primarily used as independent data partitions that can be configured independently
of each other and that contain their own set of users and groups. Each server will have at least one
production workspace that contains the primary data and user accounts, but you may want to create
additional workspaces. For an overview of workspaces, see How Workspaces are Used (p. 3).
To create a new workspace:
1.
Log into the EKM Server Administration. See Logging In and Out of the EKM Server Administration (p. 15) for details.
2.
Click Add Workspace.... The New Workspace dialog box appears.
19

Figure 4.5: New Workspace Dialog Box
3.
In the Name field, enter a name for the workspace.
4.
Do not check the Import an exported workspace? box.
5.
Click OK. A Progress dialog box opens to report the status.
Once the workspace has been created, the Add Workspace Completed dialog box appears:
6.
Click Close. The new workspace will appear in the Workspaces list in the EKM Server Administration
window, and in all other workspace drop-down lists in EKM.
Important
If the WorkspaceConfig.xml file has not been configured in accordance with the schema
definition, the new workspace will fail to initialize, and the error will be reported in the following dialog:
20
Creating a New Workspace from an Exported Workspace
It is important to note that even though the workspace has failed to initialize, it has still been
created on the server. The presence of a faulty workspace will prevent the EKM server from
starting properly. You will need to manually remove the faulty workspace from the server.
See Deleting Workspaces (p. 23) for details.
4.6. Creating a New Workspace from an Exported Workspace

In addition to creating a new, empty workspace, a superuser can also create a new workspace from
a workspace that has been exported from an EKM server. This feature is useful, for example, when you
want to upgrade from an Evaluation to a Production server and you want to migrate an entire workspace
to the new server. The exported workspace that you create is different from an empty workspace in
that it is an exact copy of the workspace including users/groups, configuration, data, controls, and so
on. See Creating a New, Empty Workspace (p. 19) to create a new empty workspace.
In the steps that follow, the EKM server from which the workspace is being exported is referred to as
the source EKM server, and the EKM server where the workspace is being created is referred to as the
destination EKM Server.
Note
The source and destination EKM servers must be running the same version of EKM (for example, EKM 15.0).
1.
Export the workspace from the source EKM server using the Export Workspace tool. For details see
Exporting a Workspace (p. 191).
2.
Log in to the Administration interface of the destination EKM server as superuser (see Logging In
and Out of the EKM Server Administration (p. 15)).
3.
In the EKM Server Administration window, click Add Workspace... to create a new workspace. This
opens the New Workspace dialog box.
21
a.
Type a name for the workspace.
b.
Check the Import an exported workspace? box.
c.
Type the path to the folder on the destination EKM server that contains the exported workspace.
d.
Click OK.
A Progress dialog box reports the progress of the import:
When the operation is complete, the Add Workspace Completed dialog box appears.
4.
Click Close. The new workspace is added to the Workspaces list in the EKM Server Administration
window and in all other workspace drop-down lists in EKM.
5.
After creating the new workspace from the exported workspace:

a.
22
Go to each application definition in the new workspace and update the application's path to point
to correct application executable.
Deleting Workspaces
b.
Update the default remote file servers (Audit Logs, EKM Base Directory) to valid paths for the target
EKM server.
4.7. Renaming Workspaces

A member of the admin group can rename a workspace by following the steps below.
Important
The EKM server must be shut down before you can rename a workspace and then restarted
afterwards for the change to take effect.
1.
Shut down the EKM server. Refer to the chapter on Starting and Connecting to EKM in the Installation
Guide for details.
2.
Navigate to the <ekm-install>/<repository>/workspaces folder and then rename the

workspace folder.
Example:
If the current workspace is named Analysts1 and you want to change it to Analysts2, then
rename <ekm-install>/<repository>/workspaces/Analysts1 to <ekm-install>/<repository>/workspaces/Analysts2.
3.
Open the workspace.xml file in the workspace folder you just renamed and make the following
changes:
a. Change the name of the workspace in the Workspace root element to the new workspace name.
Example:
<Workspace name="Analysts2">
b. In the PersistenceManager element, for the param setting named schemaObjectPrefix,
change the value of ${wsp.name}_ to the OLD workspace name.
Example:
<PersistenceManager class="org.apache.jackrabbit.core.persistence.bundle.BundleDbPersistenceManager">
<param name="schemaObjectPrefix" value="Analysts1_"/>
4.
Restart the EKM server. Refer to the chapter on Starting the EKM Server and Launching the Web Client
in the Installation Guide for details.
4.8. Deleting Workspaces

You cannot delete a workspace interactively using the EKM Server Administration interface. In order
to delete a workspace, you will need to shut down the EKM server and manually delete the files and
database tables corresponding to the workspace. Follow the instructions below for the different server
types.
23

Deleting Workspaces from Evaluation Servers (p. 24)
Deleting Workspaces for Production Servers (p. 26)
4.8.1. Deleting Workspaces from Evaluation Servers

EKM Evaluation servers use an embedded Derby database server to host the EKM database. The database
server is loaded within the EKM server application the application server and database server all run
within the same process. On Production servers, the EKM database is hosted in a database server that
runs in its own process, separate from the EKM server application. The database server for a Production
server can be either the default MySQL database server, or an external database server.
In order to delete a workspace from an Evaluation server, additional tools are required that are not part
of the EKM server set up. These tools can be downloaded for free from the web site of the Apache
Derby (Derby) database project:
http://db.apache.org/derby/
The tool that is required is ij, an interactive JDBC scripting tool provided with the bin distribution
of Derby. The instructions that follow were performed with the 10.8.1.2 version of Derby newer versions
should also work. These instructions show how to delete an EKM workspace named MYEKM.
1.
Download and uncompress the bin distribution of Derby. Derby distributions are platform-neutral,
and contain executable tools for both Windows and Linux systems. The Derby distribution used in this
example is: db-derby-10.8.1.2-bin.zip.
The suggested location for the uncompressed Derby distribution is EKM_BASE/programs/<derby>, where <derby> is the name of the uncompressed Derby distribution, such as:
db-derby-10.8.1.2-bin.
We will refer to this location as DERBY_HOME.
2.
Stop the EKM Evaluation server using the script:

EKM_BASE/bin/ekm_stop.(cmd|sh)
3.
Start the ij tool from the Derby distribution from the command-line:
DERBY_HOME/bin/ij
4.
In the ij tool, perform the following commands to delete the EKM workspace from the database. This
example demonstrates deleting the EKM workspace named MYEKM.
The EKM database is located in the following location: <ekm-install>/<repository>/db/ekm.
a. Connect to the ekm database by issuing the following command within ij (shown in bold):
ij> connect 'jdbc:derby:C:\ekm150\ekm-server\repository\db\ekm';
b. Show the database tables associated with the EKM server (tables with schema name ekm) by
issuing the following command within ij (shown in bold):
ij> show tables in ekm;
TABLE_SCHEM
|TABLE_NAME
|REMARKS
-----------------------------------------------------------------------EKM
|CACHESTORE_BINVAL
|
24
Deleting Workspaces
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
EKM
|CACHESTORE_BUNDLE
|CACHESTORE_NAMES
|CACHESTORE_REFS
|DEFAULT_BINVAL
|DEFAULT_BUNDLE
|DEFAULT_NAMES
|DEFAULT_REFS
|MYEKM_BINVAL
|MYEKM_BUNDLE
|MYEKM_NAMES
|MYEKM_REFS
|ROOT_BINVAL
|ROOT_BUNDLE
|ROOT_NAMES
|ROOT_REFS
|VERSION_BINVAL
|VERSION_BUNDLE
|VERSION_NAMES
|VERSION_REFS
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
20 rows selected
c. Drop the database tables associated with the EKM workspace named MYEKM by issuing the
following commands within ij (shown in bold):
ij> drop table EKM.MYEKM_BINVAL;
0 rows inserted/updated/deleted
ij> drop table EKM.MYEKM_BUNDLE;
ij> drop table EKM.MYEKM_NAMES;
ij> drop table EKM.MYEKM_REFS;
d. Issue the following command within ij (shown in bold) to show that the tables of the MYEKM
workspace have been dropped:
ij> show tables in ekm;
TABLE_SCHEM
|TABLE_NAME
|REMARKS
-----------------------------------------------------------------------EKM
|CACHESTORE_BINVAL
|
EKM
|CACHESTORE_BUNDLE
|
EKM
|CACHESTORE_NAMES
|
EKM
|CACHESTORE_REFS
|
EKM
|DEFAULT_BINVAL
|
EKM
|DEFAULT_BUNDLE
|
EKM
|DEFAULT_NAMES
|
EKM
|DEFAULT_REFS
|
EKM
|ROOT_BINVAL
|
EKM
|ROOT_BUNDLE
|
EKM
|ROOT_NAMES
|
EKM
|ROOT_REFS
|
EKM
|VERSION_BINVAL
|
EKM
|VERSION_BUNDLE
|
EKM
|VERSION_NAMES
|
EKM
|VERSION_REFS
|
16 rows selected
e. Exit the ij tool by issuing the exit command within ij (shown in bold):
ij> exit;
5.
Delete the folder associated with the MYEKM workspace:
25

<ekm-install>/<repository>/workspaces/MYEKM
6.
Start the EKM Evaluation server using the script:

EKM_BASE/bin/ekm_start.(cmd|sh)
4.8.2. Deleting Workspaces for Production Servers

The instructions supplied below demonstrate the deletion of a workspace for a Production EKM server
that utilizes a MySQL database server. If you use a different database, the database commands for
viewing and deleting tables will be different.
1.
Stop the application server in which EKM is running. If EKM is installed in a clustered installation, stop
the application server on each cluster node.
2.
Delete the workspace from the database. To do this you will need to remove all the tables corresponding
to the workspace from the EKM database. Assuming the name of database is ekm150 and the name
of the workspace that you want to remove is Temp, then the following sequence of commands show
how to remove the tables from a MySQL database.
Open the MySQL client console:
a. Switch to the EKM database by issuing the command:
use ekm150;
This assumes that the name of the EKM database that you provided at installation time is
ekm150.
b. List all the tables within this database by issuing the command:
show tables;
c. Delete all the tables whose prefix is temp. This assumes that the name of the workspace that
you want to delete is called Temp.
The following series of commands will delete the tables for the Temp workspace:
drop table temp_binval;drop table temp_bundle;drop table temp_names;drop
table temp_refs;
3.
Delete the workspace from the disk. Navigate to the <ekm-install>/<repository>/workspaces

folder and remove the folder corresponding to the workspace. For example, deleting the folder named
Temp will delete the Temp workspace. If EKM is installed in a clustered installation, perform this step
on each cluster node. The file contents for all files stored in the removed workspace will automatically
be deleted from the EKM data directory.
4.
When you restart the application server, the workspace will no longer be listed in any drop-down list
in EKM.
26
Migrating Workspaces
4.9. Migrating Workspaces

A superuser can dynamically migrate any workspace that is in restricted configuration mode using
the EKM Server Administration interface. Workspaces that are in configuration mode will be marked
with an asterisk (*) in the Workspaces list in the EKM Server Administration window.
Refer to Restricted Configuration (p. 31) for details on how to start a restricted configuration mode and
where it is used. Note that only a root user can perform restricted configuration actions.
Important
Data migration is a potentially risky step that may cause data loss or corruption if it
cannot be successfully completed for any reason. Therefore it is highly recommended
that you take a complete backup of your EKM data before migrating a workspace that
is in production use.
To migrate a workspace that is restricted configuration mode:
27

1.
Log into the EKM Administration Interface as superuser (see Logging In and Out of the EKM Server
Administration (p. 15)). Select a workspace that is in configuration mode and click Migrate Workspace.... This opens the Migrate Workspace dialog box.
Figure 4.6: Migrate Workspace Dialog Box
If the data model has changed as a result of your configuration and data loss may result for the
workspace, the dialog box indicates which changes are affected under Type Changes Involving
Removal of Metadata or Child Objects. If you click Cancel, no migration will take place. If you
click Apply, migration will take place but the workspace will remain in configuration mode. If you
click Apply & Accept, the workspace will exit from configuration mode after migration, and other
users will be able to log into it. When you accept changes, you can optionally add a comment that
will be used as the check-in comment for the new version of the /System/Configuration
folder.
2.
28
When you click Apply or Apply & Accept in the Migrate Workspace dialog box, migration begins and
a Progress dialog box opens and report on the status of the migration (Figure 4.7: Progress Dialog Box
During Migration (p. 29)). Depending on the amount of objects in the repository, migration can take
from several minutes to a few hours to complete. You can also view a log of the migration as it progresses
by clicking the Show Log button or download it using Download Migration Log.
Migrating Workspaces
Figure 4.7: Progress Dialog Box During Migration
Once it finishes, the Migration Completed dialog box indicates successful completion, as shown
below. You can view the log after download by selecting this option in the EKM Server Administration. The log will be overwritten each time you migrate a workspace configuration.
Figure 4.8: Migration Completed Dialog
29
30
Chapter 5: Restricted and Unrestricted Configuration of Workspaces

EKM provides many options for configuring a workspace on an EKM server that allows you to better
meet your business requirements and easily integrate with your IT infrastructure. Recall that an EKM
server can be partitioned into different workspaces that each has its own users, groups, custom types,
scripts, object lifecycles, external applications, and so on. Workspace configuration is specific to a single
workspace, which means that different workspaces in the same server can have their own configurations
and that configuration changes made in one workspace do not impact any other workspace. Furthermore,
these changes can be made dynamically without requiring the server to be shutdown or restarted. This
is in contrast to EKM server configuration, described in Configuring EKM Server Settings (p. 45), that
applies to all workspaces in an EKM server, and requires a server restart for changes to take effect.
There are two types of workspace configuration that can be performed in EKM:
Restricted configuration: This type of configuration requires the workspace to be locked down. It can
only be done by the root user and no other user can log in to the workspace while the configuration
is being performed.
Unrestricted configuration: This type of configuration can be done at any time by anyone belonging
to the admin group. It does not require that the workspace be locked down and does not impact
users of the workspace.
5.1. Restricted Configuration

Restricted configuration of a workspace can only be done when the workspace is locked down. It can
be performed only by the root user, and no other user can log in to the workspace while the configuration is being performed.
Restricted configuration applies only to objects in the /System/Configuration folder. These are
shown below.
The /System/Configuration folder is under version control. When you begin restricted configuration, the folder is checked out, allowing you to make the necessary modifications. When you exit the
configuration mode, the folder is checked in with a new version number. Thus, all changes made in
31
Restricted and Unrestricted Configuration of Workspaces

restricted mode are kept in the version history and you can go back to a previous version of the configuration if desired.
The following sections describe how you can start and end the restricted configuration mode.
Steps for Making Restricted Configuration Changes in EKM:

1. Start restricted configuration if it has not already been started.
2. Perform custom type, lifecycle, script, unit, and/or workspace setting configuration changes according
to the instructions referenced below:
Custom Types: See Defining Custom Types (p. 63)
Lifecycles: See Configuring Lifecycles for a Workspace (p. 155)
Scripts: See Configuring a Common Scripts Library (p. 193)
Units: See Units: Defining and Configuring Using XML (p. 187)
Workspace Settings: See Configuring Workspace Settings (p. 37)
3. Apply configuration changes.
4. Accept configuration changes.
5.1.1. Starting Restricted Configuration

Log in as the root user to the workspace that you want to configure. As previously described, you
must login as root to initiate a restricted configuration. While the workspace is under restricted configuration, no other user will be allowed to log in to the workspace.
Note
When you begin configuration, all other users will be logged out of the workspace, so you
may want to check the /System/Users folder to see which users are logged in before
you begin. Logged-in users will be identified with green user icons
. As a best practice,
it is recommended that you give advanced notice to all users of a workspace when configuration will start and when it will end.
To begin restricted configuration:
1.
32
Select File > Workspace Configuration > Begin Workspace Configuration. You are asked to confirm
that you want to start the configuration mode.
Restricted Configuration
Figure 5.1: Begin Workspace Configuration Dialog Box
2.
Click OK to start the configuration. This makes the /System/Configuration folder editable, and
logs other users out of the workspace.
You can now make custom type, lifecycle, and script configuration changes to your workspace. When
you are done, choose one of following three options on the Workspace Configuration menu:
Apply Workspace Configuration
Revert Workspace Configuration
Accept Workspace Configuration
5.1.2. Applying the Configuration

Once you have modified the configuration, you can test it while remaining in restricted configuration
mode by applying the changes. The changes will apply only to new objects created or uploaded.
To apply a configuration:
1.
Select File > Workspace Configuration > Apply Workspace Configuration.

The Apply Workspace Configuration dialog box informs you that you may be required to migrate
the workspace before you can accept it, if the data model has changed as a result of your changes.
Figure 5.2: Apply Workspace Configuration Dialog Box
33

2.
Click Apply to apply the changes.
5.1.3. Reverting to a Previous Configuration

If you decide to abandon your configuration changes, you can revert to the last accepted configuration.
To revert to a previous configuration:
1.
Select File > Workspace Configuration > Revert Workspace Configuration. You will be asked to
confirm that you want to revert the configuration.
Figure 5.3: Revert Workspace Configuration Dialog Box
2.
If you want to cancel the workspace configuration session after the workspace has been reverted, check
the Cancel the Workspace Configuration Session box. If this is done, the /System/Configuration
folder will become non-editable and other users will be allowed to log in to the workspace again.
3.
Click OK to revert.
5.1.4. Accepting the Configuration

When you are done configuring the workspace and you want to apply the changes and exit restricted
configuration mode, you can accept the configuration.
To accept the configuration:
1.
34
Select File > Workspace Configuration > Accept Workspace Configuration. This opens the Accept
Workspace Configuration dialog box.
Restricted Configuration
Figure 5.4: Accept Workspace Configuration
2.
If your changes have not affected the data model, then click Accept to accept the configuration. You
can optionally add a comment. The comment will be stored with the new version of the /System/Configuration folder.
3.
If your changes have affected the data model, you will be asked to log out of EKM and migrate the
workspace using the EKM Administration site, as shown in the figure below.
Figure 5.5: Accept Workspace Configuration - Migration Required
If this happens:
1. Click Cancel to close the Accept Workspace Configuration dialog box.
2. Log out of the workspace.
35

3. Log into the EKM Administration site from the EKM login screen.
4. Migrate the workspace. See Creating and Managing Workspaces From the Administration Interface (p. 15) for details.
5.2. Unrestricted Configuration

Unrestricted configuration of a workspace can be performed at any time by anyone belonging to the
admin group. It does not require that the workspace be locked down and does not impact users of
the workspace. All changes in unrestricted configuration mode are made to objects in the /System
folder.
Objects that can be configured in unrestricted configuration mode include the following:
EKM Servers. Every EKM server contains one built-in job submission server named Master. You can
also add cache servers to enable data caching. See Adding EKM Servers (p. 102).
External Applications. These are definitions for external applications that can be launched by EKM.
External applications are defined within job submission queues. See Defining External Applications (p. 110).
Remote File Servers. These definitions enable users to connect to remote files and folders on any
server type. See Defining a New Remote File Server (p. 194).
Shared Applications. This public folder contains the following pre-defined applications:
Create Custom Application
Create Job Template
Create Workflow Definition
36
Configuring Workspace Settings

Start Batch Job
Start Remote Desktop
You can edit these applications to suit your needs. See Modifying an EKM Application in the EKM
Users Guide.
You can also create custom applications, job templates or workflow definitions and save them
in the Shared Applications folder to make them accessible to other users.
Refer to the following topics in the EKM Users Guide for details:
Creating a Custom Application
Creating a Job Template
Adding Custom Dialog Resource Files to a Workflow Definition
Shared Queries. This is a public folder where users can save the following:
Search queries (see Saving a Search Query in the EKM Users Guide)
Catalog views (see Saving a View in the EKM Users Guide)
Queries and catalog views can be subsequently executed or edited as needed.
Users. Every user who will be accessing EKM must have a separate user account. See Adding and
Modifying Users (p. 8).
Groups. Users can belong to specific groups that determine the types of actions users can perform.
See Adding and Modifying Groups (p. 11).
5.3. Configuring Workspace Settings

Apart from the server settings described in this chapter, an EKM server also has some workspace-specific
settings that can be configured. These settings are specific to a particular workspace and do not require
a server shutdown and restart for changes to be applied. However, the workspace must be in restricted
configuration mode in order for you to be able to change these settings. The general steps for configuring workspace settings are presented below.
Steps for Changing WorkspaceConfig.xml Settings in EKM:

1. If restricted workspace configuration mode has not already been started, start it now. See Starting Restricted Configuration (p. 32).
2. Either download the existing WorkspaceConfig.xml file from the /System/Configuration folder
to your local file system and open it in an XML editor, or edit the XML file directly in EKM by selecting
Edit > Content.
3. Make configuration changes as described in Configuration Settings in WorkspaceConfig.xml (p. 38) and
in accordance with the schema definition presented in Schema Definition (p. 38).
4. If you downloaded the file to your local system and edited it, then upload the modified file to the
/System/Configuration folder and overwrite it.
37

5. Apply and accept the configuration changes.
5.3.1. Schema Definition

The XML schema definition file workspace-config.xsd in the EKM_Home/schema folder defines
workspace settings in EKM.
When you examine WorkspaceConfig.xml you will see that it consists of one root element named
workspace that contains child elements for various settings. Each setting is discussed below in Configuration Settings in WorkspaceConfig.xml (p. 38).
5.3.2. Configuration Settings in WorkspaceConfig.xml

The following settings can be specified in the WorkspaceConfig.xml file. All of these settings are
optional.
defaultExtensions
mimeTable
typeSettings
dashboard
preferences
downloadConfirmation
scheduledTasks
Important
When specifying values for attributes in the WorkspaceConfig.xml file, avoid using
characters that are used as identifiers in XML code, such as &, < and >. Otherwise,
an error will be reported when you apply the workspace configuration.
For example, specifying the following value for the downloadConfirmation setting would
cause an error because the & character is used.
<downloadConfirmation>The files & folders on this system may be restricted.
Please review restrictions on a file before distributing externally.</downloadConfirmation>
In this case, the following error would be reported when you apply the workspace configuration:
38
defaultExtensions Setting
The defaultExtensions setting can be used to specify the data type that will be taken as the default
for a particular extension. This is used in cases where the same extension is shared by multiple types.
A sample listing is shown below.
Example 5.1: defaultExtensions Setting
<defaultExtensions>
<extension>
<name>dat</name>
<type>PolyflowData</type>
</extension>
</defaultExtensions>
In many cases, EKM can automatically infer the correct type if a file extension is used by multiple file
types. Every user can also choose to specify the default type for a particular file extension in their
preferences. This setting is used in cases where users have not specified a preference for an extension,
and EKM cannot infer the type.
mimeTable Setting
The mimeTable setting can be used to specify the MIME type for a file extension. The MIME type for
a built-in or custom type can also be specified in the typeSettings setting by using the content
Type type attribute. The mimeTable setting is used to set the MIME type of those files that are represented as generic File types in EKM. The default MIME type of a file in EKM is application/octetstream, which is used to represent binary files.
A sample listing for the mimeTable setting is shown below. In this example all files with an out extension will have a MIME type of text/plain.
Example 5.2: mimeTable Setting
<mimeTable>
<mimeEntry>
<extension>out</extension>
<contentType>text/plain</contentType>
</mimeEntry>
</mimeTable>
39
typeSettings Setting
The typeSettings setting can be used to set or modify some settings of built-in or custom types.
The following settings can be specified for any type:
hidden: Used primarily to hide built-in types from which you do not want to extract metadata or
reports. For example, by specifying WorkBenchSimulation as a hidden type, then whenever a
Workbench Simulation file type (.dsdb) is added to EKM, it will be treated as an ordinary file and
no metadata will be extracted from it.
modelObjectClass: Used to specify the full name of a class that implements the back-end behavior of a data type. This is used for customization only.
typeAttribute: Used to specify the value of some type attributes. See Defining Custom
Types (p. 63) for a description of type attributes and acceptable names.
A sample listing for typeSettings is shown below. The name of a built-in type should be the nonlocalized name as described in Appendix B (p. 207). In this example, a modelObjectClass setting is
provided for a custom type called AcmeSimulationFile. The metaDataApplication type attribute
of the FluentCase built-in data type value is set to fluentExtractionApp, which is a custom
application defined in the applications.xml file. Finally, the hidden setting of the WorkBenchSimulation type is set to true.
Example 5.3: typeSettings Setting
<typeSettings>
<type name="AcmeSimulationFile">
<modelObjectClass>com.acme.AcmeSimulationFileObject</modelObjectClass>
</type>
<type name="FluentCase">
<typeAttribute name="metaDataApplication" value="fluentExtractionApp"/>
</type>
<type name="WorkBenchSimulation">
<hidden>true</hidden>
</type>
</typeSettings>
dashboard Setting
The dashboard setting can be used to specify default gadgets for a user dashboard. This setting can
have any number of child gadget elements. Each gadget element can have the following child elements:
name: Used to specify the name of the gadget.
path: Used to specify the path of the object that will be viewed by the gadget.
essential: An optional element that can either be true or false. It specifies whether the gadget
is essential, in which case it cannot be deleted by a user (an 'X' icon will not appear for essential
gadgets). If this element is not specified, the gadget is treated as non-essential.
By default, all dashboards contain three gadgets: My Work Items, My Jobs, and My Processes. All of
these gadgets are non-essential.
Example 5.4: dashboard Setting
<dashboard>
<gadget>
40

<name>My Work Items</name>
<path>/My Home/My Work Items</path>
</gadget>
<gadget>
<name>My Jobs</name>
<path>/My Home/My Jobs</path>
</gadget>
<gadget>
<name>My Processes</name>
<path>/My Home/My Processes</path>
</gadget>
</dashboard>
preferences Setting
The preferences setting is used to establish the default selections for preferences in the Edit Preferences dialog box. Changes made to the preferences defined in the WorkspaceConfig.xml file
apply only to new users that are created. The preferences of existing users are not affected. The default
values specified in the preferences setting are also the values that will be restored when a user
(new or existing) clicks the Restore Defaults button in the Edit Preferences dialog box. The default
values for the preferences setting are shown below.
Example 5.5: preferences Setting
<preferences>
<initialUri>/My Home</initialUri>
<locale>en</locale>
<r12Labels>true</r12Labels>
<unitSystem>SI</unitSystem>
<disableDataExtraction>false</disableDataExtraction>
<font>12px Arial, Helvetica, sans-serif</font>
<typeColumnMap>
<typeColumnMapEntry>
<typeName>Model</typeName>
<columnList>type, length, modificationTime, modifiedBy</columnList>
</typeColumnMapEntry>
</typeColumnMap>
<recyclebinPolicy>cleanAfterSpecifiedTime</recyclebinPolicy>
<recyclebinCleanupInterval>30</recyclebinCleanupInterval>
<httpProxyServer/>
<httpProxyServerAuth>false</httpProxyServerAuth>
<compressArchives>true</compressArchives>
</preferences>
The sample above sets the following preferences:

intialUrl: The location in the EKM repository in which EKM will start.
locale: The language in which you want EKM to display text. Once you have logged in to EKM, text will
be displayed in the language you choose. The language for the EKM login page will depend on the language
preference of your web browser. This is because EKM preferences are available only after you have logged
in to EKM.
r12Labels: Determines whether or not EKM displays ANSYS file labels using R12 terminology. The labels
of some files have changed as of ANSYS R12. For example, .dsdb files were called Workbench Simulation
files in R11 and are called Mechanical Database files in R12. Setting the value to true displays file labels
using R12 terminology, while setting the value to false displays labels using R11 terminology.
unitSystem: The unit system in which you want EKM to display property values in drop-down lists.
Choose one of the following values:
41

SI (the default)
CGS
US
Metric
British
Units will be shown only for custom properties of type Double that have been associated with a
quantity. All the other values are shown without any units. See Defining Properties for a Custom
Type (p. 68) for details on how to define a quantity with a custom property.
disableDataExtraction: Setting this to true prevents the automatic extraction of metadata from
CAE files when such files are uploaded or imported into the EKM repository. Files will be identified in the
repository with a warning icon
next to them, and hovering over this icon will display the message
Extracted data is not set. You can subsequently extract metadata manually. By default this preference
is set to false to allow the automatic extraction of metadata.
font: The font in which text is displayed in the EKM interface. The font-size and font-family
values are required. You can also specify any of the other standard CSS font properties if desired.
typeColumnMap: Determines what columns are displayed in the file list window for an object type. The
typeColumnMapEntry element is an entry in the column map. Each entry has a typeName and
columnList attribute. The typeName attribute is the name of the object type, and the columnList
attribute determines the columns that are to appear for that type in the file list window. You can define
a typeColumnMapEntry for each object type in EKM.
The sample typeColumnMap element below contains a typeColumnMapEntry for the Model
type, which is the base type of all object types in EKM.
Example 5.6: typeColumnMap Element
<typeColumnMap>
<typeColumnMapEntry>
<typeName>Model</typeName>
<columnList>type, length, modificationTime, modifiedBy</columnList>
</typeColumnMapEntry>
</typeColumnMap>
recyclebinPolicy: Determines how and when items are permanently removed from the recycle bin.
Use one of the values described below.
cleanAfterSpecifiedTime will delete objects from the recycle bin after a specified number of
days. This is the default setting.
cleanOnExit will permanently delete all objects on exit or logout.
cleanNever will not permanently delete objects from the recycle bin unless the user initiates it.
recyclebinCleanupInterval: The number of days after which an object will be permanently removed
from the recycle bin if the recyclebinPolicy is set to cleanAfterSpecifiedTime.
42

httpProxyServer: If you use a proxy server to access a shared EKM server, this is the host name and
port (for example, www.ekmserver.com:3128) of the default proxy server that the File Transfer Client
will use to connect to EKM.
httpProxyServerAuth: The default value for this property is false. Set to true if the proxy server
requires authentication for access.
compressArchives: When this property is set to true (the default value), archive files (for example,
.wbpz files) are compressed before they are transferred to or from the EKM server. An archive file is a
collection of files and folders stored in one file. The archive file is not compressed it uses the same
amount of disk space as all of the individual files and folders combined. A compressed file is a collection
of files and folders stored in one file and stored in a way that uses less disk space than the files and folders
that it contains. The choice to compress archive files will depend largely on your location. Compression
is most beneficial if you are transferring files from a remote location across a Wide Area Network (WAN).
Even though time is needed by the system to compress and decompress the archive file, the reduced file
size compensates for this and allows files to be transferred much more quickly when connection speeds
are slower. On the other hand, if you are on the same Local Area Network (LAN) as the EKM server, it is
recommended that you disable compression. To disable compression, set the compressArchives
property to false.
The compression preference applies to archives (.wbpz files) that are created by EKM when you
upload Workbench projects to the EKM repository, and when folders are archived on the server for
download.
Note that compression will not be used on archives that are used primarily on the server (in other
words, archives that are not specifically destined for transfer). This includes archives created for jobs.
For more information about user preferences, see Setting Your Preferences in the Users Guide.
downloadConfirmation Setting
The downloadConfirmation setting can be used to specify a customizable message that will be
displayed whenever a user tries to download a file or folder from EKM. This can be used if the data
contained within EKM is confidential, and for legal reasons, you want to inform the user about restrictions
on the data before it is downloaded. An example of this setting is shown below.
Example 5.7: downloadConfirmation Setting
<downloadConfirmation>The files and folders on this system may be restricted.
Make sure to read the restriction property associated with the file before
distributing the content to people outside the company.</downloadConfirmation>
scheduledTasks Setting
The scheduledTasks setting can be used to schedule tasks that EKM will execute on a particular
day and time. The tasks correspond to scripts that have been uploaded to EKM. Scripts can be developed
in either Python or BeanShell languages with .py and .bsh extensions, respectively.
For each scheduledTask, the scriptPath setting specifies the path of the script file in the workspace. You can specify the execution time for any script by providing the day, hour, and min values.
Any value can be used for day if you want the task to be executed on all days. Alternatively, you can
specify a particular day of the week such as Saturday, Sunday, and so on. The hour values range
from 0 (12 AM) to 23 (11 PM). The min (minute) value ranges from 0 to 59. If min is unspecified, it is
taken as 0. You can specify the interval of the task by providing the dayInterval and hourInterval
values. If you set both of these values to 0, the task will never be executed.
43

Scripts are always executed on behalf of the root user. Therefore, any action executed by the script
will have all privileges given to the root user.
In the following example there are four scheduled tasks defined. script1.py is executed every Saturday
at 10PM, script2.py is executed every day at 12AM, script3.py is executed every hour and
script4.py is executed after every 10 minutes.
Example 5.8: scheduledTasks Setting
<scheduledTasks>
<scheduledTask>
<scriptPath>/Repository/scripts/script1.py</scriptPath>
<day>Saturday</day>
<hour>22</hour>
<dayInterval>7</dayInterval>
</scheduledTask>
<scheduledTask>
<day>Any</day>
<hour>0</hour>
</scheduledTask>
<scheduledTask>
<day>Any</day>
<hour>0</hour>
<hourInterval>1</hourInterval>
</scheduledTask>
<scheduledTask>
<day>Any</day>
<hour>0</hour>
<minInterval>10</minInterval>
</scheduledTask>
</scheduledTasks>
44
Chapter 6: Configuring EKM Server Settings

You can configure an EKM server by editing the ekm.xml configuration file that is included with your
server setup. The ekm.xml file contains settings that are defined according to the syntax in the ekm.xsd
schema definition file. Configuration changes apply to all workspaces, and the server must be shut
down and restarted in order for the changes to take effect.
In this chapter:
6.1. Schema Definition for an EKM Server
6.2. General Server Settings
6.3. Optional Settings
6.1. Schema Definition for an EKM Server

Figure 6.1: Partial Listing of ekm.xsd Schema File (p. 45) shows a partial listing for ekm.xsd, the XML
schema definition (XSD) used to define custom EKM server settings. The complete listing is provided
in the EKM_HOME/schema folder.
The schema definition listing shows that ekm.xml should consist of one root element named ekm that
contains child elements for various settings. These settings are discussed in General Server Settings (p. 46)
and Optional Settings (p. 59).
Figure 6.1: Partial Listing of ekm.xsd Schema File
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.ansys.com/ekm"
xmlns:ekm="http://www.ansys.com/ekm">
<xsd:complexType name="Repository">
<xsd:sequence>
<xsd:element name="name" type="xsd:string" />
<xsd:element name="context" type="xsd:string" />
<xsd:element name="providerUrl" type="xsd:string" />
<xsd:element name="location" type="xsd:string" />
<xsd:element name="configurationFile" type="xsd:string" />
<xsd:element name="retentionPolicy"
type="ekm:SystemRetentionPolicy" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="SuperUser">
<xsd:sequence>
<xsd:element name="name" type="xsd:string" />
<xsd:element name="password" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="CustomRetentionPolicy">
<xsd:sequence>
<xsd:element name="objectType" type="xsd:string" />
<xsd:element name="expiration" type="xsd:int" />
</xsd:sequence>
</xsd:complexType>
45
Configuring EKM Server Settings
6.2. General Server Settings

General server settings are mandatory settings that are used to specify global policies in EKM. You can
edit server settings by editing the ekm.xml located in the EKM_HOME/conf folder.
General server settings include:
ekmUrl
defaultDomain
repository
location
configurationFile
retentionPolicy
modules
localprocess
remoteProcess
cache
scheduledTasks
pluginRegistry
superuser
cluster
memoryLimits
email
customResourcesPath
fileTransferService
Specifying the URL of the EKM Server (<ekmUrl>)

When an EKM server is set up using the Setup wizard, the URL is automatically set for Evaluation and
Production non-cluster servers. The Setup wizard does not set ekmUrl when setting up a Production
cluster server or when using a front-end web server. If you are using a front-end web server, you will
need to set ekmUrl manually to the URL of the front-end web server.
This setting is used in certain situations. For example, when the EKM server sends an automatic email
such as those generated during a workflow process execution or lifecycle signoff, it uses the ekmUrl
setting to create HTML links to objects that are referenced in the emails. This setting is also used for
the data management process that manages a users server data and connects it to EKM. If this setting
is incorrectly specified the data management process will fail to launch.
46
General Server Settings

Figure 6.2: Default Value for ekmUrl - Evaluation Server
<ekmUrl>http://hostname.domain.com:8080/ekm</ekmUrl>
For an Evaluation server, ekmUrl will always use the fully qualified domain name of the host, and port:
8080.
Figure 6.3: Default Value for ekmUrl - Production Non-Cluster Server
<ekmUrl>http://hostname.domain.com:8080/ekm</ekmUrl>
For a Production non-cluster server, ekmUrl will always use the fully qualified domain name of the
host, and port will be set according to the JBoss 7 ports binding set that was chosen during setup
(ports-default is 8080, ports-01 is 8180 and so on up through ports-03).
Figure 6.4: Default Value for ekmUrl - Production Cluster Node
<ekmUrl></ekmUrl>
For a Production cluster node, the ekmUrl is not set, and must be set manually after setup. The value
of ekmUrl must be set to the URL of the clusters front-end web server.
Specifying the Default Workspace (<defaultDomain>)

The specification of the default workspace is done through the defaultDomain setting. When the
EKM server starts up, it will automatically create the Default workspace specified in this setting if it does
not already exist. The default workspace is displayed as the initially-selected workspace in the EKM login
screen.
Figure 6.5: Default Value for defaultDomain Setting
<defaultDomain>Default</defaultDomain>
Configuring a Repository (<repository>)

EKM uses a bundled content management system for managing files and metadata. The repository
setting in ekm.xml can be used to configure particular policies of the content management system.
The default values for this setting are shown below.
Figure 6.6: Default Values for repository Setting
<repository>
<name>globalRepository</name>
<context>java:app</context>
<providerUrl>localhost</providerUrl>
<location>{$EKM_HOME}/repository</location>
<configurationFile>
{$EKM_HOME}/repository/repository.xml
</configurationFile>
<retentionPolicy>
<defaultExpiration>365</defaultExpiration>
<customRetentionSetting>
<objectType>AuditLog</objectType>
<expiration>30</expiration>
</customRetentionSetting>
<objectType>File</objectType>
<objectType>Folder</objectType>
47

<objectType>Job</objectType>
<objectType>DataExtractionMonitor</objectType>
</retentionPolicy>
</repository>
name
Specifies the name of the repository as registered in the JNDI server.
contextEnv
Specifies the JNDI context under which the repository is registered in the JNDI server.
providerUrl
Specifies the location of the JNDI context if one does not currently exist in the execution environment.
You will seldom need to change these values; the default values should suffice for most workgroup installations of EKM.
repository settings for location, configurationFile, and retentionPolicy are discussed
below.
Specifying the Repository Location (<location>)

The location setting specifies the full path to the repository on the EKM server. The location of the
repository is specified during installation. The repository location must contain the jaas.config and
repository.xml files.
When the EKM server starts up it creates three new folders in the repository folder: repository,
versions, and workspaces. It also creates a DataStore folder whose location is also specified
during installation and stored in the DataStore setting of repository.xml. The DataStore folder
stores the content of all files that are uploaded to EKM. Files that are stored have automatically-generated
IDs as names. This is done so that the files can be moved or renamed in EKM without changing the
location of the content.
The workspaces folder contains a folder for each workspace that is created. A workspace folder contains
the search index for the particular workspace. This index is automatically created by EKM and is used
for searching file content and metadata.
You can change the location of the DataStore folder by changing the path value in the DataStore
setting. However, because the folder contains the contents of all uploaded files to EKM, you must make
sure that it has ample storage space available.
You can change the size of the index for the DataStore directory by changing the minRecordLength
value. You must ensure that the workspaces folder has ample space for storing the index. The size
of the index will depend on the number of objects and the size of files in the repository. 2 GB of space
should be sufficient for storing the index of a medium to large-sized repository.
48
Specifying the Location of the Repository Configuration File (<configurationFile>)

The configurationFile setting specifies the location of the repository.xml file. By default this
file is stored within the repository folder.
Specifying the Object Retention Policy (<retentionPolicy>)

The retentionPolicy setting specifies the global default expiration time (in days) for those objects
that are marked as perishable in EKM. It can also be used to specify the default expiration time on a
per-type basis. Figure 6.7: Default Values for retentionPolicy Setting (p. 49) shows the default values for
this setting. You will seldom need to change this value.
In the listing, the default expiration time for any perishable object is 365 days. For objects of type File
or Folder, the expiration time is 1825 days (or 5 years). For an Audit Log, the default expiration
time is 30 days. For a Job object it is 30 days, and for a Data Extraction Monitor object it is
7 days. Jobs are not marked as perishable until they have finished executing.
Figure 6.7: Default Values for retentionPolicy Setting
<retentionPolicy>
<defaultExpiration>365</defaultExpiration>
<objectType>AuditLog</objectType>
<objectType>File</objectType>
<objectType>Folder</objectType>
<objectType>Job</objectType>
<objectType>DataExtractionMonitor</objectType>
</retentionPolicy>
Configuring Modules (<modules>)

The modules setting configures modules that provide groupings of functionality. The default value
for this setting is shown below.
Figure 6.8: Default Value for modules Setting
<modules>
<module name="ekmServer" enabled="true"/>
</modules>
When defining a module you need to specify a module name, and specify whether or not the module
is enabled by entering either a true or false value. ekmServer is the only module that is defined,
and it should be enabled.
49
Specifying Local Process Policies (<localprocess>)

The localprocess setting specifies policies for executing a predefined set of external applications
directly on the EKM server that perform metadata and report extraction on simulation files. The default
values for this setting are shown below.
Figure 6.9: Default Values for localprocess Setting
<localProcess>
<dataExtractionTimeout>3600</dataExtractionTimeout>
<dataExtractionThreads>1</dataExtractionThreads>
</localProcess>
dataExtractionTimeout
Specifies the timeout value (in seconds) for the predefined set of metadata and report extraction applications. If an application takes longer than the timeout value to complete, it will be terminated by EKM.
The default value is 3600 seconds (or 1 hour).
dataExtractionThreads
The maximum number of simultaneous data extractions that can occur on the EKM server (or cluster
node in the case of a cluster setup). To prevent data extractions from occurring, set this value to 0.
Specifying Remote Process Policies (<remoteProcess>)

The remoteProcess setting specifies policies for executing external applications on a remote machine
using ANSYS' Remote Solve Manager (RSM). The default values for this setting are shown below.
Figure 6.10: Default Values for remoteProcess Setting
<remoteProcess>
<jobSourceRootPath>D:\ekm\jobdata</jobSourceRootPath>

<jobTemplate>GenericJob.xml</jobTemplate>
<rsmClientURL>http://localhost:10012/rsm/</rsmClientURL>
<jobOutputFilename>ekm_job.out</jobOutputFilename>
<dataManagementJreLocation>{$EKM_BASE}/programs/jdk1.7.0_07/jre</dataManagementJreLocation>
<dataManagementJarLocation>{$EKM_BIN}/ekm-servo-15.0.jar</dataManagementJarLocation>
<!-Uncomment the following for integrating with EnginFrame for remote visualization.
You will need to change the following:
a) In serviceDefinitionFile, set the fully qualified host name of the server where
enginframe is running
b) Change the name of the adminUser if its different from efadmin
c) Change the queue definitions. The template provides definition for two queues:
a windows queue using NICE Neutro as the scheduler and NICE DCV as remote visualization solution;
and a linux queue using Platform LSF (or openlava) as the scheduler and NICE DCV as remote
visualization solution. You may need to modify, add or remove queue definitions as needed for
your configuration.
-->
<!-<enginframe>
<serviceDefinitionFile>https://<enginframe-server-name>:8443/enginframe/ekminteractive/ekminteractive.xml</service
<adminUser>efadmin</adminUser>
<queue>
<name>Windows Remote Viz Queue</name>
<os>windows</os>
<scheduler>neutro</scheduler>
<schedulerQueue></schedulerQueue>
<remoteType>dcv</remoteType>
</queue>
<queue>
50

<name>Linux Remote Viz Queue</name>
<os>linux</os>
<scheduler>lsf</scheduler>
</queue>
</enginframe>
-->
<workbenchServerPortRange>51215-51220</workbenchServerPortRange>
</remoteProcess>
jobSourceRootPath
The full path to the directory where EKM will stage the data files for batch jobs submitted to RSM. This
location is specified during installation.
Important
When running EKM as a cluster, this must refer to a SHARED directory path that is accessible to all the nodes in the cluster.
jobTemplate
The job template file used by RSM to run EKM jobs. Keep the default value. This could potentially be
changed if you are working with a customized RSM job template.
rsmJobSourceRootPath
The path used by RSM to access the data files for batch jobs. This setting is required only if RSM is running
on a different machine than the EKM server. In that kind of setup, jobSourceRootPath should be defined
using a network shared path that corresponds to the path on the RSM server.
Example: RSM is running on server rsm1 and the path C:\rsm_temp\jobRoot is set up to be
shared over the network. EKM is running on a different server than RSM and uses the shared path
\\rsm1\rsm_temp\jobRoot to stage files to be used for batch jobs. So, the settings would be:
<jobSourceRootPath>\\rsm1\rsm_temp\jobRoot</jobSourceRootPath>
<rsmJobSourceRootPath>C:\rsm_temp\jobRoot</rsmJobSourceRootPath>
rsmClientURL
The URL used to communicate with RSM via the ANSYS RSM XmlRpcApi Version V15.0 service. The
default setting is shown here:
This setting needs to be changed if RSM is installed on a different machine than EKM or if the default
port of the ANSYS RSM XmlRpcApi V15.0 service is changed. See Installing and Configuring
RSM (p. 120) in the Managing EKM Servers, Queues and External Applications chapter.
Example:
The ANSYS RSM XmlRpcApi V15.0 services configuration is modified to use port 10099 instead
of the default 10012. The Ans.Rsm.XmlRpcServer.exe.config file is edited and modified
to:
<appSettings>
<add key="ListenerPort" value="10099" />
</appSettings>
rsmClientURL in ekm.xml is also modified to specify 10099 as the port in the URL:
51

If you are not changing the default port of the RSM XmlRpcApi server, but RSM is installed on a
different server than EKM, then you need to change only the rsmClientURL setting to use the correct
hostname in place of localhost.
Example:
<rsmClientURL>http://rsmserver1:10012/rsm/</rsmClientURL>
jobOutputFilename
The file name that will be used by all jobs to capture batch processing output.
Note
The dataManagementJreLocation and dataManagementJarLocation settings are
used to configure the data management process. These should be changed only if RSM is
installed on a different server than EKM. If RSM is on a different machine, then it must have
a Java JRE installed and you must copy the data management process jar file to a local path
on the RSM server.
dataManagementJreLocation
The full path to the Java Runtime Environment (JRE) used to run the data management process.
You need to change this value only if RSM is installed on a different server than EKM. If so, then
specify the full path to a Java JRE installed on the RSM server.
Example:
RSM is installed on a different server than EKM. Make sure the RSM server has a JRE installed and
specify the path to the top level directory of the JRE as in this example:
<dataManagementJarLocation> C:\jre1.7.0_07</dataManagementJarLocation>
dataManagementJarLocation
The full path to the executable JAR file used to run the data management process.
By default, the ekm-servo-15.0.jar file is located in the EKM_BIN folder of the EKM installation
(see EKM Path Variables). You need to change this value only if RSM is installed on a different server
than EKM.
Example:
If RSM is installed on a different server than EKM, copy the file C:\ekm150\ekm-server\bin\ekm-servo15.0.jar from the EKM server to a path on the RSM server (such as C:\ekm150_files\ekm-servo-15.0.jar)
and enter this value:
<dataManagementJarLocation> C:\ekm150_files\ekm-servo-15.0.jar</dataManagementJarLocation>
enginframe
Contains EnginFrame settings and interactive queue definitions. For more detailed information see
Configuring EKM to Work with EnginFrame in the EKM Installation Guide.
Figure 6.11: Sample Interactive Queue Definitions
<enginframe>
<serviceDefinitionFile>https://
enginframe-server-name:8443/enginframe/ekminteractive/ekminteractive.xml
</serviceDefinitionFile>
52

<adminUser>efadmin</adminUser>
<queue>
<name>Windows Remote Viz Queue</name>
<os>windows</os>
<scheduler>neutro</scheduler>
</queue>
<queue>
<name>Linux Remote Viz Queue</name>
<os>linux</os>
<scheduler>lsf</scheduler>
</queue>
</enginframe>
The interactive queues defined in the ekm.xml file will be automatically created in the /System/Servers/Master folder when the EKM server is started. Every interactive queue that is
created in EKM will automatically contain the predefined application remoteDesktop.app.xml,
which launches an empty remote desktop session. Once interactive queues have been created in
EKM you can define job submission settings for each queue, including the account names that will
be used to launch remote sessions.
workbenchServerPortRange
The reserved range of ports that the Workbench server will use for listening to command requests from
EKM. This setting is used when Workbench server jobs are started from EKM, and when Workbench
sessions are registered with EKM. The range is defined using a min-max format, as shown in the example
below:
<workbenchServerPortRange>51215-51220</workbenchServerPortRange>
Specifying Cache Service Settings (<cache>)

The cache setting specifies policies for storing files cached from remote EKM servers. The default value
for this setting is shown below.
Figure 6.12: Default Value for cache Setting
<cache>
<size>20G</size>
</cache>
size
The maximum amount of data, in bytes, that can be cached. You can use suffixes k or K for kilobytes,
m or M or megabytes and g or G for gigabytes. For example, 20G shown in the above example denotes
20 gigabytes.
Note
A cache size of 0 means that no files will be cached.
Scheduling Automatic Tasks (<scheduledTasks>)

The scheduledTasks setting specifies the day and time when periodic tasks are executed by EKM.
Below are the default values for this setting, followed by a description of each setting.
53

Figure 6.13: Default Values for scheduledTasks Setting
<dataStoreGc>
<day>Sunday</day>
<hour>0</hour>
</dataStoreGc>
<fileBackup>
<day>Sunday</day>
<hour>0</hour>
</fileBackup>
<remoteSync>
<day>Any</day>
<hour>0</hour>
</remoteSync>
<recycleBinCleanup>
<day>Any</day>
<hour>0</hour>
</recycleBinCleanup>
<mail>
<day>Any</day>
<hour>20</hour>
</mail>
<purge>
<day>Saturday</day>
<hour>22</hour>
</purge>
<batchJobMonitor>
<day>Any</day>
<hour>0</hour>
</batchJobMonitor>
<serverMonitor>
<day>Any</day>
<hour>0</hour>
</serverMonitor>
<cacheMonitor>
<day>Any</day>
<hour>23</hour>
</cacheMonitor>
</scheduledTasks>
You can specify the execution time for any task by providing the day, hour, and min values. Any
value can be used for day if you want the task to be executed all days. Alternatively, you can specify
a particular day of the week such as Saturday, Sunday, and so on. The hour values range from 0
(12 AM) to 23 (11 PM). The min (minute) value ranges from 0 to 59. If min is unspecified, it is taken
as 0. You can specify the interval of the task by providing the dayInterval and hourInterval
values. If you set both of these values to 0, the task will never be executed.
dataStoreGC
Used to periodically clean files from the datastore folder that are no longer being used within EKM.
When a file is deleted from EKM it is not removed immediately but is marked for garbage collection.
The file content is actually removed as part of this scheduled task. As shown in Figure 6.13: Default
Values for scheduledTasks Setting (p. 54), this task is executed every day at 2 AM.
To ensure consistency during restore and preventing accidental deletion of files that have not
yet been committed, this task will delete only those files that are no longer in use, and whose
54

modification time is older than garbage collection start time minus a buffer time. The buffer
time is equal to the specified interval of dataStoreGC scheduled task plus an additional buffer
of 6 hours. For example, suppose default settings are used for dataStoreGC and a file was added
on Monday at 3PM. The next garbage collection will start on Tuesday at 2AM, but this file will
not be deleted because it is still in use. Now suppose this file is deleted on Tuesday at 10AM.
The next garbage collection will start on Wednesday at 2AM, but because the files modification
time is less than the buffer of 30 hours (24 hour dataStoreGC interval and 6 hour of additional
buffer), it will not be deleted even then. The file will only be deleted in the next garbage collection on Thursday at 2AM. This ensures that if a complete backup was started before 10 AM
on Thursday, the file will exist in both the database backup as well as the datastore backup,
as long as the backup finishes before Thursday at 2AM.
Important
The garbage collection interval should exceed the time it takes to complete a full
backup of the datastore to avoid data inconsistency during restore. Thus if the
backup time exceeds 24 hours, the dayInterval setting should be increased from the
default value of 1.
fileBackup
Used to create a backup of all files uploaded to EKM. This is desirable if you want to periodically
write all files managed by EKM to a separate, backup folder. Because you may decide to use your
own backup policy, by default, this task is specified to never execute because the dayInterval
and hourInterval values are set to 0.
remoteSync
Used to periodically synchronize all files and folders in remote file servers. EKM allows users to create
a reference to files/folders that reside in remote servers, in lieu of uploading them. This task is used
to periodically poll the external servers and synchronize the information in EKM, to determine if
any changes have occurred in the file server.
recycleBinCleanup
Used to periodically purge objects from the Recycle Bin of all users in all workspaces, based on the
recycle bin cleanup policy specified in the users' preference. Objects will be deleted only if the user
has chosen to delete objects in the Recycle Bin that are older than X days, and more than X days
have elapsed because the object was placed in the Recycle Bin.
mail
Used to send an email to users that have subscribed to receive alerts for certain objects. By default,
this task runs at 8 PM every day.
purge
Used to remove objects from the repository that have expired. By default, this task runs every Saturday at 10 PM.
batchJobMonitor
Used for monitoring the status of asynchronous batch jobs submitted to RSM. This task is run every
minute to get real time feedback.
serverMonitor
Used for monitoring the status of remote EKM servers. This task is run every 10 minutes. If a server
cannot be reached, a warning is shown in the EKM user interface, alerting the system administrator
to investigate the issue.
55

cacheMonitor
Used to monitor the size of the cached data. It is run every night at 11 PM. It first removes any
cached files that are no longer present in the master EKM workspace where the file came from. It
then calculates the total size of the cache and if the size exceeds the maximum limit, it removes
the oldest files one at a time until the size is below the limit. The age of the file is based on its
last access time.
Configuring Plug-ins (<pluginRegistry>)

The pluginRegistry setting is used to configure plug-ins that are loaded by EKM. The default values
for this setting are shown below.
Figure 6.14: Default Values for pluginRegistry Setting
<pluginRegistry>
<pluginDirectory>
{$EKM_HOME}/plugins-deploy
</pluginDirectory>
<loadAll>true</loadAll>
<pluginSettings pluginName="cae">
<param name="customResourcesPath" value=""/>
</pluginSettings>
</pluginRegistry>
pluginDirectory
Specifies the full path of the directory containing the plug-in JAR files. By default, it is set to the pluginsdeploy directory within the EKM installation directory. The loadAll setting determines whether all
the plug-in JAR files in the pluginDirectory should be loaded or not. By default, this value is set to
true. If you specify it as false, then you can explicitly list all the plug-ins you want to load by the following
line. You will seldom need to change these two values.
<plugin>PLUGIN-JAR-NAME</plugin>
pluginSettings
Used to specify plug-in-specific settings that are given as name value pairs. Currently the only available
setting is customResourcesPath for the cae plug-in. The customResourcesPath setting is used
to specify a path where script files for metadata extraction and report generation can be placed if you
want to override the default data extraction of built-in CAE types.
Specifying the Superuser Name and Password (<superUser>)

The superUser setting is used to specify the user name and password of the superuser. A superuser
is a special EKM user that has access to the EKM Administration interface of EKM, which allows workspace creation and migration. The default values for this setting are shown below.
Figure 6.15: Default Value for superUser Setting
<superUser>
<name>superuser</name>
<password>9a85a0cc0a56febcf46690a6ab1a5803</password>
</superUser>
name
Specifies the name of the user.
56

password
Specifies the md5 hash of the superuser password. For security reasons clear text password is not stored
in the file. The default value corresponds to the password: superuser123. It is recommended that
you use the administration interface to change this default password after installation.
Configuring a Cluster (<cluster>)

The cluster setting is used to specify the configuration of a cluster. The default settings, shown in
Figure 6.16: Default Value for cluster Setting (p. 57), must not be changed. These values are for nonclustered installation; for clustered installation, these settings are set according to the inputs provided
in the EKM Installation Wizard.
Figure 6.16: Default Value for cluster Setting
<cluster>
<clusterName>ekmServer</clusterName>
<nodeName>node1</nodeName>
<type>local</type>
<configFile>{$EKM_HOME}/conf/cluster.xml</configFile>
<cacheConfigFile>{$EKM_HOME}/conf/clusterCache.xml</cacheConfigFile>
</cluster>
clusterName
Specifies the name of the cluster that the node belongs to.
nodeName
Specifies the name of this cluster node.
type
Must be local for non-clustered installation and cluster for clustered installation.
configFile
Specifies the location of the cluster network transport configuration file.
cacheConfigFile
Specifies the location of the configuration file for the infinispan cache, which is a cluster-wide in-memory
cache.
sharedDir (optional)
Specifies a shared directory for cluster resource files, log files, and so on, in a clustered installation.
Specifying Memory Limits (<memoryLimits>)

The memoryLimits setting is used to limit the number of objects that can be processed by an operation. This is needed so that the server is not overloaded by operations that operate on large number
of objects. These limits also avoid server crashes caused by memory overflow. When an operation exceeds
the specified limit, an error message will be displayed to the user and the user can repeat the operation
on a smaller set of objects. The default values specified will work for most use cases and for most
servers. But if your server has very high memory available and you want to allow users to perform large
operations, you can increase the limits after some thorough testing. The default values for this setting
are shown below.
Figure 6.17: Default Values for memoryLimits Setting
<memoryLimits>
<maxSearchResults>500</maxSearchResults>
<maxNewObjects>20000</maxNewObjects>
57

<maxReadObjects>60000</maxReadObjects>
<maxDirtyObjects>20000</maxDirtyObjects>
</memoryLimits>
maxSearchResults
Specifies the maximum number of results that can be displayed by a search.
maxNewObjects
Specifies the maximum number of new objects that can be created by an operation in a single transaction.
The operations impacted by this setting are usually archive extraction and remote folder synchronization.
Users will not be able to synchronize a remote folder if the number of files and folders contained within
it exceed the specified limit.
maxReadObjects
Specifies the maximum number of objects that can be read from the database in a single operation.
maxDirtyObjects
Specifies the maximum number of objects that can be modified in a single transaction. This setting
usually impacts recursive operations such as setting of properties, permissions, version control and so
on. For example, users will not be able to recursively modify permissions of a folder that contains objects
beyond the specified limit.
Specifying the Email Domain (<email>)

The email setting enables you to specify a configured domain for all e-mails, alerts and messages that
are sent by EKM. By default, the domain that you specify will be part of every e-mail address specified
in EKM. The default value for this setting is shown below.
Figure 6.18: Default Value for email Setting
<email>
<mailFromDomain>nodomain.com</mailFromDomain>
</email>
Specifying the Custom User Interface Folder (<customResourcesPath>)

The customResourcesPath setting is used to specify the folder that contains user interface files for
custom dialog boxes. Refer to the Defining Custom Dialogs, Wizards and Applications chapter in the
EKM Users Guide for details on how to create these files.
Figure 6.19: Default Value for customResourcesPath Setting
<customResourcesPath>{$EKM_HOME}/conf/resources</customResourcesPath>
Specifying the Root Directory for File Transfers (<fileTransferService>)

The fileTransferService setting determines the root directory for the file transfer service when
uploading a file to EKM using the File Transfer Client. This is the staging area in which files are temporarily held before being imported into EKM. The default value is the TEMP directory. In a clustered environment, the rootDir value will need to be changed on each node to a shared directory that all nodes
can access.
Figure 6.20: Default Value for fileTransferService Setting
<fileTransferService>
<rootDir>{$EKM_TEMP}</rootDir>
</fileTransferService>
58
Optional Settings
6.3. Optional Settings

Optional settings are advanced settings that provide additional options for customizing and configuring
the EKM server. They are described below and their usage demonstrated by sample XML code.
bootstrapper and initializer
sessionTimeout
showBetaFeatures
fileBackupPath
testMode
dataLink
mobileConnector and mobileServer
individualMode
Configuring Custom Bootstrapper and Initializer Classes (<bootstrapper>

and <initializer>)
The bootstrapper and initializer settings can be used to configure custom bootstrapper and
initializer classes. The bootstrapper class is used when a workspace is created and is populated with
initial objects. The initializer class is used every time EKM starts up and can be used to execute
custom logic at startup time. Both of these settings require that a Java class is created in a plug-in, and
the full name of the java class is specified as a value. By default, the value for these settings is empty
as shown in Figure 6.21: Default Value for bootstrapper and initializer Settings (p. 59).
Figure 6.21: Default Value for bootstrapper and initializer Settings
<bootstrapper></bootstrapper>
<initializer></initializer>
Specifying the Maximum Idle Time for a Session (<sessionTimeout>)

The sessionTimeout setting can be used to specify the maximum time (in minutes) that a user
session can remain idle without any user activity. Once this time has elapsed, the user session is deactivated and the EKM license is released. The default value of this setting is 30 minutes as shown in the
example below.
Figure 6.22: Default Value for sessionTimeout Setting
<sessionTimeout>30</sessionTimeout>
Showing or Hiding Beta Features (<showBetaFeatures>)

The showBetaFeatures setting can be used to either show or hide beta features. By default, the
value of this setting is false as shown in the example below.
Figure 6.23: Default Value for showBetaFeatures Setting
<showBetaFeatures>false</showBetaFeatures>
59
Specifying a Backup Location (<fileBackupPath>)

The fileBackupPath setting is the full path of the folder where all files in EKM will be written to by
the fileBackup scheduled task. The default value for this setting is shown below.
Figure 6.24: Default Value for fileBackupPath Setting
!-- Uncomment the following if you plan to use the fileBackup task to export files to
an external location. Provide the full path of the folder where you want the
backup files to be stored.
<fileBackupPath></fileBackupPath>
Enabling Test Mode Operation (<testMode>)

The testMode setting is used to specify whether the EKM server should be started in test mode or in
production mode. By default, this setting is not specified which means that the server will start in production mode. testMode is used primarily to provide a sandbox server that can be made available for
prototyping activities. To enable testMode, you will need to set it to true, as shown in Example 6.1: testMode Setting (p. 60). Test server can only be accessed by a single user at a time.
Example 6.1: testMode Setting
<testMode>true</testMode>
Enabling PDM/PLM Integration (<dataLink>)

The dataLink setting is used to enable PDM/PLM integration using EKM DataLink. See the DataLink
configuration guide for more details.
Enabling EKM Mobile (<mobileConnector> and <mobileServer>)

These settings can be used to enable the EKM mobile interface as described in Configuring EKM Mobile (p. 127).
Enabling Individual Mode (<individualMode>)

The individualMode setting can be used to set some or all workspaces in individual mode. Collaboration features (for example, data sharing) are not available in an individual mode workspace. A sample
setting is shown below.
Example 6.2: individualMode Setting
<individualMode>
<default>false</default>
<exclude>SharedWorkspace</exclude>
</individualMode>
default
The default mode for all workspaces in the server. If the value is true, then all current workspaces that
are not excluded and any newly created workspace will be in individual mode. Otherwise these workspaces
will be in shared mode. The default value is false.
exclude
An optional setting that specifies the name of the workspace whose mode is different from the default.
You can specify any number of exclude settings. In Example 6.2: individualMode Setting (p. 60), the
60
Optional Settings
default mode for all current and new workspaces in the server is individual, but since the SharedWorkspace is excluded, its mode will be shared.
61
62
Chapter 7: Defining Custom Types

You can create and edit custom data types when the workspace is in restricted configuration mode. To
create a custom type you simply fill out fields in a dialog box, as described in Defining Custom Types
Directly in EKM (p. 66). Alternatively you can create an XML file outside of EKM and then upload it into
EKM. See Defining Custom Types Using XML (p. 83) for details.
This chapter will describe the steps required to add or modify a custom type, assuming that the restricted
configuration mode has already been started (see Restricted Configuration (p. 31)). Once you are done
with your modifications, you can accept the configuration to commit the changes and exit the restricted
configuration mode. At that time, EKM may ask you to migrate old data whenever it sees a structural
difference between an old type and a new one. Structural differences occur when you add or remove
a property or child from an existing type. Adding a new type or deleting a type is not considered a
structural change. See Migrating Workspaces (p. 27) for more details on how to migrate workspaces.
Data migration is a time-consuming exercise that you should undertake only when necessary on a
production workspace. Therefore you should ensure that the changes are correct and agreeable to all
stakeholders before committing them to a production workspace.
Many of the examples described in this chapter can be found in the examples folder in your EKM
server:EKM_HOME/examples/conf/customTypes.
Important
By default, Google Chrome does not display XML files such as the those in /System/Configuration/Custom Types. However, you can install an extension such as XML Tree
to enable viewing of XML. Go to https://chrome.google.com/extensions (or choose Extensions
from the Chrome menu) and search for XML. Among the search returns will be the XML Tree
extension, which has been found to work.
In this chapter:
7.1. Overview of Custom Types
7.2. Suggested Steps for Defining Custom Types
7.3. Defining Custom Types Directly in EKM
7.4. Defining Custom Types Using XML
7.5. Custom Type Examples
7.6. Extending Built-in Types
7.1. Overview of Custom Types

EKM provides you with the capability to define new custom types for a workspace that are either new
object types or extensions to built-in types. There are numerous scenarios for which you may want to
create new data types or extend a built-in type in EKM:
Creating a New Object Type:
Custom File Formats: If you have proprietary files for which EKM does not provide off-the-shelf
support for, you can easily create custom data types that support these file formats. Custom data
63
Defining Custom Types

types can be used to define metadata (properties) that are extracted by an application after a file
is uploaded. You can also define properties that users must input when a file is uploaded. These
user-defined properties can be useful for defining attributes that cannot be automatically extracted
from files but are relevant to your business process. A Project ID attribute is an example of a userdefined attribute. A custom file format definition can also specify applications for extracting images
and reports from files. See Custom File Formats (p. 94) for more details.
Custom Folder Structures: By default, EKM organizes data in files and folders in a way that is
similar to Windows and Linux file systems. The hierarchical structure is easy to understand. You
may, however, want to have more control over how data is organized in EKM, and you may want
to be able to enforce a standard way of naming or organizing files and folders. This can be done
by creating custom folder structures. Custom folder structures are data types that specify the name,
type, and occurrence (single or multiple) of child objects. They enable you to control how new
objects can be added to a particular type in EKM. See Custom Folder Structures (p. 91) for more
details.
Custom Analysis Project: Analysis Project is specific type of container that can be used to manage
all data that is associated with an analysis. Apart from data, it also manages inputs and outputs of
the analysis and enables it to be automatically re-executed if the project becomes out-of-date.
Users can create new instances of Analysis Project objects in EKM and provide information on
where inputs and outputs are located and how to execute the analysis. If you do not want users
to manually enter this information every time they create a project, you can define a custom Analysis Project that specifies this information in the type definition. See Custom Analysis Projects (p. 93)
for more details.
Extending a Built-In Type: Built-in types come with a standard list of properties that are created by
EKM (for example, Date Modified, Modified By, and so on) and metadata that are extracted automatically after upload (for example, physical model data used in a simulation). However, you may also
want users to specify additional attributes at upload time that are relevant to your business requirements or extract additional metadata. This can be done by extending a built-in type and adding more
properties. See Extending Built-in Types (p. 99) for more details.
7.1.1. About Built-in Types

The off-the-shelf version of EKM provides numerous built-in data types for storing files and capturing
data and processes that are associated with CAE simulations in an EKM repository. These built-in types
also come with a standard list of metadata (properties) that store information about the simulations.
Before you begin the process of defining a new custom type that extends a built-in type, you will need
to review built-in data types that are supplied with EKM. This section provides details about built-in
types that are commonly referenced by custom data types. See Appendix B (p. 207) for a complete listing.
Important
Data type labels that are displayed in the user interface or in the documentation are localized
labels (for example, Ansoft ePhysics File). The actual non-localized names of the types are
different (for example, AnsoftePhysics) and are described below. You MUST use non-localized
names when referring to built-in and custom type definitions.
You can think of types in EKM as being analogous to classes in an object-oriented programming language.
There is a base type named Model (also referred to by its localized name - EKM Object) and all other
types extend Model or a sub-type of Model. When a type extends another type it inherits the properties,
64
Suggested Steps for Defining Custom Types

children, and type attributes of the parent type. Sub-types can add new properties, children, and type
attributes. They cannot, however, remove anything defined by the parent type.
Below are some built-in types that are commonly referenced by custom types:
Container
This is the base type for all Container types such as Folder and custom Folder.
Folder
This type refers to a Folder object.
File
This is the base type for all File types. Some file types include:
Report: This is the base type for all Report types.
CaeModelSummaryReport: This type is used for all Simulation Details Report types.
CaeModelFile: This is the base type for all files that contain information about a simulation
model.
AnsysDatabase: This type is used for ANSYS Database/Mechanical APDL Database files (.db)
AnsysResult: This type is used for ANSYS Result files (.rst, .rth, .rmg)
WorkBenchSimulation: This type is used for Workbench Simulation files (.dsdb)
WorkBenchProjectArchiveFile: This type is used for Workbench Project Archives (.wbpz)
CfxDefinition: This type is used for CFX Definition files (.def)
CfxResult: This type is used for CFX Result files (.res)
FluentCase: This type is used for Fluent Case files (.cas)
PolyflowData: This type is used for Polyflow Data files (.dat)
HfssProject: This type is used for HFSS files (.hfss)
AnsoftDesigner: This type is used for Ansoft Designer files (.adsn)
AnsoftSimplorer: This type is used for Simplorer files (.asmp)
7.2. Suggested Steps for Defining Custom Types

The creation of custom types is an iterative process. You may want to create an initial implementation,
obtain feedback from stakeholders, make the suggested changes, and iterate through the process until
you come up with a new type (or changes to an existing type) that is agreed upon by all the concerned
parties. It is therefore recommended that you use a separate workspace for experimenting with custom
data types (see Creating a New, Empty Workspace (p. 19)). Once the changes are approved, you can
add them to the production workspace. Follow the instructions below to define your custom type using
the user interface or XML.
When you are ready to define a custom type, refer to one of the following methods:
65

Defining Custom Types Directly in EKM (p. 66)
Defining Custom Types Using XML (p. 83)
7.3. Defining Custom Types Directly in EKM

The easiest way to define a new custom type is to use the New > EKM Type feature in EKM. When you
create a custom type this way, EKM creates an XML file for the custom type definition behind the scenes.
The settings that you specify are the same settings that you would specify if you were creating a custom
type using XML, so you may at times find it helpful to refer to Defining Custom Types Using XML (p. 83).
To create or modify a custom type, you must go into restricted configuration mode. Refer to Restricted
Configuration (p. 31) for details. The instructions in this chapter assume that you have done this.
You can create three kinds of custom types: an object type, a mixin, or an extension to a built-in type.
These are discussed below in Defining a New Custom Type (p. 66). If a custom type is already defined
and you want to edit it, see Editing a Custom Type (p. 83).
7.3.1. Defining a New Custom Type

There are three types of custom types you can define: an object type, a mixin, and an extension to a
built-in type. Mixins are not types on their own, but can be embedded in an object type or extension
to a built-in type.
To define a new custom type:
1.
66
While in restricted configuration mode, select the /System/Configuration/Custom Types

folder, then right-click and select New > EKM Type from the context menu. This opens the New Custom
Type dialog box.
Defining Custom Types Directly in EKM

Figure 7.1: New Custom Type Dialog Box
2.
This dialog box contains the following tabs for specifying various settings of the custom type:
General: In this tab, you specify:
Kind of custom type: You have 3 options to choose from: Object type, Mixin or Extension to a
built-in type. Refer to Defining Custom Types Using XML (p. 83) for more details on these options.
The other settings in the tab and the other tabs in this dialog box depend on which option you
select.
Name: This is the name of the custom type. Note that the custom type name, also referred to as
typeName, is not the same as the name of the custom type object; however, usually the object
name is typeName.type.xml. Thus if you specify the name to be Project, the name of the object
will be Project.type.xml.
Label: The name is usually an internal id whereas the label is how the type is represented in the
user interface. A label is not specified if you are creating a mixin or an extension to a built-in type.
Extends from: This is the base class from which the type extends. This is not specified if you are
defining a mixin. Existing types are shown in a drop-down list. Non-localized type names are used
because some type names have a common localized name. Also, the list may not contain a new
type that you have just defined if you have not yet accepted or applied the workspace configuration.
67

If you want to refer to a recently-created type in your new custom type definition, then you will
need to apply the workspace configuration first, before you can define the new type.
Properties: On this tab you specify the properties of the custom type. This tab is not available if you
are defining an extension to a built-in type. See Defining Properties for a Custom Type (p. 68) below
for details. Note that if you want to extend an existing type by adding properties to it, you will need
to first define a mixin that specifies the properties, and then add the mixin to your extended type
definition.
Children: On this tab you specify any children of the type. This tab is not available if you are defining
an extension to a built-in type. See Defining Children for a Custom Type (p. 70) below for details.
Mixins: On this tab you specify any mixins of the type. A mixin can be used to create sharable groups
of children and properties that can be included in more than one type (new data types and extensions
to built-in types). This tab is not available if you are defining a mixin. See Defining Mixins for a Custom
Type (p. 71) below for details.
Type Attributes: On this tab you specify any type attributes of the type. This tab is not available if
you are defining a mixin or an extension to a built-in type. See Defining Type Attributes for a Custom
Type (p. 72) below for details.
Actions: On this tab you specify any actions for the type. This tab is not available if you are defining
a mixin. See Defining Actions for a Custom Type (p. 80) below for details.
3.
When you have specified all the settings, you can click Create & New to create the new type and open
the same dialog box again for creating an additional type. If you do not want to create any additional
types, you can click Create & Close to create the type and dismiss the dialog box.
7.3.1.1. Defining Properties for a Custom Type

The Properties tab in the Edit Custom Type dialog box can be used to specify properties of a custom
type as shown in Figure 7.2: Edit Custom Type - Properties (p. 69).
68

Figure 7.2: Edit Custom Type - Properties
You can click Add to add a new property. You can then specify the settings for each property in the
Property definition pane. The settings will depend on the type of the property, but will include the
following:
Name: This is the name of the property. When a new property is added it has a default name, such
as prop0. You can change the name and click the Rename button to specify a different name.
Label: This is how the property will be represented in the user interface.
Type: Choose the property type: String, Integer (referred to as Long in XML), Real Number (referred
to as Double in XML), Boolean, Date or Reference.
Default: You can specify a default value for the property. The value should be compatible with the
type, and whether or not it is multi-valued. Refer to Defining Properties Using XML (p. 85) for more
details on how to provide correct values for various property types.
Options: If the user can only select the value of the property from a limited set of options, you can
specify the options separated by comma.
Display order: This value is set when you want the property to appear in a particular order in the
Properties display or in a dialog box when user input is required. Dialog boxes include: Edit Properties,
Edit Type, New Folder, and New Object. This value can be any valid integer. Properties with lower
69

order are displayed first. If unspecified, the default value is 0, which will display the property alphabetically by name.
Extracted: If this check box is selected it means that the property value is automatically extracted.
Otherwise it is specified by the user.
Required: If this check box is selected it means that the user is required to enter the value of this
property.
Multivalued: If this check box is selected it means that the property is multi-valued or a list.
Base type: This setting is available if the property type is Reference and is used to specify the base
type of the object reference. You may need to apply the workspace configuration in order to see a
recently created custom type in this list.
Minimum and Maximum: These settings are available if the property type is Integer or Real Number.
Quantity and Unit: These settings are available if the property type is Real Number and are used to
specify the unit information. Refer to Defining Properties Using XML (p. 85) for more details.
You can also click an existing property in the Properties column to either change its settings or remove
it by clicking Remove.
7.3.1.2. Defining Children for a Custom Type

The Children tab enables you to specify the children of a custom type as shown in Figure 7.3: Edit
Custom Type - Children (p. 71).
70

Figure 7.3: Edit Custom Type - Children
You can add a new child by clicking the Add Child button. This will add a new row to the children
table. For each child you can specify the following:
Name: This is the name of the child. It can be empty if the child is a list.
Type: This is the type of the child. You may need to apply the workspace configuration in order to
see a recently created custom type in the drop-down list.
Is List: Specifies whether or not the child is a list.
7.3.1.3. Defining Mixins for a Custom Type

Mixins can be defined when you want to create a sharable group of children and properties that can
be included in more than one custom type (new data type/extension to a built-in type). The Mixins
tab enables you to specify the mixins for a custom type, as shown in Figure 7.4: Edit Custom Type Mixins (p. 72).
71

Figure 7.4: Edit Custom Type - Mixins
You can add a new mixin by clicking Add Mixin. This will add a new row to the Mixin table. You can
select the particular mixin that you want to add to the custom type from the drop-down list. You may
need to apply the workspace configuration to see a recently-created mixin in this list. You can remove
an existing mixin by clicking the Remove button in the row.
7.3.1.4. Defining Type Attributes for a Custom Type

The Type Attributes tab enables you to specify type attributes for a new object type (Figure 7.5: Edit
Custom Type - Type Attributes (p. 73).).
72

Figure 7.5: Edit Custom Type - Type Attributes
The Type Attributes that are shown in the dialog box depend on the base type from which the custom
type extends. The list of type attributes shown in Figure 7.5: Edit Custom Type - Type Attributes (p. 73)
are the default settings for a new object type that extends from CaeModelFile. Settings are described
below.
icon
This attribute can be used to specify the path of the icon file associated with this file type. You can place
icon files in the resources folder (typically EKM_HOME/conf/resources) and specify the value of this
type attribute as /custom/<path of icon file in resources folder>.
To specify icons for a parent menu that is not associated with any action, you can add a new action
and just provide an icon without supplying a macro.
extractImageOnUpload
This attribute can either be true or false and specifies whether an image of the CAE model should
be extracted after upload. Images are not extracted from all simulation files.
propertyUpdateMacro
This attribute can be used to specify a macro that will enable dependencies to be created across properties, so that if one property is changed, other properties that depend on it will change as well. The
73

macro that you specify must be defined in the Script entry box on the Actions tab. See Example: Specifying a Macro that Creates Dependencies Across Properties (p. 83) for an example.
A dependent property can change if:
the property value is changed
the property is enabled or disabled
the property options are changed for drop-down lists or list boxes
The property dependencies will be visible in the following dialog boxes in EKM:
Edit Properties (Set Properties step)
Upload
New Folder
The macro that you define on the Actions tab should have two arguments. The first argument is of
type ModelObjectInterface and for the Edit Properties dialog box, it is the object whose
properties are being changed. For the Upload and New Folder dialog boxes, it represents the
parent folder where the object will be added or uploaded. The second argument is a map of the
Property object. An overview of the methods contained in the Property object is provided
below. For more details, refer to the scripting interface API.
getValue: Returns the current value of the property.
setValue: Sets the value of the property.
If you need to modify variable values using an action macro, you can either have the macro return
a map containing the name of the property and its updated value or directly set values using the
setValue method in the macro.
isDisabled: Returns true if the property is disabled and false otherwise.
setDisabled: Disables or enables the property.
getOptions: Returns the list of options for properties shown in a drop-down list or list box.
setOptions: Sets the options for properties shown in a drop-down list or list box. The specified
options must be a subset of options specified in the type definition for that property.
imageName
This attribute can be used only when an imageApplication is specified. It specifies the name of the
image file that will be generated by the image extraction application. This name is used to determine
the content type or the format of the image.
contentType
This attribute can be used to specify the MIME type of the file.
initializeMacro
This attribute can be used to specify a macro that will executed after the object is created. The macro
that you specify should have one argument of type ModelObjectInterface that represents the
74

newly-created object and must be defined in the Script entry box on the Actions tab. See Example:
Executing a Macro When an Object Is Created (p. 83) for an example.
imageApplication
This attribute is used to specify the application used for extracting an image from a file after upload.
Images can be extracted in any web-compatible format such as GIF, JPEG, PNG, TIFF, as well as VCollabs
CAX format for 3D visualization. The application should take the name of the file as a command line
parameter and generate the image file in the current working directory. The input file will also be
available in the current working directory.
extension
This attribute can be used to specify the file extension for the format. EKM uses the extension to
identify the appropriate type for a file. If your file format can have multiple extensions then you can
specify them in a comma-delimited string.
metaDataApplication
This attribute can be used to specify an application for extracting metadata from a file after upload. The
value for this type attribute should be a key for the application defined in the application.xml
file. See Extracting Metadata from Custom File Formats (p. 96) for details. If this value is empty, the builtin extractor will be utilized if defined for that type.
extendBuiltInExtraction
This attribute can be used to specify whether the metadata or report extractors that are specified will
extend or replace any built-in extractors. When the value is set to true (default), the additional extractors
that you specify for metadata extraction in the metaDataApplication setting and simulation details
report extraction in customReportApp setting will extend the built-in extractors so that custom extraction occurs after the built-in extraction. When the value is false, the additional extractors will replace
the built-in extractors so that built-in extraction does not occur at all. This attribute will be available only
if you are defining a new object type. If you are defining an extension to a built-in type, then you will
need to set this attribute in the WorkspaceConfig.xml file.
typeValidatorClass
This attribute can be used to specify a Java class used for determining a files type. This is used for
automatic type assignments during uploads.
The custom type validator class requires the com.ansys.ingress.core.fs.FileType
Validator interface in the ekm-core-15.0.jar file for compilation. After compilation the
*.jar file containing the custom type validator class should be placed in the EKM_Home/pluginsdeploy folder. EKM will load the type validator class from this *.jar file when the server is restarted.
showContentViewAsDefault
If set to true, the content view of the CAE File will be the default view in the interface.
reportApplication
This attribute can be used to specify an application for extracting a Simulation Details Report from a
file after upload or on-demand. See Extracting Reports from Custom File Formats (p. 97) for information
on how to build an application for extracting the report.
Example: Specifying a Custom Metadata and Report Extractor for a Built-in Type
The following sample XML code is used to define a custom report extractor (customReportApp) and
a custom metadata extractor (customMetaApp) for new type that is an extension to the built-in
FluentCase type. While the workspace is in restricted configuration mode, edit the content of the
75

WorkspaceConfig.xml file in /System/Configuration (using Edit > Content), and add the
following XML code:
<typeSettings>
<type name="FluentCase">
<typeAttribute name="extendBuiltInExtraction" value="true"/>
<typeAttribute name="metaDataApplication" value="customMetaApp"/>
<typeAttribute name="reportApplication" value="customReportApp"/>
</type>
</typeSettings>
Then, apply and accept the workspace configuration. The applications need to be defined as External
Applications under EKM Server (for example, /System/Servers/Master/EKM Server). Refer
to Extracting Metadata from Custom File Formats (p. 96) for more information on defining applications
for the metadata extraction.
Example: Specifying a Metadata and Report Extractor for a New Object Type
The following example defines a custom extractor for metadata and report generation for a new custom
object type of type NCT that extends CAEModelFile. The file listings for the extractor Python files,
external application XML files, custom object type, and custom mixin type are shown below.
1. Using a text editor, create the external applications that are needed by copying and pasting the contents
of the external application files customMetaApp.app.xml and customReportApp.app.xml listed
below into an empty file and saving the files with the names and extensions as noted.
2. Using a text editor, create the custom object type and custom mixin type files that are needed by
copying and pasting the contents of the NewCustomType.type and mix1.type listed below into
an empty file and saving the files with the names and extensions as noted. You can also create these
files using the New > Custom Type action. To do this, you will have to refer to the settings in the XML
files and specify the corresponding settings in the Edit Custom Type dialog box.
3. Edit the external application files and enter the correct path to your Python executable in <execPath>.
Also, enter the path to the directory where the Python files (extract-additional-metadata.py
and extract-additional-report.py listed below) are stored on your local drive in <param>.
Example:
<execPath>C:\Python25\python.exe</execPath>
<param>C:\EKM14\extract-additional-metadata.py</param>
4. While the workspace is in restricted configuration mode, upload the external application files to the
/System/Servers/Master/EKM Server folder.
5. Upload NewCustomType.type and mix1.type files to the /System/Configuration/Custom
Types folder.
6. Apply and Accept Workspace Configuration. You may have to migrate your workspace if there are data
model conflicts that need to be resolved. To do this, log out of EKM and log in to the EKM Administration
site. Once migration is complete, log back in to EKM and Apply/Accept the Workspace Configuration.
7. Upload any Fluent case file. Change the type to NCT using Edit > Type.
8. Display the simulation details report and view the custom report additions by double-clicking on the
Fluent case file.
76
9. Display the added custom metadata for the report by clicking the Properties tab.
77
File Listing for extract-additional-report.py

f = open('ekm-report.xml', 'w')
s = """
<ekmReport:section xmlns:ekmReport="http://www.ansys.com/ekm/report" name="Custom report">
<table name="Project Information">
<column name="condition"/>
<column name="value"/>
<row><value>Client</value><value>abc</value></row>
<row><value>Company Name</value><value>ANSYS</value></row>
<row><value>Company Location</value><value>Globally</value></row>
<row><value>Contact Person</value><value>Dana</value></row>
<row><value>Contact Address</value><value>abc@def.com</value></row>
</table>
<table name="Solution Information">
<row><value>Solver</value><value>Mechanical APDL</value></row>
<row><value>iterations</value><value>1500</value></row>
<row><value>version</value><value>15.0</value></row>
<row><value>tolerance</value><value>0.02</value></row>
<row><value>physicalModels</value><value>Stress, Magnetostatic</value></row>
</table>
</ekmReport:section>
"""
f.write(s)
78
f.close()
File Listing for extract-additional-metadata.py

import os
scriptPath = os.getenv('PYTHON_EXEC_PATH')
f = open('ekm-meta-data.xml', 'w')
s = """<ekmMetaData:meta-data xmlns:ekmMetaData="http://www.ansys.com/ekm/metaData">
<data name="p1" value="%s"/>
<data name="p2" value="101"/>
<data name="fluentVersion" value="6.4.17"/>
</ekmMetaData:meta-data>
""" % scriptPath
f.write(s)
f.close()
File Listing for customMetaApp.app.xml

<ekmApplication:applications xmlns:ekmApplication="http://www.ansys.com/ekm/application"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<application>
<key>customMetaApp</key>
<param>C:\EKM14\extract-additional-metadata.py</param>
<nativeOptions />
</application>
</ekmApplication:applications>
File Listing for customReportApp.app.xml

<application>
<key>customReportApp</key>
<param>C:\EKM14\extract-additional-report.py</param>
<nativeOptions />
</application>
File Listing for NewCustomType.type

<ekmTypes:types xmlns:ekmTypes="http://www.ansys.com/ekm/types"
<type name="New Custom Type" extends="CaeModelFile" label="NCT" version="0">
<properties />
<children />
<mixins>
<mixin>mix1</mixin>
</mixins>
<typeAttributes>
<typeAttribute name="extension" value="cas" />
<typeAttribute name="extendBuiltInExtraction" value="true" />
<typeAttribute name="metaDataApplication" value="customMetaApp" />
<typeAttribute name="extractImageOnUpload" value="true" />
<typeAttribute name="imageName" value="file.cax" />
<typeAttribute name="showContentViewAsDefault" value="false" />
<typeAttribute name="contentType" value="text/plain" />
<typeAttribute name="reportApplication" value="customReportApp" />
<typeAttribute name="imageApplication" value="extractCaxImage" />
</typeAttributes>
<actions>
<script />
79

</actions>
</type>
File Listing for mix1.type

<mixin name="mix1" version="0">
<properties>
<property name="p2" type="Long" label="" multivalued="false"
required="true" specifiedBy="extractor" displayOrder="1">
<defaultValue>0</defaultValue>
<constraint name="min" value="-9223372036854775808" />
<constraint name="max" value="9223372036854775807" />
</property>
<property name="p1" type="String" label="" multivalued="false"
required="true" specifiedBy="extractor" displayOrder="0">
<defaultValue />
</property>
</properties>
<children />
</mixin>
</ekmTypes:types>
7.3.1.5. Defining Actions for a Custom Type

The Actions tab enables you to define actions for a custom type. Actions that you add will be associated
with the custom type and selectable from the right-click context menu as well as from the action toolbar.
You can also define an icon to represent the action which will be visible on the toolbar and in menu
items as well.
80

Figure 7.6: Edit Custom Type - Actions
To edit a custom type:

1.
Select the Script Language that you want to use for the script that will be associated with the action.
2.
Enter or paste the script into the Script text box.
3.
Click the Add Action button to add an action for the custom type. A new row will be added for each
new action you add. For each action in the table, specify the Name, Macro, Permissions, and (optional)
Icon, in accordance with the settings described in Defining Actions Using XML (p. 89). For menu groups,
you may add a row containing just the Name and Icon of the group. There is no Macro associated with
a menu group. Click Remove to remove an action from the list.
4.
Click OK if you are finished editing the type or another tab to continue editing.
Example: Custom Action with Icon

The following example defines an icon for two actions added to a custom Project folder type.
1. Create two sample image files containing icons and name them tips.gif and ansysIconSmall.gif.
2. Create an icons folder in EKM_HOME/resources/ if it does not exist. Copy the image files to this
folder.
81

3. Begin workspace configuration.
4. Upload the Project.type.xml file that is provided in the examples folder in EKM_HOME/examples/conf/customTypes to the System/Configuration/Custom Types folder in the EKM
repository.
5. Edit the custom type by selecting the custom type file (Project.type.xml), right-clicking, and selecting
Edit > Custom Type. This will open the Edit Custom Type dialog box. (Figure 7.6: Edit Custom Type Actions (p. 81))
6. In the Icon column, enter /custom/icons/tips.gif for the first row and /custom/icons/ansysIconSmall.gif for the second row.
7. Click OK.
8. Apply and accept the workspace configuration.
9. In the repository, create a new custom folder of type Project and give it a name.
10. Right-click the new custom folder that was added and verify that a new menu item named Custom Actions
appears at the bottom of the context menu. When you right-click the menu item, verify that two submenu
items named Append Description and Set Description are listed, along with their corresponding icons
(tips.gif and ansysIconSmall.gif, respectively).
Verify that the actions are also available in the Action toolbar.
82
Defining Custom Types Using XML
Example: Specifying a Macro that Creates Dependencies Across Properties

The following macro named updateProperties creates dependencies across properties for a custom
type. In the first line, the property partId is set to be disabled if the boolean property exportControlled is true. After that it creates a list of options for the property disciplines. The options
depend on the value of componentType property. You must specify the name of this macro in the
propertyUpdateMacro setting in the Type Attributes tab. See Defining Type Attributes for a Custom
Type (p. 72) for more details.
File listing for updateProperties:
updateProperties(model, properties) {
properties.get("partId").setDisabled(properties.get("exportControlled").getValue());
l = new LinkedList();
l.add("Flow");
l.add("Electromagnetic");
ct = properties.get("componentType").getValue();
if (!ct.equals("Type B")) {
l.add("Thermal");
l.add("Stress");
}
properties.get("disciplines").setOptions(l);
}
Example: Executing a Macro When an Object Is Created

The following macro named initObject sets the description property of an object when it is created.
You must specify the name of this macro in the initalizeMacro setting in the Type Attributes tab.
See Defining Type Attributes for a Custom Type (p. 72) for more details.
initObject(model) {
ekm.startTransaction();
model.setProperty("description", "Set from script during initialization");
ekm.commitTransaction();
}
7.3.2. Editing a Custom Type

To be able to edit a custom type, you must be in restricted configuration mode.
To edit a custom type, right-click it and select Edit > Custom Type from the context menu. The Edit
Custom Type dialog box that opens is essentially the same as the New Custom Type dialog box, except
that you can modify only a single type at a time. For this reason, the Edit Custom Type dialog box
contains the OK button instead of Create & Close and Create & New buttons.
See Defining a New Custom Type (p. 66) for details on how to edit the properties, children, mixins, type
attributes, and actions of a custom type.
7.4. Defining Custom Types Using XML

An alternative way of defining a custom type is to create an XML file in an XML editor. You can specify
the same settings that you would specify if you were defining the custom type using the New > EKM
Type feature (see Defining Custom Types Directly in EKM (p. 66)), with the added flexibility of customizing the new type even further if necessary.
The following are some key points to remember while defining custom types in XML:
The XML file should conform to the schema definition as described in Schema Definition for Custom
Types (p. 84).
83

There can only be one type defined per file.
The name of the XML file must end with the extension: .type.xml.
The name of the XML file should start with the type name. This is not a strict requirement but a good
practice to follow. For example, the name of the XML file for a custom Project type should be
Project.type.xml.
When the XML definition is ready, you can upload it to the /System/Configuration/Custom
Types folder. The upload wizard will automatically recognize the file to be of type EKM Type based
on its file extension.
If you want to edit an existing type in XML, you can first download the desired file, make the changes
using an XML editor, upload it back to EKM and overwrite the existing file. Alternatively, if the changes
are minor and you are comfortable with the XML syntax, you can use the Edit > Content action menu
for the selected type to make the changes directly to the file in EKM.
7.4.1. Schema Definition for Custom Types

The figure below shows a partial listing for types.xsd, the XML schema definition (XSD) used for
defining custom types in EKM. The complete listing is provided in the EKM_HOME/schema folder in
your EKM server installation.
Figure 7.7: Partial Listing of the types.xsd Schema File
xmlns:ekmTypes="http://www.ansys.com/ekm/types"
targetNamespace="http://www.ansys.com/ekm/types">
xmlns:ekmScript="http://www.ansys.com/ekm/script">
<xsd:import namespace="http://www.ansys.com/ekm/script" schemaLocation="script.xsd"/>
<xsd:simpleType name="Version">
<xsd:restriction base="xsd:string">
<xsd:pattern value="[0-9]+(\.[0-9]+)*"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="Constraint">
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="value" type="xsd:string" use="required" />
</xsd:complexType>
<xsd:complexType name="Property">
<xsd:sequence>
<xsd:element name="defaultValue" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="enumeration" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="constraint" type="ekmTypes:Constraint" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="type" use="required">
<xsd:simpleType>
<xsd:enumeration value="Boolean" />
<xsd:enumeration value="Date" />
<xsd:enumeration value="Double" />
<xsd:enumeration value="Long" />
<xsd:enumeration value="String" />
<xsd:enumeration value="Reference" />
</xsd:restriction>
</xsd:simpleType>
84

The file indicates that a custom type file consists of a root element called types that can have one
child element that can be either a type, mixin or extension.
type
This element is used to define a new data type.
extension
This element is used to extend a built-in type.
mixin
This element is used to create sharable groups of children and properties that can be included in
more than one type or extension element. A mixin can have properties or child types as
sub-elements. Child types are used for enforcing an object hierarchy. An extension can have
mixins as sub-elements. A type can have properties, child types, mixins or type attributes as sub-elements. Type attributes are used to specify type-specific attributes such
as applications for extracting metadata or reports. These are primarily used for defining custom file
formats.
You must specify a version attribute for types and mixins. By convention, a version in EKM consists
of three revision numbers: X.Y.Z where X Y and Z are integers that represent the major revision, minor
revision, and patch revision of the type, respectively. All versions start with 1.0.0. You are free to
choose a different version convention that can consist of greater or fewer revision numbers.
7.4.2. Defining Properties Using XML

This section describes how to define properties for a custom type and includes examples of property
definitions.
Property definitions are used to define the metadata that are associated with a custom type. To define
a property, you need to specify the name and type of the property. Property names cannot contain
the following special characters: / \ : [ ] % * ' " |
You can also assign a label to a property. The label can contain any character and is used to display
the property in the user interface. The type of the property must be defined as one of the following:
Boolean, Date, Double, Long, Reference or String. The Boolean type is used for properties
whose value can be either true or false. Date is used for dates. Double is used for real numbers
and Long for integers. Reference can be used for properties whose values reference another object
in EKM. For example, a simulation file can have a reference property called geomFile that is a reference
to a geometry file used in a simulation. String can be used to define strings.
Properties have the following optional attributes:
specifiedBy: The valid values are user and extractor. If extractor is specified, then the
value for this property will be automatically extracted using a metadata extractor application. If user
is specified, then the value for this property will be manually entered by the user. If this attribute is
not given, its value is assumed to be user. Only properties whose specifiedBy attribute is set to
user can be modified by a user in the Edit Properties dialog box in the EKM user interface.
required: The valid values for this attribute are true or false. This attribute is used only when
the value for the specifiedBy attribute is set to user. If the value is true then the user will be
prompted to enter a value for this property whenever an object of the type containing this property
is created. For example, if you define metadata for a new file format with the specifiedBy attribute
set to user and the required attribute set to true, then whenever a file of that format is uploaded,
85

users will be asked to enter values for all the user-defined properties. If the value is false, then
users will not be prompted to enter values when the object is created or the file is uploaded. However,
values can still be modified in the user interface using the Edit Properties dialog box. If this attribute
is not specified, its value is assumed to be false.
multivalued: The valid values for this attribute are true or false. If the value is true, then the
value for the property can be a list of values instead of a single value. If this attribute is not specified,
its value is assumed to be false.
Note
If a date is defined as having a multi-valued property, dates are input separated by
commas:
1/12/1953 3:32 AM, 3/23/1996 12:00 AM
If a single date is input with an internal comma, an error is generated. This is an example of a date format that is incorrect for a multi-valued field:
Feb. 12, 2013 11:08
displayOrder: This value is set when you want the property to appear in a particular order
in the Properties display or in a dialog box when user input is required. Dialog boxes include:
Edit Properties, Edit Type, New Folder, and New Object. This value can be any valid integer.
Properties with lower order are displayed first. If unspecified, the default value is 0, which will
display the property alphabetically by name.
Properties can also have the following child elements:
defaultValue: This element is used for specifying the default value for the property. For multi-valued
properties you can specify more than one default value. If you specify a default value you will need to
ensure that the value is correctly specified for the property type.
Boolean types can only have true or false as valid values. If unspecified, the default value is false.
Date types must have default values in either ISO-8601 format or a format that depends on the locale
of the EKM server.
For ISO-8601, the format is: YYYY-MM-DDThh:mm:ss.sTZD, where hh is two hour digits (00 through
23) and TZD is the time zone designator (Z or +hh:mm or -hh:mm)
2007-11-04T18:30-05:00 for Nov 4, 2007 at 6.30 PM in US Eastern Standard Time
For the English locale, the format is: month/day/year hour:min AM/PM
Example: 11/4/07 6:30 PM for Nov 4, 2007 at 6.30 PM
2/21/2008 8:0 AM for Feb 21, 2008 at 8:00 AM
If unspecified, the default value is the current time on the server.
Double type values can be any valid real number.
Examples: 0.0, 123.456
86

You can also use scientific notation such as 1.235E6 or 1.235E-6. If unspecified, the default
value is 0.0.
Note
Double type is referred to as Real Number in the Custom Type dialog in EKM.
Long types can contain only numbers such as 0, 5, -5 and so on as values. If unspecified the default
value is 0.
Note
Long type is referred to as Integer in the Custom Type dialog in EKM.
Reference types contain the full path to an existing object in EKM as a default value.
Example: /Repository/my-folder/my-file.txt
If unspecified, the default value is an empty string , which denotes a null reference.
String can have any arbitrary text as value. If unspecified, the default value is an empty string .
enumeration: Sometimes you may want users to choose a property value from a list of options. These
options can be specified as an enumeration (that is, an enumerated list) for the property. You can
specify an enumeration for any property type (Double, Integer, String, and so on) except Boolean.
While specifying enumerations, follow the value syntax for the various property types that were described
above.
constraint: This element can be used to put constraints on property values. Constraints are validated
when a user provides property values, and a validation error message is generated if a constraint is violated.
A constraint element has a name and a value attribute. The constraint name must be one of the following:
min: Used for specifying the minimum value for a Double or Long type. The value for this constraint
denotes the minimum value for the property.
max: Used for specifying the maximum value for a Double or Long type. The value for this constraint
denotes the maximum value for the property.
quantity: Used for specifying the unit quantity for a Double type. The value for this constraint
denotes one of the quantities specified in the /System/Configuration/Units.xml file (for example, length, volume, and so on) See Units: Defining and Configuring Using XML (p. 187) for more
details on specifying units.
unit: Used for specifying the unit for a Double type. The value for this constraint denotes one
of the units specified in the /System/Configuration/Units.xml file for the quantity specified
above. This constraint should only be used if the quantity constraint has been used. For example, if
the quantity is length, acceptable unit values are: m, cm, ft, and so on If a quantity is specified
but a unit is not specified, then the chosen unit for this property will be the default unit of the users'
preferred unit system. For example, if the users' preferred unit system is SI, the unit will be m, and if
it is British it will be ft. Thus you should specify the unit constraint only if you want to force the
87

property to always be viewed in the specified unit for all users. See Units: Defining and Configuring
Using XML (p. 187) for more details on specifying units.
baseType: Used for specifying the base type for a Reference type. The value for this constraint
denotes the base type of the referenced object. For example, you can use this constraint to ensure that
a reference always points to an object of type File.
Examples - Property Definitions

This section contains five examples of property definitions in EKM.
version
dimension
revisionStatus
physicalModels
inputFile
Example 7.1: version Property (p. 88) defines a property named version of type String. Because
the specifiedBy value is extractor, this property will be extracted from the file by the metadata
extraction application. Because a label is specified, the property will appear in the user interface as
Version.
Example 7.1: version Property
<property name="version" type="String" specifiedBy="extractor" label="Version" />
Example 7.2: dimension Property (p. 88) defines a property named dimension of type Double. Because
the specifiedBy attribute is not specified, it is assumed that the value will be specified by the user.
Because the required attribute is set to true, users will be prompted to enter the value for this
property when they create the object or upload a file containing this property. A default value of 15.0
is also specified. This property also has min and max constraints specified. This means that the value
for this property should be between the specified range of 10.0 and 20.0.
Example 7.2: dimension Property
<property name="dimension" type="Double" required="true">
<defaultValue>15.0</defaultValue>
<constraint name="min" value="10.0" />
<constraint name="max" value="20.0" />
</property>
Example 7.3: revisionStatus Property (p. 88) defines a property named revisionStatus of type
String that will appear in the user interface as Revision Status. It is a required property that will be
specified by users. This property also has enumerations specified, so users can select only one of
these values: Draft, Released or Obsolete. This property will appear in dialog boxes as a select
menu (or drop-down list).
Example 7.3: revisionStatus Property
<property name="revisionStatus" label="Revision Status" type="String" required="true">
<enumeration>Draft</enumeration>
<enumeration>Released</enumeration>
<enumeration>Obsolete</enumeration>
</property>
88

Example 7.4: physicalModels Property (p. 89) defines a property named physicalModels of type
String that will appear in the user interface as Physical Models. The property value will be automatically extracted. Because the multivalued attribute is set to true, the property can accept more
than one value. Enumerations are specified, and the values must be equal to one of the enumerations.
Example 7.4: physicalModels Property
<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>
Example 7.5: inputFile Property (p. 89) defines a property named inputFile of type Reference. It
is a required property that will be specified by the users. Because the baseType constraint is
specified, the referenced object should be of the same type (or a subtype) of CaeModelFile.
Example 7.5: inputFile Property
<property name="inputFile" type="Reference" required="true">
<constraint name="baseType" value="CaeModelFile" />
</property>
7.4.3. Defining Actions Using XML

In some cases you may want to define actions to be associated with your custom types. These custom
actions will be displayed as additional menus in the action menus of the custom type object in EKM.
Actions may simply execute some commands when they are clicked or they may open up a dialog box
to enable users to specify inputs before commands are executed.
The listing in Example 7.6: Custom Actions (p. 89) shows a type definition that also defines some custom
actions. The XML code related to the action definition is contained within <actions> and </actions>.
This example shows how two action menus Append Description and Set Description are added to
the Project custom type. These action menus are added to a new and common parent menu called
Custom Actions. So, in addition to the other built-in action menus (such as Delete, Edit, Help, and
so on) you will now see another menu called Custom Actions that will contain two submenus: Append
Description and Set Description. When the Append Description menu is clicked, it does not open a
dialog box but simply appends the current time stamp to the Projects description. When the Set Description menu is clicked, it opens a dialog box that displays the current description, and enables you
to enter a new description. The description entered is then applied to the Project when the dialog box
is submitted. The user interface files for the dialog box are stored in a folder named set-project-description within the resources folder (which is typically EKM_HOME/conf/resources unless its location
has been changed in the ekm.xml file).
Example 7.6: Custom Actions
<type name="Project" extends="Container" version="1.0.0">
<properties>
<property name="componentType" label="Component Type"
type="String" required="true">
<enumeration>Type A</enumeration>
<enumeration>Type B</enumeration>
<enumeration>Type C</enumeration>
</property>
<property name="disciplines" label="Disciplines"
type="String" required="true" multivalued="true">
<enumeration>Flow</enumeration>
89

<enumeration>Electromagnetic</enumeration>
</property>
<property name="partId" label="Part Id" type="Long" required="true">
<constraint name="min" value="0" />
</property>
<property name="exportControlled" label="Export Controlled?"
type="Boolean" required="true"/>
<property name="dateOfIssue" label="Date Of Issue"
type="Date" required="true"/>
</properties>
<children>
<child name="Requirements" occurs="required" type="Folder"/>
<child name="Common Files" occurs="required" type="Folder"/>
<child name="" occurs="list" type="Folder"/>
<child name="Reports" occurs="required" type="Folder"/>
</children>
<actions>
<script>
appendDescription(object, dialog) {
description = object.getProperty("description");
time = Calendar.getInstance().getTime().toString();
object.setProperty("description", description+", added at: "+time);
}
setDescription(dialog) {
object = dialog.getObject();
object.setProperty("description", dialog.getVars().get("description").getValue());
}
setDescriptionDialog(object, dialog) {
dialog.addStep("Set Description",
"/custom/set-project-description/set-description.xhtml",
"setDescription");
dialog.addVar("description", dialog.VARIABLE_TYPE_STRING,
description, false);
}
</script>
<action name="Custom Actions/Append Description" icon="/custom/icons/tips.gif"
macro="appendDescription" permissions="modify" />
<action name="Custom Actions/Set Description" icon="/custom/icons/ansysIconSmall.gif"
macro="setDescriptionDialog" permissions="modify" />
</actions></type>
As shown in the code in Example 7.6: Custom Actions (p. 89), all actions related to a type must be
defined within the actions element. This element contains a script element and any number of
action elements. The script element is used to define macros that are associated with the action.
See the chapter on Defining Macros and Custom Dialog Boxes in the EKM User's Guide for details on
scripting and macro definition. The action element defines each action associated with the type and
has the following attributes:
name: Specifies the name of the action menu and any parent menus. The parent menus are separated by
a slash /. Parent menus will be created if they do not already exist. The name of the parent menu can
also be an existing menu (such as Edit) and in this case, the new menu will be added to the existing
parent menu. You can specify the name of the parent menu only in a single language. This means that if
you have users in multiple locales, it will be better to place the custom actions in a new parent menu,
rather than an existing one.
macro: Specifies the name of the macro that will be called when the menu is clicked. See the chapter on
Defining Macros and Custom Dialog Boxes in the EKM User's Guide for details on macro definition and the
EKM scripting interface. Typically, the macro will be defined in the script element before the action
90
Custom Type Examples

definition, but you can also define it in the common library of macros that are loaded by EKM at startup.
The macro must take the following two arguments:
an instance of ModelObjectInterface that specifies the object on which the action will be performed
an instance of DialogInterface that specifies the dialog box that will be opened. If the action does
not require a dialog box to be opened, then you can ignore this argument in the macro body. The
macro named appendDescription in the above listing is an example of this type of macro. If the
action requires a dialog box to be displayed, the macro body should define the steps that are part of
the dialog box, using the addStep() method of the DialogInterface. The macro named setDescriptionDialog in the listing is an example of this type of macro.
permissions: Specifies the permissions that a user must have in order to view this action on the action
menu. The permitted permission values are:
access: Specifies who can access (or view) the object.
create: Specifies who can add a child to a folder object.
delete: Specifies who can delete the object.
modify: Specifies who can modify the object.
lifecycle: Specifies who can perform lifecycle operations such as promote and demote.
download: Specifies who can download a file or folder object.
fullControl: Specifies who has full control over the object. Full control means that all permissions
are available, including the ability to change permissions.
icon: Specifies the path to the image file that will be used to represent the icon. The convention used
for the path is: /custom/<relative location of the file in EKM_HOME/conf/resources
folder>, which is the location of the EKM_HOME/conf/resources folder. For example, suppose you
have added an icon called myicon.gif to your EKM_HOME/conf/resources/icons folder. The
path you would specify for icon would then be: /custom/icons/myicon.gif.
To specify icons for a parent menu that is not associated with any action, you can add a new action
and just provide an icon and not supply a macro. In the Project example shown above, you can create
a new action named Custom Actions and supply it with an icon. Once configured, the icon will
be displayed along with the label for the new menu category.
7.5. Custom Type Examples

The following sections contain examples of custom types that you can define in EKM. These include
custom folder structures, analysis projects, file formats, and extensions to built-in types.
7.5.1. Custom Folder Structures

You can define a custom folder structure to control how your data is organized in EKM. It can provide
a standard way of naming and organizing files and folders. Custom folder structure data types specify
the name, type, and occurrence (single or multiple) of child objects and enable you to control how new
objects are added to a particular type. All custom folders should extend the Container type, or a subtype
of Container.
91

Let's look at how you can define a custom folder structure by means of an example.
Suppose you want all of your simulation projects to be stored in a common place in EKM, and you want
each project to organize the data in three folders: Requirements, Common Files, and Reports. Let's say
you also want users to create new folders for each simulation they perform for the project, and furthermore, you want users to enter some required attributes when they start a new project.
The first step in the process is to define a new type named ProjectContainer (Example 7.7: Defining a
Project Container Type (p. 92)). It will appear in the user interface as Project Container (its localized
name) with version 1.0.0. It extends the built-in Container type. The listing below shows the XML
code fragment.
Example 7.7: Defining a Project Container Type
<type name="ProjectContainer" extends="Container" label="Project Container" version="1.0.0">
<children>
<child name="" occurs="list" type="Project"/>
</children>
</type>
The ProjectContainer type can only have children of type Project, where Project is another
custom type that we will define shortly. The occurs attribute of the child element dictates whether
a single instance or multiple instances of the child type are allowed. In this case, occurs is set to list
which means that multiple instances of Project type can be added to a ProjectContainer. The
other valid values for occurs are required and optional. The required value is used if only
one instance of the child is allowed, and this instance must always exist. The optional value is used
if the child may or may not exist. For custom types, you should only use required or list values.
The name attribute specifies the name of the child. It is ignored and can be set to an empty string if
occurs is set to list. If occurs is set to required then the child will be automatically created
when the parent object is created. You therefore need to provide a valid name for the child. The child
name can not contain the following special characters:
/ \ : [ ] % * ' " | > < ?
Now that we have created the Project Container type, we will define a new Project type. The XML
code listing shown in Example 7.8: Defining a Project Type (p. 92) is for a new Project type. It extends
the built-in type Container and defines some required user-defined properties: componentType,
disciplines, partId, exportControlled and dateOfIssue. The user who creates a project
in EKM by will be prompted to enter values for these properties. This type also has some required
children: Requirements, CommonFiles and Reports that are all of type Folder. When a Project
instance is created, these required children are also created automatically at the same time. You cannot
delete a required child. The Project type also enables you to create more instances of Folder type
for the various simulations to be performed in the project. Some custom actions are also specified for
the Project type. These were explained in the previous section.
In EKM you can use the New > Folder action menu in any folder to create an instance of a custom
folder that is allowed in the parent folder. If there are any required user-defined properties associated
with the type, you will be prompted to enter their values at the time of object creation in the New
Folder dialog box. All of the necessary user interface components will be automatically generated by
EKM.
Example 7.8: Defining a Project Type
<type name="Project" extends="Container" version="1.0.0">
<properties>
<property name="componentType" label="Component Type" type="String"
92

required="true">
<enumeration>Type A</enumeration>
<enumeration>Type B</enumeration>
<enumeration>Type C</enumeration>
</property>
<property name="disciplines" label="Disciplines" type="String"
required="true" multivalued="true">
<enumeration>Flow</enumeration>
<enumeration>Electromagnetic</enumeration>
</property>
<property name="partId" label="Part Id" type="Long" required="true">
<constraint name="min" value="0" />
</property>
<property name="exportControlled" label="Export Controlled?"
type="Boolean" required="true"/>
<property name="dateOfIssue" label="Date Of Issue" type="Date" required="true"/>
</properties>
<children>
<child name="Requirements" occurs="required" type="Folder"/>
<child name="Common Files" occurs="required" type="Folder"/>
<child name="" occurs="list" type="Folder"/>
<child name="Reports" occurs="required" type="Folder"/>
</children>
<actions>
<script>
appendDescription(object, dialog) {
time = Calendar.getInstance().getTime().toString();
object.setProperty("description", description+", added at: "+time);
}
setDescription(dialog) {
object = dialog.getObject();
object.setProperty("description", dialog.getVars().get("description").getValue());
}
setDescriptionDialog(object, dialog) {
dialog.addStep("Set Description",
"/custom/set-project-description/set-description.xhtml",
"setDescription");
dialog.addVar("description", dialog.VARIABLE_TYPE_STRING, description, false);
}
</script>
<action name="Custom Actions/Append Description" macro="appendDescription"
permissions=" modify"/>
<action name="Custom Actions/Set Description" macro="setDescriptionDialog"
permissions=" modify"/>
</actions>
</type>
7.5.2. Custom Analysis Projects

Analysis projects are specialized containers that not only store all data pertaining to an analysis, but also
manage the input and output dependencies of the analysis and enable it to be automatically executed
if it becomes out-of-date. Users can create new instances of analysis project in EKM and provide information about the location of inputs and outputs, and how to execute the analysis. If you do not want
users to manually enter this information every time they create a project, you can define a custom
analysis project type and specify this information in the type definition.
Custom analysis projects are defined by extending the Analysis Project built-in type. You can then use
the following type attributes to specify input, output and execution information:
93

inputPattern: Specifies the path to an input file or folder containing input files. The path is relative
to the analysis project and can contain wildcards (* for any number of any character and ? for a
single occurrence of any character). Any number of inputPattern type attributes can be specified.
outputPattern: Specifies the path to an output file or folder containing output files. The path is
relative to the analysis project and can contain wildcards. Any number of outputPattern type
attributes can be specified.
executionWorkflow: Specifies the full path of the workflow that will be executed when the analysis project is updated. The workflow should not have any required variables.
executionWorkflowVar: Specifies a reference variable defined in the workflow that will be initialized with the instance of the analysis project that starts the workflow. This is used to reference the
analysis project in the workflow.
Below is an example of a custom analysis project type definition.
Example 7.9: Defining a Custom Analysis Project Type
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ansys.com/ekm/types ../../schema/types.xsd">
<type name="TestAnalysis" extends="AnalysisContainer" version="1.0.0">
<children>
<child name="inputs" occurs="required" type="Folder" />
<child name="outputs" occurs="required" type="Folder" />
</children>
<typeAttributes>
<typeAttribute name="inputPattern" value="inputs/*" />
<typeAttribute name="outputPattern" value="outputs/*" />
</typeAttributes>
</type>
</ekmTypes:types>
The name of the custom type in the listing is TestAnalysis. It extends the AnalysisContainer
type and defines two children: inputs and outputs of type Folder. It specifies the input pattern
to be inputs/*, which means that all files in the inputs subfolder will be treated as inputs of the
analysis. It specifies the output pattern to be outputs/*, which means that all files in the outputs
subfolder will be treated as outputs of the analysis.
You can see how these sample files are used in Tutorial: Creating a Custom Analysis Project, located at
the end of the Working with Analysis Projects chapter in the Users Guide.
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.
94

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>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 (p. 95), 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 depends
on the base type that you are extending. See Defining Type Attributes for a Custom Type (p. 72) 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.8: ModelAttribute mixin Example (p. 95)). This mixin defines two userdefined 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.8: ModelAttribute mixin Example
<mixin name="ModelAttributes" version="1.0.0">
<properties>
<property name="revisionStatus" label="Revision Status"
<enumeration>Draft</enumeration>
type="String" required="true">
95

<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.9: metadata.xsd Schema Definition Listing (p. 96). The complete listing is included in the EKM_HOME/schema
folder.
Figure 7.9: meta-data.xsd Schema Definition Listing
targetNamespace="http://www.ansys.com/ekm/metaData"
xmlns:ekmMetaData="http://www.ansys.com/ekm/metaData">
<xsd:complexType name="MetaData">
</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.
96

The value is the extracted value of that property. Multi-valued properties can be specified in a commaseparated manner.
Figure 7.10: Sample Metadata File for Custom AcmeSimulationFile Type (p. 97) 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.10: 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.11: Listing of report.xsd Schema Definition (p. 97). The complete listing is included in the EKM_HOME/schema folder.
Figure 7.11: Listing of report.xsd Schema Definition
targetNamespace="http://www.ansys.com/ekm/report"
xmlns:ekmReport="http://www.ansys.com/ekm/report">
<xsd:complexType name="Image">
<xsd:attribute name="src" type="xsd:string" use="required" />
</xsd:complexType>
<xsd:complexType name="Link">
<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"
97

type="xsd:string" use="optional" />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
<xsd:complexType name="Column">
<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="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:complexType>
<xsd:element name="section" type="ekmReport:Section" />
</xsd:schema>
Figure 7.11: Listing of report.xsd Schema Definition (p. 97) 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.12: 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
98
Extending Built-in Types

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.13: Sample Report File for AcmeSimulationFile Type (p. 99) 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.13: 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">
<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>
7.6. Extending Built-in Types

In some situations you may want to extend the properties (or children) of a built-in type rather than
create a new type. For example, you may want to simply add some user-defined properties or actions
to a built-in type. You can achieve this by defining an extension. To define an extension that adds
properties to a built-in type, you will first need to define one or more mixins that define the properties
or children that you want to add to the built-in type, and then reference the mixins in the extension.
You can also define custom actions in an extension similar to how you define it for a custom type.
The listing in Example 7.11: Extending a Fluent Case Built-in Type (p. 99) shows an example that extends
the FluentCase built-in type. It creates an extension named AcmeFluentExtension that extends
FluentCase. The ModelAttributes mixin was defined in a previous example (see Figure 7.8: ModelAttribute mixin Example (p. 95)). ModelAttributes defines user-defined properties that a user will
be prompted to enter values for, when a file of this type is uploaded to EKM.
Example 7.11: Extending a Fluent Case Built-in Type
<extension name="AcmeFluentExtension" extends="FluentCase">
<mixins>
<mixin>ModelAttributes</mixin>
</mixins>
</extension>
7.6.1. Migrating Built-in extensions or Custom Types

You can add extensions to built-in types or new custom types using the New > EKM Type action
available in /System/Configuration/Custom Types. You can then use the typeSettings
setting to set or modify the built-in or custom type by editing the WorkspaceConfig.xml file in the
/System/Configuration folder.
If you later need to migrate your workspace, you may perform the migration without having performed
the step of editing the WorkspaceConfig.xml. If this happens, data extraction will fail even if you
subsequently edit the WorkspaceConfig.xml file and attempt to migrate again. The workaround
in the case of a failed data extraction is to subsequently extract metadata using the Extract Data tool.
See Extracting Data On Demand in the EKM Users Guide for details.
99
100
Chapter 8: Defining EKM Servers, Queues, and External Applications

Every EKM Server has a built-in /System/Servers folder in its file structure. This folder contains a
built-in job submission server named Master, and is also the folder where you would install a cache
server if using one.
The built-in Master server contains the installed Data Extraction Queue named EKM Server, and
may contain any number of job submission queues. A job submission queue can be batch or interactive.
For more information about queues, see Types of Queues (p. 104).
Each queue contains application definition files (*.app.xml files) that will launch external applications
from EKM.
EKM launches external applications for a variety of tasks, including:
Extracting metadata, images and reports from supported simulation files
Executing batch processes in a job, workflow, or custom application
This chapter describes how to create and define servers, queues, and external applications in EKM.
However, it does not explain how to modify process-related configuration settings in the ekm.xml file
that may be required for your system. These are listed below.
localProcess: Specifies settings for applications that are run locally on the EKM server.
remoteProcess: Specifies settings for applications that are run remotely through ANSYS Remote
Simulation Manager (RSM), or through EnginFrame. This is required only if you want to configure
EKM to use RSM for remote execution, or if you want to provide users with the ability to run interactive
jobs from EKM.
customRetentionSetting: Specifies the retention policy for a Job object.
scheduledTasks: Specifies settings for the batchJobMonitor task.
For details on these settings, see General Server Settings
Specific usages of external applications are covered in detail in other chapters in this Administration
Guide and in the Users Guide. Refer to Defining Workflows in EKM Studio in the Users Guide for using
external applications in workflows and batch processes.
The high-level steps required to configure EKM for launching external applications are listed below.
Specify the process-related configuration settings in the ekm.xml file (see General Server Settings).
For batch jobs, install and configure RSM as explained in Installing and Configuring RSM (p. 120).
For interactive jobs, install and configure EnginFrame as explained in Installing and Configuring EnginFrame in the EKM Installation Guide.
101
Defining EKM Servers, Queues, and External Applications

Create batch job submission queues in EKM that correspond to RSM queues, and interactive job
submission queues that correspond to queues defined in the ekm.xml file. This is done automatically
at startup. See Synchronizing Job Submission Queues (p. 106).
Set permissions on queues to control which users may submit jobs to them (see Editing Permissions).
Define applications in the desired queue as explained in Defining External Applications (p. 110).
This chapter presents information on how to set up EKM servers, queues, and external applications.
Topics include:
8.1. Adding EKM Servers
8.2. Defining EKM Cache Servers
8.3. Defining External Applications
8.4. Running Batch Jobs in EKM
8.5. Installing and Configuring RSM
8.6. Running Interactive Jobs in EKM
8.1. Adding EKM Servers

There are two types of servers in EKM:
Job Submission Server
Every EKM Server has a built-in EKM Server object of type JobSubmissionServer named
Master. The Master server is located in the /System/Servers folder.
The Master server is where EKM is running, and is defined by the host name and port that EKM is
running on. This server will be used to submit all batch jobs from EKM to RSM, and all interactive
jobs from EKM to EnginFrame.
Cache Server
Cache Servers may be added to represent instances of EKM running on other machines and can be
used when you want to assign another EKM server as a cache server for some users. They have an
object type of CacheServer. You may not submit batch jobs to these remote EKM servers. All jobs
must be submitted using the Master server.
8.2. Defining EKM Cache Servers

To enable caching in EKM, you must create a server definition in the EKM Master Server that represents
the EKM Cache Server that will cache the data. See Distributed Servers and Caching (p. 4) for information on setting up a cache server.
8.2.1. Creating a New EKM Cache Server

To create a new EKM Cache Server:
1.
102
Select /System/Servers, right-click and select New > Cache Server from the context menu. This
opens the New EKM Cache Server dialog box.
Defining EKM Cache Servers

Figure 8.1: New EKM Cache Server Dialog Box
2.
Enter a name for the new server that is to be added (for example, RemoteServer1). The server name
is an identifier used by EKM to refer to that server.
3.
Enter the fully qualified host name of the server (for example, server1.domain.com).
4.
Enter the port number for the port that the EKM Server on that host is running on.
5.
Select the users to assign to this cache server. All selected users will make use of this cache server for
their file transfers. You may also assign the cache server for a user when creating a new user. See Adding
and Modifying Users (p. 8).
6.
Click OK. A new server of type Cache Server is created in the Servers folder.
8.2.2. Editing an Existing EKM Cache Server

To edit an existing EKM Cache Server, right-click an existing Cache Server under /System/Servers
and select Edit > EKM Cache Server. This opens the Edit EKM Cache Server dialog box:
103

Figure 8.2: Edit EKM Cache Server Dialog Box
8.2.3. Types of Queues

All queues are defined under the Master EKM Server, which is located at /System/Servers/Master.
104

Figure 8.3: Sample Queues on Master Server
There are three types of queues in EKM:

Data Extraction Queue
EKM installs with a Data Extraction Queue at /System/Servers/Master/EKM Server. There
can only be one Data Extraction Queue defined. This queue specifies a set of applications that can
be run directly on the EKM Server and are used for extracting metadata, images and reports from
supported simulation files (see Predefined External Applications (p. 110)).
Batch Job Submission Queues
These queues are used to run batch jobs in EKM. In order to run batch jobs, there must be a Batch
Job Submission Queue for every queue in RSM that you want to use. The name of the EKM queue
should match the name of a queue defined in RSM. Batch jobs submitted to the EKM queue will be
sent to the queue of the same name in RSM.
To automate the process of creating batch job submission queues, EKM provides a Synchronize
Queues action for the Master server. This action will automatically create queues in EKMs /System/Servers/Master folder for all queues defined in RSM. This is the only way to create batch
queues in EKM, and is covered in Synchronizing Job Submission Queues (p. 106).
Interactive Job Submission Queues
These queues are used to run interactive jobs in EKM. Interactive queues are defined in the ekm.xml
file. Queues defined in this file will be automatically created in the /System/Servers/Master
folder when the EKM server starts. If you accidentally delete an interactive queue, you can use the
Synchronize Queues action to restore it.
8.2.4. Managing Queues

This section describes:
8.2.4.1. Synchronizing Job Submission Queues
8.2.4.2. Defining Job Submission Queue Settings
105
8.2.4.1. Synchronizing Job Submission Queues

The first time that the EKM server is started, it will attempt to find queues defined in RSM and automatically create batch job submission queues of the same name in EKM under /System/Servers/Master.
EKM will also detect interactive queues defined in the ekm.xml file and add them to the same folder.
This automatic synchronization will occur every time that the EKM server is subsequently started to
keep EKM up-to-date with the settings defined in RSM and the ekm.xml file.
For batch job submission queues, the synchronization process works as follows:
1. EKM contacts RSM so that it can compare the queues defined in RSM with the Batch Job Submission
Queues defined in EKM in the /System/Servers/Master folder.
2. If there are any queues in RSM that are not defined in EKM under /System/Servers/Master, they
will be created in EKM.
3. If a queue is defined in EKM but is not defined in RSM, a notConfigured status flag is set for the
queue in EKM. In /System/Servers/Master, you will see a warning icon
the corresponding tool tip will indicate" Queue not configured in RSM."
next to the queue and
Important
Any queues that are marked as notConfigured will be unavailable for job submission.
Users will not be able to send jobs to these queues as they do not exist in RSM. If this queue
is later defined in RSM and you synchronize from EKM again, the notConfigured status
flag will be cleared and the queue will be available for job submission.
Note
During synchronization, the EKM Server Data Extraction Queue is ignored (see Types of
Queues (p. 104)). Only Job Submission Queues are synchronized.
During startup, the EKM server will synchronize the queues for all workspaces. Each workspace
stores its own queue definitions, so they all will be synchronized.
RSM always defines a queue named Local that is mapped to an RSM compute server running
on the host "localhost", so you can always expect to see a queue named Local defined in
EKM.
In addition to the synchronization performed at startup, an EKM administrator may synchronize queues
at any time from the EKM interface. This may be necessary, for example, if a queue has been accidentally
deleted in the current session. Unlike the automatic synchronization performed at startup, on-demand
synchronization only synchronizes the queues in the current workspace.
To synchronize queues for the workspace you are currently logged into, do the following:
1.
In the navigation pane, select the following folder: /System/Servers/Master.
2.
Right-click and select Synchronize Queues, or click the Synchronize Queues button on the toolbar.
This displays a dialog reporting the progress of the synchronization.
106

Figure 8.4: Status of On-demand Queue Synchronization
In this example, it reports that three queues were processed.
8.2.4.2. Defining Job Submission Queue Settings

When defining a batch or interactive job submission queue (see Types of Queues (p. 104)), there are
several properties that you can set to determine how jobs are handled in that queue.
To define a job submission queues settings:
1.
In the navigation pane, go to /System/Servers/Master and select the queue whose settings you
would like to define.
2.
Right-click and select Edit > Job Submission Settings from the context menu. The Edit Job Submission
Settings dialog box appears (Figure 8.5: Edit Job Submission Settings Dialog Box (p. 108)).
107

Figure 8.5: Edit Job Submission Settings Dialog Box
3.
Define the job submission settings. These are described below.

Job Submission System
Select the underlying job submission system to which this queue is mapped that is, the scheduler
that will run the jobs.
Choices for batch job schedulers include:
Native RSM RSM itself is the batch system (this is the default value)
IBM LSF
Altair PBS
SGE
Windows HPC
Note that in order to run jobs on the RSM compute server, the RSM server must be running
on a 64-bit Linux system. Also, the VNC password must be set.
Choices for interactive job schedulers include:
108

IBM LSF
Adaptive Computing MOAB
NICE Neutro
Altair PBS
Torque
Automatically load default application definitions
Enable this check box if you want to automatically load the default applications defined in the
EKM_HOME/conf/jobSubmissionApplications folder. This check box is enabled by default
if you have not added any external applications to the queue. Make sure that you specify the Operating system of the queue so that the appropriate applications are loaded from either the linx64
or winx64 sub-folder under the jobSubmissionApplications folder.
Operating system of the queue
If you have enabled the Automatically load default application definitions check box, then you
will need to specify the operation system of the queue so that the appropriate job submission applications are loaded. Selecting the Windows (64 Bit) operating system option will load applications
from the EKM_HOME/conf/jobSubmissionApplications/winx64 folder. Selecting the
Linux (64 Bit) option will load applications from the EKM_HOME/conf/jobSubmissionApplications/linx64 folder.
Note
The operating system of interactive queues is specified in the ekm.xml file, and is
therefore predetermined and non-selectable in the Edit Job Submission Settings
dialog box.
Domain name for all user accounts
On Windows systems, enter an operating system domain name to be used for all user accounts that
will submit batch jobs to this queue. This name will be added to the beginning all the account
names mapped to this queue when the job is submitted to RSM. For example, if you specify
MYDOMAIN for the queue domain name, and the account name for one of the EKM users is
joe_smith, then the actual account name sent to RSM will be MYDOMAIN\joe_smith. If you
do not enter a domain name here, you will need to manually add a domain name to the beginning
of every account name listed.
Specify the account name of EKM users
The dialog displays all EKM users who have access to the queue. When an EKM user submits a batch
job to RSM, EKM notifies RSM of the actual operating system account to use to run the job. Similarly,
when you run an interactive job, EKM notifies EnginFrame of the account to use when creating the
interactive session. You can specify the Account Name to be used for each EKM user that has access
to the queue. Unless changed by the administrator, the Account Name will be the same as the
EKM User Name.
If you have already defined account names in another queue and would like to use them in
the current queue, click the browse button next to the Get account names from another
queue option, then select the desired queue from the /System/Servers/Master folder.
Then, click Load to copy the account names defined in that queue into the current queue.
109

4.
When you are finished defining settings, click OK.
8.3. Defining External Applications

External Application objects are used to represent applications that are external to EKM, and that can
be run by EKM. External applications are stored as XML-formatted files in EKM and are always defined
and associated with a particular Queue. Queues are used to specify different locations where applications
are run.
Important
Any application that you define must be accessible on all compute hosts where the batch
job may ultimately run. For example, if you define an application for a queue named
TestQueue, and RSM has two compute servers available to run jobs submitted to TestQueue,
then both of these compute servers need to be able to access the application that will be
run.
When you select a queue in the navigation pane, any external applications associated with that queue
are listed in the file list pane. In this way the queue object acts like a folder in the navigation pane, and
that folder can contain external application files. For example, if there were an application named
myApp.app.xml that was associated with a queue named MyQueue1 under the Master server, the
path to that application would be:
/System/Servers/Master/MyQueue1/myApp.app.xml
Important
All Queues and External Applications must be defined under /System/Servers/Master.
Cache Servers cannot contain these definitions as they do not support running applications.
8.3.1. Predefined External Applications

For your convenience, EKM comes with various predefined External Application definitions. These are
definitions for external applications that can be launched by EKM when data is extracted from simulation
files, or when jobs are run from EKM. External applications are directly associated with Data Extraction
and Job Submission queues. Predefined applications are located in two different folders under
EKM_HOME/conf/.
The predefined applications in the EKM_HOME/conf/applications folder are loaded into the Data
Extraction queue at /System/Servers/Master/EKM Server the very first time that EKM is started.
When defining settings for a Job Submission queue, you can choose to automatically load the predefined
applications in the EKM_HOME/conf/jobSubmissionApplications folder into the queue that
you are defining.
Some external applications (such as graph generation) are bundled with EKM, while other applications
are required to be installed on the server. See the EKM Installation Guide for a complete list of applications
that require installation. The AWP_ROOT150 environment variable must be correctly set in order to run
these installed applications. This environment variable is set automatically on Windows systems. To
learn how to set it on Linux systems, see Set the Location of ANSYS 15.0 Applications (Linux).
The following is a list of all predefined applications in EKM:
110
Defining External Applications

ansys.app.xml: This is the ANSYS executable and is used for extracting metadata and reports
from Mechanical APDL files. You will need to specify the correct location of this application on the
server.
caeinterface.app.xml: This application is bundled within EKM and is used to extract metadata
and reports from some non-ANSYS file formats such as Abaqus and Nastran. You do not need to
configure this application.
cfx5dfile.app.xml: This application is part of the CFX installation and is used for extracting
metadata and reports from CFX files. You will need to specify the correct location of this application
on the server.
cfx5post.app.xml: This is the CFD Post executable and is used for extracting images from CFX
files. You will need to specify the correct location of this application on the server.
cfx5pre.app.xml: This application is part of the CFX installation and is used for extracting images
from CFX files. You will need to specify the correct location of this application on the server.
dot.app.xml: This application is bundled with EKM and is used to generate workflow and process
flow graphs. You do not need to configure this application.
extractCaxImage.app.xml: This application is used to extract VCollabs CAX file from simulation
files for 3D visualization. In order to use this application you need to have VCollab installed and the
VMOVE_EXEC_PATH environment variable defined. See Installing VCollab and Configuring EKM for
3D Visualization for more details.
fluent.app.xml: This is the Fluent executable and is used for extracting reports from Fluent files.
You must specify the correct location of this application on the server. You will also need to specify
the appropriate command line parameters for running this application in the background. The
hidden parameter is used for running it in the background on a Windows server. You will need to
change this parameter to g for Linux. The post parameter is used for running Fluent in postprocessing mode, only. You will need to remove this parameter or create a new application definition if
you need to run the Fluent solver.
jython.app.xml: This application is bundled with EKM and is used to execute Python scripts. You
do not need to configure this application.
polyflowReport.app.xml: This application is bundled with EKM and is used to extract reports
from Polyflow files. You dont need to configure this application.
workbench.app.xml: This is the Workbench executable that is used for extracting metadata and
reports from Mechanical Database (.dsdb, .mechdb, .mechdat) and Workbench Project Archive
(.wbpz) files.
Important
You should not edit the files in the EKM_HOME/conf/applications folder because the
changes will not be applied to instances of those files in EKM. If you want to make changes
111

to an application definition, you should do so only from within EKM using either the Edit >
External Application or Edit > Content tool.
Important
You should not change the application key name for any of the predefined applications. If
the key name is changed, EKM will be unable to find the application.
The next sections, Defining External Applications Using XML (p. 116) and Defining External Applications
Directly in EKM (p. 112), describe two methods of creating your own external application definitions.
8.3.2. Defining External Applications Directly in EKM

This section presents information on how to define external applications directly in EKM. See Defining
External Applications Using XML (p. 116) if you want to define an application using XML.
8.3.2.1. Creating a New External Application

To create a new application directly in EKM:
1.
In the navigation pane, go to /System/Servers/Master and select the queue with which you want
to associate the external application.
2.
Right-click and select New > External Application from the context menu. This will open the New
External Application dialog box, shown below.
112

Figure 8.6: New External Application Dialog Box
3.
Enter the Application key, Application name, Execution path, 0 or more Command line parameters,
0 or more Environment variables and optional Job submission options. Click the Add buttons to
add more parameters or environment variables. Environment variables are specified as a name and
value. Click the Remove buttons to remove parameters or environment variables.
Important
It is highly recommended that you specify a different Application key and Application
name in each external application file that you define. (Do not use the same key or label
in more than one file.) This ensures that applications are uniquely identified when they
are displayed in a list, and ensures that the correct execution path is used.
On Windows compute servers, any parameter that contains a space (for example, a file
path) should be enclosed in double quotation marks to ensure that it is treated as a
single parameter. Otherwise, the job may fail.
113

Application key
A string that identifies the application. For example, when you execute a batch process in a workflow,
custom application or analysis project, the Application key name that you specify here is used to
execute the application.
Application name
The name that will be used to identify the application in the interface (for example, in the Execute
Job dialog box, in the Job Details view, or the Edit Batch Node dialog box).
Execution path
The full path to the application executable on your local file system.
Command line parameters
Parameters that can be added to the command that will be run.
Environment variables
Variables that can be added and will be defined when the command is run. These variables only
exist while the command is executing.
Job submission options
Settings relating to the batch submission system. Leave this blank if you do not have any options
to specify.
4.
When you have finished defining your new external application, click Create & Close to create the application and exit the dialog box, or Create & New to continue to create more applications.
The application will be automatically saved as an XML file with the file extension .app.xml in the
queues folder, with the name that is specified for the Application key. In our example, the application file myAppKey.app.xml is saved as: /System/Servers/Master/Local/myAppKey.app.xml
8.3.2.2. Editing an External Application Definition

To edit an existing application definition using a dialog:
1.
In the navigation pane, select the queue with which the application is associated. Queues are located
in the /System/Servers/Master folder.
2.
Right-click and select Edit > External Application from the context menu. This will open the Edit External Application dialog box.
114

Figure 8.7: Edit External Application Dialog Box
3.
Make any changes to the Application key, Application name, Execution path, Command line parameters, Environment variables and Job submission options and then click OK to save your changes.
Important
On Windows compute servers, any parameter that contains a space (for example, a file path)
should be enclosed in double quotation marks to ensure that it is treated as a single
parameter. Otherwise, the job may fail.
8.3.2.3. Editing an External Application Using XML

You can edit the definition of an external application by editing the content of the XML file. You can
do this directly within EKM.
1.
In the navigation pane, select the queue with which the application is associated. Queues are located
in the /System/Servers/Master folder.
2.
Right-click and select Edit > Content from the context menu. This will open the Edit Content dialog
box.
115

Figure 8.8: Edit Content Dialog Box
3.
Make the desired changes to the file content, and then click OK to save your changes.
If you want, you can also download the file first, modify it in an XML or text editor, and then upload
the file and overwrite the existing application definition with the modified one.
8.3.3. Defining External Applications Using XML

This section presents information on how you can define external applications using XML. See Defining
External Applications Directly in EKM (p. 112) if you want to define an application using a dialog box in
EKM.
8.3.3.1. Schema Definition for Applications

application.xsd defines the format for .app.xml (or .appxml) files that are used to define the
external applications in EKM. The listing for the application.xsd schema definition file is shown
in Figure 8.9: File listing for application.xsd Schema File (p. 117). A full listing is provided in the
EKM_HOME/schema folder.
application.xsd consists of a root element named applications that contains one application element. The application element consists of a key, execPath, 0 or more param elements, 0 or more
env elements and an optional nativeOptions element.
116

key
Used to identify the application. For example, a batch node in a workflow will use the key to refer to a
particular external application.
label
The name that will be used to identify the application in the interface (for example, in the Execute Job
dialog box, or in the Job Details view).
execPath
Defines the full path of the application executable. This must correspond to the fully qualified application
path on the execution host.
param
Can be used to specify command line parameters. Each command line parameters is defined separately.
You should not define just a single parameter and use space as a separator for multiple parameters.
env
Can be used for environment variables. Each env element consists of a name and value attribute.
nativeOptions
Specifies any batch submission system-specific options. This is useful if you integrate with a queuing or
batch submission system such as LSF and you want to specify some additional parameters for controlling
the job execution. You can use the nativeOptions element to control the resources granted to a
batch job (such as OS type, number of nodes, minimum RAM, and so on). For example, for an SGE system,
you could define:
<nativeOptions>-hard -l arch="lx24 amd64"</nativeOptions>
to specify that the job can run only on machines matching that architecture.
Figure 8.9: File listing for application.xsd Schema File
targetNamespace="http://www.ansys.com/ekm/application"
xmlns:ekmApplication="http://www.ansys.com/ekm/application">
<xsd:complexType name="NameValue">
</xsd:complexType>
<xsd:complexType name="Application">
<xsd:sequence>
<xsd:element name="key" type="xsd:string"/>
<xsd:element name="label" type="xsd:string" minOccurs="0"/>
<xsd:element name="execPath" type="xsd:string"/>
<xsd:element name="param" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="env" type="ekmApplication:NameValue" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="nativeOptions" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="Applications">
<xsd:sequence>
<xsd:element name="application" type="ekmApplication:Application" minOccurs="1" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="applications" type="ekmApplication:Applications" />
</xsd:schema>
117
8.3.3.2. Defining External Applications Using XML

Application definitions are stored in XML files in EKM. Because of this, EKM supports adding new applications simply by uploading XML files in the proper format. See Schema Definition for Applications (p. 116)
for details on the format of these files. Only one application is defined per file.
Once you have defined an application in an XML file and saved it with the .app.xml or .appxml file
extension, you can upload it to an existing queue. EKM will recognize the file as an External Application
type based on its file extension.
For example, to add an application to the Local queue, go to /System/Servers/Master/Local,
and then upload the application using the Upload > Files/Archives Using the Browser action. The
usual naming convention is to name the file after the Application key. For example, if the Application key is myAppKey, the file name is myAppKey.app.xml.
The content of the sample application named myAppKey.app.xml is shown in Figure 8.10: myAppKey.app.xml listing (p. 118).
Figure 8.10: myAppKey.app.xml listing
<application>
<key>myAppKey</key>
<label>My Application</label>
<execPath>{$APP_PATH}/myApp.exe</execPath>
<param>-x</param>
<param>1</param>
<env name="VAR1" value="a" />
<env name="VAR2" value="b" />
<nativeOptions />
</application>
When configuring external applications, you can use the syntax {$ENV_NAME} to include the value of
an environment variable while defining any of the applications element values such as execPath,
param, or env.
Important
Always use the forward slash (/) as a path separator in all configuration files even when
running EKM on Windows.
8.4. Running Batch Jobs in EKM

Generally speaking, a job refers to a process that runs when an external application is launched from
EKM.
A batch job is a sequence of tasks to be executed by the operating system. Batch jobs are run in RSM
and do not require that that EKM wait for the job to complete before performing other tasks. These
jobs are often long-running. Consequently EKM provides a way to monitor the status of jobs, and notifies
the user when a job is complete. Batch jobs in EKM are typed as Job objects.
118
Running Batch Jobs in EKM
8.4.1. Running RSM Jobs in EKM

A common configuration for using RSM with EKM is shown below. In this configuration, a second server
is running an RSM Compute Server. EKM submits jobs to the RSM Manager (via the RSM XmlRpc Server),
which then dispatches them to the RSM Compute Server. The RSM XmlRpc Server is used to communicate
between EKM and the RSM Manager. The RSM XmlRpc Server must always be running on the same
server as the RSM Manager. The RSM Compute Server may be on the same machine as the RSM Manager,
or as shown in this example, it may be on a different server. There is no requirement that EKM must
be installed on the same server as the RSM services, so in the example that follows, the EKM Server
could have instead been running on a different server: Server 3.
Figure 8.11: Using EKM with RSM
As described in Types of Queues (p. 104), integration with RSM is based on the creation of EKM queues
that map to RSM queues. The specific configuration steps for this example are:
1.
Install EKM Server, XmlRpc Server, and RSM Manager on Server 1.
2.
Install RSM Compute Server on Server 2.
3.
In the RSM Manager on Server 1, define a queue and compute server that will allow you to run jobs on
Server 2. Note that in order to run jobs on the RSM compute server, the RSM server must be running
on a 64-bit Linux system. Also, the VNC password must be set. Refer to RSM Installation and Configuration
in the Remote Solve Manager User Guide for details on configuring RSM.
Note
If there are more jobs queued than the compute server can process, the jobs wait in
the queue without any error reporting. If RSM is used as the job scheduler, you can increase the number of jobs per compute server from 1 job (the default). For details on
how to do this, refer to the description of the Compute Server Properties dialog box
in the Remote Solve Manager Administration Guide.
4.
Configure EKM to work with RSM. See Installing and Configuring RSM (p. 120).
5.
Synchronize queues with RSM (see Synchronizing Job Submission Queues).
6.
Set permissions on the queue to control which users may submit jobs to them (see Editing Permissions
in the EKM Users Guide).
119
8.4.2. Using Other Batch Systems with RSM

To use third-party batch systems such as LSF or SGE with EKM, you must first configure those systems
to work with RSM. EKM uses RSM as the sole integration point to third-party batch systems. See Installing
and Configuring RSM (p. 120) for more details.
As described in Types of Queues (p. 104), integration with RSM is based on the creation of EKM queues
that map to RSM queues. For example, suppose you have an LSF cluster on your LAN that is spread
across three servers, as shown in Figure 8.12: LSF Cluster (p. 120).
Figure 8.12: LSF Cluster
For this system, the integration steps you would need to follow to configure the LSF cluster to EKM are:
1. Install EKM Server.
2. Install RSM Services on an LSF Head Node/Submit Host. In LSF, a submit host is a machine that is
able to submit jobs to the cluster.
3. Configure RSM to work with the LSF cluster. Refer to RSM Installation and Configuration in the Remote
Solve Manager User Guide for details on configuring RSM.
4. Define a queue in RSM that maps to an LSF queue.
5. Configure EKM to work with RSM. See Installing and Configuring RSM (p. 120).
6. Synchronize queues with RSM. See Synchronizing Job Submission Queues (p. 106) for details.
7. Set permissions on the queues to control which users may submit jobs to them (see Editing Permissions).
An EKM user can use an EKM queue to send work to the LSF cluster via RSM without knowing any details
about the LSF or RSM configuration. Refer to the ANSYS Remote Solve Manager (RSM) 15.0 user documentation for more details on configuring RSM.
8.5. Installing and Configuring RSM

ANSYS RSM is a job queuing system and is the sole integration point that EKM uses to interact with
batch systems. RSM itself may be used directly to run batch jobs or it may be configured to work with
other batch systems such as LSF, PBS and Windows HPC. Refer to the RSM release 15.0 user documentation for more details.
120
Installing and Configuring RSM

Refer to Specifying Remote Process Policies (<remoteProcess>) for details on the RSM integration settings
that are stored in EKM.
Important
There is no requirement that EKM must be installed on the same server as RSM.
8.5.1. Windows RSM Installation/Configuration

Follow the instructions in the ANSYS Remote Solve Manager (RSM) 15.0 user documentation noting
these configuration steps, which are specific to EKM:
1. When installing the RSM services, be sure to include the xmlrpc option as shown below. This
enables the ANSYS RSM XmlRpcApi V15.0 service, which is provided exclusively for use with EKM.
AnsConfigRSM.exe -mgr -svr -xmlrpc
In this example, you are configuring the Solve Manager, Compute Server and XmlRpc service
to all start at boot time.
The RSM services are:
ANSYS JobManager Service Version 15.0
ANSYS RSM XmlRpcApi Version 15.0
ANSYS ScriptHost Service Version 15.0
Important
The ScriptHost Service may be installed on a separate server, but the JobManager
and XmlRpcApi services must always be installed together on the same server.
Important
If the ScriptHost Service is installed on a separate server, you must configure RSM's
compute server to reuse the project directory as the working directory. EKM expects
compute servers to directly access and write to the RSM project directory.
2. You must run the ANSYS RSM XmlRpcApi V15.0 Windows service as a user with administrative
privileges.
3. EKM Server Account Requirements
To work with RSM, there are some requirements that must be met by the EKM Server Account.
This is the account used to run the EKM Server that is described in Create an EKM Server Account
in the EKM Installation Guide.
If EKM is run as a Windows service (the recommended way to run EKM) and you do not
change the default account the service uses to logon (Local System account), then there are
no additional requirements for integrating with RSM.
121

If EKM is not run as a Windows service, or if it is run a service configured to log on as a different account than the default Local System account, then the following configuration steps
must be performed:
The EKM Server Account must belong to the RSM Admins Windows User group. Refer to
the ANSYS RSM 15.0 documentation for more details about the RSM Admins Windows User
group.
The EKM Server Account information (user name and password) must be stored as an
account in RSM and kept up-to-date. Refer to the ANSYS RSM 15.0 documentation for more
details about RSM Accounts.
4. Create network domain accounts (for example, MYDOMAIN\jsmith) in RSM for any user name you
want to use when running batch jobs. You will need to enter the password information for these
accounts into RSM. Refer to the ANSYS RSM 15.0 documentation for more details.
5. Optionally configure the port for ANSYS RSM XmlRpcApi V15.0 service.
Note
If you change the default port value described below, you will need to restart the
service for it to pick up the changes. Services are accessed via the Windows Control
Panel under Administrative Tools.
The ANSYS RSM XmlRpcApi V15.0 service provides the interface from the EKM Server to RSM
and must be running for EKM to communicate with RSM.
This service runs on a tcp port specified in the file Ans.Rsm.XmlRpcServer.exe.config
that is located in the install_root\RSM\bin directory of the RSM installation.
If you need to change the default port (10012) used, edit this file and change the value specified
for the ListenerPort in the appSettings settings:
<appSettings>
</appSettings>
EKM defines a URL used to communicate with this RSM service. If you change the default port of the
XmlRpcApi service, you will also need to change the port specified in the default value of the
rsmClientURL setting. The rsmClientURL setting in EKM also includes the hostname where this XmlRpcApi service is running. If this is on a different server than EKM, the default value of localhost must
be changed. See Specifying Remote Process Policies (<remoteProcess>) (p. 50) for details.
8.5.2. Linux RSM Installation/Configuration

Follow the instructions in the ANSYS Remote Solve Manager (RSM) 15.0 user documentation noting
these configuration steps that are specific to EKM:
1.
Configure the RSM Services following the instructions in the ANSYS Remote Solve Manager (RSM) 15.0
user documentation.
The RSM services are:
Solve Manager Service
122
Installing and Configuring RSM

Compute Server Service
XmlRpcServer Service
Important
The Compute Server Service may be installed on a separate server, but the JobManager
and XmlRpcServer services must always be installed together on the same server.
Important
If the Compute Server Service is installed on a separate server, you must configure RSM's
compute server to reuse the project directory as the working directory. EKM expects
compute servers to directly access and write to the RSM project directory.
2.
EKM Server Account Requirements

To work with RSM, there are some requirements that must be met by the EKM Server Account.
This is the account used to run the EKM Server and which is described in Create an EKM Server
Account in the EKM Installation Guide.
There are two options for configuring the EKM Server Account to work with RSM on Linux:
Option 1 (recommended configuration):
The EKM Server Account must belong to the rsmadmins group. Refer to the ANSYS RSM 15.0
documentation for more details about the rsmadmins group.
The EKM Server Account information (user name and password) must be stored as an account
in RSM and kept up-to-date. Refer to the ANSYS RSM 15.0 documentation for more details about
RSM Accounts.
Option 2:
Run all of the RSM services using the same account as the EKM Server Account and do not configure
the services to start at boot time as daemons. They must be configured to be started manually. Refer
to the ANSYS RSM 15.0 documentation for more details.
Note
When installing RSM to a multiuser Linux machine, ANSYS strongly recommends that
you set up RSM as a daemon that starts at boot time, so Option 2 is not recommended
in that case.
3.
Create accounts in RSM for any user name you want to use when running batch jobs. You will need to
enter the password information for these accounts into RSM. Refer to the ANSYS RSM 15.0 documentation
for more details.
123

4.
Optionally configure the port for ANSYS RSM XmlRpcServer service.
Note
If you change the default port value described below, you will need to restart the service
for it to pick up the changes.
The ANSYS RSM XmlRpcServer service provides the interface from the EKM Server to RSM and
must be running for the batch service to communicate with RSM.
This service runs on a tcp port specified in the file Ans.Rsm.XmlRpcServer.exe.config
which is located in the <install root>\RSM\bin directory of the RSM installation. For example:
C:\Program Files\ANSYS Inc\v150\RSM\bin\Ans.Rsm.XmlRpcServer.exe.config.
If you need to change the default port (10012) used, edit this file and change the value specified
for the ListenerPort in the appSettings settings:
<appSettings>
</appSettings>
EKM defines a URL that is used to communicate with this RSM service. If you change the default port
of the XmlRpcServer service, you will also need to change the port specified in the default value
of the rsmClientURL setting. The rsmClientURL setting in EKM also includes the hostname where
this XmlRpcApi service is running. If this is on a different server than EKM, the default value of localhost
must be changed. See Specifying Remote Process Policies (<remoteProcess>) (p. 50) for details.
8.6. Running Interactive Jobs in EKM

An interactive job is similar to a batch job in that an external application is launched from EKM, but the
job is processed in real time. EKM uses NICE EnginFrame for creating and managing remote visualization
sessions. EnginFrame supports a number of remote visualization technologies such as DCV, VNC and
HP RGS. It can also work with many job scheduling systems for load balancing remote visualization
jobs. A schematic of the overall system architecture is shown below.
124
Running Interactive Jobs in EKM

Figure 8.13: Overview of Interactive Job System
The following steps are required to enable interactive job performance in EKM:
An administrator must install and configure EnginFrame. For details see Installing and Configuring EnginFrame in the EKM Installation Guide.
An administrator must configure EKM to integrate with EnginFrame. For details see Configuring EKM to
Work with EnginFrame in the EKM Installation Guide.
An administrator may optionally define additional applications in the interactive queues that are created
in EKM on startup. By default, interactive queues are created with a single predefined application called
remoteDesktop.app.xml, which launches an empty remote desktop session. For details see Creating
a New External Application (p. 112).
Users must install the remote visualization client on their computer or mobile device. See Table 11.2: Remote
Visualization Technologies Supported by EnginFrame in the EKM Installation Guide.
8.6.1. Running Remote Desktop Sessions

Users can start interactive jobs by launching the default Start Remote Desktop application in the Applications folder, or by executing an interactive job template that has been created in the repository.
When an interactive session is started, the user will be prompted to select an application to launch (for
example, ANSYS Workbench). A job object will be created in the users My Jobs folder, and from there
they will be able to connect to the remote session. The selected application will then launch remotely
on the users desktop.
For more information, see Running an Interactive Job in the EKM Users Guide.
125
126
Chapter 9: Configuring EKM Mobile

EKM Mobile is an application designed for cell phones and tablets. With it, users can log into a server
and view files, reports, and objects, perform searches, monitor and control jobs, create design points,
and control remote Workbench jobs.
There are two ways to deploy EKM Mobile:
With the Mobile Connector running on the same host as the EKM Server
With the Mobile Connector running on a host that is not the EKM Server
The benefits of running the Mobile Connector on a separate host are:
A single Mobile Connector can act as an access point for multiple EKM Servers.
The Mobile Connector can run on an Internet-accessible host (for example, in your company's DMZ), while
the EKM Servers remain unexposed to Internet traffic.
Note
Running the Mobile Connector on a host other than the EKM Server is a beta feature that
has not been fully tested.
9.1. Running the Mobile Connector on the Same Host as the EKM Server
To configure the server to accept EKM Mobile connections:
1.
In the ekm.xml file, which is located in the EKM_HOME/conf folder, uncomment the sections:
<mobileConnector>
<ekmServer serverName="ekm" serverKey="" />
</mobileConnector>
<mobileServer>
<mobileConnectorUrl></mobileConnectorUrl>
<serverName>ekm</serverName>
<serverKey></serverKey>
</mobileServer>
Leaving the <mobileConnectorUrl> element blank causes the <EKM URL> value to be used
as the Mobile Connector URL, which works for this single-server scenario.
2.
Restart the EKM server.

Users can now access the server from EKM Mobile at:
<EKM URL>/m/
For example: http://server.companyname.com:8080/ekm/m/
127
Configuring EKM Mobile

For more information, see Using EKM Mobile in the EKM Users Guide.
9.2. Running the Mobile Connector on a Host Other than the EKM Server
If you run the Mobile Connector on a host other than the EKM server, the Mobile Connector can be
used as an access point for multiple EKM servers. If you run the Mobile Connector on an Internet-accessible host (for example, in your companys DMZ), the EKM servers will not be exposed to Internet traffic.
Note
Running the Mobile Connector on a separate host is a beta feature that has not been fully
tested.
To configure another server to accept EKM Mobile connections:
1.
In the Mobile Connectors ekm.xml file, which is located in the EKM_HOME/conf folder, uncomment
the section:
<mobileConnector>
<ekmServer serverName="ekm" serverKey="" />
</mobileConnector>
2.
For every EKM Server that will use this Mobile Connector, add an <ekmServer> element that specifies
a unique serverName attribute and a serverKey attribute. The serverKey attribute can be any string, and
is used as a like a password to authenticate messages. An example where one Mobile Connector connects
to three EKM Servers might look like:
<mobileConnector>
<ekmServer serverName="ekm1" serverKey="password1" />
</mobileConnector>
On all EKM Server hosts:

1.
Uncomment the section:

<mobileServer>
<mobileConnectorUrl></mobileConnectorUrl>
<serverName>ekm</serverName>
<serverKey></serverKey>
</mobileServer>
2.
Enter the URL of the Mobile Connector in the <ekmConnectorUrl> element. (For example: http://mobile-host:8080/ekm)
3.
Enter the serverName and serverKey attributes for this server that were entered in step 1 of this procedure. An example might look like:
<mobileServer>
<mobileConnectorUrl>http://mobile-host:8080/ekm</mobileConnectorUrl>
<serverName>ekm1</serverName>
<serverKey>password1</serverKey>
</mobileServer>
4.
128
Restart all servers.
Running the Mobile Connector on a Host Other than the EKM Server
Users can now access the EKM Servers from EKM Mobile at:
MOBILE CONNECTOR URL/m/
For example: http://mobile-host:8080/ekm/m/
For more information, see Using EKM Mobile in the EKM Users Guide.
Note
When logging into EKM Mobile, users will specify the serverName of the EKM Server to which
they want to connect (for example: ekm1, ekm2, or ekm3).
129
130
Chapter 10: Defining and Configuring Lifecycles

A lifecycle is a set of stages that an EKM object moves through during its life, where each stage is
connected by one or more transitions. When an object is in a particular lifecycle stage, predefined
policies such as permissions and automatic deletion settings are applied to the object and its descendants.
Signoff processes can also be defined for a transition that require that an object undergo review and
approval by an individual or committee before it can be promoted to the next stage. Signoff committee
members are sent email alerts notifying them that review and approval is needed, and a new work item
is placed in their My Work Items folder. In addition, an instance of the signoff process is placed in My
Processes and can be used to monitor the approval process. Multiple levels of signoffs can also be
defined for a lifecycle.
Once a lifecycle is defined for an object type, it needs to be configured for a workspace by the root
user before it can be used. Once configured and enabled, any object of that type that is uploaded or
created in EKM will have the predefined lifecycle associated with it.
This chapter describes how to define lifecycles graphically in EKM Studio. For instructions on defining
lifecycles manually using XML, see Appendix C (p. 229).
Topics covered in this chapter:
10.1. Introduction to Lifecycles
10.2. Lifecycle Terminology
10.3. Basic Steps for Creating, Configuring, and Managing Lifecycles
10.4. Launching EKM Studio
10.5. Defining Lifecycles in EKM Studio
10.6. Enabling Lifecycles
10.7. Displaying Lifecycles
10.8. Promoting a Lifecycle Stage
10.9. Demoting a Lifecycle Stage
10.10. Managing Lifecycle Signoff Requests
10.11. Setting a Lifecycle Stage
10.12. Configuring Lifecycles for a Workspace
10.1. Introduction to Lifecycles

A lifecycle is a set of sequential stages that an object such as a file or folder moves through during its
lifetime. Lifecycles are defined in terms of stage and transition elements, where each stage is connected
by one or more transitions. In the lifecycle definition, you can define policies for each stage. These include
setting permissions for who can access, modify and perform other operations on an object and setting
criteria for automatic deletion of the object from the EKM repository.
You can define a lifecycle for any object type in EKM and you can use the lifecycle to track an object
as it matures. Figure 10.1: Sample Lifecycle Graph (p. 132) shows an example of a four-stage lifecycle
graph.
131
Defining and Configuring Lifecycles

Figure 10.1: Sample Lifecycle Graph
Lifecycle stages are promoted and demoted automatically by EKM or by a user/group based on completion criteria that are specified in the lifecycle definition. For example, you can specify completion criteria
that require an object to undergo review and approval by committee members before the stage can
be changed. This is referred to as a signoff process. A signoff process is automatically generated by EKM
whenever a request for stage promotion or demotion is made. Individuals and/or committee members
are sent an email notifying them that action is required. The email provides a link to the work item for
easy access and the work item is also placed in the assignee's My Work Items folder. An object can
also require multiple levels of review and approval before it can be promoted (or demoted) to the next
stage. For example, you can define a stage that requires an initial level of signoff by, say, all members
of a Design Review Team and Project Manager followed by a second level of approval from, say, the
VP of Engineering.
You can define lifecycle templates in two different ways: graphically in EKM Studio, and using XML. The
easiest method is to use EKM Studio. When saved to your local file system or an EKM repository, the lifecycle you define in EKM Studio is converted to XML and the file is typed as a Lifecycle object and
given the .lc.xml file extension.
You can also define a lifecycle file in XML, using any XML or text editor. See Appendix C (p. 229) for details.
Lifecycle files behave like any other object in EKM with respect to being able to be tagged with userdefined properties, placed under version control, and searched for using a keyword and advanced
search criteria.
Once a lifecycle has been defined and saved as an XML file, it will need to be configured for your
workspace before it can be used. The configuration process associates the lifecycle with all the object
types that it is defined for. The lifecycle then either gets automatically enabled for all objects in the
repository belonging to that type, or the lifecycle will require manual enabling for individual object,
depending on how it has been defined. See the Restricted and Unrestricted Configuration of Workspaces
chapter in the Administration Guide for more details.
10.2. Lifecycle Terminology

Let's start with defining some lifecycle terms that are used throughout EKM Studio.
Stages
132
Launching EKM Studio

Stages are phases within a lifecycle where you can set permissions for who can access, modify
or do other operations on an object and set criteria for automatic deletion of the object from
the connected EKM repository. They are represented in a lifecycle diagram with the icon shown
above.
Lifecycles must adhere to the following rules:
Lifecycles should have exactly one start stage. A start stage is the stage that is not the
destination of any transition. Lifecycles can have more than one end stage. An end stage
is the stage that is not the source of any transition.
Lifecycles must be acyclic. For example, if you have a transition from stage A to stage B, then
you cannot have a transition from stage B to stage A. Similarly, if you have defined transitions
from stage A to stage B and from stage B to stage C, you cannot have a transition from stage
C to stage A. Lifecycles are always directed acyclic diagrams.
Transitions
A transition is a link between a starting stage (source) and an ending stage (destination). It is
used to specify the subsequent and preceding stages of a lifecycle stage. A transition can also
optionally specify a signoff process for moving to the next stage. Transitions are represented
in a lifecycle diagram as an arrow.
Signoff Process
A signoff process is a separate process automatically generated by EKM when completion criteria
for a stage transition require that the object undergo review and approval before being promoted
or demoted. Members are sent an email notifying them that an action is needed, and a new work
item is placed in their My Work Items folder.
10.3. Basic Steps for Creating, Configuring, and Managing Lifecycles

1. Define a lifecycle in EKM Studio or using XML.
2. Upload the lifecycle file to the repository. It will be assigned the Lifecycle type.
3. (admin group members only) Configure the lifecycle file for the workspace.
4. Enable the lifecycle for an object type if it was not automatically enabled when it was configured
for the workspace.
5. Display the lifecycle for an object, promote or demote a lifecycle stage, manage signoff requests,
and set a lifecycle stage (admin only).
10.4. Launching EKM Studio

You can launch EKM Studio from the EKM web client. When you launch EKM Studio, it will attempt to
connect to the current server workspace.
There are three ways in which you can launch EKM Studio:
In the EKM web client, select File > EKM Studio.
133

In the EKM web client, select a folder in the navigation pane that permits the addition of new data, then
select New > Workflow.
In the EKM web client, select an existing Lifecycle object type and then right-click and select Edit >
Lifecycle in EKM Studio. An example is shown below.
Tip
If you see a pop-up that gives you the option of opening LaunchStudio.jnlp or saving
the file, select the Do this automatically for files like this from now on option, select Open
with Java(TM) Web Start Launcher (default), and click OK.
For an overview of EKM Studio, see The EKM Studio Environment in the EKM Users Guide.
10.5. Defining Lifecycles in EKM Studio

To define a lifecycle in EKM Studio you simply insert stages in the editing window. When inserting
stages sequentially, a transition is automatically created between the last stage inserted and the next
one that you insert. You can also insert transitions manually between any two existing stages. Once
you have inserted stages and transitions, you can define their settings. For stages you can specify their
name, expiration, and permissions. For transitions you can define validation and action macros, as well
as signoff processes.
To launch EKM Studio, select File > EKM Studio.
134
Defining Lifecycles in EKM Studio

For an overview of EKM Studio, see The EKM Studio Environment in the EKM Users Guide.
10.5.1. Steps for Defining New Lifecycles

Follow these basic steps to define a new lifecycle in EKM Studio.
1.
In EKM Studio, select File > New > Lifecycle.
2.
Insert a start stage using the Insert Stage action and add additional stages to build your diagram. See
Inserting New Stages (p. 136).
3.
Add transitions between stages using the Insert Transition action. See Inserting New Transitions (p. 139).
4.
Edit the stages and transitions to further define them. See Editing Stages (p. 137) and Editing Transitions (p. 139).
5.
Define the object types to which the lifecycle will be applied. See Editing Lifecycle Attributes (p. 144).
6.
Select File > Save As to save the lifecycle file to your local file system or to an EKM Repository. The lifecycle is saved as an XML file with the .lc.xml extension. See Saving Lifecycle Files (p. 143).
135
10.5.2. Defining and Editing Lifecycle Stages

Stages are used to define tasks that users/groups will perform as an object moves through its lifecycle.
Stages are connected by transitions.
Actions associated with lifecycle stages are presented in the following sections. Topics include:
10.5.2.1. Inserting New Stages
10.5.2.2. Editing Stages
10.5.2.3. Renaming Stages
10.5.2.4. Deleting Stages
10.5.2.1. Inserting New Stages

To insert a stage in a lifecycle diagram, click
to edit it. See Editing Stages (p. 137) for details.
on the toolbar. Then, double-click the stage
If an existing stage is currently selected when you insert a new stage, the new stage will be placed next
to the existing stage, and a transition will be automatically inserted between the two stages. If no stage
is selected when you insert a new stage, the new stage will be placed at the beginning of the diagram
and can then be dragged to the desired position within the diagram. In the latter scenario you will
need to manually insert a transition between an existing stage and the new stage.
You can drag and drop stages to arrange them in a particular order. This is particularly necessary when
a new stage inserts on top of an existing stage.
Note
You cannot insert a stage if the current selection is a transition. If you attempt to do this,
the following dialog will be displayed:
In this case, click OK and then either click in blank space or select an existing stage to connect
the new stage to.
136

Once a stage is inserted, it will be listed in the Stage folder in the Elements tree, and its properties
will be displayed in the Properties window.
10.5.2.2. Editing Stages

Once a stage is inserted, you can define its properties using the Edit tool.
To edit a stage:
1.
Double-click the stage in the lifecycle diagram, or right-click the stage in the diagram or tree and select
Edit from the context menu. The Edit Stage dialog box will appear:
Figure 10.2: Edit Stage Dialog Box
2.
In the Name edit box, enter a name for the stage as you would like it to appear in the diagram and
tree. Names cannot contain these characters:
/ \ : [ ] * ' " |
3.
In the Description edit box, enter a description to help identify what will happen during the stage
(optional). The description will be displayed when you mouse over the stage in the diagram, and in the
Properties window when the stage is selected.
4.
If you want the object to be automatically deleted from the repository within a certain number of days,
check the Delete automatically box. Then, in the Expiration days edit box, specify the number of
days after which the object should be automatically deleted from the repository. Usually this will only
be specified in the last phase of the lifecycle, if you want an obsolete object to be automatically deleted
after a certain period of time. If you leave this value at 0, the object will not be deleted automatically
and will be preserved indefinitely.
5.
To allow the object to become part of the previous stage, check the Demote Allowed box.
137

6.
In the Permissions pane, set permissions for the stage. To set permissions, click the Insert link to add
an entry to the Member list, then click the drop box to select a user or group member. You can also
use * to specify the user who created the object. Once you have selected a user you can check the
boxes of permissions that you want that user to have.
Permission type options include:
Access: Specifies who can access (or view) this object. By default this is selected and users
cannot change this setting. However, other permissions can be granted.
Create: Specifies who can add a child to a folder object.
Delete: Specifies who can delete the object.
Modify : Specifies who can modify the object.
Download: Specifies who can download a file or folder object.
Lifecycle: Specifies who can perform lifecycle operations such as promote and demote.
Full Control: Specifies who has full control over the object. Full control means all permissions
Note
If an object associated with a lifecycle is not accessible because the parent folder containing the object does not provide access permission to sign-off members or lifecycle
users, those users cannot "Promote" the stage. To enable the ability to promote, give
the required users at least "Access" permission to the parent folder.
7.
Click OK.
10.5.2.3. Renaming Stages

You can rename a lifecycle stage using the Rename tool.
To rename a stage:
1.
Right-click the stage in the diagram or tree and select Rename.
2.
In the Rename dialog box, enter the desired name for the stage in the New name edit box.
3.
Click OK.
10.5.2.4. Deleting Stages

To remove a stage from a lifecycle, right-click and the stage in the diagram or tree and select Delete.
You can also remove a stage by selecting it in the diagram and pressing the [Delete] key on your
keyboard.
When you delete a stage, the transitions connected to it will also be deleted.
138
10.5.3. Defining and Editing Lifecycle Transitions

Actions that are associated with lifecycle transitions are presented in the following sections.
Topics in this section include:
Inserting New Transitions (p. 139)
Editing Transitions (p. 139)
Deleting Transitions (p. 142)
10.5.3.1. Inserting New Transitions

You can add a transition between any two stages in a lifecycle diagram by selecting the stages you
want to connect and clicking
on the toolbar.
10.5.3.2. Editing Transitions

Once you have inserted a transition in a lifecycle diagram you can set up macros for promoting and
demoting objects, and define Promote and Demote signoff processes.
To edit a transition:
1.
Double-click the transition in the lifecycle diagram, or right-click the transition in the diagram or tree
and select Edit from the context menu. The Edit Transition dialog box will appear.
139

Figure 10.3: Edit Transition Dialog Box for a Lifecycle
2.
Specify any macros that are to be used for performing actions associated with promote/demote requests.
The types of macros that you can specify are described below. See Using Macros in Lifecycle Definitions (p. 141) for details on how to define macros.
Promote validation macro
The name of the macro that is used to perform validation before a promote request can be processed.
Promote action macro
The name of the macro that is used to perform an automatic action after a promotion request has
been processed.
Demote validation macro
The name of the macro that is used to perform validation before a demote request can be processed.
Demote action macro
The name of the macro that is used to perform an automatic action after a demote request has
been processed.
140

3.
Define the signoff processes for promoting and demoting the object. Only the person who created the
workflow can promote it. You can create a multi-level signoff process by adding any number of signoff
elements to the Promote signoff or Demote signoff window pane. In the example shown in Figure 10.3: Edit Transition Dialog Box for a Lifecycle (p. 140), there are two levels of signoff defined for
stage promotion: Level 1 is required by all members of the Design Team; and Level 2 by the
Development Manager. The first level must be completed before the next one can begin.
Click Insert to add rows to the Promote signoff or Demote signoff table. To remove a row, select
it and click Delete. Once an entry has been added to a table, you can define its properties:
Level: Specifies the name of signoff level. There are no character restrictions for the level definition.
Double-click in the Level text box to enter/edit the name.
Members: Specifies the names of users and groups who are involved in the signoff at this level. If
you specify more than one user or group, you will need to separate their names by a comma. Singleclick in the Members box and a drop-down list of available members will be displayed (drop-down
list not shown in Figure 10.3: Edit Transition Dialog Box for a Lifecycle (p. 140)).
Inclusive: Specifies whether or not all Members for this level need to approve the signoff. If the Inclusive box is checked, then ALL Members must approve the signoff. If it is cleared, then any member
can approve the level signoff.
Due Days Specifies the number of days allowed for the signoff. If a user has not approved or a rejected
the signoff by then, a daily reminder mail is sent to the user. Double-click in the Due Days box to
enter/edit the amount of time the Members have to complete the signoff process.
4.
Click OK to save your changes.
10.5.3.3. Using Macros in Lifecycle Definitions

You can define macros in EKM Studio and embed them in a lifecycle definition to automate certain
tasks.
You can specify a macro in a transition to:
Perform validations before promoting or demoting a stage.
Execute automated tasks after promotion or demotion.
Dynamically assign users and groups to a signoff request in a lifecycle.
To define a macro, select Edit > Script, then type your script in the Edit Script dialog box. Note that
you do not insert the <script> tag in the macro definition; this is added automatically by EKM Studio.
You should define the macro using the scripting language (Python or Beanshell) displayed above the
editing window. The scripting language for a lifecycle is set in your lifecycle attributes.
The example below shows the script for a BeanShell macro named solveOnce.
141

Figure 10.4: Edit Script Dialog Box
The name that you define for the macro in the script can then be entered in the Edit Transition dialog
box so that it can be utilized.
Note
Jython imposes a limit of 100 KB per script file. To avoid lifecycle errors it is recommended
that you create scripts using the EKM scripting interface and store them in the /System/Configuration/Scripts folder. For details see Using EKM's Scripting Interface (p. 159).
Storing scripts in a centralized library makes them available for any workflow, lifecycle, or
custom type. See Configuring a Common Scripts Library (p. 193) for details.
10.5.3.4. Deleting Transitions

To delete a transition in a lifecycle diagram, right-click the transition in the diagram or in the tree and
select Delete from the context menu. You can also delete a transition by selecting it in the diagram
and pressing the Delete key on your keyboard.
142
10.5.4. Saving Lifecycle Files

You can save a lifecycle definition on your local file system or in an EKM repository. The lifecycle will
be saved as an XML file with the .lc.xml extension.
Note
You cannot save a lifecycle in the /System/Configuration/Lifecycles folder unless
you are in Workspace Configuration mode.
To save a lifecycle to your local computer:
1.
Select File > Save. If the current lifecycle has been saved previously, and you want to save it under a
different name, select File > Save As > Local File.
2.
In the Save dialog, navigate to the folder where you want to save the file.
3.
In the File name edit box, enter a name for the lifecycle file.
4.
Click Save.
To save a lifecycle file to an EKM repository:

1.
Select File > Save As > Repository File.
2.
In the Save File dialog box, enter a name for the lifecycle in the File name edit box. You do not need
to include the extension.
3.
Click Browse... to display the contents of your repository connection.
4.
Select the folder where you want to save the lifecycle.
5.
Click Save.
10.5.5. Opening Lifecycle Files

You can open EKM lifecycle XML files that are stored on your local file system or in an EKM repository
using options on the File > Open menu. Lifecycle files can either have the .lc.xml extension or
.lcxml for previous EKM releases.
To open a lifecycle file that is located on your local file system, select File > Open > Local File, then
choose the file in the Open dialog box.
143

To open a lifecycle file that is located in a connected EKM repository, select File > Open > Repository
File. The Open File dialog box opens. Click the Browse... button to display the contents of your currentlyselected repository connection. Select the desired lifecycle file and click Open to open it in EKM Studio.
Figure 10.5: Opening a Lifecycle File in the Repository
10.5.6. Editing Lifecycle Attributes

Once you have defined your lifecycle diagram as described in Steps for Defining New Lifecycles (p. 135),
you need to specify which object types that the lifecycle will be applied to, and whether the lifecycle
will be enabled when an object of that type is created. You can also select the scripting language to
be used for macros and expressions.
To define the object types that a lifecycle will be associated with:
1.
144
Select Edit > Lifecycle Attributes from the menu bar to open the Edit Lifecycle Attributes dialog
box.

Figure 10.6: Edit Lifecycle Attributes Dialog
2.
Click Insert to add a row to the Types table.
3.
Click in the New Type box and select an object type from the drop-down list.
4.
If you want an object of that type to be enabled automatically by EKM whenever it is uploaded to a
repository or created, check the Enabled by default box. If you do not enable an object type by default,
then the lifecycle can manually be enabled by any user who has Lifecycle permission for the object
using the Enable Lifecycle action. See Enabling Lifecycles (p. 146) for more details.
5.
From the Language drop box, select the scripting language (Python or BeanShell) that you would like
to use for macros and expressions.
Python is a powerful and easy-to-use scripting language that is becoming very popular. EKM uses
Jython 2.5.2 to handle Python syntax. To learn more about Jython, refer to http://www.jython.org/
index.html. To learn more about Python, refer to http://www.python.org. Jython 2.5.2 allows the
use of Python 2.5 language features. In addition you can use any Java classes offered by JDK 1.7.
BeanShell is a scripting language that can execute code written in standard Java syntax while
providing scripting conveniences such as loose types. For more information on BeanShell and to
see its detailed documentation, refer to http://www.beanshell.org. With BeanShell you have full
access to all classes provided by Javas JDK. EKM uses JDK 1.7, so you can use any of its classes in
macros defined using BeanShell.
If you change the Language setting, you will be prompted to edit any existing macros and expressions after you click OK in the Edit Lifecycle Attributes dialog:
145

All expressions and scripts in the lifecycle should be consistent with the Language specified in
your lifecycle attributes. If you have not defined any macros or expressions in the current lifecycle,
you can disregard this warning message.
6.
Repeat this process to add more object types to the lifecycle template. To remove a type, select it in
the list and click Delete.
10.6. Enabling Lifecycles

Lifecycles can be defined as automatically enabled in a lifecycle template XML file or not enabled.
If automatically enabled, whenever an object of a type associated with the lifecycle is uploaded to or
created in EKM, it will automatically be assigned the lifecycle template and its stage will be set to the
starting stage of the lifecycle. Alternatively, if a lifecycle is not enabled, then it must be enabled from
within EKM by a user who has lifecycle permission for the object.
If a lifecycle has been defined for a parent object but not for a child object, then the child will automatically inherit its parents lifecycle.
Important
Once a lifecycle is enabled, the lifecycle permission policies that are defined in the lifecycle XML file are applied to the object, and will override any other permissions that
were previously set for the object using Edit > Permissions. The Enable Lifecycle
dialog box contains this reminder, as shown in Figure 10.7: Enable Lifecycle Dialog
Box (p. 146). Note that lifecycle permission policies can be subsequently overridden by
anyone with lifecycle permission for the object.
To enable a lifecycle:
1.
Select the object, right-click, and select Edit > Lifecycle > Enable from the context menu. This will
open the Enable Lifecycle dialog box.
Figure 10.7: Enable Lifecycle Dialog Box
2.
146
Click OK.
Displaying Lifecycles
10.7. Displaying Lifecycles

Once a lifecycle is enabled for an object, you can display it by selecting Display > Lifecycle on the
right-click menu or toolbar. A sample lifecycle is shown below.
Figure 10.8: Displaying a Lifecycle
A lifecycle display contains the following four components:

Graph. In the graph, the current lifecycle stage is shown in white (for example, Thermal Analysis in
the sample figure). The graph elements will change color as the stage changes, giving you a visual depiction
of the object as it matures.
147

Stages. The name, description and permissions of each stage in the lifecycle are listed.
Transitions. Each transition requires a signoff before the next stage can be promoted. This is indicated
under Promote Signoff.
History. This section shows actions that have been performed so far, along with any comments that users
have entered.
Displaying Lifecycle Stages in the File List Window

You can set your preferences to display lifecycle stages on the List tab of the file list window.
To add a Lifecycle Stage column to your file list display:
1.
Select Settings > Preferences.
2.
In the Edit Preferences dialog box, select List Display in the left pane, and then check the Lifecycle
Stage box in the right pane, as shown below.
Figure 10.9: Edit Preferences Dialog Box - Lifecycle Stage
148
Promoting a Lifecycle Stage

3.
Click OK.
Figure 10.10: List Display With Lifecycle Stage
10.8. Promoting a Lifecycle Stage

An object can be promoted to the next stage by any user who has Lifecycle permission for the
stage.
To promote an object to the next lifecycle stage:
1.
Select the object, right-click and select Edit > Lifecycle > Promote from the context menu. This opens
the Promote Lifecycle Stage dialog box.
Figure 10.11: Promote Lifecycle Stage Dialog Box - Signoff Required
149

2.
Select the new stage.
3.
Optionally enter comments. These are viewable in the Lifecycle history.
4.
If the lifecycle stage requires a signoff before it can be promoted, the signoff committee members are
listed.
5.
Click OK. If the object does not require a signoff, it will be immediately promoted to the next stage. If
signoff is required, a separate Signoff process will be launched.
10.9. Demoting a Lifecycle Stage

A user with Lifecycle permission can demote an object to the previous stage if demotion is allowed
for that stage in the lifecycle definition.
To demote a lifecycle stage to the previous stage:
1.
Select the object, right-click and select Edit > Lifecycle > Demote from the context menu. This opens
the Demote Lifecycle Stage dialog box.
Figure 10.12: Demote Lifecycle Stage Dialog Box
2.
3.
Optionally enter comments. These are viewable in the Lifecycle history.
4.
If the stage has a signoff process, the signoff committee members will be shown.
5.
Click OK to demote the lifecycle stage. A separate Signoff request process will be launched if the object
requires a signoff before it can be demoted.
10.10. Managing Lifecycle Signoff Requests

An object can require multiple levels of review and approval before it can be promoted (or demoted)
to the next stage. Two options are available: either all members in a level can be asked to review and
perform a signoff; or any member can. This behavior is defined in the lifecycle XML file and is displayed
in the transition table in the lifecycle display as "All of" and "Any of" respectively.
150
Managing Lifecycle Signoff Requests

In the example lifecycle, a promote signoff process has been defined for three stages: Thermal Analysis,
Stress Analysis, and Lifetime Calculation. The first two stages require a single level of signoff by all
members of the Design Review Team and the Project Manager. This is a Level-1 Signoff. The Lifetime
Calculation stage requires an additional level of signoff from the VP Engineering (Level-2 Signoff). This
example lifecycle does not have any demote signoff levels defined. This means that the stage can be
demoted without approval from anyone.
If a signoff is defined for a stage transition, a separate Signoff process is automatically initiated by EKM
whenever the request is made to promote (or demote) the stage. The pending stage on the lifecycle
display graph will change color to indicate that a signoff is pending.
Objects under lifecycle control will be displayed in the List display as locked by the ekm_life
cycle_user while the signoff process is active, and the tool tip will indicate that the objects are exclusively controlled by that user. This will ensure that no one else can modify the objects while they
are under review. ekm_lifecycle_user is a system account used by EKM to manage lifecycles.
Email alerts are sent to all members of the signoff committee (as defined in the lifecycle template) notifying them that their action is required. The work item for the signoff will be listed in each committee
members My Work Items folder. The signoff process can be displayed by clicking the Signoff link in
the work item as shown in Figure 10.13: My Work Items Showing Level-1 Signoff Work Item (p. 152). The
review is started by clicking the
action on the toolbar. Once the objects have been reviewed,
the committee member can approve or reject the signoff request using the action menus. The user
who initiated the signoff request or the system administrator can also cancel an active signoff request.
151

Figure 10.13: My Work Items Showing Level-1 Signoff Work Item
Figure 10.14: Signoff Process Graph
Here are some rules for signoff requests:

If a signoff requires Any committee member to approve it, then the first member to approve it will cause
the object to be promoted or demoted to the next stage (or advance to the next level of signoff ). If any
member rejects the request, then the signoff process is cancelled and the stage is not promoted (or demoted).
If a signoff requires All members to approve it, then when any member rejects the request, the signoff
process is cancelled without promotion or demotion.
A signoff process is ended when one of the following occurs:
All approvals are obtained from the last approval level
152
Managing Lifecycle Signoff Requests

A request is denied by one of the signoff committee members.
The process initiator or system administrator cancels the signoff while the request is still pending.
When a signoff has ended (through approval, rejection, or cancellation), the process and all associated
work items are deleted from My Work Items.
10.10.1. Approving a Lifecycle Signoff Request

Once the review for a Signoff work item has been started, it can approved for stage promotion or
demotion.
To approve a signoff request:
1.
Select the signoff request in your My Work Items folder, then click
open the Approve Signoff Request dialog box.
on the toolbar. This will
Figure 10.15: Approve Signoff Request Dialog Box
2.
Optionally enter acceptance comments. You can view these comments in the object's lifecycle history.
3.
Click OK to approve the signoff. This will remove the level signoff request from your My Work Items.
The approval will be logged in the lifecycle history.
10.10.2. Rejecting a Lifecycle Signoff Request

Once the review for your lifecycle Signoff work item has been started, you can reject the request for
stage promotion or demotion. If you reject a signoff, then the Signoff process will be cancelled and the
stage will not be promoted (or demoted).
To reject a signoff request:
1.
Select the signoff request in your My Work Items folder, and then click
opens the Reject Signoff Request dialog box.
on the toolbar. This
153

Figure 10.16: Reject Signoff Request Dialog Box
2.
Optionally enter rejection comments. You can view these comments in the object's lifecycle history.
3.
Click OK to reject the signoff. This action will cancel the Signoff process and cause the stage promotion/demotion request to be cancelled. The stage will roll back to its last state. It will also remove the
level signoff request from your My Work Items folder. Your rejection will be logged in the lifecycle
history.
10.10.3. Cancelling a Lifecycle Signoff Request

Once a Signoff process is underway, it can be cancelled at any time while the signoff is still pending
by the user who initiated the promotion or demotion request, or by the system administrator.
To cancel a signoff request:
1.
Select
from the Edit > Lifecycle action menu of the object being promoted or demoted.
This will open the Cancel Signoff dialog box.
Figure 10.17: Cancel Signoff Dialog Box
2.
154
Optionally enter comments. You can view these comments in the object's lifecycle history.
Configuring Lifecycles for a Workspace

3.
Click OK to cancel the signoff request. This action will remove the level signoff work item from every
member's My Work Items folder.
10.11. Setting a Lifecycle Stage

The system administrator can set the current lifecycle stage for an object to any stage without validation
or signoff using the Set Lifecycle Stage dialog box. The Set Stage option is not available when a signoff
process is active. In this case, the system administrator will first need to cancel the request before the
new stage can be set.
To set a lifecycle stage:
1.
Select the object, right-click, and select Edit > Lifecycle > Set Stage from the context menu. This will
open the Set Lifecycle Stage dialog box.
Figure 10.18: Set Lifecycle Stage Dialog Box
2.
3.
Optionally, enter comments. You can view these comments in the object's lifecycle history.
4.
To set the new stage, click OK.
10.12. Configuring Lifecycles for a Workspace

Before it can be used, a lifecycle must be configured for the workspace in which it will be used. Lifecycle
configuration must be performed in restricted configuration mode, which can only be done by the
155

root user and requires the workspace to be locked down. While restricted configuration is underway,
no other user can log into the workspace until the process is completed.
To configure a lifecycle in EKM:
1. Start restricted configuration if it has not already been started.
2. Upload. copy or move the Lifecycle object that was created using EKM Studio or created using XML to
the Systems/Configuration/Lifecycles folder.
3. Apply configuration changes.
4. Accept configuration changes.
156
Chapter 11: Scripts and Journals

This chapter presents information on how to define scripts in EKM using a supported scripting language
(Python or BeanShell) and using EKM's scripting interface, to enhance the standard product features.
Scripting actions include recording a journal script and running it, and executing any Python or BeanShell
script on-demand. You can also use scripts in workflows, lifecycles, custom types, job templates and
custom applications to automate tasks.
Topics covered in this chapter:
11.1. Introduction to Scripts and Journals
11.2. Defining Scripts Using a Supported Scripting Language
11.3. Using EKM's Scripting Interface
11.4. Using Sample Scripts Supplied by EKM
11.5. Scripting Actions
11.6. Recording Journal Scripts
11.7. Running Journal Scripts
11.8. Example of Journal Recording and Execution
11.9. Running Python and BeanShell Scripts From a Command Window
11.1. Introduction to Scripts and Journals

Let's begin by defining some terms.
macro
A method defined in a supported language that can execute a sequence of tasks or call other macros.
The arguments that a macro can be passed, and the values that it can return, will depend on the context
in which it is used. Macros can be specified in separate script files or defined within workflows, lifecycles,
custom types, and custom applications.
script
A file that is written in the Python or BeanShell scripting language that contains one or more macros.
BeanShell scripts have the .bsh extension; Python scripts have the .py extension.
journal
A special type of script file that can be created using the File > Scripting menu in EKM through the recording of user interface actions. Also referred to as a journal script or a journal file. This is a Python file
with extension .jou.py.
Applications for Scripts in EKM

Some common applications for scripts in EKM are:
Embedding scripts in workflow files: You can embed scripts in workflow XML files to:
Define logic that must be used in an expression but cannot be defined because it is too complex or
you want to use reuse the logic in other ways.
Define logic for auto nodes. An auto node will execute the associated script upon activation.
157
Scripts and Journals

Define custom dialog boxes for batch execution or work item completion.
Embedding scripts in lifecycle files: You can embed scripts in lifecycle XML files to:
Perform a validation before promotion or demotion the next or previous stage.
Execute an automated task after promotion or demotion.
Embedding scripts in custom type files: You can embed scripts in custom type XML files to:
Add new action menus to built-in and custom types.
Define execution settings and update logic for analysis projects.
Define dependent properties (properties that depend on other properties) for any custom type. Example:
The options available in a state property may be dependent on the value of a country property.
Define a macro that can be hooked to a custom type that will automatically execute whenever a new
instance of that type is created.
Embedding scripts in job template files: You can embed scripts in job template files to:
Define a macro for validating variable values entered by the user.
Define variables of type Expression whose value depends on other variables.
Defining custom applications using a script file: You can use a script file to define a custom application.
Two macros are needed in the file: an initialization macro that defines the variables used by the custom
application to get user inputs, and an execution macro that processes the user inputs once they are submitted and executes some commands. See Steps for Creating and Using Custom Applications (p. 179).
Building a common script library: A common script library can be constructed by an EKM administrator
to make its macros accessible to all users in all contexts. This is done by placing the script under workspace
configuration control in the /System/Configuration/Scripts folder. Once the script is placed in
that location and the workspace configuration is accepted or applied, all of its macros will be accessible
in all contexts: lifecycles, workflows, custom types, custom applications, and even the Command Window.
On the other hand, macros defined in a specific context such as lifecycle file, are accessible only in that
context. See the section on Configuring a Common Scripts Library in the Administration Guide for more
details.
Important
Scripts that are defined in the /System/Configuration/Scripts folder cannot access
the global ekm variable that is used in EKM's scripting interface. Therefore, this variable
must be passed as an argument if a script is to make use of it.
11.2. Defining Scripts Using a Supported Scripting Language

A script file can be defined in EKM using one of the two supported scripting languages: BeanShell or
Python.
BeanShell can execute code that is written in standard Java syntax while providing scripting conveniences
such as loose types and dynamic execution. For more information on BeanShell and to see its detailed
158
Using EKM's Scripting Interface

documentation, refer to http://www.BeanShell.org. With BeanShell you have full access to all classes
provided by Javas JDK. EKM uses JDK 1.7, so you can use any of its classes in scripts defined using
BeanShell. BeanShell script files are saved with the .bsh file extension.
Python is a powerful and easy-to-use scripting language that is becoming very popular. EKM uses Jython
2.5.2 to handle Python syntax. To learn more about Jython, refer to http://www.jython.org/index.html.
To learn more about Python, refer to http://www.python.org. Jython 2.5.2 allows the use of Python 2.5
language features. In addition you can use any Java classes offered by JDK 1.7. Python script files are
saved with the .py file extension.
In addition to the language features and libraries provided by the scripting languages, scripts can also
use a scripting interface provided by EKM. This interface exposes predefined methods that can be used
to access or modify data in EKM and execute common operations. See Using EKM's Scripting Interface (p. 159) for information about the classes and methods that are available through the scripting interface.
Note
A limitation of Python is that the output from a script is displayed only in the console of
your application server (for example, JBoss 7) and does not appear in the Output log in the
Open Command Window dialog box.
11.3. Using EKM's Scripting Interface

EKM provides a scripting interface that you can use to define scripts that automate many common
operations. Scripts are typically used as a back-end for custom applications, and can be embedded
within a workflow, lifecycle or custom type definition to provide automation where required. EKMs
scripting interface exposes a number of methods or macros that can be used in your script. The detailed
documentation of the interface is provided in the EKM_HOME/api folder. This folder contains two sub
folders: ekm-api-docs-15.0.0 and ekm-cae-api-docs-15.0.0. The first sub-folder contains
the majority of the documentation. The second sub-folder is just limited to the cae plug-in and provides
a single interface with methods for creating simulation details reports. To access the documentation
you can open the index.html files in these sub folders.
The primary interfaces provided are:
EkmInterface: This is the primary interface and provides methods to get or search for existing
objects, create new objects, execute batch tasks, start and commit transactions, perform uploads,
downloads, copy, move and lifecycle operations. An instance of this interface is available as a global
variable for use in scripts. The name of the variable is ekm. For example, within a script you can call
ekm.getRoot() to get the root object of EKM.
EkmAdminInterface: This interface extends EkmInterface. If you belong to the admin group,
the global ekm variable that you can access within scripts will be an instance of this interface instead
of EkmInterface. This interface provides additional methods to add users and groups and set lifecycle stage without validation or review. For example, within a script you can call ekm.addUser("testuser") to add a new user with user name "testuser."
ModelObjectInterface: This interface represents an object in EKM. It contains methods to obtain
properties, children, name, id, path, type and version of the object. It also contains methods to add
or remove a child, delete the object, add it to version control, perform check in or check out, set
properties and permissions. There are some interfaces that extend ModelObjectInterface to
159

provide additional methods for specific object types. These are FileObjectInterface, ReportObjectInterface, AnalysisContainerInterface, ShortcutObjectInterface,
UserObjectInterface and GroupObjectInterface. When you create a new file object or
get an existing file object, what you will get is an instance of FileObjectInterface and not
ModelObjectInterface. Similarly when you create or get an instance of Report, Analysis Project,
Shortcut, User or Group, you will get an instance of the extended interface and not ModelObjectInterface.
DialogInterface: This interface is used to define a dialog box for the web user interface. It
provides methods to add steps and variables.
VariableInterface: This interface is used to define variables used in a dialog box. It contains
methods to get/set the value, type, label, and so on for any dialog variable.
EkmCaeInterface: This interface provides methods to create simulation details reports. An instance
of this interface is also available as a global variable for use in scripts. The name of the variable is
ekmCae.
When you are using methods provided by the scripting interface, you will need to refer to the accompanying API documentation to determine whether the method needs to be called within or outside of
a transaction. A transaction is a group of commands that are committed together. If any command fails,
none of the previous commands will be committed and the whole transaction will be aborted. You can
start a transaction by calling the startTransaction method of EkmInterface and you can
commit a transaction by calling the commitTransaction method of the same interface. Any method
that does not change the state of an object can be called either within or outside a transaction. Most
methods that change the state of an object are called within a transaction. Examples: setPermissions
and setProperties methods in ModelObjectInterface. Some methods must be called outside
a transaction because they start a transaction internally. Example: enableLifecycle method in EkmInterface.
11.4. Using Sample Scripts Supplied by EKM

Some sample scripts that make use of EKM's scripting interface are packaged in a script library with
an EKM server. The script library is saved in the EKM_HOME/examples/conf/scripts directory
where the EKM server is installed. You can access this remote folder directly in EKM from the built-in
/Repository/Sample Files folder. The Sample Files folder is a remote folder that maps to
the EKM_HOME/examples directory and to access the scripts, just navigate to the Sample Files
folder and drill down to the conf/scripts sub-folder. See Accessing Examples and Scripts from the
Built-in Sample Files Folder for more details.
Note
The Sample Files folder is accessible only by admin users.
160
Using Sample Scripts Supplied by EKM
The scripts folder contains Python sample scripts. You can copy the macros defined in these scripts
to your custom scripts. However, you cannot reference a macro directly. Only when a script from
this directory is placed under workspace configuration control by an EKM admin user in the common
/System/Configuration/Scripts folder, will its macros be globally available in all contexts. See
the section on Configuring a Common Scripts Library in the Administration Guide for more details on
how a global script library can be configured by an admin user.
11.4.1. Python Scripts

Some Python scripts are accessible from the Repository/Sample Files/conf/scripts folder.
These include the following:
change_permissions_properties.py Script
The change_permissions_properties.py script file contains two methods. One method is to
recursively change the given object permissions for a given folder and other method is to recursively
change the given properties for a given folder.
create_groups_users.py Script
The create_groups_users.py script file contains two methods. One method is to create groups
or/and optionally add users to those groups, by reading group properties from a user given csv file,
and the other method is to create users by reading user properties from a user given csv file.
create_remotefileserver_remoteitem.py Script
The create_remotefileserver_remoteitem.py script file contains two methods. One method
is to create a Remote File Server based on given inputs and the other method is to create a Remote
Folder based on given inputs including Remote File Server input.
extract_file_data.py Script
The extract_file_data.py script file contains a method to extract all data (metadata/details report/image) for the given file.
161
extract_file_data_recursively.py Script
The extract_file_data_recursively.py script file contains two methods. One method is to
find all objects of given types recursively from a given folder, with a property status of extraction failed
and re-extracts the missing metadata and the other method is find all CAE files recursively from a given
folder, with the missing report child object and generate and add the new report child object.
test_script.py Script
The test_script.py script file contains code snippets for performing a variety of operations. If an
EKM admin user places the test_script.py file under workspace configuration control (see Configuring a Common Scripts Library), then any user can simply use the name of the macro when defining
a custom script.
11.5. Scripting Actions

Admin users can select File > Scripting to act on three types of scripts in EKM: Python scripts (.py),
BeanShell scripts (.bsh), and journal scripts or journals (.jou.bsh or .jou.py). You can use a
scripting action to dynamically record a journal script from your user interface actions, execute a
journal script on-demand, and open a command window to dynamically run any Python or BeanShell
script. These actions are described in the following sections.
11.6. Recording Journal Scripts

EKM provides you with a way to dynamically record a sequence of actions that you invoke from the
user interface in a journal script (also referred to as journal or journal file) using a scripting action.
To do this, you need to start the recording process, perform a set of actions in the user interface and
then stop recording. A journal Python script with extension .jou.py will be written to your My Data
folder (or other EKM location you designate) along with an associated _files folder which is used as
temporary storage for the script. An example of a journal script is presented in Example of Journal Recording and Execution (p. 166).
Once the journal is created, you can execute it by double-clicking the file, or right-clicking on it and
selecting Execute from the action menu. You can also choose to embed the script in a workflow, lifecycle,
162
Recording Journal Scripts

or custom type definition, use it to define a custom application or custom user interface, or execute it
on demand using the Run Journal File action from the Scripting menu.
Important
Not all actions can be recorded in a journal script in Release 15.0. Support for journaling is
currently available for the following actions:
Analysis project > update analysis
Application > execute
Case model file > create summary report
Create Custom Application
Create Workflow Definition
Edit > Copy (Copy Object)
Edit > Created By Property (Change Creator)
Edit > Custom Application (for Application objects)
Edit > EKM Server (for EKM Server objects)
Edit > Get Exclusive Control (Lock)
Edit > Group Membership (for Group objects)
Edit > Shortcut (Edit Link)
Edit > Move (Move Object)
Edit > Move (multiple objects selected: Move Multiple Objects)
Edit > Permissions (Change Permissions)
Edit > Profile (for User objects)
Edit > Properties
Edit > Release Exclusive Control (Unlock)
Edit > Remote Item (for File or Remote Folder objects)
Edit > Rename (Rename Object)
Edit > Type (Change Container Type for a Container object)
Edit > Type (Change Type)
Edit > Type (multiple objects of same type selected: Change Multiple Types)
Edit > Versioning > Add To Version Control
163

Edit > Versioning > Checkin
Edit > Versioning > Checkout
Edit > Versioning > Create Branch
Edit > Versioning > Get Copy Of Version
Edit > Versioning > Remove From Version Control
Edit > Versioning > Undo Checkout
File > Export Workspace
File > Accept Workspace Configuration
File > Apply Workspace Configuration
File > Begin Workspace Configuration
File > extract metadata
File > Revert Workspace Configuration
File > synchronize
Lifecycle > edit in Studio
New > (Child Type) (Add Catalog Content for a Catalog object)
New > EKM Server
New > Folder (Add Container for a Container object)
New > Group
New > Object (Add Object for a Container object)
New > Shortcut
New > User
Recycle bin > empty
Remote Folder > synchronize
Report > refine comparison
Saved query > execute
Saved query > refine search
Script file > execute
Settings > Alerts
164
Recording Journal Scripts

Settings > Preferences
Settings > Profile
Settings > RSM Accounts
Workflow > edit in Studio
Change Files Type
Copy Report Action in a Simulation Details Report view for a CAE file (Copy Report Object)
Create Shortcut
Delete Object
Delete Multiple Objects (multiple objects selected)
Execute Batch
Execute New DOE Run
New Connection to File/Folder on Remote Server
Synchronize (for Remote Folder objects)
11.6.1. Start Recording a Journal Script

To start recording a journal:
1.
Select File > Scripting > Record Journal. The Start Journal Recording dialog box appears:
Figure 11.1: Start Journal Recording Dialog Box
2.
Specify the folder where the journal file will be saved. The default location is My Home/My Data which
is displayed in the dialog box as /System/User Accounts/Users/USERNAME/My Data.
3.
Enter a name for the journal file.
165

4.
Click OK. When you record a journal, two objects will be written to the location you specify:
An empty journal file of type EKM Journal File with extension .jou.py that does not contain any
data because you have not recorded any actions yet.
A companion _files folder that is used as temporary storage for the recorded actions.
5.
Invoke the actions that you want to record in the journal.
11.6.2. Stop Recording a Journal Script

To stop recording a journal file, simply select File > Scripting > Stop Recording Journal.
11.7. Running Journal Scripts

You can use the Run Journal File dialog box to execute any journal script of type EKM Journal
(.jou.py or .jou.bsh) on-demand. To open the dialog box, select File > Scripting > Run Journal
File. (Figure 11.2: Run Journal File Dialog Box (p. 166))
Figure 11.2: Run Journal File Dialog Box
1.
Enter the full path to the EKM journal script you want to run or click Browse... to select the file from
the Folders tree.
2.
Click OK and the journal script will execute immediately.
Important
Any error that occurs while executing the journal will result in an unhandled exception.
Clicking Continue when such an exception occurs dismisses the exception and returns you
to the object from which the script was executed.
11.8. Example of Journal Recording and Execution

A simple example that you could try involves setting a display preference and capturing your preference
selections in a journal file. Executing the journal file would then set your preferences automatically at
any given time.
166
Running Python and BeanShell Scripts From a Command Window
Recording a Sample Journal

To record a journal in which preferences are set:
1. Start recording a journal file by selecting File > Scripting > Record Journal.
2. In the Start Journal Recording dialog, select the My Data folder as the save location, and then
specify Test Journal as the journal name. Click OK.
3. Select Settings > Preferences.
4. In the Edit Preferences dialog box, select List Display in the left pane and then enable the Lifecycle
Stage check box in the right pane to add a Lifecycle Stage column to your file list display. (Or,
make other changes to your preferences that are different than the default settings.) Click OK.
5. Stop recording the journal by select File > Scripting > Stop Recording Journal.
Testing the Sample Journal Script

To test the sample journal:
1. Select Settings > Preferences, and then click Restore Defaults in the Edit Preferences dialog box (or
return the preferences to their original state). This should remove the Lifecycle Stage column from your
file list display.
2. Select File > Scripting > Run Journal File.
3. In the Run Journal File dialog box, select the Test Journal.jou.py file in your My Data folder,
then click OK. Your preferences are automatically updated behind the scenes, and a Lifecycle Stage
column is added to your file list display.
11.9. Running Python and BeanShell Scripts From a Command Window

Admin users can use the Open Command Window Scripting action to open a command window and
define and/or execute a Python or BeanShell script on demand.
Note
A limitation of Python is that the error output from a script is displayed only in the console
of your application server (for example, JBoss 7) and does not appear in the Output log in
the Open Command Window dialog box.
To run a Python or BeanShell script:
1.
Select File > Scripting > Open Command Window. (Figure 11.3: Open Command Window Dialog
Box (p. 168))
167

Figure 11.3: Open Command Window Dialog Box
2.
Select the scripting language that you will use. Supported languages are Python and BeanShell.
3.
You can copy and paste text from a script or enter the script commands directly into the Script input
box. Click the Submit button and the script commands will be immediately processed by EKM and the
submitted script, as well as any output, will be displayed in the Output log.
4.
To load a script command file from your local file system, click Browse... and select the BeanShell or
Python script file, then click the Load button. The script will not be executed at this point, but its contents
will appear in the Script Input text box. This allows you to view and modify the commands before they
are executed. Once you are ready, you can click Submit to execute it.
168
Chapter 12: Defining Custom Dialogs, Wizards and Applications

This chapter provides information on how you can enhance the standard EKM features by creating
custom user interfaces such as dialog boxes and wizards, as well as custom applications that utilize
these interfaces in EKM.
This chapter describes in defining custom dialog boxes XHTML:
12.1. Defining Custom Dialog Boxes
12.2. Steps for Creating and Using Custom Applications
12.3. Creating a Custom Application
12.4. Executing a Custom Application
12.5. Modifying an EKM Application
12.1. Defining Custom Dialog Boxes

EKM enables you to create custom dialog boxes for the web user interface. These dialog boxes can be
used in the following contexts:
Action Menus: You can define new actions for custom types and built-in types. These actions can
be executed using the action menu. If the action requires any user input then you will need to show
a dialog box when the action menu is clicked.
Workflows: By default, EKM shows an automatically generated dialog box for Work Item completion
and batch execution. But you could define a custom dialog box to be used in its place, especially if
you want more control over the work item is presented.
Custom Applications: You will need to define a dialog box for any custom application. This dialog
box is shown when the custom application is executed in the web user interface.
There are two aspects to defining a custom dialog box:
Defining the user interface of the dialog box in XHTML files
Defining the dialog box's steps and variables in a macro.
12.1.1. Defining a Custom User Interface

EKM's user interface is designed using web technologies such as XHTML and JSF. You can utilize these
technologies when you want to define a custom user interface such as a dialog box or wizard that can
open when an action, workflow, or custom application is invoked.
XHTML: Dialog boxes are defined using XHTML syntax. See XHTML Files (p. 171) for details.
JSF: Java Server Faces (JSF) is a new standard for developing web-based applications. It introduces tags
that can be used in XHTML files. These tags can be used to provide complex user interface components
(such as calendar, tree, and so on) that are not directly supported by HTML. Some components have builtin AJAX support to increase user interface responsiveness and interactivity. In addition, these tags are
used to bind the values specified in the user interface to some variables defined in the back-end. This
169
Defining Custom Dialogs, Wizards and Applications

binding enables JSF to automatically fill the values of the variables with user inputs when the form is
submitted. The tags that can be used depend on the JSF component libraries loaded by the system. EKM
uses the following JSF component libraries: MyFaces Core 2.1.8, Tomahawk 201.1, and RichFaces 4.2.2.
Refer to http://myfaces.apache.org/ for more information on MyFaces and Tomahawk libraries. Refer to
http://www.jboss.org/richfaces for more information on the RichFaces libraries.
Note
If you use custom applications and JSF validation tags, you need to provide a label so that
the validation protocols can apply a proper error message to the custom application. In the
example that follows, the error message is missing the label of the field that has an invalid
entry.
Figure 12.1: A Faulty Error Message in a Custom Application
Variable names used in a custom application should always be a valid java identifier. For
example, a variable cannot have a name that is a reserved word such as "boolean".
170
Defining Custom Dialog Boxes

If you are new to XHTML, CSS, JavaScript and JSF, then it may feel a little overwhelming to understand
all of the technologies and languages at first. Indeed, the possibilities offered by these technologies
are very extensive making them both powerful and complex. However, if you have a basic understanding
of HTML, the documentation and examples provided in this chapter will enable you to create a basic
user interface.
12.1.1.1. XHTML Files

XHTML files are XML files that support all of the tags (for example, div, span, table, br, img, and
so on) and attributes (for example, style, class, and so on) of HTML. This syntax enables you to
have complete freedom when designing the layout and presentation of a dialog box. You can create
tables, use different font styles and sizes, embed custom images, and so on. If needed, you can also
utilize CSS to specify styles for user interface components and JavaScript to provide dynamic behavior.
All of the XHTML files that you create must have the .xhtml file extension and contain the following:
header
body
footer
Sample XHTML Code for a Custom Dialog Box (p. 172) contains a full listing for an XHTML file for a
sample custom dialog box. Figure 12.2: Sample Custom Dialog Box (p. 172) shows how the dialog box
is displayed in the EKM user interface. The file defines common user interface components and can be
used as a template to define any custom dialog box.
Header
An XHTML must start with the header:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:t="http://myfaces.apache.org/tomahawk"
xmlns:ui="http://java.sun.com/jsf/facelets"
xmlns:ing="http://www.ansys.com/ingress/spdm"
xmlns:a4j="https://ajax4jsf.dev.java.net/ajax"
xmlns:rich="http://richfaces.org/rich">
<body>
<ui:component>
Body
In between the header and footer, you may insert any HTML or JSF tag in the XHTML file to define the
user interface components. See User Interface Components (p. 174) for details.
Footer
An XHTML must end with the footer:
</ui:component>
</body>
</html>
171
12.1.1.2. Sample XHTML Code for a Custom Dialog Box

The sample XHTML code shown below defines a custom dialog box that is displayed in the EKM user
interface as Figure 12.2: Sample Custom Dialog Box (p. 172).
The dialog box uses common user interface components such as check boxes, selection lists, and so
on that can be used as a template when you define any custom dialog box. The variables for the dialog
box are defined in a separate initialization macro named init that EKM uses to create the dialog box.
Figure 12.2: Sample Custom Dialog Box
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:t="http://myfaces.apache.org/tomahawk"
xmlns:ui="http://java.sun.com/jsf/facelets"
xmlns:ing="http://www.ansys.com/ingress/spdm"
xmlns:a4j="https://ajax4jsf.dev.java.net/ajax"
xmlns:rich="http://richfaces.org/rich">
<body>
<ui:component>
<div style="text-align: center; font-size: large">
Sample Dialog<br/>
<span style="color: red">For Displaying Common UI Components</span>
172

</div>
<div style="padding-top: 10px; padding-bottom: 10px; width: 100%">
<table>
<tr>
<td>File upload:</td>
<td>
<t:inputFileUpload size="60" value="#{custom.vars.file.value}"/>
</td>
</tr>
<tr>
<td>Reference selection:</td>
<td>
<ing:inputCustomReference size="60" referenceVar="reference"/>
</td>
</tr>
</table>
</div>
<table>
<tr>
<td><h:graphicImage value="#{custom.url}/tank.jpg" /></td>
<td>
<table style="padding-left: 10px; width: 250px">
<tr>
<td>String Entry:</td>
<td>
<h:inputText value="#{custom.vars.string.value}" />
</td>
</tr>
<tr>
<td>Integer Entry:</td>
<td>
<h:inputText value="#{custom.vars.integer.value}">
<f:validateLongRange minimum="0" maximum="10"/>
</h:inputText>
</td>
</tr>
<tr>
<td>Real Entry:</td>
<td>
<h:inputText value="#{custom.vars.real.value}" />
</td>
</tr>
<tr>
<td>Date:</td>
<td>
<rich:calendar value="#{custom.vars.date.value}"
datePattern="MMM d, yyyy HH:mm"
enableManualInput="true" />
</td>
</tr>
<tr>
<td>Check box:</td>
<td>
<h:selectBooleanCheckbox value="#{custom.vars.boolean.value}" />
</td>
</tr>
<tr>
<td>Radio buttons:</td>
<td>
<h:selectOneRadio value="#{custom.vars.radio.value}"
layout="lineDirection">
<f:selectItem itemValue="Radio 1"/>
</h:selectOneRadio>
</td>
</tr>
<tr>
<td>Select menu:</td>
<td>
<h:selectOneMenu value="#{custom.vars.menu.value}">
<f:selectItems value="#{custom.vars.menu.optionItems}"/>
</h:selectOneMenu>
173

</td>
</tr>
<tr>
<td>List box:</td>
<td>
<h:selectManyListbox value="#{custom.vars.listBox.value}">
<f:selectItem itemValue="List Option 1"/>
</h:selectManyListbox>
</td>
</tr>
</table>
</td>
</tr>
</table>
</ui:component>
</body>
</html>
12.1.1.3. User Interface Components

This section defines syntax for common user interface components for a custom dialog box that are
defined in the body of the XHTML file. Refer to Sample XHTML Code for a Custom Dialog Box (p. 172)
for the full listing of the XHTML file that generates the sample dialog box shown in Figure 12.2: Sample
Custom Dialog Box (p. 172).
12.1.1.3.1. Layout and Style

You can define the layout and style of a dialog box using any HTML tag and attributes. For the example
dialog box (Figure 12.2: Sample Custom Dialog Box (p. 172)) the label at the top of the dialog box is
defined using the plain HTML code fragment:
<div style="text-align: center; font-size: large">
Sample Dialog<br/>
<span style="color: red">For Displaying Common UI Components</span>
</div>
You can also use an HTML table to display an image and other controls, side by side.
12.1.1.3.2. Embedded Images

The graphicImage setting can be used to embed an image in a dialog box. The value attribute
specifies the path of the image file. You must specify #{custom.url}/ at the start. This will make
sure that the path starts with the location of the expanded resource archive in the custom resources
folder. After that, you need to specify the relative path of the image in the resource archive.
<h:graphicImage value="#{custom.url}/tank.jpg" />
For the sample dialog box (Figure 12.2: Sample Custom Dialog Box (p. 172)), tank.jpg is at the toplevel of the resources folder, so the full path becomes: #{custom.url}/tank.jpg.
12.1.1.3.3. User Inputs

Except for a reference selection, all elements that capture user inputs must have a value attribute.
This attribute points to the value of the variable defined in the initialization script that stores the user
input. The common syntax to specify the value is: #{custom.vars.varName.value}, where
varName is the name of the variable defined in the initialization script. In this case the name of the
variable is string.
174
String Input
The inputText setting can be used to define a text box for capturing string input in a dialog box, as
shown in the following code fragment:
<h:inputText value="#{custom.vars.string.value}" />
Except for a reference selection, all elements that capture user inputs must have a value attribute.
This attribute points to the value of the variable, defined in the initialization script, that stores the user
input. The common syntax to specify the value is: #{custom.vars.varName.value}, where
varName is the name of the variable defined in the initialization script. In this case the name of the
variable is string.
Integer Input
The inputText setting can be used to define a text box for capturing integer input in a dialog box,
as shown in the following code fragment:
<h:inputText value="#{custom.vars.integer.value}">
<f:validateLongRange minimum="0" maximum="10"/>
</h:inputText>
The value attribute must point to a variable of type long in the initialization script. In this case, the
name of the variable is integer. If required, you can also specify minimum and/or maximum values
for the integer as shown above with the f:validateLongRange tag. This is optional and if its not
specified, the integer will not have any minimum or maximum value.
Real Number Input

The inputText setting can be used to define a text box for capturing real number input in a dialog
box, as shown in the following code fragment:
<h:inputText value="#{custom.vars.real.value}" />
The value attribute must point to a variable of type double in the initialization script. In this case
the name of the variable is real. If required, you can also specify minimum and/or maximum values
for the real number as shown above for integer inputs. This is optional and if it is not specified, the real
number will not have any minimum or maximum value.
Date Input
The rich:calendar setting can be used to define a text box for capturing date and time input in a
dialog box, as shown in the following code fragment:
<rich:calendar value="#{custom.vars.date.value}"
datePattern="MMM d, yyyy HH:mm"
enableManualInput="true" />
The value attribute must point to a variable of type Date in the initialization script. In this case the
name of the variable is date. The datePattern attribute specifies the format in which the date will
be displayed or entered manually. The enableManualAttribute specifies whether manual date
input is allowed or not. Refer to the RichFaces documentation for information about this component
and to learn about additional attributes.
Reference Selection
The inputCustomReference setting can be used to define a combination text box and browse
button for selecting a reference to another object in EKM, as shown in the following code fragment:
175

<ing:inputCustomReference size="60" referenceVar="reference"/>
The referenceVar attribute specified the name of the reference variable defined in the dialog boxs
macro. In this case the name of the variable is reference. You can control the size of the text box
using size or width attributes.
File Selection
The inputFileUpload setting can be used to define a combination text box and browse button for
selecting a file to upload to EKM, as shown in the following code fragment:
<t:inputFileUpload size="60" value="#{custom.vars.file.value}"/>
The value attribute must point to a variable of type VARIABLE_TYPE_FILE in the initialization
script. In this case the name of the variable is file.
12.1.1.3.4. Check Boxes

The selectBooleanCheckbox setting can be used to define a check box in a dialog box, as shown
in the following code fragment:
<h:selectBooleanCheckbox value="#{custom.vars.boolean.value}" />
The value attribute must point to a boolean variable in the initialization script. For the example
dialog box (Figure 12.2: Sample Custom Dialog Box (p. 172)) the name of the variable is boolean.
12.1.1.3.5. Radio Buttons

The selectoneRadio setting can be used to define a radio button group in a dialog box, as shown
in the following code fragment:
<h:selectOneRadio value="#{custom.vars.radio.value}"
layout="lineDirection">
</h:selectOneRadio>
The value must point to a string variable defined in the initialization script. For the example dialog
box (Figure 12.2: Sample Custom Dialog Box (p. 172)), the name of the variable is radio. The layout
attribute specifies whether radio buttons are displayed horizontally (using the lineDirection value)
or vertically (using the pageDirection value). The options for the radio button are specified using
the f:selectItem tags as shown above. Instead, you can use the f:selectItems tag to specify
the variable options in the dialog boxs macro. See Selection Menu for an example of the f:selectItems tag.
12.1.1.3.6. Selection Menu

You can define a selection menu or drop-down list in a dialog box using the selectOneMenu setting.
The value attribute must point to a string variable defined in the dialog boxs script. The common
syntax for specifying the value is #{custom.vars.varName.optionItems}, where varName
is the name of the variable. The options for the menu can be specified as either f:selectItems or
f:selectItem. If you are using f:selectItems, the value attribute must point to the options
defined for the variable in the dialog boxs macro.
<h:selectOneMenu value="#{custom.vars.menu.value}">
<f:selectItems value="#{custom.vars.menu.optionItems}"/>
</h:selectOneMenu>
176

In this case the name of the variable is menu.
12.1.1.3.7. List Box

A list box can be defined using the selectManyListbox setting.
<h:selectManyListbox value="#{custom.vars.listBox.value}">
</h:selectManyListbox>
The value attribute must point to a string variable defined in the initialization script. In this case the
name of the variable is listBox. If the variable is defined as multi-valued, the list box will allow multiple
selections. Otherwise only a single selection is allowed. The options for the list box are specified using
the f:selectItem tags as shown above. Instead of this, you can use f:selectItems tag to specify
the variable options for the dialog boxs macro. See Selection Menu for an example of the f:selectItems tag.
12.1.2. Defining Dialog Box Steps and Variables

When you define a dialog box, you first need to define a macro that specifies the following:
The steps contained in the dialog box. Dialog boxes can either have a single step or have multiple
steps (for example, in case of wizards). For each step you would need to specify the header of the
step and the XHTML file that provides the interface for that step. For the last step you would also
need to specify the execution macro that will be called when the dialog box is submitted. This macro
is used to process the user inputs and then execute some commands.
The variables used by the dialog box. Variables are used to store the inputs specified by the user
in the dialog box. These variables can then be accessed by the execution macro to retrieve the user
inputs and act upon them.
The following code snippet shows how dialog boxes can be defined in a macro. This file is provided in
the examples folder in your EKM server installation: EKM_HOME/examples/custom-apps.
init(dialog) {
dialog.addStep("Test Variables", "test-variables.xhtml", "action");
dialog.addVar("file", dialog.VARIABLE_TYPE_FILE, null, false);
referenceVar = dialog.addVar("reference", dialog.VARIABLE_TYPE_REFERENCE, "", false);
referenceVar.setReferenceType("Folder");
referenceVar.selectOnlyModifiableFolders(true);
dialog.addVar("string", dialog.VARIABLE_TYPE_STRING, "Hello World", false);
dialog.addVar("integer", dialog.VARIABLE_TYPE_LONG, 10, false);
dialog.addVar("real", dialog.VARIABLE_TYPE_DOUBLE, 1.2345, false);
dialog.addVar("date", dialog.VARIABLE_TYPE_DATE, Calendar.getInstance().getTime(), false);
dialog.addVar("boolean", dialog.VARIABLE_TYPE_BOOLEAN, true, false);
dialog.addVar("radio", dialog.VARIABLE_TYPE_STRING, "Radio 2", false);
menuVar = dialog.addVar("menu", dialog.VARIABLE_TYPE_STRING, "Menu Option 2", false);
menuOptions = new LinkedList();
menuOptions.add("Menu Option 1");
menuVar.setOptions(menuOptions);
dialog.addVar("listBox", dialog.VARIABLE_TYPE_STRING, new String[]
{"List Option 1", "List Option 2"}, true);
}
177

The name of the macro is init and it takes a single argument dialog box that is an instance of DialogInterface.
The first line of the macro adds a step to the dialog box as follows:
dialog.addStep("Test Variables", "test-variables.xhtml", "action");
The first argument is the header and will be shown in the Title Bar of the dialog box when it is opened
in the web user interface.
The second argument is the path of the XHTML file that defines the user interface for this step. The
path can be either relative or absolute. An absolute path is used primarily for defining action dialog
boxes for custom types. The location of the XHTML files (and other resource files used in the user interface
such as images, CSS files, JavaScript files, and so on) is dictated by the customResourcesPath setting
in ekm.xml and is by default EKM_HOME/conf/resources. The XHTML file for the custom type
dialog box can be placed in any sub folder in the custom resources folder. You can then use the path:
/custom/<relative path of file in custom resources folder> to refer to the XHTML
file in the custom resources folder. Workflows and custom applications can be added or modified dynamically to EKM by any user who may or may not have access to EKM servers file system. EKM handles
this issue in the following ways:
The user interface resource files needed for custom applications and workflows are added as an
archive (in .zip, .tar, or .tar.gz formats).
The resources archive is made a child of the workflow or custom application object in EKM.
When a custom dialog box needs to be opened, the resource archive is extracted to a specific location.
This location is:
path-to-custom-resources_folder/_custom_resource_cache_/id-of-theobject
where id-of-the-object refers to the internal ID of the object in EKM. It is used to store
the resource files from different custom applications and workflows in a separate folder.
Because you do not know the ID of an object before it has been added to EKM, you cannot use the
absolute path to specify XHTML files for custom applications and workflow dialog boxes. You can,
however, specify a relative path and behind the scenes EKM will create the full path before the dialog
box is opened. User interface resources are contained in an archive, and the relative path will depend
on the path of the XHTML file in the archive. If the file is at the top level of the archive, then you can
simply specify the file name (for example, test-variables.xhtml). However, if the file is in a folder
then you will need to specify the name of the parent folder too (for example, folder-name/testvariables.xhtml).
The third argument is the name of the action macro that will be called when the dialog box is submitted.
For a multistep wizard, you need to specify only the execution macro in the last step.
The addStep() method returns an instance of DialogStepInterface.
Once the steps have been specified you can then add the variables used in the dialog box. This is done
using the addVar() method of the DialogInterface as shown in the following line:
dialog.addVar("string", dialog.VARIABLE_TYPE_STRING, "Hello World", false);
178
Steps for Creating and Using Custom Applications

The first argument is the name of the variable, the second argument is the type of the variable, the
third argument is the default value and the fourth argument specifies whether the variable is multivalued or not. The following types can be specified:
VARIABLE_TYPE_LONG: For integers
VARIABLE_TYPE_DOUBLE: For real numbers
VARIABLE_TYPE_BOOLEAN: For Boolean (true/false) values
VARIABLE_TYPE_STRING: For strings
VARIABLE_TYPE_DATE: For date and time
VARIABLE_TYPE_REFERENCE: For reference to other objects in EKM
VARIABLE_TYPE_FILE: For files that are uploaded to EKM
The default value will depend on the type of the variable. For VARIABLE_TYPE_DATE, it must be an
instance of java.util.Date class. You can set the default to the current time by calling Calendar.getInstance().getTime(). For VARIABLE_TYPE_FILE the default must be null. For multivalued variables, the default value must be a list. For example:
dialog.addVar("listBox", dialog.VARIABLE_TYPE_STRING, new String[]
{"List Option 1", "List Option 2"}, true);
In the above line, the variable listBox is a multi-valued variable whose default value is a list with two
elements: List Option 1 and List Option 2.
The addVar() method returns the newly added variable, which is an instance of the VariableInterface. You can use this instance to specify some additional attributes that cant be specified in the
addVar() method. For example, for reference variables you can specify the type of objects to be selected using the setReferenceType() method of ReferenceVariableInterface as shown
in the following snippet. Here we are setting the type to Folder, this means that users will only be able
to select Folder objects for this variable:
referenceVar = dialog.addVar("reference", dialog.VARIABLE_TYPE_REFERENCE, "", false);
referenceVar.setReferenceType("Folder");
Similarly you can specify the options for any variable using the setOptions() method as shown in
the following snippet. Here we are setting 3 options: Menu Option 1, Menu Option 2, and Menu
Option 3.
menuVar = dialog.addVar("menu", dialog.VARIABLE_TYPE_STRING, "Menu Option 2", false);
menuOptions = new LinkedList();
menuVar.setOptions(menuOptions);
12.2. Steps for Creating and Using Custom Applications

Follows these steps to create and use custom applications:
1. Create custom application files in a scripting language or in Java that defines the application. For a scriptbased application, this will include back-end logic for executing the application as well as a resource
archive for defining the front-end user interface.
179

2. Create a new application for the custom application files by clicking the Create Custom Application
icon in the Applications folder. Once you have filled in the dialog box and clicked OK, the new
custom application you set up will be saved as an EKM Application type object and placed in the folder
you specified.
3. Navigate to the folder the custom application is saved to and execute it by double-clicking on it. The
user interface dialog box that is defined for the application will open, allowing you to input values.
12.3. Creating a Custom Application

Sample files will be used to demonstrate how a new custom application is created in EKM. The script
file is named mixing-tank-simulation.py and the resource archive is named mixing-tanksimulation.zip. You will need to download these files to your local computer. They are located in
the following folder: EKM_HOME/Sample Files/custom-apps.
Note that the Create Custom Application item is only available to admin users.
To create a custom application:
1.
In the navigation pane, select the Applications folder, and then click the Create Custom Application
icon in the file list window.
This will open the Create Custom Application dialog box (Figure 12.3: Create Custom Application
Dialog Box (p. 181)).
180
Executing a Custom Application

Figure 12.3: Create Custom Application Dialog Box
2.
In the Application name edit box, type Mixing Tank Simulation.
3.
next to the Application folder edit box and then select the repository folder where
Click
you would like to save the application. For easy access you may want to save it in the My Home/My
Applications folder or the System/Shared Applications folder.
4.
Click
under Script file to select a script file for the application. Select the sample mixingtank-simulation.py file on your local system. This is the script file that provides the back-end of
the application.
5.
In the Macro name for dialog creation edit box, enter init for the macro name that creates the
custom user interface dialog box. This is the name of the macro that is defined in the script file.
6.
Click
under Resource archive to select the archive file (.zip, .tar or .tar.gz) that
contains the user interface resources needed to define the front-end user interface. Select the mixingtank-simulation.zip archive file on your local system.
7.
Click OK. The application named Mixing Tank Simulation of type EKM Application will be created
and added to the repository folder that you specified.
12.4. Executing a Custom Application

To execute a custom application, navigate to the folder where it is stored and double-click it. You can
also right-click the application and select Execute from the context menu.
You can also launch a custom application from the Applications folder by clicking on its associated
icon. You may need to filter the view in the file list window to be able to see the application. For example,
if you did not save the application in the My Applications or Shared Applications folder,
181

selecting All Applications from the Show drop box will display applications from all repository applications.
The custom user interface that opens will vary depending on the application. When you click OK in the
custom application dialog box, the inputs that you have specified in the dialog box will be processed
by the back-end, and the desired operations will be executed before the dialog box is dismissed.
Figure 12.4: Custom Mixing Tank Simulation Dialog Box (p. 183) shows the dialog box of the mixing tank
custom application created in the previous step. When you click OK, Fluent launches in the background
and simulates the mixing tank using the parameters you supplied. Note that for this example, the Fluent
solver application must be defined (without the -post command line parameter).
182
Executing a Custom Application

Figure 12.4: Custom Mixing Tank Simulation Dialog Box
A job object is created for the simulation process in My Jobs, where you can monitor its status.
You can then navigate to the output folder you specified and review the Simulation Details Report that
was created for the simulation. This is shown below in Figure 12.5: Report for Custom Mixing Tank
Simulation (p. 184).
183

Figure 12.5: Report for Custom Mixing Tank Simulation
12.5. Modifying an EKM Application

Sometimes you may find it necessary to modify the front-end (user interface) or back-end (script) of an
application. You can do this by editing the custom application.
184
Modifying an EKM Application

To edit a custom application:
1.
Select the custom application in the folder where it was saved, and then right-click and select Edit >
Application from the context menu. This will open the Edit Custom Application dialog box. (Figure 12.6: Edit Custom Application Dialog Box for Custom EKM Application (p. 185))
Figure 12.6: Edit Custom Application Dialog Box for Custom EKM Application
2.
To select a new script file, or reload the script file if it has changed, click
3.
Change the name of the macro for dialog box creation, if required.
4.
If the user interface has changed, click

under Resource archive and select the new archive
(.zip, .tar or .tar.gz) for user interface resources.
5.
Click OK. The changes will be applied to the application and will take effect the next time that you execute the application.
under Script file.
185
186
Chapter 13: Units: Defining and Configuring Using XML

EKM enables you to assign units to properties when you are defining a custom type. Units for built-in
types, however, are stored in a consistent system within the database and cannot be changed internally.
You can however, add units for built-in types that will display property values in the units that are
defined. Note that this only affects the presentation of property values in the user interface and not
the actual values that are stored.
The following terms are used for describing unit functionality in EKM:
quantity: This refers to a physical quantity that can be measured in various units. For example,
length is a quantity that can be measured in various units such as m, f, and so on.
unit: This refers to the unit of measurement of a physical quantity. For example, m and ft are units
for the quantity length.
unit system: This refers to a consistent set of units for measuring various quantities. For example,
SI, British, and so on.
Units are defined for a particular workspace in the Units.xml file in the /System/Configuration
folder. This chapter describes the Units.xml file and explains how you can add units, quantities, and
unit systems that are displayed in the user interface. Changes to this file can be made only in restricted
configuration mode. Refer to Restricted Configuration (p. 31) for details on how you can start and end
the restricted configuration mode.
You can use the units and quantities defined in the Units.xml file to define properties of type Double
in custom types described in Defining Properties Using XML (p. 85). You can assign a quantity and
a unit for each Double property. If you assign a quantity and not a unit, then the property value
will be shown in the preferred unit system that is defined for the user in their preferences. Refer to the
Setting User Profiles and Preferences chapter in the EKM User's Guide for details.
The overall process for defining a unit XML file and configuring it for a workspace is as follows:
Download the unit definition file (Units.xml) and add a unit, quantity or unit system using the
schema definition for units and an XML editor.
Start restricted workspace configuration mode if it has not already been started. See Starting Restricted
Configuration (p. 32).
Upload the unit file using the Upload > Files/Archives Using the Browser method to the /System/Configuration folder.
Accept the workspace configuration. See Accepting the Configuration (p. 34).
The remainder of this chapter presents information on how to define new units in EKM using XML.
Topics include:
13.1. Schema Definition for Units
13.2. Adding a New Unit
187
Units: Defining and Configuring Using XML

13.3. Adding a New Quantity
13.4. Adding a New Unit System
13.1. Schema Definition for Units

EKM provides schema files for all files that you define using XML. These XML Schema Definition (XSD)
files describe the structure or "grammar" that an XML document must adhere to. Schema definitions
provide the building blocks that enable you to write valid XML configuration files for use in EKM. For
more information on how to read schema files, refer to: http://www.w3.org/TR/xmlschema-0.
XSD files are contained in the EKM_HOME/schema folder and are identified by the .xsd extension.
Important
EKM_HOME is the directory where the EKM server application is installed. This is typically
EKM_BASE/ekm-server, where EKM_BASE is the EKM base directory.
Figure 13.1: Partial Listing of units.xsd Schema Definition (p. 188) shows the partial listing for units.xsd,
the XML schema definition (XSD) that is used for defining units in EKM. The complete listing is provided
in the EKM_HOME/schema folder.
Figure 13.1: Partial Listing of units.xsd Schema Definition
targetNamespace="http://www.ansys.com/ekm/units"
xmlns:ekmUnits="http://www.ansys.com/ekm/units">
<xsd:complexType name="Unit">
<xsd:attribute name="multFactor" type="xsd:double" use="required" />
<xsd:attribute name="addFactor" type="xsd:double" use="optional" />
</xsd:complexType>
<xsd:complexType name="Quantity">
<xsd:sequence>
<xsd:element name="unit" type="ekmUnits:Unit" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="Quantities">
<xsd:sequence>
<xsd:element name="quantity" type="ekmUnits:Quantity" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="UnitSystemQuantity">
<xsd:attribute name="unit" type="xsd:string" use="required" />
</xsd:complexType>
EKM also supplies a default Units.xml file that contains some predefined units, quantities, and unit
systems. The schema listing in Figure 13.1: Partial Listing of units.xsd Schema Definition (p. 188) show
that the units file consists of a root element named units and has the following child elements:
quantities: contains a list of quantity element as children. Each quantity element has a list
of units elements as children.
unitSystems. This has a list of unitSystem element as children. Each unitSystem element has
a list of quantity elements as children.
188
Adding a New Unit

Figure 13.2: Partial Listing of Units.xml (p. 189) shows a partial listing of the Units.xml file. The complete
listing can be found in the EKM_HOME/conf folder in your EKM server setup, or in the /System/Configuration folder in the EKM repository.
Figure 13.2: Partial Listing of Units.xml
<ekmUnits:units xmlns:ekmUnits="http://www.ansys.com/ekm/units"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ansys.com/ekm/units ../schema/units.xsd">
<quantities>
<quantity name="forcePerArea">
<unit name="N/m2" multFactor="1.000000"/>
<unit name="lbf/ft2" multFactor="47.890000"/>
<unit name="dyn/cm2" multFactor="0.100000"/>
</quantity>
<quantity name="massTransferRate">
<unit name="kgmol/m3-s" multFactor="1.000000"/>
<unit name="kgmol/cm3-s" multFactor="1000000.000000"/>
<unit name="kgmol/ft3-s" multFactor="35.314725"/>
</quantity>
<quantity name="force">
<unit name="N" multFactor="1.000000"/>
<unit name="dyn" multFactor="0.000010"/>
<unit name="kgf" multFactor="9.806805"/>
<unit name="tonf" multFactor="9964.129140"/>
<unit name="lbf" multFactor="4.448200"/>
<unit name="ozf" multFactor="0.278020"/>
<unit name="pdl" multFactor="0.138260"/>
</quantity>
<quantity name="energy">
<unit name="J" multFactor="1.000000"/>
<unit name="kgf-m" multFactor="9.806800"/>
<unit name="erg" multFactor="0.000000"/>
<unit name="kWh" multFactor="3600000.000000"/>
<unit name="BTU" multFactor="1055.040000"/>
<unit name="hp-h" multFactor="2684500.000000"/>
<unit name="ft-lbf" multFactor="0.135600"/>
<unit name="kcal" multFactor="4186.800000"/>
<unit name="cal" multFactor="4.186800"/>
</quantity>
13.2. Adding a New Unit

Units are defined within the quantity element in Units.xml. Figure 13.3: Quantity and Unit Definition (p. 189) demonstrates how units are defined for the temperature quantity. To add a new unit to
an existing quantity, simply add a new unit element with the following attributes:
name: This is the name of the unit. For example, C is the name for centigrade unit in Figure 13.3: Quantity and Unit Definition (p. 189).
multFactor: This is the factor that needs to be multiplied to the unit value to convert it to SI. For
example, 1R = 0.555556K. SI units will always have multFactor equal to 1.0.
addFactor: This is an optional attribute that needs to be added to the unit value to convert it to
SI. For example, 1C = (1+273.15)K. If the addFactor is not specified it is assumed to be 0.0.
Figure 13.3: Quantity and Unit Definition
<quantity name="temperature">
<unit name="K" multFactor="1.000000"/>
<unit name="C" multFactor="1.000000" addFactor="273.150000"/>
<unit name="R" multFactor="0.555556"/>
<unit name="F" multFactor="0.555556" addFactor="459.670000"/>
</quantity>
189
Units: Defining and Configuring Using XML
13.3. Adding a New Quantity

You can add a new quantity to Units.xml by doing the following:
Add a new quantity element to the units/quantities element. This element must have an attribute
name that holds the value of the quantitys name and contains a list of child unit elements. See Figure 13.3: Quantity and Unit Definition (p. 189) for a sample quantity listing.
Add the quantity to the various unitSystem elements. This is used to specify the unit to be
used for that quantity in each unit system. See Figure 13.4: Unit System (p. 190) for an example of
quantity elements within a unitSystem element.
13.4. Adding a New Unit System

You can add a new unit system by adding a new unitSystem element to the units/unitSystems
element. This element must have an attribute name that holds the value of unitSystem name. It may
also have an optional attribute baseSystem that refers to the base unit system to use if a requested
quantity is not found in the current unit system. If this attribute is not specified, the base system is assumed to be SI. This attribute is useful if you want to create a new unit system that only differs in some
minor ways from an existing system. In this case, you only need to specify the quantities that differ
from the base system in the new unit system.
The unitSystem element also has a number of child quantity elements. Each quantity element
has attributes name and unit. This specifies the unit name to be used for a particular quantity. For
example, Figure 13.4: Unit System (p. 190) shows a sample listing for a unitSystem named British. The
unit for the quantity energy is BTU. Thus if the user has specified the British unit system as the preferred
unit system in their user preferences, then the value of property with quantity energy will be displayed
in BTU units.
Figure 13.4: Unit System
<unitSystem name="British">
<quantity name="forcePerArea" unit="lbf/ft2"/>
<quantity name="massTransferRate" unit="kgmol/ft3-s"/>
<quantity name="force" unit="lbf"/>
<quantity name="energy" unit="BTU"/>
190
Chapter 14: Transferring a Workspace Between EKM Servers

EKM provides administrative users with the ability to copy a workspace from one EKM server to another.
This is useful, for example, when you want to upgrade from an Evaluation to a Production server and
you want to migrate an entire workspace to the new server.
Transferring a workspace involves exporting the workspace on the source server and then importing
the exported workspace on the destination server.
14.1. Exporting a Workspace

You can use the Export Workspace feature in EKM to easily export an entire workspace. When a
workspace is exported, an exact copy is made that includes users/groups, configuration, data, controls,
and so on.
Note
Workspace exports can be performed by any member of the admin group.
To export a workspace:
1.
Select File > Export Workspace. The Export Workspace dialog box appears:
2.
Specify a folder to be created for the exported workspace on the destination server. To do this, enter
an absolute path to the folder on the servers file system. For example, if you enter C:\ekm150\ekmserver\WorkspaceExport, a folder named WorkspaceExport will be created on the server, and
the workspace will be exported to that folder. Note that you cannot export to an existing folder.
3.
Click OK. The workspace is exported to the specified folder.
191
Transferring a Workspace Between EKM Servers
14.2. Importing a Workspace

An exported workspace can be imported into another EKM server when a new workspace is being created
on that server. Workspace creation is performed in the EKM Administrative Interface. Follow the instructions in Creating a New Workspace from an Exported Workspace (p. 21).
192
Chapter 15: Miscellaneous Tasks

This chapter presents information on how to perform miscellaneous administrative tasks in EKM such
as gathering usage statistics, connecting to remote file servers, managing logs, adding visualization
support using VCollab, and using the EKM Server Diagnostics tool to capture information about your
EKM installation that can be sent to the support person working on your case. Topics include:
15.1. Configuring a Common Scripts Library
15.2. Gathering Usage Statistics
15.3. Remote File Servers
15.4. Managing Logs
15.5. Installing VCollab and Configuring EKM for 3D Visualization
15.6. Using the EKM Server Diagnostics Tool
15.7. Lifecycle Approval Process for Workflows
15.1. Configuring a Common Scripts Library

You can build a script library that contains global scripts by placing the script in the /System/Configuration/Scripts folder.
Some sample scripts that make use of EKM's scripting interface are packaged in the EKM_HOME/examples/conf/scripts directory where the EKM server is installed. This folder is referenced by a
built-in remote folder named /Repository/Sample Files. You can place any or all of these scripts
in the common /System/Configuration/Scripts folder for it to be globally available in all
contexts.
Important
Scripts that are defined in the /System/Configuration/Scripts folder cannot access
the global ekm variable that is used in EKM's scripting interface. Therefore, this variable will
need to be passed as an argument if a script needs to use it.
The overall process for configuring a scripts library for a workspace is as follows:
Start restricted workspace configuration mode if it has not already been started. See Starting Restricted
Configuration (p. 32).
Upload the script to the /System/Configuration/Scripts folder or copy it from an existing
location in the Repository.
Accept the workspace configuration. See Accepting the Configuration (p. 34).
15.2. Gathering Usage Statistics

The File > Create Usage Report action item that is invoked from the Menu bar enables EKM system
administrators to create a report showing the EKM usage for each user. This report provides valuable
information such as the amount of data being transferred that can help you in your resource planning.
193
Miscellaneous Tasks
The usage report presents details on how many times a user has logged in, number of bytes uploaded
or downloaded, the number of searches executed and the number of workflows or custom applications
executed. It keeps a record of the last 12 months and keeps track of the cumulative usage for each
user.
Note
Table titles in reports are not localized.
15.3. Remote File Servers

EKM provides users with the capability to remotely connect to files and folders that are hosted on any
server type (such as a file server, database, proprietary data management system, and so on) in a generic way. Currently only off-the-shelf support for file servers is provided.
When a new connection to a file or folder in a remote server is made, EKM creates a soft reference to
the remote file/folder and extracts metadata from it that can be used for report generation, searching,
and so on. However, before a user can create a remote file or folder connection, an EKM administrator
must define the remote file server in EKM. This is done from the System/Remote File Servers
folder using the New Remote File Server dialog box. You can do this following the instructions below
in Defining a New Remote File Server (p. 194). There are also two remote file servers that are built-in to
EKM and are already defined. See Built-in Remote File Servers (p. 196) for details.
15.3.1. Defining a New Remote File Server

To utilize an existing built-in remote file server, see Built-in Remote File Servers (p. 196).
To add a new remote file server to EKM,
1.
194
Select the Remote File Server folder under System, right-click, and select New > Remote File
Server. This will open the New Remote File Server dialog box. (Figure 15.1: New Remote File Server
Dialog Box (p. 195))
Remote File Servers

Figure 15.1: New Remote File Server Dialog Box
2.
Enter a name for the new file server.
3.
Enter the type of server or choose one from the drop-down list. Currently, File Server is the only
available option.
4.
Enter the server address. The server address should be mapped path or UNC path of the file server or
a folder within the file server. For example:
\\fileserver\cae-folder
f:\cae-folder
/nfs/fileserver/cae-folder
5.
Select Extract keywords for full-text search if you want keywords to be extracted from files in this
server after upload or transfer to EKM. If you clear this option, then users can reference files in the
server but keywords won't be automatically extracted and you will not be able to search by keywords.
6.
Select Extract metadata if you want metadata to be extracted from files in this server after upload or
transfer to EKM. If you clear this option, then users can reference files in the server but metadata will
not be automatically extracted. This may be useful if you have a large repository of legacy data that
you want to quickly expose in EKM, but do not want the overhead of metadata extraction.
7.
Click OK to create the file server. You can display the File Server Properties for the object using the
Properties display. You can also modify the server properties for the remote file server using the Edit
Properties dialog box.
195
Miscellaneous Tasks
15.3.2. Built-in Remote File Servers

EKM has two built-in remote file servers that only members of the admin group can reference in new
connections to remote files/folders: Audit Logs and EKM Base Directory. These built-in remote file
servers cannot be deleted and they are hidden for non-admin users. The server address (or the location
that the server points to) for the Audit Logs file server is the logs directory in EKM_HOME (that is,
EKM_HOME/logs). This folder contains the daily logs generated by EKM. See Managing Logs (p. 196)
for more details.
The server address for the EKM Base Directory file is EKM_BASE, which is the directory where the EKM
server is set up.
The EKM Base Directory server, by default, is only referenced by the Sample Files folder in /Repository. However, as an admin user, you can create a Remote Folder or File that points to any other
location in EKM_BASE. For example, by creating a remote folder that points to the log folder in JBOSS
7, any user with permission to access the folder can view the server logs to investigate errors or failures
without logging on to the EKM server.
For more details on EKM_HOME and EKM_BASE, refer to EKM Path Variables.
15.4. Managing Logs

EKM generates logs on a daily basis. These log files are written to the System/Logs folder for easy
access, and record details about object transactions such as object name, time of operation, action
performed, and the user who performed it. The title of the log includes the workspace it was generated
in and the creation date.
You cannot delete the Audit Logs file server but you can change the location (server address) where
the log files are written to by editing the properties for the Audit Log object in the System/Remote
File Servers folder.
EKM automatically synchronizes data in the System/Logs folder at regular intervals. The frequency
and time of synchronization can be configured only by an EKM system administrator in the ekm.xml
configuration file. Alternatively data can be manually synchronized.
The log file is kept for 30 days and then automatically deleted. You can configure the duration of the
log file in the ekm.xml configuration file. See Configuring EKM Server Settings (p. 45) for details.
When you double-click a log file, the contents of the file will be displayed as text in the Object view. A
sample audit log is shown in Figure 15.2: Sample Log Display (p. 197).
196
Installing VCollab and Configuring EKM for 3D Visualization

Figure 15.2: Sample Log Display
15.5. Installing VCollab and Configuring EKM for 3D Visualization

EKM enables you to visualize 3D VCollab images of models and simulation data in the EKM Object view,
eliminating the need for you to download files to your local machine and open them in their associated
application. This can be achieved by configuring EKM to extract a CAX file from supported simulation
files using the VMoveCAE application of VCollab after upload. VCollab Presenter is needed to visualize
the CAX file in EKM. See http://www.vcollab.com for more information on VCollab, its products, and
supported file formats. VCollab 2012 release is supported in EKM for 3D visualization.
The two main products required are:
VMoveCAE: This tools needs to be installed on EKM server and is used to extract CAX files from
supported simulation files.
VCollab Presenter or VCollab Presenter Lite: Either of these tools needs to be installed
on the client machine to be able to visualize CAX files.
Once these tools have been installed, the EKM server machine must have the environment variable
VMOVE_EXEC_PATH defined as a system variable. Alternatively, you can specify this environment
variable in the extractCaxImage built-in external application in the /System/Servers/Master/EKM Server folder. VMOVE_EXEC_PATH must be set to the following paths:
Windows 64-bit: C:\Program Files\VCollab\VMoveCAE64\VMoveCAEBatch.exe
Linux: /usr/local/bin/vmovecae
You need to re-start the EKM server if you have set this environment variable as a system variable. When
you upload supported CAE files (for example, Fluent Case files or ANSYS Results files), .cax image files
will be automatically generated and displayed on the files Image display tab.
You will now need to configure any additional simulation file that needs to be visualized using VCollab.
Make sure that the simulation file is supported by VCollab. To configure the type for VCollab, you will
need to define the following type attributes:
197
Miscellaneous Tasks
extractImageOnUpload: The value for this type attribute must be true.
imageName: The value for this type attribute must be file.cax.
imageApplication: The value for this type attribute must be extractCaxImage.
showContentViewAsDefault: The value for this type attribute must be false, if you want the
visualization view to be the default view when you open the file in the EKM web client.
Refer to Defining Custom Types Using the user interface to find out how to define type attributes for
a custom type and to Configuring Workspace Settings Using XML for details on modifying type attributes
of a built-in type.
With these steps completed, when you upload a configured CAE file to a repository, EKM will automatically extract the CAX image from the file and save it as a new EKM object of type VCollab File with
the .cax extension. You can then display the 3D CAX image by selecting the Display > Image action
menu item from the context menu for the CAE file, or by selecting the Image display tab if the CAE file
is already displayed in the EKM Object view. The VCollab viewer will be loaded in the EKM Object view
and will display the 3D simulation image. You can visualize the 3D image using VCollab interactive tools
that are available in the viewer. For more details, see Displaying 3D Simulation Images Using VCollab.
15.6. Using the EKM Server Diagnostics Tool

If you encounter any problems relating to EKM administration or configuration that require the help of
an EKM technical support representative, you can use the built-in EKM Server Diagnostics tool to capture
information about your EKM installation that can be sent to the support person working your case. For
information on how to use this tool, refer to Gathering Support Diagnostics. This tool will gather ondisk configuration files and logs that can help the technical specialist to diagnose and troubleshoot the
problem. It is also advisable to download and send the /System/Configuration folder in the
package because it contains workspace-specific configuration files that may be helpful when
troubleshooting the problem.
15.7. Lifecycle Approval Process for Workflows

With the default EKM configuration (/System/Configuration/Lifecycles/WorkflowApprove.lc.xml), Workflow objects are not executable on upload or creation. See Steps for Executing
and Managing Workflows for details. Administrators can choose among the following options:
No changes to WorkflowApprove.lc.xml. Enable lifecycle-based approval process by default on all
workflow objects. Workflows are not executable by default.
Change WorkflowApprove.lc.xml in a way not to enable lifecycle-based approval process by default.
Workflows are executable by default. No approval is required.
Delete WorkflowApprove.lc.xml. All Workflows are executable by default. No approval is required.
Note
By default, the 'admin' group will be assigned promote privilege, but it can be configured
for assignment to some other group by admin.
198
Chapter 16: Backing Up and Restoring EKM

As with any application that stores important data, it is critical to establish a system of regular backups
of the EKM data and application files. In the event that data loss or corruption occurs, data can be restored
to the EKM server from a recent backup, minimizing data loss and interruption.
This chapter discusses where EKM stores data, how a member of the admin group can back it up, and
how to restore data to EKM in the event that data recovery is necessary.
Topics include:
16.1. Data Stored by EKM
16.2. Backing Up EKM
16.3. Restoring EKM
16.1. Data Stored by EKM

EKM stores data in the following locations:
EKM database
EKM data directory
EKM base directory (EKM_BASE)
In order to fully back up EKM, it is necessary to back up the data at all of these locations.
16.1.1. The EKM Database

The EKM database is stored on the database server. The EKM database stores everything in the EKM
repository except for binary objects (files). Binary objects are stored in the EKM data directory.
The EKM database stores both user data and application data. Files that are uploaded to EKM are stored
outside the EKM database in the EKM data directory, but the EKM database contains records related to
those files. These records include references to the files in the EKM data directory, and metadata extracted
from the files. The EKM database also stores in-program objects such as users, groups, workflows and
so on.
16.1.2. The EKM Data Directory

The EKM data directory stores all files that are uploaded to EKM. These files are referenced by the EKM
database, but their actual content is stored in the EKM data directory. The EKM data directory is where
most of the data stored in EKM resides. It is typical to host the EKM data directory on a RAID or SAN
for better data protection and performance.
16.1.3. The EKM Base Directory

The EKM base directory is the base directory where EKM is installed to. This is the path referred to as
EKM_BASE elsewhere in the Installation Guide. For example:
199
Backing Up and Restoring EKM

Windows: C:\ekm\v150
Linux: /home/ekm/v150
The EKM base directory contains the EKM server home directory: EKM_BASE/ekm-server, referred
to as EKM_HOME.
The EKM base directory also contains the EKM service control scripts: EKM_BASE/bin.
16.2. Backing Up EKM

In order to back up EKM, it is necessary to back up all locations where data is stored in EKM. This includes
the following locations:
EKM database
EKM data directory
EKM base directory (EKM_BASE)
EKM job data directory
EKM repository directory
A backup of EKM that is made while EKM is running is referred to as a hot backup because the system
is running (hot) while the backup is taking place.
A backup of EKM that is made while EKM is stopped is referred to as a cold backup because the system
is not running (cold) while the backup is taking place. This requires stopping the application server
and database server that are used with EKM.
It is expected that in most installations, hot backups of EKM will be conducted regularly while cold
backups will be conducted less frequently on special occasions such as before an upgrade or during
periods of scheduled maintenance.
It is essential to perform backups of EKM on a regular basis. This section will discuss the backup procedure for EKM so that you can implement an appropriate backup procedure and schedule for your
EKM installation.
16.2.1. Backup Procedure

In order to back up EKM, follow this procedure:
1. Back up the EKM database.
2. Back up the EKM data, base, job data and repository directories.
It is important to follow this procedure strictly in the sequence given below, as the order of operations
is relevant. A brief discussion of the order of operations will illustrate the backup procedure and explain
the relationships between the steps. Each step will also be discussed individually, in order to specify
what is required at each step.
Sequence:
200
Backing Up EKM
1. The EKM database is backed up at time T1, using a database dump procedure that ensures consistency
of the dump at time T1. All application and user data in the EKM database are captured at time T1.
2. The EKM data directory is backed up at time T2_start where T2_start >= T1. This means that the
backup of the EKM data directory starts at the same time or after the EKM database backup. This
operation completes at time T2_end. All the data files stored in EKM are captured at time T2_start.
Files added between T2_start and T2_end are not relevant as described below.
The EKM base, job data and repository directories can be backed up at any time.
Important
It is ABSOLUTELY CRITICAL that if garbage collection runs while a backup is in progress that
it does not delete any files that were still in use at time T1, as this can cause the backups to
become inconsistent, and data loss/corruption could result if they are used to restore from.
This can be ensured by setting the interval for dataStoreGC scheduled task to be greater
than the time it takes for a complete backup of the datastore. See the description of the
dataStoreGC setting in Scheduling Automatic Tasks (<scheduledTasks>) (p. 53) for more
details.
When restoring, the restore of the EKM database will take place with data from time T1, and the restore
of the EKM data directory will take place with data from time T2_start. This is not a problem because
of how the EKM data directory and EKM database are related. The end result is that a consistent set of
EKM data from time T1 will be restored to EKM. The internal workings of the EKM database and EKM
data directory ensure that the data in the EKM database and EKM data directory will be synchronized
to contain only data present at time T1. Any leftover, non-referenced data in the EKM data directory
will be cleaned up the next time the garbage collection is run (see Cleaning Up Unused Files)*.
*When the EKM database from T1 and the EKM data directory from T2_start are restored, the following
conditions apply:
1. Changes to the EKM database after time T1 are not captured because the backup captures the state
of the EKM database at time T1.
2. Additions made to the EKM data directory after T1 are discarded the next time the garbage collection
is run, as they are not referenced by the EKM database backup from time T1.
3. Deletions from the EKM data directory after T1 are not carried out, as data files deleted from the
EKM data directory do not actually get deleted until the next time the garbage collection is run.
Note that this cleanup must not run between times T1 and T2_end.
4. Updates/edits to existing files in the EKM data store are implemented internally as adds/deletes, so
the previous rules governing additions and deletions apply to modifications of existing items.
16.2.1.1. Garbage Collection

Garbage collection, also referred to as "cleaning" the EKM data directory, is an operation that can be
run by the dataStoreGc task, which is configured in ekm.xml or can be started by a superuser from
the EKM Server Administration interface (see Cleaning Up Unused Files). It is described here, because
it affects backup operations.
201
Backing Up and Restoring EKM
16.2.1.2. Backing up the EKM Database

The procedure for backing up the EKM database varies by database server type; follow the directions
provided with your database server.
Note
For the MySQL database server, use the mysqldump command to back up the EKM
database. EKM uses the ACID-compliant InnoDB storage engine under MySQL, as opposed
to the default MyISAM storage engine, so certain options to the mysqldump command
must be used. These options are demonstrated in the example below.
Here is the suggested command-line for dumping the ekm150 database using mysqldump:
MYSQL_HOME/bin/mysqldump --databases ekm150 --single-transaction --hex-blob > ekm.sql
where MYSQL_HOME is the directory where the MySQL database server is installed.
16.2.1.3. Backing up the EKM Data, EKM Base, Job Data and Repository Directories
Once you have backed up the the EKM database you can back up the following directories located in
the root install directory (for example, C:\ekm).
To back up these directories, take a full copy of each directory, including all files and subdirectories. It
is recommended that an enterprise-quality commercial backup solution be used to perform the file
backups of these directories.
\datastore
\jobdata
\repository
\v150 (EKM_BASE)
16.3. Restoring EKM

Depending on the need, there are various ways to restore data to EKM. This section will discuss how
to perform full or partial restores of EKM.
16.3.1. Restoring Procedure

A full restore involves restoring all components where EKM data is stored. This would be used for example,
if the server where EKM was installed suffered a catastrophic disk failure, and needed to be reinstalled
from scratch.
A partial restore, say of just the EKM base directory, might be necessary if the files in this directory were
corrupted or accidentally deleted.
A restore of the EKM program/user data would be necessary if data within the EKM application got
corrupted. In this case, the EKM database and the EKM data directory would need to be restored.
In all cases, the EKM database and EKM data directory must be restored together because they are very
closely linked.
202
Restoring EKM
Restoring the EKM Database (p. 203)
Restoring the EKM Data, EKM Base, Job Data and Repository Directories (p. 203)
Clearing the Search Indices (p. 203)
16.3.1.1. Restoring the EKM Database

The procedure for restoring the EKM database varies by database server type. Follow the directions
provided with your database server to restore the EKM database from the backups you created.
For the MySQL database server, use the mysql command to restore the EKM database from the dump
created by the mysqldump command, as described in Backing up the EKM Database (p. 202). Here is
the suggested command-line for restoring the ekm database:
MYSQL_HOME/bin/mysql < ekm.sql
where MYSQL_HOME is the directory where the MySQL database server is installed.
After restoring the EKM database and EKM data directory, it is also necessary to clear the search indices
as instructed in Clearing the Search Indices (p. 203).
Important
When restoring the EKM database, it is also necessary to restore the EKM data directory from
the same backup set.
16.3.1.2. Restoring the EKM Data, EKM Base, Job Data and Repository Directories
You can restore these directories from your EKM data directory backup. This is a simple filesystem restore,
with no special commands to run.
After restoring anything from the EKM data or repository directory, clear the search indices as instructed
in Clearing the Search Indices (p. 203).
Important
When restoring the EKM data directory, it is also necessary to restore the EKM database from
the same backup set.
16.3.1.3. Clearing the Search Indices

After any restore, it is necessary to clear the search indices for all domains present on the EKM server.
The search indices will automatically get recreated the next time EKM is started. This will ensure that
the search indices are consistent with the data in the EKM repository after the restore operation.
To clear the search indices:
1. Go to the repository directory and open the workspaces sub-directory.
2. For each subdirectory in the workspaces directory (such as Default, root and so on), delete the
index subdirectory and all of its contents.
203
204
Appendix A. Java Security Manager and EKM Scripting

The EKM server makes use of the Java Security Manager to prevent scripts executing on the server from
performing malicious operations. These operations could be done intentionally by a knowledgeable
script developer or inadvertently by a novice one. One of the main things the security manager prevents
is allowing scripts to arbitrarily read and write files anywhere on the servers file system. By default,
scripts in EKM 15.0 will only be able to read and write files in the EKM_TEMP directory of the server.
Other limitations placed on scripts is the ability to start processes and access network resources exposed
to the server. In instances where a script has attempted to perform some privileged operation, the
system will report an access violation. For example, if a script attempted to write a file to the servers
root directory, the following error would be encountered:
access denied (java.io.FilePermission C:\foo.txt write)
In some instances, there may be EKM users that have valid reasons to develop scripts that perform
operations expressly forbidden by the default security policy. In these instances, you have a way to
grant the script the necessary privileges to perform the operation. This is done by modifying the
scripting security policy. The scripting security policy is defined in a file called script.policy that
is located in EKM_HOME/conf. The default file is as follows:
//
// The following permissions apply to scripts executed within the context of an
// EKM server.
//
grant {
permission java.io.FilePermission "${jboss.home.dir}/modules/-", "read";
permission java.io.FilePermission "${jboss.home.dir}/standalone/deployments/-", "read";
permission java.io.FilePermission "${jboss.home.dir}/standalone/tmp/-", "read";
};
Note
The default script policy grants read access to the /modules and /standalone/deployments and /standalone/tmp directories under JBOSS_HOME. The EKM scripting interface
(Jython in particular) must be able to access these locations in order to function. Other locations under JBOSS_HOME do not have read access because they may contain sensitive information.
To grant privileges to scripts running on the server, you must insert the appropriate permission entries
within the brackets "{}" of the grant statement. For detailed information on the syntax of the policy
file, refer to the Java documentation located here:
http://docs.oracle.com/javase/7/docs/technotes/guides/security/PolicyFiles.html#FileSyntax
Because a likely permission needed by scripts is to access files or folders outside of the servers EKM_TEMP
directory, the following is an example entry in the policy for providing scripts with this capability.
grant {
permission java.io.FilePermission "C:\\users\\jsmith\\data", "read";
};
205
Java Security Manager and EKM Scripting

In the above example, scripts executing on the server are granted permission to read files in
C:\users\jsmith\data as well as the servers EKM_TEMP directory. If the scripts also needed to
access files within subdirectories of C:\users\jsmith\data, the permission entry would look as
follows:
grant {
permission java.io.FilePermission "C:\\users\\jsmith\\data\\-", "read";
};
The "-" at the end of the path indicates that this permission is applied to the specified directory as well
as any subdirectories. If write permission is needed within a directory, the entry would look like this:
grant {
permission java.io.FilePermission "C:\\users\\jsmith\\data", "read,write";
};
Once the script.policy file has been edited with the appropriate permission entries and saved,
you simply need to execute the script again. Assuming the appropriate permission entries were placed
in the policy, the script will execute without any access violations.
206
Appendix B. Built-in Types - Reference

EKM uses an object-oriented system for data typing with EKM Object as the base type for all data types.
All other types directly extend EKM Object or extend some other type that is an extension of EKM
Object. When a type extends another type, it inherits all the features of the base type such as properties,
actions, displays and type attributes, and it can add new features of its own. This section provides a
detailed description of each built-in data type used in EKM. For each type, the base type that it extends
from is specified along with any new properties and type attributes added by the type. For file types,
it also notes the valid file extensions. Non-localized names of types and properties are provided in
parenthesis. Localized names are displayed in the user interface, whereas non-localized names are used
in configuration files (such as workflows and lifecycles) and macros.
Note
For general information on data types, see Object Types in the User's Guide.
B.1. Abaqus Input (AbaqusInput)

Base Type: FE Model
File Extensions: .inp
B.2. Abaqus Output Database (AbaqusOutputDatabase)

Base Type: CAE Model File
File Extensions: .odb
B.3. Abaqus Result (AbaqusResult)

Base Type: FE Model
File Extensions: .fil
B.4. Adobe Acrobat Document (AdobePdfFile)

Base Type: File
File Extensions: .pdf
B.5. Analysis Project (AnalysisContainer)

Base Type: Folder
Properties:
207
Built-in Types - Reference

Execution Process (executionMonitor): a reference variable for the process used to monitor the analysis
Execution Workflow (executionWorkflow): the workflow used to execute the analysis
Input Files (analysisInputs): input files of the analysis
Input Patterns (inputPatterns): path patterns where inputs are stored
Last Successful Execution Start Time (lastSuccessfulExecutionStartTime): the last time the execution
was successfully started
Output Patterns (outputPatterns): path patterns where outputs are stored
Workflow Variable (executionWorflowVar): a reference variable defined in the workflow that will be
executed when the analysis project is updated
Type Attributes:
executionWorkflow: the path of the workflow that will be executed when the analysis project is updated
executionWorflowVar: a reference variable defined in the workflow that will be executed when the
analysis project is updated
inputPattern: path pattern where inputs are stored
outputPattern: path pattern where outputs are stored
B.6. Ansoft Designer File (AnsoftDesigner)

File Extensions: .adsn
Properties:
Properties (properties): This file can contain any number of Nexxim Circuit', 'Nexxim Netlist, 'Planar
EM Circuit' and 'System Circuit'.
Properties of Nexxim Circuit (propertiesOfNexximCircuit): Design Name (designName), Number of
Excitations (nExcitations), Number of Optimetrics Setups (nOptimetricsSetups), Number of Ports
(nPorts), Number of Results (nResults), Solution Setups (solutionSetups)
Properties of Nexxim Netlist (propertiesOfNexximNetlist): Design Name (designName), Number of
Results (nResults)
Properties of Planar EM Circuit (propertiesOfPlanarEmCircuit): Design Name (designName) Number
of Optimetrics Setups (nOptimetricsSetups) Number of Ports (nPorts) Number of Results (nResults)
Properties of System Circuit (propertiesOfSystemCircuit): Design Name (designName) Number of Excitations (nExcitations) Number of Optimetrics Setups (nOptimetricsSetups) Number of Ports (nPorts)
Number of Results (nResults) Solution Setups (solutionSetups)
208
ANSYS Input/Mechanical APDL Input (AnsysInput)
B.7. ANSYS Database/Mechanical APDL Database (AnsysDatabase)

File Extensions: .db, .cdb
Properties:
Load Steps (loadSteps): number of load steps performed in the simulation
Components (components): names of all components
Macro File (macroFile): associated macro file
Version (ansysVersion): version of ANSYS Mechanical that generated this file
Mesh File (meshFile): associated mesh file
Iterations (iterations): number of iterations
Analysis Type (analysisType): type of analysis
Sub Steps (subSteps): number of sub steps
Element Types (elementTypes): names of element types in this simulation
Creation Date (creationDate): the date this simulation file was created
Dimensionality (dimensionality): dimensionality of the model (2D or 3D)
Large Deformation (largeDeformation): whether large deflection effects are included or not
Contact Types (contactTypes): types of contacts in this simulation
Elements (elements): number of elements
BC Types (bcTypes): boundary condition types like constraints, forces, surface loads and body loads
in this simulation
Material Models (materialModels): material models like creep, hyperelasticity and plasticity in this
simulation
B.8. ANSYS Input/Mechanical APDL Input (AnsysInput)

Base Type: File
File Extensions: .dat, .inp
Properties:
Analysis Types (analysisTypes): types of analysis
209
B.9. ANSYS Output/Mechanical APDL Output (AnsysOutput)

Base Type: File
File Extension: .out
Analysis Types (analysisTypes): types of analysis
B.10. ANSYS Result/Mechanical APDL Result (AnsysResult)

File Extensions: .rst, .rth, .rmg
B.11. Applications Grid (ApplicationsGrid)

Base Type: EKM Object
B.12. Approval Work item (ApprovalWorkItem)

Base Type: Work Item
Properties:
Reviewers (reviewers): work item reviewers
Due Date (dueDate): due date
B.13. Archive (Archive)

Base Type: File
File Extensions: .zip, .tar, .tz
B.14. AUTODYN Database (AutodynDatabase)

Base Type: File
File Extensions: .ad
B.15. Base Job (BaseJob)

Properties:
Status (status): A numeric code representing the current status of the running job
0 = Queued
210
CAE Model File (CaeModelFile)

1 = Running
2 = Cancelled
3 = Completed
4 = Failed
-1 = Invalid/Not Initialized
Job Template (jobTemplate): Reference to the job template used for this job
Execution Start Time (executionStartTime): The start time of the last execution of the job
Execution End Time (executionEndTime): The end time of the last execution of the job
Execution ID (executionId): An identifier for the execution of the job
Application (application): Reference to the application used in the last execution of the job
B.16. Batch Job Submission Queue (BatchQueue)

Base Type: Job Submission Queue
Properties:
Queue Type (queueType): The type of job submission system (rsmNative, lsf, pbs, windowsHpc, sge)
B.17. Batch Work Item (BatchWorkItem)

Properties:
Job (job): Reference to the Job that is associated with this batch work item. When the job completes
and is removed, this will be blank.
B.18. BladeGen Database (BladeGenDatabase)

Base Type: File
File Extension: .bgd
B.19. CAE Model File (CaeModelFile)

Base Type: File
Type Attributes:
showContentViewAsDefault: Boolean flag that specifies whether the content view should be set to
default (false)
imageApplication: name of the application used to extract an image (extractCaxImage)
imageName: name of the image file generated by the imageApplication (file.cax)
211

reportApplication: name of the application used to generate a Simulation Details Report
extractImageOnUpload: Boolean flag that specifies whether an image should be automatically extracted
after the file is uploaded
B.20. Cache Server (CacheServer)

Base Type: Server
B.21. Catalog (Catalog)

Base Type: Container
Type Attributes:
childObjectPrefix: Prefix used for child names in the catalog. All children of the catalog will start with
this prefix and end with a unique id.
B.22. CFX Definition (CfxDefinition)

File Extensions: .def
Properties:
Heat Transfer Model (heatTransferModel): heat transfer model
Combustion Model (combustionModel): combustion model
Radiation Model (radiationModel): radiation model
Turbulence Model (turbulenceModel): turbulence model
Time (time): steady state or transient
CFX Version (cfxVersion): version of CFX that generated this file
Materials (materials): names of all materials
Domains (domains): names of all domains
Boundaries (boundaries): names of all boundaries
B.23. CFX Result (CfxResult)

Base Type: CFX Definition
File Extensions: .res
B.24. CFX Session File (CfxSessionFile)

Base Type: File
212
DesignModeler Database (WorkBenchDesignModelerFile)

File Extensions: .cse
Type Attributes:
contentType: MIME type of the file (text/plain)
B.25. CFX State File (CfxStateFile)

Base Type: File
File Extensions: .cst, .ccl
Type Attributes:
B.26. Comparison Report (ComparisonReport)

Base Type: Report
Properties:
Objects for Comparison (comparisonObjects): list of objects used for creating the Comparison Report
B.27. Container (Container)

B.28. Data Extraction Monitor (DataExtractionMonitor)

B.29. Data Extraction Monitor Container (DataExtractionMonitorContainer)

B.30. Data Extraction Queue (DataExtractionQueue)

Base Type: Queue
B.31. DesignXplorer Database (R11) (DesignXplorerDatabase)

Base Type: File
File Extensions: .dxdb
B.32. DesignModeler Database (WorkBenchDesignModelerFile)

Base Type: File
File Extensions: .agdb
213
B.33. EKM Application (Application)

Properties:
URL Type (urlType): type of the application (script, JAVA or external URL)
URL (applicationUrl): application identifier (for script based applications it is name of the initialization
macro)
scriptLanguage (scriptLanguage): scripting language used for script based applications
B.34. EKM Journal File (ScriptFile)

Base Type: File
File Extensions: .jou.py, .jou.bsh
Properties:
Result Report Macro (resultReportMacro): When you double-click the script in the web user interface,
the generated report is shown, rather than the script content. If this macro is not defined, the script
contents are shown.
B.35. EKM Object (Model)

Properties:
Checked Out By (checkedOutBy): user who checked out this object
Check In Policy (checkinPolicy): check in policy
Created By (creator): user who created this object
Date Created (creationTime): date when the object is created
Date Modified (modificationTime): date when the object is last modified
Description (description): description associated with this object
Expiration Date (expirationDate): date of expiration of this object
Image (associatedImage): image associated with this object
Lifecycle Stage (lifecycleStage): current lifecycle stage
Modified By (modifiedBy): user who last modified this object
Name (name): name of this object
Perishable (perishable): indicator of whether this object is perishable
Status Flags (statusFlags): status flags for this object
214
External Application (ExternalApplication)

Is Internal (_isInternal_): specifies whether the object is internal and should be hidden from the view
Type Attributes:
icon: icon associated with this object type
B.36. EKM Server (Server)

Properties:
Port (port): The port number on which this server is running
Host Name (hostname): The fully qualified host name of the server
B.37. EKM Type (Type)

Base Type: File
File Extensions: .type.xml
B.38. EKM Workflow (Workflow)

Base Type: File
File Extensions: .wfxml, .wf.xml
B.39. Engineering Data Database (R11) (WorkBenchEngineeringData)

Base Type: File
File Extensions: .eddb
Properties:
Material Library (materialLibrary): associated material library file
B.40. ePhysics File (AnsoftEPhysics)

Base Type: File
File Extensions: .ephy
B.41. External Application (ExternalApplication)

Base Type: File
Properties:
Executable Path (execPath): The full path of the application executable.
Parameters (params): One or more command line parameters. (optional)
215

Native Options (nativeOptions): Batch submission system-specific options. (optional)
Environment Variables (environmentVars): One or more environment variables (name, value) definitions.
(optional)
Key (key): A unique string used to identify the application.
Label (label): The name of the application as it appears in dialog boxes and other interface components.
B.42. FE Model (FeModelInput)

Properties:
Analysis Types (analysisTypes): The type of analysis performed
Solution Types (solutionTypes): The type of solution performed
B.43. FE Modeler Database (FeModelerDatabase)

Base Type: File
File Extensions: .fedb
B.44. File (File)

Properties:
Date Content Created (contentCreationTime): date when the file content was created. If the file was
uploaded using the browser, this is the date on which the file was uploaded to EKM. If the file was
uploaded using the File Transfer Client, this is the last modification date of the file on the user's system
prior to upload.
Date Content Modified (contentModificationTime): date when the file content was last modified. Initially
this will be the date on which the file was uploaded to EKM.
Size (length): size of the file
Content Type (contentType): MIME type of the file
Remote Item Location (remoteItemLocation): The location of the file in the remote server (shown
only if the file is located on a remote file server)
Remote File Server (externalResource): The reference to the remote file server containing the file
(shown only if the file is located on a remote file server)
Upstream Dependencies (upstreamDependencies): The upstream objects (such as analysis projects)
that this file depends on
Type Attributes:
extension: Additional extensions supported by this file type
216
Fluent Case (FluentCase)

extendBuiltInExtraction: (new object types only) Specifies whether additional extractors that are
specified will extend or replace the built-in extractors. When the value is set to true (default), the
additional extractors that you specify for metadata extraction in the metaDataApplication setting
and simulation details report extraction in customReportApp setting will extend the built-in extractors so that custom extract occurs after the built-in extraction. When the value is false, the
additional extractors will replace the built-in extractors so that built-in extraction does not occur at
all.
metaDataApplication: The name of the application used to extract metadata from this file.
typeValidatorClass: The Java class used for finding the type of a file. This is used for automatic type
assignment during uploads.
showContentViewAsDefault: Specifies whether or not the content view of the CAE File is the default
view in the web interface.
B.45. File Server (ExternalResourceFs)

Properties:
Server Address (baseLocation): The absolute path of the base directory
Extract metadata (extractMetaData): Indicates whether metadata should be extracted from files on
this server
Extract keywords for full-text search (extractKeywords): Indicates whether keywords should be extracted
from files on this server
B.46. Fluent Case (FluentCase)

File Extensions: .cas
Properties:
Solver (solver): solver type
Energy Model (energy): energy model
DPM Model (dpm): DPM model
Fluent Version (fluentVersion): which version of Fluent generated this case file
Radiation Model (radiation): radiation model
Formulation (formulation): whether it is an explicit or implicit formulation
Space (space): 2d/axi-symmetric/3d
Multiphase Model (multiphase): multiphase model used
217

Materials (materials): material names
Regions (regions): regions
Time (time): time method used in the simulation (steady or transient)
Viscous Model (viscous): viscous model used
B.47. Fluent Data (FluentData)

Base Type: File
File Extensions: .dat
B.48. Fluent Plot (FluentPlot)

Base Type: File
File Extensions: .xy
B.49. Folder (Folder)

B.50. Group (Group)

Properties:
Groups (groups): The list of groups that this group belongs to
B.51. HFSS File (HfssProject)

File Extensions: .hfss
Properties: This file can contain multiple "Material" and "Design" models.
A "Material" has the following property:
Frequency Dependent (frequencyDependent): Whether the material is frequency-dependent.
A "Design" has the following properties:
Design Type (designType): Type of design (HFSS or HFSS-IE)
Solution Type (solutionType): Solution type
Excitation Types (excitationTypes): Types of added excitations
Optimetric Setups (optimetricSetups): Names of added optimetric setups
Design Notes (designNotes): Design notes
218
Job (Job)
A "Design" can have multiple "Analysis" models, each of which can have the following properties:
Frequency (frequency): Solution frequency in GHz
Minimum Frequency (Eigenmode) (minimumFrequency): Minimum frequency in the case of a design with
the solution type of eigenmode.
An "Analysis" can have multiple "Frequency Sweep" models, each of which can have following properties:
Sweep Type (sweepType): Discrete/Fast/Interpolating
Sweep Start (sweepStart): Sweep-start frequency in GHz
Sweep Stop (sweepStop): Sweep-stop frequency in GHz
B.52. Image (Image)

Base Type: File
File Extensions: .jpeg, .jpg, .gif, .png, .tiff, .tif, .bmp
B.53. Imported Report (ImportedReport)

Base Type: Report
File Extensions: .rpxml
B.54. Interactive Job (InteractiveJob)

Base Type: Base Job
Properties:
Connection URL (connectionURL): Allows iPad users to open the VNC iPad app to connect to the remote
session
B.55. Interactive Job Submission Queue (InteractiveQueue)

Base Type: Job Submission Queue
Properties:
Queue Type (queueType): The type of job submission system (LSF, PBS, Moab, Torque, Neutro)
OS Type (osType): The operating system of the queue (Windows or Linux)
Job Submission Queue (schedulerQueue): The job scheduler that submits jobs for execution
Remote Type (remoteType): The remote serialization type (for example VNC or DVC)
B.56. Job (Job)

Base Type: Base Job
219

Properties:
Working Directory Path (workingDirectoryPath): Path of the working directory
Monitoring Object (monitoringObject): Reference to the monitoring work item
B.57. Job Submission Queue (JobSubmissionQueue)

Base Type: Queue
Properties:
Queue Domain (queueDomain): The domain name for all user accounts
B.58. Job Submission Server (JobSubmissionServer)

Base Type: Server
Properties:
B.59. Job Template (JobTemplate)

Base Type: File
File Extensions: .jt.xml
B.60. Job Template Container (JobTemplateContainer)

B.61. Lifecycle (Lifecycle)

Base Type: File
File Extensions: .lcxml .lc.xml
B.62. Maxwell File (AnsoftMaxwell)

Base Type: File
File Extensions: .mxwl
Properties:
Materials (materials): names of materials in the project
This file can have multiple Maxwell 2D Designs, Maxwell 3D Designs, and RMxprt Designs.
A Maxwell 2D Design has following properties:
Design Name (designName): Name of the design
Solution Type (solutionType): Solution Type
220
Maxwell File (AnsoftMaxwell)

Geometry Mode (geometryMode): Geometry Mode (Cartesian or Cylindrical)
Eddy Effects Included (eddyEffectsIncluded): Whether eddy effects are included
Core Loss Included (coreLossIncluded): Whether core loss is included
Enable Transient-Transient Link With Simplorer (enableTransientTransientLinkWithSimplorer): Whether
transient-transient link with Simplorer is enabled
Motion Types (Transient Solver) (motionTypes): Motion Types (for Transient solver only)
Optimetric Setups (optimetricSetups): Types of optimetric setups added
A Maxwell 3D Design has following properties:
Design Name (designName): Name of the design
Solution Type (solutionType): Solution Type
Include Insulator Field (DC Conduction Solver) (includeInsulatorField): Whether insulator field is included
(for DC Conduction Solver only)
Eddy Effects Included (eddyEffectsIncluded): Whether eddy effects are included
Core Loss Included (coreLossIncluded): Whether core loss is included
Enable Transient-Transient Link With Simplorer (enableTransientTransientLinkWithSimplorer): Whether
transient-transient link with Simplorer is enabled
Motion Types (Transient Solver) (motionTypes): Motion Types (for Transient solver only)
Optimetric Setups (optimetricSetups): Types of optimetric setups added
An RMxprt Design has following properties:
Machine Type (machineType): Machine Type
Number Of Poles (numberOfPoles): Number Of Poles
Operation Types (operationTypes): Operation types of solution setups added in the design
Number Of Poles In Rotor (SRM, GRM) (numberOfPolesInRotor): Number of poles in rotor. (for Switched
Reluctance Motor and Generic Rotating Machines)
Number Of Poles In Stator (SRM, GRM) (numberOfPolesInStator): Number of poles in stator (for Switched
Reluctance Motor and Generic Rotating Machines)
Source Type (GRM) (sourceType): Source type (for Generic Rotating Machines)
Structure Type (GRM) (structureType): Structure type (for Generic Rotating Machines)
Stator Type (GRM) (statorType): Stator type (for Generic Rotating Machines)
Rotor Type (GRM) (rotorType): Rotor type (for Generic Rotating Machines)
221
B.63. Meshing Database (MeshingDatabase)

Base Type: File
File Extensions: .cmdb
B.64. Message Board (MessageBoard)

Properties:
Listeners (listeners): The list of members who can access and read messages that are posted
B.65. Microsoft Excel Worksheet (MSOfficeExcelFile)

Base Type: File
File Extensions: .xls, .xlsx
B.66. Microsoft Powerpoint Presentation (MSOfficePowerpointFile)

Base Type: File
File Extensions: .ppt, .pptx
B.67. Microsoft Word Document (MSOfficeDocumentFile)

Base Type: File
File Extensions: .doc, .docx
B.68. My Data (MyData)

Base Type: Folder
B.69. NASTRAN Bulk Data (NastranBulkData)

Base Type: FE Model
File Extensions: .nas, .bdf, .dat
B.70. NASTRAN Result (NastranResult)

Base Type: File
File Extensions: .f04, .f06
B.71. Polyflow Data (PolyflowData)

File Extensions: .dat
222
Report (Report)
Properties:
Solver Type (solverType): The type of solver
Problem Types (problemTypes): All problem types defined in the file
Problem Names (problemNames): All problem names defined in the file
Task Name (taskName): The name of the task
Version (version): The version of Polyflow that generated this file
Geometry Type (geometryType): The type of geometry
B.72. Polyflow Export (UNS) (PolyflowExportFile)

Base Type: File
File Extensions: .uns
B.73. Process Container (ProcessContainer)

B.74. Public Saved Query (PublicSavedQueryContainer)

Base Type: Folder
B.75. Q3D File (AnsoftQ3D)

Base Type: File
File Extensions: .q3dx
B.76. Queue (Queue)

B.77. Remote Folder (RemoteFolder)

Properties:
Remote Item Location (remoteItemLocation): The location of the folder in the remote server
Remote File Server (externalResource): The reference to the remote file server containing the folder
B.78. Report (Report)

Base Type: File
223
B.79. Saved Query (SavedQuery)

B.80. Saved Query Container (SavedQueryContainer)

B.81. Search Results Report (SearchResultsReport)

Base Type: Report
B.82. Shortcut (Link)

Properties:
Link (link): The reference to the object pointed to by the shortcut
B.83. Simplorer File (AnsoftSimplorer)

File Extensions: .asmp
Properties:
Component Names (componentNames): the names of all components used in the project
Component Libraries (componentLibraries): the names of all component libraries used in the project.
This file can contain multiple 'Simplorer Design, each of which has following properties:
Solution Setups (solutionSetups): the names of solution setups that are associated with a given
design
B.84. Simulation Details Report (CaeModelSummaryReport)

Base Type: Report
Properties:
Model File (modelFile): The simulation file whose report is created
B.85. Siwave File (AnsoftSiwave)

Base Type: File
File Extensions: .siw
224
Workbench Project Archive File (WorkBenchProjectArchiveFile)
B.86. Update Analysis Project Work Item (UpdateAnalysisProjectWorkItem)

File Extensions: .cax
B.87. URL (Url)

Properties:
Address (address): Complete URL (for example: http://mydomain.com/page.html)
Open this URL in a new window (openNewWindow): if true, opens the URL in a new browser window
B.88. User (User)

Properties:
Cache Server (cacheServer): Reference to the EKM Server (Server) (p. 215) representing the cache
server assigned to the user. If blank, user is not configured to use a cache server.
Enabled (enabled): set to false to disable user
B.89. VCollab File (VcollabCompressedFile)

Base Type: File
File Extensions: .cax
B.90. Workbench Journal File (WorkBenchJournalFile)

Base Type: File
File Extensions: .wbjn
B.91. Workbench Design Point File (WorkBenchDesignPointFile)

Base Type: File
File Extensions: .wbdp
B.92. Workbench Project Archive File (WorkBenchProjectArchiveFile)

File Extensions: .wbpz
Properties:
225

System Names (systemNames): The names of systems defined for the project.
System Types (systemTypeNames): The types of systems defined for the project.
Parameters (parameterNames): The names of parameters defined for the project.
Design Points (designPointNames): The names of design points defined for the project.
Update Required (updateRequired): Whether this project needs update or not.
B.93. Workbench Project File (WorkBenchProjectFile)

File Extensions: .wbpj
Properties:
System Names (systemNames): The names of systems defined for the project.
System Types (systemTypeNames): The types of systems defined for the project.
Parameters (parameterNames): The names of parameters defined for the project.
Design Points (designPointNames): The names of design points defined for the project.
Type Attributes:
contentType: MIME type of the file (text)
B.94. Workbench Project File R11 (WorkBenchProjectFileR11)

Base Type: File
File Extensions: .wbdb
B.95. Workbench Simulation/Mechanical Database (WorkBenchSimulation)

File Extensions: .dsdb, .mechdb, .mechdat
Properties:
Workbench Version (workbenchVersion): version of the file
Engineering Data File (engineeringDataFile): reference to the engineering data file used
This file can contain multiple WorkBench Simulation models or Mechanical models, each of which
has the following properties:
Analysis Types (analysisTypes): types of analyses performed
Space (space): 2d/3d
226
Work Item (WorkItem)

Mass (mass): mass of the model
Volume (volume): volume of the model
Nodes (nodes): number of nodes
Elements (elements): number of elements
Contact Types (contactTypes):
Geometry Source (geometrySource):
Material Behaviors (materialBehaviors):
Material Properties (materialProperties):
Materials (materials):
Parts (parts):
Solution Names (solutionNames):
B.96. Workflow Process (Process)

Properties:
Completion Time (completionTime): completion time of the process
Monitoring Work Item (monitoringWorkItem): reference to the Work Item (if any) monitoring this
process
Status (status): status of the process
Workflow (workflow): reference to the workflow from which this process has been started
Workflow Resource (workflowResource): Class path of an internal workflow associated with the process
Parent Item (parentItem):
Delete on Completion (deleteOnCompletion):
B.97. Work Item (WorkItem)

Properties:
Node (node): name of the node in the workflow corresponding to the work item
Process (process): reference to the process containing this work item
Reassignment Note (assignmentNote): The note shown when a work item is reassigned to another
user
227

Status (status): status of the work item
User (user): name of the user to which the work item has been assigned
228
Appendix C. Lifecycles: Defining and Configuring Using XML

As an alternative to using EKM Studio, you can use an XML editor to define a lifecycle definition file. A
lifecycle XML file must adhere to the schema definition for lifecycles, and must be saved with the
.lc.xml extension so that it can be recognized by EKM and typed as a Lifecycle object.
Note
The file extension .lcxml was used in previous versions of EKM and is an allowable extension.
Once you have created a lifecycle XML file you will need to upload and configure the file as described
in Basic Steps for Creating, Configuring, and Managing Lifecycles (p. 133).
C.1. Defining Lifecycles Using XML

This section describes how you can define a lifecycle file using XML constructs and syntax. Lifecycles
that you define in XML must be saved with the .lc.xml file extension. When uploaded to a repository,
the lifecycle XML file is typed as a Lifecycle object by EKM.
Lifecycle XML files are defined according to a XML Schema Definition file that describes the structure
or "grammar" that the XML code must adhere to. Schema definitions provide the building blocks that
will enable you to write valid XML files. lifecycle.xsd is supplied with your installation in the
EKM_HOME/schema folder.
Important
This section and the proceeding sections assume that you have a basic understanding of XML constructs
and syntax. If you are unfamiliar with these technologies, you will need to review them before proceeding.
http://www.w3.org offers extensive tutorials and documentation. In particular, it is recommended that
you review the documentation on XML schemas found at: >http://www.w3.org/TR/xmlschema-0. While
creating or editing XML files it is recommended that you use schema-aware XML editors. This will allow
you to easily create configuration files that are syntactically correct and reduce the likelihood of errors.
C.1.1. Schema Definition for Lifecycles

EKM provides schema files for all files that you define using XML. These XML Schema Definition (XSD)
files describe the structure or "grammar" that an XML document must adhere to. Schema definitions
provide the building blocks that enable you to write valid XML configuration files for use in EKM. For
more information on how to read schema files, refer to: http://www.w3.org/TR/xmlschema-0.
229
Lifecycles: Defining and Configuring Using XML

XSD files are contained in the EKM_HOME/schema folder and are identified by the .xsd extension.
Important
Figure 1: Partial Listing of lifecycle.xsd Schema Definition (p. 230) shows the partial listing for lifecycle.xsd, the XML schema definition (XSD) that is used for defining lifecycles in EKM. The complete
listing is provided in the EKM_HOME/schema folder.
The listing shows that a lifecycle file consists of a root element named lifecycle. The lifecycle element
must contain the following:
1 or more type elements
1 or more stage elements
0 or more transition elements
an optional script element
See Defining a Lifecycle XML File (p. 231) for a description of each element.
Figure 1: Partial Listing of lifecycle.xsd Schema Definition
targetNamespace="http://www.ansys.com/ekm/lifecycle"
xmlns:ekmLifecycle="http://www.ansys.com/ekm/lifecycle">
xmlns:ekmScript="http://www.ansys.com/ekm/script">
<xsd:import namespace="http://www.ansys.com/ekm/script" schemaLocation="script.xsd"/>
<xsd:complexType name="Stage">
<xsd:sequence>
<xsd:element name="permission" minOccurs="0"
<xsd:complexType>
<xsd:sequence>
<xsd:element name="type" minOccurs="1"
<xsd:simpleType>
<xsd:enumeration value="access" />
<xsd:enumeration value="create" />
<xsd:enumeration value="delete" />
<xsd:enumeration value="modify" />
<xsd:enumeration value="download" />
<xsd:enumeration value="lifecycle" />
<xsd:enumeration
value="fullControl" />
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="member" type="xsd:string"
minOccurs="1" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
230
Defining Lifecycles Using XML
C.1.2. Defining a Lifecycle XML File

A lifecycle is defined in terms of the following constructs:
Types
Stages
Transitions
C.1.2.1. Types
A single lifecycle can be associated with one or more than one types. The type element is used for
defining this association.
A type definition consists of the following required attributes:
name: used to specify the name of the type associated with this lifecycle. If you are associating the
lifecycle with a built-in type, you will need to use the non-localized type name as described in Appendix B (p. 207).
enabledByDefault: used to specify whether the lifecycle is enabled by default when an instance
of the type is created. Its value can be either true or false. If set to true, this means that
whenever an object of this type is created, it will be associated with this lifecycle with the start stage
as the current stage. If set to false, the lifecycle will need to be enabled manually.
C.1.2.2. Stages
A stage defines a phase of the lifecycle. Within a stage you can define permissions that specify who
can access the object, modify it, or perform other operations on the object that is associated with the
lifecycle. You can also specify whether the objects needs to be automatically deleted from the repository
and if so after how many days.
A stage definition consists of the following required attributes:
name: specifies the name of the stage. As with child names in custom types, node names cannot
contain the following special characters:
/ \ : [ ] % * ' " | > < ?
description: used to provide a description of the stage
A stage definition may also consist of the following optional attributes:
demoteAllowed: specifies whether the object in this stage can be demoted to a previous stage.
Its value can either be true or false. If it is unspecified, its value is assumed to be true.
expirationDays: specifies the number of days after which the object should be automatically
deleted from the repository. Usually this will only be specified in the last phase of the lifecycle, if you
want an obsolete object to be automatically deleted after a certain period of time. If it is unspecified,
its value is assumed to be 0, which means that the object is not deleted automatically and will be
preserved indefinitely.
231

A stage definition may also contain any number of permission child elements. They are used to
specify permissions applicable in the current stage. A permission element consists of the following
child elements:
type: specifies the type of the permission. One or more than one type elements can be specified
in a permission element. Valid values of type are:
access: specifies who can access (or view) this object in the user interface
create: specifies who can add a child to a folder object
delete: specifies who can delete the object
modify : specifies who can modify the object
lifecycle: specifies who can perform lifecycle operations such as promote and demote
download: specifies who can download a file or folder object
fullControl: specifies who has full control over the object. Full control means all permissions
member: specifies the name of the user or group for which the permission is specified. One or more
than one member elements can be specified in a permission element. Its value must correspond
to a user or group name defined in EKM. You can also use * to specify the user who created the
object.
The example in Figure 2: Stage Example 1 (p. 232) shows a lifecycle stage named Obsolete which does
not have any permissions associated with it, whose demoteAllowed attribute is set to false and
whose expirationDays attribute is set to 365 days. This means that once the object goes to this
stage, only root users can access this object, it cannot be demoted to a previous stage and it will reside
in the repository for 365 days before it is automatically deleted.
Figure 2: Stage Example 1
stage name="Obsolete" description="description for obsolete" demoteAllowed="false"
expirationDays="365" />
The example in Figure 3: Stage Example 2 (p. 232) shows a lifecycle stage named Release with three
permission elements. The all group is given access and download permissions. Turbine Group
and Combustion Group have been given modify permission and Turbine Group Lead and
Combustion Group Lead have been given lifecycle permission. Because the expirationDays
attribute is not set, the object in this stage will not be automatically deleted. Also, because demoteAl
lowed is not specified, the object in this stage can be demoted to a previous stage.
Figure 3: Stage Example 2
<stage name="Release" description="description for release">
<permission>
<type>access</type>
<type>download</type>
<member>all</member>
</permission>
<permission>
<type>modify</type>
<member>Turbine Group</member>
<member>Combustion Group</member>
</permission>
<permission>
232

<type>lifecycle</type>
<member>Turbine Group Lead</member>
<member>Combustion Group Lead</member>
</permission>
</stage>
C.1.2.3. Transitions
A transition is used to specify the subsequent and preceding stages of the any lifecycle stage. A transition
can also optionally specify a signoff process for moving to the next stage.
A transition definition consists of the following required attributes:
source: specifies the name of the lifecycle stage from which the transition begins
destination: specifies the name of the lifecycle stage at which the transition ends
The transitions must adhere to the following rules:
Like workflows, lifecycles should have exactly one start stage. The start stage is the stage that is not
the destination of any transition. Unlike workflows, lifecycles can have more than one end stage. The
end stage is the stage that is not the source of any transition.
Like workflows, lifecycles must be acyclic. For example, if you have a transition from stage A to stage
B, then you cant have a transition from stage B to stage A. Similarly, if you have defined transitions
from stage A to stage B and from stage B to stage C, you cant have a transition from stage C to stage
A. In this way, lifecycles, like workflows, are always Directed Acyclic Graphs.
A transition definition may also consist of the following optional attributes:
promoteValidationMacro: specifies the name of the macro that is used to perform validation
before a promote request can be processed
promoteActionMacro: specifies the name of the macro that is used to perform an automatic action
after a promotion request has been processed
demoteValidationMacro: specifies the name of the macro that is used to perform validation
before a demote request can be processed
demoteActionMacro: specifies the name of the macro that is used to perform an automatic action
after a demote request has been processed
These optional macros are usually specified in the optional script element at the beginning of a lifecycle definition. See the Defining Macros and Custom Dialogs chapter in the EKM Users Guide to learn
more about macro definition and scripting. All these macros take the following arguments:
an instance of ModelObjectInterface that specifies the object associated with the lifecycle.
the name of the next stage.
These optional macros do not return any values. The validation macros may throw an exception if validation fails. The action macros specify commands that are to be executed when the stage change
succeeds. For example, the following XML listing shows a transition with all four macros defined, followed
by the definition of each macro. This is a dummy example that is used for illustration purposes, only.
<transition source="Draft" destination="Release"
promoteActionMacro="promoteToReleaseAction"
233

promoteValidationMacro="promoteToReleaseValidation"
demoteActionMacro="demoteToDraftAction"
demoteValidationMacro="demoteToDraftValidation" />
<script>
promoteToReleaseValidation(model, nextStage) {
if (!model.getChildNames().contains("test-child"))
throw new RuntimeException("test-child doesn't exist");
}
promoteToReleaseAction(model, nextStage) {
model.addChild(ekm.createObject("auto-created-folder", "Folder"));
}
demoteToDraftValidation(model, nextStage) {
if (model.getChildNames().contains("test-child"))
throw new RuntimeException("test-child exists");
}
demoteToDraftAction(model, nextStage) {
model.getChild("auto-created-folder").delete();
}
</script>
In the listing, the promoteToReleaseValidation macro verifies that the object associated with
the lifecycle has a child named test-child and the demoteToDraftValidation macro verifies
that such a child does not exist. The promoteToReleaseAction adds a folder named auto-created-folder to the object and the demoteToDraftAction removes this folder.
A transition definition may also contain any number of promoteSignoff or demoteSignoff child
elements. These elements are used to specify any number of signoff processes that can be associated
with promotion or demotion. Multiple signoff elements can be defined to model a multi-level signoff
process. For example if you specify two promoteSignoff elements, it means that the promotion
process will involve a two-level signoff. The first level signoff will need to be completed before the
second level signoff can begin.
A signoff element definition consists of the following required attributes:
level: specifies the name of signoff level. There are no character restrictions for the level definition.
members: specifies the names of users and groups involved in the signoff at this level. If you specify
more than one user or group, you will need to separate their names by a comma. For example: group1, group-2. In some cases, you may want to use the same lifecycle definition for various teams. In
this case, say the stages and transitions are the same and the only difference is the members that
are involved in the signoff process. For these situations, you can define a macro for determining the
member names. This macro could use some logic, based on object type or path, for example, to determine the list of members to be used in a given context.
If you want to make use of this feature, you must do the following:
Define the macro in the script tag as described above. The macro should take two arguments:
the object associated with the lifecycle and the name of the next stage. It should return either
an array or a list of strings. Each item in the list or array should correspond to a user or group
name. If it returns null or an empty list or array, then the signoff process will advance to the
next signoff level if it exists. If no more levels exist, the signoff process will be completed and
the request will be approved. The following XML listing shows a sample macro definition of
this type. In the example, the list of approvers will be user1 if the object associated with the
234

lifecycle is in the /Repository/bar folder, user1 and user2 if the object is in /Repository/foo, or null if the object is in any other folder.
<script>
releaseLevel1(model, nextStage) {
if (model.getPath().startsWith("/Repository/foo"))
return new String[] {"user1", "user2"};
else if (model.getPath().startsWith("/Repository/bar")) {
list = new LinkedList();
list.add("user1");
return list;
}
}
</script>
Define the members to be $ followed by the macro name as shown in the following listing:
<promoteSignoff members="$releaseLevel1" level="1""/>
A signoff element definition consists of the following optional attributes:

inclusive: specifies whether all members of the signoff committee need to approve the signoff
at this level. Its value can be either true or false. If it is set true or it is not specified (in which
case its value assumed to be true), then all members of the signoff committee must approve the
signoff at this level. If it is set to false, then any member can approve the level signoff.
dueDays: specifies the number of days allowed for the signoff. If a user has not approved or rejected
the signoff by then, a daily email reminder is sent to the user. If it is not specified, then the value is
assumed to be 7.
The example in Figure 4: Transition Example 1 (p. 235) shows a transition from Draft stage to In-Work
stage. It has a single-level promote signoff involving Turbine Group. Because the inclusive attribute
is set to false, the signoff will be completed when any user from the Turbine Group accepts or
rejects the signoff.
Figure 4: Transition Example 1
<transition source="Draft" destination="In-Work">
<promoteSignoff level="group" members="Turbine Group" inclusive="false"/>
</transition>
The example in Figure 5: Transition Example 2 (p. 235) shows another transition from In-Work stage
to Release stage. It has a two-level promote signoff. The first level involves Combustion Group
Lead and Turbine Group Lead and the second level involves VP Engineering. Because the
inclusive attribute is not specified, all users in the first level will need to accept the signoff before it can
advance to the next level.
Figure 5: Transition Example 2
<transition source="In-Work" destination="Release">
<promoteSignoff level="lead" members="Combustion Group Lead, Turbine Group Lead"/>
<promoteSignoff level="vp" members="VP Engineering"/>
</transition>
235
236

ANSYS EKM Administration Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ANSYS EKM Administration Guide

Uploaded by

Copyright:

Available Formats

ANSYS EKM Administration Guide

Copyright and Trademark Information

U.S. Government Rights

Chapter 1: Using This Guide

Chapter 2: Overview of Servers and Workspaces

Planning Server Installations

How Workspaces are Used

Overview of Servers and Workspaces

2.1. Distributed Servers and Caching

Distributed Servers and Caching

2.1.1. Cache Architecture

2.1.2. Cache Configuration

Chapter 3: Setting Up Users and Groups

3.1. Introduction to Users and Groups

Setting Up Users and Groups

3.2. Adding and Modifying Users

3.2.1. Adding a New User

Adding and Modifying Users

Setting Up Users and Groups

Adding and Modifying Groups

3.2.2. Editing a Users Profile

3.3. Forcing the Logout of a User

next to their name.

3.4. Adding and Modifying Groups

3.4.1. Adding a New Group

Setting Up Users and Groups

Enter a name for the new group.

3.4.2. Editing Group Membership

Adding and Modifying Groups

Chapter 4: Creating and Managing Workspaces From the

4.1. Logging In and Out of the EKM Server Administration

Enter the password. The default password is superuser123.

Click Log In. The EKM Server Administration window opens.

Creating and Managing Workspaces From the Administration Interface

Resetting a Lost Superuser Password

4.2. Changing the Superuser Password

Enter the same password in the Confirm Password field.

4.3. Resetting a Lost Superuser Password

Open the ekm.xml file in a text editor.

Creating and Managing Workspaces From the Administration Interface

4.4. Cleaning Up Unused Files

Creating a New, Empty Workspace

4.5. Creating a New, Empty Workspace

Click Add Workspace.... The New Workspace dialog box appears.

Creating and Managing Workspaces From the Administration Interface

In the Name field, enter a name for the workspace.

Do not check the Import an exported workspace? box.

Click OK. A Progress dialog box opens to report the status.

Creating a New Workspace from an Exported Workspace

4.6. Creating a New Workspace from an Exported Workspace

Creating and Managing Workspaces From the Administration Interface

Type a name for the workspace.

Check the Import an exported workspace? box.

A Progress dialog box reports the progress of the import:

After creating the new workspace from the exported workspace:

4.7. Renaming Workspaces

Navigate to the <ekm-install>/<repository>/workspaces folder and then rename the

4.8. Deleting Workspaces

Creating and Managing Workspaces From the Administration Interface

4.8.1. Deleting Workspaces from Evaluation Servers

Stop the EKM Evaluation server using the script:

Delete the folder associated with the MYEKM workspace:

Creating and Managing Workspaces From the Administration Interface

Start the EKM Evaluation server using the script: