EKM provides a scripting interface that you can use to
define scripts that
automate many common operations. Scripts are typically used as a back-end
for custom applications, and can be embedded within a process template,
lifecycle or custom type definition to provide automation where required. EKM’s scripting interface exposes a number of methods or “macros” that can be
used in your script. The detailed documentation of the interface is
provided in the EKM_HOME/api folder. This folder
contains two sub folders: ekm-api-docs-18.2.0 and ekm-cae-api-docs-18.2.0.
The first sub-folder contains the majority of the documentation. The
second sub-folder is just limited to the cae plug-in and provides a single interface with methods for creating
simulation details reports. To access the documentation you can open
the index.html files in these sub folders.
The primary interfaces provided are:
EkmInterface: This is the
primary interface and provides methods to get or search for existing
objects, create new objects, execute batch tasks, start and commit
transactions, perform uploads, downloads, copy, move and lifecycle
operations. An instance of this interface is available as a global
variable for use in scripts. The name of the variable is ekm. For example, within a script you can call ekm.getRoot() to get the root object of EKM.
EkmAdminInterface: This interface
extends EkmInterface. If you belong to the admin group, the global ekm variable
that you can access within scripts will be an instance of this interface
instead of EkmInterface. This interface provides
additional methods to add users and groups and set lifecycle stage
without validation or review. For example, within a script you can
call ekm.addUser("testuser") to add a new
user with user name "testuser."
ModelObjectInterface: This
interface represents an object in EKM. It contains methods to
obtain properties, children, name, id, path, type and version of the
object. It also contains methods to add or remove a child, delete
the object, add it to version control, perform check in or check out,
set properties and permissions. There are some interfaces that extend ModelObjectInterface to provide additional methods for
specific object types. These are FileObjectInterface, ReportObjectInterface, AnalysisContainerInterface, ShortcutObjectInterface, UserObjectInterface 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 accompanying API documentation to determine
whether the method needs to be called within or outside of a transaction.
A transaction is a group of commands that are committed together.
If any command fails, none of the previous commands will be committed
and the whole transaction will be aborted. You can start a transaction
by calling the startTransaction method of EkmInterface and you can commit a transaction by calling
the commitTransaction method of the same
interface. Any method that does not change the state of an object
can be called either within or outside a transaction. Most methods
that change the state of an object are called within a transaction.
Examples: setPermissions and setProperties methods in ModelObjectInterface. Some methods must be called outside a transaction because they
start a transaction internally. Example: enableLifecycle method in EkmInterface.
If you need to specify an object path when defining a script,
you can obtain an object’s path from its Details page (
(More) > > ). 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.
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"
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)