ANSYS EKM Administration Guide

ANSYS EKM Administration Guide
ANSYS, Inc. Release 17.0

Southpointe January 2016
2600 ANSYS Drive
Canonsburg, PA 15317 ANSYS, Inc. is
[email protected] certified to ISO
9001:2008.
http://www.ansys.com
(T) 724-746-3304
(F) 724-514-9494
Copyright and Trademark Information
© 2015 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, AIM
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 CONFID-
ENTIAL 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, Contact ANSYS, Inc.
Published in the U.S.A.

Table of Contents
1. Using This Guide ..................................................................................................................................... 1
1.1. Path Variables ................................................................................................................................... 2
2. Overview of Servers and Workspaces ..................................................................................................... 3
2.1. Distributed Servers and Workspace Access ........................................................................................ 5
2.1.1. Caching Data when Transferring Files ....................................................................................... 6
2.1.2. Setting Up Caching .................................................................................................................. 8
3. Setting Up Users and Groups .................................................................................................................. 9
3.1. Introduction to Users and Groups ..................................................................................................... 9
3.2. Automatic Creation of User Accounts .............................................................................................. 10
3.3. Adding and Modifying Users ........................................................................................................... 11
3.3.1. Adding a New User ................................................................................................................. 11
3.3.2. Editing a User’s Profile ............................................................................................................ 14
3.4. Forcing the Sign-out of a User ......................................................................................................... 14
3.5. Designating a Root User .................................................................................................................. 14
3.6. Accessing a User’s Data ................................................................................................................... 15
3.7. Adding and Modifying Groups ........................................................................................................ 16
3.7.1. Adding a New Group .............................................................................................................. 16
3.7.2. Editing Group Membership .................................................................................................... 18
4. Creating and Managing Workspaces .................................................................................................... 19
4.1. Signing In and Out of EKM Server Administration ............................................................................ 19
4.2. Changing the Superuser Password .................................................................................................. 21
4.3. Resetting a Lost Superuser Password ............................................................................................... 21
4.4. Cleaning Up Unused Files ................................................................................................................ 22
4.5. Creating a New, Empty Workspace ................................................................................................... 23
4.6. Transferring a Workspace Between EKM Servers ............................................................................... 25
4.6.1. Exporting a Workspace ........................................................................................................... 25
4.6.2. Importing a Workspace .......................................................................................................... 26
4.6.3. Converting an Exported Workspace into a Human-readable Format ........................................ 28
4.7. Renaming Workspaces .................................................................................................................... 28
4.8. Deleting Workspaces ...................................................................................................................... 29
4.9. Migrating Workspaces ..................................................................................................................... 31
5. Restricted and Unrestricted Configuration of Workspaces .................................................................. 35
5.1. Restricted Configuration ................................................................................................................. 35
5.1.1. Starting Restricted Configuration ........................................................................................... 37
5.1.2. Applying the Configuration .................................................................................................... 38
5.1.3. Reverting to a Previous Configuration ..................................................................................... 38
5.1.4. Accepting the Configuration .................................................................................................. 39
5.2. Unrestricted Configuration .............................................................................................................. 40
5.3. Configuring Workspace Settings ...................................................................................................... 41
5.3.1. Schema Definition .................................................................................................................. 42
5.3.2. Configuration Settings in WorkspaceConfig.xml ...................................................................... 42
6. Configuring EKM Server Settings ......................................................................................................... 51
6.1. Schema Definition for an EKM Server ............................................................................................... 51
6.2. Specifying General Server Settings .................................................................................................. 52
6.3. Optional Settings ............................................................................................................................ 66
7. Defining Custom Types ......................................................................................................................... 69
7.1. Overview of Custom Types .............................................................................................................. 69
7.1.1. About Built-in Types ............................................................................................................... 70
7.2. Suggested Steps for Defining Custom Types .................................................................................... 71
7.3. Defining Custom Types Directly in EKM ........................................................................................... 72
Release 17.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. Defining a New Custom Type .................................................................................................. 72

7.3.1.1. Defining Properties for a Custom Type ........................................................................... 74
7.3.1.2. Defining Children for a Custom Type .............................................................................. 76
7.3.1.3. Defining Mixins for a Custom Type ................................................................................. 77
7.3.1.4. Defining Type Attributes for a Custom Type .................................................................... 78
7.3.1.5. Defining Scripts for a Custom Type ................................................................................. 87
7.3.1.6. Creating Actions for a Custom Type ................................................................................ 88
7.3.1.7. Creating Custom Views for a Type .................................................................................. 92
7.3.2. Editing a Custom Type ............................................................................................................ 94
7.4. Defining Custom Types Using XML .................................................................................................. 94
7.4.1. Schema Definition for Custom Types ....................................................................................... 94
7.4.2. Defining Properties Using XML ............................................................................................... 95
7.4.3. Defining Actions Using XML ................................................................................................... 99
7.5. Custom Type Examples ................................................................................................................. 102
7.5.1. Custom Folder Structures ..................................................................................................... 102
7.5.2. Custom Analysis Projects ...................................................................................................... 104
7.5.3. Custom File Formats ............................................................................................................. 105
7.5.3.1. Extracting Metadata from Custom File Formats ............................................................ 107
7.5.3.2. Extracting Reports from Custom File Formats ............................................................... 108
7.6. Extending Built-in Types ................................................................................................................ 110
7.6.1. Migrating Built-in extensions or Custom Types ...................................................................... 110
8. Integrating EKM with Remote Solve Manager (RSM) .......................................................................... 111
8.1. Important Changes for R16 Users .................................................................................................. 111
8.2. Steps for Setting Up Batch Job Submission .................................................................................... 112
8.3. EKM and RSM Platform Support .................................................................................................... 113
8.3.1. Distribution of Services ........................................................................................................ 113
8.3.2. Supported Platforms ............................................................................................................ 116
8.4. Installing RSM for use with EKM ..................................................................................................... 116
8.5. Configuring RSM for use with EKM and Third-Party Clusters ........................................................... 117
8.5.1. Configuring RSM Automatically ............................................................................................ 118
8.5.2. Configuring RSM Manually ................................................................................................... 119
8.5.2.1. Specifying a Directory for RSM Configuration Files ........................................................ 119
8.5.2.2. Generating RSM Configuration Files ............................................................................. 120
8.5.2.3. Modifying RSM Configuration Files ............................................................................... 124
8.5.2.4. Starting RSM Services on Windows ............................................................................... 126
8.5.2.5. Starting RSM Services on Linux .................................................................................... 128
8.6. EKM and RSM Job Directories ........................................................................................................ 129
8.6.1. How Job Data Files are Handled in EKM and RSM .................................................................. 129
8.6.1.1. The Data Management Process .................................................................................... 130
8.6.1.2. The Creation and Structure of Job Directories ............................................................... 130
8.6.1.3. Access and Permission Requirements of the Job Data Directory .................................... 131
9. Defining EKM Servers, Queues, and External Applications ................................................................ 133
9.1. Adding EKM Servers ...................................................................................................................... 134
9.2. Defining EKM Cache Servers .......................................................................................................... 134
9.2.1. Creating a New EKM Cache Server ........................................................................................ 134
9.2.2. Editing an Existing EKM Cache Server .................................................................................... 136
9.3.Types of Queues ............................................................................................................................ 136
9.4. Managing Queues ......................................................................................................................... 137
9.4.1. Synchronizing Job Submission Queues ................................................................................. 137
9.4.2. Defining Job Submission Queue Settings .............................................................................. 138
9.5. Defining External Applications ...................................................................................................... 139
9.5.1. Predefined External Applications .......................................................................................... 140
iv of ANSYS, Inc. and its subsidiaries and affiliates.
9.5.2. Defining External Applications Directly in EKM ...................................................................... 142

9.5.2.1. Creating a New External Application ............................................................................ 142
9.5.2.2. Editing an External Application Definition .................................................................... 143
9.5.2.3. Editing an External Application Using XML ................................................................... 144
9.5.3. Defining External Applications Using XML ............................................................................ 145
9.5.3.1. Schema Definition for Applications .............................................................................. 145
9.5.3.2. Defining External Applications Using XML .................................................................... 147
9.6. Running Interactive Jobs in EKM .................................................................................................... 147
9.6.1. Running Remote Desktop Sessions ....................................................................................... 148
10. Configuring EKM Mobile ................................................................................................................... 149
10.1. Running the Mobile Connector on the Same Host as the EKM Server ............................................ 149
10.2. Running the Mobile Connector on a Host Other than the EKM Server ........................................... 150
11. Defining and Configuring Lifecycles ................................................................................................. 153
11.1. Introduction to Lifecycles ............................................................................................................ 153
11.2. Lifecycle Terminology .................................................................................................................. 154
11.3. Basic Steps for Creating, Configuring, and Managing Lifecycles ..................................................... 155
11.4. Defining Lifecycles in EKM Studio ................................................................................................ 155
11.4.1. Steps for Defining New Lifecycles ....................................................................................... 156
11.4.2. Defining and Editing Lifecycle Stages .................................................................................. 156
11.4.2.1. Inserting New Stages ................................................................................................. 156
11.4.2.2. Editing Stages ............................................................................................................ 157
11.4.2.3. Renaming Stages ....................................................................................................... 159
11.4.2.4. Deleting Stages ......................................................................................................... 159
11.4.3. Defining and Editing Lifecycle Transitions ........................................................................... 159
11.4.3.1. Inserting New Transitions ........................................................................................... 160
11.4.3.2. Editing Transitions ..................................................................................................... 160
11.4.3.3. Using Macros in Lifecycle Definitions .......................................................................... 162
11.4.3.4. Deleting Transitions ................................................................................................... 163
11.4.4. Saving Lifecycle Files .......................................................................................................... 164
11.4.5. Opening Lifecycle Files ....................................................................................................... 164
11.4.6. Editing Lifecycle Attributes ................................................................................................. 165
11.5. Enabling Lifecycles ...................................................................................................................... 166
11.6. Displaying Lifecycles ................................................................................................................... 167
11.7. Promoting a Lifecycle Stage ........................................................................................................ 170
11.8. Demoting a Lifecycle Stage ......................................................................................................... 171
11.9. Managing Lifecycle Signoff Requests ........................................................................................... 172
11.9.1. Approving a Lifecycle Signoff Request ................................................................................ 173
11.9.2. Rejecting a Lifecycle Signoff Request .................................................................................. 174
11.9.3. Cancelling a Lifecycle Signoff Request ................................................................................. 175
11.10. Setting a Lifecycle Stage ............................................................................................................ 175
11.11. Configuring Lifecycles for a Workspace ...................................................................................... 176
12. Scripts and Journals .......................................................................................................................... 177
12.1. Introduction to Scripts and Journals ............................................................................................ 177
12.2. Defining Scripts Using a Supported Scripting Language ............................................................... 179
12.3. Using EKM's Scripting Interface ................................................................................................... 179
12.4. Using Sample Scripts Supplied by EKM ........................................................................................ 181
12.4.1. Python Scripts .................................................................................................................... 182
12.5. Scripting Actions ......................................................................................................................... 183
12.6. Recording Journal Scripts ............................................................................................................ 183
12.6.1. Start Recording a Journal Script .......................................................................................... 185
12.6.2. Stop Recording a Journal Script .......................................................................................... 186
12.7. Running Journal Scripts ............................................................................................................... 186
of ANSYS, Inc. and its subsidiaries and affiliates. v
12.8. Example of Journal Recording and Execution ............................................................................... 187

12.9. Running Python and BeanShell Scripts From a Command Window ............................................... 188
12.10. Testing or Debugging a Process Template .................................................................................. 190
12.11. Viewing a Script Error Log .......................................................................................................... 193
13. Defining Custom Dialogs, Wizards and Applications ........................................................................ 195
13.1. Defining Custom Dialog Boxes .................................................................................................... 195
13.1.1. Defining a Custom User Interface ........................................................................................ 196
13.1.1.1. XHTML Files ............................................................................................................... 197
13.1.1.2. Sample XHTML Code for a Custom Dialog Box ............................................................ 198
13.1.1.3. User Interface Components ........................................................................................ 201
13.1.1.3.1. Layout and Style ............................................................................................... 201
13.1.1.3.2. Embedded Images ............................................................................................ 201
13.1.1.3.3. Linked Images ................................................................................................... 201
13.1.1.3.4. Object Links ...................................................................................................... 202
13.1.1.3.5. User Inputs ....................................................................................................... 202
13.1.1.3.6. Check Boxes ...................................................................................................... 203
13.1.1.3.7. Radio Buttons ................................................................................................... 204
13.1.1.3.8. Selection Menu ................................................................................................. 204
13.1.1.3.9. List Box ............................................................................................................. 204
13.1.1.4. Invoking Methods from UI Components ..................................................................... 204
13.1.2. Defining Dialog Box Steps and Variables ............................................................................. 205
13.1.3. Example: Creating a Custom Interface for Fluent Batch Jobs ................................................. 207
13.2. Defining and Using Custom Applications ..................................................................................... 215
13.3. Creating a Custom Application .................................................................................................... 216
13.4. Executing a Custom Application .................................................................................................. 217
13.5. Modifying an EKM Application .................................................................................................... 219
14. EKM Connector End User API ............................................................................................................ 221
14.1. Installing the API Library .............................................................................................................. 221
14.2. Using the Library in Client Applications ....................................................................................... 223
14.2.1. Opening and Closing a Connection ..................................................................................... 223
14.2.2. API Interfaces ..................................................................................................................... 225
14.2.3. Searching the EKM Repository ............................................................................................ 226
14.2.4. C.R.U.D. .............................................................................................................................. 229
14.2.5. Checking Permissions ......................................................................................................... 231
14.2.6. Locking and Unlocking Objects .......................................................................................... 232
14.2.7. Version Control ................................................................................................................... 233
14.2.8. Transferring Files ................................................................................................................ 234
14.2.9. Managing Users and Groups ............................................................................................... 235
14.2.10. Miscellaneous Operations ................................................................................................. 236
14.3. Submitting and Monitoring Jobs ................................................................................................. 237
14.4. Building and Running a Java Application ..................................................................................... 242
14.5. Running a Python Script Using Jython ......................................................................................... 243
14.6. Writing and Running a Python Script Using IronPython ................................................................ 243
14.6.1. Accessing the JAR Files ....................................................................................................... 243
14.6.2. Accessing the C# DLLs ........................................................................................................ 243
14.6.3. Directory Structure for an IronPython Script without Workbench ......................................... 243
14.6.4. Writing the Script ............................................................................................................... 244
14.7. Building and Executing C# Sample .............................................................................................. 246
14.8. API Documentation ..................................................................................................................... 246
15. Units: Defining and Configuring Using XML ..................................................................................... 247
15.1. Schema Definition for Units ......................................................................................................... 248
15.2. Adding a New Unit ...................................................................................................................... 249
vi of ANSYS, Inc. and its subsidiaries and affiliates.
15.3. Adding a New Quantity ............................................................................................................... 250

15.4. Adding a New Unit System .......................................................................................................... 250
16. Miscellaneous Tasks .......................................................................................................................... 251
16.1. Configuring a Common Scripts Library ........................................................................................ 251
16.2. Gathering Usage Statistics ........................................................................................................... 252
16.3. Connecting to Remote File Servers .............................................................................................. 252
16.3.1. Defining a New Remote File Server ..................................................................................... 252
16.3.2. Using Built-in Remote File Servers ....................................................................................... 254
16.4. Managing Logs ........................................................................................................................... 254
16.5. Using VCollab for 3D Visualization in EKM .................................................................................... 255
16.6. Using the EKM Server Diagnostics Tool ........................................................................................ 256
16.7. Lifecycle Approval Process for Process Templates ......................................................................... 256
16.8. Using a Custom Background Image on the EKM Sign-in Page ....................................................... 257
16.9. Adding Custom Text to the EKM Sign-in Box ................................................................................ 257
16.10. Customizing the Heading on the EKM Title Bar ........................................................................... 258
17. Backing Up and Restoring EKM ......................................................................................................... 259
17.1. Data Stored by EKM ..................................................................................................................... 259
17.1.1. The EKM Database .............................................................................................................. 259
17.1.2. The EKM Data Directory ...................................................................................................... 259
17.1.3. The EKM Root Directory ...................................................................................................... 259
17.2. Backing Up EKM .......................................................................................................................... 260
17.2.1. Backup Procedure .............................................................................................................. 260
17.2.1.1. Garbage Collection .................................................................................................... 261
17.2.1.2. Backing up the EKM Database .................................................................................... 262
17.2.1.3. Backing up the EKM Data, Version Root, Job Data, and Repository Directories .............. 262
17.3. Restoring EKM ............................................................................................................................ 262
17.3.1. Restoring Procedure ........................................................................................................... 262
17.3.1.1. Restoring the EKM Database ...................................................................................... 263
17.3.1.2. Restoring the EKM Data, Version Root, Job Data, and Repository Directories ................. 263
17.3.1.3. Clearing the Search Indices ........................................................................................ 263
A. Java Security Manager and EKM Scripting .............................................................................................. 265
B. Built-in Types - Reference ....................................................................................................................... 267
B.1. Abaqus Input (AbaqusInput) ......................................................................................................... 267
B.2. Abaqus Output Database (AbaqusOutputDatabase) ...................................................................... 267
B.3. Abaqus Result (AbaqusResult) ....................................................................................................... 267
B.4. Adobe Acrobat Document (AdobePdfFile) ..................................................................................... 267
B.5. AIM System in Workbench ............................................................................................................. 267
B.6. Analysis Project (AnalysisContainer) .............................................................................................. 268
B.7. Ansoft Designer File (AnsoftDesigner) ........................................................................................... 268
B.8. ANSYS Database/Mechanical APDL Database (AnsysDatabase) ...................................................... 269
B.9. ANSYS Input/Mechanical APDL Input (AnsysInput) ........................................................................ 270
B.10. ANSYS Output/Mechanical APDL Output (AnsysOutput) .............................................................. 270
B.11. ANSYS Result/Mechanical APDL Result (AnsysResult) ................................................................... 270
B.12. ANSYS Viewer File (AnsysViewerFile) ............................................................................................ 270
B.13. Applications Grid (ApplicationsGrid) ............................................................................................ 270
B.14. Approval Task (ApprovalWorkItem) .............................................................................................. 270
B.15. Archive (Archive) ......................................................................................................................... 271
B.16. AUTODYN Database (AutodynDatabase) ...................................................................................... 271
B.17. Base Job (BaseJob) ...................................................................................................................... 271
B.18. Batch Job Submission Queue (BatchQueue) ................................................................................. 271
B.19. Batch Task (BatchWorkItem) ........................................................................................................ 271
B.20. BladeGen Database (BladeGenDatabase) ..................................................................................... 272
of ANSYS, Inc. and its subsidiaries and affiliates. vii
B.21. CAE Model File (CaeModelFile) .................................................................................................... 272

B.22. Cache Server (CacheServer) ......................................................................................................... 272
B.23. Catalog (Catalog) ........................................................................................................................ 272
B.24. CFX Definition (CfxDefinition) ...................................................................................................... 272
B.25. CFX Result (CfxResult) ................................................................................................................. 273
B.26. CFX Session File (CfxSessionFile) .................................................................................................. 273
B.27. CFX State File (CfxStateFile) ......................................................................................................... 273
B.28. Comparison Report (ComparisonReport) ..................................................................................... 273
B.29. Container (Container) .................................................................................................................. 273
B.30. Data Extraction Monitor (DataExtractionMonitor) ........................................................................ 273
B.31. Data Extraction Monitor Container (DataExtractionMonitorContainer) ......................................... 274
B.32. Data Extraction Queue (DataExtractionQueue) ............................................................................ 274
B.33. DesignXplorer Database (R11) (DesignXplorerDatabase) .............................................................. 274
B.34. DesignModeler Database (WorkBenchDesignModelerFile) ........................................................... 274
B.35. Discussion Board (DiscussionBoard) ............................................................................................ 274
B.36. EKM Application (Application) ..................................................................................................... 274
B.37. EKM Journal File (ScriptFile) ......................................................................................................... 274
B.38. EKM Object (Model) .................................................................................................................... 275
B.39. EKM Process Template (Workflow) ............................................................................................... 275
B.40. EKM Server (Server) ..................................................................................................................... 275
B.41. EKM Type (Type) ......................................................................................................................... 275
B.42. Electronics Desktop File (ElectronicsDesktop) .............................................................................. 276
B.43. Engineering Data Database (R11) (WorkBenchEngineeringData) .................................................. 276
B.44. ePhysics File (AnsoftEPhysics) ...................................................................................................... 276
B.45. External Application (ExternalApplication) ................................................................................... 276
B.46. FE Model (FeModelInput) ............................................................................................................ 276
B.47. FE Modeler Database (FeModelerDatabase) ................................................................................. 277
B.48. File (File) ..................................................................................................................................... 277
B.49. File Server (ExternalResourceFs) .................................................................................................. 278
B.50. Fluent Case (FluentCase) ............................................................................................................. 278
B.51. Fluent Data (FluentData) ............................................................................................................. 278
B.52. Fluent Plot (FluentPlot) ................................................................................................................ 278
B.53. Folder (Folder) ............................................................................................................................ 279
B.54. Group (Group) ............................................................................................................................ 279
B.55. HFSS File (HfssProject) ................................................................................................................. 279
B.56. Icepak Packed Project (IcepakPackProject) ................................................................................... 280
B.57. Icepak Project Data (IcepakProjectData) ....................................................................................... 280
B.58. Image (Image) ............................................................................................................................. 281
B.59. Imported Report (ImportedReport) ............................................................................................. 281
B.60. Interactive Job (InteractiveJob) .................................................................................................... 281
B.61. Interactive Job Submission Queue (InteractiveQueue) ................................................................. 281
B.62. Job (Job) ..................................................................................................................................... 282
B.63. Job Submission Queue (JobSubmissionQueue) ........................................................................... 282
B.64. Job Submission Server (JobSubmissionServer) ............................................................................ 282
B.65. Job Template (JobTemplate) ........................................................................................................ 282
B.66. Job Template Container (JobTemplateContainer) ......................................................................... 282
B.67. Lifecycle (Lifecycle) ..................................................................................................................... 283
B.68. Maxwell File (AnsoftMaxwell) ...................................................................................................... 283
B.69. Meshing Database (MeshingDatabase) ........................................................................................ 284
B.70. Microsoft Excel Worksheet (MSOfficeExcelFile) ............................................................................. 284
B.71. Microsoft Powerpoint Presentation (MSOfficePowerpointFile) ...................................................... 284
B.72. Microsoft Word Document (MSOfficeDocumentFile) .................................................................... 284
viii of ANSYS, Inc. and its subsidiaries and affiliates.
B.73. My Data (MyData) ....................................................................................................................... 284

B.74. NASTRAN Bulk Data (NastranBulkData) ........................................................................................ 284
B.75. NASTRAN Result (NastranResult) ................................................................................................. 285
B.76. Polyflow Data (PolyflowData) ...................................................................................................... 285
B.77. Polyflow Export (UNS) (PolyflowExportFile) .................................................................................. 285
B.78. Process Container (ProcessContainer) .......................................................................................... 285
B.79. Public Saved Query (PublicSavedQueryContainer) ....................................................................... 285
B.80. Q3D File (AnsoftQ3D) .................................................................................................................. 285
B.81. Queue (Queue) ........................................................................................................................... 285
B.82. Remote Folder (RemoteFolder) .................................................................................................... 286
B.83. Report (Report) ........................................................................................................................... 286
B.84. Saved Query (SavedQuery) .......................................................................................................... 286
B.85. Saved Query Container (SavedQueryContainer) ........................................................................... 286
B.86. Search Results Report (SearchResultsReport) ............................................................................... 286
B.87. Shortcut (Link) ............................................................................................................................ 286
B.88. Simplorer File (AnsoftSimplorer) .................................................................................................. 286
B.89. Simulation Details Report (CaeModelSummaryReport) ................................................................ 286
B.90. Siwave File (AnsoftSiwave) .......................................................................................................... 287
B.91. SpaceClaim Document (SpaceClaimDocument) ........................................................................... 287
B.92. Update Analysis Project Task (UpdateAnalysisProjectWorkItem) ................................................... 287
B.93. URL (Url) ..................................................................................................................................... 287
B.94. User (User) .................................................................................................................................. 287
B.95. VCollab File (VcollabCompressedFile) .......................................................................................... 287
B.96. Workbench Journal File (WorkBenchJournalFile) .......................................................................... 287
B.97. Workbench Design Point File (WorkBenchDesignPointFile) .......................................................... 288
B.98. Workbench Project Archive File (WorkBenchProjectArchiveFile) ................................................... 288
B.99. Workbench Project File (WorkBenchProjectFile) ........................................................................... 288
B.100. Workbench Project File R11 (WorkBenchProjectFileR11) ............................................................. 288
B.101. Workbench Simulation/Mechanical Database (WorkBenchSimulation) ....................................... 288
B.102. Process (Process) ....................................................................................................................... 289
B.103. Task (WorkItem) ........................................................................................................................ 289
C. Lifecycles: Defining and Configuring Using XML ..................................................................................... 291
C.1. Defining Lifecycles Using XML ....................................................................................................... 291
C.1.1. Schema Definition for Lifecycles ........................................................................................... 291
C.1.2. Defining a Lifecycle XML File ................................................................................................ 293
C.1.2.1. Types .......................................................................................................................... 293
C.1.2.2. Stages ......................................................................................................................... 293
C.1.2.3. Transitions ................................................................................................................... 295
of ANSYS, Inc. and its subsidiaries and affiliates. ix
x of ANSYS, Inc. and its subsidiaries and affiliates.
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. 9)
• Creating and Managing Workspaces (p. 19)
• Restricted and Unrestricted Configuration of Workspaces (p. 35)
• Configuring EKM Server Settings (p. 51)
• Defining EKM Servers, Queues, and External Applications (p. 133)
• Defining Custom Types (p. 69)
• Defining and Configuring Lifecycles (p. 153)
• Scripts and Journals (p. 177)
• Defining Custom Dialogs, Wizards and Applications (p. 195)
• Units: Defining and Configuring Using XML (p. 247)
• Miscellaneous tasks (p. 251) (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. 259)
Some administrative tasks may require editing XML files. This guide assumes that you have a basic un-
derstanding of XML constructs and syntax (schema definition). If you are unfamiliar with these techno-
logies, 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.
of ANSYS, Inc. and its subsidiaries and affiliates. 1
Using This Guide
1.1. Path Variables

This guide uses several EKM path variables as shorthand to describe locations of files or directories. In
most cases, these variables correspond to environment variables used by EKM for the same purpose. It
is not necessary to define these variables before installing EKM; in all cases, where an environment
variable needs to be set, explicit instructions will be given to do so.
For the definitions of the EKM path variables, see EKM Path Variables in the Engineering Knowledge
Manager.
2 of ANSYS, Inc. and its subsidiaries and affiliates.
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. When
you sign in to EKM, you sign in to a workspace on the EKM server.
Every EKM server contains one default user-accessible workspace with a repository for data. More
workspaces can be created if needed. When you set up a workspace you determine who can access it,
and specify the permissions that each user has in that workspace. Every EKM server also has a hidden
workspace for caching data from remote servers. This workspace may be involved in file transfers when
data is downloaded from or uploaded to a remote EKM server using the File Transfer Client.
Figure 2.1: Default Composition of an EKM Server
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 (see Figure 2.2: Multiple EKM Servers in a Global Setup (p. 5)). The recommended ar-
chitecture 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:
Overview of Servers and Workspaces
• 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 user’s behalf.
This enables users to quickly and asynchronously transfer large amount of data to the local server and
sign 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 among 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 sign 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. 4).
A detailed overview of regional servers and how they can be used for caching is provided in Distributed
Servers and Workspace Access (p. 5).
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
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 (p. 19). 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, per-user access level assignments, 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.
Distributed Servers and Workspace Access
2.1. Distributed Servers and Workspace Access

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.
Figure 2.2: Multiple EKM Servers in a Global Setup
Each EKM server has one default workspace that can be configured for user access, and more workspaces
can be created if needed.
Each workspace contains a repository for storing and sharing data. EKM will automatically create a user
account for a user when they first sign in to the workspace. Initially the user will have limited permissions,
but you can edit their permissions after the account has been created. When a user logs into EKM, they
are automatically logged into their default workspace, and can potentially access other workspaces if
they have access permission in those workspaces. See Configuring Login-related Access Settings in the
Installation Guide for details.
In the example above, the EKM server in New York contains a workspace whose data is shared globally
by users in New York, London and Tokyo. Any user who wants to be able to access the shared data on
the New York server must have a user account defined in the workspace on the New York server. If a
user in London wants to download a file from the server in New York, they must sign in to the global
workspace on the New York server. In this case file transfers occur over a Wide Area Network (WAN).
File transfer performance in this type of setup may be improved if caching is used. See Caching Data
when Transferring Files (p. 6) for more information.
In the sample configuration, the servers in London and Tokyo can have a regional workspace set up
that only users in that local region or office can access. This enables those users to collaborate among
themselves and share data locally if needed. In this case, user accounts are defined in a workspace on
the local EKM server, and file transfers occur over a Local Area Network (LAN).
2.1.1. Caching Data when Transferring Files

Caching can greatly improve file transfer performance in a globally distributed environment. In addition
to a user-accessible workspace, every EKM server has a hidden system workspace that can cache data
belonging to multiple remote servers when the File Transfer Client is used to upload/download files.
To set up caching in a distributed configuration, you must specify a Cache Server definition in the EKM
server that contains the repository that remote users will be accessing to upload/download files. This
establishes the connection between the EKM server that hosts the data and the EKM server that is being
used for caching. See Setting Up Caching (p. 8) for more information.
Sometimes you may want to use an EKM server only for caching. In this case the Default user-accessible
workspace is simply not used. It is important to note that users are not defined in the cache workspace.
Users cannot sign in to such a workspace, or perform any actions in it. Its sole purpose is to store, syn-
chronize and release data during file transfers.
Note
Caching is only used when the File Transfer Client is used to upload/download files. Caching
is not used when files are transferred using the Browser.
How Caching Works

In Figure 2.3: Distributed Setup with Dedicated Cache Server (p. 7), a user in London has a user account
on the EKM server in New York (the Master Server). In order for data to be cached on the EKM server
in London, a Cache Server definition must be specified on the Master Server in New York, and that user
must be assigned in the Cache Server definition.
When the user logs into the EKM server in New York, and chooses to upload or download a file, the
EKM server in New York recognizes that their user account is configured to use the Cache Server in
London, and communicates this to the File Transfer Client. The Cache Server will first check to see if it
has the file. If it does not, it will download it from the remote server in New York. At the same, the
Cache Server will stream the file data to the user’s machine.
The user does not interact with the Cache Server at all because caching occurs seamlessly behind the
scenes. To the user, it just seems like the file is being downloaded to their machine from the New York
server. The only noticeable indicator is the data reported in the File Transfer Client.
Distributed Servers and Workspace Access
Figure 2.3: Distributed Setup with Dedicated Cache Server
In the figure above, note that the EKM server in London does not have to be a dedicated Cache Server.
It can also have its own user-accessible workspaces for data and simulation management.
How Caching Improves Performance

As users transfer files between a remote server and their desktops, the cache in their local EKM server
becomes populated with files. Referring to Figure 2.3: Distributed Setup with Dedicated Cache Serv-
er (p. 7), if a user in London downloads a file from the New York server that has been downloaded
before by any user in London (and therefore exists in the cache workspace in London), the Cache
Server will first ensure that it has the latest copy of the file from New York. If the file has changed on
the New York server, the Cache Server will begin downloading the file from New York to get the cache
in London up-to-date, and the File Transfer Client will simultaneously stream the downloaded data to
the user’s machine.
If the file has not changed on the server in New York, the request can be processed by the Cache
Server in London without requiring a data transfer from the Master Server in New York. File transfer
performance will be improved because the user is getting the file directly from their regional server
over a LAN rather than from the Master Server over a WAN.
Similarly, when a user in London uploads a file to the Master Server in New York, the file is first uploaded
to the Cache Server in London. The Cache Server then uploads the file to the Master Server in New York
and retains a copy of the file in 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 Cache Server, there is a perceived performance gain. Once
the file is uploaded to the Cache Server, you do not have to wait for the Cache Server to upload the
file to the Master Server and you may perform other actions. This essentially enables the setup of a
queue of pending uploads (to the Master Server) that the Cache Server will handle later. You can even
sign out once the files have been transferred to the Cache Server.
2.1.2. Setting Up Caching

If you want to use caching in a globally distributed environment, you must create a Cache Server
definition in the EKM server that hosts the repository that remote users will be uploading files
to/downloading files from. A Cache Server definition indicates the host name of the EKM server that
will cache the data. Referring to Figure 2.3: Distributed Setup with Dedicated Cache Server (p. 7), a
Cache Server definition would need to be specified in the Master Server in New York in order to establish
caching on the server in London. See Creating a New EKM Cache Server (p. 134).
When creating the Cache Server definition, you will specify which remote 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. 11)). Referring once again to Figure 2.3: Distributed Setup with Dedicated Cache
Server (p. 7), when the administrator in New York creates a Cache Server definition on the Master
Server for the Cache Server in London, they will assign users based in London to the Cache Server
definition. Users based in New York would not be assigned to the Cache Server because they are already
accessing the data locally on the New York server. When a user in London (who is part of the Cache
Server definition) logs into the Master Server in New York, the Master Server will know to involve the
Cache Server in London when files are being transferred to/from the Master Server.
Note
When transferring files using the File Transfer Client, if a connection to the cache server
cannot be established or is lost, files will instead be transferred to/from the EKM repository
directly.
This behavior will be captured in the following logs:
• Windows: %APPDATA%\Ansys\v170\EKM\connector.log
• Linux: ~/.ansys/v170/EKM/connector.log
Chapter 3: Setting Up Users and Groups
Any person who wants to access EKM must have their own 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. Automatic Creation of User Accounts
3.3. Adding and Modifying Users
3.4. Forcing the Sign-out of a User
3.5. Designating a Root User
3.6. Accessing a User’s Data
3.7. 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.
• 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.
• 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.
During installation, a default Root User is also specified. The Root User is the primary administrator for
a workspace and the only user who can perform restricted workspace configuration. When a workspace
is initialized, a user account is automatically created for the designated Root User. That account cannot
be deleted unless a different user is designated as the Root User. See Designating a Root User (p. 14)
for details.
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 full permissions available and can perform almost any action within EKM. Note that only users
with Shared access can be members of this group (see Licensing and Access in the Installation Guide),
and once added to this group, their access level cannot be changed.
Users and groups are defined on the Administration/Users page in EKM.
Setting Up Users and Groups
Figure 3.1: Administration > Users
3.2. Automatic Creation of User Accounts

If a workspace has automatic account creation enabled, a user account is automatically created for a
user on the Administration/Users page when the user signs in to the workspace for the first time and
is successfully authenticated. When the account is created, the User Name entered during sign-in be-
comes the user’s EKM account name.
Note
• The Default workspace that is created during the EKM installation has automatic account creation
enabled by default.
• For new workspaces, automatic account creation is enabled if the Create new users automatically
check box was enabled when the workspace was created.
• EKM user names are case-sensitive. Once an account has been created with the user name entered
at first sign-in, the user must enter that exact user name for subsequent sign-ins.
• By default, users whose accounts have been automatically created will have Analyst privileges
initially (see Licensing and Access in the Installation Guide). You can change a user’s access level
in their profile. See Editing a User’s Profile (p. 14).
Upon the creation of the user’s account, an admin user can further edit the user’s profile and add him
or her to groups, as described in Editing a User’s Profile (p. 14). The user can also update his or her
own personal information and even upload a custom profile image to display on the title bar. See Setting
Your User Profile in the User’s Guide for details.
User accounts are not created in a workspace automatically if:
Adding and Modifying Users
• When signing in, a user fails to enter the correct credentials for the active login module, and he or she is
not authenticated. Note that user names and passwords are case-sensitive in EKM.
Also note that EKM will not allow two user accounts that differ only by case. For example, if an account
with the user name jsmith already exists, entering the variation JSMITH at sign-in would not result
in the creation of a new account.
For information about user sign-ins and authentication, see How User Logins Work in the Installation
Guide.
• The Create new users automatically option was disabled when the workspace was created, or the cre-
ateUsersAutomatically setting has been set to false in the WorkspaceConfig.xml file. See
Configuration Settings in WorkspaceConfig.xml (p. 42) for details.
• The workspace is one that has been migrated from version 15 or earlier, in which case auto account creation
is disabled by default. You can enable this setting in the WorkspaceConfig.xml file if desired. See
Configuration Settings in WorkspaceConfig.xml (p. 42) for details.
If you want to enable or disable automatic account creation for an existing workspace, you must start
restricted configuration mode and add a createUsersAutomatically setting to the Workspace-
Config.xml file. If the setting already exists you can change its value. See createUsersAutomatically
Setting (p. 49) for details.
3.3. Adding and Modifying Users

You can create and modify user accounts on the Administration/Users page. New users that are created
are typed as User objects in EKM. Note that by default, EKM creates user accounts automatically when
users successfully sign in to a workspace. See Automatic Creation of User Accounts (p. 10) for details.
Refer to the following topics:
• Adding a New User (p. 11)
• Editing a User’s Profile (p. 14)
3.3.1. Adding a New User

Any user with admin privileges can create new user accounts in a workspace.
To add a new user:
1. Go to the Administration section, then select the Users page.
2. Select (New) > User. The New User dialog box opens.
Figure 3.2: Adding a New User
3. Enter a user name. This is the user name that the user will be required to enter when they sign in to EKM.
If you have chosen to authenticate users to the operating system, use the same user name that the user
enters to sign into their operating system. If users are authenticated to an LDAP server or Windows Active
Directory, the user name may be an OS account name or some other unique identifier. Details about sign-
in authentication can be found in Configuring Login Authentication and Access Settings in the EKM Install-
ation Guide.
Note
• User names are case-sensitive in EKM, even if they are not case-sensitive in the system to
which users are being authenticated (LDAP or Windows, for example). The case used at the
time an EKM user account is created in a workspace is the same case that the user must use
when subsequently signing in to that EKM workspace.
• EKM does not allow variations of the same user name (that differ only by case) in the same
workspace. For example, if a user account with the user name jsmith already exists in a
workspace, you cannot create another account with the user name JSMITH in the same
workspace. Attempting to do so will result in an error:
Adding and Modifying Users
4. Optionally specify other details such as First name, Last name, Title, and Phone.
5. Specify the user’s email address. This address is used by EKM to send any alerts or notifications to the
user.
6. 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.
7. From the Access level drop box, select the type of license that you want to be checked out when the
user signs in to EKM: Shared, Analyst or Basic. This determines what the user can access in EKM, and
what they can do. For more information, see Licensing and Access in the Installation Guide.
8. Select Enabled to enable the user for sign-in. If you do not select this, the user will not be able to sign in
to EKM.
9. If the user needs to be granted access for a limited time only, select Temporary and enter the Expiration
date when prompted.
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.
Note
Only users with Shared access can be added to the admin group.
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 Administra-
tion/Users page.
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 User’s Profile (p. 14) for more details.
3.3.2. Editing a User’s Profile

If you are an admin user, you can edit a user’s access level, group membership, and other personal
information. The easiest way to do this is to click on the user’s name on the Administration/Users
page. 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 on the
Administration/Users page 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. 11) for details on how to fill out the dialog box.
Important
• If you change a user’s access level, the user will be forcibly signed out of EKM if he or she is cur-
rently signed in.
• You cannot edit the access level of an admin user. If you want to reduce the access level of a
user in the admin group, you will first need to remove that user from the admin group.
3.4. Forcing the Sign-out of a User

A system administrator can force the sign-out of concurrent users who are logged in to the EKM server.
When viewing the list of users on the Administration/Users page, users who are currently signed in
to EKM have a green icon next to their name.
To sign out a user who is currently signed in, select the user and then select (More) > Force sign-
out on the toolbar. The user will immediately be signed out of EKM, and the icon next to their name
will change to white .
Note
• You cannot sign out a user who is part of the admin group.
• If a user is currently connected to more than one workspace via a web browser (see Making
Simultaneous Connections), forcibly signing out the user from one workspace will disconnect
the user from the other workspace(s) as well.
3.5. Designating a Root User

The Root User is the primary administrator for an EKM workspace, and is the only user who can perform
restricted workspace configuration.
One user is designated as the default Root User for all workspaces. This is done during installation. See
Installing a New EKM Server in the Installation Guide for details.
Accessing a User’s Data
If you want to edit the designated Root User, you can do so by editing the defaultRootUser setting
in the ekm.xml file. Note that you must first stop the EKM server and then restart it after making the
change in order for the change to take effect. See Specifying General Server Settings (p. 52) for details.
Note
• There is no separate root account in a workspace’s user list. The user designated as the Root
User must have a valid OS or LDAP account, and will sign in to EKM using their normal username
and password. For more information on how EKM user names are determined, see How User
Logins Work in the Installation Guide.
• You cannot delete a user’s account if that user is currently the designated Root User.
3.6. Accessing a User’s Data

Any user with administrative privileges can access the personal data, jobs, processes, applications and
saved queries of individual users.
1. Select the Administration category, then select Users.
2. Right-click the user’s name and select More > Display > List.
The user’s personal folders will be displayed:
You can then browse through these folders to find a specific object.
Note
When using the Advanced search, you can choose to search in a specific user’s folder. For
details see Specifying Search Criteria in the User’s Guide.
3.7. Adding and Modifying Groups

You can create and modify groups on the Administration/Groups page. New groups that are created
are typed as Group objects in EKM.
Refer to the following topics:
• Adding a New Group (p. 16)
• Editing Group Membership (p. 18)
3.7.1. Adding a New Group

To add a new group:
1. In the Administration section, select the Groups page.
2. Select (New) > Group. The New Group dialog box appears, as shown below.
Adding and Modifying Groups
Figure 3.3: Adding a Group
3. Enter a name for the new group.
4. 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.
5. 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.
6. 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
Administration/Groups page.
3.7.2. Editing Group Membership

Once a group has been defined, you can modify it by clicking on it on the Administration/Groups
page. The Edit Group Membership dialog box that opens is essentially the same as the New Group
dialog box with the following differences:
1. The group name field is not editable. To change the name of an existing group, right click on the
group on the Groups page 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. 16) for details on how to fill out the New Group dialog.
Note
Only users with Shared access can be added to the admin group.
Chapter 4: Creating and Managing Workspaces
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. Signing In and Out of 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.Transferring a Workspace Between EKM Servers
4.7. Renaming Workspaces
4.8. Deleting Workspaces
4.9. Migrating Workspaces
4.1. Signing In and Out of EKM Server Administration

EKM has a special Administration interface for managing workspaces that the superuser can access
from their web browser.
To sign in to EKM Administration:
1. In the browser address bar, type the Fully Qualified Domain Name (FQDN) of the EKM server you want to
connect to, with /su appended to the end. For example:
http://ekmServer.mycompany.com:8080/ekm/su
where
ekmServer is the hostname, mycompany.com is the domain, and 8080 is the port that was
either specified or taken as default when the EKM server was set up.
The following sign-in window will appear:
Creating and Managing Workspaces
2. Choose a locale, then enter the superuser password. The default password is superuser123.
3. Click Sign In. The EKM Server Administration window opens.
Figure 4.1: EKM Server Administration Window
4. The EKM Server Administration window contains a list of Workspaces, and these actions:
• Add Workspace lets you add a new empty workspace (p. 23) or an exported workspace (p. 26).
• Delete Workspace lets you delete an existing workspace (p. 29).
• Migrate Workspace lets you migrate a workspace (p. 31) that is in configuration mode.
• Download Migration Log lets you download a log file detailing the last executed migration.
Resetting a Lost Superuser Password
5. To change the password to the EKM Server Administration site, click the Change Password command
link. See Changing the Superuser Password (p. 21) for details.
6. To clean the EKM data directory, click Clean Up Unused Files. See Cleaning Up Unused Files (p. 22) for
details.
7. When server administration is complete, click the Sign Out link at the bottom of the window to sign out
of the site and return to the EKM login window.
Once you are logged out, you can also reset a lost password (p. 21), rename a workspace (p. 28) and
delete a workspace (p. 29).
4.2. Changing the Superuser Password

You can change the superuser password from the EKM Server Administration window.
To change the superuser password:
1. Sign in to EKM Server Administration. See Signing In and Out of EKM Server Administration (p. 19) 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.
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:
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. 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
sign out. To monitor the progress of the garbage collection, click the Clean Up Unused Files button at
Creating a New, Empty Workspace
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.
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. 62) 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. 4).
To create a new workspace:
details.
2. Click Add Workspace. The New Workspace dialog box appears.
Figure 4.4: New Workspace Dialog Box
3. In the Name field, enter a name for the workspace.
4. If you want EKM to create user accounts automatically when users successfully sign in to the EKM workspace
for the first time, enable the Create new users automatically check box. See Automatic Creation of User
Accounts (p. 10) for details. Otherwise, if this option is disabled, you must create user accounts for the
workspace before users can connect to it (when they are signing in to EKM, or when switching from an-
other workspace). See Adding and Modifying Users (p. 11) for details.
You can change this setting later by editing the createUsersAutomatically setting in the
WorkspaceConfig.xml file. See Configuration Settings in WorkspaceConfig.xml (p. 42) for details.
5. Do not check the Import an exported workspace? box.
6. Click OK. A Progress dialog box opens to report the status.
Once the workspace has been created, the Add Workspace Completed dialog box appears:
7. 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 fol-
lowing dialog:
Transferring a Workspace Between EKM Servers
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. 29) for details.
4.6. 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 your EKM server to a new version, and you want
to transfer 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.
Note
• The source and destination EKM servers must be running the same release of EKM. For example,
if you exported a workspace in EKM 16.0, you could import that workspace into EKM 16.1 and
16.2, but you could not import that workspace into EKM R17. If the source and destination EKM
servers are different versions within the same release (for example, 16.0 and 16.2), workspaces
from the older version can be imported into the newer version, but not vice versa.
• You cannot import an exported workspace that has been converted into human-readable format.
For more information see Converting an Exported Workspace into a Human-readable
Format (p. 28).
• If a workspace contains custom object types that use the initializeMacro attribute to call
a script containing transactions, certain transactions in the script may cause the import/export
of the workspace to fail. You should disable such scripts before exporting the workspace.
In this section:
4.6.1. Exporting a Workspace
4.6.2. Importing a Workspace
4.6.3. Converting an Exported Workspace into a Human-readable Format
4.6.1. Exporting a Workspace

You can use the Export Workspace feature in EKM to easily export an entire workspace to another
EKM server. When a workspace is exported, an exact copy is made that includes users/groups, configur-
ation, data, controls, and so on. You can then import the workspace (p. 26) into another EKM server.
Note
Workspace exports can be performed by any member of the admin group.
To export a workspace:
1. Go to the Administration section, then select More > 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 server’s file system. For example, if you enter C:\ekm\v170\ekm-
server\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.
4.6.2. Importing a Workspace

A superuser can create a new workspace from a workspace that has been exported from another
EKM server provided that the source and destination servers are within the same release of EKM (see
Transferring a Workspace Between EKM Servers (p. 25) for specific rules). 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. 23)
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.
1. Export the workspace from the source EKM server using the Export Workspace action. For details see
Exporting a Workspace (p. 25).
2. Sign in to the Administration interface of the destination EKM server as superuser (see Signing In and
Out of EKM Server Administration (p. 19)).
3. In the EKM Server Administration window, click Add Workspace to create a new workspace. This opens
the New Workspace dialog box.
Transferring a Workspace Between EKM Servers
a. Type a name for the workspace.
b. If you want EKM to create user accounts for new users automatically, enable the Create new users
automatically check box. See Automatic Creation of User Accounts (p. 10) for details. Otherwise, if
this option is disabled, you must create user accounts for new users before they can connect to the
workspace (when they are signing in to EKM, or when switching from another workspace). See Adding
and Modifying Users (p. 11) for details.
You can change this setting later by editing the createUsersAutomatically setting in
the WorkspaceConfig.xml file. See Configuration Settings in WorkspaceConfig.xml (p. 42)
for details.
c. Check the Import an exported workspace? box.
d. Type the path to the folder on the destination EKM server that contains the exported workspace.
e. 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. Go to each application definition in the new workspace and update the application's path to point
to the correct application executable.
b. Update the default remote file servers (Audit Logs, EKM Root Directory) to valid paths for the target
EKM server.
4.6.3. Converting an Exported Workspace into a Human-readable Format

When you export a workspace, the data is exported in a machine-readable format, which is sufficient
for importing the workspace into another server later on. If you want to get a snapshot of the data in
the EKM repository, you can use a provided utility script to convert the machine-readable data into a
human-readable format.
The script for converting exported data, ekmExportConverter.py, is located in the

EKM_ROOT170/utils/bin folder (for example, /server/share/ekm/v170/utils/bin). The
script is accompanied by a README.txt file that provides detailed information on how to execute the
script and view the converted data.
Note
• The ekmExportConverter.py script is designed to run on Linux operating systems only.
• The original exported workspace does not remain intact during conversion, and once converted,
cannot be imported into another server to create a new workspace. Therefore, make sure that
you either back up the exported workspace or have access to the original workspace before
performing the conversion.
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>/repositories folder and then rename the workspace folder.
Example:
Deleting Workspaces
If the current workspace is named Analysts1 and you want to change it to Analysts2, then
rename <ekm-install>/repositories/Analysts1 to <ekm-install>/repositor-
ies/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.persist-
ence.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 can delete a workspace interactively using the EKM Server Administration interface. Once the
workspace has been deleted from the list of active workspaces in EKM, you can manually delete the
files and database tables corresponding to the workspace.
Removing a Workspace from EKM

The first step in deleting a workspace is to remove the reference to it in EKM.
1. Ensure all users have logged out of the workspace that you wish to delete.
2. Sign in to the EKM Administration Interface as superuser (see Signing In and Out of EKM Server Ad-
ministration (p. 19)). Select a workspace and click Delete Workspace. This opens the Delete Workspace
dialog box.
3. Click OK to confirm that you want to delete the selected workspace.
4. When the operation is complete, the Delete Workspace Completed dialog box appears. Make note of
the schema prefix which is required for deleting database tables. The schema prefix is also written to the
log file. Click Close.
Deleting Files and Database Tables Associated with a Removed Workspace

When you remove a workspace from EKM, various files and database tables associated with that work-
space remain on the EKM server. The instructions below demonstrate the deletion of these remaining
files for an 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 ekm 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 ekm;
b. List all the tables within this database by issuing the command:
show tables;
c. Delete all the tables whose prefix matches the schema prefix for the deleted workspace. When
deleting a workspace using the EKM Server Administration interface, the schema prefix will be
displayed and written to the log file.
The following series of commands will delete the tables that begin with the schema prefix
"R2":
drop table r2_root_binval;drop table r2_root_bundle;drop table r2_root_names;drop table r2_root_refs;
drop table r2_vn_binval;drop table r2_vn_bundle;drop table r2_vn_names;drop table r2_vn_refs;
3. When you restart the application server, the workspace will no longer be listed in any drop-down list in
EKM.
Migrating Workspaces
4.9. Migrating Workspaces

A superuser can dynamically migrate any workspace that is in restricted configuration mode (p. 35)
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. 35) for details on how to start a restricted configuration mode and
where it is used. Note that only the user who has been designated as the 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:
1. Sign in to the EKM Administration Interface as superuser (see Signing In and Out of EKM Server Ad-
ministration (p. 19)). Select a workspace that is in “configuration mode” and click Migrate Workspace.
This opens the Migrate Workspace dialog box.
Figure 4.5: 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 sign in to 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 /Administration/Con-
figuration folder.
2. 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.6: Progress Dialog Box
During Migration (p. 33)). 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.6: 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 Administra-
tion. The log will be overwritten each time you migrate a workspace configuration.
Figure 4.7: Migration Completed Dialog
Note
• Workspaces migrated from EKM version 15 or earlier will have automatic account creation turned
off by default in EKM version 17.0.
• In EKM version 17, workspaces are no longer designated as “shared” or “individual”. A user’s
privileges in a workspace are determined by the Access level assigned to the user in his or her
user profile (Shared, Analyst, or Basic). For more information, see Licensing and Access in
the Installation Guide.
When migrating a repository from version 16 or earlier, users belonging to both shared
and individual workspaces in version 16 will be granted Shared access in version 17. If
you do not want certain users to have Shared access, you must change their Access
level to Analyst in their user profile. See Editing a User’s Profile (p. 14).
• When viewing the migration log, you may see the message DEBUG - Removing Property:
fullControl if you are migrating a version 16 repository to version 17. This has no implications
for the migrated workspace, and can be ignored.
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. 51), 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 (p. 35): This type of configuration requires the workspace to be locked down.
It can only be done by the user designated as the Root User. No other user can sign in to the workspace
while the configuration is being performed.
• Unrestricted configuration (p. 40): This type of configuration can be done at any time by anyone be-
longing 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
only be performed by the user designated as the Root User for the workspace. No other user can sign
in to the workspace while the configuration is being performed.
Restricted configuration applies only to objects on the Administration/Configuration page. These are
shown below.
Restricted and Unrestricted Configuration of Workspaces
The files and folders in this location are under version control. When you begin restricted configuration,
these items are 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
restricted mode are kept in the version history and you can go back to a previous version of the config-
uration 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 (p. 37) 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. 69)
• Lifecycles: See Configuring Lifecycles for a Workspace (p. 176)
• Scripts: See Configuring a Common Scripts Library (p. 251)
• Units: See Units: Defining and Configuring Using XML (p. 247)
• Workspace Settings: See Configuring Workspace Settings (p. 41)
3. Apply configuration changes (p. 38).
4. Accept configuration changes (p. 39).
Restricted Configuration
5.1.1. Starting Restricted Configuration

Only the user designated as the Root User can perform a restricted configuration (see Designating a
Root User (p. 14)). While the workspace is under restricted configuration, no other user will be allowed
to sign 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 Administration/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 recom-
mended that you give advanced notice to all users of a workspace when configuration will start
and when it will end.
• If a user has the same user account in two workspaces, and is currently signed in to both of those
workspaces via a web browser (see Making Simultaneous Connections in the User’s Guide), placing
one workspace under restricted configuration will forcibly sign that user out of both workspaces,
even if the workspace that they currently have open is not the one being configured. However,
if proxy clients such as the File Transfer Client and EKM Studio are active in either workspace,
they will only be disconnected in the workspace that is being configured.
Note that this rule only applies to connections made through a web browser. It does not
apply to connections made through a client such as Workbench.
To begin restricted configuration:
1. In the Administration section, click the Configure button and select Begin Workspace Configuration.
Note that this feature is only available if you are the designated Root User for the current workspace. You
are asked to confirm that you want to start the configuration mode.
Figure 5.1: Begin Workspace Configuration Dialog Box
2. Click OK to start the configuration. This makes items on the Configuration page editable, and signs
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 (p. 38)
• Revert Workspace Configuration (p. 38)
• Accept Workspace Configuration (p. 39)
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. In the Administration section, click the Configure button and select 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
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. In the Administration section, click the Configure button and select Revert Workspace Configuration.
You will be asked to confirm that you want to revert the configuration.
Restricted 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 items on the Administra-
tion/Configuration page will become non-editable and other users will be allowed to sign 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, click the Configure button in the Administration section and select Accept
Workspace Configuration.
• If your changes have not affected the data model, the Accept Workspace Configuration dialog box looks
like this:
Figure 5.4: Accept Workspace Configuration
Click Accept to accept the configuration. You can optionally add a comment.
• If your changes have affected the data model, the Accept Workspace Configuration dialog box looks like
this:
Figure 5.5: Accept Workspace Configuration - Migration Required
In this case you must migrate the workspace before it can be accepted. Follow the steps below.
1. Click Cancel to close the Accept Workspace Configuration dialog box.
2. Sign out of the workspace.
3. Sign into the EKM Administration site from the EKM login screen.
4. Migrate the workspace. See Creating and Managing Workspaces (p. 19) for details.
5. Accept the workspace configuration.
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 Administration
section.
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. 134).
Configuring Workspace Settings
• 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 Applica-
tions (p. 139).
• 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. 252).
• Shared Applications. This public folder contains the following pre-defined applications and job tem-
plates:
– Start Batch Job
– Start Interactive Job
– Start CFX Job
– Start Electronics Job
– Start Fluent Job
– Start MAPDL Job
You can edit these applications and templates to suit your needs. See Modifying an EKM Applic-
ation in the EKM User’s Guide.
You can also create custom applications, job templates or process templates and save them in
the /Administration/Shared Applications folder to make them accessible to other users.
Refer to the following topics in the EKM User’s Guide for details:
– Creating a Custom Application
– Creating a Custom Job Template
– Assigning Custom Dialog Resource Files to a Process Template
• Shared Queries. This is a public folder where users can save the following:
– Search queries (see Saving a Search Query in the EKM User’s Guide)
– Catalog views (see Saving a View in the EKM User’s 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. 11).
• Groups. Users can belong to specific groups that determine the types of actions users can perform.
See Adding and Modifying Groups (p. 16).
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 config-
uring 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. 37).
2. Either download the existing WorkspaceConfig.xml file from the Administration/Configuration

page 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. 42) and
in accordance with the schema definition presented in Schema Definition (p. 42).
4. If you downloaded the file to your local system and edited it, then upload the modified file to the Admin-
istration/Configuration page and overwrite it.
5. Apply (p. 38) and accept (p. 38) 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 Con-
figuration Settings in WorkspaceConfig.xml (p. 42).
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 (p. 43)
• mimeTable (p. 44)
• typeSettings (p. 44)
• dashboard (p. 45)
• preferences (p. 45)
• downloadConfirmation (p. 48)
• scheduledTasks (p. 48)
• createUsersAutomatically (p. 49)
• designatedRootUser (p. 49)
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 configur-
ation:
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 rep-
resented as generic File types in EKM. The default MIME type of a file in EKM is application/octet-
stream, 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 ex-
tension will have a MIME type of text/plain.
Example 5.2: mimeTable Setting

<mimeTable>
<mimeEntry>
<extension>out</extension>
<contentType>text/plain</contentType>
</mimeEntry>
</mimeTable>
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. 69)
for a description of type attributes and acceptable names.
• disableDataExtraction: Used to disable data extraction when a file of this type is uploaded to
EKM. To disable data extraction, set its value to true.
Note
Even if data extraction is enabled globally in your Preferences, this attribute will
override it. See Specifying General Preferences in the EKM User’s Guide for details.
A sample listing for typeSettings is shown below. The name of a built-in type should be the non-
localized name as described in Appendix B (p. 267). 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. The hidden setting of the WorkBenchSimula-
tion type is set to true. Finally, the disableDataExtraction setting is set to true for the
CfxDefinition type, indicating that data will not be extracted from .def files when they are uploaded
to EKM.
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>
<type name="CfxDefinition">
<typeAttribute name="disableDataExtraction" value="true"/>
</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 ele-
ments:
• 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 four gadgets: My Tasks, Job Monitor, Process Monitor, and Extraction
Monitor. All of these gadgets are non-essential.
Example 5.4: dashboard Setting

<dashboard>
<gadget>
<path>/Processes/My Tasks</path>
</gadget>
<gadget>
<path>/Jobs/Job Monitor</path>
</gadget>
<gadget>
<path>/Processes/Process Monitor</path>
</gadget>
<gadget>
<path>/Data/Extraction Monitor</path>
</gadget>
</dashboard>
Note
The dashboard setting in the WorkspaceConfig.xml file is applied when new user
accounts are created. Changes to the dashboard setting will not affect existing users.
preferences Setting
The preferences setting is used to establish the default selections for preferences in the Settings
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 Settings dialog box. The default values for the
preferences setting are shown below.
Example 5.5: preferences Setting

<preferences>
<initialUri>/My Home</initialUri>
<onSignInObject>lastAccessedObject</onSignInObject
<locale>en</locale>
<r12Labels>true</r12Labels>
<unitSystem>SI</unitSystem>
<disableDataExtraction>false</disableDataExtraction>
<theme>midnightblue</theme>
<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:
• initialUrl: The location in the EKM workspace in which EKM will start.
• onSignInObject: The location that you want to be opened every time you sign in to EKM. The default
value, lastAccessedObject, opens the location that was open when you last signed out of EKM. If you
would prefer to open the same specific location every time, set the value to specificObject, then specify
the desired location in the initialUrl setting.
• locale: The language in which you want EKM to display text. Once you have logged into 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
into 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:
– 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. 74) 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 Ex-
tracted 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.
• theme: The theme that is used to display the EKM interface. Themes are defined in CSS files that are included
in the EKM installation. The default value for this setting is midnightblue. If you prefer a lighter theme,
change the value to sunrise.
• 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.
• 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 col-
lection 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 User’s 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 work-
space. 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.
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>/Data/Shared Data/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>
createUsersAutomatically Setting
The createUsersAutomatically setting specifies whether or not user accounts will be created
automatically when users successfully sign in to the workspace for the first time.
The default behavior for workspaces is as follows:
• The Default workspace that is created during the EKM installation has automatic account creation enabled.
• If the workspace is one that has been migrated from version 15 or earlier, automatic account creation is
disabled.
• For new workspaces, automatic account creation is enabled if the Create new users automatically check
box was enabled when the workspace was created.
An example of this setting is shown below.

<createUsersAutomatically>true</createUsersAutomatically>
If the setting has a value of true, any user with valid credentials for the active login module will be
able to sign in to the workspace, and EKM will create a user account for that user automatically. For
information about configuring user logins, see Configuring Login Authentication in the Installation
Guide. If the setting has a value of false, a user will only be able to sign in to the workspace if an
administrator has created a user account for that user. See Adding and Modifying Users (p. 11) for details.
designatedRootUser Setting
The Root User is the primary administrator for an EKM workspace, and the only user who can make re-
stricted configuration changes in that workspace. By default, the Root User for a workspace is the user
specified in the <defaultRootUser> setting in the ekm.xml file (see Specifying the Default Root
User (<defaultRootUser>) (p. 53)).
If you want to specify a different Root User for a specific workspace, you must manually add a desig-
natedRootUser setting to that workspace’s WorkspaceConfig.xml file, and for its value specify
the EKM user name of the user you want to designate as the Root User for that workspace. This effectively
overrides the <defaultRootUser> setting.
An example of this setting is shown in bold below.

<createUsersAutomatically>true</createUsersAutomatically>
<designatedRootUser>jsmith</designatedRootUser>
Note
• This setting must be added after the <createUsersAutomatically> setting.
• EKM user names are case-sensitive. See How User Logins Work in the EKM Installation Guide to
see how EKM user names are defined.
• Once you have added this setting and designated a Root User for the workspace, you can apply
and/or accept the configuration change. If you choose to apply the configuration (p. 38), you
will lose your root privileges at that time. You must then sign out of the workspace and let the
new designatedRootUser sign in so that he or she can accept the workspace configuration
changes.
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. Specifying 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. 51) 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 Specifying General Server
Settings (p. 52) and Optional Settings (p. 66).
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>
Configuring EKM Server Settings
6.2. Specifying 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 (p. 52)
• defaultDomain (p. 53)
• defaultRootUser (p. 53)
• retentionPolicy (p. 53)
• modules (p. 54)
• localprocess (p. 54)
• remoteProcess (p. 55)
• cache (p. 62)
• scheduledTasks (p. 62)
• pluginRegistry (p. 64)
• superUser (p. 65)
• cluster (p. 65)
• memoryLimits (p. 66)
• email (p. 66)
• customResourcesPath (p. 66)
• fileTransferService (p. 66)
Specifying the URL of the EKM Server (<ekmUrl>)

The value of ekmUrl must be set to the URL of the EKM server. If a front-end web server is used, the
value should be set 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 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 user’s server data and connects it to EKM. See The Data Manage-
ment Process (p. 130) for details. If this setting is incorrectly specified the data management process will
fail to launch.
Figure 6.2: Sample Value for ekmUrl

<ekmUrl>http://webserver.yourdomain.com</ekmUrl>
Specifying General Server Settings
Specifying the Default Workspace (<defaultDomain>)

When the EKM server starts up, it will automatically create the default workspace specified in this setting
if one does not exist. This is the workspace that all users will be signed in to by default when they sign
in to EKM.
Figure 6.3: Default Value for defaultDomain Setting

<defaultDomain>Default</defaultDomain>
Note
If you are changing the default workspace to another existing workspace, ensure that user
accounts exist for users in that workspace (see Adding and Modifying Users (p. 11)), or that
automatic account creation is enabled for that workspace (see Automatic Creation of User
Accounts (p. 10)). Otherwise, users will not be able to sign in to it. In this case EKM will then
attempt to sign users in to another workspace in which automatic account creation is enabled,
or in which user accounts exist for them.
Specifying the Default Root User (<defaultRootUser>)

When the EKM server starts up, it will automatically create a user account for the user that was specified
as the Designated Root User during installation. This user will have Shared access. The Root User is
the primary administrator for all workspaces defined in EKM, and the only user who can make restricted
configuration changes.
You can change the default Root User by specifying the EKM user name of another user as defined by
their OS or LDAP account. This is case-sensitive. See How User Logins Work in the EKM Installation Guide
to see how EKM user names are defined.
Figure 6.4: defaultRootUser Setting

<defaultRootUser>ekmadmin</defaultRootUser>
Note
• When changing the Root User to an existing EKM user who currently has Analyst or Basic
access, that user's access level will be automatically changed to Shared in his or her profile.
• You can override the defaultRootUser setting for a specific workspace by editing the
WorkspaceConfig.xml file. For details see designatedRootUser Setting (p. 49).
Once the Root User has been changed, and the server has been restarted, the previous EKM user will
no longer be treated as the Root User, but their account will still exist.
Specifying the Object Retention Policy (<retentionPolicy>)

EKM uses a bundled content management system for managing files and metadata. The repository
setting in ekm.xml can be used to configure the retentionPolicy setting.
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.5: Default Values for retentionPolicy Setting (p. 54) 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.5: Default Values for retentionPolicy Setting

<repository>
<retentionPolicy>
<defaultExpiration>365</defaultExpiration>
<customRetentionSetting>
<objectType>AuditLog</objectType>
<expiration>30</expiration>
</customRetentionSetting>
<objectType>File</objectType>
<objectType>Folder</objectType>
<objectType>Job</objectType>
<objectType>DataExtractionMonitor</objectType>
</retentionPolicy>
</repository>
Configuring Modules (<modules>)

The modules setting configures modules that provide groupings of functionality. The default value
for this setting is shown below.
Figure 6.6: 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.
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.7: Default Values for localProcess Setting

<localProcess>
<dataExtractionTimeout>3600</dataExtractionTimeout>
<dataExtractionThreads>1</dataExtractionThreads>
<maxDataExtractionMemory>16</maxDataExtractionMemory>
</localProcess>
dataExtractionTimeout
Specifies the timeout value (in seconds) for the predefined set of metadata and report extraction applica-
tions. 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.
maxDataExtractionMemory
The maximum amount of memory (in GBs) that can be used for data extraction. This is the cumulative
memory of all extraction threads. The value should be based on the available RAM as well as the memory
required by EKM and other processes on the server. For example, for a 64GB server, this value might be
set to 48 to keep the server functioning optimally when data extraction is taking place.
If the memory required to extract data from a file exceeds the maxDataExtractionMemory
limit, data will not be extracted from that file. For Fluent (.cas) and CFX (.def, .res) files, which
support partial data extraction, metadata may be extracted from the file but not a report or image
if there is insufficient memory. The same applies to the component files of a Workbench archive
(.wbpz) file.
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.8: Default Values for remoteProcess Setting

<remoteProcess>
<jobSourceRootPath>{$EKM_TEMP}/jobRoot</jobSourceRootPath>
<clusterVisibleDirectories>
</clusterVisibleDirectories>
<rsmWindowsDomain>MYDOMAIN</rsmWindowsDomain>
<rsmLauncherURL>http://localhost:10017/LauncherService</rsmLauncherURL>
<jobOutputFilename>ekm_job.out</jobOutputFilename>
<dataManagementJreLocation>%AWP_ROOT170%\EKM\programs\jre1.8.0_40</dataManagementJreLocation>
<dataManagementJarLocation>%AWP_ROOT170%\EKM\bin\ekm-servo-17.0.jar</dataManagementJarLocation>


<workbenchServerPortRange>40000-40100</workbenchServerPortRange>



<solverVersions default="170">
<version>
<value>170</value>
<label>17.0</label>
</version>
</solverVersions>

<emagInstallationDirectory>/path/to/AnsysEM</emagInstallationDirectory>
</remoteProcess>
jobSourceRootPath
The path to the directory where EKM will stage the data files for batch jobs submitted to RSM, if users do
not choose a working directory when setting up jobs. This directory is specified in the EKM job data dir-
ectory field during installation, and is resolved on the RSM Manager machine, so it must be accessible
from that machine. See The Creation and Structure of Job Directories (p. 130) for details.
In Windows:
If EKM and RSM are running on Windows and integrating with a Windows HPC cluster, this path
must be a UNC path to a shared directory (for example, \\RSMMANAGER\HPCTemp). All of the
nodes and the submit host (the machine submitting the job) should be able to access this share.
In this case, EKM will create a workspace directory under the job data directory, and username
directories will be created for each user under that directory (for example, \\RSMMAN-
AGER\HPCTemp\Default\jsmith).
In Linux:
If EKM and RSM are running on Linux and integrating with a Linux cluster, this can be an absolute
path to a shared directory, or a path that is relative to users’ home directories. The use of home
directories (via a relative path) is strongly recommended. A user’s home directory is determined by
the RSM Manager, and the user has read/write permission on this directory and any subdirectories
that it contains. For example, specifying the value jobRoot would translate into
/path/to/user/home/jobRoot for each user.
In either Windows or Linux, if you specify an absolute path to a shared job data directory, you must
make considerations regarding access and security, as described in Access and Permission Require-
ments of the Job Data Directory (p. 131).
Important
• You must create the job data directory specified in the jobSourceRootPath setting before
job submission begins. EKM will not create it for you.
• If you are using a shared directory in either Windows or Linux, it is recommended that you
create the workspace directory up front, and ensure that all users have read/write permission
on that directory, so that username directories can be created under it. Additional steps
may also be required depending on your security requirements. For more information, see
The Creation and Structure of Job Directories (p. 130) and Access and Permission Requirements
of the Job Data Directory (p. 131).
• Advanced configurations (where EKM and RSM are running on Windows and integrating with
a Linux cluster) are not supported.
clusterVisibleDirectories
You only need to specify this setting if you are using a relative path for a Linux installation.
EKM automatically considers the path specified in the jobSourceRootPath setting to be visible,
so you do not need to specify that path in the clusterVisibleDirectories setting.
EKM assumes that it is submitting jobs to a compute cluster (either RSM-native or third-party). Use
the clusterVisibleDirectories setting to list directories that are visible to all compute
cluster nodes. This determines where the job data directory can reside, ensures that each RSM job
runs directly in its specified working directory, and prevents unnecessary file transfers to/from RSM.
In the example below, the /net/userhomes directory is a shared directory that all cluster nodes
can access. It is also the directory under which all users’ home directories are located. Specifying
this directory as a visible cluster directory means that directories such as /net/userhomes/jsmith
and /net/userhomes/mjones are also visible and valid.
<jobSourceRootPath>jobdata</jobSourceRootPath>
<clusterVisibleDirectories>
<dir>/net/userhomes</dir>
</clusterVisibleDirectories>
If EKM and RSM are integrating with a Linux cluster, you can specify an absolute or relative path.
For rules on specifying paths in Windows and Linux, see the preceding jobSourceRootPath
section.
rsmWindowsDomain (Windows only)

Use this setting when EKM is configured to use an RSM Manager running on Windows. This is the Windows
domain name that will be prepended to the user name of all EKM users when batch jobs are submitted to
RSM. All user jobs will be submitted to RSM as rsmWindowsDomain value\OS account name. For
example, if MYDOMAIN is specified as the value for rsmWindowsDomain, and a user’s OS account name
is jsmith, then jobs will be submitted to RSM as MYDOMAIN\jsmith.
Note
It is recommended that you use a NetBIOS domain name rather than a Fully Qualified
Domain Name (FQDN) for this setting.
jobTemplate
Use this optional setting to change the default RSM job template file used to run EKM jobs to a customized
one.
rsmLauncherURL
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 Launcher V17.0 service is changed. See Installing RSM for use with EKM (p. 116).
Example:
The ANSYS RSM Launcher V17.0 service’s configuration is modified to use port 10099 instead of
the default 10017. The Ans.Rsm.AppSettings.config file in the install_root\RSM\Con-
fig directory is edited as follows:
</appSettings>
<appSettings name="LauncherService">
<add key="LauncherXmlRpcEnabled" value="true" />

<add key="LauncherXmlRpcPort" value="10099" />
<add key="LauncherXmlRpcSecure" value="false" />
<add key="XmlRpcMaxConcurrentRequests" value="10" />


<add key="ProxyXmlRpcPortRange" value="50000-50100" />
<add key="ProxyTokenRegistrationTimeoutMilliseconds" value="10000" />
</appSettings>
rsmLauncherURL in ekm.xml is also modified to specify 10099 as the port in the URL:
<rsmLauncherURL>http://localhost:10099/rsm/</rsmLauncherURL>
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 host name in place of localhost.
rsmClientTimeout
Specifies how long in seconds EKM should wait for a response from the RSM XmlRpcApi service (see
the rsmLauncherURL (p. 58) setting) before giving up and reporting an error.
This setting is optional. If included, the value must be positive. A value of 0 will cause EKM to wait
for a response indefinitely. If this setting is not included, the timeout used will be 120 seconds.
Example:
<rsmClientTimeout>90</rsmClientTimeout>
jobOutputFilename
The file name that will be used by all jobs to capture batch processing output.
dataManagementJreLocation
The full path to the Java Runtime Environment (JRE) used to run the data management process. For details
see The Data Management Process (p. 130).
<dataManagementJreLocation>%AWP_ROOT170%\EKM\programs\jre1.8.0_40</dataManagementJreLocation>
By default this path is set to the full path of the JRE (JRE Home) included under the EKM folder
under the ANSYS installation root folder. In general, you should not need to change this setting.
The AWP_ROOT170 variable in the path will be resolved on the RSM Manager machine.
Example:
AWP_ROOT170 = C:\Program Files\ANSYS Inc\v170
RSM will use a JRE located at C:\Program Files\ANSYS Inc\v170\EKM\programs\jre1.8.0_40.
Note
• The dataManagementJreLocation should always be set to a valid local path on the

RSM Manager machine, as the Data Management process is launched on that machine.
• You do not need to change the path format of the dataManagementJreLocation for a
Linux installation. RSM will convert the Windows path into a Linux path automatically.
dataManagementJarLocation
The full path to the executable JAR file used to run the data management process.
<dataManagementJarLocation>%AWP_ROOT170%\EKM\bin\ekm-servo-17.0.jar</dataManagementJarLocation>
By default this path is set to the full path of the ekm-servo-17.0.jar file included under the
EKM folder under the ANSYS installation root folder. In general, you should not need to change this
setting.
The AWP_ROOT170 variable in the path will be resolved on the RSM Manager machine.
Example:
AWP_ROOT170 = C:\Program Files\ANSYS Inc\v170
RSM will use a JAR located at C:\Program Files\ANSYS Inc\v170\EKM\bin\ekm-servo-17.0.jar.
Note
• The dataManagementJarLocation should always be set to a valid local path on the

RSM Manager machine, as the Data Management process is launched on that machine.
• You do not need to change the path format of the dataManagementJreLocation and
dataManagementJarLocation for a Linux installation. RSM will convert the Windows
path into a Linux path automatically.
enginframe
Contains EnginFrame settings and interactive queue definitions. For more detailed information see Con-
figuring EKM to Work with EnginFrame in the EKM Installation Guide.
Figure 6.9: Sample Interactive Queue Definitions

<enginframe>
<serviceDefinitionFile>https://
enginframe-server-name:8443/enginframe/ekminteractive/ekminteractive.xml
</serviceDefinitionFile>
<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 /Adminis-
tration/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 (p. 138) 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. The range is defined using a
min-max format, as shown in the example below:
<workbenchServerPortRange>51215-51220</workbenchServerPortRange>
clusterMonitors
When EKM is deployed on the Cloud, configuring CycleCloud in the ekm.xml file enables EKM users to
monitor the HPC cluster. When configured correctly, a Cluster Monitor page is available in the Jobs section
in EKM, and cluster monitor graphs are displayed on the HPC tab on that page. See Cluster Monitoring in
the EKM User’s Guide for details.
<clusterMonitors>
<clusterMonitor>
<type>CycleCloud</type>
<param name="url" value="http://<cycle-cloud-server-name>/node_status"/>
<param name="credentialInfoFilePath" value="{$EKM_HOME}/conf/cycleCloudCredentials.json"/>
<param name="clusterName" value="kumo-hpc"/>
<param name="hostPrefix" value="ip-"/>
<param name="excludeNodeArrays" value="master,sgemaster,app,execute"/>
</clusterMonitor>
</clusterMonitors>
The <type> should remain set to CycleCloud.
Specify the parameters described below:
• url: The URL of the REST API endpoint that will be queried for data
• credentialInfoFilePath: The path to the .json file where encrypted credentials will be stored
• clusterName: The name of the cluster to be monitored
• hostPrefix: The prefix appended to host names
• excludeNodeArrays: A comma-separated list of node arrays that you do not want to be included
in the Cluster Monitor
solverVersions
The solver versions specified here correspond to the installed versions of ANSYS solvers that are used when
jobs are submitted using EKM’s built-in CFX, Fluent, and MAPDL job templates.
<solverVersions default="170">
<version>
<value>170</value>
<label>17.0</label>
</version>
</solverVersions>
Solver versions specified in <version> elements will appear in the Version drop-down list in the
Start Job: Specify Execution Settings dialog box when a built-in job template is used to start a
job. The default attribute determines which version will be selected by default in this list.
To add support for more solver versions, create additional <version> elements with <value>
and <label> attributes. For example, to add support for version 16.1 solvers, you would add the
following <version> element:
<version>
<value>161</value>
<label>16.1</label>
</version>
The <value> is what EKM uses to refer to the version internally, while the <label> is what is
displayed in the Version drop-down list in the Start Job: Specify Execution Settings dialog box.
Note
• Make sure that the versions specified correspond to the actual ANSYS application versions
installed on your compute servers.
• The <solverVersions> element is intended for ANSYS products only. Non-ANSYS solvers
are not supported.
• Adding support for an older solver version may limit the availability of certain features in
EKM, should a user choose to use that older solver version during a job run. For example, live
job monitoring will not be available if a solver from release 15 or earlier is used. To provide
users with maximum functionality, we recommend that you use current and recent releases
only.
emagInstallationDirectory
If users will be using the built-in Electronics job template, use this setting to specify the installation directory
of ANSYS Electronics Desktop. The value must be a shared path or the same path on all compute nodes.
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.10: 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.
Figure 6.11: 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>1</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.11: Default
Values for scheduledTasks Setting (p. 62), 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
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 file’s 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 col-
lection 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.
Important
Do not schedule the remoteSync task to run at midnight. Doing so can interfere
with the creation of the daily audit logs.
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.
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.12: 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 plugins-
deploy 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. The Superuser
has access to the EKM Administration interface, which allows workspace creation and migration.
Figure 6.13: Default Value for superUser Setting

<superUser>
<name>superuser</name>
<password>9a85a0cc0a56febcf46690a6ab1a5803</password>
</superUser>
name
The name of the user who is the designated Superuser. This setting is optional. Only a password is required
to sign in to the EKM Administration interface.
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.
For information on the EKM Administration interface, see Creating and Managing Workspaces (p. 19).
Configuring a Cluster (<cluster>)

The cluster setting is used to specify the configuration of a cluster.
Figure 6.14: Default Value for cluster Setting

<cluster>
<type>cluster</type>
<cacheConfigFile>{$EKM_HOME}/conf/clusterCache.xml</cacheConfigFile>
</cluster>
type
Must be cluster.
cacheConfigFile
Specifies the location of the configuration file for the infinispan cache, which is a cluster-wide in-memory
cache.
Specifying the Maximum Number of Search Results to Display

(<memoryLimits>)
The maxSearchResults value in the memoryLimits setting is used to limit the number of objects
that are returned by a search. This limits the amount of time and resources that are spent on search
operations. If your server has a large amount of memory available and you want to allow users to search
for more objects, you can increase the limit. The default value for this setting is shown below.
Figure 6.15: Default Value for maxSearchResults Setting

<memoryLimits>
<maxSearchResults>500</maxSearchResults>
</memoryLimits>
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.16: 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 User’s Guide for details on how to create these files.
The default path shown is a suggested location for the custom resources folder. You can either create
a folder in this location, or specify a path to a different folder on the EKM server.
Figure 6.17: 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 tempor-
arily held before being imported into EKM. The default value is the TEMP directory. In a clustered envir-
onment, the rootDir value will need to be changed on each node to a shared directory that all nodes
can access.
Figure 6.18: Default Value for fileTransferService Setting

<fileTransferService>
<rootDir>{$EKM_TEMP}</rootDir>
</fileTransferService>
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.
Optional Settings
• bootstrapper (p. 67) and initializer (p. 67)
• sessionTimeout (p. 67)
• showBetaFeatures (p. 67)
• fileBackupPath (p. 67)
• dataLink (p. 68)
• mobileConnector and mobileServer (p. 68)
• passwordChangeScript (p. 68)
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.19: Default Value for bootstrapper and initializer Settings (p. 67).
Figure 6.19: 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 deac-
tivated and the EKM license is released. The default value of this setting is 30 minutes as shown in the
example below.
Figure 6.20: 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.21: Default Value for showBetaFeatures Setting

<showBetaFeatures>false</showBetaFeatures>
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.22: 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 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 Mo-
bile (p. 149).
Configuring a Password Change Script (<passwordChangeScript>)

You can configure EKM to use a password change script that allows users to change their password
within EKM. Configuring a password change script causes a Change password option to be displayed
in the Edit Profile dialog box when a user is editing their own profile information.
To enable this functionality, set the value of the <passwordChangeScript> setting to the path of
the password change script. The username and new password will be provided to the script in two
environment variables, username and password, respectively.
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. 72). Alternatively you can create an XML file outside of EKM and then upload it into
EKM. See Defining Custom Types Using XML (p. 94) 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. 35)). Once you are done
with your modifications, you can accept the configuration (p. 39) 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 con-
sidered a structural change. See Migrating Workspaces (p. 31) 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 those in /Administra-
tion/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
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 user-defined
attribute. A custom file format definition can also specify applications for extracting images and reports
from files. See Custom File Formats (p. 105) 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. 102) 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 spe-
cifies this information in the type definition. See Custom Analysis Projects (p. 104) for more details.
• Extending a Built-In Type: Built-in types (p. 70) 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 automat-
ically 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. 110) 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. 267) 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,
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.
Suggested Steps for Defining Custom Types
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, .rstp, .rth, .rmg, .rfl)
– 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. 23)). 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 (p. 72) or XML (p. 94).
When you are ready to define a custom type, refer to one of the following methods:
• Defining Custom Types Directly in EKM (p. 72)
• Defining Custom Types Using XML (p. 94)
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. 94).
To create or modify a custom type, you must go into restricted configuration mode. Refer to Restricted
Configuration (p. 35) 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. 72). If a custom type is already defined
and you want to edit it, see Editing a Custom Type (p. 94).
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. While in restricted configuration mode (p. 35), select the /Administration/Configuration/Custom

Types folder, then select (New) > EKM Type. This opens the New Custom Type dialog box.
Defining Custom Types Directly in EKM
Figure 7.1: Defining a New Custom Type
2. This dialog box contains the following tabs for specifying various settings of the custom type:
• General: On 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. 94) 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. Do not use the label or name of any built-in type. If the type extends a built-in type, you
may want to append a suffix such as _c to the label to make it unique.
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 de-
fining 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. 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. 74) 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. 76) 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. 77) 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. 78) below for details.
• Script: On this tab you can define macros that you can reference when defining type attributes, actions
and views for a custom type. See Defining Scripts for a Custom Type (p. 87) 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 Creating Actions for a Custom Type (p. 88) below for details.
• Views: On this tab you can define custom views for the type. These will appear as additional tabs in
the view window when viewing an object of this type. See Creating Custom Views for a Type (p. 92)
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: Custom Type - Properties (p. 75).
Figure 7.2: 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.
• Multi-line value: For String properties, enables you to specify two or more lines of text as the value
of the string.
• 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. 95) 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
order are displayed first. If unspecified, the default value is 0, which will display the property alphabet-
ically 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. 95) 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: Custom
Type - Children (p. 77).
Figure 7.3: 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: Custom Type - Mix-
ins (p. 78).
Figure 7.4: 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: 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: Custom Type - Type Attributes (p. 79) 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.
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 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. 88) 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 Script 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.
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.
imageName
This attribute can be used to specify the format of the image file that is extracted when an image extraction
application is specified. For example, to extract an image in CAX format, you would specify file.cax as
the value of this attribute. Note that a suitable extractor must be specified for the imageApplication
attribute.
Note that 3D images are automatically extracted from several built-in CAE file types by default. For
certain Fluent, CFX and Mechanical APDL file types, 3D images are extracted and displayed in an
interactive 3D viewer on the Image tab when viewing the CAE file in EKM. Specifying values for the
imageName and imageApplication attributes will override this default. For more information
about the default image extraction, see Automatic Extraction of Images on Upload in the EKM User’s
Guide.
disableDataExtraction
This attribute can either be true or false. It is used to specify whether or not data is extracted from a
file of this type when it is uploaded to EKM, and whether or not data can be manually extracted from it
after it has been uploaded.
Note
If you are enabling data extraction for a type, you must also make sure that the global
Disable data extraction setting is disabled in your Preferences. See Specifying General
Preferences in the EKM User’s Guide for details.
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 newly-
created object and must be defined on the Script tab. See Example: Executing a Macro When an Object
Is Created (p. 88) 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 VCollab’s 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.
For example, if the imageName attribute is set to file.cax, you could specify extractCaxImage
as the value of the imageApplication attribute to use the built-in CAX extractor application,
extractCaxImage.app.xml, to extract CAX files. For more information about configuring EKM
to use VCollab, see Using VCollab for 3D Visualization in EKM (p. 255).
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.
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.
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. 107) for details. If this value is empty, the built-in
extractor will be utilized if defined for that type.
typeValidatorClass
This attribute can be used to specify a Java class used for determining a file’s type. This is used for auto-
matic type assignments during uploads.
The custom type validator class requires the com.ansys.ingress.core.fs.FileType

Validator interface in the ekm-core-17.0.jar file for compilation. After compilation the
*.jar file containing the custom type validator class should be placed in the EKM_Home/plugins-
deploy folder. EKM will load the type validator class from this *.jar file when the server is restar-
ted.
showContentViewAsDefault
If set to true, the content view of the CAE file will be the default view in the interface.
allowJobExecution
If set to true, an Execute menu will be available for the CAE file, enabling users to execute batch and in-
teractive jobs directly from the file.
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. 108) for information on
how to build an application for extracting the report.
customStatusFlagsMacro
Use this attribute to specify the name of a macro that will display custom status flags and icons when an
object of this type is displayed or queried in the list view.
In Python, the macro should use def testStatus(model):, as shown in the example below:
def testStatus(model):
statuses = [["testStatus", "/custom/testStatusFlag/status.gif"]]
return statuses
The status flag is a list with two values: a key and an icon. In the example above, if the key test-
Status is defined in the custom.properties file, a localized tooltip will be displayed. Otherwise,
the key will appear as the tooltip.
In BeanShell, the macro should use List testStatus(model), as shown in the example below:
import java.util.List;
import java.util.ArrayList;
List testStatus(model) {
List statuses = new ArrayList();
List status = new ArrayList();
status.add("testStatus");
status.add("/custom/testStatusFlag/status.gif");
statuses.add(status);
return statuses;
}
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
WorkspaceConfig.xml file in /Administration/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, /Administration/Servers/Master/EKM
Server). Refer to Extracting Metadata from Custom File Formats (p. 107) for more information on de-
fining 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:\EKM\extract-additional-metadata.py</param>
4. While the workspace is in restricted configuration mode, upload the external application files to the /Ad-
ministration/Servers/Master/EKM Server folder.
5. Upload NewCustomType.type and mix1.type files to the /Administration/Configura-

tion/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, sign out of EKM and sign into the EKM Administration
site. Once migration is complete, sign back into 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 clicking on the Fluent case
file.
9. Display the added custom metadata for the report by clicking the Details tab.
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>[email protected]</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>17.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)
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:\EKM\extract-additional-metadata.py</param>
<nativeOptions />
</application>
</ekmApplication:applications>
File Listing for customReportApp.app.xml

<application>
<key>customReportApp</key>
<param>C:\EKM\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 />
</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 Scripts for a Custom Type

The Script tab enables you to input a script using either Python or BeanShell. Macro names specified
in the script can be referenced when defining type attributes (p. 78), actions (p. 88) or views (p. 92)
for the object type.
Figure 7.6: Edit Custom Type - Script
To define a script for a type:
1. On the Script tab of the Custom Type dialog box, select the Script Language that you want to use for
the script that will be associated with the action, view, or type attribute.
2. Enter or paste the script into the Script text box.
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 exportCon-
trolled 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. 78) 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. 78) for more details.
initObject(model) {
ekm.startTransaction();
model.setProperty("description", "Set from script during initialization");
ekm.commitTransaction();
}
7.3.1.6. Creating Actions for a Custom Type

The Actions tab enables you to define actions for a custom type, and remove selected built-in actions
from it. 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. Built-in actions that you remove will not be available
on the context menu and toolbar. When adding an action, you can also define an icon to represent the
action which will be visible on the toolbar and in menu items.
Figure 7.7: Custom Type - Actions
Prior to defining an action you will need to specify a script (p. 87) on the Script tab that contains the
macro to be executed when the action is performed. You will reference the macro name when defining
the action.
To create an action for a custom type:
1. On the Actions tab of the Custom Type dialog box, click the Add Action button. A new row will be added
for each new action that you add.
2. 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. 99). 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.
3. To display an action when multiple objects of this type are selected, enable the Show on multi-selection
check box for that action. Otherwise, the action will only be displayed when a single object is selected.
If you enable this option, make sure that the corresponding macro script handles single and multiple
objects, as shown in the following sample script:
# Example macros for custom actions
# 'Show on multi-selection' disabled, custom action menu will be displayed for a single object selection only.
def appendDescription(object, dialog):
import time
description = object.getProperty("description")
ekm.startTransaction()
time = time.asctime(time.localtime(time.time()))
object.setProperty("description", description+", added at: "+time)
ekm.commitTransaction()
# 'Show on multi-selection' enabled, custom action will be displayed when multiple objects of the same type ar
# Custom action menu will also be displayed for a single object selection.
def setDescription(objects, dialog):
import time
try:
# pythonic approach is to assume an iterable, then fail gracefully if it does not work on the given o
# Duck-typing avoids tests using type() or isinstance()
# iterate assuming list for multiple objects
for object in objects :
object.setProperty("description", description+", added at: "+time + " on multiple objects")
except TypeError:
# not a list of objects, then it must be a single object
object = objects
object.setProperty("description", description+", added at: "+time + " on single object")
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.
3. Begin workspace configuration.
4. Upload the Project.type.xml file that is provided in the examples folder in EKM_HOME/ex-
amples/conf/customTypes to the Administration/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.
6. In the Edit Custom Type dialog box, select the Actions tab.
7. Use Add Action to add two action rows.
8. In the Icon column, enter /custom/icons/tips.gif for the first row and /custom/icons/an-
sysIconSmall.gif for the second row.
9. Click OK.
10. Apply and accept the workspace configuration.
11. In the repository, create a new custom folder of type Project and give it a name.
12. 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.
Localizing Custom Action Labels

You can configure EKM to display custom action labels in the language that is selected for the EKM in-
terface.
Guide for details.
2. On the EKM server, go to EKM_HOME/bundles and open the folder that corresponds to the chosen
locale (de = German, en = English, fr = French, ja = Japanese). Open the custom.properties file
in a text editor. If such a file does not exist, create a text file named custom with the extension proper-
ties.
3. In a text editor, specify the following entry in the custom.properties file:
actionName.menu=localized text
where actionName is the name of the action in the custom type definition (without spaces), and
localized text is the desired action label text.
For example, if you defined a custom type with an action named Set Description, and wanted it
to appear in German when the German locale is selected, you would enter the following in the
EKM_HOME/bundles/de/custom.properties file:
SetDescription.menu=Beschreibung Definieren
4. Save the custom.properties file, and then restart the EKM server.
Removing Built-in Actions from a Custom Types

When defining a custom type, the Actions tab displays a list of built-in actions that are available for
that type. If you do not want a particular action to be included on an object’s context menu or toolbar,
simply enable its check box to remove it:
The available built-in actions will vary depending on the object type:
• For containers and folders: Delete, Edit, New, Download, Upload, More
• For files: Delete, Edit, New, Download, More
• For all other types: Delete, Edit, New, More
7.3.1.7. Creating Custom Views for a Type

When defining an object type, you can create custom views for the object. These views will be displayed
as custom tabs in the view window when you open an object of the specified type.
Views can contain object properties, images, links to other EKM objects, or other components.
There are three aspects to defining a custom view:
• Defining the interface in an XHTML file
• Defining a macro that references the XHTML file
• Adding a view that references the macro
Step 1: Define the Interface

To define the components of the custom view, such as images or object links, you can use JSF, RichFaces,
Tomahawk, HTML, JavaScript, or CSS. For information about these technologies, the structure of XHTML
files, and defining interface components, refer to Defining a Custom User Interface (p. 196).
Step 2: Define a Macro

Once you have defined the interface in an XHTML file, you must specify a macro (p. 87) that will be
used to define the functionality of the custom view, and initialize it.
This macro should specify:
• The name of the XHTML file that defines the content of the custom view
• The variables used to initialize input and output interface components, and store inputs specified by the
user in the input components
Variables can be accessed by the macro to retrieve user inputs and act upon them.
For an example of how a macro is defined, see Example: Creating a Custom Interface for Fluent Batch
Jobs (p. 207).
Step 3: Add a View

To define a custom view for an object type:
1. In the Custom Type dialog box, select the Views tab, then click Add View. A new row will be added for
each new view that you add.
Figure 7.8: Custom Type - Views
2. Specify a Name for the view. When you open an object of this type, this will be the label displayed on the
view’s tab.
3. Specify the name of the Init Macro that you defined on the Script tab which references the XHTML file.
4. If you want a custom view to be the default view when an object of this type is opened, enable the Default
radio button in that view’s row.
7.3.2. Editing a Custom Type

To be able to edit a custom type, you must be in restricted configuration mode (p. 35).
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. 72) for details on how to edit the properties (p. 74), children (p. 76),
mixins (p. 77), type attributes (p. 78), script (p. 87), actions (p. 88) or views (p. 92) 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. 72)), with the added flexibility of custom-
izing 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. 94).
• 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 Pro-
ject.type.xml.
• When the XML definition is ready, you can upload it to the /Administration/Configuration/Cus-
tom 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.9: 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"/>
Defining Custom Types Using XML
<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>
The file indicates that a custom type file consists of a root element called types that can have one
child element that can be 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 attrib-
utes as sub-elements. Type attributes are used to specify type-specific attributes such as ap-
plications 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,
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 ex-
ample 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
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: /Data/Shared Data/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 the 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 /Administration/Configuration/Units.xml
file (for example, length, volume, and so on) See Units: Defining and Configuring Using XML (p. 247)
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 /Administration/Configuration/Units.xml file for the quantity
specified above. This constraint should only be used if the quantity constraint has been used. For ex-
ample, 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
property to always be viewed in the specified unit for all users. See Units: Defining and Configuring Using
XML (p. 247) 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.
– rows. Can be used to accept multi-line values for a String type. If the specified number of rows is
greater than 1, a text area with the specified number of rows is rendered rather than a single-line text
box. For example, specifying a value of 5 permits the input of 5 lines of text in a text box.
Examples - Property Definitions

This section contains five examples of property definitions in EKM.
• version (p. 98)
• dimension (p. 99)
• revisionStatus (p. 99)
• physicalModels (p. 99)
• inputFile (p. 99)
Example 7.1: version Property (p. 98) 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. 99) 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. 99) 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>
Example 7.4: physicalModels Property (p. 99) defines a property named physicalModels of type
String that will appear in the user interface as Physical Models. The property value will be automat-
ically 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. 99) 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. 100) 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 Project’s description. When the Set De-
scription 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-descrip-
tion 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>
<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);
}
# 'Show on multi-selection' enabled, custom action will be displayed when multiple objects of the same type are se
# Custom action menu will also be displayed for a single object selection.
def setDescriptionOnObjects(object, dialog) {
import time
try:
# pythonic approach is to assume an iterable, then fail gracefully if it does not work on the given ob
# Duck-typing avoids tests using type() or isinstance()
# iterate assuming list for multiple objects
for object in objects :
object.setProperty("description", description+", added at: "+time + " on multiple objects")
except TypeError:
# not a list of objects, then it must be a single object
object = objects
object.setProperty("description", description+", added at: "+time + " on single object")
}
</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" />
<action name="Custom Actions/Set Description On Objects" icon="/custom/icons/ansysIconSmall.gif"
macro="setDescriptionOnObjects " permissions="modify" multiSelectEnabled="true" />
</actions></type>
As shown in the code in Example 7.6: Custom Actions (p. 100), 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
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 re-
quires 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 setDescription-
Dialog 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.
• multiSelectEnabled: To display an action when multiple objects of this type are selected, set this at-
tribute to true. Otherwise, if set to false, the action will only be displayed when a single object is selected.
If you enable this option, make sure that the corresponding macro script handles single and multiple objects,
as shown in the sample script.
7.5. Custom Type Examples

The following sections contain examples of custom types that you can define in EKM. These include
custom folder structures (p. 102), analysis projects (p. 104), file formats (p. 105), and extensions to built-
in types (p. 110).
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.
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 further-
more, you want users to enter some required attributes when they start a new project.
Custom Type Examples
The first step in the process is to define a new type named ProjectContainer (Example 7.7: Defining a
Project Container Type (p. 103)). 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 cannot 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. 103) 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"
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 inform-
ation 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:
• 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 attrib-
utes can be specified.
• executionWorkflow: Specifies the full path of the process template that will be executed when the
analysis project is updated. The process should not have any required variables.
• executionWorkflowVar: Specifies a reference variable defined in the process template that will
be initialized with the instance of the analysis project that starts the process. This is used to reference
the analysis project in the process.
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 User’s 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.
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. 106), the new type is named AcmeSimulationFile and is
given the label Acme Simulation File that will appear in the user interface. If you just need to extract
metadata from the file, then you can extend the new custom file format from the File type. However,
if you want to extract image or simulation details from the file (for a Simulation Details Report), then
you will need to extend it from the CaeModelFile type. This allows the Simulation Details Report action
menu to be visible in the user interface for this file.
This custom data type defines three properties that are automatically extracted by the metadata extraction
application: version, iterations, and physicalModels. It also defines some type attributes.
As previously explained, type attributes are used to specify settings that apply to all instances of that
type. Type attributes require a name and a value to be specified. The valid options for name depend
on the base type that you are extending. See Defining Type Attributes for a Custom Type (p. 78) 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 AcmeSimula-
tionFile 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.10: ModelAttribute mixin Example (p. 106)). This mixin defines two user-
defined properties: revisionStatus and reviewedBy. Because the AcmeSimulationFile type
definition includes this mixin, it will also include these properties. Therefore, when a file of this type
is uploaded, a user will be asked to enter values for these properties.
Figure 7.10: ModelAttribute mixin Example

<mixin name="ModelAttributes" version="1.0.0">
<properties>
<property name="revisionStatus" label="Revision Status" type="String" required="true">
<enumeration>Draft</enumeration>
<enumeration>Released</enumeration>
<enumeration>Obsolete</enumeration>
</property>
<property name="reviewedBy" label="Reviewed By" type="String" required="true"
multivalued="true"/>
</properties>
</mixin>
7.5.3.1. Extracting Metadata from Custom File Formats

The application for extracting metadata from custom file formats is an external program that is executed
by EKM whenever a file of the associated format is uploaded. It can be written in any language and
must fulfill the following requirements:
• accept the file name as a command line parameter
• read the input file from the current working directory
• write the metadata in a file named ekm-meta-data.xml to the current working directory
• support only metadata files that adhere to the format specified in the meta-data.xsd schema file
The schema definition for metadata files is simple and the code listing is shown in Figure 7.11: meta-
data.xsd Schema Definition Listing (p. 107). The complete listing is included in the EKM_HOME/schema
folder.
Figure 7.11: 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.
The value is the extracted value of that property. Multi-valued properties can be specified in a comma-
separated manner.
Figure 7.12: Sample Metadata File for Custom AcmeSimulationFile Type (p. 108) 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.12: 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.13: Listing of re-
port.xsd Schema Definition (p. 108). The complete listing is included in the EKM_HOME/schema folder.
Figure 7.13: 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"
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.13: Listing of report.xsd Schema Definition (p. 108) 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 in-
cluded 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.14: Report Image Element

<image name="Plot Name' src="reportFiles/plot.gif"/>
The table element can have any number of column and row child elements. The format of the table
can be controlled by showBorder and showHeaders attributes. The column element has a name
attribute that is shown in the column header. The row element has a number of child elements named
value. Each value element specifies the value for a particular row and column. The number of value
elements must be the same as the number of columns in the table.
Figure 7.15: Sample Report File for AcmeSimulationFile Type (p. 110) 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.15: 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. 110) 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.10: Mod-
elAttribute mixin Example (p. 106)). 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 /Administration/Configuration/Custom Types. You can then use the type-
Settings setting to set or modify the built-in or custom type by editing the WorkspaceConfig.xml
file in the /Administration/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 action.
See Extracting Data On Demand in the EKM User’s Guide for details.
Chapter 8: Integrating EKM with Remote Solve Manager (RSM)
In order to successfully run and manage jobs in EKM, you must ensure that RSM is installed and set up
properly, and that EKM is configured to work with RSM.
Important
When setting up RSM for use with EKM, it is imperative that you follow the instructions here
(in the EKM Administration Guide) and not those in the Remote Solve Manager’s User’s Guide.
Topics in this chapter include:

8.1. Important Changes for R16 Users
8.2. Steps for Setting Up Batch Job Submission
8.3. EKM and RSM Platform Support
8.4. Installing RSM for use with EKM
8.5. Configuring RSM for use with EKM and Third-Party Clusters
8.6. EKM and RSM Job Directories
8.1. Important Changes for R16 Users

The configuration of RSM when integrating with EKM has changed considerably in R17:
• For information about supported operating system scenarios, see Supported Platforms (p. 116).
• You cannot use RSM to run jobs on machines other than the RSM Manager machine. To be able to run jobs
on other machines, you must use a commercial cluster such as LSF or Microsoft HPC.
• The Compute Server service (Ans.Rsm.SHHost.exe) and RSM-RPC Server (Ans.Rsm.XmlRpcServer) are no
longer used. Only the RSM Job Manager service (Ans.Rsm.JMHost.exe) is required. For details see Starting
RSM Services on Windows (p. 126) or Starting RSM Services on Linux (p. 128).
• You cannot use the RSM Admin interface to edit RSM settings, define queues or compute hosts, create ac-
counts, run test jobs, and so on. Settings in the RSM Admin interface apply only when jobs are submitted
directly to RSM from clients other than EKM (such as Workbench and Mechanical).
• All configuration is done through XML configuration files instead of the RSM Admin interface:
– Queues are defined through an .rsmq file
– Cluster configurations are defined through an .rsmcc file
• When integrating with third-party batch systems such as LSF and SGE, RSM Manager should always be installed
on a cluster submission host.
• When using RSM without the involvement of a commercial batch-queuing system:
– All jobs must run on localhost (the machine where RSM Manager is running)
Integrating EKM with Remote Solve Manager (RSM)
– Jobs will queue only when all of the localhost machine's resources are being used by other jobs
• When used by EKM, accounts/passwords are not cached by the RSM Job Manager. Since accounts are not
managed by RSM, the concept of alternate accounts no longer applies when using EKM with RSM.
• The Settings dialog box in EKM no longer has an RSM Accounts tab. Now, EKM passes your EKM credentials
to RSM. If necessary, you can override these credentials in your preferences. See Specifying Job Management
Preferences in the EKM User’s Guide.
8.2. Steps for Setting Up Batch Job Submission

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 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.
In order to successfully run batch jobs in EKM, you must install and configure RSM, and configure EKM
to work with RSM. An overview of the required steps is provided below.
Required Steps
1. Install ANSYS Workbench, RSM, and the ANSYS applications that you want to run.
Note
• RSM is automatically installed with Workbench. For information on installing RSM, refer to
Distribution of Services (p. 113) and Installing RSM for use with EKM (p. 116).
• ANSYS applications (Fluent, CFX, MAPDL, and so on) should be installed on the machine(s)
where you will be running jobs. They should be installed in a way that they can be accessed
by the RSM machine and any other cluster machines being used.
2. Configure RSM to work with EKM and (if applicable) a third-party cluster. The easiest way to do this is to
run a script that automates the process. For an overview see Configuring RSM for use with EKM and Third-
Party Clusters (p. 117). For instructions see Configuring RSM Automatically (p. 118).
If do not wish to use the automated script, you will need to perform each configuration step indi-
vidually, as described in Configuring RSM Manually (p. 119).
3. If RSM is not installed on the same machine as EKM, change the value of the rsmLauncherURL setting
in ekm.xml from localhost to the hostname of the server where the ANSYS RSM Launcher service is
running. See Specifying Remote Process Policies (<remoteProcess>) (p. 55) for details.
4. If necessary, modify RSM configuration files to complete the integration of EKM with RSM and third-party
batch systems. See Modifying RSM Configuration Files (p. 124).
5. Ensure that EKM and RSM job directories are correctly defined. See EKM and RSM Job Directories (p. 129).
EKM and RSM Platform Support
6. In EKM, synchronize EKM job submission queues with those defined in RSM. See Synchronizing Job Sub-
mission Queues (p. 137).
7. For each job submission queue in EKM, load or create application definitions that determine the applications
to be run. See Defining Job Submission Queue Settings (p. 138) and Defining External Applications (p. 139).
Note
If users will be submitting Electronics jobs, you must specify the installation directory of
Electronics Desktop in the ekm.xml configuration file. See the emagInstallationDir-
ectory setting in Specifying Remote Process Policies (<remoteProcess>) (p. 55).
Optional Steps
• If the RSM Manager is running on Windows, you will have specified the RSM Windows domain name during
the EKM server installation. If for some reason you need to edit this value after installation, you can do so
in the ekm.xml file by editing the rsmWindowsDomain setting. For details see Specifying Remote Process
Policies (<remoteProcess>) (p. 55).
• By default, all users will have access to all RSM queues. If desired, you can restrict certain users from submitting
jobs to a queue by setting permissions on the queue. (See Editing Permissions in the EKM User’s Guide.)
8.3. EKM and RSM Platform Support

Using EKM with RSM involves the configuration of the following services:
• EKM Server
• RSM Manager
• (optional) Third-Party Batch System
When using EKM with RSM, there are only certain platform combinations and distribution of services
that are supported.
In this section:
8.3.1. Distribution of Services
8.3.2. Supported Platforms
8.3.1. Distribution of Services

The EKM Server and RSM Manager services may run on one machine, or they may each run on their
own machine on the same network (LAN).
As described in Types of Queues (p. 136), integration with RSM is based on the creation of EKM queues
that map to RSM queues.
EKM and RSM on the Same Machine

If the EKM Server and RSM Manager will run on the same machine, follow these configuration steps:
1. Install an EKM Server and RSM Manager on Server 1:
2. On Server 1, generate the required RSM configuration files, and modify them as necessary to complete
the RSM configuration. See Configuring RSM for use with EKM and Third-Party Clusters (p. 117).
Note
If you are using RSM as the job scheduler, all jobs will run directly on the RSM machine.
If a job requests more cores than are available, it will remain queued until the requested
cores become available. If a job requests more cores than exist on the RSM machine, it
will be rejected.
3. In EKM, synchronize queues with RSM (see Synchronizing Job Submission Queues).
EKM and RSM on Different Machines

If the EKM Server and RSM Manager will each run on a different machine on the same network (LAN),
follow these configuration steps:
1. Install an EKM Server on Server 1, and RSM Manager on Server 2:
2. On Server 2, generate the required RSM configuration files, and modify them as necessary to complete
the RSM configuration. See Configuring RSM for use with EKM and Third-Party Clusters (p. 117).
3. On Server 1, specify the value of the following settings in the ekm.xml file:
EKM and RSM Platform Support
a. jobSourceRootPath: Specify the path to the directory where EKM will stage the data files for
batch jobs submitted to RSM. You must create this directory before job submission begins. This dir-
ectory is resolved on the RSM Manager machine, so it must be accessible from that machine.
b. rsmLauncherURL: Change the value from localhost to the hostname of the server where the
ANSYS RSM Launcher service is running.
For details about these settings, see Specifying Remote Process Policies (<remoteProcess>) (p. 55).
4. In EKM, synchronize queues with RSM (see Synchronizing Job Submission Queues).
Integrating RSM with Third-Party Batch Systems

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
RSM for use with EKM (p. 116) for more details.
As described in Types of Queues (p. 136), 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 you want to
use with EKM, as shown in Figure 8.1: EKM and RSM with an LSF Cluster (p. 115).
Figure 8.1: EKM and RSM with an 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 the RSM Manager on an LSF Head Node/Submit Host. In LSF, a submit host is a machine that is able
to submit jobs to the cluster; often this is just a head node.
3. On the LSF Head Node/Submit Host where RSM is installed, generate the required RSM configuration files,
and modify them as necessary to complete the RSM configuration. This will include mapping the LSF queue
to an RSM queue. See Configuring RSM for use with EKM and Third-Party Clusters (p. 117). For a relevant
example, see Example 8.1: EKM/RSM with an LSF Cluster (Jobs use Local Scratch Directory) (p. 121).
4. In EKM, synchronize queues with RSM. See Synchronizing Job Submission Queues (p. 137) for details.
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.
8.3.2. Supported Platforms

The EKM Server and RSM Manager must run on the same operating system family (all Windows or all
Linux). If a third-party batch system is integrated with the RSM Manager, it must also be from the same
operating system family.
Important
The O.S. family requirement does not exclude using a Linux file server that is accessed from
Windows. The EKM Server, RSM Manager and machine(s) where jobs process must all be
from the same family, but could all be Windows machines that only use a Linux server to
serve files.
See Supported Operating System Versions in the Engineering Knowledge Manager and the ANSYS Remote
Solve Manager documentation for more specific information on supported operating systems.
8.4. Installing RSM for use with EKM

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 Professional, UGE/SGE, and Microsoft Windows HPC.
Important
• There is no requirement that EKM must be installed on the same server as RSM. For a description
of supported platforms and acceptable EKM/RSM configurations, see EKM and RSM Platform
Support (p. 113).
• RSM is automatically installed with ANSYS Workbench, but can also be installed as a standalone
package.
• If using third-party batch systems such as LSF or SGE, install RSM on a Head Node/Submit Host.
• An EKM server only needs to be configured to use RSM if the server’s user-accessible workspace
is being used, and jobs are being submitted from it. If an EKM server is being used for caching
only, RSM does not need to be configured on that server. For more information about server
configurations, see Distributed Servers and Workspace Access (p. 5).
• In order to run jobs successfully in EKM, the installed version of RSM must be exactly the same
version as EKM. For example, EKM 17.0 will not work with RSM 16.2.
Configuring RSM for use with EKM and Third-Party Clusters
• After installing RSM, do not start RSM services. If you will be using the automated script to con-
figure RSM, the script will start RSM services for you. See Configuring RSM for use with EKM and
Third-Party Clusters (p. 117). If you will not be using the automated script, you will need to configure
RSM and start RSM services manually. See Configuring RSM Manually (p. 119).
• If after installing and configuring RSM you wish to install another ANSYS product using the ANSYS
unified installer, make sure that you stop all RSM services before proceeding with the installation,
and then restart them after the installation. For instructions refer to RSM Service Installation and
Configuration in the Remote Solve Manager User’s Guide.
For details about installing RSM, refer to RSM Software Installation in the Remote Solve Manager User’s
Guide.
For details on the RSM integration settings that are stored in EKM, refer to Specifying Remote Process
Policies (<remoteProcess>).
8.5. Configuring RSM for use with EKM and Third-Party Clusters
Once you have installed RSM, you must configure it to work with EKM. For your convenience, a script
is provided in the EKM_HOME\examples\rsm folder which automates the configuration process.
Running the enable-portal-setting.cmd[sh] script does the following:
• Enables the LauncherService setting in the RSM\Config\Ans.Rsm.AppSettings.config file:

Note that the LauncherService is enabled by default, and should not be disabled.
• Sets the value of the ConfigurationDirectory setting in the RSM\Config\Ans.Rsm.AppSet-

tings.config file, which determines where RSM configuration files will be generated:
<appSettings name="JobManagement">
<add key="CompressionThresholdMb" value="0" />
<add key="CleanupTimeSpan" value="00:10:00" />
<add key="FinishedJobHistoryCleanupTimeSpan" value="02:00:00" />
<add key="FailedJobHistoryCleanupTimeSpan" value="1.00:00:00" />
<add key="CancelJobHistoryCleanupTimeSpan" value="00:10:00" />
<add key="JobsWatcherPeriodMs" value="5000" />
<add key="LogWatcherPeriodMs" value="1000" />
<add key="AsyncResultPollingTimeoutMs" value="1000" />
<add key="ConfigurationDirectory" value="\some\local\path" />
If the specified directory does not exist, it will be created automatically.
• Creates the RSM ClusterConfiguration (.rsmcc) and ConfiguredQueue (.rsmq) files in the specified con-
figuration directory.
• Starts the RSM Manager. In Windows, enable-portal-setting.cmd also registers the RSM Manager
as a Windows service.
For instructions on using the automated script, see Configuring RSM Automatically (p. 118).
You can also perform the configuration steps manually if desired. See Configuring RSM Manually (p. 119).
8.5.1. Configuring RSM Automatically

The enable-portal-setting.cmd[sh] script that is provided with the EKM installation automates
most of the steps required to configure RSM (see Configuring RSM for use with EKM and Third-Party
Clusters (p. 117)). Using the script is optional, but can make configuration faster and easier.
Important
Prior to running the script, make sure that you have set the AWP_ROOT170 environment
variable.
To configure RSM automatically using a script:
1. If the RSM Manager Service is currently running, stop it.
• In Windows, as an administrator, run net stop RSMJobManagerService170.
• In Linux, runrsmmanager stop.
2. If jobs will be run from RSM only, you can skip this step. Otherwise, if you are integrating RSM with an LSF,
PBS, TORQUE, UGE/SGE or Windows HPC cluster:
a. Go to EKM_HOME\examples\rsm and open the enable-portal-setting.cmd[sh] script

in a text editor.
b. If you will be running jobs exclusively via the cluster, comment out the default rsm config com-
mand, as shown below:
rem "%AWP_ROOT170%\RSM\bin\rsm.exe" config create default
If you will be running jobs via RSM as well as via the cluster, you can leave this uncommented.
c. Uncomment the rsm config command that corresponds to your cluster type, and optionally
specify arguments to configure the cluster configuration. You can also modify the .rsmcc and
.rsmq files after they have been generated (see Modifying RSM Configuration Files (p. 124)).
rem Uncomment one of the following "rsm config" commands:
rem (1) Local RSM sample...

"%AWP_ROOT170%\RSM\bin\rsm.exe" config create default
rem (2) LSF sample...

rem "%AWP_ROOT170%\RSM\bin\rsm.exe" config create LSF -name lsfcc -rsmQueue mylsfqueue
-clusterQueue lsfqueue1
rem (3) Win HPC (using local scratch) sample...

rem "%AWP_ROOT170%\RSM\bin\rsm.exe" config create MSHPC -name MSHpcConfiguration
-localscratch c:\rsmtemphpc -scratchUnc rsmtemphpc -rsmQueue MsHpcQueue
3. Running as Administrator, use a command line to go to EKM_HOME/examples/conf/rsm.
4. Use enable-portal-setting.cmd[sh] along with a parameter that specifies the location of the
configuration directory. This is the directory where the .rsmcc and .rsmq files will be generated. Referring
to the sample below, replace /some/path with a local path on the RSM server that is read/write accessible
to the user running the RSM Job Manager (for example, D:\RSMData).
enable-portal-setting.cmd /some/path
If the directory that you specify does not currently exist, it will be created automatically.
8.5.2. Configuring RSM Manually

If you do not want to use the enable-portal-setting.cmd[sh] script provided with EKM to
configure RSM, you can configure RSM manually instead.
Configuration steps include:

8.5.2.1. Specifying a Directory for RSM Configuration Files
8.5.2.2. Generating RSM Configuration Files
8.5.2.3. Modifying RSM Configuration Files
8.5.2.4. Starting RSM Services on Windows
8.5.2.5. Starting RSM Services on Linux
Note
When EKM is used with RSM, it is required that the LauncherService be enabled in the
RSM\Config\Ans.Rsm.AppSettings.config file. This setting is enabled by default,
and should not be disabled.
8.5.2.1. Specifying a Directory for RSM Configuration Files

When using EKM with RSM, you must change the ConfigurationDirectory in the
Ans.Rsm.AppSettings.config file to a specific path on the RSM server. This is the directory in
which RSM configuration files will be generated. If not specified, this will resolve to %APPDATA% on
Windows or ~/.ansys/vVER/ on Linux, and job submission will not work.
To set this directory manually:
1. If the RSM Manager Service is currently running, stop it.
• In Windows, as an administrator, run net stop RSMJobManagerService170.
• In Linux, runrsmmanager stop.
2. Go to the RSM\Config folder where ANSYS products are installed and open the Ans.Rsm.AppSet-
tings.config file.
3. Specify a local path on the RSM server that is read/write accessible to the user running the RSM Job
Manager:
<appSettings name="JobManagement">
<add key="CompressionThresholdMb" value="0" />
<add key="CleanupTimeSpan" value="00:10:00" />
<add key="FinishedJobHistoryCleanupTimeSpan" value="02:00:00" />
<add key="FailedJobHistoryCleanupTimeSpan" value="1.00:00:00" />
<add key="CancelJobHistoryCleanupTimeSpan" value="00:10:00" />
<add key="JobsWatcherPeriodMs" value="5000" />
<add key="LogWatcherPeriodMs" value="1000" />
<add key="AsyncResultPollingTimeoutMs" value="1000" />
<add key="ConfigurationDirectory" value="\some\local\path" />
8.5.2.2. Generating RSM Configuration Files

When using EKM with RSM, the configuration of RSM is done through XML-based configuration files.
These files enable you to define RSM queues and cluster configurations, and integrate RSM with third-
party batch systems.
To begin, you must run a command to generate the RSM configuration files required for your particular
setup. Two configuration files are generated:
• The .rsmq file enables you to define RSM queues
• The .rsmcc file enables you to define a cluster configuration
Basically, the .rsmcc file contains information about the cluster, and how RSM will work with the
cluster. The .rsmq file defines the RSM queue names that users will see in EKM. Each RSM queue maps
to an actual cluster queue name as well as a cluster configuration defined in the .rsmcc file.
Once the configuration files have been generated, you can modify them and specify values for additional
properties that they contain.
To generate the required RSM configuration files, you must run the rsm config command at \Pro-
gram Files\ANSYS Inc\v170\RSM\bin, appending options if necessary to create the desired
configuration. (In Linux, use rsmutils config at RSM/Config/tools/linux.)
Before generating files, make sure that you have specified a target directory (p. 119) for the generated
configuration files. To ensure that you specify appropriate configuration options, it is recommended
that you read Important Considerations and Recommendations for Job Submission (p. 124) before gen-
erating configuration files.
Command usage and possible arguments are outlined below.

D:\Program Files\ANSYS Inc\v170\RSM\bin>rsm config
Usage:
-? or -h: Display usage
config {operator} [options] [arguments]
where operator:
list: For listing configuration

where arguments
-cc configuration_name: list options for single cluster configuration (Native only)
create: For creating configurations

where option:
default: Equivalent to 'config create ARC -name localhost -rq Local'.

ARC|LSF|PBS|TORQUE|SGE|UGE|MSHPC: Creates a configuration for specified cluster type.
where argument
[-name name]: Configuration name. Defaults to cluster type option.
[-rsmQueue|-rq name]: RSM queue name. Defaults to same as cluster queue.
[-clusterQueue|-cq name]: Cluster queue name. Required except ARC and MSHPC.
[-submitHost|-sh machine]: Submit host. Defaults to localhost.
[-platform|-p win|lin]: Submit host platform. Required when submit host not localhost.
[-stagingDir|-sd path]: Staging path. This will be a UNC path on Windows.
[-localScratch|-ls path]: Local scratch path.
[-scratchUnc|-su path] (Windows only): UNC share path of -localScratch path not including
'\\machine\' portion.
[-peSmp|-ps name] (UGE|SGE only): Default will be 'pe_smp' if not specified.
[-peMpi|-pm name] (UGE|SGE only): Default will be 'pe_mpi' if not specified.
[-noCleanup|-nc] (with -stagingDir): Skip cleanup of staging directory.
Use the examples below as a guide when generating configuration files.
Generating Configuration Files for a Basic Setup (EKM with RSM Only)
If jobs will be run from RSM only, you can enter the following command:
C:\Program Files\ANSYS Inc\v170\RSM\bin>rsm config create default
or
C:\Program Files\ANSYS Inc\v170\RSM\bin>rsm config create ARC -name localhost -rq Local
In this case, a LOCALHOST.rsmcc file is created which contains the following settings:
<?xml version="1.0" encoding="utf-8"?>
<ClusterConfiguration version="1">
<name>localhost</name>
<type>ARC</type>
<machine>localhost</machine>
<submitHostPlatform>AllWindows</submitHostPlatform>
<stagingDirectory />
<localScratchDirectory />
<fileCopyOption>None</fileCopyOption>
<nativeSubmitOptions />
<useSsh>False</useSsh>
<sshAccount />
<sshStagingDirectory />
<useSshForLinuxMpi>True</useSshForLinuxMpi>
<deleteStagingDirectory>True</deleteStagingDirectory>
<readonly>False</readonly>
</ClusterConfiguration>
In this configuration, the cluster type is ARC, which stands for ANSYS RSM Cluster, the configuration
name is localhost, and the RSM queue name is Local. If not specified, the cluster queue name
defaults to Local.
If you were to open the queues.rsmq file, you would see the Local queue added there:
<Queues>
<Queue version="1">
<name>Local</name>
<clusterConfigurationName>localhost</clusterConfigurationName>
<clusterQueueName>Local</clusterQueueName>
<enabled>True</enabled>
</Queue>
</Queues>
Generating Configuration Files for Integration with Third-Party Clusters: Examples and
Overview
The following examples provide a general overview of how to integrate a third-party cluster with EKM
and RSM. For more in-depth examples, see Generating Configuration Files for Integration with Third-
Party Clusters: Additional Examples (p. 123).
Example 8.1: EKM/RSM with an LSF Cluster (Jobs use Local Scratch Directory)
To configure EKM/RSM to use an LSF queue, and run jobs in the local scratch directory, you would enter
a command similar to the following:
/ansys_inc/v170/RSM/Config/tools/linux/rsmutils>rsmutils create LSF -name LSFSCRATCH -localScratch /rsmtmp
-rsmQueue LSF-SCRATCH -clusterQueue normal
The following arguments are used in this example:
• LSF = cluster type is LSF
• -name LSFSCRATCH = cluster configuration name will be LSFSCRATCH
• -localScratch /rsmtmp = jobs will run in a local scratch directory /rsmtmp
• -rsmQueue LSF-SCRATCH = RSM queue name will be LSF-SCRATCH
• -clusterQueue normal = actual cluster queue name is normal
An LSFSCRATCH.rsmcc file is created which contains the following settings:

<name>LSFSCRATCH</name>
<type>LSF</type>
<submitHostPlatform>AllLinux</submitHostPlatform>
<localScratchDirectory>/rsmtemp</localScratchDirectory>
<sshAccount />
In this example, an RSM queue name (LSF-SCRATCH) is specified. This will be the queue name displayed
in EKM. If an RSM queue name is not included in the command line (for example, -rsmQueue LSF-
SCRATCH), the actual cluster queue name will be displayed instead.
If you were to open the queues.rsmq file, you would see the LSF-SCRATCH queue added there:
<Queues>
<Queue version="1">
<name>LSF-SCRATCH</name>
<clusterConfigurationName>LSFSCRATCH</clusterConfigurationName>
<clusterQueueName>normal</clusterQueueName>
</Queue>
</Queues>
The clusterConfigurationName value, LSFSCRATCH in this example, is what links the queue to
the actual cluster configuration.
Example 8.2: EKM/RSM with a Microsoft HPC Cluster (Jobs use a Local Scratch Directory)
To integrate EKM/RSM with a Microsoft HPC cluster, and run cluster jobs in a local scratch directory,
you would enter a command similar to the following:
C:\Program Files\ANSYS Inc\v170\RSM\bin>rsm config create MSHPC -name HPCSCRATCH -localscratch C:\RSMTemp
-scratchUnc RSMTemp -rsmQueue HPC-SCRATCH
When integrating with a Microsoft HPC cluster, the cluster queue name will default to Local if not
specified.
In this example, including the -localscratch argument indicates that jobs will run in a local scratch
directory. The path is the same as what you would see specified for the Share Path for Local Scratch
setting in the Compute Server Properties dialog box in RSM (see Properties on the File Management
Tab in the RSM User’s Guide).
An MSHPC.rsmcc file is created which contains the following settings:

<name>HPCSCRATCH</name>
<type>MSCC</type>
<submitHostPlatform>AllWindows</submitHostPlatform>
<localScratchDirectory>C:\RSMTemp</localScratchDirectory>
<sshAccount />
<nativeSetting name="HPC_SCRATCH_UNC">RSMTemp</nativeSetting>
If you were to open the queues.rsmq file, you would see the following queue added there:
<Queues>
<Queue version="1">
<name>HPC-SCRATCH</name>
<clusterConfigurationName>HPCSCRATCH</clusterConfigurationName>
<clusterQueueName>Local</clusterQueueName>
</Queue>
</Queues>
Generating Configuration Files for Integration with Third-Party Clusters: Additional Ex-
amples
Here are more in-depth examples of commands for generating RSM configuration files for SGE, Microsoft
HPC and LSF clusters.
Note that a single cluster queue can be mapped to more than one RSM queue.
Cluster Configuration RSM Queue Cluster Queue

Name Name Name
SGELOCAL all.qa all.q
SGESHARE SGE_SHARE ekmshare1
HPCSCRATCH HPC-SCRATCH N/Ab
HPCSHARE HPC-SHARE N/Ab
LSFSCRATCH LSF-SCRATCH normal
LSFSHARE LSF-SHARE normal
a
When an RSM queue name is not specified with the -rsmQueue option, the underlying cluster queue name is used.
b
HPC does not define named queues.
Example 8.3: SGE on Linux
2 cluster queues: all.q and ekmshare1
In EKM, the SGE queue ekmshare1 is referred to as SGE_SHARE. all.q is not aliased and is referred
to as all.q.
Local scratch setup: Jobs submitted to RSM all.q queue will run in a local scratch folder /rsmtmp.
rsmutils config create UGE -name SGELOCAL -localScratch /rsmtmp -peMpi myPE -clusterQueue all.q
No local scratch. Jobs submitted to RSM’s SGE_SHARE queue will run in shared cluster directory specified
by jobSoureRootPath in ekm.xml.
rsmutils config create SGE -name SGESHARE -peSmp myPE -clusterQueue ekmshare1 -rsmQueue SGE_SHARE
Note that you can specify UGE or SGE for config create. They are the same.
Example 8.4: Microsoft Windows HPC on Windows Server 2012
HPC does not define named queues.
We define 2 queues in RSM: HPC-LOCAL and HPC-SHARE.
Local scratch setup. Jobs submitted to RSM’s HPC-SCRATCH queue will run in a local scratch folder
C:\RSMTemp. Note that the cluster nodes will all share this folder as \\[ExecutionNode]\RSMTemp.
rsm config create MSHPC -name HPCSCRATCH -localscratch C:\RSMTemp -scratchUnc RSMTemp -rsmQueue HPC-SCRATCH
No local scratch. Jobs submitted to RSM’s HPC-SHARE queue will run in shared cluster directory specified
rsm config create MSHPC -name HPCSHARE -rsmQueue HPC-SHARE
Example 8.5: LSF on Linux
1 cluster queue: normal
In EKM, the LSF queue normal is accessed via the RSM queue names LSF-SCRATCH and LSF-SHARE.
Local scratch setup. Jobs submitted to RSM’s LSF-SCRATCH queue will run in a local scratch folder
/rsmtmp.
rsmutils config create LSF -name LSFSCRATCH -localScratch /rsmtmp -rsmQueue LSF-SCRATCH -clusterQueue normal
No local scratch. Jobs submitted to RSM’s LSF-SHARE queue will run in shared cluster directory specified
rsmutils config create LSF -name LSFSHARE -rsmQueue LSF-SHARE -clusterQueue normal
8.5.2.3. Modifying RSM Configuration Files

When you generate RSM configuration files (p. 120), they are generated in the configuration direct-
ory (p. 119) that is specified in the \RSM\Config\Ans.Rsm.AppSettings.config file.
You can modify these files after they are created to complete your configuration.
Sample configuration files for different cluster types can be found in the EKM_HOME\ex-
amples\rsm\sample-configurations folder.
Important Considerations and Recommendations for Job Submission

The way in which you configure EKM and RSM will depend largely on the solver that you want to use
for job submission.
Here are some key points to keep in mind:
• The option of using a shared staging directory applies to all ANSYS solvers.
• The option of using a local scratch directory applies to MAPDL/Mechanical only.
• If you use a Fluent, CFX or Electronics job template to submit a job to a queue that uses a local scratch dir-
ectory, the job may fail.
• When configuring a job template in EKM, ensure that you make available only those queues that support
the type of job being submitted. For example, in the CFX or Electronics template, ensure that you enable
only those queues that use a shared staging directory. For more information about job template properties,
see Creating a Custom Job Template in the EKM User’s Guide.
• Consider giving your RSM queues meaningful names, so that you can easily identify what they are to be
used for. For example, you may want to indicate whether or not the queue uses a local scratch directory.
Defining Cluster Configuration Properties

Below is a description of each property in the .rsmcc configuration file. Note that some properties
are specific to certain cluster types.
<name>: The cluster configuration name. This name will be referenced in the queue definition
(queues.rsmq) file.
<type>: The type of cluster. Possible values are ARC (ANSYS RSM Cluster), LSF, PBS, TORQUE,
SGE, UGE, and MSCC.
<machine>: This will always be set to localhost.
<submitHostPlatform>: The platform of the cluster submission host. The value can be AllWin-
dows or AllLinux.
<stagingDirectory>: IMPORTANT: Leave this property blank. This is the shared cluster directory
in which jobs will run. It is specified in the jobSourceRootPath setting in the ekm.xml file. For
more information see Specifying Remote Process Policies (<remoteProcess>) (p. 55).
<localScratchDirectory>: If cluster jobs will run in a scratch directory local to the execution
node, specify the path of the desired local scratch space on the cluster. This should be a local path
such as D:\storage\RsmTemp. Note that the use of local scratch is supported for MAPDL/Mech-
anical solutions only. If using other solvers, you must use a shared staging directory. See Important
Considerations and Recommendations for Job Submission (p. 124).
<fileCopyOption>: Always leave this set to None.
<nativeSubmitOptions>: Not applicable for most EKM setups. For advanced, customized con-
figurations, refer to [scheduler] Job Submission Arguments in Properties on the Cluster Tab in the
RSM User’s Guide.
<useSsh>: If integrating with a Linux cluster, specify whether or not you want to use the SSH
protocol to communicate with remote cluster nodes. This value can be True or False.
<sshAccount>: If SSH is being used, enter the user account that will be used to access the cluster
node.
<sshStagingDirectory>: If SSH is being used, enter the path of the directory on the remote
machine where jobs will be run.
<useSshForLinuxMpi>: Applies only to distributed jobs using multiple cluster execution nodes.
If true, use SSH for inter-node communication on the cluster, If false, use RSH.
<deleteStagingDirectory>: Specify whether the temporary job subdirectories created in the
staging directory are deleted upon completion of jobs. This value can be True or False. Retaining
job files in the staging directory can be helpful for testing and debugging failed jobs. Note that if
the job staging directory is the same as the EKM job data directory (jobSourceRootPath), RSM
will never try to delete the user’s client directory.
<readonly>: Internal use only.
(Microsoft HPC only) <nativeSetting name=”HPC_Scratch_UNC”>: If cluster jobs will run

in a scratch directory local to the execution node, specify the UNC path of the scratch directory so
that it can be located on all execution nodes.
(SGE/UGE only) <nativeSetting name=”SGE_PE_DISTRIBUTED”>: Enter the name of the
Distributed Parallel environment.
(SGE/UGE only) <nativeSetting name=”SGE_PE_SHARED”>: Enter the name of the Shared
Memory Parallel environment.
Defining RSM Queues

The queues.rsmq configuration file contains a <Queues> element in which individual RSM queues
are defined. RSM queues are mapped to RSM configuration files.
Each queue has the following properties:
<name>: The RSM queue name to be displayed in EKM. If this is not specified, the actual cluster
queue name will be displayed instead.
<clusterConfigurationName>: The name of the cluster configuration that will use this queue.
Specify the same value that is specified for the <name> property in the .rsmcc configuration file.
<clusterQueueName>: The actual cluster queue name. Required for all cluster types except ARC
(native RSM) and MSCC (Microsoft HPC). If left blank for an ARC or MSCC cluster, the cluster queue
name will default to Local.
<enabled>: Specify True to enable the queue, or False to disable it. Only enabled queues will
appear as available queues in EKM.
8.5.2.4. Starting RSM Services on Windows

Follow the instructions below to install and configure the RSM services required for EKM/RSM integration.
1. Referring to Installing RSM Services for Windows in the Remote Solve Manager User’s Guide, install only
the RSM Manager service:
AnsConfigRSM.exe -mgr
The RSM Manager (Ans.Rsm.JMHost.exe) provides an XmlRpc interface called the Launcher
Service to be used by EKM.
2. In EKM, OS account names are determined by the mapping login module that is configured for your
installation. For details refer to How User Logins Work in the Installation Guide.
Important
• On a Windows machine, the account name must always include the domain (for example,
MYDOMAIN\jsmith).
• In EKM, this same domain must be specified in the rsmWindowsDomain setting in the
ekm.xml file. By default, jobs are submitted to RSM as rsmWindowsDomain value\OS
account name. Refer to rsmWindowsDomain (Windows only) (p. ?) for details.
• If a user’s RSM account has different credentials than the credentials used to sign in to
EKM, the user must specify those RSM account credentials in his or her job management
preferences in EKM. When submitting jobs, EKM will then pass these credentials to RSM
instead of the user’s EKM credentials. See Specifying Job Management Preferences in
the User’s Guide.
3. Optionally configure the XmlRpc port for ANSYS RSM Launcher 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 XmlRpc interface of the ANSYS RSM Launcher service provides the interface from the EKM
Server to RSM. The Launcher service must be running with XmlRpc enabled for EKM to be able
to communicate with RSM. This is done through the LauncherXmlRpcEnabled setting.
This service runs on a tcp port specified in the file Ans.Rsm.AppSettings.config that
is located in the install_root\RSM\Config directory of the RSM installation. For example:
C:\Program Files\ANSYS Inc\v170\RSM\Config\Ans.Rsm.AppSettings.config.
If you need to change the default XmlRpc port (10017) used, edit this file and change the
value specified for the LauncherXmlRpcPort in the appSettings settings:
<add key="TokenVerification" value="false" />
EKM defines a URL used to communicate with this RSM service. If you change the default XmlRpc
port of the Launcher service, you will also need to change the port specified in the default
value of the rsmLauncherURL setting. The rsmLauncherURL setting in EKM also includes
the hostname where this Launcher 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. 55) for details.
4. Specify other Launcher service settings:


</appSettings>
• LauncherXmlRpcSecure: Set to true to enable SSL for the XmlRpc HTTP interface.
• ProxyXmlRpcPortRange: Limit the range of ports for the User Proxy XmlRpc interfaces.
8.5.2.5. Starting RSM Services on Linux

Follow the instructions below to install and configure the RSM services required for EKM/RSM integration.
1. Referring to Installing RSM Services for Linux in the Remote Solve Manager User’s Guide, install only the RSM
Manager service. The RSM Manager (Ans.Rsm.JMHost.exe) provides an XmlRpc interface called the
Launcher Service to be used by EKM. Before installing the RSM Manager service, be sure to read Configuring
RSM to Use a Remote Computing Mode for Linux > Adding Common Job Environment Variables in the Remote
Solve Manager User’s Guide.
2. In EKM, account names are determined by the mapping login module that is configured for your installation.
For details see How User Logins Work (p. ?) in the EKM Installation Guide.
If a user’s RSM account has different credentials than the credentials used to sign in to EKM, the
user must specify those RSM account credentials in his or her job management preferences in EKM.
When submitting jobs, EKM will then pass these credentials to RSM instead of the user’s EKM cre-
dentials. See Specifying Job Management Preferences in the User’s Guide.
3. Optionally configure the XmlRpc port for ANSYS RSM Launcher 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 XmlRpc interface of the ANSYS RSM Launcher service provides the interface from the EKM
Server to RSM. The Launcher service must be running with XmlRpc enabled for EKM to be able
to communicate with RSM. This is done through the LauncherXmlRpcEnabled setting.
This service runs on a tcp port specified in the file Ans.Rsm.AppSettings.config which is
located in the <install root>\RSM\Config directory of the RSM installation. For example:
C:\Program Files\ANSYS Inc\v170\RSM\Config\Ans.Rsm.AppSettings.config.
If you need to change the default XmlRpc port (10017) used, edit this file and change the value
specified for the LauncherXmlRpcPort in the appSettings settings:
EKM defines a URL used to communicate with this RSM service. If you change the default XmlRpc
port of the Launcher service, you will also need to change the port specified in the default value
of the rsmLauncherURL setting. The rsmLauncherURL setting in EKM also includes the host-
name where this Launcher 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 (<remotePro-
cess>) (p. 55) for details.
4. Specify other Launcher service settings:

EKM and RSM Job Directories


</appSettings>
• LauncherXmlRpcSecure: Set to true to enable SSL for the XmlRpc HTTP interface.
• ProxyXmlRpcPortRange: Limit the range of ports for the User Proxy XmlRpc interfaces.
8.6. EKM and RSM Job Directories

The following directory settings in EKM and RSM are critical to the seamless integration of EKM and
RSM:
EKM Job Data Directory

The directory where EKM will stage the data files for batch jobs submitted to RSM, if users do not choose
to specify a working directory during job setup. The path to this directory is resolved on the RSM Manager
machine, so it must be accessible from that machine. The job data files are created by the data management
process (p. 130) running on the RSM Manager machine under this path.
The EKM job data directory is specified during installation, and is captured in the jobSource-
RootPath setting in the ekm.xml file. See Specifying Remote Process Policies (<remotePro-
cess>) (p. 55).
This directory has some essential requirements and considerations. Refer to Access and Permission
Requirements of the Job Data Directory (p. 131).
RSM Cluster Configuration Shared Cluster Directory (when applicable)

A directory used to share files within the cluster.
Important
• These two directories must be the same location when using EKM with RSM. When RSM is being
used with a cluster, network shares will be used to accomplish this. There is no requirement that
the physical location of the directory is on one of the machines running EKM or RSM. It just needs
to be accessible.
• If users will be submitting jobs to EKM from Workbench, and Workbench and RSM are on different
machines that refer to the job directory using different paths, then you must specify a
pathMapping in the ekm.xml file. This ensures that EKM passes a job path to RSM that RSM
can recognize. See Specifying Remote Process Policies (<remoteProcess>) (p. 55).
8.6.1. How Job Data Files are Handled in EKM and RSM
This section describes:
8.6.1.1.The Data Management Process
8.6.1.2.The Creation and Structure of Job Directories
8.6.1.3. Access and Permission Requirements of the Job Data Directory
8.6.1.1. The Data Management Process

A data management process is used to both stage and retrieve files for jobs submitted to RSM. It is a
Java process that runs on the RSM Manager as the same user who submits the RSM job.
When a user starts a job in EKM, the user’s data management process writes job data to the job data
directory, which is specified in the jobSourceRootPath setting in the ekm.xml file. The RSM Manager
accesses this directory when managing the job.
In order for the data management process to execute properly, the job data directory must meet the
following requirements:
• The directory must exist before EKM is deployed and users begin running jobs, and must be accessible by
the RSM Manager machine.
• All users who will be submitting jobs must have read/write permission on this directory.
For more information about the jobSourceRootPath setting, see Specifying Remote Process Policies
(<remoteProcess>) (p. 55).
To see how the data management process works, see the example in The Creation and Structure of Job
Directories (p. 130).
8.6.1.2. The Creation and Structure of Job Directories

When users set up a batch job in EKM, they have the option of choosing a working directory for the
job. If they do not choose one, EKM will stage job files in the job data directory. This directory is specified
in the jobSourceRootPath setting in the ekm.xml file.
If a shared job data directory is being used, EKM will create a workspace directory under the job data
directory (if not already present), followed by a username directory, and time stamp directory.
As an example in Windows:
1. In the ekm.xml file, the jobSourceRootPath is set to \\RSMMANAGER\HPCTemp. This is a UNC path
to a shared directory named HPCTemp on the RSM Manager machine. This translates to C:\HPCTemp on
that machine.
2. John Smith (with user name jsmith) is signed in to the Default workspace. When John runs a job, js-
mith’s data management process creates the following directory for the job:
C:\HPCTemp\Default\jsmith\20_May_2015_10.39.18_AM
3. When John selects input files for the job, the files are uploaded to the 20_May_2015_10.39.18_AM
directory. RSM Manager accesses this directory to manage the job. The RSM compute server can access
this directory, and will run the job directly in it to avoid unnecessary file transfers.
4. Every time John starts a new job, a new subdirectory named with the job’s time stamp will be created under
the C:\HPCTemp\Default\jsmith directory.
5. When another user, Susan Thomas, starts a job, a directory will be created for her job under the job data
directory in a similar way:
C:\HPCTemp\Default\sthomas\20_May_2015_11.40.26_AM
EKM and RSM Job Directories
In a Linux configuration, if home directories are being used instead of a shared job directory, only a
time stamp directory will be created under the job data directory, as shown in the following example:
/net/server/home/jsmith/jobRoot/20_May_2015_10.39.18_AM
For information about specifying the jobSourceRootPath setting, see Specifying Remote Process
Note
If using a shared job data directory, it is recommended that you create the workspace sub-
directory up front, and ensure that all users who will be submitting jobs have read/write
permission on that subdirectory. Additional steps may be needed depending on your security
requirements. For more information, see Access and Permission Requirements of the Job
Data Directory (p. 131).
8.6.1.3. Access and Permission Requirements of the Job Data Directory

Before job submission begins, you must create the job data directory that you have specified in the
jobSourceRootPath setting, and ensure that it is accessible to all users who will be submitting jobs.
EKM will create workspace, user, and time stamp subdirectories as described in The Creation and
Structure of Job Directories (p. 130). There are important considerations to be made regarding the job
data directory and its subdirectories. If you are working in Linux, additional steps may be required de-
pending on the directory that you have chosen, and the level of security that you desire.
In Windows:
• The job data directory must be a shared directory, specified by a UNC path in the jobSourceRootPath
setting.
• Make sure that this directory is open to all users who will be running RSM jobs.
• It is recommended that you create the workspace subdirectory up front, and ensure that all users have
read/write permission on this directory, so that each user’s data management process will be able to create
a user directory for that user under the workspace directory. For example, if your job data directory path is
\\RSMMANAGER\HPCTemp, and users will be submitting jobs from the Default workspace, create a De-
fault directory under the HPCTemp directory (\\RSMMANAGER\HPCTemp\Default), and set appropriate
permissions on the Default directory.
In Linux:
• The use of home directories (via a relative path) is the recommended way of handling users’ job data in
Linux. Home directories provide each user with guaranteed access to his or her own job data, while preventing
unwanted access by other users. The home directory is accessible by RSM, and the permission requirements
are satisfied because users have read/write access on their own home directories.
• You may choose to use a shared job directory (via an absolute path) instead of home directories. This may
be less secure, however, because users could potentially have access to each other’s data. If you do choose
to use a shared job directory, it is recommended that you create the workspace subdirectory up front, and
ensure that all users have read/write access on this subdirectory. Although not necessary, for tighter security
you may also want to create user subdirectories up front and grant each user full read/write permissions on
his or her user subdirectory rather than the workspace directory. Keep in mind, however, that if you remove
read/write permissions on the workspace directory, you will need to create user subdirectories for any new
users who will be added to EKM later on, and set up appropriate permissions on those directories.
It is important to ensure that all users have at least access (execute) permission on all parent folders
in the chain, right up to the top level. Consider the path /someshare/folder1/jobRoot/De-
fault. If you granted users read/write permissions on the jobRoot and Default folders, but did
not grant them access permission on folder1, job submission would fail for those users.
For information about specifying the jobSourceRootPath setting, see Specifying Remote Process
Chapter 9: Defining EKM Servers, Queues, and External Applications
The /Administration/Servers page contains a built-in job submission server named Master, and is
also the page where you would add 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. 136).
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, process, 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
Solve 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 Specifying General Server Settings
Specific usages of external applications are covered in detail in other chapters in this Administration
Guide and in the User’s Guide. Refer to Defining Process Templates in EKM Studio in the User’s Guide for
using external applications in process templates 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 Specifying General Server
Settings).
• For batch jobs, install and configure RSM as explained in Installing RSM for use with EKM (p. 116).
• For interactive jobs, install and configure EnginFrame as explained in Installing and Configuring Engin-
Frame in the EKM Installation Guide.
Defining EKM Servers, Queues, and External Applications
• Create batch job submission queues in EKM that correspond to RSM queues, and interactive job sub-
mission queues that correspond to queues defined in the ekm.xml file. This is done automatically at
startup. See Synchronizing Job Submission Queues (p. 137).
• 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. 139).
This chapter presents information on how to set up EKM servers, queues, and external applications.
Topics include:
9.1. Adding EKM Servers
9.2. Defining EKM Cache Servers
9.3.Types of Queues
9.4. Managing Queues
9.5. Defining External Applications
9.6. Running Interactive Jobs in EKM
9.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 on the /Administration/Servers page.
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.
9.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 Workspace Access (p. 5)
for information on setting up a cache server.
9.2.1. Creating a New EKM Cache Server

To create a new EKM Cache Server:
1. From the main drop box, select Administration, then select the Servers page.
2. Select (New) > Cache Server. This opens the New EKM Cache Server dialog box.
Defining EKM Cache Servers
Figure 9.1: Creating a New EKM Cache Server
3. 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.
4. Enter the fully qualified host name of the server (for example, server1.domain.com).
5. Enter the port number for the port that the EKM Server on that host is running on.
6. 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. 11).
7. Click OK. A new server of type Cache Server is created on the Administration/Servers page.
9.2.2. Editing an Existing EKM Cache Server

To edit an existing EKM Cache Server, select an existing Cache Server under /Administration/Serv-
ers and select (Edit) > EKM Cache Server. This opens the Edit EKM Cache Server dialog box.
Refer to Creating a New EKM Cache Server (p. 134) for details about the available settings.
9.3. Types of Queues

All queues are defined under the Master EKM Server, which is located at /Administration/Serv-
ers/Master.
Figure 9.2: Sample Queues on Master Server
There are three types of queues in EKM:
• Data Extraction Queue
EKM installs with a Data Extraction Queue at /Administration/Servers/Master/EKM

Server. There can only be one Data Extraction Queue defined. This queue specifies a set of applic-
ations 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. 140)).
• 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 EKM’s /Admin-
istration/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. 137).
• 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 /Administration/Servers/Master
Managing Queues
folder when the EKM server starts. If you accidentally delete an interactive queue, you can use the
Synchronize Queues action to restore it.
9.4. Managing Queues

This section describes:
9.4.1. Synchronizing Job Submission Queues
9.4.2. Defining Job Submission Queue Settings
9.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 automat-
ically create batch job submission queues of the same name in EKM under /Administration/Serv-
ers/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 on the /Administration/Servers/Master page.
2. If there are any queues in RSM that are not defined in EKM under /Administration/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 /Administration/Servers/Master, you will see a warning icon next to the queue
and the corresponding tool tip will indicate" Queue not configured in RSM."
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. 136)). 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. Go to the Administration section and then go to the Servers/Master folder.
2. Click the synchronize queues button on the toolbar. This displays a dialog reporting the progress of
the synchronization.
9.4.2. Defining Job Submission Queue Settings

When defining a batch or interactive job submission queue (see Types of Queues (p. 136)), there are
settings that you can specify that determine how jobs are handled in that queue.
To define a job submission queue’s settings:
1. Go to Administration/Servers/Master and select the queue whose settings you would like to define.
2. Select (Edit) > Job Submission Settings. The Edit Job Submission Settings dialog box appears.
Figure 9.3: Editing a Queue’s Job Submission Settings
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
• Torque
Defining External Applications
• SGE
• Microsoft Windows HPC
Note
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:
• IBM LSF
• Adaptive Computing MOAB
• NICE Neutro
• Altair PBS
• Torque
• SGE
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 applic-
ations 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/jobSubmissionApplica-
tions/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.
4. When you are finished defining settings, click OK.
9.5. 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 (p. 136). 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 file list window, any external applications associated with that queue
are listed. In this way the queue object acts like a folder in the file list window, 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 applic-
ation would be:
/Administration/Servers/Master/MyQueue1/myApp.app.xml
Important
All Queues and External Applications must be defined under /Administration/Serv-

ers/Master. Cache Servers cannot contain these definitions as they do not support running
applications.
9.5.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 /Administration/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_ROOT170 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 17.0 Applications.
The following is a list of all predefined applications in EKM:
• 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 con-
figure 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.
• extractCaxImage.app.xml: This application is used to extract VCollab’s CAX file from simulation
files for 3D visualization. To make CAX extraction possible, you need to have VMoveCAE installed on
the EKM server. Note that this not the default image extractor in EKM. In order to extract CAX files you
must specify image attributes for each built-in or custom file type from which you want to extract CAX
images. For details see Using VCollab for 3D Visualization in EKM (p. 255).
• 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 don’t need to configure this application.
• vrml2gltf.app.xml: This application is bundled within EKM and is used to convert VRML models
extracted from Fluent and MAPDL files to the glTF format that is used by EKM’s 3D image viewer.
• 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
to an application definition, you should do so only from within EKM using either the Edit >
External Application or Edit > Content action.
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. 145) and Defining External Applications
Directly in EKM (p. 142), describe two methods of creating your own external application definitions.
9.5.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. 145) if you want to define an application using XML.
9.5.2.1. Creating a New External Application

To create a new application directly in EKM:
1. Go to the Administration/Servers/Master and select the queue with which you want to associate the
external application.
2. Select (New) > External Application. This will open the New External Application dialog box, shown
below.
Figure 9.4: Creating a New External Application
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.
Application key
A string that identifies the application. For example, when you execute a batch task in a process,
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 applic-
ation 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
queue’s folder, with the name that is specified for the Application key. In our example, the applic-
ation file myAppKey.app.xml is saved as: /Administration/Servers/Master/Local/myApp-
Key.app.xml
9.5.2.2. Editing an External Application Definition

To edit an existing application definition using a dialog:
1. Select the queue with which the application is associated. Queues are located in the /Administration/Serv-
ers/Master folder.
2. Right-click and select Edit > External Application from the context menu. This will open the Edit External
Application dialog box.
3. Make any changes to the Application key, Application name, Execution path, Command line paramet-
ers, 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.
9.5.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. Select the queue with which the application is associated. Queues are located in the /Administration/Serv-
ers/Master folder.
2. Right-click and select Edit > Content from the context menu. This will open the Edit Content dialog box.
Figure 9.5: 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.
9.5.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. 142) if you want to define an application using a dialog box in
EKM.
9.5.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 9.6: File listing for application.xsd Schema File (p. 146). A full listing is provided in the
EKM_HOME/schema folder.
application.xsd consists of a root element named applications that contains one application ele-
ment. The application element consists of a key, execPath, 0 or more param elements, 0 or more
env elements and an optional nativeOptions element.
key
Used to identify the application. For example, a batch node in a process will use the key to refer to a par-
ticular 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 9.6: 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>
Running Interactive Jobs in EKM
<xsd:element name="applications" type="ekmApplication:Applications" />
</xsd:schema>
9.5.3.2. Defining External Applications Using XML

Application definitions are stored in XML files in EKM. Because of this, EKM supports adding new applic-
ations simply by uploading XML files in the proper format. See Schema Definition for Applications (p. 145)
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 /Administration/Servers/Mas-

ter/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 9.7: myApp-
Key.app.xml listing (p. 147).
Figure 9.7: 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 application’s 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.
9.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.
Figure 9.8: 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. 142).
• Users must install the remote visualization client on their computer or mobile device. See Table 9.2: Remote
Visualization Technologies Supported by EnginFrame in the EKM Installation Guide.
9.6.1. Running Remote Desktop Sessions

Users can start interactive jobs by launching the default Start Interactive Job application on the Ap-
plications panel, 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 on the user’s Jobs/Job Monitor page, and
from there they will be able to connect to the remote session. The selected application will then launch
remotely on the user’s desktop.
For more information, see Running an Interactive Job in the EKM User’s Guide.
Chapter 10: Configuring EKM Mobile
EKM Mobile is an application designed for cell phones and tablets. With it, users can sign in to an EKM
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.
10.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/
Configuring EKM Mobile
For more information, see Using EKM Mobile in the EKM User’s Guide.
10.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-access-
ible host (for example, in your company’s 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 Connector’s 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. 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 User’s 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).
Chapter 11: 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 requires 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 task is
added to their My Tasks page. In addition, an instance of the signoff process is placed on the Process
Monitor page 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 user
designated as 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. 291).
Topics covered in this chapter:

11.1. Introduction to Lifecycles
11.2. Lifecycle Terminology
11.3. Basic Steps for Creating, Configuring, and Managing Lifecycles
11.4. Defining Lifecycles in EKM Studio
11.5. Enabling Lifecycles
11.6. Displaying Lifecycles
11.7. Promoting a Lifecycle Stage
11.8. Demoting a Lifecycle Stage
11.9. Managing Lifecycle Signoff Requests
11.10. Setting a Lifecycle Stage
11.11. Configuring Lifecycles for a Workspace
11.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 11.1: Sample Lifecycle Graph (p. 154) shows an example of a four-stage lifecycle
graph.
Defining and Configuring Lifecycles
Figure 11.1: Sample Lifecycle Graph
Lifecycle stages are promoted and demoted automatically by EKM or by a user/group based on comple-
tion 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 task for easy
access and the task is also placed on the assignee's My Tasks page. 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 li-
fecycle you define in EKM Studio is converted to XML and the file is typed as a Lifecycle (p. 283) 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. 291) for details.
Lifecycle files behave like any other object in EKM with respect to being able to be tagged with user-
defined 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.
11.2. Lifecycle Terminology

Let's start with defining some lifecycle terms that are used throughout EKM Studio.
Stages
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
Defining Lifecycles in EKM Studio
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 task is placed
on their My Tasks page.
11.3. Basic Steps for Creating, Configuring, and Managing Lifecycles

1. Define a lifecycle (p. 155) 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 (p. 176) for the workspace.
4. Enable the lifecycle (p. 166) for an object type if it was not automatically enabled when it was configured
for the workspace.
5. Display (p. 167) the lifecycle for an object, promote (p. 170) or demote (p. 171) a lifecycle stage, manage
signoff requests (p. 172), and set a lifecycle stage (p. 175) (admin only).
11.4. 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.
For an overview of EKM Studio, see The EKM Studio Environment in the EKM User’s Guide.
11.4.1. Steps for Defining New Lifecycles

Follow these basic steps to define a new lifecycle in EKM Studio.
1. Open EKM Studio, as described in Launching EKM Studio in the User’s Guide.
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.
If you are already in EKM Studio and have another item open, 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. 156).
3. Add transitions between stages using the Insert Transition action. See Inserting New Transitions (p. 160).
4. Edit the stages and transitions to further define them. See Editing Stages (p. 157) and Editing Trans-
itions (p. 160).
5. Select Edit > Lifecycle Attributes to define the object types to which the lifecycle will be applied. See
Editing Lifecycle Attributes (p. 165).
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. 164).
11.4.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:
11.4.2.1. Inserting New Stages
11.4.2.2. Editing Stages
11.4.2.3. Renaming Stages
11.4.2.4. Deleting Stages
11.4.2.1. Inserting New Stages
To insert a stage in a lifecycle diagram, click on the toolbar. Then, double-click the stage
to edit it. See Editing Stages (p. 157) for details.
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 (p. 160) 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.
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.
11.4.2.2. Editing Stages

Once a stage is inserted, you can define its properties using the Edit action.
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 11.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 (op-
tional). 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 spe-
cified 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.
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
are available, including the ability to change permissions.
Note
• Object-level permissions will only be granted to users who have an appropriate license
checked out. For example, a user with an Analyst license will not be able to modify an
object even if he or she has been granted Modify permission on the object. He or she must
have a Shared license checked out to be able to modify the object.
• 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.
11.4.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.
11.4.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.
11.4.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. 160)
• Editing Transitions (p. 160)
• Deleting Transitions (p. 163)
11.4.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.
11.4.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.
Figure 11.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 Defini-
tions (p. 162) 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.
3. Define the signoff processes for promoting and demoting the object. Only the person who created the
process 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 Fig-
ure 11.3: Edit Transition Dialog Box for a Lifecycle (p. 161), 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 Develop-
ment 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. Single-click
in the Members box and a drop-down list of available members will be displayed (drop-down list not
shown in Figure 11.3: Edit Transition Dialog Box for a Lifecycle (p. 161)).
• 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.
11.4.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 (p. 165).
The example below shows the script for a BeanShell macro named solveOnce.
Figure 11.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 Scripts folder
on the Administration/Configuration page. For details see Using EKM's Scripting Inter-
face (p. 179). Storing scripts in a centralized library makes them available for any process
template, lifecycle, or custom type. See Configuring a Common Scripts Library (p. 251) for
details.
11.4.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.
11.4.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 Lifecycles folder on the Administration/Configuration

page 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 dif-
ferent name, select File > Save As > Local File.
2. In the Save dialog box, select a save location and specify a file name.
3. Click Save.
To save a lifecycle file to an EKM repository:
1. Select File > Save As > Repository File.
2. In the Save Lifecycle dialog box, enter a name for the lifecycle in the File name edit box. You do not
need to include the extension. If you are in restricted configuration mode, the lifecycle will be saved in
the Lifeycles folder on the Administration/Configuration page.
3. Click Save.
11.4.5. Opening Lifecycle Files

In EKM Studio you can open EKM lifecycle XML files that are stored on your local file system or in the
/Administration/Configuration/Lifecycle folder 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.
To open a lifecycle file that is located in the /Administration/Configuration/Lifecycle folder, select

File > Open > Repository File. Select the desired lifecycle file and click Open.
Figure 11.5: Opening a Lifecycle File in the Repository
11.4.6. Editing Lifecycle Attributes

Once you have defined your lifecycle diagram as described in Steps for Defining New Lifecycles (p. 156),
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. Select Edit > Lifecycle Attributes from the menu bar to open the Edit Lifecycle Attributes dialog box.
Figure 11.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 repos-
itory 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. 166) 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 Java’s 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 expres-
sions after you click OK in the Edit Lifecycle Attributes dialog:
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.
11.5. 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 automat-
ically inherit its parent’s lifecycle.
Important
Once a lifecycle is enabled, the lifecycle permission policies that are defined in the life-
cycle 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
Displaying Lifecycles
dialog box contains this reminder, as shown in Figure 11.7: Enable Lifecycle Dialog
Box (p. 167). 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, then select (Edit) > Lifecycle > Enable. This will open the Enable Lifecycle dialog
box.
Figure 11.7: Enable Lifecycle Dialog Box
2. Click OK.
11.6. Displaying Lifecycles
Once a lifecycle is enabled for an object, you can display it by selecting (More) > Display > Lifecycle
on the right-click menu or toolbar. A sample lifecycle is shown below.
Figure 11.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.
• 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.
Displaying Lifecycles
• 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. Click the user icon in the upper right of the window and select Settings.
2. In the Settings dialog box, select List Display in the left pane, and then check the Lifecycle stage box
in the right pane, as shown below.
Figure 11.9: Adding a Lifecycle Stage Column to the List Display
3. Click OK.
Figure 11.10: List Display with Lifecycle Stage
11.7. 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, then select (Edit) > Lifecycle > Promote. This opens the Promote Lifecycle Stage
dialog box.
Figure 11.11: Promote Lifecycle Stage Dialog Box - Signoff Required
Note
You cannot promote an object if it is under version control and currently checked out
by a user, or if a user has exclusive control of it.
2. Select the new stage.
Demoting a Lifecycle 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.
11.8. 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, then select (Edit) > Lifecycle > Demote. This opens the Demote Lifecycle Stage
dialog box.
Figure 11.12: Demote Lifecycle Stage Dialog Box
Note
You cannot demote an object if it is under version control and currently checked out
by a user, or if a user has exclusive control of it.
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.
11.9. 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.
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 ex-
clusively 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) no-
tifying them that their action is required. The signoff will be listed in each committee member’s My
Tasks page in the Processes section. The signoff process can be displayed by clicking the Signoff link
in the task as shown in Figure 11.13: Level-1 Signoff Task on My Tasks Page (p. 173). The review is started
by clicking the start button 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.
Managing Lifecycle Signoff Requests
Figure 11.13: Level-1 Signoff Task on My Tasks Page
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
• 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
tasks are deleted from the My Tasks page.
11.9.1. Approving a Lifecycle Signoff Request

Once the review for a Signoff task has been “started”, it can be approved for stage promotion or de-
motion.
To approve a signoff request:
1. Select the signoff request on your My Tasks page, then click the approve button on the toolbar. This
will open the Approve Signoff Request dialog box.
Figure 11.14: 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 Tasks page. The
approval will be logged in the lifecycle history.
11.9.2. Rejecting a Lifecycle Signoff Request

Once the review for your lifecycle Signoff task 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 on your My Tasks page, and then click the reject button on the toolbar. This
opens the Reject Signoff Request dialog box.
Figure 11.15: Reject Signoff Request Dialog Box
2. Optionally enter rejection comments. You can view these comments in the object's lifecycle history.
Setting a Lifecycle Stage
3. Click OK to reject the signoff. This action will cancel the Signoff process and cause the stage promotion/de-
motion request to be cancelled. The stage will roll back to its last state. It will also remove the level signoff
request from your My Tasks page. Your rejection will be logged in the lifecycle history.
11.9.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 the object, then select (Edit) > Lifecycle > Cancel Signoff. This will open the Cancel Signoff
dialog box.
Figure 11.16: Cancel Signoff Dialog Box
2. Optionally enter comments. You can view these comments in the object's lifecycle history.
3. Click OK to cancel the signoff request. This action will remove the level signoff task from every member's
My Tasks page.
11.10. 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, then select (Edit) > Lifecycle > Set Stage. This will open the Set Lifecycle Stage
dialog box.
Figure 11.17: Set Lifecycle Stage Dialog Box
Note
You cannot edit the lifecycle stage of an object if it is under version control and currently
checked out by a user, or if a user has exclusive control of it.
3. Optionally, enter comments. You can view these comments in the object's lifecycle history.
4. To set the new stage, click OK.
11.11. 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 user
designated as the Root User, and requires the workspace to be locked down. While restricted configur-
ation is underway, no other user can sign in to the workspace until the process is completed.
To configure a lifecycle in EKM:
1. Start restricted configuration (p. 37) if it has not already been started.
2. Upload, copy, or move the Lifecycle object that was created using EKM Studio (p. 155) or created using
XML (p. 291) to the Lifecycles folder on the Administration/Configuration page.
3. Apply configuration changes (p. 38).
4. Accept configuration changes (p. 39).
Note
It is recommended that you define only one lifecycle per object type.
Chapter 12: 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 process templates, lifecycles, custom types, job templates
and custom applications to automate tasks.

12.1. Introduction to Scripts and Journals
12.2. Defining Scripts Using a Supported Scripting Language
12.3. Using EKM's Scripting Interface
12.4. Using Sample Scripts Supplied by EKM
12.5. Scripting Actions
12.6. Recording Journal Scripts
12.7. Running Journal Scripts
12.8. Example of Journal Recording and Execution
12.9. Running Python and BeanShell Scripts From a Command Window
12.10.Testing or Debugging a Process Template
12.11. Viewing a Script Error Log
12.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 process templates, life-
cycles, 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 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 process templates: You can embed scripts in process template 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.
Scripts and Journals
– Define logic for auto nodes. An auto node will execute the associated script upon activation.
– Define custom dialog boxes for batch execution or task 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 in-
stance 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.
– Define a custom dialog box for executing a job.
• 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 Defining and Using Custom Applications (p. 215).
• Testing/debugging process templates: You can use scripts to launch a process from a given process
template, and test tasks in the process. See Testing or Debugging a Process Template (p. 190).
• 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 on the /Administration/Configuration/Scripts page. Once the script is
placed in that location and the workspace configuration is accepted or applied, all of its macros will be ac-
cessible in all contexts: lifecycles, process templates, 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 on the /Administration/Configuration/Scripts page

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.
Using EKM's Scripting Interface
12.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
documentation, refer to http://www.BeanShell.org. With BeanShell you have full access to all classes
provided by Java’s 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 Inter-
face (p. 179) for information about the classes and methods that are available through the scripting in-
terface.
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.
12.3. Using EKM's Scripting Interface

EKM provides a scripting interface that you can use to define scripts (p. 177) that automate many common
operations. Scripts are typically used as a back-end for custom applications, and can be embedded
within a process template, lifecycle or custom type definition to provide automation where required.
EKM’s scripting interface exposes a number of methods or “macros (p. 177)” 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-17.0.0 and ekm-cae-api-docs-17.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("tes-
tuser") 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 provide addi-
tional methods for specific object types. These are FileObjectInterface, ReportObjectInt-
erface, AnalysisContainerInterface, ShortcutObjectInterface, UserObjectInt-
erface and GroupObjectInterface, ProcessObjectInterface, and TaskInterface.
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, Process or Task, 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 accom-
panying 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 Ek-
mInterface.
If you need to specify an object path when defining a script, you can obtain an object’s path from its
Details page ( (More) > Display > Details). The path is reported in the EKM Object Properties
section of that page. You can then use Ctrl + C to copy the path to your clipboard, and Ctrl + V to
paste it into the script.
Note
• When creating a Python script, you may need to add an "r" when using raw inputs. Python may
interpret some characters differently (for example, "\n" for new line, or "\t" for tab). If a string
contains these values and you want it to be interpreted as raw input, add an “r” before the string.
For example, the string that contains a path in the following line contains characters that
may be misinterpreted by Python and result in an error:
data["externalFolderPath"] = "\\networkSharedPath\new folder"
Using Sample Scripts Supplied by EKM
Adding an “r” before the string (as shown in bold below) specifies that you want it to be
interpreted as raw input:
data["externalFolderPath"] = r"\\networkSharedPath\new folder"
• It is the responsibility of the script/journal creator to ensure that errors and warnings are properly
handled during script execution. Errors and warnings can be retrieved from the command object
after execution using the getErrorMessages() and getWarningMessages() methods.
The sample code snippet below shows the getErrorMessages() method being used:
import java.text.DateFormat as DateFormat
df = DateFormat.getDateTimeInstance()
cmd0 = ekm.getCommandObject("downloadToExternalFolderCommandObject")
cmd0.addModel(ekm.getObjectByPath(r"/Data/Shared Data/Sample Files/README.txt"))
data = {}
data["externalFolderPath"] = r"\\networkSharedPath\new folder"
cmd0.execute(data)
errMessages = cmd0.getErrorMessages()
size = errMessages.size()
if size>0:
errString = r""
for msg in errMessages:
error= errMessages[msg]+ r": "+ msg
errString = errString+ r"\n" + error
ekm.raiseException(errString)
12.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
/Data/Shared Data/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 Sample Files for more
details.
Note
The Sample Files folder is accessible only by admin users.
The scripts folder contains Python (p. 182) 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 on the
common /Administration/Configuration/Scripts page, 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.
12.4.1. Python Scripts

Some Python scripts are accessible from the /Data/Shared Data/Sample Files/conf/scripts
page. These include the following:
change_permissions_properties.py: Contains two methods. One method is to recursively

change the given object permissions for a given folder; the other method is to recursively change
the given properties for a given folder.
create_groups_users.py: Contains two methods. One method is to create groups and optionally
add users to those groups by reading group properties from a user-supplied csv file; the other
method is to create users by reading user properties from a user-supplied csv file.
create_remotefileserver_remoteitem.py: Contains two methods. One method is to
create a Remote File Server based on given inputs; the other method is to create a Remote Folder
based on given inputs including Remote File Server input.
extract_file_data.py: Extracts all data (metadata/details report/image) for a given file.
extract_file_data_recursively.py: Contains two methods. One method is to find all
objects of given types recursively from a given folder and re-extract metadata that failed to extract
initially; the other method is find all CAE files recursively from a given folder and generate and add
new report child objects for files in which report child objects are missing.
Recording Journal Scripts
test_script.py: 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.
12.5. Scripting Actions

Admin users can use the Scripting menu 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 (p. 183) from your user interface actions, execute
a journal script on-demand (p. 186), open a command window to dynamically run any Python or BeanShell
script (p. 188), and view a script error log (p. 193). These actions are described in the following sections.
12.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 (p. 183) process, perform a set of actions in the user interface
and then stop recording (p. 186). 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. 187).
Once the journal is created, you can execute it by clicking on the file, or right-clicking on it and selecting
Execute from the action menu. You can also choose to embed the script in a process template, lifecycle,
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 17.0. Support for journaling is
currently available for the following actions:
• Change Files Type
• Copy Report Action in a Simulation Details Report view for a CAE file (Copy Report Object)
• Configure > Accept Workspace Configuration
• Configure > Apply Workspace Configuration
• Configure > Begin Workspace Configuration
• Configure > Revert Workspace Configuration
• Delete Object
• Delete Multiple Objects (multiple objects selected)
• Edit > Alerts
• Edit > Copy/Paste (Copy Object)
• Edit > Created By Property (Change Creator)
• Edit > Custom Application (for Application objects)
• Edit > Cut/Paste (Move Object)
• Edit > EKM Server (for EKM Server objects)
• Edit > Get Exclusive Control (Lock)
• Edit > Group Membership (for Group 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 > Shortcut (Edit Link)
• 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
• Edit > Versioning > Checkin
• Edit > Versioning > Checkout
• Edit > Versioning > Create Branch
• Edit > Versioning > Get Copy Of Version
Recording Journal Scripts
• Edit > Versioning > Remove From Version Control
• Edit > Versioning > Undo Checkout
• Execute Batch
• Execute New DOE Run
• More > Create Shortcut
• More > Export Workspace
• New Connection to File/Folder on Remote Server
• New > (Child Type) (Add Catalog Content for a Catalog object)
• New > Custom Application
• 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
• Profile
• Remote Folder > synchronize
• Saved query > execute
• Settings > Alerts
• Settings > Preferences
• Synchronize (for Remote Folder objects)
12.6.1. Start Recording a Journal Script

To start recording a journal:
1. In the Administration section, select Scripting > Record Journal. The Start Journal Recording dialog
box appears:
Figure 12.1: Setting Up a Journal Recording
2. Click Browse to specify the folder where the journal file will be saved. The default location is /Data/My
Data.
3. Enter a name for the journal file.
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.
Note
If you start recording a journal on one browser tab, any journal-supported actions that you
perform on other browser tabs will be recorded in the same journal file.
12.6.2. Stop Recording a Journal Script

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

You can use the Run Journal File dialog box to execute any journal script of type EKM Journal (p. 274)
(.jou.py or .jou.bsh) on-demand. To open the dialog box, select Scripting > Run Journal File.
Example of Journal Recording and Execution
Figure 12.2: Running a Journal File
1. Click Browse to select the journal file.
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.
12.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.
Recording a Sample Journal

To record a journal in which preferences are set:
1. Start recording a journal file by selecting Scripting > Record Journal.
2. In the Start Journal Recording dialog, select the /Data/My Data folder as the save location, and then
specify Test Journal as the journal name. Click OK.
3. Click the user icon in the top right corner of the EKM window and select Settings.
4. In the Settings 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 selecting Scripting > Stop Recording Journal.
Testing the Sample Journal Script

To test the sample journal:
1. Click the user icon in the top right corner of the EKM window and select Settings.
2. In the Settings dialog box, click Restore Defaults (or return the list display preferences to their original
state). This should remove the Lifecycle Stage column from your file list display.
3. Select Scripting > Run Journal File.
4. 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.
12.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 Scripting > Open Command Window.
Running Python and BeanShell Scripts From a Command Window
Figure 12.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.
12.10. Testing or Debugging a Process Template

Admin users can write scripts to test and debug a process template. The following APIs are used to
accomplish this:
public interface ProcessObjectInterface extends ModelObjectInterface{
public void setVariableState(Map<String, Object> variableState);
public TaskInterface getTask(String taskName);
public Map<String, TaskInterface> getActiveTaskMap()();
public Map<String, Object> getVariableState();
public void reassignTask(String relativeTaskPath, String assignee, String assignmentNote);
public void setBreakpointTasks(List<String> taskNames);
public void removeBreakpointTasks();
}
public interface TaskInterface extends ModelObjectInterface{

public void complete();
public String getStatus();
public String getAssignee();
}
//ProcessTemplateNode
public interface ProcessTemplateTaskInterface extends TaskInterface {
public ProcessObjectInterface getNestedProcess();
}
//BatchNode
public interface BatchTaskInterface extends TaskInterface{
public String getJobStatus();
public boolean isJobStopped();
public void execute();
}
//Auto node
public interface AutoTaskInterface extends TaskInterface {
public void execute();
}
//Custom Dialog Node

public interface CustomDialogTaskInterface extends TaskInterface{
public Map<String, Object> executeMacro(String macroName);
}
Detailed documentation of the scripting interface is provided in the EKM_HOME/api folder. You can
use the scripting Command Window (p. 188) to input scripts for testing.
The examples below demonstrate how to use these APIs to test or debug a process template.
Manual Task
To launch a process template, use the API shown below. You need to specify the process template path,
process name and location, and required variables map.
########### Create Process Object using specified process template and required variables ##########
po = ekm.executeWorkflow("/Data/Shared Data/run-simulation.pt.xml", "test-run-simulation",
"/Processes/Process Monitor", {"Disciplines":["Flow"]})
########### Get all the active tasks and set variables state in process object ##########
activeTasks = po.getActiveTaskMap()
variableState = {"Mesh Quality":"Coarse", "Dimension 1":6.5,
"Geometry File":ekm.getObjectByPath("/Data/Shared Data/elbow.cas"), "Dimension 2":3.0,
"Mesh Folder":ekm.getObjectByPath("/Administration/Users/jsmith/My Data")}
po.setVariableState(variableState)
########### Get specified task and complete it with current variables state ###########
setupTask = activeTasks["Setup"]
setupTask.complete()
Testing or Debugging a Process Template
Batch Task
If a batch task is set to start automatically, it will do so if it is the first task in the process, or when the
prior task has been completed. You can launch a batch task and monitor the job’s progress using code
similar to that shown below.
In this snippet, the task is set to complete itself automatically (autoComplete is true).
######### Monitor batch task till the job and task itself gets completed #############
batchPreProcessTask = po.getTask("Batch Pre-process")
try:
while ((not batchPreProcessTask.isJobStopped()) or batchPreProcessTask.getStatus() != "active"):
batchPreProcessTask = ekm.getObjectById(batchPreProcessTask.getId())
if batchPreProcessTask == None :
break
except:
print "Batch task exceuted"
If autoComplete is false, you must explicitly mark the batch task as complete once the job is ex-
ecuted:
batchPreProcessTask.complete()
If autoStart is false, you must explicitly start the execution of batch task as follows:
batchPreProcessTask.execute()
If autoStart is true, you can specify the task as a breakpoint task. The process will not execute
further until the task is manually executed, either through a script or in the Process Monitor. Breakpoints
can be added as follows:
##########Even if autostart = true, task will not proceed#########
breakpointTasks = list()
breakpointTasks.append('Batch Pre-process')
po.setBreakpointTasks(breakpointTasks)
To remove all breakpoints, user needs to call po.removeBreakpointTasks().
Auto Task
Usually, auto tasks start executing automatically and complete themselves. You can, however, use
scripting to define a breakpoint task that allows you to review or update inputs before the task executes.
You can then execute the task manually using the Execute action in the Process Monitor or through
scripting.
po = ekm.executeWorkflow("/Data/Shared Data/Sample Files/process-templates/batch-monitor.pt.xml",
"test-batch-monitor", "/Processes/Process Monitor", {})
breakpointTasks = list()
breakpointTasks.append('solve')
po.setBreakpointTasks(breakpointTasks)
activeTasks = po.getActiveTaskMap()()
variableState = {"caseFile":ekm.getObjectByPath("/Data/Shared Data/test.xml), "count":3,
"outputFolder":ekm.getObjectByPath("/Data/Shared Data")}
setupTask = activeTasks["setup"]
setupTask.complete()
Once the setup task is complete, the solve task is created but will not execute automatically because it
is defined as a breakpoint task. Here you can review or update the variable state before the auto task
is executed. Once updated, the auto task can be executed as follows:
solveTask = po.getTask(solve)
solveTask.execute()
You can even complete the task without executing a macro by issuing:
solveTask.complete()
Custom Dialog Task

Custom dialog boxes can have buttons and links that execute macros. For example, the Next button
in a wizard can take you to the next wizard screen, while command links or buttons enable you to
perform actions. These macros can be run explicitly using the scripting API as follows:
po = ekm.executeWorkflow("/Data/Shared Data/Sample Files/process-templates/custom-dialog-node-process-templates
/test-features/test-features.pt.xml", "test-custom-dialog", "/Processes/Process Monitor", {})
task = po.getTask("Test Custom Dialog Workflow")
task.executeMacro("action")
You can complete the custom dialog task as follows:

task.complete()
This will execute the completion macro specified for the last step as well.
Process Template Task

For tasks that contain a nested process template, you can retrieve the nested process using:
task.getNestedProcess()
Once you have access to the process, you can complete the tasks contained within it. An example of
this is shown in the sample script below.
po = ekm.executeWorkflow("/Data/Shared Data/Sample Files/process-templates/nested-process-template
/main-process-template.pt.xml", "test-nested", "/Processes/Process Monitor", {})
activeTasks = po.getActiveTasks()
variableState = {"outerVariable":True}
beginTask = activeTasks["Begin"]
beginTask.complete()
nestedWorkflowTask = po.getTask("Nested Workflow")

nestedPO = nestedWorkflowTask.getNestedProcess()
nestedPO.getTask("Verify Variable").complete()
Reassignment Task
Current and/or future tasks in a process can be reassigned to other users.
In a process template that contains no nested templates, you can reassign a task using the reas-
signTask method in the ProcessObjectInterface API as follows:
po.reassignTask("End", "ekmadmin", "Please check mesh for approval")
In the example above, “End” is the task name, and “ekmadmin” is the user to whom the task is being
reassigned. The note "Please check mesh for approval" will be displayed when the task is
reassigned.
If a process template has another process template nested inside of it, and you want to reassign a task
that resides in the nested template, you must specify the path to the task within the sequence of tasks,
as shown in the example below:
po.reassignTask("Nested Workflow/Run Simulation/Approve Mesh", "ekmadmin", "Please check mesh for approval")
Viewing a Script Error Log
In this example, Nested Workflow, Run Simulation and Approve Mesh are the sequential
tasks in a nested process template, and Approve Mesh is the task that is being reassigned.
Once a task has been reassigned, the target user must sign in to EKM and accept the task to be able
to complete it. This is accomplished using the accept method, as shown in the example below.
po = ekm.executeWorkflow("/Data/Shared Data/run-simulation.pt.xml", "test-run-simulation", "/Processes/Process Monit
task=po.getTask("Setup")
po.reassignTask("Setup", "ekmadmin", "dummy note")
ekm.login("ekmadmin")
task.accept()
12.11. Viewing a Script Error Log

Job templates, process templates, custom applications, custom actions, custom views, and other macros
such as initializeMacro, propertyUpdateMacro and customStatusFlagsMacro, may use
scripts to automate certain tasks. When a script fails to execute, any errors that have occurred are cap-
tured in a log.
If you have added debug statements to a script using print, the output of those statements will get
captured in the log as well.
To view the script error log, go the Administration section and select Scripting > Show log.
By default, the Script log dialog box displays the debug messages and error messages that were dis-
played in the interface when the errors occurred. To view more details about the error, enable the Show
error details check box. This may help you identify the source of an error.
Errors will continue to be added to the log as they occur. To reduce the amount of content shown in
the log, disable the Show error details check box.
To download the log to an HTML file so that it can be viewed and shared externally, click Download
as HTML.
Note
• A maximum of 100K characters can be captured in the log. When that limit has been reached,
content is no longer added.
• The log captures errors in the current session only, and is emptied when the session ends.
Chapter 13: 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.
Contents include:
13.1. Defining Custom Dialog Boxes
13.2. Defining and Using Custom Applications
13.3. Creating a Custom Application
13.4. Executing a Custom Application
13.5. Modifying an EKM Application
13.1. Defining Custom Dialog Boxes

EKM enables you to create custom dialog boxes for use within EKM. 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.
• Job Execution: When defining a job template, you can specify that you want a custom interface to be dis-
played when that template is used to execute a batch job.
• Process Templates: By default, EKM shows an automatically generated dialog box for task 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 task 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.
Note
In custom dialog boxes that involve job execution, only batch jobs are supported. Interactive
jobs are not supported.
There are two aspects to defining a custom dialog box:
• Defining the interface (p. 196) in an XHTML file
• Defining the steps and variables (p. 205) in a macro
Defining Custom Dialogs, Wizards and Applications
13.1.1. Defining a Custom User Interface

EKM's user interface is designed using web technologies such as XHTML (p. 197) 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, process template, job template, or custom application is invoked.
• XHTML: Dialog boxes are defined using XHTML syntax. See XHTML Files (p. 197) 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 built-in 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 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 20–1.1, and RichFaces 4.2.2. Refer to http://my-
faces.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.
Defining Custom Dialog Boxes
Figure 13.1: A Faulty Error Message in a Custom Application
– Variable names used in a custom application should always be a valid java identifier. For ex-
ample, a variable cannot have a name that is a reserved word such as "boolean".
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.
13.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 (p. 198)
• body (p. 198)
• footer (p. 198)
Sample XHTML Code for a Custom Dialog Box (p. 198) contains a full listing for an XHTML file for a
sample custom dialog box. Figure 13.2: Sample Custom Dialog Box (p. 199) 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:
<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:rich="http://richfaces.org/rich"
xmlns:a4j="http://richfaces.org/a4j"
xmlns:ing="http://www.ansys.com/ingress/spdm">
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. 201) for details.
Footer
An XHTML must end with the footer:
</ui:component>
</body>
</html>
13.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 13.2: Sample Custom Dialog Box (p. 199).
The dialog box uses common user interface components (p. 201) 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 13.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">
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>
</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>
</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>
13.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 (p. 198) of the XHTML file. Refer to Sample XHTML Code for a Custom Dialog
Box (p. 198) for the full listing of the XHTML file that generates the sample dialog box shown in Fig-
ure 13.2: Sample Custom Dialog Box (p. 199).
13.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 13.2: Sample Custom Dialog Box (p. 199)) 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.
13.1.1.3.2. Embedded Images

The graphicImage setting can be used to embed an image in an interface. 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 (p. 205) in the custom re-
sources 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 13.2: Sample Custom Dialog Box (p. 199)), tank.jpg is at the top-
level of the resources folder, so the full path becomes: #{custom.url}/tank.jpg.
If you want to display an image that resides in the EKM repository, see Linked Images (p. 201).
13.1.1.3.3. Linked Images

The image component can be used to display an image that resides in the EKM repository. You can
include this component by adding the <ing:image> tag to the markup. If doing so, you must ensure
that the ing namespace is defined in the XHTML file.
This component can have the following attributes:
path: specifies the path of the image file. It can be a JSF EL expression such as #{custom.vars.im-
agePath}, or an absolute value such as /Data/Shared Data/image.gif.
style: can be used to define a style for the image. For example, you may want to display a colored
border around it, as shown in the sample below.
<ing:image path="/Data/Shared Data/test.gif" style="border:1px solid green"/>
13.1.1.3.4. Object Links

The objectLink component can be used to display a link to an object in the EKM repository. Clicking
on the link displays the object in its default view. You can include this component by adding the
<ing:objectLink> tag to the markup.
This component can have the following attributes:
path: specifies the path of the object. It can be a JSF EL expression such as #{cus-
tom.vars.path}, or an absolute value such as /Data/Shared Data.
style: can be used to define a style for the link.
styleClass: refers the CSS class to be applied to link.
value: can be used to specify the link text. If not specified, the object name is used for the link
text, with the object path shown in a tooltip.
<ing:objectLink path="/Data/Shared Data" styleClass="facesCommandLink" value="Click here for Shared Data"/>
13.1.1.3.5. 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 (p. 205) 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 (p. 205). In this case the
name of the variable is string.
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 (p. 205), 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 (p. 205). 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 (p. 205). 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
it’s 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 (p. 205). 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 (p. 205). 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:
<ing:inputCustomReference size="60" referenceVar="reference"/>
The referenceVar attribute specified the name of the reference variable defined in the dialog box’s
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 (p. 205). In this case the name of the variable is file.
13.1.1.3.6. 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 (p. 205). For the example
dialog box (Figure 13.2: Sample Custom Dialog Box (p. 199)) the name of the variable is boolean.
13.1.1.3.7. 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 (p. 205). For the example
dialog box (Figure 13.2: Sample Custom Dialog Box (p. 199)), 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 box’s macro. See Selection Menu for an example of the
f:selectItems tag.
13.1.1.3.8. 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 box’s 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 box’s macro.
<h:selectOneMenu value="#{custom.vars.menu.value}">
<f:selectItems value="#{custom.vars.menu.optionItems}"/>
</h:selectOneMenu>
In this case the name of the variable is menu.
13.1.1.3.9. 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 (p. 205). 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 box’s macro. See Selection Menu for an example of
the f:selectItems tag.
13.1.1.4. Invoking Methods from UI Components

You can use #{custom.dialog} to retrieve the current information from a view associated with a
custom application or process, and then invoke an API method such as executeMacro directly from
the XHTML components. For example, #{custom.dialog.executeMacro('<macro name>')}
can be used as an action for a commandLink or commandButton component. For job templates you
can use #{custom.executeMacro('<macro name>')} to execute a macro.
In the example below, when a user clicks an Update command link next to an input box, the macro
testMacro (specified in the script) is executed. This macro updates the value of the variable test-
String. After the macro is executed, the input box is rendered again to display the updated value,
New Value.
<h:inputText value="#{custom.vars.testString.value}" id="inputText"/>
<a4j:commandLink id="testLink" action="#{custom.dialog.executeMacro('testMacro')}"
render="inputText" value="Update"/>
<h:inputText class="submitXMLData" value="#{custom.dialog.vars.xmlData.value}" style="display:none"/>
The testMacro definition is as follows:

def testMacro(dialog):
dialog.getVar("testString").setValue("New value")
13.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.
Defining Steps
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);
}
The name of the macro is init and it takes a single argument dialog box that is an instance of Dia-
logInterface.
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. Process templates and custom applications can be added or modified
dynamically to EKM by any user who may or may not have access to EKM server’s file system. EKM
handles this issue in the following ways:
• The user interface resource files needed for custom applications and process templates are added as
an archive (in .zip, .tar, or .tar.gz formats).
• The resources archive is made a child of the process template 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-the-
object
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 process templates 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 process template 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/test-variables.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.
Defining Variables
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);
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 multi-
valued 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 Calen-
dar.getInstance().getTime(). For VARIABLE_TYPE_FILE the default must be null. For multi-
valued 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 VariableIn-
terface. You can use this instance to specify some additional attributes that can’t be specified in the
addVar() method. For example, for reference variables you can specify the type of objects to be se-
lected 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);
13.1.3. Example: Creating a Custom Interface for Fluent Batch Jobs

This example shows you the code used and steps taken to create a custom interface that will be incor-
porated into a job template. When a user executes the job template, the following custom dialog box
will be displayed:
Figure 13.3: Custom Dialog Box for Fluent Batch Jobs
To create a custom interface to be used in a job template, you must perform two main tasks:
1. Define the components of the interface in an XHTML file.
2. Define a script with an initial macro, action macro, and ajax macro (if required).
Step 1: Define the XHTML Code

The XHTML code shown below can be used to define the components of the interface shown in Fig-
ure 13.3: Custom Dialog Box for Fluent Batch Jobs (p. 208): The code consists of style classes, java script,
and a mix of JSF, facelets, tomahawk, richfaces and some built-in EKM component tags.
xmlns:rich="http://richfaces.org/rich"
xmlns:a4j="http://richfaces.org/a4j"
xmlns:ing="http://www.ansys.com/ingress/spdm">
<body>
<ui:component>
<script>
function showHideCores() {
if(document.forms['actionForm']['actionForm:processingRadio'][0].checked == true ){
document.getElementById('numberOfCoresDiv').style.display='none';
}
else if(document.forms['actionForm']['actionForm:processingRadio'][1].checked == true ){
document.getElementById('numberOfCoresDiv').style.display='block';
}
}
</script>
<div style="height:100%; width:100%; min-height:330px; min-width:400px">
<h:graphicImage value="#{custom.url}/images/launcher.jpg" style="width:99%; padding-top:5px;"/>
<div style="float:left; padding-top:8px; width:49%">
<h:outputText value="Dimension" style="padding-bottom: 2px"/>
<h:selectOneMenu id="dimensionDropDown" value="#{custom.vars.dimension.value}">
<f:selectItem id="_2dDimension" itemLabel="2D" itemValue="2d" />
<f:selectItem id="_3dDimension" itemLabel="3D" itemValue="3d" />
<f:ajax render="doublePrecisionCheckbox" listener="#{custom.executeMacro('setDoublePrecisionValue')}"
event="change" execute="@form"/>
</h:selectOneMenu>
</div>
<div style="float:right; padding-top:8px; width:49%;">
<h:outputText value="Options" style="padding-bottom: 2px"/>
<div>
<h:selectBooleanCheckbox id="doublePrecisionCheckbox" value="#{custom.vars.doublePrecision.value}"
style="float:left;padding-right:5px"/>
<h:outputText value="Double precision" style="float:left; padding-top:3px"/>
</div>
</div>
<div style="clear:both">
<div style="float:right; padding-top:10px; width:49%">
<h:outputText value="Processing options" style="padding-bottom: 2px"/>
<h:selectOneRadio id="processingRadio" value="serial" onchange="showHideCores()" >
<f:selectItem id="serial" itemLabel="Serial" itemValue="serial" />
<f:selectItem id="parallel" itemLabel="Parallel" itemValue="parallel" />
</h:selectOneRadio>
<div id="numberOfCoresDiv" style="padding-top:4px; margin-left:10px; display:none; ">
<h:outputText value="Number of processes" style="padding-bottom: 2px"/>
<t:div>
<rich:inputNumberSpinner id="numberOfCores" value="#{custom.vars.cores.value}" inputSize="1"
style="margin-top:5px; padding-left:15px"/>
</t:div>
</div>
</div>
</div>
<div style="float:left; width:98%;padding:3px 0px">
<div style="padding-top:5px; width:100%;clear:both; ">
<h:outputText value="Use journal file" style="float:left; padding-top:2px"/>
<t:div id="journalFileDiv" style="float:left;">
<t:div id="innerJournalFileDiv">
<ing:browseWorkingDirectory value="#{custom.vars.journalFile}" width="99%" id="journalFile"
render="innerJournalFileDiv"/>
</t:div>
</t:div>
</div>
</div>
<div style="width:98%; padding-top:8px; clear:both;">
<h:outputText value="Other commandline options" style="float:left; width:100%;"/>
<h:inputText id="otherCommandLine" value="#{custom.vars.otherCommandLine.value}" style="float:left;
width:100%; margin-top:2px"/>
</div>
<t:div id="queuesDiv" style="width:99%; padding-top:8px; clear:both;">
<h:outputText value="Queues" style="float:left; width:100%;"/>
<ing:selectQueue value="#{custom.vars.queue}" hasAppKey="#{custom.vars.appKey.value}" style="width:100%"/>
</t:div>
<t:div id="commandLineDiv" style="padding-top:10px; float:right;">
<ing:viewCommandLine label="Command line"/>
</t:div>
</div>
</ui:component>
</body>
</html>
In addition to components described in Defining a Custom User Interface (p. 196), the following built-in
EKM components are used:
Queue Selector Component
This built-in component shows a list of available queues. To following code is used to add the Queues
drop box to the interface:
<ing:selectQueue value="#{custom.vars.queue}" hasAppKey="#{custom.vars.appKey.value}" style="width:100%"/>
Required attributes:
• value. The variable for the queues defined by the user in the initial macro. In this example, a queue variable
whose type is QueuesVariableInterface is defined in the initial macro.
• hasAppKey. The application key for which queues need to be found. This variable is defined in the initial
macro. In this example, an appKey variable is defined in the initial macro.
Optional attributes:
• style. The CSS style definition to be applied to the component.
• styleClass. The CSS class to be applied to the component. If not defined, the default EKM style is applied.
• id. A unique identifier for this component. The value must be unique within the closest naming container.
File Selector Component
This built-in component enables the user to browse the working directory on the server and select an
input file. It consists of an input box and browse button. When a file/folder is selected it will be shown
in the input box. The following code is used to add the file selector component to the interface:
<ing:browseWorkingDirectory value="#{custom.vars.journalFile}" width="99%" id="journalFile"
render="innerJournalFileDiv"/>
Required attributes:
• id. An identifier for the component.
• value. The variable for the journal file defined in the initial macro. In this example, a journalFile variable
whose type is ServerFileVariableInterface is defined in the initial macro.
• width. The width of the component.
• render. A comma-separated list of component ids that will be rendered after clicking a node in the tree.
Command Line Component
This built-in component enables the user to view the command line. When the user clicks the View
Command Line link, a pop-up box will be displayed that shows the current command line. The following
code is used to add the command line component to the interface:
<ing:viewCommandLine label="Command line"/>
Optional attributes:
• linkStyle. The CSS style definition to be applied to the link.
• linkStyleClass. The CSS class to be applied to the link. If not defined, the default EKM style is applied.
• popupStyle. The CSS style definition to be applied to the pop-up box.
• popupStyleClass. The CSS class to be applied to the pop-up box. If not defined, the default EKM style is
applied.
• id. A unique identifier for the component. The value must be unique within the closest naming container.
• label. The text of the link.
Step 2: Define Macros

To define the functionality of the custom interface, you must define a script that contains the following
macros:
• An initial macro
• An action macro
• An ajax macro (if required)
You can define the macros on the Script tab of the Edit Job Template dialog box when creating the
job template in which the custom interface will be used. See Creating a Custom Job Template in the
User’s Guide for more information.
Defining the Initial Macro
The initial macro specifies the following:
• The name of the XHTML file that defines the content of the custom interface
• The name of the action macro that is used when the Execute button is clicked in the Start Job dialog box
• The variables used to store inputs specified by the user in the custom interface
def init(ui, jobTemplate):
ui.setCustomUi("ui/fluent_launcher.xhtml")
ui.setActionMacro("action")
ui.addVar("dimension", ui.VARIABLE_TYPE_STRING, "2d", False)

ui.addVar("doublePrecision", ui.VARIABLE_TYPE_BOOLEAN, False, False)
ui.addVar("cores", ui.VARIABLE_TYPE_STRING, "1", False)
journalFile=ui.addVar("journalFile", ui.VARIABLE_TYPE_SERVER_FILE, "", False)
journalFile.setFilterTypes("jou")
ui.addVar("otherCommandLine", ui.VARIABLE_TYPE_STRING, "", False)
appKeyVar=ui.addVar("appKey", ui.VARIABLE_TYPE_STRING, "", False)

defaultAppKey=jobTemplate.getAppKey()
appKeyVar.setValue(defaultAppKey)
queueVar=ui.addVar("queue", ui.VARIABLE_TYPE_QUEUE, "", False)

queueOptions=[]
selectableQueues=jobTemplate.getSelectableQueues()
for queue in selectableQueues:
if queue not in queueOptions:
queueOptions.append(queue)
queueVar.setSelectableQueues(queueOptions)
The name of the initial macro is init. It has two arguments:
• ui. An instance of CustomUiInterface
• jobTemplate. An instance of JobTemplateInterface
The first line specifies the location of the XHTML file:

ui.setCustomUi("ui/fluent_launcher.xhtml")
The argument is the path of the XHTML file that defines the content of the custom interface. The location
of the XHTML file (and other resource files such as images, CSS files, JavaScript files, and so on) is dictated
by the customResourcesPath setting in the ekm.xml file, which by default is set to
EKM_HOME/conf/resources. The XHTML file 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. Job templates can be added to
EKM by any user who may or may not have access to the EKM server’s file system. EKM handles this issue
in the following ways:
• The resource files needed for the custom interface are added the job template as an archive (in .zip, .tar,
.tar.gx or .tgz format).
• The resource archive becomes a child of the job template object in EKM.
• When a custom interface needs to be opened, the resource archive is extracted to the following location:
<path to custom resources folder>/_custom_resource_cache_/<id of object>
where <id of object> is the internal ID of the object in EKM.
Because you do not know the ID of an object before it has been added to EKM, you cannot use an ab-
solute path to specify the location of the XHTML file. When you specify a relative path, EKM will create
the full path behind the scenes before the dialog box is opened. If the XHTML 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 include the parent folder in the path (for example,
folder-name/test-variables.xhtml).
The second line specifies the action macro that will be called when the Execute button is clicked in
the Start Job dialog box.
ui.setActionMacro("action")
When the initialization is complete, you can then add the variables used in the interface. This is done
using the addVar () method of the CustomUiInterface as shown in the following line:
ui.addVar("dimension", ui.VARIABLE_TYPE_STRING, "2d", False)
The arguments are as follows:
1. The name of the variable
2. The type of variable
3. The default value of the variable
4. Whether or not the variable is multi-valued
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
The default value must be an instance of the java.util.Date class. You can set the default to
the current time by calling Calendar.getInstance().getTime().
• VARIABLE_TYPE_FILE: For files that are uploaded to EKM
The default value must be null.
• VARIABLE_TYPE_QUEUES: For specifying the queues
To use the Queues drop-down box as defined in the Example: Creating a Custom Interface for Fluent
Batch Jobs (p. 210) section, you must add a variable of type VARIABLE_TYPE_QUEUE in the initial
macro:
queueVar=ui.addVar("queue", ui.VARIABLE_TYPE_QUEUE, "", False)
queueOptions=[]
selectableQueues=jobTemplate.getSelectableQueues()
for queue in selectableQueues:
if queue not in queueOptions:
queueOptions.append(queue)
queueVar.setSelectableQueues(queueOptions)
This will create a variable of type QueuesVariableInterface. Optionally, you can get the list of
selectable queues as defined in the job template using the setSelectableQueues() method. If
the list of selectable queues is also specified for the queues variable, only the selectable queues
containing the application will be shown in the drop-down list.
• VARIABLE_TYPE_TABLE: For tables
• VARIABLE_TYPE_SERVER_FILE: For selecting a file from the server
To use the server file selection component defined in the Example: Creating a Custom Interface for
Fluent Batch Jobs (p. 210) section, you must add a variable of type VARIABLE_TYPE_SERVER_FILE in
the initial macro:
journalFile=ui.addVar("journalFile", ui.VARIABLE_TYPE_SERVER_FILE, "", False)
journalFile.setFilterTypes("jou")
This will create a variable of type ServerFileVariableInterface. Optionally, you can specify
a comma-separated list of file types using the setFilterTypes() method. If filter types are spe-
cified, only files of those type in the working directory will be shown in the tree.
For multi-valued variables, the default value must be a list. For example:
ui.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.
Defining the Action Macro
An action macro is called when the user clicks Execute in the Start Job dialog box. This macro processes
user inputs and executes commands. The code for the tutorial example is shown below.
def action(ui, jobTemplate):
jobTemplate.addParam("-hidden")
defaultAppKey=jobTemplate.getAppKey()
jobTemplate.setAppKey(defaultAppKey)
dim= ui.getVar("dimension").getValue()
precision=ui.getVar("doublePrecision").getValue()
if precision:
precisionString="dp"
else:
precisionString=""
if dim:
jobTemplate.addParam(dim+precisionString)
journalFile=ui.getVar("journalFile").getValue()
if journalFile:
jobTemplate.addParam("-i")
jobTemplate.addParam(journalFile)
cores= ui.getVar("cores").getValue()
if cores:
jobTemplate.addParam("-t")
jobTemplate.setCores(int(cores))
jobTemplate.addParam(cores)
otherCommandLine= ui.getVar("otherCommandLine").getValue()
if otherCommandLine:
jobTemplate.addParam(otherCommandLine)
queue=ui.getVar("queue").getValue()
if queue:
jobTemplate.setQueue(queue)
The name of the macro is action. It has two arguments:
• ui. An instance of CustomUiInterface
• jobTemplate. An instance of JobTemplateInterface
You must update the values in JobTemplateInterface; in other words update the job execution
settings with the values specified in the variables of CustomUiInterface. The updated job settings
will be used to execute the job.
Defining the Ajax Macro
An ajax macro is used to partially update the interface when a user interacts with it. For example, if the
user enables a check-box or radio button, you may need to re-render a portion of the interface so that
different content is displayed.
You can define an ajax macro for any component specified in the XHTML file using the f:ajax tag of
jsf, as shown below:
<f:ajax render="componentId1, componentId2" listener="#{custom.executeMacro('ajaxMacro')}"
event="change" execute="@form"/>
The executeMacro method of CustomUiInterface has a single String argument, which is the
name of the ajax macro. In this example the name of the macro is ajaxMacro and it has a single ar-
gument, ui, that is an instance of CustomUiInterface. You can change the value of any variable
in CustomUiInterface using another variable and render the corresponding component again to
see the changes.
Defining and Using Custom Applications
Final Step: Adding the Custom Interface to the Job Template

When the XHTML file and macros have been defined, you can incorporate the custom interface into
the job template by following these steps:
1. Save the XHTML file and all required resource files in an archive file (.zip, .tar, .tar.gz or .tgz) on
your local computer. In this example, the name of the resource archive is Fluent Launcher.zip.
2. In the Edit Job Template dialog box, select the UI tab, and specify the name of the initial macro (for ex-
ample, init) and the location of the resource archive, as shown below:
For more information, see Using a Custom Interface for Job Execution in the User’s Guide.
13.2. Defining and Using Custom Applications

Follows these steps to create and use custom applications:
1. Create custom application files in a scripting language (p. 179) or in Java that defines the application. For
a script-based application, this will include back-end logic for executing the application as well as a resource
archive for defining the front-end user interface.
2. Create a new application for the custom application files by selecting (New) > Custom Application on
the Home/My Applications or Administration/Shared Applications page (if accessible). 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 (p. 274) type object and placed in the folder you specified.
3. Click on an application to execute it. The dialog box that is defined for the application will open, allowing
you to input values.
13.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-tank-
simulation.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 Custom Application action is only available to admin users.
To create a custom application:
1. Go to Home/My Applications or Administration/Shared Applications and select (New) > Custom

Application.
This will open the Create Custom Application dialog box.
Figure 13.4: Creating a Custom Application
2. In the Application name edit box, type Mixing Tank Simulation.
Executing a Custom Application
3. Click under Application folder to select the repository folder where you would like to save
the application. For easy access you may want to save it in the /Home/My Applications folder or
the /Administration/Shared Applications folder.
4. Click under Script file to select a script file for the application. Select the sample mixing-
tank-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
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 mixing-tank-
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.
13.4. Executing a Custom Application

To execute a custom application, navigate to the folder where it is stored and click on it. You can also
right-click the application and select Execute from the context menu.
You can also click to display the Application launcher, and launch the custom application from
there.
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 13.5: Custom Mixing Tank Simulation Dialog Box (p. 218) 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).
Figure 13.5: Custom Mixing Tank Simulation Dialog Box
A job object is created for the simulation process in the Job Monitor, 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 13.6: Report for Custom Mixing Tank
Simulation (p. 219).
Modifying an EKM Application
Figure 13.6: Report for Custom Mixing Tank Simulation
13.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.
To edit a custom application:
1. Go to the location where the custom application is saved (for example, Home/My Applications or Ad-
ministration/Shared Applications), and then right-click the application and select Edit > Application.
This opens the Edit Custom Application dialog box.
Figure 13.7: Editing a Custom Application
2. To select a new script file, or reload the script file if it has changed, click under Script file.
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.
Chapter 14: EKM Connector End User API
The EKM Connector End User API is a library that can be used to develop client applications that interact
with an EKM repository. The programs can be developed in Java, C#, or Python. Python programs must
be executed using either the Jython or IronPython interpreter. You can develop applications to:
• Search the repository for data.
• Create, update, and delete objects in the repository.
• Transfer files and folders to and from the repository.
• Perform version control and locking operations on objects in the repository.
• Trigger execution of scripts in the repository.
• Manage users and groups in the repository.

14.1. Installing the API Library
14.2. Using the Library in Client Applications
14.3. Submitting and Monitoring Jobs
14.4. Building and Running a Java Application
14.5. Running a Python Script Using Jython
14.6. Writing and Running a Python Script Using IronPython
14.7. Building and Executing C# Sample
14.8. API Documentation
14.1. Installing the API Library

The EKM Connector End User API library is installed along with the EKM server product. Under the EKM
installation directory, the following directories are provided for the library:
EKM_ROOT170/ekm-client - the home directory for the library

EKM_ROOT170/ekm-client/bin - scripts for running Jython and for building and running the
included Java samples
EKM_ROOT170/ekm-client/lib - Java and C# libraries
EKM_ROOT170/ekm-client/programs - additional programs needed to build and run the Java
samples
EKM_ROOT170/ekm-client/samples/CSSamples - example application written in C#
EKM_ROOT170/ekm-client/samples/ironpython - example applications written in Python
for execution using IronPython
EKM_ROOT170/ekm-client/samples/java - example applications written in Java
EKM_ROOT170/ekm-client/samples/jython - example applications written in Python for
execution using Jython
EKM_ROOT170/ekm-client/schema - schema files
After the installation is complete, do the following to build and run the Java and Jython examples:
EKM Connector End User API
1. Open EKM_ROOT170/ekm-client/bin/ekm_env script in an editor.
2. Change the EKM_BASE environment variable to EKM_ROOT170, where EKM_ROOT170 is the directory
in which the ekm-client directory resides.
3. Change the JAVA_HOME environment variable to point to the JDK installation.
4. Add the EKM_ROOT170/ekm-client/bin directory to the path.
5. On Unix machines, use the chmod command to make all of the .sh files in EKM_ROOT170/ekm-cli-
ent/bin executable.
6. On Unix machines, use the chmod command to make the ant script in EKM_ROOT170/ekm-cli-
ent/programs/apache-ant-1.9.1/bin executable.
Once this has been done, the samples can be built and run in place on the server where the library was
installed.
Installing the Library on a Client Machine

Follow the steps below to install the library on a client machine.
1. Copy the ekm-client directory from the server install to a location on the client machine. The only
prerequisite for the client machine is that it has the Java Development Kit (JDK) version 1.8.0_40 or later
installed on it.
2. Open EKM_ROOT170/ekm-client/bin/ekm_env script in an editor.
3. Change the EKM_BASE environment variable to the directory in which you placed the ekm-client
directory.
4. Change the JAVA_HOME environment variable to point to the JDK installation on the client machine.
5. Add EKM_ROOT170/ekm-client/bin to your PATH.
6. Save your changes.
7. On Unix machines, use the chmod command to make all of the .sh files in EKM_ROOT170/ekm-cli-
ent/bin executable.
8. On Unix machines, use the chmod command to make the ant script in EKM_ROOT170/ekm-cli-
ent/programs/apache-ant-1.9.1/bin executable.
Testing the Installation

To test the installation, follow the steps below.
1. Execute the jython script in EKM_ROOT170/ekm-client/bin. This should open a jython console. For
example:
Jython 2.5.3 (2.5:c56500f08d34+, Aug 13 2012, 14:48:36)
[Java HotSpot(TM) 64-Bit Server VM (Oracle Corporation)] on java1.8.0_40
Type "help", "copyright", "credits" or "license" for more information.
>>>
2. At the prompt, enter the following commands:
Using the Library in Client Applications
>>> from com.ansys.ingress.client.api import ConnectionFactory

>>> conn = ConnectionFactory.open("http://host:port", "user", "password")
The first command imports the ConnectionFactory class into the interpreter. The second
command opens a connection to the EKM server. In the second command, replace host:port
with the hostname and port number of the EKM server (for example, http://localhostmyekmserv-
er.mycompany.com:8080), user with the EKM username, and password with the EKM user’s
password. After entering the open command, you should see something similar to the following
in the interpreter:
ConnectionFactory.open("http://ekmserver:8080", "ekmuser", "Ekmpass123!")
09:46:21,874 DEBUG RepositoryConnectionManager:? - Open started: Default @ ekmserver[http://ekmserver:8080/,De
09:46:23,880 INFO RemoteRepositoryAdapter:? - Using cache: false
09:46:23,997 DEBUG RepositoryConnectionManager:? - Open completed
This indicates the installation was successful and you are now connected to the EKM server.
3. Close the connection before exiting the interpreter.

>>> conn.close()
09:46:38,592 DEBUG RepositoryConnectionManager:? - Connection closed: Default @ ekmserver[http://ekmserver:808
14.2. Using the Library in Client Applications

The following sections describe how to use the library in C#, Java, and Python. This includes covering
the various features of the API. There are some differences in the library depending on which language
is being used.
First, method names in the library follow the standard coding style for each language.
Java
Methods are camelcase and start with lowercase letters. For example, findByPath
C#
Methods are camelcase and start with uppercase letters. For example, FindByPath
Accessing attributes of objects also follows standard conventions for each language.
Java
Attribute values are retrieved using “getter” methods. For example, someObject.getPath()
Attribute values are assigned using “setter” methods. For example, someObject.setName(“foo”)
C#
Attribute values are retrieved by name or “getter” methods. For example, someObject.Path or someOb-
ject.getName()
Attribute values are set using assignment or “setter” methods. For example, someObject.Name =
“foo” or someObject.setValue(“foo”)
The Python code reflects these differences depending on whether the interpreter uses Java (Jython) or
.NET (IronPython).
14.2.1. Opening and Closing a Connection

As described above, the first thing an application must do is open a connection to the server. When
doing this, the application must provide the address (host and port) of the server where EKM is running,
the username, and password of the user logging into EKM. After the connection is opened, the applic-
ation can make use of the library’s functionality to access and manage data on the server. The one thing
the application should always do when exiting is close the connection. This will ensure that a license
acquired by the user is released.
The following examples show how to open and close a connection:
Java
package samples.java;
import com.ansys.ingress.client.api.Connection;
import com.ansys.ingress.client.api.ConnectionFactory;
public class OpenCloseConnection {
public static void main(String[] args) throws Exception {

Connection conn = null;
try {
conn = ConnectionFactory.open(
"http:// ekmserveraddr:8080", // Host URL
"ekmadmin", // User ID
"Adminuser123!" // Password
);
System.out.println(">>>>> Connection " + conn + " opened");
} finally {
if (conn != null) {
conn.close();
}
System.out.println(">>>>> Connection " + conn + " closed");
}
}
Python (Jython)
from com.ansys.ingress.client.api import ConnectionFactory
if __name__ == "__main__":
conn = None
try:
conn = ConnectionFactory.open(
"http://ekmserveraddr:8080", # host
" ekmadmin " , # username
" Adminuser123!") # password
print ">>>>> Connection " + str(conn) + " opened"
finally:
if conn:
conn.close()
print ">>>>> Connection " + str(conn) + " closed"
Python (IronPython)
# Load EKM assemblies
import client_init
if __name__ == "__main__":
conn = None
try:
# Change the username and password below as needed
conn = ConnectionFactory.Open(
"http://ekmserveraddr:8080", # host
"ekmadmin", # username
"Adminuser123!") # password
print ">>>>> Connection " + conn.GetName() + " opened"
finally:
if conn:
conn.Close()
print ">>>>> Connection " + conn.GetName() + " closed"
C#
Connection conn = null;
try
{
//
// Modify the workspace, user name, and password to reflect
// the actual EKM server you are using.
///
"http://ekmserveraddr:8080", // Host URL
"ekmadmin", // EKM user
"Adminuser123!" // User's password
);
Console.WriteLine(">>>> Connection " + conn.GetName() + " opened");
}
finally
{
if (conn != null)
{
conn.Close();
Console.WriteLine(">>>> Connection " + conn.GetName() + " closed");
}
}
}
14.2.2. API Interfaces

Once a connection is established, the Connection object provides access to a number of interfaces for
interacting with the server. These interfaces are:
• AdministrationManager – provides methods for managing users and groups, interacting with a user’s recycle
bin, and query the server for configuration data
• DataManager – provides methods for managing data on the EKM server. This includes uploading and
downloading files and folders.
• JobManager – provides methods for managing jobs
The Connection object has methods for getting each of these interfaces. For example, to get the
DataManager in Java, you invoke getDataManager on the Connection object.
Java
DataManager dm = conn.getDataManager();
Python (Jython)
dm = conn.getDataManager()
Python (IronPython)
dm = conn.GetDataManager()
C#
DataManager dm = conn.GetDataManager();
14.2.3. Searching the EKM Repository

The DataManager interface provides a number of ways for searching the EKM repository for data. These
are:
• Search for a specific object by its path
• Search for a specific object by its unique identifier
• Search for all objects that have a property containing a specific keyword
• Search for objects using an existing saved query on the server
• Search for objects using a query created on the client.
Each of these operations returns one or more instances of a ModelObject. The ModelObject is a
representation of the object stored in the EKM repository.
Searching for an Object by its Path

The simplest search provided is to search for an object by its path. The examples below show this op-
eration.
Java
DataManager dm = conn.getDataManager()
ModelObject object = dm.findByPath("/Data/Shared Data");
Python (Jython)
dm = conn.getDataManager()
object = dm.findByPath("/Data/Shared Data")
Python (IronPython)
object = dm.FindByPath("/Data/My Data/My Projects")
C#
DataManager dm = conn.GetDataManager()
ModelObject obj = dm.FindByPath("/Data/Shared Data");
Searching for an Object by its Unique Identifier

Each object stored in the EKM repository has a unique identifier that can also be used when searching
for an object. The following shows this operation:
Java
ModelObject object = dm.findByID("d23ae05b-3a07-446c-a052-1eae22ce06ec");
Python (Jython)
object = dm.findByID("d23ae05b-3a07-446c-a052-1eae22ce06ec");
Python (IronPython)
object = dm.FindByID("d23ae05b-3a07-446c-a052-1eae22ce06ec");
C#
ModelObject obj = dm.FindById("d23ae05b-3a07-446c-a052-1eae22ce06ec");
Searching for Objects by Keyword

Multiple objects can be located by searching the repository for objects containing specific keywords.
When using this type of search, every property of every object in both the /Data/Shared Data
folder and the user’s /Data/My Data folder is searched to see if they contain the keyword. For example,
if searching for the keyword “test”, any object that has the keyword in its name, description, or any
other property would be returned. The following code snippets show this operation and how to iterate
over the results.
Java
Set<ModelObject> objects = dm.findByKeyword("test");
if (objects.size() == 0)
System.out.println(">>>>> No objects found with keyword \"test\"");
else
for (ModelObject obj : objects)
System.out.println(">>>>> Object with keyword \"test\" found at " +
obj.getPath());
Python (Jython)
objects = dm.findByKeyword("test")
if objects.size() == 0:
print ">>>>> No objects found with keyword \"test\""
else:
for obj in objects:
print ">>>>> Object with keyword \"test\" found at " + obj.getPath()
Python (IronPython)
objects = dm.FindByKeyword("test")
if objects.Count == 0:
print ">>>>> No objects found with keyword \"test\""
else:
for obj in objects:
print ">>>>> Object with keyword \"test\" found at " + obj.Path
C#
HashSet<ModelObject> results = dm.FindByKeyword("test");
if (results.Count == 0)
Console.WriteLine(">>>>> No objects found with keyword \"test\"");
else
foreach (ModelObject result in results)
Console.WriteLine(">>>>> Object with keyword \"test\" found at " + result.Path);
Searching for Objects Using a Saved Query

EKM provides a powerful search user interface that enables users to execute very complex queries. Once
complete, the user can save a query so it can be executed again at a later time. Queries are saved on
the user’s Home/My Queries page or on the Administration/Shared Queries page for those queries
that should be available to all users. The library provides a way to execute these saved queries. When
executing one of these queries from an application, the application must specify the name of the query
to execute, and whether or not the query is shared. The results of the query are processed exactly like
those returned when searching using a keyword.
The following examples show this operation:
Java
// Execute a saved query in the user's "My Queries" folder.
Set<ModelObject> objects = dm.executeSavedQuery("my-query", false);
// Execute a saved query in the "Shared Queries" folder.
Set<ModelObject> objects = dm.executeSavedQuery("shared-query", true);
Python (Jython)
# Execute a saved query in the user's "My Queries" folder.
objects = dm.executeSavedQuery("my-query", False)
# Execute a saved query in the "Shared Queries" folder.
objects = dm.executeSavedQuery("shared-query", True)
Python (IronPython)
# Execute a saved query in the user's "My Queries" folder.
objects = dm.ExecuteSavedQuery("my-query", False)
# Execute a saved query in the "Shared Queries" folder.
objects = dm.ExecuteSavedQuery("my-query", True)
C#
// Execute a saved query in the user's "My Queries" folder.
HashSet<ModelObject> objects = dm.ExecuteSavedQuery("my-query", false);
// Execute a saved query in the "Shared Queries" folder.
HashSet<ModelObject> objects = dm.ExecuteSavedQuery("shared-query", true);
Searching for Objects Using a Client Created Query

You can also generate complex queries using the API. You do this by first creating a Query object and
then adding QueryRow instances to the query. When creating a query object, you can specify specific
object types that you want to limit the query to. For example, in Java:
Query myQuery = new Query(“WorkbenchProjectArchiveFile”);
This executes a query that searches only Workbench project archive objects. In addition, you must
specify the query operation to perform. This is one of match all rows or match any rows:
QueryOperation queryOp = new QueryOperation();
queryOp.setMatch(QueryMatch.ALL);
Next, you need to add rows to the query operation. This is where you specify the actual properties and
values to search:
List<QueryRow> rows = new ArrayList<QueryRow>();
QueryRow row = myQuery.createRow(“property”, Condition.EQUAL, “value”);
queryOp.setRows(rows);
You can also limit the query to a specific location in the EKM server. This is done by setting the path
of the query. This path must be an actual EKM path. To do this, make sure to fix up the path prior to
setting it in the query:
String path = PathUtils.fixUpPath(“/Data/My Data”, “AnEkmUsername”);
myQuery.setPath(path);
Finally, apply the operation to the query and execute it:

myQuery.setOp(queryOp);
Set<ModelObject> results = dm.findByQuery(myQuery);
14.2.4. C.R.U.D.
C.R.U.D. stands for Create, Read, Update, and Delete. Searching for objects, as described previously,
covers the Read portion of the acronym. The following section will cover the other portions.
Creating New Objects

The library provides operations for creating new objects in the repository. Each object in the repository
has a type associated with it. For example, a folder in the repository is of the type Folder. When cre-
ating new objects in the repository, the application must specify the type of the object being created.
The available types can be retrieved from the server as shown below:
Java
Map<String, ModelSpec> types = dm.getModelSpecs();
for (String type : types.keySet())
System.out.println(">>>>> " + type + " : Label : " + types.get(type).getLabel());
Python (Jython)
types = dm.getModelSpecs()
for type in types:
print ">>>>> " + type + " : Label : " + types[type].getLabel()
Python (IronPython)
types = dm.GetModelSpecs()
for type in types.Keys:
print ">>>>> " + type + " : Label : " + types[type].Label
C#
Dictionary<string, ModelSpec> specs = dm.GetModelSpecs();
foreach (string type in specs.Keys)
Console.WriteLine(">>>> " + type + " Label: " + specs[type].Label);
In the above examples, the type is the internal type name (for example, AdobePdfFile) and getLabel
/Label returns a localized, human readable label (for example, Adobe Acrobat Document). Once the in-
ternal type name of a new object has been determined, it can be used to create the object. This is
shown in the examples below.
Java
dm.createModelObject("/Data/My Data/My Workbench Projects", "Folder");
Python (Jython)
dm.createModelObject("/Data/My Data/My Workbench Projects", "Folder")
Python (IronPython)
dm.CreateModelObject("/Data/My Data/My Workbench Projects", “Folder”)
C#
dm.CreateModelObject("/Data/My Data/My Workbench Projects", “Folder”);
Since folders are one of the more likely object types to be created by the library, a convenience method
is provided to do this.
Java
dm.createFolder("/Data/My Data", "My Projects");
Python (Jython)
dm.createFolder("/Data/My Data", "My Projects")
Python (IronPython)
dm.CreateFolder("/Data/My Data", "My Projects")
C#
dm.CreateFolder("/Data/My Data", "Test");
Modifying and Updating Objects

Once an object has been created or read from the server, the application can modify properties in the
object. For example, you can modify an object’s description, set a user-defined property, and then update
the object on the server. This is shown in the examples below.
Java
1. ModelObject folder = dm.findByPath("/Data/My Data/My Projects");
2. folder.setDescription("Folder for my personal projects");
3. VariantFactory vf = conn.getVariantFactory();
4. Variant value = vf.createVariant(25);
5. folder.setProperty("maxNumberProjects", value);
6. dm.updateModelObject(folder);
Python (Jython)
1. folder = dm.findByPath("/Data/My Data/My Projects")
2. folder.setDescription("Folder for my personal projects")
3. vf = conn.getVariantFactory()
4. value = vf.createVariant(25)
5. folder.setProperty("maxNumberProjects", value)
6. dm.updateModelObject(folder)
Let’s look at this example in more detail. All property values stored in an object in EKM are stored as a
Variant. A Variant is a data structure that can store any type of data including strings, numbers, lists,
and even references to other objects. Therefore, when you set a property using the setProperty
operation, you must first create a Variant instance. This is done using the VariantFactory. This is
shown on lines 3-5 in the examples above. Once the object has been modified, you must update it on
the server as shown on line 6 in the examples above. Doing the above operation in C#/IronPython is
slightly different.
Python (IronPython)
1. folder = dm.FindByPath("/Data/My Data/My Projects")
2. folder.SetUserProperty(“description”, VariantFactory.CreateVariant("My test folder"));
3. value = VariantFactory.CreateVariant(25);
4. if folder.Properties.ContainsKey("maxNumberProjects"):
5. folder.SetUserProperty("maxNumberProjects", value)
6. else:
7. folder.AddProperty(ModelSpec.TAGS_CATEGORY, "maxNumberProjects", value);
8. dm.UpdateModelObject(folder);
C#
1. ModelObject folder = dm.FindByPath("/Data/My Data/My Projects");
2. folder.SetUserProperty(“description, VariantFactory.CreateVariant("My test folder"));
3. Variant value = VariantFactory.CreateVariant(25);
4. if (!folder.Properties.ContainsKey("maxNumberProjects"))
5. folder.AddProperty(ModelSpec.TAGS_CATEGORY, "maxNumberProjects", value);

6. else
7. folder.SetUserProperty("maxNumberProjects", value);
8. dm.UpdateModelObject(folder);
The key difference here is that when setting a “user property” in C# or IronPython, you must first check
to see if it exists, and add the property if it does not. This is shown on lines 4-7.
Deleting Objects
The function of deleting objects on the server is shown in the examples below.
Java
dm.deleteModelObject("/Data/My Data/My Projects");
Python (Jython)
dm.deleteModelObject("/Data/My Data/My Projects")
Python (IronPython)
dm.DeleteModelObject("/Data/My Data/My Projects")
C#
dm.DeleteModelObject("/Data/My Data/My Projects");
14.2.5. Checking Permissions

EKM uses permissions to authorize actions on objects. If the application attempts to perform an action
on an object for which the user has insufficient permissions, an exception is thrown and the action fails.
Actions include access, create, delete, modify, download, full control, and checkout. When checking
permissions, the application creates a collection of actions that it wants to check. If any single permission
is denied, the check will return false. The following example checks to see if the user has permission to
delete an object:
Java
ModelObject folder = dm.findByPath("/Data/My Data/My Projects");
Set<PermissionAction> actions = new HashSet<>();
actions.add(PermissionAction.DELETE);
if (dm.hasPermission(folder, actions))
dm.DeleteModelObject(folder.getPath());
Python (Jython)
folder = dm.findByPath("/Data/My Data/My Workbench Projects")
actions = [PermissionAction.DELETE]
if dm.hasPermission(folder, actions):
dm.deleteModelObject("/Data/My Data/My Projects")
Python (IronPython)
folder = dm.FindByPath("/Data/My Data/My Projects")
actions = List[PermissionAction]()
actions.Add(PermissionAction.DELETE)
if dm.HasPermission(folder, actions):
dm.DeleteModelObject(folder.Path)
C#
ModelObject folder = dm.FindByPath("/Data/My Data/My Projects");
HashSet<PermissionAction> actions = new HashSet<PermissionAction>();
actions.Add(PermissionAction.DELETE);
if (dm.HasPermission(folder, actions))
dm.DeleteModelObject(folder.Path);
14.2.6. Locking and Unlocking Objects

Since objects in the EKM repository can be accessed by any number of users, some users may wish to
ensure they have exclusive control of an object before modifying it. One of the easiest ways to do this
is to lock the object before modifying it. The library provides operations for both locking and unlocking
objects so that the user can gain exclusive use of the object. When locking or unlocking an object, you
must specify if any children of the object should be locked as well. The following shows examples of
locking and unlocking an object:
Java
ModelObject folder = dm.createFolder("/Data/My Data", "My Projects");
if (dm.lock(folder, true)) {
try {
// Modify the folder
} finally {
dm.unlock(folder, true);
}
} else {
System.err.println(“>>> Unable to lock the folder for exclusive use”);
}
Python (Jython)
folder = dm.createFolder("/Data/My Data", "My Projects")
if dm.lock(folder, True):
try:
# Modify the folder
finally:
dm.unlock(folder, True)
else:
print “>>>> Unable to lock the folder for exclusive use”
Python (IronPython)
folder = dm.CreateFolder("/Data/My Data", "My Projects")
if dm.Lock(folder, True):
try:
# Modify the folder
finally:
dm.Uunlock(folder, True)
else:
print “>>>> Unable to lock the folder for exclusive use”
C#
ModelObject folder = dm.CreateFolder("/Data/My Data", "My Projects");
if (dm.Lock(folder, true))
{
try
{
// Modify the folder
}
finally
{
dm.Unlock(folder, true);
}
}
else
Console.WriteLine(“>>>> Unable to lock folder for exclusive use”);
14.2.7. Version Control

Another powerful feature of EKM is that it provides a fully featured version control system. This provides
users with the ability to maintain multiple versions of an object and also track the history of the object.
The library provides access to the version control system.
To use the version control system, an application must first add an object to the version control system.
Then the object must be checked out prior to modifying it. After an object is modified and updated, it
must be checked back in to create a new version of the object. If an object no longer needs to be
tracked, an application can also remove it from version control. At any time, an application can get the
history of a versioned object. The history includes version number, the user that modified the object,
comments related to the modification, and the date the version was created. Similar to locking and
unlocking, any time an object is added to version control, checked out, checked in, or removed, the
application must indicate if the action should be applied to all of the children of the object.
The examples below show how an application can access and use the version control system.
Java
ModelObject folder = dm.createFolder("/Data/My Data", "My Projects");
folder = dm.addToVersionControl(folder, true);
folder = dm.checkout(folder, true);
folder.setDescription("foo bar");
dm.updateModelObject(folder);
folder = dm.checkin(folder, "Set the description", true);
Map<String, VersionHistoryItem> history = dm.getVersionHistory(folder);
for (Map.Entry<String, VersionHistoryItem> entry : history.entrySet()) {
System.out.println(">>>>> Version number: " + entry.getKey());
VersionHistoryItem item = entry.getValue();
System.out.println(">>>>> Comment: " + item.getComment());
System.out.println(">>>>> User: " + item.getUsername());
System.out.println(">>>>> Date: " + item.getDate());
}
folder = dm.checkout(folder, true);
dm.removeFromVersionControl(folder, true);
Python (Jython)
folder = dm.createFolder("/Data/My Data", "My Projects")
folder = dm.addToVersionControl(folder, True)
folder = dm.checkout(folder, True)
folder.setDescription("foo bar")
dm.updateModelObject(folder)
folder = dm.checkin(folder, "Set the description", True)
history = dm.getVersionHistory(folder)
for key in history:
print ">>>>> Version number: " + key
item = history[key]
print ">>>>> Comment: " + item.getComment()
print ">>>>> User: " + item.getUsername()
print ">>>>> Date: " + str(item.getDate())
folder = dm.checkout(folder, True)
dm.removeFromVersionControl(folder, True)
Python (IronPython)
folder = dm.CreateFolder("/Data/My Data", "My Projects")
folder = dm.AddToVersionControl(folder, True)
folder = dm.Checkout(folder, True)
folder.SetUserProperty(ModelSpec.DESCRIPTION_PROPERTY,
VariantFactory.CreateVariant("My test folder"));
dm.UpdateModelObject(folder)
folder = dm.Checkin(folder, "Set the description", True)
history = dm.GetVersionHistory(folder)
for kvp in history:
print ">>>>> Version number: " + kvp.Key

item = kvp.Value
print ">>>>> Comment: " + item.Comment
print ">>>>> User: " + item.Username
print ">>>>> Date: " + str(item.Date)
folder = dm.Checkout(folder, True)
dm.RemoveFromVersionControl(folder, True)
C#
ModelObject folder = dm.CreateFolder("/Data/My Data", "My Projects");
folder = dm.AddToVersionControl(folder, true);
folder = dm.Checkout(folder, true);
folder.SetUserProperty(ModelSpec.DESCRIPTION_PROPERTY,
VariantFactory.CreateVariant("My test folder"));
folder = dm.UpdateModelObject(folder);
folder = dm.Checkin(folder, "Set the description", true);
Dictionary<string, VersionHistoryItem> history = dm.GetVersionHistory(folder);
foreach (KeyValuePair<string, VersionHistoryItem> entry in history)
{
Console.WriteLine(">>>> Version number: " + entry.Key);
VersionHistoryItem item = entry.Value;
Console.WriteLine(">>>> Comment: " + item.Comment);
Console.WriteLine(">>>> User: " + iteme.Username);
Console.WriteLine(">>>> Date: " + item.Date);
}
folder = dm.Checkout(folder, true);
dm.RemoveFromVersionControl(folder, true);
14.2.8. Transferring Files

One of the more common tasks that an application may wish to perform is transferring files between
the client and the EKM server. Whenever an application transfers files, it must provide a TransferEvent-
Listener. This is an object that will receive events about the transfer. Events include the start, cancel-
lation, failure, or completion of a transfer. Additionally, it will receive events with progress information
about the transfer.
The following examples show how to upload and download a file:
Java
ModelObject destination = dm.findByPath(“/Data/My Data/My Projects”);
List<String> files = new ArrayList<>();
files.add(“/projects/my-project.wbpj”);
TransferEventListener listener = new MyTransferEventListener();
dm.upload(files, destination.getPath(), new ArrayList<String>(), listener), true;
//
// Wait for the upload to complete and check the status
// to ensure it was successful.
//
List<String> toDownload = new ArrayList<>();
toDownload.add("/Data/My Data/My Projects/my-project.wbpz");
dm.download(toDownload , System.getenv("TEMP"), true, listener);
//
// Wait for the download to complete and check the status
//
Python (Jython)
toUpload = [“/projects/my-project.wbpz”]
destination = dm.findByPath(“/Data/My Data/My Projects”)
listener = MyTransferEventListener()
dm.upload(toUpload, destination.getPath(), None, listener, True)
#
# Wait for the upload to complete and check the status
# to ensure it was successful.
#
toDownload = ["/Data/My Data/My Projects/my-project.wbpz"]

dm.download(toDownload, os.environ[“TEMP”], True, listener)
#
# Wait for the download to complete and check the status
#
Python (IronPython)
toUpload = List[str]()
toUpload .Add(“/projects/my-project.wbpz”)
destination = dm.FindByPath("/Data/My Data/My Projects")
listener = MyTransferEventListener()
dm.Upload(toUpload, destination.Path, listener, True)
#
# Wait for the upload to complete and check the status
#
toDownload = List[str]()
toDownload .Add("/Data/My Data/My Projects/my-project.wbpz")
dm.Download(toDownload, os.environ["TEMP"], True, listener)
#
# Wait for the download to complete and check the status
#
C#
List<string> toUpload = new List<string>();
toUpload.Add(“/projects/my-project.wbpz”);
ModelObject destination = dm.FindByPath(“/Data/My Data/My Projects”);
TransferEventListener listener = new MyTransferEventListener();
dm.Upload(toUpload, destination.Path, listener, true);
//
// Wait for the upload to complete and check the status
//
List<string> toDownload = new List<string>();
toDownload.Add("/Data/My Data/My Projects/my-project.wbpz");
dm.Download(toDownload, Environment.GetEnvironmentVariable("TEMP"), true, listener);
//
// Wait for the download to complete and check the status
//
14.2.9. Managing Users and Groups

EKM controls access to the repository with user accounts. EKM controls access to objects in the repository
by assigning permissions to users and groups for the objects. The library provides a way to create,
manage, and delete EKM users and groups. The examples below show how to do this.
Java
AdministrationManager mm = conn.getAdministrationManager();
ModelObject user = mm.createUser(“jsmith”);
ModelObject group = mm.createGroup(“engineers);
List<String> users = new ArrayList<>();
users.add(user.getName());
mm.addUsersToGroup(users, group.getName());
user = mm.findUser(user.getName());
group = mm.findGroup(group.getName());
if (!mm.belongsTo(user, group))
System.err.println(">>>>> " + user.getName() + " not member of " + group.getName());
else
mm.removeUsersFromGroup(users, group.getName());
Python (Jython)
mm = conn.getAdministrationManager()
user = mm.createUser(“jsmith”)
group = mm.createGroup(“engineers”)
users = [user.getName()]
mm.addUsersToGroup(users, group.getName())
user = mm.findUser(“jsmith”)
group = mm.findGroup(“engineers”)
if not mm.belongsTo(user, group):
print ">>>>> " + user.getName() + " not member of " + group.getName()
else:
mm.removeUsersFromGroup(users, group.getName())
Python (IronPython)
mm = conn.getAdministrationManager()
user = mm.CreateUser(“jsmith”)
group = mm.CreateGroup(“engineers”)
users = List[str]()
users.Add(user.Name)
mm.AddUsersToGroup(users, group.Name)
user = mm.FindUser(user.Name)
group = mm.FindGroup(group.Name)
if not mm.BelongsTo(user.Name, group.Name):
print ">>>>> " + user.Name + " not member of " + group.Name
else:
mm.RemoveUsersFromGroup(users, group.Name)
C#
AdministrationManager mm = conn.GetAdministrationManager();
ModelObject user = mm.CreateUser(“jsmith”);
ModelObject group = mm.CreateGroup(“engineers”);
List<string> users = new List<string>();
users.Add(user.Name);
mm.AddUsersToGroup(users, group.Name);
user = mm.FindUser(user.Name);
group = mm.FindGroup(group.Name);
if (!mm.BelongsTo(user.Name, group.Name))
Console.WriteLine(">>>> " + user.Name + " not member of " + group.Name);
else
mm.RemoveUsersFromGroup(users, group.Name);
14.2.10. Miscellaneous Operations

The final operations provided by the library include retrieving the server’s date and time, clearing or
restoring a user’s recycle bin, and executing a script on the server. For script execution, the script
provided by the application is actually sent to the server and executed there. The examples below show
these operations.
Java
String script=
"obj = ekm.getObjectByPath(\"/Data/Shared Data\")\n" +
"print \"Found object: \" + str(obj)\n";
dataManager.executeScript(script);
System.out.println(">>>>> Current server date/time is " + adminManager.getServerTime();
ModelObject group = adminManager.createGroup("ParentGroup");
String id = group.getID();
adminManager.deleteMember(group.getName());
List<String> idsToRestore = new ArrayList<String>();
idsToRestore.add(id);
adminManager.restoreRecycleBin(idsToRestore);
adminManager.deleteMember(group.getName());
adminManager.clearRecycleBin();
Submitting and Monitoring Jobs
Python (Jython)
script = \
"obj = ekm.getObjectByPath(\"/Data/Shared Data\")\n" + \
"print \”Found object: \” + str(obj)\n" dataManager.executeScript(script)
print ">>>>> Current server date/time is " + str(adminManager.getServerTime())
group = adminManager.createGroup("ParentGroup")
id = group.getID()
adminManager.deleteMember(group.getName())
ids = [id]
adminManager.restoreRecycleBin(ids)
adminManager.deleteMember(group.getName())
adminManager.clearRecycleBin()
Python (IronPython)
script = \
"obj = ekm.getObjectByPath('/Data/Shared Data')\n" + \
"print 'Found object: ' + str(obj)\n"
dataManager.ExecuteScript(script)
print str(adminManager.GetServerTime())
group = adminManager.CreateGroup("ParentGroup")
ids = List[str]()
ids.Add(group.ArchiveId)
adminManager.DeleteMember(group.Name)
adminManager.RestoreRecycleBin(ids)
adminManager.DeleteMember(group.Name)
adminManager.ClearRecycleBin()
C#
StringBuilder script = new StringBuilder("a = 1\n");
script.Append("print 'a = ' + str(a)\n");
script.Append("b = 2\n");
script.Append("print 'b = ' + str(b)\n");
script.Append("print 'a + b = ' + str(a + b)\n");
dataManager.ExecuteScript(script.ToString());
Console.WriteLine(am.GetServerTime());
ModelObject parent = adminManager.CreateGroup("ParentGroup");
string id = parent.ArchiveId;
adminManager.DeleteMember(parent.Name);
List<string> idsToRestore = new List<string>();
idsToRestore.Add(id);
adminManager.RestoreRecycleBin(idsToRestore);
adminManager.DeleteMember(parent.Name);
adminManager.ClearRecycleBin();
14.3. Submitting and Monitoring Jobs

The library provides operations for running and monitoring jobs. The examples below show the basic
operations.
Java
JobManager rjm = conn.getJobManager();
//set this path to one that contains commands.xml and SecInput.txt

String jobFilesPath = "C:\\temp\\job_files";
//set this path to where the job will run

String clientDirectoryPath = "C:\\temp\\job_dir";
String jobType = "TEST";
File markerFile = File.createTempFile("job.", ".marker", new File(clientDirectoryPath));

String markerFileName = markerFile.getName();
String markerFilePath = markerFile.getAbsolutePath();
Variant jobSpaceCreationResult = rjm.CreateJobSpace(clientDirectoryPath, markerFileName, UUID.randomUUID().toSt
String jobSpaceId = jobSpaceCreationResult.getMap().get("jobSpaceId").getString();
System.out.println("Job created: " + jobSpaceId);
boolean clientWorkDirVisible = jobSpaceCreationResult.getMap().get("clientWorkDirVisible").getBoolean();

System.out.println("client working directory " + (clientWorkDirVisible ? "IS" : "is NOT") + " visible.");
//do an upload if the client working directory is not visible to RSM...

if (!clientWorkDirVisible)
{
String sourceLocalFilePath = jobFilesPath + File.separator + "commands.xml";
String destinationRelativeFilePath = "commands.xml";
System.out.println("uploading " + sourceLocalFilePath + " to " + destinationRelativeFilePath + ".");
rjm.UploadFile(jobSpaceId, sourceLocalFilePath, destinationRelativeFilePath);
sourceLocalFilePath = jobFilesPath + File.separator + "SecInput.txt";
destinationRelativeFilePath = "SecInput.txt";
System.out.println("uploading " + sourceLocalFilePath + " to " + destinationRelativeFilePath + ".");
rjm.UploadFile(jobSpaceId, sourceLocalFilePath, destinationRelativeFilePath);
}
else
{
org.apache.commons.io.FileUtils.copyFile(new File(jobFilesPath + File.separator + "commands.xml"),
new File(clientDirectoryPath + File.separator + "commands.xml"));
org.apache.commons.io.FileUtils.copyFile(new File(jobFilesPath + File.separator + "SecInput.txt"),
new File(clientDirectoryPath + File.separator + "SecInput.txt"));
}
String configQueueName = "Local";

System.out.println("Submitting job to ConfiguredQueue: " + configQueueName);
RsmSubmitData submitData = new RsmSubmitData();

submitData.AutomaticInputs = true;
submitData.AutomaticOutputs = true;
submitData.ClientDirectory = clientDirectoryPath;
submitData.CommandsXmlFileName = "commands.xml";
submitData.DisplayName = "MyJob";
submitData.JobType = jobType;
submitData.ConfiguredQueue = configQueueName;
String uniqueCallId = UUID.randomUUID().toString();
List<String> patterns = new ArrayList<String>();

patterns.add("force.out");
String submitReturn = rjm.SubmitJob(uniqueCallId, submitData.serialize(), jobSpaceId, jobType, patterns);
WebResult<String> webResult = AbstractSerializableData.deSerialize(submitReturn, new TypeToken<WebResult<String
String batchJobId = processWebResult(webResult);

if (submitReturn != null)
{
System.out.println("Batch Job Id = " + batchJobId);
}
else
{
System.out.println("SubmitJob Result is null.");
}
// Check the status of the job every 5 seconds...

JobStatus jobStatus = JobStatus.Unknown;
do
{
String statusStr = rjm.GetJobStatus(uniqueCallId, jobSpaceId, batchJobId);
WebResult<JobState> jobStateResult = AbstractSerializableData.deSerialize(statusStr, new TypeToken<WebResul
JobState jobState = processWebResult(jobStateResult);
int theStatus = jobState.getJobStatus();
jobStatus = JobStatus.getAsEnum(theStatus);
System.out.println("=============================");
System.out.println("GetJobStatus: " + jobStatus);
System.out.println("IsReleased: " + jobState.isIsReleased());
Thread.sleep(1000);
}
while (jobStatus == JobStatus.Running || jobStatus == JobStatus.Queued);
ReleaseData relData = new ReleaseData(true, false);
FinalizeData finalizeData = new FinalizeData(jobStatus);

String finalizeDataStr = finalizeData.serialize();
String finalizeResultStr = rjm.FinalizeJob(uniqueCallId, jobSpaceId, batchJobId, finalizeDataStr);
webResult = AbstractSerializableData.deSerialize(finalizeResultStr, new TypeToken<WebResult<FinalizeResult>>()
processWebResult(webResult);
ReleaseData releaseData = new ReleaseData(true, false);
String releaseDataStr = releaseData.serialize();
String releaseJobResultStr = rjm.ReleaseJob(uniqueCallId, jobSpaceId, batchJobId, releaseDataStr);
webResult = AbstractSerializableData.deSerialize(releaseJobResultStr, new TypeToken<WebResult<?>>() {});
processWebResult(webResult);
String jobConclusionInfo = rjm.GetJobConclusionInformation(jobSpaceId, batchJobId);

JobConclusionInformation jobConclusionResult = AbstractSerializableData.deSerialize(jobConclusionInfo, new Type
System.out.println("FinalStatus: " + jobConclusionResult.getFinalStatus());
System.out.println("IsReleased: " + jobConclusionResult.isIsReleased());
System.out.println("ExitCodes: " + jobConclusionResult.getCommandExitCodes());
...
// helper function
public static <T extends Object> T processWebResult(WebResult<T> webResult) throws IngressException {
ServiceCallOutcome outcome = webResult.getOutComeEnum();
if (outcome.equals(ServiceCallOutcome.Failure) || outcome.equals(ServiceCallOutcome.Exception)) {
Throwable cause = new Throwable(webResult.getStackTrace());
IngressException e = new CommonsException("job.generalError", cause, webResult.getFailureMessage());
throw e;
}
T resultData = webResult.getData();
return resultData;
}
Python (IronPython)
# set this path to one that contains commands.xml and SecInput.txt
job_files_path = "C:\\temp\\job_files"
# set this path to where the job will run

client_directory_path = "C:\\temp\\job_dir"
jm = conn.getJobManager()
configQueueName = "Local"
markerName = tempfile.NamedTemporaryFile('w+b', delete=False).name
associatedUncPathsForClientDirectory = List[str]([]).AsReadOnly()
jobSpaceCreationData = JobSpaceCreationData(markerName, client_directory_path, str(uuid.uuid4()), associatedUnc
jobSpaceCreationResult = jm.CreateJobSpace(jobSpaceCreationData);
jobSpaceId = jobSpaceCreationResult.JobSpaceId
# do an upload if the client working directory is not visible to RSM...

if not jobSpaceCreationResult.CanSeeClientWorkingDirectory:
sourceLocalFilePath = os.path.join(job_files_path, 'commands.xml')
destinationRelativeFilePath = "commands.xml"
cancelHandle = None
print "uploading " + sourceLocalFilePath + " to " + destinationRelativeFilePath + "."
jm.UploadFile(jobSpaceId, sourceLocalFilePath, destinationRelativeFilePath, cancelHandle)
sourceLocalFilePath = os.path.join(job_files_path, 'SecInput.txt')
destinationRelativeFilePath = "SecInput.txt"
print "uploading " + sourceLocalFilePath + " to " + destinationRelativeFilePath + "."
jm.UploadFile(jobSpaceId, sourceLocalFilePath, destinationRelativeFilePath, cancelHandle)
else:
shutil.copyfile(os.path.join(job_files_path, "commands.xml"), os.path.join(client_directory_path, "commands.xm
shutil.copyfile(os.path.join(job_files_path, "SecInput.txt"), os.path.join(client_directory_path, "SecInput.tx
submitData = RsmSubmitData()
submitData.AutomaticInputs = True
submitData.AutomaticOutputs = True
submitData.ClientDirectory = client_directory_path
submitData.CommandsXmlFileName = "commands.xml"
submitData.DisplayName = "MyJob"
submitData.JobType = "TEST"
submitData.ConfiguredQueue = configQueueName
uniqueCallId = str(uuid.uuid4())
solverTranscriptFileSearchPatterns = List[str](["force.out"]).AsReadOnly()
submitReturnVal = jm.SubmitJob(uniqueCallId, jobSpaceId, submitData.Serialize(), PortalSubmitData(jobSpaceId, "
batchjobid = None
if submitReturnVal is not None:
print "submitReturnVal:" + submitReturnVal
webResult = Serializer.DeserializeWebResult[str](submitReturnVal)
batchjobid = webResult.Data
print "Batch Job Id = " + batchjobid
else:
print "submitReturnVal is null."
# Check the status of the job every 5 seconds...

stat = JobStatus.Running;
while (stat == JobStatus.Running or stat == JobStatus.Queued):
statusStr = jm.GetJobStatus(uniqueCallId, jobSpaceId, batchjobid)
print "GetJobStatus returned:" + statusStr
statusWebResult = Serializer.DeserializeWebResult[JobState](statusStr)
jobState = statusWebResult.Data
stat = jobState.JobStatus;
print "============================="
print "GetJobStatus: " + stat.ToString()
print "IsReleased: " + jobState.IsReleased.ToString()
print "============================="
time.sleep(5);
relData = ReleaseData(False, False)

finData = FinalizeData(stat)
jm.FinalizeJob(uniqueCallId, jobSpaceId, batchjobid, finData.Serialize())
jm.ReleaseJob(uniqueCallId, jobSpaceId, batchjobid, relData.Serialize())
infoStr = jm.GetJobConclusionInformation(jobSpaceId, batchjobid)

print "GetJobConclusionInformation returned: " + infoStr
infoWebResult = Serializer.DeserializeWebResult[JobConclusionInformation](infoStr)
jInfo = infoWebResult.Data
print "============================="
print "final status: " + jInfo.FinalStatus.ToString()
print "is released: " + jInfo.IsReleased.ToString()
print "============================="
C#
//set this path to one that contains commands.xml and SecInput.txt
string jobFilesPath = "C:\\temp\\job_files";
//set this path to where the job will run

string clientDirectoryPath = "C:\\temp\\job_dir";
string jobType = "TEST";
string markerFileName = Path.GetRandomFileName();

string markerFilePath = System.IO.Path.Combine(clientDirectoryPath, markerFileName);
File.Create(markerFilePath);
//List<string> inputFiles = new List<string> { "SecInput.txt", "commands.xml" };

List<String> uncPaths = new List<string>();
IJobSpaceCreationData jobSpaceCreationData = new JobSpaceCreationData(markerFileName, clientDirectoryPath, Guid
IJobSpaceCreationResult jobSpaceCreationResult = rjm.CreateJobSpace(jobSpaceCreationData);
string jobSpaceId = jobSpaceCreationResult.JobSpaceId;
Console.WriteLine("Job created: " + jobSpaceId);
Console.WriteLine("client working directory " + (jobSpaceCreationResult.CanSeeClientWorkingDirectory ? "IS" : "
//do an upload if the client working directory is not visible to RSM...

if (!jobSpaceCreationResult.CanSeeClientWorkingDirectory)
{
string sourceLocalFilePath = System.IO.Path.Combine(jobFilesPath, "commands.xml");
string destinationRelativeFilePath = "commands.xml";
Console.WriteLine("uploading " + sourceLocalFilePath + " to " + destinationRelativeFilePath + ".");
rjm.UploadFile(jobSpaceId, sourceLocalFilePath, destinationRelativeFilePath, null);
sourceLocalFilePath = System.IO.Path.Combine(jobFilesPath, "SecInput.txt");
destinationRelativeFilePath = "SecInput.txt";
Console.WriteLine("uploading " + sourceLocalFilePath + " to " + destinationRelativeFilePath + ".");
rjm.UploadFile(jobSpaceId, sourceLocalFilePath, destinationRelativeFilePath, null);
}
else
{
System.IO.File.Copy(System.IO.Path.Combine(jobFilesPath, "commands.xml"),
System.IO.Path.Combine(clientDirectoryPath, "commands.xml"));
System.IO.File.Copy(System.IO.Path.Combine(jobFilesPath, "SecInput.txt"),
System.IO.Path.Combine(clientDirectoryPath, "SecInput.txt"));
}
string configQueueName = "Local";

Console.WriteLine("Submitting job to ConfiguredQueue: " + configQueueName);
RsmSubmitData submitData = new RsmSubmitData();

submitData.AutomaticInputs = true;
submitData.AutomaticOutputs = true;
submitData.ClientDirectory = clientDirectoryPath;
submitData.CommandsXmlFileName = "commands.xml";
submitData.DisplayName = "MyJob";
submitData.JobType = jobType;
submitData.ConfiguredQueue = configQueueName;
string uniqueCallId = Guid.NewGuid().ToString();
List<string> patterns = new List<string> { "force.out" };

ReadOnlyCollection<string> solverTranscriptFileSearchPatterns = patterns.AsReadOnly();
string submitReturn = rjm.SubmitJob(uniqueCallId, "", submitData.Serialize(), new PortalSubmitData(jobSpaceId,
string batchjobid = null;
if (submitReturn != null)
{
Console.WriteLine("SubmitJob Result:" + Environment.NewLine + submitReturn);
var webResult = Serializer.DeserializeWebResult<String>(submitReturn);
CheckForError(webResult);
batchjobid = webResult.Data;
Console.WriteLine("Batch Job Id = " + batchjobid);
}
else
{
Console.WriteLine("SubmitJob Result is null.");
}
// Check the status of the job every 5 seconds...

JobStatus stat = JobStatus.Unknown;
do
{
string statusStr = rjm.GetJobStatus(uniqueCallId, jobSpaceId, batchjobid);
var statusWebResult = Serializer.DeserializeWebResult<JobState>(statusStr);
CheckForError(statusWebResult);
JobState jobState = statusWebResult.Data;
stat = jobState.JobStatus;
Console.WriteLine("=============================");
Console.WriteLine("GetJobStatus: " + stat);
Console.WriteLine("IsReleased: " + jobState.IsReleased);
Thread.Sleep(5000);
}
while (stat == JobStatus.Running || stat == JobStatus.Queued);
ReleaseData relData = new ReleaseData(true, false);
FinalizeData finData = new FinalizeData(stat);

Console.WriteLine(rjm.FinalizeJob(uniqueCallId, jobSpaceId, batchjobid, finData.Serialize()));
Console.WriteLine(rjm.ReleaseJob(uniqueCallId, jobSpaceId, batchjobid, relData.Serialize()));
string infoStr = rjm.GetJobConclusionInformation(jobSpaceId, batchjobid);

Console.WriteLine(infoStr);
var infoWebResult = Serializer.DeserializeWebResult<JobConclusionInformation>(infoStr);
CheckForError(infoWebResult);
JobConclusionInformation jInfo = infoWebResult.Data;
Console.WriteLine("FinalStatus: " + jInfo.FinalStatus);
Console.WriteLine("IsReleased: " + jInfo.IsReleased);
Console.WriteLine("ExitCodes: " + jInfo.CommandExitCodes);
14.4. Building and Running a Java Application

If developing a Java application, this document assumes the reader already knows how to compile and
run the code being written. The developer must include all of the JAR files in ekm-client/lib in
the classpath used by the Java compiler and Java virtual machine. Also included in the ekm-client
directory is a sample ANT build file called build-samples.xml that can be used to compile and run
the sample Java applications. To use this, simply open a command prompt or shell, change to the ekm-
client directory, and execute the run-samples script in ekm-client/bin. This will compile and
execute the sample Java applications.
Important
These samples all have hard-coded server addresses, user names, and passwords. You will
need to modify them accordingly for your current installation.
The example below shows how to execute the sample applications using Ant.
F:\ekm170\v170\ekm-client>run-samples
Buildfile: F:\ekm170\v170\ekm-client\build-samples.xml
init:
[mkdir] Created dir: F:\ekm170\v170\ekm-client\build
compile:
[javac] F:\ekm170\v170\ekm-client\build-samples.xml:72: warning: 'includeantruntime' was not set, defaulting to
[javac] Compiling 9 source files to F:\ekm170\v170\ekm-client\build
run-samples:
[output omitted]
[echo] Running samples.java.Download

[java] 15:17:37,010 DEBUG RepositoryConnectionManager:? - Open started: temp[http://lebmmoales764:8080,null]
[java] 15:17:39,864 DEBUG RepositoryConnectionManager:? - Setup completed
[java] 15:17:39,865 INFO RemoteRepositoryAdapter:? - Using cache: false
[java] 15:17:40,008 DEBUG RepositoryConnectionManager:? - Open completed
[java] >>>>> Connection Default@lebmmoales76412[http://lebmmoales764:8080,Default] opened
[java] 15:17:40,181 DEBUG FileManagerClient:? - Created httpclient: http.conn-manager.timeout = 100
[java] 15:17:40,325 DEBUG DownloadStage:? - Processing transfer item: /Data/My Data/test.txt
[java] 15:17:40,356 INFO TempFileManager:? - TempFileReaper started
[java] 15:17:40,390 DEBUG FileManagerClient:? - Shutting down connectionmanager
[java] >>>>> Download completed
[java] 15:17:41,496 DEBUG RepositoryConnectionManager:? - Connection closed: Default@lebmmoales76412[http://leb
Default]
[java] >>>>> Connection Default@lebmmoales76412[http://lebmmoales764:8080,Default] closed
BUILD SUCCESSFUL
Total time: 39 seconds
Writing and Running a Python Script Using IronPython
14.5. Running a Python Script Using Jython

To run a Jython program, simply use the jython script in ekm-client/bin. This script will execute
the Jython interpreter with all of the necessary JAR files needed to use the library. There are sample
Jython programs in ekm-client/samples/jython.
To run one of these programs, open a command prompt or shell, change to the ekm-cli-
ent/samples/jython directory and type jython program-name. For example:
F:\ekm170\v170\ekm-client>cd samples\jython
F:\ekm170\v170\ekm-client\samples\jython>jython OpenCloseConnection.py
15:19:35,573 DEBUG RepositoryConnectionManager:? - Open started: temp[http://lebmmoales764:8080,null]
15:19:37,725 DEBUG RepositoryConnectionManager:? - Setup completed
15:19:37,726 INFO RemoteRepositoryAdapter:? - Using cache: false
15:19:37,849 DEBUG RepositoryConnectionManager:? - Open completed
>>>>> Connection Default@lebmmoales76412[http://lebmmoales764:8080,Default] opened
15:19:38,025 DEBUG RepositoryConnectionManager:? - Connection closed: Default@lebmmoales76412[http://lebmmoales764:8
>>>>> Connection Default@lebmmoales76412[http://lebmmoales764:8080,Default] closed
14.6. Writing and Running a Python Script Using IronPython

IronPython is not distributed with the library. Therefore, to run the examples using IronPython, the
developer will need to install it. After IronPython is installed, make sure you add the IronPython install-
ation directory to your path.
14.6.1. Accessing the JAR Files

The .NET implementation of the API still makes use of the JAR files contained in the ekm-client/lib
directory. If you have ANSYS Workbench 17.0 installed, you do not need to do anything else. If you do
not have ANSYS Workbench installed, you must have a lib directory in the working directory of your
script that contains all of the JAR files in ekm-client/lib. If you have ANSYS Workbench 17.0, you
can simply open a command prompt or shell and change to the ekm-client/samples/ironpython
directory and run the scripts there. For example:
F:\ekm170\v170\ekm-client\samples\jython>cd ..\ironpython
F:\ekm170\v170\ekm-client\samples\ironpython>ipy OpenCloseConnection.py
>>>>> Connection Default@lebmmoales7641 opened
>>>>> Connection Default@lebmmoales7641 closed
14.6.2. Accessing the C# DLLs

Similar to the JAR files, an IronPython script must load the DLLs contained in ekm-client/lib. This
is done by importing the Common Language Runtime (CLR) into the script and then loading the DLLs.
A helper script is included in the IronPython samples called client_init.py that you can import
to enable access to the DLLs. This script assumes you have Workbench installed.
14.6.3. Directory Structure for an IronPython Script without Workbench

If you do not have Workbench installed, you will need to have a bin and lib directory in the same dir-
ectory as your Python script. This is shown below:
Figure 14.1: Main Folder Containing Script or Application
Figure 14.2: Folder Containing C# Libraries
Figure 14.3: Folder Containing Java JAR Files
14.6.4. Writing the Script

The first thing that the script must do is import the Common Language Runtime object and load the
C# libraries. This is shown below:
import clr
clr.AddReferenceToFileAndPath("bin//CookComputing.XmlRpcV2.dll")
clr.AddReferenceToFile("bin//CSConnector.dll")
Writing and Running a Python Script Using IronPython
clr.AddReferenceToFile("bin//EkmClientApi.dll")
clr.AddReferenceToFile("bin//log4net.dll")
Next, the script needs to import any classes needed. For example, this script only needs specific access
to the ConnectionFactory class:
from com.ansys.ingress.client.api import EkmConnection
Finally, the script can open the connection and perform some task. The full script contained in
ListEkmFolder.py is provided below:
import clr
clr.AddReferenceToFileAndPath("bin//CookComputing.XmlRpcV2.dll")
clr.AddReferenceToFile("bin//CSConnector.dll")
clr.AddReferenceToFile("bin//EkmClientApi.dll")
clr.AddReferenceToFile("bin//log4net.dll")
import sys
if __name__ == "__main__":
conn = None
try:
"http://lebmmoales764:8080",
"ekmadmin",
"Adminuser123!"
)
print ">>>>> Connection " + conn.GetName() + " opened"
specs = dm.GetModelSpecs()
path = raw_input(">>>>> Enter path of object to list: ")
object = dm.FindByPath(path)
if object is None:
print ">>>>> Object not found at path: " + path
else:
print ">>>>> Contents of " + path
children = object.GetChildNames()
for name in children:
child = dm.FindByPath(object.Path + "/" + name)
print ">>>>> " + child.Name + " Type: " + specs[child.GetTypeName()].Label
except:
print sys.exc_info()[0]
print sys.exc_info()[1]
finally:
if conn:
conn.Close();
print ">>>>> Connection " + conn.GetName() + " closed"
The following is the sample output of this script:

F:\scripts>ipy ListEkmFolder.py
>>>>> Connection Default@lebmmoales7641 opened
>>>>> Enter path of object to list: /Data/Shared Data/Sample Files
>>>>> Contents of /Data/Shared Data/Sample Files
>>>>> job-templates Type: Remote Folder
>>>>> README.txt Type: File
>>>>> conf Type: Remote Folder
>>>>> process-templates Type: Remote Folder
>>>>> simulation-files.zip Type: Archive
>>>>> custom-apps Type: Remote Folder
>>>>> rsm Type: Remote Folder
>>>>> apps Type: Remote Folder
>>>>> Connection Default@lebmmoales7641 closed
14.7. Building and Executing C# Sample

No tools are provided to build or execute the C# sample. In order to build the C# sample, you will need
a C# compiler to compile the source code and a Common Language Runtime (CLR) to execute the ap-
plication. The steps for building and executing the C# sample are beyond the scope of this document
as it will vary depending on the development and execution environment used by the developer. Sim-
ilar to the IronPython samples, the C# sample must be able to access the C# libraries provided with the
installation and have a lib directory containing the JAR files provided with the installation.
14.8. API Documentation

The API documentation is provided as HTML documents in the ekm-client/doc directory.
Javadoc: ekm-client/doc/java/html/index.html
C# doc: ekm-client/doc/cs/html/index.html
Chapter 15: 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 /Administration/Con-
figuration 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. 35) 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. 95). 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 (p. 249), quantity (p. 250) or unit sys-
tem (p. 250) using the schema definition for units (p. 248) and an XML editor.
• Start restricted workspace configuration mode if it has not already been started. See Starting Restricted
• Upload the unit file using the (Upload) > Files/Archives Using the Browser method to the /Ad-
ministration/Configuration folder.
• Accept the workspace configuration. See Accepting the Configuration (p. 39).
The remainder of this chapter presents information on how to define new units in EKM using XML.
Topics include:
15.1. Schema Definition for Units
15.2. Adding a New Unit
Units: Defining and Configuring Using XML
15.3. Adding a New Quantity

15.4. Adding a New Unit System
15.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.
Figure 15.1: Partial Listing of units.xsd Schema Definition (p. 248) 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 15.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 15.1: Partial Listing of units.xsd Schema Definition (p. 248) 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.
Adding a New Unit
Figure 15.2: Partial Listing of Units.xml (p. 249) 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 /Administra-
tion/Configuration folder in the EKM repository.
Figure 15.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>
15.2. Adding a New Unit

Units are defined within the quantity element in Units.xml. Figure 15.3: Quantity and Unit Defini-
tion (p. 249) 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 15.3: Quant-
ity and Unit Definition (p. 249).
• 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 15.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>
Units: Defining and Configuring Using XML
15.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 quantity’s name and contains a list of child unit elements. See Fig-
ure 15.3: Quantity and Unit Definition (p. 249) 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 15.4: Unit System (p. 250) for an example of quantity
elements within a unitSystem element.
15.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 as-
sumed 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 15.4: Unit System (p. 250) 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 15.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"/>
Chapter 16: Miscellaneous Tasks
This chapter presents information on how to perform miscellaneous administrative tasks in EKM. Topics
include:
16.1. Configuring a Common Scripts Library
16.2. Gathering Usage Statistics
16.3. Connecting to Remote File Servers
16.4. Managing Logs
16.5. Using VCollab for 3D Visualization in EKM
16.6. Using the EKM Server Diagnostics Tool
16.7. Lifecycle Approval Process for Process Templates
16.8. Using a Custom Background Image on the EKM Sign-in Page
16.9. Adding Custom Text to the EKM Sign-in Box
16.10. Customizing the Heading on the EKM Title Bar
16.1. Configuring a Common Scripts Library

You can build a script library that contains global scripts by placing the script in the /Administra-
tion/Configuration/Scripts folder.
Some sample scripts that make use of EKM's scripting interface are packaged in the EKM_HOME/ex-
amples/conf/scripts directory where the EKM server is installed. This folder is referenced by a
built-in remote folder named /Data/Shared Data/Sample Files. You can place any or all of
these scripts in the common /Administration/Configuration/Scripts folder for it to be
globally available in all contexts.
Important
Scripts that are defined in the /Administration/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
• Upload the script to the /Administration/Configuration/Scripts folder or copy it from an

existing location in the repository.
• Accept the workspace configuration. See Accepting the Configuration (p. 39).
Miscellaneous Tasks
16.2. Gathering Usage Statistics

In the Administration section, select More > Create Usage Report 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.
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 processes 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.
16.3. Connecting to 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 gen-
eric 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 Administration/Remote File
Servers folder using the New Remote File Server action. You can do this following the instructions
below in Defining a New Remote File Server (p. 252). There are also two remote file servers that are built-
in to EKM and are already defined. See Using Built-in Remote File Servers (p. 254) for details.
16.3.1. Defining a New Remote File Server

To utilize an existing built-in remote file server, see Using Built-in Remote File Servers (p. 254).
To add a new remote file server to EKM,
1. Go to the Administration section and select the Remote File Server page.
2. Select (New) > Remote File Server. This will open the New Remote File Server dialog box.
Connecting to Remote File Servers
Figure 16.1: Defining a Remote File Server
3. Enter a name for the new file server.
4. Enter the type of server or choose one from the drop-down list. Currently, File Server is the only
available option.
5. In the Server address field, enter the path of the remote file server or a folder within the file server. For
example:
\\fileserver\cae-folder
/nfs/fileserver/cae-folder
On Windows, the remote file server path should be a UNC path.
6. 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.
Miscellaneous Tasks
7. 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.
8. 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.
16.3.2. Using 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 Root 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. 254)
for more details.
The server address for the EKM Root Directory file is EKM_ROOT170, which is the directory where the
EKM server is set up.
The EKM Root Directory server, by default, is only referenced by the Sample Files folder in
/Data/Shared Data. However, as an admin user, you can create a Remote Folder or File that points
to any other location in EKM_ROOT170.
For more details on EKM_HOME and EKM_ROOT170, refer to EKM Path Variables.
16.4. Managing Logs

EKM generates logs on a daily basis. These log files are written to the Administration/Logs page
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 on the Administration/Re-
mote File Servers page.
EKM automatically synchronizes data on the Administration/Logs page 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. 51) for details.
When you click on a log file, the contents of the file will be displayed as text in the file list window. A
sample audit log is shown in Figure 16.2: Sample Log Display (p. 255).
Using VCollab for 3D Visualization in EKM
Figure 16.2: Sample Log Display
16.5. Using VCollab for 3D Visualization in EKM

By default, EKM extracts 3D images in glTF format from supported CAE files and displays them in an
interactive viewer in EKM. If instead you want to display images in the VCollab viewer, you must first
configure CAE types to extract images in the CAX format, which is the format supported by VCollab.
To achieve this, the following requirements must be met:
• For each CAE file type from which you want to extract CAX images, you must specify the following attributes:
– extractImageOnUpload: The value for this type attribute must be true.
– imageName: To extract CAX files, the value of this attribute must be file.cax.
– imageApplication: For CAX files, the value of this attribute must be extractCaxImage.
– showContentViewAsDefault: The value for this type attribute must be false if you want the visu-
alization view to be the default view when you open the file in the EKM web client.
For more information about editing type attributes see Defining Type Attributes for a Custom
Type (p. 78).
Miscellaneous Tasks
• To make the extraction of CAX images possible, you must install VMoveCAE on the EKM server. You must
then edit the external application being used for image extraction (for example, extractCaxIm-
age.app.xml) and specify the execution path of VMoveCAE in the application’s settings. For more inform-
ation see Editing an External Application Definition (p. 143).
• To be able to visualize extracted image files in VCollab within EKM, each user must have either VCollab
Presenter or VCollab Presenter Lite installed on their system.
See http://www.vcollab.com for more information on VCollab products and VMoveCAE supported file
formats. VCollab 2012 release is supported in EKM for 3D visualization.
With these steps completed, when you upload a configured CAE file to a repository, EKM will automat-
ically extract a CAX image from the file and save it as a new EKM object of type VCollab File with the
appropriate extension. You can then display the 3D image by selecting (More) > Display > Image
when the CAE file is selected, or by selecting the Image tab if the CAE file is already open. The VCollab
viewer will be loaded in the EKM file list window and will display the 3D simulation image. You can
visualize the 3D image using the interactive tools that are available in the VCollab viewer. For more
details, see Displaying 3D Simulation Images Using VCollab.
16.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 on-
disk 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 /Administration/Configuration folder
in the package because it contains workspace-specific configuration files that may be helpful when
troubleshooting the problem.
16.7. Lifecycle Approval Process for Process Templates

With the default EKM configuration (/Administration/Configuration/Lifecycles/Work-
flowApprove.lc.xml), process templates are not executable on upload or creation. See Basic Steps
for Creating, Configuring, and Managing Lifecycles in the User’s Guide for details. Administrators can
choose among the following options:
• No changes to WorkflowApprove.lc.xml. Enable lifecycle-based approval process by default on all

process templates. Process templates are not executable by default.
• Change WorkflowApprove.lc.xml in a way not to enable lifecycle-based approval process by default.

Process templates are executable by default. No approval is required.
• Delete WorkflowApprove.lc.xml. All process templates are executable by default. No approval is re-
quired.
Note
By default, the 'admin' group will be assigned promote privilege, but it can be configured
for assignment to some other group by admin.
Adding Custom Text to the EKM Sign-in Box
16.8. Using a Custom Background Image on the EKM Sign-in Page

Follow the steps below if you want to incorporate a custom background image on the sign-in page.
Guide for details.
2. If not already present, create a text file named custom.properties and save it in \Apache\htdocs.
3. Add the following entry to the custom.properties file, then save the file:
login.backgroundImage=/../../loginPageBackGroundImageFolder/loginPage-
BackGroundImage.png
4. Go to \Apache\htdocs and create a folder there named loginPageBackGroundImageFolder.
5. Name your custom background image loginPageBackGroundImage.png, and copy it to

\Apache\htdocs\loginPageBackGroundImageFolder.
Note
To revert the background to the default that ships with EKM, simply remove the login.back-
groundImage entry from the custom.properties file. Remember that you will need
to stop and restart the server in order for the change to take effect.
16.9. Adding Custom Text to the EKM Sign-in Box

Follow the steps below if you want to display a disclaimer or other custom text in the Sign in to EKM
box.
Guide for details.
2. Go to EKM_HOME/bundles/en (or other language folder if using a different locale). If not already
present, create a text file named custom.properties.
3. Add a login.header entry to the custom.properties file which contains your custom text, as
shown in the example below:
login.header=ALERT! You are about to access CONFIDENTIAL, PROPRIETARY and TRADE SECRET INFORMATION of Your Or
4. Save the file.
The custom text will be displayed in the sign-in box when users launch EKM:
Miscellaneous Tasks
16.10. Customizing the Heading on the EKM Title Bar

By default, the text ANSYS EKM appears as a heading on the application title bar. You can customize
this text by following the steps below.
Guide for details.
2. Go to EKM_HOME/bundles/en (or other language folder if using a different locale). If not already
present, create a text file named custom.properties.
3. In a text editor, add a home.header entry to the custom.properties file which contains your custom
text:
home.header=custom text
For example, if you want the heading to say ANSYS Engineering Knowledge Manager, you would
specify home.header=ANSYS Engineering Knowledge Manager.
4. Save the custom.properties file, and then restart the EKM server. The custom text will be displayed
on the title bar when users launch EKM.
Chapter 17: 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:
17.1. Data Stored by EKM
17.2. Backing Up EKM
17.3. Restoring EKM
17.1. Data Stored by EKM

EKM stores data in the following locations:
• EKM database
• EKM data directory
• EKM root directory (EKM_ROOT)
In order to fully back up EKM, it is necessary to back up the data at all of these locations.
17.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, processes, and
so on.
17.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.
17.1.3. The EKM Root Directory

The EKM root directory is the root directory where EKM is installed to. This is the path referred to as
EKM_ROOT.
Backing Up and Restoring EKM
For each EKM version, a version-specific root directory (EKM version root) is installed under the parent
EKM_ROOT directory. For EKM 17.0, this directory is EKM_ROOT170. This directory corresponds to the
v170 directory under EKM_ROOT. For example:
Windows: \\server\share\ekm\v170
Linux: /server/share/ekm/v170
The EKM version root directory contains the EKM server home directory: EKM_ROOT170/ekm-server,
referred to as EKM_HOME.
The EKM version root directory also contains the EKM service control scripts: EKM_ROOT170/bin.
17.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 version root directory (EKM_ROOT170)
• 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 pro-
cedure for EKM so that you can implement an appropriate backup procedure and schedule for your
EKM installation.
17.2.1. Backup Procedure

In order to back up EKM, follow this procedure:
1. Back up the EKM Database (p. 262).
2. Back up the EKM Data, Version Root, Job Data, and Repository Directories (p. 262).
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.
Backing Up EKM
Sequence:
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 version root, 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. 62) 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 (p. 261) 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 collec-
tion (p. 261) 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 (p. 261) 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.
17.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.
Backing Up and Restoring EKM
17.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 ekm database using mysqldump:
MYSQL_HOME/bin/mysqldump --databases ekm --single-transaction --hex-blob > ekm.sql
where MYSQL_HOME is the directory where the MySQL database server is installed.
17.2.1.3. Backing up the EKM Data,Version Root, Job Data, and Repository Directories
Once you have backed up the EKM database you can back up the EKM data, version root, job data, and
repository directories.
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
• \v170 (EKM_ROOT170)
17.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.
17.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 version root 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.
Restoring EKM
• Restoring the EKM Database (p. 263)
• Restoring the EKM Data, Version Root, Job Data, and Repository Directories (p. 263)
• Clearing the Search Indices (p. 263)
17.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. 262). 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. 263).
Important
When restoring the EKM database, it is also necessary to restore the EKM data directory from
the same backup set.
17.3.1.2. Restoring the EKM Data, Version Root, 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. 263).
Important
When restoring the EKM data directory, it is also necessary to restore the EKM database from
the same backup set.
17.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.
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 server’s file system. By default,
scripts in EKM 17.0 will only be able to read and write files in the EKM_TEMP directory of the server.
Other limitations placed on scripts are 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 server’s
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/deploy-
ments 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 loca-
tions under JBOSS_HOME do not have read access because they may contain sensitive in-
formation.
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 server’s 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";
};
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 server’s 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.
Appendix B. Built-in Types - Reference
EKM uses an object-oriented system for data typing with EKM Object (p. 275) 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 process templates 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 (p. 276)
File Extensions: .inp
B.2. Abaqus Output Database (AbaqusOutputDatabase)

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

File Extensions: .fil
B.4. Adobe Acrobat Document (AdobePdfFile)

Base Type: File (p. 277)
File Extensions: .pdf
B.5. AIM System in Workbench

Not a standalone type
Base Type: EKM Object (p. 275)
Built-in Types - Reference
Properties:
• Geometry Import Sources (geometryImportSources): list of geometry files imported
• Simulation Processes (simulationProcesses): Number of simulation processes defined
• Materials (materials): Material names
• Physics Types (physicsTypes): types of physics involved (Structural, Fluid Flow, and so on)
• Calculation Types (calculationTypes): types of calculations involved (Static, Transient, and so on)
• Interface Condition Types (interfaceConditionTypes): types of interfaces involved (Contact, Coupling,

and so on)
B.6. Analysis Project (AnalysisContainer)

Base Type: Folder (p. 279)
Properties:
• Execution Process (executionMonitor): a reference variable for the process used to monitor the analysis
• Execution Process Template (executionWorkflow): the process template 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
• Process Template Variable (executionWorflowVar): a reference variable defined in the process that will
be executed when the analysis project is updated
Type Attributes:
• executionWorkflow: the path of the process template that will be executed when the analysis project
is updated
• executionWorflowVar: a reference variable defined in the process that will be executed when the ana-
lysis project is updated
• inputPattern: path pattern where inputs are stored
• outputPattern: path pattern where outputs are stored
B.7. Ansoft Designer File (AnsoftDesigner)

File Extensions: .adsn
Properties:
ANSYS Database/Mechanical APDL Database (AnsysDatabase)
• 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 Ex-

citations (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 Excit-

ations (nExcitations) Number of Optimetrics Setups (nOptimetricsSetups) Number of Ports (nPorts)
Number of Results (nResults) Solution Setups (solutionSetups)
B.8. 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 sim-
ulation
B.9. ANSYS Input/Mechanical APDL Input (AnsysInput)

File Extensions: .dat, .inp
Properties:
• Analysis Types (analysisTypes): types of analysis
B.10. ANSYS Output/Mechanical APDL Output (AnsysOutput)

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

File Extensions: .rst, .rstp, .rth, .rmg, .rfl
B.12. ANSYS Viewer File (AnsysViewerFile)

File Extensions: .avz
B.13. Applications Grid (ApplicationsGrid)

B.14. Approval Task (ApprovalWorkItem)

Base Type: Task (p. 289)
Properties:
• Reviewers (reviewers): task reviewers
• Due Date (dueDate): due date
Batch Task (BatchWorkItem)
B.15. Archive (Archive)

File Extensions: .zip, .tar, .tz
B.16. AUTODYN Database (AutodynDatabase)

File Extensions: .ad
B.17. Base Job (BaseJob)

Properties:
• Status (status): A numeric code representing the current status of the running job
0 = Queued
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.18. Batch Job Submission Queue (BatchQueue)

Base Type: Job Submission Queue (p. 282)
Properties:
• Queue Type (queueType): The type of job submission system (rsmNative, lsf, pbs, torque, windowsHpc, sge)
B.19. Batch Task (BatchWorkItem)

Properties:
• Job (job): Reference to the Job (p. 282) that is associated with this batch task. When the job completes
and is removed, this will be blank.
B.20. BladeGen Database (BladeGenDatabase)

File Extension: .bgd
B.21. CAE Model File (CaeModelFile)

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
• imageName: format of the image file generated by the imageApplication
• 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.22. Cache Server (CacheServer)

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

Base Type: Container (p. 273)
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.24. CFX Definition (CfxDefinition)

File Extensions: .def
Properties:
• Heat Transfer Model (heatTransferModel): heat transfer model
• Combustion Model (combustionModel): combustion model
• Radiation Model (radiationModel): radiation model
Data Extraction Monitor (DataExtractionMonitor)
• 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.25. CFX Result (CfxResult)

Base Type: CFX Definition (p. 272)
File Extensions: .res
B.26. CFX Session File (CfxSessionFile)

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

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

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

B.30. Data Extraction Monitor (DataExtractionMonitor)

B.31. Data Extraction Monitor Container (DataExtractionMonitorContain-

er)
B.32. Data Extraction Queue (DataExtractionQueue)

Base Type: Queue (p. 285)
B.33. DesignXplorer Database (R11) (DesignXplorerDatabase)

File Extensions: .dxdb
B.34. DesignModeler Database (WorkBenchDesignModelerFile)

File Extensions: .agdb
B.35. Discussion Board (DiscussionBoard)

B.36. 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.37. EKM Journal File (ScriptFile)

File Extensions: .jou.py, .jou.bsh
Properties:
• Result Report Macro (resultReportMacro): When you click on 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.
EKM Type (Type)
B.38. 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
• 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.39. EKM Process Template (Workflow)

File Extensions: .pt.xml, .wfxml, .wf.xml
B.40. 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.41. EKM Type (Type)

File Extensions: .type.xml
B.42. Electronics Desktop File (ElectronicsDesktop)

File Extensions: .aedt
B.43. Engineering Data Database (R11) (WorkBenchEngineeringData)

File Extensions: .eddb
Properties:
• Material Library (materialLibrary): associated material library file
B.44. ePhysics File (AnsoftEPhysics)

File Extensions: .ephy
B.45. External Application (ExternalApplication)

Properties:
• Executable Path (execPath): The full path of the application executable.
• Parameters (params): One or more command line parameters. (optional)
• 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.46. FE Model (FeModelInput)

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

File Extensions: .fedb
B.48. 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 up-
loaded 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
• 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 sim-
ulation 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 as-
signment during uploads.
• showContentViewAsDefault: Specifies whether or not the content view of the CAE File is the default
view in the web interface.
B.49. 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.50. Fluent Case (FluentCase)

File Extensions: .cas, .cas.h5
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
• 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.51. Fluent Data (FluentData)

File Extensions: .dat, .dat.h5
B.52. Fluent Plot (FluentPlot)

HFSS File (HfssProject)
File Extensions: .xy
B.53. Folder (Folder)

B.54. Group (Group)

Properties:
• Groups (groups): The list of groups that this group belongs to
B.55. 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
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.56. Icepak Packed Project (IcepakPackProject)

Base Type: Icepak Project Data (p. 280)
File Extensions: .tzr
Properties:
• Flow (flow): Flow solved or not
• Temperature (temperature): Temperature solved or not
• Radiation (radiation): Radiation model used
• Flow Regime (flowRegime): Laminar or turbulent flow
• Turbulence Model (turbulenceModel): Turbulence model used
• Natural Convection (naturalConvection): Natural convection model
• Solar Loading (solarLoading): Off/On
• Altitude (altitude): Off/On
• Species (species): Off/On
• Coupled Solver (coupledSolver): Off/On
• Sequential Solution (sequentialSolution): Off/On
• Parameterization (parameterization): Off/Parametric Trials/Optimization
• Parallel Solution (parallelSolution): Off/On
• Time Variation (timeVariation): Steady or transient calculation
• Version (version): The version of Icepak that generated the file
B.57. Icepak Project Data (IcepakProjectData)

File Extensions: .ice.xml
Properties:
• Flow (flow): Flow solved or not
• Temperature (temperature): Temperature solved or not
• Radiation (radiation): Radiation model used
• Flow Regime (flowRegime): Laminar or turbulent flow
• Turbulence Model (turbulenceModel): Turbulence model used
Interactive Job Submission Queue (InteractiveQueue)
• Natural Convection (naturalConvection): Natural convection model
• Solar Loading (solarLoading): Off/On
• Altitude (altitude): Off/On
• Species (species): Off/On
• Coupled Solver (coupledSolver): Off/On
• Sequential Solution (sequentialSolution): Off/On
• Parameterization (parameterization): Off/Parametric Trials/Optimization
• Parallel Solution (parallelSolution): Off/On
• Time Variation (timeVariation): Steady or transient calculation
• Version (version): The version of Icepak that generated the file
B.58. Image (Image)

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

File Extensions: .rpxml
B.60. Interactive Job (InteractiveJob)

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

Base Type: Job Submission Queue (p. 282)
Properties:
• Queue Type (queueType): The type of job submission system (LSF, PBS, Moab, Torque, Neutro, SGE)
• 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.62. Job (Job)

Base Type: Base Job (p. 275)
Properties:
• Working Directory Path (workingDirectoryPath): Path of the working directory
• Monitoring Object (monitoringObject): Reference to the monitoring task
B.63. Job Submission Queue (JobSubmissionQueue)

Base Type: Queue (p. 285)
Properties:
• Queue Type (queueType): The underlying job submission system to which a queue is mapped — that is,
the scheduler that will run the jobs.
Supported values are:
– rsmNative (Native RSM)
– lsf (LSF)
– pbs (PBS)
– windowsHpc (Microsoft Windows HPC)
– sge (SGE)
– moab (Moab)
– torque (Torque)
– neutro (Neutro)
B.64. Job Submission Server (JobSubmissionServer)

Base Type: Server (p. 285)
Properties:
B.65. Job Template (JobTemplate)

File Extensions: .jt.xml
B.66. Job Template Container (JobTemplateContainer)

Maxwell File (AnsoftMaxwell)
B.67. Lifecycle (Lifecycle)

File Extensions: .lcxml .lc.xml
B.68. Maxwell File (AnsoftMaxwell)

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
• 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 Re-
luctance 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)
B.69. Meshing Database (MeshingDatabase)

File Extensions: .cmdb
B.70. Microsoft Excel Worksheet (MSOfficeExcelFile)

File Extensions: .xls, .xlsx
B.71. Microsoft Powerpoint Presentation (MSOfficePowerpointFile)

File Extensions: .ppt, .pptx
B.72. Microsoft Word Document (MSOfficeDocumentFile)

File Extensions: .doc, .docx
B.73. My Data (MyData)

B.74. NASTRAN Bulk Data (NastranBulkData)

Queue (Queue)
File Extensions: .nas, .bdf, .dat
B.75. NASTRAN Result (NastranResult)

File Extensions: .f04, .f06
B.76. Polyflow Data (PolyflowData)

File Extensions: .dat
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.77. Polyflow Export (UNS) (PolyflowExportFile)

File Extensions: .uns
B.78. Process Container (ProcessContainer)

B.79. Public Saved Query (PublicSavedQueryContainer)

B.80. Q3D File (AnsoftQ3D)

File Extensions: .q3dx
B.81. Queue (Queue)

B.82. 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.83. Report (Report)

B.84. Saved Query (SavedQuery)

B.85. Saved Query Container (SavedQueryContainer)

B.86. Search Results Report (SearchResultsReport)

B.87. Shortcut (Link)

Properties:
• Link (link): The reference to the object pointed to by the shortcut
B.88. 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.89. Simulation Details Report (CaeModelSummaryReport)

Workbench Journal File (WorkBenchJournalFile)
Properties:
• Model File (modelFile): The simulation file whose report is created
B.90. Siwave File (AnsoftSiwave)

File Extensions: .siw
B.91. SpaceClaim Document (SpaceClaimDocument)

File Extensions: .scdoc
B.92. Update Analysis Project Task (UpdateAnalysisProjectWorkItem)

File Extensions: .cax
B.93. 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.94. User (User)

Properties:
• Cache Server (cacheServer): Reference to the EKM Server (Server) (p. 275) 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.95. VCollab File (VcollabCompressedFile)

File Extensions: .cax
B.96. Workbench Journal File (WorkBenchJournalFile)

File Extensions: .wbjn
B.97. Workbench Design Point File (WorkBenchDesignPointFile)

File Extensions: .wbdp
B.98. Workbench Project Archive File (WorkBenchProjectArchiveFile)

File Extensions: .wbpz
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.
• Update Required (updateRequired): Whether this project needs update or not.
B.99. Workbench Project File (WorkBenchProjectFile)

File Extensions: .wbpj
Type Attributes:
• contentType: MIME type of the file (text)
B.100. Workbench Project File R11 (WorkBenchProjectFileR11)

File Extensions: .wbdb
B.101.Workbench Simulation/Mechanical Database (WorkBenchSimula-

tion)
File Extensions: .dsdb, .mechdb, .mechdat
Properties:
• Workbench Version (workbenchVersion): version of the file
• Engineering Data File (engineeringDataFile): reference to the engineering data file used
Task (WorkItem)
• 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
– 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.102. Process (Process)

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

Properties:
• Node (node): name of the node in the process corresponding to the task
• Process (process): reference to the process containing this task
• Reassignment Note (assignmentNote): The note shown when a task is reassigned to another user
• Status (status): status of the task
• User (user): name of the user to which the task has been assigned
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 (p. 291) 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. 155).
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
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.
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.
Lifecycles: Defining and Configuring Using XML
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 1: Partial Listing of lifecycle.xsd Schema Definition (p. 292) shows the partial listing for life-
cycle.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. 293) 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>
Defining Lifecycles Using XML
C.1.2. Defining a Lifecycle XML File

A lifecycle is defined in terms of the following constructs:
• Types (p. 293)
• Stages (p. 293)
• Transitions (p. 295)
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 life-
cycle with a built-in type, you will need to use the non-localized type name as described in Ap-
pendix B (p. 267).
• 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.
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 are
available, including the ability to change 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. 294) 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 the user designated as the Root User for a workspace 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. 294) 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>
<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 process templates, lifecycles should have exactly one start stage. The start stage is the stage that
is not the destination of any transition. Unlike process templates, lifecycles can have more than one
end stage. The end stage is the stage that is not the source of any transition.
• Like process templates, lifecycles must be acyclic. For example, if you have a transition from stage A to
stage B, then you can’t 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 can’t have a transition from stage C to stage
A. In this way, lifecycles, like process templates, 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 life-
cycle definition. See the Defining Macros and Custom Dialogs chapter in the EKM User’s 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 val-
idation 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"
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-cre-
ated-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: group-
1, 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
lifecycle is in the /Data/Shared Data/bar folder, “user1” and “user2” if the object is in
/Data/Shared Data/foo, or null if the object is in any other folder.
<script>
releaseLevel1(model, nextStage) {
if (model.getPath().startsWith("/Data/Shared Data/foo"))
return new String[] {"user1", "user2"};
else if (model.getPath().startsWith("/Data/Shared Data/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 as-
sumed to be 7.
The example in Figure 4: Transition Example 1 (p. 297) 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. 297) 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>

ANSYS EKM Administration Guide

Uploaded by

Copyright:

Available Formats

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

ANSYS, Inc. Release 17.0

ANSYS, Inc. is certified to ISO 9001:2008.

U.S. Government Rights

Published in the U.S.A.

7.3.1. Defining a New Custom Type .................................................................................................. 72

9.5.2. Defining External Applications Directly in EKM ...................................................................... 142

12.8. Example of Journal Recording and Execution ............................................................................... 187

15.3. Adding a New Quantity ............................................................................................................... 250

B.21. CAE Model File (CaeModelFile) .................................................................................................... 272

B.73. My Data (MyData) ....................................................................................................................... 284

Topics covered in this guide include:

• Overview of Servers and Workspaces (p. 3)

• Setting Up Users and Groups (p. 9)

• Creating and Managing Workspaces (p. 19)

• Restricted and Unrestricted Configuration of Workspaces (p. 35)

• Configuring EKM Server Settings (p. 51)

• Defining EKM Servers, Queues, and External Applications (p. 133)

• Defining Custom Types (p. 69)

• Defining and Configuring Lifecycles (p. 153)

• Scripts and Journals (p. 177)

• Defining Custom Dialogs, Wizards and Applications (p. 195)

• Units: Defining and Configuring Using XML (p. 247)

• Backing Up and Restoring EKM (p. 259)

1.1. Path Variables

Figure 2.1: Default Composition of an EKM Server

Planning Server Installations

How Workspaces are Used

2.1. Distributed Servers and Workspace Access

Figure 2.2: Multiple EKM Servers in a Global Setup

2.1.1. Caching Data when Transferring Files

How Caching Works

Figure 2.3: Distributed Setup with Dedicated Cache Server

How Caching Improves Performance

2.1.2. Setting Up Caching

This behavior will be captured in the following logs:

3.1. Introduction to Users and Groups

Users and groups are defined on the Administration/Users page in EKM.

Figure 3.1: Administration > Users

3.2. Automatic Creation of User Accounts

User accounts are not created in a workspace automatically if:

3.3. Adding and Modifying Users

Refer to the following topics:

• Adding a New User (p. 11)

• Editing a User’s Profile (p. 14)

3.3.1. Adding a New User

To add a new user:

1. Go to the Administration section, then select the Users page.

Figure 3.2: Adding a New User

3.3.2. Editing a User’s Profile

3.4. Forcing the Sign-out of a User

3.5. Designating a Root User

3.6. Accessing a User’s Data

1. Select the Administration category, then select Users.

The user’s personal folders will be displayed:

3.7. Adding and Modifying Groups

Refer to the following topics:

• Adding a New Group (p. 16)

• Editing Group Membership (p. 18)

3.7.1. Adding a New Group