1. 1 Copyright ©2008 Serena Software, Inc. ZMF Web Services John Skelton Principal Software Developer, Serena

2. 2 Copyright ©2008 Serena Software, Inc. ZMF Web Services - Agenda Web Services Overview Web Services Technology ZMF Web Services Architecture ZMF Web Services Specifics

3. 3 Copyright ©2008 Serena Software, Inc. What are Web Services? The W3C definition: a software system designed to support interoperable machine-to-machine interaction over a network More simply Web Services are just WEB-APIs Web Services are described by WSDL Service Location Methods Method Parameters Parameter Data Types Moving towards a universal programming API

4. 4 Copyright ©2008 Serena Software, Inc. What are Web Services? Application Components Communicate using open protocols Self Contained and Self Describing Discovered using UDDI Consumed by other applications XML based

5. 5 Copyright ©2008 Serena Software, Inc. How do they work? Web Services platform is XML + HTTP HTTP is most widely used internet protocol XML can be used between different platforms and programming languages and still express complex messages and functions. Web Services platform elements SOAP UDDI WSDL

6. 6 Copyright ©2008 Serena Software, Inc. SOAP Simple Object Access Protocol Application communication protocol Format for sending messages XML based Platform independent Language independent

7. 7 Copyright ©2008 Serena Software, Inc. UDDI Universal Description Discovery and Integration Directory for storing information about Web Services Communicates using SOAP

8. 8 Copyright ©2008 Serena Software, Inc. WSDL Web Services Description Language XML document Where is the Web Service? What methods are in the Web Service? What are the Service Parameters

9. 9 Copyright ©2008 Serena Software, Inc. ZMF Web Services ZMF Connect Web Service looks like this:

10. 10 Copyright ©2008 Serena Software, Inc. ZMF Protocol Evolution APPC and TCP/IP SERENA XChange client Proprietary wire protocol XML over proprietary wire protocol ZDD, TeamTrack clients Requires SERXMLxx modules Still uses proprietary wire protocol Web Services ZMF access using open HTTP/XML protocols

11. 11 Copyright ©2008 Serena Software, Inc. ZMF Web Services Access to all areas of ZMF Administration APIs - may be read only Developer APIs Grouped into logical package groups (18) Distributed as part of ZMF Runs on Tomcat Application Server Requires AXIS Servlet, WSDL, Java Stubs

12. 12 Copyright ©2008 Serena Software, Inc. ZMF Web Services - AXIS AXIS provides SOAP infrastructure WSDL2JAVA utility generates JAVA code to access Web Services XML documents appear as JAVA objects Other utilities available for other languages

13. 13 Copyright ©2008 Serena Software, Inc. ZMF Web Services - AXIS A look at the AXIS generated Web Services Objects // Create connect logon request. LogonRequest logonReq = new LogonRequest(); logonReq.setHost(D001.SERENA.COM); logonReq.setPortid(6611); logonReq.setUser(WSER27); logonReq.setPassword(********);

14. 14 Copyright ©2008 Serena Software, Inc. ZMF Web Services - AXIS The call and the response: Logon logon = new Logon(logonReq); Connect.Response connectResponse = null; connectResponse = binding.logon(logon); connectResponse.getMessage() == SER8209I Logon accepted for user WSER27; Local CCSID=00939

15. 15 Copyright ©2008 Serena Software, Inc. ZMF Web Services Web Service Clients communicate with SERENA Servlet using HTTP/SOAP JAVA objects Servlet extracts SOAP body (XML) and forwards it to ZMF Servlet receives response from ZMF, wraps response in SOAP envelope, returns response back to client.

16. 16 Copyright ©2008 Serena Software, Inc. ZMF Web Services ZMFConnectServices Logon Logoff Change Password Must maintain session state

17. 17 Copyright ©2008 Serena Software, Inc. ZMF Web Services ZMFPackageLifeCycle Create Package Approve Demote Promote Backout Freeze Revert

18. 18 Copyright ©2008 Serena Software, Inc. ZMF Web Services ZMFPackageInfoManagement Get Affected Applications Get Approvers Get Package General Parameters Get Implementation Get Install Schedule Get Library Types Get Promotion History Get User Variables

19. 19 Copyright ©2008 Serena Software, Inc. ZMF Web Services ZMFComponentLifeCycle Checkout Checkin Build Recompile Relink Lock Unlock Scratch

20. 20 Copyright ©2008 Serena Software, Inc. ZMF Web Services ZMFComponentInfoManagement Component Change Descriptions Component Descriptions Component Promotion History Component History

21. 21 Copyright ©2008 Serena Software, Inc. ZMF Web Services ZMFChangeLibraryAdmin Baseline Libraries Production Libraries Promotion Libraries Read Only

22. 22 Copyright ©2008 Serena Software, Inc. ZMF Web Services ZMFDeveloperEnvironmentAdmin Global Parameters Application Parameters Global Library Types Application Library Types Build Procedures Read only

23. 23 Copyright ©2008 Serena Software, Inc. ZMF Web Services general format All Services have request / response elements Logon Request Userid Password New Password Logon Response Return code Reason code Message May return array of result elements Get Application Parms

24. 24 Copyright ©2008 Serena Software, Inc. Session State ZMF runs multiple transactions over a session Logon, Checkout, Stage, Build, Promote, Build… HTTP is stateless Problem: How to correlate discrete Web Service requests with an existing Servlet - ZMF session? AXIS Session Header Retrieve Session Header at completion of Logon Transaction Set Session Header for all other Soap Bindings.

25. 25 Copyright ©2008 Serena Software, Inc. Session State Java code generated by AXIS has common Stub Stub used by Java to access Soap Methods ZMF Web Services has 18 Stubs Session Header returned from Connect Service passed to all other Services Sample code provided as part of Web Services package

26. 26 Copyright ©2008 Serena Software, Inc. Session State – Java Connect // Get the stub which implements the SDI. ConnectServicesLocator csl = new ConnectServicesLocator(); binding = (ConnectSOAPBindingStub) csl.getConnect(); binding.setMaintainSession(true); // Create connect logon request. LogonRequest logonReq = new LogonRequest(); logonReq.setHost(server.getProperties().getAddress()); logonReq.setPortid(server.getPort()); logonReq.setUser(username); logonReq.setPassword(password); // Logon and Get the Response com.serena.zmf.webservices.client.internal.Connect.Response connectResponse = null; connectResponse = binding.logon(logon); // store cookie cookie = (String) binding._getCall().getMessageContext().getProperty(HTTPConstants.HEADER_COOKIE);

27. 27 Copyright ©2008 Serena Software, Inc. Session State 2 nd Transaction // Create a new package public NewPackageResults createPackage(NewPackageRequest request) throws CoreException { NewPackage np = new NewPackage(request); NewPackageResults results = null; PackageLifeCycleSOAPBindingStub binding = getPackageLifeCycleSOAPBindingStub(); try { results = binding.newPackage(np); } catch (Exception e) { e.printStackTrace(); } return results; }

28. 28 Copyright ©2008 Serena Software, Inc. Session State – 2 nd Transaction // Get PackageLifeCycleSOAPBindingStub private PackageLifeCycleSOAPBindingStub getPackageLifeCycleSOAPBindingStub() throws CoreException { PackageLifeCycleSOAPBindingStub binding = null; try { PackageLifeCycleServicesLocator sl = new PackageLifeCycleServicesLocator(); sl.setPackageLifeCycleEndpointAddress(updateURL(sl.getPackageLifeCycleAddress())); binding = (PackageLifeCycleSOAPBindingStub) sl.getPackageLifeCycle(); setCookieAndMaintainSession(binding); } catch (javax.xml.rpc.ServiceException jre) { throwCoreException(jre); } return binding; } // Set session cookie private void setCookieAndMaintainSession(Stub binding) { binding.setMaintainSession(true); binding._setProperty(HTTPConstants.HEADER_COOKIE, cookie); }

29. 29 Copyright ©2008 Serena Software, Inc. ZMF Web Services Questions?

30. 30 Copyright ©2008 Serena Software, Inc. Questions