Howdy|out|there|in automation land! It has been a while since my last blog,andnew and exciting things continuetohappen. (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 thelab 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 iscalledCisco 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. ClickNEW TARGETand pick HTTP Endpoint. Call itBCS Operational Insights Auth API
3. SetNO ACCOUNT KEYSto true. SetPROTOCOLto HTTPS,HOST/IPto api-cx.cisco.com andPATHto /torii-auth/v1/. You can see all of these values in the Python script as well. ClickSUBMIT.
   
4. Click the Workflows on the left menu and then clickNEW WORKFLOW
5. On the far right underVARIABLES, clickADD VARIABLEand add aSTRINGcalledI_client_id, make it required and make itsSCOPEto be input. Add aSECURE STRING called I_client_secret, make it required and make itsSCOPEto be input.
   
6. Then add another variableSECURE STRING. Call it O_jwt_tokenand make itsSCOPEto be output.
   
7. In the TARGETsection, selectEXECUTE ON THIS TARGETand select the target type ofHTTP ENDPOINTand 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 forHTTP 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 theRELATIVE URL to token, theMETHODto post, and theREQUEST BODYshould 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 theclientId and secretblank. This is because we want to pass variables into those fields, so you can copy the above into theREQUEST BODYfield 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 toWorkflow->input->I_client_idfor the client id field andWorkflow->input->I_client_secretfor the secret. Set the content type to JSON.
    
13. Next we want to parse the token out and save it to a secure string. Searchfor theJSONPath Query activity and drag and drop it below your HTTP Request activity.
14. Click on the JSONPath activity. In theSOURCE JSON TO QUERY, click the puzzle piece icon and selectActivities->Your HTTP Request ->Bodyand save. Click+ADDbelow that field and then in theJSONPATH QUERYfield enter$..accessTokenand then justaccessToken for the PROPERTY NAME. Set it to typeSECURE STRING.
    
15. Lastly, look for theSET VARIABLEactivity and drag and drop it below the JSONPath query. Click+ADDand in theVARIABLE TO UPDATE, click the puzzle piece icon and selectWorkflow->output->O_jwt_token. In theNEW VALUEfield, 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 [email protected]

Thanks and Happy Automating!!!

- Shaun Roberts,  [email protected] 

Join our daily livestream from the DevNet Zone during Cisco Live!

Stay Informed!

Sign up for theDevNet Zone Cisco Live Email Newsand be the first to know about special sessions and surprises whether you are attending in person or will engage with us online.

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 | YouTube Channel