REST API: Uploading the jar of an RA Solution

Products

• CA Automic Workload Automation - Automation Engine

Issue/Introduction

The documentation of the REST endpoint POST http[s]://{host}:{port}/ae/api/v1/0/system/ra-solutions can be found here:

https://docs.automic.com/documentation/webhelp/english/AA/21.0/DOCU/21.0.12/REST%20API/Automation.Engine/index.html?overrideUrls=../Automation.Engine/swagger.json,../Continuous.Delivery.Automation/swagger.json,../Analytics/swagger.json,../Infrastructure.Manager/swagger.json#operations-system-installOrUpdate

And the documentation of the REST endpoint POST http[s]://{host}:{port}/ae/api/v1/0/system/ra-solutions/0/system/ra-solutions/update here:

https://docs.automic.com/documentation/webhelp/english/AA/21.0/DOCU/21.0.12/REST%20API/Automation.Engine/index.html?overrideUrls=../Automation.Engine/swagger.json,../Continuous.Delivery.Automation/swagger.json,../Analytics/swagger.json,../Infrastructure.Manager/swagger.json#operations-system-upload

The latter can be used through a curl command as documented, which is by far the easiest way to upload an RA solution through the REST endpoint.

However, if you want to 

• use an API development tool like Postman,
• encode the jar-file 

... the details on how to use the above endpoints are not straightforward from the Swagger documentation. 

Environment

v21.0 (later versions) or v24.x

Resolution

1/ Using POST http[s]://{host}:{port}/ae/api/v1/0/system/ra-solutions/0/system/ra-solutions/update in Postman:

The trick to understanding how this works is importing the Swagger documentation into Postman. This shows that:

• the jar-file is passed into the query as the body with type binary
• all other parameters, normally added to the body, are passed in the request's header while Content-Type is set to application/octet-stream.

So the header should look like this:

Key	Value
Content-Type	application/octet-stream
checksum	3d207bd3ccb6f01e7cd22fa810cbac1a
algorithm	MD5 (or SHA256)
Authorization	•••••• (this information comes from the Auth tab)

 

2/ Using POST http[s]://{host}:{port}/ae/api/v1/0/system/ra-solutions/0/system/ra-solutions 

This method is more laborious because the jar-file needs to be base64 encoded ahead of time which may contain pitfalls the first time around.

The encoding needs to be done in such a way that the result is a one-line string, so without linefeeds, this can be done as follows:

1. Calculate the MD5 or SHA256 hash of the jar-file
   • On Linux: md5sum <RA.solution>.jar or sha256sum <RA.solution>.jar  
   • On Powershell: Get-FileHash -Path "<RA.solution>.jar" -Algorithm MD5|SHA256
2. Encode the <RA.solution>.jar
   • On Linux: base64 <RA.solution>.jar -w 0 (the -w 0 option prevents wrapping)

Subsequently, the body of the request should look like this:

{
  "solution": "UEsDBBQACAgIAKJcTVYAAAAAAAAAAAAAAAAUAAAATUVUQS1JTkYvTUFOSUZFU1QuTUa9kkuPokAQ...",
  "checksum": "566a36a08b0c8a145693f5cd6693fc8b",
  "algorithm": "MD5",
}

IMPORTANT: the 'ignore-signature' option that was previously documented is obsolete and should not be used anymore: The reason for this is that since the second half of 2024 jar-files are not signed anymore, so using this option can lead to an error. See also, this KB.