Setting Up the Prerequisites

The following steps describe how to set up your environment to run the various tutorials.

Step 1: Clone the GitHub repository

Fetch tutorial samples from GitHub and run git clone to create a local copy of the source code.

Copy 
git clone https://github.com/controlm/automation-api-quickstart.git

If you do not yet have Git installed, obtain it from the Git Downloads page.

Step 2: Obtain access to Control-M Automation API

Control-M Automation API is a REST API interface over HTTPS. You can either install Control-M Workbench or access a Control-M instance where you must have Control-M credentials.

Step 3: Install Control-M Automation CLI

To run the tutorials you need a working Control-M CLI. Refer to Control-M Automation API CLI and follow the steps for the relevant platform.

Step 4: Set up a Control-M environment

The Control-M Automation CLI requires an environment to run the commands. An environment is a combination of an endpoint and API token, or a combination of an endpoint, username, and password.

An endPoint is the URI for Control-M Automation API. The endpoint has the following format:

Copy 
https://<controlmEndPointHost>:8443/automation-api

Use one of the following commands to add an environment:

  • A command to add an environment named devEnvironment, with an API token specified:

    Copy 
    ctm environment add devEnvironment "https://<controlmEndPointHost>:8443/automation-api" "<token>"

    You can obtain your first API token through the Control-M user interface, as described in Creating an API Token. For more information about API tokens, see Authentication Service.

  • A command to add an environment named devEnvironment, with a username and password specified:

    Copy 
    ctm environment add devEnvironment "https://<controlmEndPointHost>:8443/automation-api" "<ControlmUser>" "<ControlmPassword>"

  • If you installed Control-M Workbench, you can also use the following command to add an environment for the Workbench:

    Copy 
    ctm environment workbench::add

While the environment is added, it is checked for its policy regarding certificates. If the environment is currently set to accept self-signed certificates, a warning is displayed. If you want to apply a stricter policy of accepting only certificates signed by a trusted Certificate Authority (and not accepting self-signed certificates), you can use the environment configure command to set the rootCertificateRequired parameter to true.

Step 5: Set the environment as default

When you set up your first environment, it is automatically set as the default environment that is used by any API commands that you invoke. In such a case, you can skip this step. Later, after defining additional environments, perform this step to set the default environment of your choice.

In the following example, the Control-M Workbench is set as the default environment. The returned response lists the single environment that is currently defined and notifies you that it is set as the default environment.

Copy 
> ctm environment set workbench
 
info:    current environment: workbench
info:    environments: {
   "workbench": {
      "endPoint": "https://localhost:8443/automation-api",
      "user": "workbench"
   }
}

In the following example, devEnvironment (a Control-M instance) is set as the default environment, and the returned response lists all existing environments.

Copy 
> ctm environment set devEnvironment
 
info:    current environment: devEnvironment
info:    environments: {
   "local": {
      "endPoint": "http://localhost:48080/",
      "user": ""
   },
   "devEnvironment": {
      "endPoint": "https://<controlmEndPointHost>:8443/automation-api",
      "user": "<controlmUser>"
   }
}

After setting the default environment, if you want to run API commands against a different, non-default environment, you must include the -e <environmentName> option in any API command that you run. In addition, ensure that the version of the destination environment matches the version of the CLI.

Step 6: Verify the setup by running an API command

To verify that setup was successful, you can run your first API command. Here are a couple of suggestions for your first API command:

  • Obtain information about the Control-M Servers by running the Config Service API command:

    Copy 
    > ctm config servers::get
     
    {
      "name": "controlm",
      "host": "myhost",
      "state": "Up",
      "message": "Connected",
      "version": "9.0.21.000"
    }

  • If you created the Control-M environment for CLI using a username and password, log in to Control-M and return a session token by running the session login API command:

    Copy 
    > ctm session login
     
    {
      "username": "emuser",
      "token": "E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7",
      "version": "9.0.21"
    }

Step 7: Access documentation

You can access the REST API documentation for this environment:

Copy 
ctm documentation restApi

To access this web-based API documentation:

Copy 
ctm doc gettingStarted