Stop/Start Agent via REST API

[Steven NODATA]

I want to write a program to start and stop agents within Automic Automation. How can I do that?

-------------------------------------------

[Peter Grundler]

Hi Steven,

if there is no dedicated REST call available you can use /{client_id}/scripts and start the respective AE script methods.

regards,
Peter

------------------------------
Automic Certified Professional/Expert & Broadcom Knight
------------------------------

[Markus Embacher]

Hi Steve,

use the /scripts endpoint to run :MODIFY_SYSTEM

https://docs.automic.com/documentation/webhelp/english/ALL/components/DOCU/24.4.0/Automic%20Automation%20Guides/Content/Script/Reference/MODIFY_SYSTEM.htm

Regards, Markus

-------------------------------------------

[Steven Blumenkrantz]

I have written the following python code and when it runs, I get the following error. I am confused because when I use the UI to stop/start an agent, I do it in client ZERO because that operation affects ALL other clients.

Anyway, when I use a different existing client id, the code seems to work (Status Code of 200 is returned). The issue is that the agent continues to be active. Is my code wrong?

ae/api/v1/0/scripts; status=400; body={
  "code" : 7020,
  "error" : "Activation in client 0 is not permitted.",
  "details" : "No detail information available."
}

---------------------------------

    json_payload = {

        "script": f":MODIFY_SYSTEM, \'TERMINATE\', \'agent\'"

    }

    response = post_api(f"/ae/api/v1/{CLIENT_ZERO}/scripts", json.dumps(json_payload), auth)

def post_api(endpoint: str, jsonPayload: str, auth: tuple) -> Any:
   try:
        response = requests.post(
            f"{REST_ENDPOINT}/ae/api/v1/0/scripts",
            headers={"Content-Type": "application/json"},
            data=jsonPayload,
            auth=auth,
            timeout=REQUEST_TIMEOUT
        )
        response.raise_for_status()
        return response
    except requests.RequestException as e:
        # Use the response attached to the exception if present,
        # otherwise fall back to the local variable (which may be None)
        resp = getattr(e, "response", response)
        if resp is not None and getattr(resp, "status_code", None) == 200:
            return resp
        if resp is not None:
            try:
                body = resp.text
            except Exception:
                body = '<unreadable response body>'
            logging.error("POST API request failed: %s; status=%s; body=%s", e, getattr(resp, 'status_code', None), body)
        else:
            logging.exception("POST API request failed: %s", e)
        return None

-------------------------------------------

[Steven Blumenkrantz]

Even though I am getting a Status return of 200, when I examine the run id, I get:

Last message

U00021719 Syntax error in object '*SCRIPT', line '00001'. 'U01001300 It is not possible to interpret command 'MODIFY_SYSTEM,'.'.

The report (Logging) says:

<ecc-report-line tokenize="">:MODIFY_SYSTEM, </ecc-report-line>'TERMINATE'<ecc-report-line tokenize="">, </ecc-report-line>'AGENT'

I've tried changing the json payload to :

<ecc-report-line tokenize="">:MODIFY_SYSTEM(</ecc-report-line>'TERMINATE'<ecc-report-line tokenize="">, </ecc-report-line>'AGENT')

with the same results. What is the proper syntax for this script being sent via the REST API?

[Steven Blumenkrantz]

I just tried the following syntax:

        "script": f":SET &RET# = MODIFY_SYSTEM(\"TERMINATE\", \"AGENT\")"

And the error message in "Details" for the resulting run id says:

U00000009 'AGENT': Access denied

-------------------------------------------

[Markus Embacher]

Please replace AGENT by the name of the agent you would like to terminate. If the name of the agent is indeed AGENT, them make sure you have the required permissions to terminate the agent.

-------------------------------------------

[Steven Blumenkrantz]

The agent that I was trying to terminate (originally from client 0, because that's where I stop agents via the UI) was not authorized for the client I was using.  Once I made it authorized for the client, the operation succeeded.

I suggest/request that these types of operations be made available via a dedicated REST API endpoint, rather than using the scripting capabilities. This is now MUCH more complicated as I now need to find a non-zero client where the agent is authorized to do the desired operation.

-------------------------------------------

[Markus Embacher]

Hi Steve, 

I'm glad it works now!

Regards, Markus

-------------------------------------------

[Steven Blumenkrantz]

Thank you for your help!

Now when I try to restart the agent after it has been terminated via the following, as it does when I go to start the agent from Client 0 in the UI, the operation eventually times out and fails. I have had to log onto the agent and manually restart the service manager.

Any ideas why that is the case?

:SET &RET# = MODIFY_SYSTEM("STARTUP", "AGENT")

-------------------------------------------

[Markus Embacher]

Please open the agent object and check the "Service Manager Link". It seems, that the connection to the Service Manager is either not configured correctly, or the Service Manager is not reachable from the Automation Engine.

-------------------------------------------

[Markus Embacher]

Hi Steve, 

no executions allowed in client 0, so it denies to execute the script you are sending.

Further, the syntax is

:SET &RET#=MODIFY_SYSTEM("TERMINATE","AGENT")

not

:MODIFY_SYSTEM TERMINATE,AGENT

Regards, Markus

-------------------------------------------

[Joshua Mclean]

If no scripts are allowed to run in client 0, how can you stop/inactivate an agent via REST API call? 

[Steven Blumenkrantz]

You have to use a client for which the agent is authorized.

    json_payload = {

        "script": f":SET &RET# = MODIFY_SYSTEM(\"{operation}\", \"{agent}\")"

    }
    use_client = <client number for which the agent is authorized>
...

    response = post_api(f"/ae/api/v1/{use_client}/scripts", json.dumps(json_payload), auth, "agent")

[Matthias Schelp]

Hi,

if it doesn't have to be REST you could also use the "classic way" using the service manager dialog client (ucybsmcl). 

Matthias

-------------------------------------------