AE v24 REST API

[Michael A. Lowry]

Automation Engine version 24 introduces substantial updates to the AE REST API.

Most notably, v24 adds the ability to create, read, update, and delete objects. The documentation page Using the AE REST API provides examples for several things, but not these "CRUD" operations. I did some basic tests to figure out how it works.

Operation	HTTP method & AE REST API endpoint	Body
Create	​POST /{client_id}​/objects	Complete JSON object definition
Read	GET /{client_id}/objects/{object_name}	NA
Update	PATCH /{client_id}/objects/{object_name}	Partial JSON object definition. Omit type, name, and path properties.
Delete	DELETE /{client_id}/objects/{object_name}	NA

The GET method is essentially equivalent to an XML export, but delivering a JSON payload instead of XML.

Similarly, the POST method is essentially equivalent to an XML import, but requiring a JSON payload instead of XML.

The PATCH method is interesting, because it offers the ability to change just one property of an object. You do this by providing only the portion of the JSON object schema that corresponds to the property you wish to change.

For example, if you wanted to change the queue of an SCRI object, you could use the PATCH method and provide the following JSON in the body of the request. As far as I can tell, this is the minimal JSON payload sufficient to change the queue property.

{
  "data" : {
    "scri" : {
      "general_attributes" : {
        "queue" : "NEW_QUEUE"
      }
    }
  }
}

The remainder of the JSON object schema is irrelevant and can be omitted. When using the PATCH method, the properties type, name, and path must be omitted.

If you want to move or duplicate an object, there are also dedicated API endpoints for these operations.

Operation	HTTP method & AE REST API endpoint	Body
Move	PATCH /{client_id}/objects/{object_name}/move	{ "target_path": "FOLDER/SUBFOLDER" }
Duplicate	​POST /{client_id}​/objects/{object_name}/duplicate	{ "name": "NEW_OBJECT_NAME", "title": "New object description", "path": "FOLDER/SUBFOLDER" }
Rename	?	?

There is currently no way to rename an existing object, other than exporting, deleting, and then re-importing the object.

Update: APIs for renaming objects are coming in a future relese. See @Martin Uferbach’s comment, below.

[Michael A. Lowry]

The Open API 3.0 swagger.json file for the AE REST API includes many examples of AE object JSON payloads.

I've attached a ZIP file containing these examples as separate files categorized by method (GET, PUT, & PATCH).

Attachment(s)

AE JSON schema examples.zip   53 KB 1 version

[SIVANESAN SIVAKUMAR]

Hi Team,

I want to execute job/job plan outside uc4 via rest api . Can i get some
examples for that ?

On Tue, Mar 5, 2024 at 3:04 PM Michael A. Lowry via Broadcom <
[e-mail]> wrote:

> Automation Engine version 24 introduces substantial updates to the AE REST
> API. Most notably, v24 adds the ability to create, read, update, and...
> -posted to the "Automic Workload Automation" community
> [image: Broadcom] <https: community.broadcom.com="">
> Automic Workload Automation
> <https: community.broadcom.com/communities/community-home/digestviewer?communitykey="2e1b01c9-f310-4635-829f-aead2f6587c4">
> Post New Message
> <[e-mail]>
> AE v24 REST API
> <https: community.broadcom.com/discussion/ae-v24-rest-api#bm6f35e1ea-b927-49bb-8a25-a158f1d17604="">
> Reply to Group
> <broadco[e-mail]?subject=re:+ae+v24+rest+api> Reply
> to Sender
> <https: community.broadcom.com/communities/all-discussions/postreply?messagekey="6f35e1ea-b927-49bb-8a25-a158f1d17604&ListKey=7e4de604-f950-4e81-9d19-4e72b8898fb4&SenderKey=4cbb3ea7-a3e4-473c-8b9b-3019a08d286c">
> [image: Michael A. Lowry]
> <https: community.broadcom.com/network/members/profile?userkey="4cbb3ea7-a3e4-473c-8b9b-3019a08d286c">
> Mar 5, 2024 4:35 AM
> Michael A. Lowry
> <https: community.broadcom.com/network/members/profile?userkey="4cbb3ea7-a3e4-473c-8b9b-3019a08d286c">
>
> Automation Engine version 24 introduces substantial updates to the AE REST
> API.
>
> Most notably, v24 adds the ability to create, read, update, and delete
> <https: en.wikipedia.org/wiki/create,_read,_update_and_delete=""> objects.
> The documentation page Using the AR REST API
> <https: docs.automic.com/documentation/webhelp/english/all/components/docu/24.0/automic%20automation%20guides/content/rest_api/ae_rest_api_using.htm="">
> provides examples for many things, but not these "CRUD" operations. I did
> some basic tests to figure out how it works.
> *Operation*
> *HTTP method & AE REST API endpoint* *Body*
> Create
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/post="">
> ​*POST* /{client_id}​/objects
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/post=""> Complete
> JSON object definition
> Read *GET* /{client_id}/objects/{object_name}
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/get="">
> NA
> Update *PATCH* /{client_id}/objects/{object_name}
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/patch=""> Partial
> JSON object definition. Omit *type*, *name*, and *path *properties.
> Delete *DELETE* /{client_id}/objects/{object_name}
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/delete="">
> NA
>
> The GET method is essentially equivalent to an XML export, with providing
> a JSON payload instead of XML.
>
> Similarly, the POST method is essentially equivalent to an XML import, but
> requiring JSON instead of XML as the payload.
>
> The PATCH method is interesting, because it offers the ability to change *just
> one property* of an object. You do this by providing only the portion of
> the JSON object schema that corresponds to the property you wish to change.
>
> For example, if you wanted to change the queue of an SCRI object, you can
> use the PATCH method and provide the following JSON in the body of the
> request.
> { "total" : 1, "data" : { "scri" : { "general_attributes" : { "queue" :
> "NEW_QUEUE" } } } }
>
> The remainder of the JSON object schema is irrelevant and can be omitted.
> When using the PATCH method, the properties *type,* *name, *and *path*
> must be omitted. It is not possible to change the type of an existing
> objects.
>
> If you want to move or duplicate an object, there are dedicated API
> endpoints for these operations.
> *Operation*
> *HTTP method & AE REST API endpoint* *Body*
> Move *PATCH* /{client_id}/objects/{object_name}/move
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/moveobject_1=""> {
> "target_path": "FOLDER/SUBFOLDER" }
> Duplicate
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/post="">
> ​*POST* /{client_id}​/objects/{object_name}/duplicate
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/duplicate=""> {
> "name": "NEW_OBJECT_NAME", "title": "New object description", "path":
> "FOLDER/SUBFOLDER" }
> Rename ?
> ?
>
> I have not found a way to rename an existing object using the AE REST API
> (other than exporting, deleting, and importing).
> *Reply to Group Online
> <https: community.broadcom.com/communities/all-discussions/postreply?messagekey="6f35e1ea-b927-49bb-8a25-a158f1d17604&ListKey=7e4de604-f950-4e81-9d19-4e72b8898fb4">*
> *Reply to Group via Email
> <broadco[e-mail]?subject=re:+ae+v24+rest+api>*
> *View Thread
> <https: community.broadcom.com/discussion/ae-v24-rest-api#bm6f35e1ea-b927-49bb-8a25-a158f1d17604="">*
> *Recommend
> <https: community.broadcom.com:443/discussion/ae-v24-rest-api?messagekey="6f35e1ea-b927-49bb-8a25-a158f1d17604&cmd=rate&cmdarg=add#bm6f35e1ea-b927-49bb-8a25-a158f1d17604">*
> *Forward
> <https: community.broadcom.com/communities/all-discussions/forwardmessages?messagekey="6f35e1ea-b927-49bb-8a25-a158f1d17604&ListKey=7e4de604-f950-4e81-9d19-4e72b8898fb4">*
> *Flag as Inappropriate
> <https: community.broadcom.com/discussion/ae-v24-rest-api?markappropriate="6f35e1ea-b927-49bb-8a25-a158f1d17604#bm6f35e1ea-b927-49bb-8a25-a158f1d17604">*
>
>
>
>
> You are subscribed to "Automic Workload Automation" as
> [e-mail]. To change your subscriptions, go to My
> Subscriptions
> <http: community.broadcom.com/preferences?section="Subscriptions">. To
> unsubscribe from this community discussion, go to Unsubscribe
> <http: community.broadcom.com/higherlogic/egroups/unsubscribe.aspx?userkey="bbc24d99-5ad5-4b6f-bbc3-8eab5b500688&sKey=KeyRemoved&GroupKey=7e4de604-f950-4e81-9d19-4e72b8898fb4">.
>
>
> Copyright © 2005-2023 Broadcom. All Rights Reserved. The term "Broadcom"
> refers to Broadcom Inc. and/or its subsidiaries.
>
> Hosted by Higher Logic, LLC on the behalf of Broadcom - Privacy Policy
> <https: www.broadcom.com/company/legal/privacy-policy=""> | Cookie Policy
> <https: www.higherlogic.com/legal/privacy=""> | Supply Chain Transparency
> <https: www.broadcom.com/company/citizenship/governance-and-ethics#supply="">
> | Terms of Use <http: termsandconditions="">
>


--
Thanks & Regards,
Sivanesan
9094570061

[Michael A. Lowry]

Take a look at the POST /{client_id}/executions endpoint.

[Martin Uferbach]

With V24.0 the following renaming action is supported: https://docs.automic.com/documentation/webhelp/english/AA/24.0/DOCU/24.0/REST%20API/Automation.Engine/index.html?overrideUrls=../Automation.Engine/swagger.json,../Continuous.Delivery.Automation/swagger.json,../Analytics/swagger.json,../Infrastructure.Manager/swagger.json#/system%20agents/rename

But this is pure renaming without considering "search for use" dependencies that will follow in future releases.

------------------------------
Product Owner for Automic Automation
Broadcom
Austria
------------------------------

[Michael A. Lowry]

Hi @Martin Uferbach. Thanks for the reply.

The POST /{client_id}/system/agents/{object_name}/rename endpoint appears to be limited to renaming agents. Is there a way to rename other object types? (Perhaps that too will come in a later release.)

[Martin Uferbach]

Hi @Michael A. Lowry, unfortunately this is the only one at the moment. Indeed, it's more of an agent management endpoint than a general object renaming one. As renaming used objects most likely a complex "search for use" challenge is involved we need to consider when providing a general renaming functionality. Yes, such a powerful renaming functionality via REST API is planned for future release.

------------------------------
Product Owner for Automic Automation
Broadcom
Austria
------------------------------

[Joel Wiesmann]

Hi @Martin Uferbach

So the REST implementation is completely independant of the JAVA API? I mean, basically it could be implemented like a wrapper/converter.

Regards
Joel

------------------------------
☎️ Swisscom Automation Engineer & 🧙 PE Membership Creator

Automic Kurse, Tutorials, Tools und mehr auf:
https://membership.philippelmer.com/
Zwei Wochen kostenlos testen!
------------------------------

[Michael A. Lowry]

Hi @Joel Wiesmann.

The AE REST Process is implemented in Java. It might be performing some actions via the AE Java API, but a DB trace also reveals plenty of direct DB activity.

[Martin Uferbach]

Hi @Joel Wiesmann, 

Yes, the two interfaces JavaAPI and AE REST API are basically completely separated/decoupled - both code-wise and business case-wise (in other words, the AE REST API is no "copy" of the JavaAPI providing exactly the same just in a different way).

The goal is to provide a modern state-of-the-art interface via AE REST API that offers at some point in time in the future an equal functional range as the JavaAPI that fits today's needs. At the moment there are no plans/no ETA to replace/sunset the JavaAPI. 

The functional range of the AE REST API is successively extended/enriched version by version.

Kind regards,

Martin 

------------------------------
Product Owner for Automic Automation
Broadcom
Austria
------------------------------

[Steven Blumenkrantz]

We just upgraded to v21 fairly recently and I've been looking at the v21 REST API, looking for some examples, etc as the Broadcom documentation is difficult to wade through to find anything useful to get started.  I am working on a "project" to use the REST API to recursively delete folders.  This post leads me to believe that I can't do that with v21. Is that the case?

I read that v24 will support deleting folders containing subfolders so my "project" won't really mean anything after we upgrade, but I'd still like to see how I would do that with the REST API. ANy pointers or examples related to what I want to do would be greatly appreciated.

[Steven Blumenkrantz]

I am trying to automate adding an existing agent to an agent group in a client but can't seem to get it right. Any help would be greatly appreciated! My questions are:

1. Does this functionality exist in Automic v24?
2. If it does, has anyone done this and would you share your code with me?
3. Is there any documentation on the REST API out there that's better than Broadcom's?
4. Here is what Copilot gave me, but doesn't work. Any suggestions, other than stop using Copilot :-)

# This script adds an agent to an agent group membership using the AE REST API.
REST_ENDPOINT="< <https: aoa-rest.idx-pl-live.eislz.com>endPoint>"
CLIENT="<clientnumber>"
AGENTGROUP_ID="WINDOWS_POOL"
AGENT_ID="<agentname>"
read -sp "Enter password: " PASSWORD
AE_USER_PW="<username>:$PASSWORD"

# JSON payload
PAYLOAD=$(cat << />
{
"agent_id": "${AGENT_ID}"
}
EOF
)

echo "Adding agent $NEW_AGENT to Agent Group $AGENT_GROUP for client $CLIENT"
URL="$REST_ENDPOINT/ae/api/v1/${CLIENT}/agentgroups/${AGENTGROUP_ID}/agents"
response=$(curl -X POST "${URL}" \
--header "Content-Type: application/json" \
--user "$AE_USER_PW" \
--data "${PAYLOAD}")
# Output the response
echo "Response: ${response}"
# Check if the response contains an error
if echo "$response" | grep -q '"error"'; then
echo "Error adding agent to agent group: $response"
else
echo "Agent added successfully."
fi

I get the following output:

Adding agent to Agent Group for client <clientnumber>
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 160 100 125 100 35 1157 324 --:--:-- --:--:-- --:--:-- 1481
Response: {
"code" : 45109,
"error" : "The requested resource cannot be found.",
"details" : "No detail information available."
}
Error adding agent to agent group: {
"code" : 45109,
"error" : "The requested resource cannot be found.",
"details" : "No detail information available."
}

[Steven Blumenkrantz]

We just upgraded to v21 fairly recently and I've been looking at the v21 REST API, looking for some examples, etc as the Broadcom documentation is difficult to wade through to find anything useful to get started.  I am working on a "project" to use the REST API to recursively delete folders.  This post leads me to believe that I can't do that with v21. Is that the case?

I read that v24 will support deleting folders containing subfolders so my "project" won't really mean anything after we upgrade, but I'd still like to see how I would do that with the REST API. ANy pointers or examples related to what I want to do would be greatly appreciated.

[Martin Uferbach]

Hi @Steven Blumenkrantz, yes, we offer a delete folder functionality in V24. Please check out the online swagger docu ->  https://docs.automic.com/documentation/webhelp/english/AA/24.0/DOCU/24.0/REST%20API/Automation.Engine/index.html?overrideUrls=../Automation.Engine/swagger.json,../Continuous.Delivery.Automation/swagger.json,../Analytics/swagger.json,../Infrastructure.Manager/swagger.json#/folder%20objects/deleteFolderObjects

The {folder_path} in the URL has to be encoded like "FOLDER%2FSUBPATH%2FANOTHERSUBPATH" where %2F represents "/" as folder separator and then ends up as "FOLDER/SUBPATH/ANOTHERSUBPATH" in the logic.

(As the current example in the swagger docu doesn't point the %2F part out, we will extend it so that this gets more clear)

 

------------------------------
Product Owner for Automic Automation
Broadcom
Austria
------------------------------