15.6 Importing Workloads Using the PTM REST API

You can use PlateSpin Transformation Manager REST APIs to import Workloads from an external system to a project in PTM. An import succeeds if the workload has been properly defined and the credentials in a specified Credentials resource is valid. The Connector automatically initiates discovery for the imported workload to inventory the workload and add its details to PTM.

15.6.1 Generating a Custom PTM Client from the PTM REST API

The PTM REST API leverages the Swagger framework to present descriptions for its REST APIs. Swagger is built around the OpenAPI Specification (OAS). You can use Swagger tools to generate a client to “talk” to PTM. That is, your client sends a request to PTM and PTM responds with the requested information. Swagger supports a variety of programming languages.

The PTM RESTAPI interface is available on your PTM server at the following URL:

http://<your-ptmserver-ip-address-or-fqdn>:8082/restapi

For example: http://10.10.10.10:8082/restapi

The basic workflow for generating a PTM client:

  1. In a web browser, go to

    http://<your-ptmserver-ip-address-or-fqdn>:8082/restapi/swagger.json

  2. Click Raw Data to expand the code.

  3. Click Copy to save the information to your computer clipboard.

  4. In a web browser, go to the Swagger Editor website at http://editor.swagger.io.

  5. In the Swagger Editor toolbar, select File > Clear editor.

  6. Right-click in the editing panel on the left, then click Paste to insert the information you copied.

  7. Click OK to agree to convert the code from JSON to YAML.

    The PlateSpin Transformation Manager REST API with REST commands and syntax display in the right panel.

    This is the same type of information displayed when you visit the REST API location on your PlateSpin Transformation Manager server at http://<your-ptmserver-ip-address-or-fqdn>:8082/restapi.

  8. In the Swagger Editor toolbar, select Generate Client > Python to download a client written in Python.

    Our example code is written in Python. Swagger Editor supports over 50 other languages that you can use for the client interface you develop.

  9. In the pop-up dialog, select Save File then click OK to save the a ZIP file that contains the generated Python client (python-client-generated.zip).

15.6.2 Using a Custom Client to Import Workloads

After you create an instance of the PTM Client in Section 15.6.1, Generating a Custom PTM Client from the PTM REST API, you can use your generated PTM client to import workloads to PTM.

A simple example of a Python script to import workloads is available (with annotations) on the PlateSpin Transformation Manager Appliance in the <connector-path>\resources\ folder. It demonstrates how to use the REST APIs for PlateSpin Transformation Manager to import workloads for a single project. All values are sample values. You must replace them with information for your own project. We used Python for the example, but you can use any of the available programming languages supported by the Swagger Editor.

The basic workflow in the sample Python script:

  1. Create a blank, in-memory Transformation object.

  2. Set the Workload Name and Project ID on the Transformation object.

    You can get the Project ID by using the REST API, using the PTM Client you generated, or pausing the pause over the icon on the Workload dialog.

  3. Create a blank, in memory Workload object.

  4. Set the FQDN or IP address for the Workload object.

  5. (Optional) Set one or more Application names to associate with the workload.

  6. Set the Workload Admin Credential for authentication with the source workload by referencing an existing one or by creating a new one. Optionally encrypt the password.

    You can do this during the initial workload import. Both methods are illustrated in the sample script.

  7. Perform the import. It returns a Transformation object that you can edit.

  8. If the workload was imported successfully and the credentials you provided are valid, PTM automatically begins discovery on the workload.

  9. Perform other edits on the returned object.

    For example, you can move the workload into a Wave and Batch.

  10. Save the edited information to PTM.

Before you run the sample script:

  1. In a text editor, copy the script and save it as example_simple_import.py.

  2. Modify the various values to correspond with your PTM server and workload environment.

    For example, you provide values for the following. Refer to the script for a complete list of the variables that require your input.

    • PTM User user name, which is an email address

    • PTM User password

    • PTM Server URL of the REST API