Webex Admin Functions
via Control Hub

The next few sections will take you through the steps implement a variety of capabilities allowing your portal to interact with Webex APIs. To achieve these goals, you will start with the following steps:

  1. Add your Service App Client ID, Secret, and Refresh Token to the Environment.
  2. Look up the user by email, get their user object ID and, with that, look up the user's details, including all Webex Calling information.
  3. Retrieve all licenses, then find the object ID of a Webex Calling and On-prem UCM licenses.
  4. Webex Calling users must be associated with a Location, so the object ID of a desired location must be retrieved.
  5. Update the user, modifying the licenses and updating their location.

Step 1 - Add your Service App Client ID, Secret, and Refresh Token to the Environment

In the example you completed earlier, you obtained an access token using a Service App client ID, client secret, and refresh token. This enabled administrative access to Webex. In this section, you will use the information you obtained previously to enable your Portal to perform administrative tasks in Webex as well.

  1. Access your VS Code instance: https://dev1.pod6.col.lab:8443 and from the Explorer open BOTH of the following files:
    • examples\service_app.py; and
    • .env
  2. In examples\service_app.py, find and copy the values of the Service App variables and copy them to the corresponding variables in the .env file:

    Source Variable (examples\service_app.py) Destination Setting (.env)
    client_id='Ca083181a235caf__Your_Client_ID__caff336f93cd1ded' SERVICE_APP_CLIENT_ID='___PASTE_SERVICE_APP_CLIENT_ID___'
    client_secret='083181aCa083181a__Your_Client_Secret__1a23181a2ca' SERVICE_APP_CLIENT_SECRET='___PASTE_SERVICE_APP_CLIENT_SECRET___'
    refresh_token='Q4ZG1NmIa__Your_Refresh_Token__-733-48f-86f-be4d' SERVICE_APP_REFRESH_TOKEN='___PASTE_SERVICE_APP_REFRESH_TOKEN___'
  3. Save the .env file

Step 2 - Look up Person Details

Now you can start using the wxc_sdk in your project.

  1. In your VS Code tab, open up flaskr/api/v1/wbxc.py using the Explorer.
  2. In the earlier examples, you ran the service_app.py script to create an access token, which you then manually pasted into the wxc_enable_user.py file. The access token was then used to instantiate a wxc_sdk instance to be able to access the Webex APIs.

    To handle this automatically, we have created a class:

    In this code, self.get_tokens() will either read a set of access/refresh tokens from a file, or use the environment variables you set above. If an access token is about to expire or isn't found to begin with, then the refresh token will be used to create a new access token, as you did in the example. The access token is then used to create an instance of the API. By placing this token refresh capability in this class, each time a new instance of this ServiceApp class is instantiated, the token may be refreshed, if needed, as long as the refresh token has not expired.

    To create an instance of the ServiceApp class, you just need this single line of code:

    In previous examples, you had created a variable named api which contained an instance of the WebexSimpleApi class and used it to perform API calls like this:

    You will be using the sa instance of the ServiceApp class to perform the same API calls. The ServiceApp() class calls the WebexSimpleApi class for you but before doing so, it will check if the access token is still valid and refresh it if needed. You can perform the same people list call like this:

    Note the use of sa.api.people.list() instead of api.people.list().

    If you would like to explore in more detail how the ServiceApp() class works, you can look at the code in the flaskr/api/v1/service_app/__init__.py file.

    Now you are ready to add to the portal code. Remove the pass from the section in get_person_det and replace with the following:

    The get_person_det() function takes an email address as an argument and returns the detailed user information for a user with that email address. This code is very similar to what you did in the previous examples. It creates a new instance of the ServiceApp class, then uses it to look up a user using the people.list() API and then retrieves the detailed user information using the people.details() API.

  3. The wbxc.py file already contains a class named wbxc_user_api that will be called when the /wbxc/user/<userid> API is called on your Portal API. Extend it to report success or failure based on the get_person_det() results. Any RestError exceptions that may be generated by the wxc_sdk are already handled.

    Now if your Portal API receives a request on the /user/<userid> endpoint, it will look up that user in Webex and return the result as JSON. If the user is not found, it will return an error message.

Step 3 - Enabling a User for Webex Calling

  1. This section will add the code to enable a user for Webex Calling. Find the class wbxc_user_enable_api() section in the flaskr/api/v1/wbxc.py file. You will be updating the put method.

    The put accespt a single argument, the userid which is the user's email address. The first step to enabling a user for Webex Calling is to get the detailed user information by calling get_person_det() method that you just implemented, then look up the Webex Calling Professional and On-Prem UCM licenses. Since this is also a common task, a get_lic_by_name() function was created to look up the respective license in the same way you did in the earlier example sections. Next, query the Location to which this user and number will be assigned. Following this, look up the user's phone number, which should already be pre-populated based on what was synchronized to the account from the Active Directory via the Directory Connector. If no number is found for the user, return an error. This is an area that could require a lot of custom enhancements. For example, you could use APIs to look for available numbers in the location and assign the next available number to the user.

    Add the following to your code:

  2. Check to see if the user is already enabled for Webex Calling and if they are not, prepare the user by adding the Webex Calling Professional license and removing the On-prem UCM license, then set the location and update the person.

    Add the following to your code and then examine it. The comments in the code explain what each step does.

  3. Save this file
  4. In VS Code, start (or restart) your Flask app by clicking Debug > Start Debugging (or Restart Debugging, if already started).

The put method in the wbxc_user_disable_api class has already beeen implemented for you. This function is used to disable Webex Calling and just does the opposite of the steps you just perfromed. The function looks up the user details and the license, exactly as before, then removes the Webex Calling License and adds the Unified Communication Manager (UCM) license. The only other difference is that since removing the Webex Calling license also removes the phone number, you can simply save that data before updating the user's license and then running another update to the user afterwards to re-apply the phone number. You can look at the code in the wbxc_user_disable_api medthod if you want to see the exact code that does this.

Step 4 - Try it out

First test retrieving a user.

  1. Point your browser to the Portal API page - http://dev1.pod6.col.lab:5000/api/v1/
  2. Expand wbxc
  3. Click the GET request with the URI "/wbxc/user/{userid} Retrieve a user in WbxC by user id"
  4. Click Try it out at the right
  5. In the userid field, enter the userid pod6wbxuser
  6. Click Execute
  7. You should see a 200 response code and a successful message, with the entire user object being printed out in the Response body.

In a previous section of this lab, you enabled Webex Calling features for the user pod6wbxuser. To test the code you just implemented, you will first disable Webex Calling for this user, then re-enable it.

  1. While still in the wbxc section of your Portal API page, click the PUT request with the URI "/wbxc/user/disable/{userid}" and description "Disable a Webex Calling Person by user ID."
  2. Click Try it out at the right
  3. In the userid field, enter the userid pod6wbxuser
  4. Click Execute
  5. You should see a 200 response code and a successful message, with a message indicating Successfully disabled Webex Calling for user pod6wbxuser.
  6. The Webex app should be already running on your PC. Within a few seconds of disabling Webex Calling, you should see the bottom left corner of the Webex App show an error indicating "Phone services are disconnected".

Now go through the steps to re-enable Webex Calling on the phone using the API you created.

  1. Point your browser to the Portal API page - http://dev1.pod6.col.lab:5000/api/v1/
  2. Expand wbxc
  3. Remain in the wbxc section of your Portal API page and find the PUT request with the URI "/wbxc/user/enable/{userid}" and description "Enable a Person for Webex Calling by user ID".
  4. Click Try it out at the right
  5. Make sure the location field is set to your Pod number.
  6. In the userid field, enter the userid pod6wbxuser
  7. Click Execute
  8. You should see a 200 response code and a successful message, with the entire user object being printed out in the Response body.

  9. To get phone services back up and running quickly after re-enabling Webex calling, sign out of your Webex App, then sign in again with pod6wbxuser@collab-api.com and password: C1sco.123 . You must sign out and sign back in for the call to work.
  10. Once signed in, you should see the Call Settings in the bottom left corner. There should be no "Phone services are disconnected" or similar errors.

  11. In the Webex app, click the PU icon at top left. Click Settings, then click Phone Service. Make sure it shows Webex Calling and connected.

  12. Click the following to place a call: +19197061111. This calls another UCM-registered phone via a CUBE Local gateway between Cisco Webex and your pod's Unified CM.

Webex Calling has a vast amount of configuration exposed via the API. From placing calls to configuring call handling, many things can be automated and simplified depending on your requirements. In the next section, you will take a look at using a Bot to send notifications as well as receive commands that can execute some of the same APIs that you have already implemented.


Note: You will need to have a valid access token for this to work.