11.3. Using EKM's Scripting Interface

Engineering Knowledge Manager

Administration Guide | Chapter 11: Scripts and Journals |

11.2. Defining Scripts Using a Supported Scripting Language |  | 11.4. Using Sample Scripts Supplied by EKM
Prev |  | Next

## 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:

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

Contains proprietary and confidential information of ANSYS, Inc. and its subsidiaries and affiliates.

Prev | Up / Contents | Next

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