Calling the Ansible Automation Platform API Using 'Friendly' Job Template Names

Have you ever wanted to call the AAP/Tower API to launch a Job Template? The REST API allows you to do that, fast and efficiently. This means you can integrate AAP with orchestrator tools, like ServiceNow for instance.

AAP uses a Postgres database behind the scenes. When you create a Job Template, it gets a unique 'primary key' or id. You'll see this id in the Tower GUI, when you look at a Job Template:

You can see here that the id for my openshift_example Job Template is 68.

This is great. With the right access, we can make a call into the API and launch this job. But what if we have a number of platforms, and want to make sure our ids stay consistent when we create or recreate them? Well, you can't (and don't even *think* about trying to alter the database primary keys because you'll break things). But you can call the Job Template using Named URLs.

That documentation is a little hard to get your head around, hence this blog to give you an example usage to demonstrate :)

So we have a Job Template we'd like to launch through the AAP API in place - openshift_example. We need authorised access to make the call. You can use a username/password combo for this, but better to setup and use a Personal Access Token (PAT). So let's see how we do that now.

Creating A PAT

Go into the GUI Users section, select your user (in my case admin) and click Tokens:

Click the green + icon to create a new token:

Fill out the Description and make the scope Write:

When you click SAVE, you'll get presented with the PAT token. This is the only time you'll see this and you won't be able to edit it so make sure you save the details!

We'll use this PAT token now to make the remote API call.

Remote AAP Job Template Launch

I'm going to use curl from the command line to demonstrate this, so you'll get to see the format of the call, which is sometimes the hard part to figure out!

I'm also going to use the fantastic 'jq' utility to help parse the output coming back, so I can get the job id and then query for it's status.

Now at the moment I can launch Job Template id 68. But we want to use the friendly template name to keep things consistent, when, or if, the id changes. So we can use the named URL facility for this.

According to the docs... "Suppose you want to manually determine the named URL for a label with ID 5. A typical procedure of composing a named URL for this specific resource object using NAMED_URL_FORMATS is to first look up the labels field of NAMED_URL_FORMATS to get the identifier format <name>++<organization.name>"

Blimey. That could be a lot easier to understand! But this means we can use job_template_name++organsation_name in the API call, in place of the id.

So, to fire off a Job Template launch, we can use:

curl -s -k -X POST -H "Authorization: Bearer YOUR-PAT-TOKEN" -H "Content-Type: application/json" https://YOUR-TOWER-HOST/api/v2/job_templates/openshift_example++Default/launch/ | jq .job
2014

Let's break that down.

We need to make a -X POST HTTP request into the API.

I'm telling curl to be silent and ignore cert errors with -s -k

We pass YOUR-PAT-TOKEN as a Bearer token as a HTTP Header request.

Likewise, we make sure that the Content-type is as expected, application/json

The actual request is in the https://YOUR-TOWER-HOST section, ending with a /launch/

I then tell jq to get the job number, which is 2014.

If you look in AAP now, you'll see that in the Jobs output.

If you need to query the output, you then leave off the | jq part, and you'll get a whole load of information coming back.

If you want to just query the status of the job, we can make a HTTP GET request back into the API for that:

curl -s -k -X GET -H "Authorization: Bearer YOUR-PAT-TOKEN" -H "Content-Type: application/json" https://YOUR-TOWER-HOST/api/v2/jobs/2014/ | jq .status
"running"

You can see mine's running still. Keep making a few more calls to see the final status.

That's it. Quite simple but effective!

I hope that was useful for you. Happy automating!