Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
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);