This question pops up from time to time, so I thought it would be  good to share the answer with the developer community.

 

IPICS 2.2(x) - 4.0(x)

 

The answer lies in the IPICS API documentation,namely:

http://www.cisco.com/c/dam/en/us/td/docs/interoperability_systems/c_ipics/221/api/guide/api.pdf

Executing API Request by Using a URL

You can execute API requests from any browser. The following sections provide information about executing these requests. In addition, the Web Services Description Language(WSDL) file for the Cisco IPICS API includes helpful information. See Chapter 4, “Web Services Description Language File.”

Guidelines

When you use the URL method to execute an API request, be aware of the following guidelines:

  • The first time that you execute a request in a browser session, the system prompts you for a user name and password. Enter your Cisco IPICS user name and password.
  • The output format of API responses can vary depending on the browser that you are using.
  • To allow error messages from the API to display in Internet Explorer, start Internet Explorer and choose Internet Options. In the Advanced tab, check the Show friendly HTTP error messages check box in the list of Browsing options.
  • Google Chrome removes new lines and the XML tags from API responses.

 

Page 1-1

 

So the answer depends on what tool you are trying to use:

  • If you are using a web browser, a popup window should appear where you can enter the IPICS credentials.
  • If you are using the “curl” command line tool or in a script, the syntax would be something like this:

# curl --insecure --user <your ipics user login name>:<your ipics user password> "https://<your ipics server>/ipics_server/services/NorthboundService/executePolicy?policyId=<your policy ID number>"


which then returns:

 

<ns:executePolicyResponse xmlns:ns="http://com.cisco.ipics.issymo.northbound.service"><ns:executePolicyReturn>true</ns:executePolicyReturn></ns:executePolicyResponse>

 

where “true” means IPICS successfully queued the policy for execution.

 

  • If you are using the “wget” command line tool or in a script, the syntax would be something like this:

# wget --no-check-certificate --http-user=<your ipics user login name> --http-password=<your ipics user password> "https://<your ipics server>/ipics_server/services/NorthboundService/executePolicy?policyId=<your policy ID number>"


which then returns:


--15:11:08-- https://ipics402.cisco.com/ipics_server/services/NorthboundService/executePolicy?policyId=44

=> `executePolicy@policyId=44'

Resolving ipics402.cisco.com... 10.0.1.2

Connecting to ipics302.cisco.com|10.0.1.2|:443... connected.

WARNING: Certificate verification error for ipics402.cisco.com: self signed certificate

HTTP request sent, awaiting response... 200 OK

Length: unspecified [application/xml]

15:11:08 (12.62 MB/s) - `executePolicy@policyId=44' saved [166]


# cat "executePolicy@policyId=44"

 

<ns:executePolicyResponse xmlns:ns="http://com.cisco.ipics.issymo.northbound.service">

<ns:executePolicyReturn>true</ns:executePolicyReturn></ns:executePolicyResponse>


where “true” means IPICS successfully queued the policy for execution.

 


IPICS 4.5(x)+

Starting in IPICS 4.5(1), the API is a little easier to use, namely we added a few REST-style APIs that can take the IPICS credentials as API arguments instead of HTTP headers.  Also note the service URL has changed:

 

Old

https://<your ipics server>/ipics_server/services/NorthboundService/executePolicy?policyId=<your

policy ID number>


New

https://<your ipics server>/ipics_server/handsetservice/websvc/policy/<your policy ID number>?u=<your ipics user login name>&p=<your ipics user password>

 

For example

# wget --no-check-certificate "https://10.0.1.3/ipics_server/handsetservice/websvc/policy/44?u=ipics&p=secret"

 

Here is a link to the documentation: Cisco IPICS API Reference Guide, Cisco IPICS Release 4.5 - REST-Based API Functions [Cisco IP Interoperability and Colla…

 

Policy ID Numbers

 

The next question is usually "How do I get the policy ID number?"

 

Typically you would call getAllPolicies and parse the PolicyVO objects in the PolicyContainerVO.  This not a big deal if you are calling other SOAP web services in your code, but it is a bit of a pain if you are trying to do this in a Linux BASH or Windows BAT script.

 

Alternatively, policies don't change frequently, so you could probably get away with hard coding the policy ID.  To do so, you can open the Policy List page in IPICS Admin Console using Firefox.  Then select the name text of the policy you want, right click and choose View Selection Source.  This will popup a window showing something like:

<a href="#" onclick="doShowPolicyDetails('44');">p1</a>

In the example above, the policy ID is 44.  Done.