Webex Admin Functions
via Control Hub

The Cisco Webex API documentation in conjunction with the wxc_sdk documentation allows you to implement business logic in a programmatic fashion. Now you will essentially embed your code, along with some error handling, into the Flask application framework provided.

In your portal, you will perform 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:

    Then to execute queries instead of using the api variable which represents the WebexSimpleApi class like this:

    you can use do the following:

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

    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:

  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 back-end. 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.

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 method already has code to read in the arguments passed in the HTTP REST request to Flask. In this case the argument is the userid field. The first step to to enabling a user for Webex Calling is to get the detailed user information by calling get_person_det(), then look up the Webex Pro 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 add and/or activate numbers in Webex Calling as they must first exist there before they can be assigned to a 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 Pro license and removing the On-prem UCM license, then set the location and update the person.

    Add the following to your code:

  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. Sign out by clicking on the logged in user's profile and settings on the top left of the Webex Client application window.
  7. Log in using email: pod6wbxuser@collab-api.com and password: C1sco.123

    You will be able to log in, however, there should not be phone services available because you deleted the CSF device for this user in a previous section.

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. 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.

  8. As a final test, 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.
  9. 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.

  10. 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.

  11. 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 notification, as well as receive commands that can execute some of the same APIs that you have already programmed.

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