How to Enable Web Services

The Web Services component is a prerequisite for the Eclipse-Based UI. In addition, you can use Web Services to connect your user-written program to the API.
ce18
As a change manager (
CA Endevor
administrator), you can enable the Web Services component. This component is a prerequisite for the Eclipse-Based UI. In addition, you can use Web Services to connect your user-written program to the
CA Endevor
API.
Enabling Web Services is a complex process that requires that you coordinate the assistance of other roles.
Prerequisites
  • CA Endevor
  • CA Common Services:
    • If you are using CA Common Services Version 14.0, verify that the following PTFs are applied:
      • RO50139
        ,
        RO53584
        ,
        RO56246
        ,
        RO57125
        ,
        RO59782
        These PTFs affect CAICCI.
      • RO47492
        This PTF is required to make VSAM Extended Addressability available through CA L-Serv.
    • If you are using CA Common Services Release 14.1, verify that the following PTFs are applied:
      • RO52401, RO53583, RO55947, RO57149, RO59727
        These PTFs affect CAICCI
      • RO96566, RO99990
        These PTFs ensure that when a CCI Spawn client abends or is cancelled, the services that the client spawns are terminated.
    • If you are using CA Common Services Version 15.0, verify that the following PTF is applied:
      • SO06329
        This PTF is required for spawning services under 64-bit Java.
        To use Tomcat 9.0.27 or higher with CA Common Services, you must also apply the
        CA Endevor
        PTF SO11466.
  • Java 8
    Web Services supports 64-bit Java from Increment 18.0.12 onward. For more information, see Web Services Support for 64-bit Java.
  • Apache Tomcat for the HTTP and application server
    You can install a supported version of Apache Tomcat from CA Common Services for z/OS. For more information on this process, see the CA Common Services for z/OS documentation.
    Web Services supports only Tomcat versions 8 and higher.
Roles and Responsibilities
The following graphic shows the responsibilities (scenarios) associated with each role for the master scenario How to Enable Web Services:
How to enable Web Services
Web Services Installation Checklist
The following roles should ensure that the above software requirements are met, and then complete these scenarios in the order specified:
  1. CA Endevor
    administrator -- Configure
    CA Endevor
    for Web Services
    .
  2. CA Common Services CAICCI administrator -- Enable STC Definitions for Web Services.
  3. Security administrator -- Enable Security Access to Web Services.
Completing these steps sets up Web Services to use the Eclipse Plug-in and, if installed, the CA Brightside command line interface (CLI). For more information about client stubs, see SOAP Clients and Using the REST API.
Web Services Clients
The
CA Endevor
® SCM Web Services component enables client applications to communicate with the
CA Endevor
® SCM API. Web Services runs in an HTTP Application server (Tomcat) under a z/OS USS environment. The
CA Endevor
® SCM Web Services component supports the following two web service client design models:
  • SOAP
    Web Services uses Axis2 for SOAP message handling.
  • RESTful
    The RESTful model uses Jersey (JAX-RS).
The Eclipse-Based UI and user-written programs use Web Services to send Software Control Language (SCL) statements, with some restrictions, (directly or indirectly, depending on the client model used) to the
CA Endevor
® SCM API. Web Services lets you perform actions or queries on
CA Endevor
® SCM abstractions, such as Elements, Packages, Types, Processors, and so on. You can use defined web service functions to perform Endevor actions and queries. Queries can return information to the web service caller in the following formats:
  • Comma Separated Value (CSV) format (using the submitSCL operation)
  • XML format (using Get<Object>)
  • JSON format (using the RESTful API)
Possible client applications include thin or thick clients, browsers, mobile application, or Rich Client Platform (RCP) programs.
How Client Programs Access the API
Web Services is a multithreaded application built with Java2 (the Apache Axis2/Java web services/SOAP/WSDL engine) and the Jersey framework (which serves as a JAX-RS reference implementation for RESTful web services). Web Services and client applications communicate using the Simple Object Access Protocol (SOAP) or the direct RESTful approach. The client and Web Services communicate in a request-response fashion using the HTTP protocol.
The following graphic shows the flow of information between the client, Web Services, and the
CA Endevor
API:
How to enable Web Services
As shown in the graphic, client applications access the
CA Endevor
® SCM API through Web Services. Details of this process follow:
  • If the SOAP web service client model is used, then the client application formats and sends a SOAP message to the HTTP/Application server based on the definitions in the Web Services Description Language (WSDL) file. The request includes the name of the
    CA Endevor
    ® SCM configuration that the client wants to access.
  • With the RESTful model, the client creates an HTTP request that includes a specific URL and parameters. The request corresponds to a specific Endevor action and sets the appropriate HTTP method associated with the action.
  • Web Services matches the name of the data source that is requested by the client call to a configuration (.cfg) file. One or more configuration files are stored on the HTTP web server and enable access to the
    CA Endevor
    ® SCM API. A configuration file identifies the name and number of API STCs (the STC pool) available to pass requests to
    CA Endevor
    ® SCM. The CA Common Services CAICCI Spawn facility spawns the specified number of API STCs.
  • CA Endevor
    processes the request and then the results are returned by CAICCI to Web Services where the data are processed and transformed into the appropriate response structure and then returned to the client.
  • To enable Web Services to process requests and communicate with the API, the z/OS environment where
    CA Endevor
    ® SCM is installed requires certain CA Common Services components, including the following:
    • CAICCI provides a common communications software layer that enables communication between Web Services and the API.
    • CAIENF must be configured to enable the CAICCI Spawn facility that lets
      CA Endevor
      ® SCM schedule, execute, and monitor a pool of STCs for Web Services requests.
This process uses the following standard technologies:
  • XML language
    - The data format used by web service components. Communications between web service applications are written in XML format.
  • Simple Object Access Protocol (SOAP)
    - An XML-based messaging protocol and encoding format for inter-application communication. SOAP messages are XML messages sent between applications. A SOAP message is a text file written in standard XML format that is enclosed in a SOAP structure. SOAP enables applications to know how to send and interpret the XML data.
  • Web Services Description Language (WSDL)
    - A service description protocol. A web service's WSDL file is a dynamic XML file that serves as the interface between a SOAP-based client program and the web service. The Web Service WSDL file describes what
    CA Endevor
    ® SCM operations are available to the client program and the SOAP protocol bindings and message formats required to enable the client to interact with the web service.
    If you are using Web Services for a user-written client application, your web developer must create a client stub from the WSDL file. The client stub is responsible for conversion of parameters used in a function call and deconversion of results passed from the server after execution of the function. The client stub interacts with the web service stub. For more information see, SOAP Clients.
  • Web Application Description Language (WADL)
    -- Jersey supports WADL. WADL is an XML description of the deployed RESTful web application. It contains the model of the resources, structure, supported media types, HTTP methods, and so on. It is similar to the WSDL, which is used for the SOAP-based Web Services model. WADL can be used for generating a client-side stub, however this feature is not as sophisticated as the stubs generated using the WSDL.
  • HTTP Protocol
    -- The Hyper Text Transfer protocol (HTTP) is an application protocol for distributed, collaborative information systems, and is the foundation for data communication on the World Wide Web.
  • JSON (JavaScript Object Notation)
    -- JSON is an open standard, language independent, data format used to transmit data objects as structured attribute-value pairs in human-readable text. It is considered an alternative to XML.
  • JAX-RS
    -- Java API for RESTful Services (JAX-RS) is a Java programing language API that provides support for the Representational State Transfer (REST) type of web services.