cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
1827
Views
5
Helpful
7
Replies

APIs Flags on UCCX9 for time of day

richard.jackson
Level 1
Level 1

Hi,

I was discussing UCCX and our upgrades to V9 for a few of our customers with a Voice CCIE at an event a few days ago, and was explaining that  our customers found the configured time of day and holidays  in scripts was very restricting. They want the ability to upload holidays and early close the call centre via a Web interface. I advised that was looking into doing this via a SQL server running a stored procedure fired from a script; however this would not be possible with our clients on the enhanced license.

The CCIE mentioned that in UCCX v9 we can use APIs to set flags and reference these in scripts. I have has a trawl of the Web but cannot find any reference to this. Can someone point me in the right direction where I can find :-

a) How to reference these flags in scripts – I am more than happy to write the script logic

b) Info to pass to our Developer on how to integrate with APIs to set these flags.

1 Accepted Solution

Accepted Solutions

Anthony Holloway
Cisco Employee
Cisco Employee

Hi, first thing first, you should see this post, which lays out for you how to integrate UCCX Enhanced with an external DB via a "man in the middle" web server.

https://supportforums.cisco.com/docs/DOC-29776

Long story short, tell your developer to build a URL for accessing calendar and business hours logic in various formats: XML, JSON, HTML, etc.  You'll use XML, but asking them for more opens your options down the road.

Next up, the API's.  These are pretty new to UCCX, with v9.0 bringing the first round of access and then v10 coming in behind with even more access.

Normally, when I don't know the answer to a question on the forums, I go research it, and sometimes proof of concept it, and then post my findings.  However, the developer.cisco.com site has a revoked certificate at the moment and I cannot get to the API docs for UCCX.  Or says the proxy im going through anyway.

I've managed to get my hands on the documentation, unfortunately I don't have UCCX 9 or 10 to try this out on so look at this more of a point in the right direction.

The API you're CCIE was referring to is most likely the application API within System Configuration grouping of APIs.  It has five or so methods, one of them is an HTTP PUT to modify the application of your choice.

HTTP Method
PUT
URIhttp:///adminapi/application/{applicationName}
Example URIhttp://10.10.10.10/adminapi/application/mysweetapplication
Content Body TypeApplication/XML or Application/JSON
Response Code on SuccessHTTP 200
Response Codes on FailureHTTP 401, 405 or 412
Error CodesNone


In your Content Body, which is like a file you send it with instructions in either XML or JSON format, you will need to send it:

  1. script - The name of the current script (unless you plan to also change it)
  2. scriptParams - The list of parameters for the script

script

In order to send it the same script name that is currently using, you'll need to query the application first, which means you'll need to use another one of the five available methods for the application: Get Application

HTTP Method
GET
URIhttp:///adminapi/application/{applicationName}
Example URIhttp://10.10.10.10/adminapi/applications/mysweetapplication
Content Body TypeApplication/XML or Application/JSON
HTTP Code on SuccessHTTP 200
HTTP Codes on FailureHTTP 401, 405
Error CodesNone


Inside that response (assume XML for a moment) you will see:

 

   

 

This gives you the current script name to use in your Modify Method.

scriptParams

This is where things get a little fuzzy without some hand on experience (good thing there's also a forum on the delvepor site).  The application XSD shows us that the scriptParams element is defined as:


Which tells us that the name of the element is scriptParams, the type is variable (more on that in a second), it is optional, and can occur an infinite amount of times in the XML document.

The type variable is pretty key, as the application XSD defines type variable as:

 

   

     

       

         

       

     

   

   

     

       

         

       

     

   

   

     

       

         

       

     

   

 

That tells us three major things about variable types:

  1. It has to have a single name element whose value has to be a string and have atleast one character in it
    1. This is the name of the variable in your script  E.g., start_time

  2. It has to have a single value element whose value has to be a string and have atleast one character in it
    1. This is what value you want to set it to  E.g., T[8:00 AM]

  3. It has to have a single type element whose value has to be a string and have atleast one character in it
    1. This is what type of variable it is in your script  E.g., Time

Note that the XSD does not define the format of the name, value, or type elements, above the the string and 1 character limitation.

Therefore a valid XML document should look like:

 

   

   

      start_time

      T[8:00 AM]

      Time

   

 

To conclude this much longer than anticipated reply, a few things I do not know about how this works:

  1. How do you disable the use of a parameter such that the script default value takes effect?
  2. How do you set multiple parameters at once without sending multiple API PUT requests?

It might just be:

 

   

   

      start_time

      T[8:00 AM]

      Time

   

   

      end_time

      T[5:00 PM]

      Time

   

  1. Do you have to send all of the existing parameters, as to not inadvertinly disable them?  And if so, how do you get a list of them?  Perhaps from the Get Application method, but I don't see that sepcified anywhere.

    EDIT: I do see that there is a query parameter for the GET operation of an application named detail which can have a value of full.  I'd need to test it though.

Good luck and happy API programming!

Anthony Holloway

Please use the star ratings to help drive great content to the top of searches.

View solution in original post

7 Replies 7

Anthony Holloway
Cisco Employee
Cisco Employee

Hi, first thing first, you should see this post, which lays out for you how to integrate UCCX Enhanced with an external DB via a "man in the middle" web server.

https://supportforums.cisco.com/docs/DOC-29776

Long story short, tell your developer to build a URL for accessing calendar and business hours logic in various formats: XML, JSON, HTML, etc.  You'll use XML, but asking them for more opens your options down the road.

Next up, the API's.  These are pretty new to UCCX, with v9.0 bringing the first round of access and then v10 coming in behind with even more access.

Normally, when I don't know the answer to a question on the forums, I go research it, and sometimes proof of concept it, and then post my findings.  However, the developer.cisco.com site has a revoked certificate at the moment and I cannot get to the API docs for UCCX.  Or says the proxy im going through anyway.

I've managed to get my hands on the documentation, unfortunately I don't have UCCX 9 or 10 to try this out on so look at this more of a point in the right direction.

The API you're CCIE was referring to is most likely the application API within System Configuration grouping of APIs.  It has five or so methods, one of them is an HTTP PUT to modify the application of your choice.

HTTP Method
PUT
URIhttp:///adminapi/application/{applicationName}
Example URIhttp://10.10.10.10/adminapi/application/mysweetapplication
Content Body TypeApplication/XML or Application/JSON
Response Code on SuccessHTTP 200
Response Codes on FailureHTTP 401, 405 or 412
Error CodesNone


In your Content Body, which is like a file you send it with instructions in either XML or JSON format, you will need to send it:

  1. script - The name of the current script (unless you plan to also change it)
  2. scriptParams - The list of parameters for the script

script

In order to send it the same script name that is currently using, you'll need to query the application first, which means you'll need to use another one of the five available methods for the application: Get Application

HTTP Method
GET
URIhttp:///adminapi/application/{applicationName}
Example URIhttp://10.10.10.10/adminapi/applications/mysweetapplication
Content Body TypeApplication/XML or Application/JSON
HTTP Code on SuccessHTTP 200
HTTP Codes on FailureHTTP 401, 405
Error CodesNone


Inside that response (assume XML for a moment) you will see:

 

   

 

This gives you the current script name to use in your Modify Method.

scriptParams

This is where things get a little fuzzy without some hand on experience (good thing there's also a forum on the delvepor site).  The application XSD shows us that the scriptParams element is defined as:


Which tells us that the name of the element is scriptParams, the type is variable (more on that in a second), it is optional, and can occur an infinite amount of times in the XML document.

The type variable is pretty key, as the application XSD defines type variable as:

 

   

     

       

         

       

     

   

   

     

       

         

       

     

   

   

     

       

         

       

     

   

 

That tells us three major things about variable types:

  1. It has to have a single name element whose value has to be a string and have atleast one character in it
    1. This is the name of the variable in your script  E.g., start_time

  2. It has to have a single value element whose value has to be a string and have atleast one character in it
    1. This is what value you want to set it to  E.g., T[8:00 AM]

  3. It has to have a single type element whose value has to be a string and have atleast one character in it
    1. This is what type of variable it is in your script  E.g., Time

Note that the XSD does not define the format of the name, value, or type elements, above the the string and 1 character limitation.

Therefore a valid XML document should look like:

 

   

   

      start_time

      T[8:00 AM]

      Time

   

 

To conclude this much longer than anticipated reply, a few things I do not know about how this works:

  1. How do you disable the use of a parameter such that the script default value takes effect?
  2. How do you set multiple parameters at once without sending multiple API PUT requests?

It might just be:

 

   

   

      start_time

      T[8:00 AM]

      Time

   

   

      end_time

      T[5:00 PM]

      Time

   

  1. Do you have to send all of the existing parameters, as to not inadvertinly disable them?  And if so, how do you get a list of them?  Perhaps from the Get Application method, but I don't see that sepcified anywhere.

    EDIT: I do see that there is a query parameter for the GET operation of an application named detail which can have a value of full.  I'd need to test it though.

Good luck and happy API programming!

Anthony Holloway

Please use the star ratings to help drive great content to the top of searches.

Many thanks for this very informative answer, it gives me a lot to build on,  so lab hours to be booked by me and the Dev guy.

I'm excited to get my hands on UCCX 10.0 and CUCM 10.0 for the matter.  I really enjoy all the AIPs Cisco is exposing to us.  I'm a wannabe computer programmer, so the UCCX scripting + API's really appeal to my inner coder. 

I hope you get it working the way you want.  Good luck.

Anthony Holloway

Please use the star ratings to help drive great content to the top of searches.

Hi Anthony,

I saw the following questions in your post.

How do you disable the use of a parameter such that the script default value takes effect?

How do you set multiple parameters at once without sending multiple API PUT requests?

Do you have to send all of the existing parameters, as to not inadvertinly disable them?  And if so, how do you get a list of them?  Perhaps from the Get Application method, but I don't see that sepcified anywhere.

Use a GET against /adminapi/application/. This will give you the list of parameters that are checked and override the script default.

Example: A GET against /adminapi/application/ICD with DelayWhileQueued checked and set to 20

DelayedWhileQueued

20

java.lang.Integer

0

ICD

Cisco Script Application

ICD

5

true

If a parameter is checked to override the script variable value, not specifying it in the PUT unchecks the box and sets it to the default.

In the AppAdmin page, DelayWhileQueued is checked and set to 20, issuing the following PUT request unchecks the box and resets the value to the script default.

0

ICD

Cisco Script Application

ICD

5

true

This unchecks the box and sets the value back to the script value.

You can set multiple by appending additional nodes.

Example: To set both the CSQ value and the DelayWhileQueued value...

DelayWhileQueued

20

java.lang.Integer

CSQ

"CSQA"

java.lang.String

0

ICD

Cisco Script Application

ICD

5

true

Let me know if this answers your questions.

Interestingly enough, mispelling a param name still returns a 200 OK but unchecks the box and defaults it, like you didn't include it. This is something I'll be following up on.

Thanks,

Ryan

Hey Ryan,

Thank you very much for taking the time to respond to this topic.

I know have a good understanding of how to set the application parameters individually and in bulk, while also determining which current parameters are enabled.

From what I understand in your reply, you "check" a parameter by including it in a scriptParams block, and you "uncheck" a parameter by omitting it from the request all together.

However, there doesn't seem to be a mechanism to pull a list of all parameters, only those which are currently "checked," via the Get Application method.

Therefore, a program utilzing the API could not discover all application parameters; only those which are "checked."

Use case:  I want to update 150 applications, but I want to only update those applications which use an application parameter called "customer_service" and where parameter is not enabled and the default "unchecked" value is "2000".  Leaving all other instances unchanged.

I would have to go into the AppAdmin web interface, click on all 150 applications, and manually inventory the parameters, load them into a text file for processing by my program.  And if a few weeks or months go by, my list is outdated, and I'd have to repeat the process again.

It would have been nice, if the API for GET application would have been structured more like, to allow for all parameters to be returned:

    

         

         

               true

               DelayedWhileQueued

               20

               java.lang.Integer

         

         

               false

               DelayWhileQueued

               30

               java.lang.Integer

         

    

     0

     ICD

     Cisco Script Application

     ICD

     5

     true

Did I understand the API correctly, and if so, did I present a case for a change well enough to have made sense?

Again, thank you for commenting on this post Ryan, I know your time is valuable, and the community, and I, appreciate your efforts.

Anthony Holloway

Please use the star ratings to help drive great content to the top of searches.

Hi Anthony,

First update, there is a enhancement bug opened to CSCul49794 to address the lack of XSD validation against the payload. I'm working to see when this can be implemented. This is for the entire API so will affect all stubs.

I am also working separately on the suggestion to re-work the scriptParams section if I can. I had the same ideas as you when I was testing this so have already started a dialogue with the development team. I'll update when I have some more info.

Thanks,

Ryan

Oh awesome!  Thanks for the validation and feedback.  Good luck with your pursuit with development.

Anthony Holloway

Please use the star ratings to help drive great content to the top of searches.