11.3. Using EKM's Scripting Interface

EKM provides a scripting interface that you can use to define scripts that automate many common operations. Scripts are typically used as a back-end for custom applications, and can be embedded within a 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:

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) > 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"

    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)


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