Download TechNote - CPAM WS

Tech Note - Using CPAM Web Service
Messages (Method calls)
SOAP
XML
SOAP
XML
Endpoint Ref. URI
URI
URI
Bindings
Interface
PSIMWsPortType
URI
URI
Bindings
Interface
AccessPolicyPortType
PSIMWsService Web Service
The CPAM Web Service (PSIMWsService) primarily exposes two interfaces – PSIMWsPortType and
AcecssPolicyPortType (The interface is also known as portType in web service terminology). The
interfaces are exposed using WSDL 1.1 specifications.
Bindings & Endpoint Address
Both the interfaces support SOAP/HTTP or XML/HTTP message formats. So there are 4 unique endpoint
addresses/ URIs – one for each binding. In a nutshell, each endpoint address uniquely identifies the
interface and the message format to use.
Interface
PSIMWsPortType
PSIMWsPortType
AcecssPolicyPortType
AcecssPolicyPortType
Message
Format
SOAP
XML
SOAP
XML
Endpoint Address used by client application
http://<cpam-server>/acws/services/psimws
http://<cpam-server>/acws/services/psimxml
http://<cpam-server>/acws/services/acpolicy
http://<cpam-server>/acws/services/acpolicyxml
The client application must use one of these Endpoint Addresses to access a web-service method in
a required interface using required message format type (SOAP or XML).
The implementation for many individual methods using XML/HTTP format is not complete. Please
refer to the actual WSDL or send an e-mail to [email protected] to get details on exactly what is
supported.
The interfaces
The PSIMWsPortType interface provides methods to






Authenticate user (Login), Logout user
Get details of access control device such as Door or Lock
Get details of Personnel, Organization etc.
Act on an alarm
Execute a door command
Register a listener to receive CPAM events
The AccessPolicyPortType interface provides method to



Get details of access levels and schedules
Get details of badges
Update badges
The PSIMWsService web service does not provide any method to configure the CPAM server. It is
assumed that the user will use CPAM Client to configure the CPAM server.
Viewing the Web Service information on a CPAM server
Following URL will list available web service methods on a CPAM server.
http://<cpam-server>/acws/services
This web page lists available interfaces, methods and the endpoint addresses.
Please ignore the methods defined under ACVSMPortTYpe interface. This interface provides the
method for integration between Cisco CPAM and Cisco VSM. These methods should not be used by any
third party applications.
Following URLs will list the actual WSDL.
http://<cpam-server>/acws/services/psimws?wsdl
http://<cpam-server>/acws/services/acpolicy?wsdl
Security
The CPAM Web Service provides HTTP or HTTPS based access.
It also provides an application level authentication. Before calling any method, the client application
must call authenticateUser method to authenticate the user. This method returns a security context
object which must be used as a parameter in subsequent API calls.
Error handling
In case of an error or exception, all methods throw an exception of type AcWsFault. This object wraps
the error information such as major code, minor code and description.
Refer to the major fault codes are described in the appendix in API reference guide.
Client Application code - Java
The web service client uses the auto-generated code to reference the remote CAPM web service
endpoint.
STEP – Use WSDL to Java converter
The wsdl2java takes a WSDL document and generates fully annoatated code that can be used to access
the CPAM Web service methods.
More information on wsdl2java converter tool is here
https://cwiki.apache.org/CXF20DOC/wsdl-to-java.html
The syntax is…
wsdl2java –d <destination-folder> <wsdl-url>
e.g.
wsdl2java –d /generated-source http://my-cpam-server/acws/services/psimws?wsdl
This will generate the Java code in /generated-source folder. Compile and use these classes in the client
application.
STEP – Calling Web Service methods – Sample Code
Sample code …
// The PSIMWsService Web Service
private final static QName SERVICE = new QName("http://cisco.com/physec/acws/", "PSIMWsService");
// WSDL location URL
private final static URL WSDL_LOCATION = new URL(“http://cpam-server/acws/services/psimws?wsld”);
PSIMWsService _webService = null;
PSIMWsPortType m_ PSIMWsInterface = null;
AccessPolicyPortType m_AccessPolicyInterface
SecurityContext _ctx = null;
…
try
{
//Reference to the PSIMWsService web service
_webService = new PSIMWsService(WSDL_LOCATION, SERVICE);
//Get handle to PSIMWsPortType interface
_ PSIMWsInterface = _webService.getPSIMWsSoapPort();
//Get handle to AccessPolicyPortType interface
_ AccessPolicyInterface = _webService.getAccessPolicySoapPort();
}
catch (WebServiceException e)
{
//Handle exception
}
catch (Exception e)
{
//Handle exception
}
….
// Authenticate user
UserCredentialType uct = new UserCredentialType();
uct.setUsername(“username”);
uct.setPassword(“password”);
_ctx = _ PSIMWsInterface.authenticateUser(uct);
…
//Call methods using interface handles
AcDeviceTypeList deviceTypeList= _ PSIMWsInterface.getAcDeviceTypes(_ctx);
…
List<Schedule> schedules = _AccessPolicyInterface.getAllSchedules(_ctx);
…
//In the end logout user and close the session
_PSIMWsInterface.logoutUser(_ctx);
Client application code – C#
The web service client uses the auto-generated code to reference the remote CAPM web service
endpoint.
STEP – Use WSDL to C# converter
If you install MS Dev Studio 2008 and .NET Framework SDK 3.5 then you already have the WSDL
converter tool.
More information on wsdl.exe tool is here
http://msdn.microsoft.com/en-us/library/7h3ystb6(VS.71).aspx
The syntax is…
wsdl /l:CS /protocol:SOAP <wsld-file> <xsd files …>
e.g.
wsdl /l:CS /protocol:SOAP acws.wsdl physic-common.xsd ws-addr.xsd ac-common.xsd acschedule.xsd ac-policy.xsd ac-event.xsd
This will generate the PSIMWsService.cs C# code.
STEP – Create Client Proxy DLL
To create a Client Proxy DLL, use C# command line compiler. More information on wsdl.exe tool is here.
http://msdn.microsoft.com/en-us/library/78f4aasd(VS.80).aspx
e.g.
csc /t:library /r:System.Web.Services.dll /r:System.Xml.dll PSIMWsService.cs
This will generate the PSIMWsService.dll. Add reference to this DLL in the MS Dev Studio for your C#
application.
STEP – Calling Web Service methods – Sample Code
Sample code …
// The PSIMWsService Web Service
private String _PSIMServiceUrl = “http://cpam-server/acws/service/psimws”;
private String _AccessPolicyServiceUrl = “http://cpam-server/acws/service/acpolicy”;
private PSIMWsBinding _psimBinding;
private AccessPolicyBinding _apBinding;
private SecurityContext _ctx;
…
// PSIMWsPortType interface with SOAP/HTTP
_ psimBinding = new PSIMWsBinding();
_ psimBinding.Url = _PSIMServiceUrl;
// AccessPolicyPortType interface with SOAP/HTTP
_apBinding = new AccessPolicyBinding();
_apBinding.URL = _AccessPolicyServiceUrl;
….
// Authenticate user
UserCredentialType uct = new UserCredentialType();
uct.username = “username”;
uct.password = “password”;
_ctx = _ psimBinding.authenticateUser(uct);
…
//Call methods using interface handles
getAcDeviceTypesReqType reqType = new getAcDeviceTypesReqType();
reqType.secCtx = _ctx;
getAcDeviceTypesResponse resp = _ psimBinding.getAcDeviceTypes(reqType);
AcDeviceType[] dtypes = resp.deviceTypes;
…
getAllAccessLevels gaal = new getAllAccessLeves();
gaal.ctx = _ctx;
accessLevel[] als = _apBinding.getAllAccessLevels(gaal);
…
//In the end logout user and close the session
logoutUser lu = new logoutUser();
lu.setCtx = _ctx;
_ psimBinding.logoutUser(lu);