Pondering Automation: Let’s make some BCS magic!

Howdy out there in automation land! It has been a while since my last blog, and new and exciting things continue to happen. (Hence the lack of blogs.) I’m hopeful this kicks off the summer on a hot foot and we get plenty out there. To let you know about some of the new work I’ve been taking on, I wanted to bring you something from the land of Business Critical Services (BCS). This is a new arena I have entered so I wanted to share with you some foundational pieces of automation goodness! So we are going to take a stab at a few things in this blog…

1. Building some amazing Atomics for an API in SecureX Orchestration!
2. Building workflows geared towards our BCS Operational Insights API!
3. Being able to map given code (in this case python) to SXO workflows
4. Giving some best practices around workflow and atomic creation
5. Sharing with the readers a ton of pre-built content you can use to accelerate your BCS automation work

Before I get to our great content of the day, I have a few things to share. The first one is that Cisco Live is back and will be in person in fabulous Las Vegas! And yes readers, I will be there ready to teach you all about automation and orchestration. I will be teaching a 4 hour lab that you can find at LTRATO-1000. In the lab I will be teaching alongside my awesome friend and co-automation expert, Mohammed Hamzeh. Space is limited and a few spots are still there so sign up today! Secondly, another cool thing I’ve started to work on is a podcast that we have started (again, hence less blogs). This podcast is around bringing the best Cisco minds to you the listening audience and our customers. The podcast is called Cisco Tech Insiders and you can find it on SoundCloud (look for our logo… its a microphone with Cisco Tech Insiders next to it) or on Spotify. I highly would suggest some listens and see if anything we talk about excites you. As always, you can suggest things via email to me or comments on the blog.

Like I said… let’s make some magic! So time to concentrate on what we are going to do today and that is to build some atomics off of some python code from DevNet and help us start to build out an API set or “Atomic Adapter” for BCS Operational Insights API.

To start with any API, we need to find Authentication and Documentation on the API Spec. Thankfully, this is a well done API and we have both! Authentication is done via Client Secret+Client ID into a JWT token…. we can find the information we need here…

1. Authentication
2. OpenAPI Spec

Note: Prior to doing some of the API greatness you will need to go through the On-boarding Process and Application Registration so you can get your Client ID and Client Secret to authenticate with the API. Registration will make use of the CX Cloud API Gateway! More exciting technology for you to use. If you have any issues getting on boarded or in the application registration process please reach out to your BCS Account Project Manager and/or associated Consulting Engineers on your project.

So let’s take a look at the Authentication part first and some sample Python code. We are going to semi-map this code to SXO activities in a workflow. The python code does not belong to me and I am not the author, so I am linking it here for your reference.

The steps we need for Authentication (assuming you have your client id and client secret) are…

1. Make API call to the token endpoint
2. Extract and keep token from API return

In python to call the API we might do something like this (in python):

url = f'https://{server}/torii-auth/v1/token'

    data = {
        "grantType": "client_credentials",
        "clientId": client_id,
        "secret": client_secret,
        "scope": "api.bcs.manage"
    }

    try:
        resp = httpx.Client().post(url=url, json=data)
        resp.raise_for_status()
    except (httpx.HTTPStatusError, httpx.RequestError) as err:
        logger.error(
            f'Failed to JSON Web Token(JWT): {err}'
        )
        raise err
    else:
        return resp.json().get('accessToken')

To map this to SXO we need to…

So let’s walk through building those pieces…

How To Build a JWT Token Atomic

1. Go to SXO and select Targets on the left menu
2. Click NEW TARGET and pick HTTP Endpoint. Call it BCS Operational Insights Auth API
3. Set NO ACCOUNT KEYS to true. Set PROTOCOL to HTTPS, HOST/IP to api-cx.cisco.com and PATH to /torii-auth/v1/. You can see all of these values in the Python script as well. Click SUBMIT.
4. Click the Workflows on the left menu and then click NEW WORKFLOW
5. On the far right under VARIABLES, click ADD VARIABLE and add a STRING called I_client_id, make it required and make its SCOPE to be input. Add a SECURE STRING called I_client_secret, make it required and make its SCOPE to be input.
   
6. Then add another variable SECURE STRING. Call it O_jwt_token and make its SCOPE to be output.
   
7. In the TARGET section, select EXECUTE ON THIS TARGET and select the target type of HTTP ENDPOINT and then select the target you created above.
8. This is part where we handle step 2 and 3 above from the python to SXO conversion table. On the toolbar search for HTTP Request, then drag and drop one onto your workflow canvas.
9. Click on the activity you just dragged and dropped and you will be able to configure it on the right side of your window.
10. On the activity set the RELATIVE URL to token , the METHOD to post, and the REQUEST BODY should mirror what is in the example. It should like this…
    {"grantType": "client_credentials", "clientId": "", "secret": "", "scope": "api.bcs.manage" }

11. As you see I left the clientId and secret blank. This is because we want to pass variables into those fields, so you can copy the above into the REQUEST BODY field and hit the format button to make it look nice!
12. To pass in the variables we need to click the puzzle piece icon in that field. This is the insert variable reference icon. Once you click that, navigate to Workflow->input->I_client_id for the client id field and Workflow->input->I_client_secret for the secret. Set the content type to JSON.
    
13. Next we want to parse the token out and save it to a secure string. Search for the JSONPath Query activity and drag and drop it below your HTTP Request activity.
14. Click on the JSONPath activity. In the SOURCE JSON TO QUERY, click the puzzle piece icon and select Activities->Your HTTP Request ->Body and save. Click +ADD below that field and then in the JSONPATH QUERY field enter $..accessToken and then just accessToken for the PROPERTY NAME. Set it to type SECURE STRING.
    
15. Lastly, look for the SET VARIABLE activity and drag and drop it below the JSONPath query. Click +ADD and in the VARIABLE TO UPDATE, click the puzzle piece icon and select Workflow->output->O_jwt_token. In the NEW VALUE field, click the puzzle piece icon and select Activities->JSONPATH Query Activity->accessToken.
16. Your workflow is complete! You should be able to validate it and click run. Input your client id and secret and it will generate a token for you!

Now I would be a poor instructor if I did not include a final result for you to view alongside what we just stepped through… so I have plenty of that upcoming for you. As they say in cooking shows, “always have a pre-baked turkey to go along with the one you are baking.” To help everyone out I have built an entire atomic adapter for you to use for BCS Operational Insights! (not just a JWT generator). Just like you importing a package or copying and pasting sample code you will have all of my workflows for you to use and build cool BCS automations. (or MAGIC!) You can find them on the Shared CX SXO Repo and in time they will be published to the official SXO atomics git. To make this *even* better you will find some sample usage workflows on the Shared CX SXO Repo to help you get started. These include the demo I will show in the blog video (you did not think you would not get a video right???) and an example workflow that would refresh your JWT token in the background instead of you having to re-call it each time you want to use the API. These are still an opensource style nature workflows and atomics so if you have issues, please let me know!

So I know I just spoiled the fun… but as always…

On to the Video!!!

Pondering Automation Demo of BCS Operational Insights API

Password: There is no password!

Standard End-O-Blog Disclaimer:

Thanks as always to all my wonderful readers and those who continue to stick with and use SXO! I have always wanted to find good questions, scenarios, stories, etc… if you have a question, please ask, if you want to see more, please ask… if you have topic ideas that you want me to blog on, Please ask! I am happy to cater to the readers and make this the best blog you will find

AUTOMATION BLOG DISCLAIMER: As always, this is a blog and my (Shaun Roberts) thoughts on SXO, orchestration, development, devops, and automation, my thoughts on best practices, and my experiences with the products and customers. The above views are in no way representative of Cisco or any of it’s partners, etc. None of these views, etc are supported and this is not a place to find standard product support. If you need standard product support please do so via the current call in numbers on Cisco.com or email tac@cisco.com

Thanks and Happy Automating!!!

— Shaun Roberts,  shaurobe@cisco.com 

We’d love to hear what you think. Ask a question or leave a comment below.
And stay connected with Cisco DevNet on social!

LinkedIn | Twitter @CiscoDevNet | Facebook | Developer Video Channel

Share: