Web Services Management

This article contains the following topics:
casm171
This article contains the following topics:
Web Services
are a set of data exchange standards that enable communication between products, even if they are on different operating environments. This ability is analogous to browsing the Web on a personal computer -- all remote websites are accessible regardless of whether they are hosted on Solaris, AIX, Windows, and so on. In the same manner, Web Services allow products to communicate over HTTP to various servers regardless of operating environment. For example, a Microsoft Office product can communicate with a program on a UNIX server, and a Java Server Page can access a server hosted on a Windows server. This platform-neutral communication allows for powerful integrations.
The Web Services take advantage of this technology, allowing almost any product to access CA SDM and Knowledge Management. Web Services clients can create tickets, update assets, search the knowledge base, and so forth.
 For additional information on web services, see the CA SDM Reference.
CA SDM Components
CA SDM provides the installation files for this version of the J2EE Web Services in the following directory:
<NX_ROOT>/sdk/websvc/R11
<NX_ROOT> specifies the root installation path for CA SDM.
Web Service Options
These options control the web service session:
  • rest_webservice_access_duration
    Specifies the number of hours that the REST Web Service Access Key remains active before expiration. The Access Key timeout is not based on inactivity time, but it is based on duration time since the Access Key creation. After the Access Key meets the specified duration, the Access Key ends regardless of whether it is being used.
    Optionally, the REST client can also provide the Access Key duration time for the specific Access Key during the Access Key request. To provide the duration value, set it directly on the expiration_date attribute of the rest_access resource, as part of the POST request payload.
    Valid Range:
    1-8760 hours
    Defaut:
    168
  • rest_webservice_disable_basic_auth
    Disables Basic Authentication in REST Web Services.
    Default:
    No
  • rest_webservice_list_max_length
    Specifies the maximum number of rows that a REST Web Service query returns.
    Default:
    500
  • rest_webservice_list_page_length
    Specifies the default number of rows that a REST Web Service query returns per page.
    Valid Range:
    1-500
    Default:
    25
  • rest_webservice_resources_to_expose
    Specifies the list of Majic factories (resources) that CA SDM exposes through REST Web Services. This option overrides the default behavior. By default, CA SDM exposes all factories through REST Web Services.
    If you do not enter values in this option, the default behavior exposes any Majic factory that does not have the REST_OPERATIONS property set to NONE. By default, no Majic fatory has this property set to NONE.
    Use the REST_OPERATIONS property to set the specific HTTP CRUD (CREATE, READ, UPDATE, DELETE) methods for CA SDM to expose on a given Majic factory.
    Default:
    rest_access
    Example:
    rest_access, cnt, grp, cr, crs, pri, alg, urg, imp, pcat, org
  • hmac_algorithm
    Specifies the algorithm that you use to compute the signature for Custom/Secret Key Auhentication in REST Web Services.
    Default:
    HmacSHA1
  • string_to_sign_fields
    Specifies the fields that you use to compute the signature for Custom/Secret Key Authentication in REST Web Services, in addition to the default REQUEST_METHOD, REQUEST_URI, and QUERY_STRING fields.
    Default:
    blank
  • webservice_domsrvr
    Specifies the name of the object engine that SOAP web services use. If not installed, SOAP web services use "domsrvr".
    The value of the option must be a string beginning with the characters "domsrvr:"
  • webservice_session_timeout
    Sets the timeout value (in minutes) for SOAP Web Service sessions. When the time between successive web method calls is greater than the value specified, the session ID is marked expired. The session is then no longer valid.
    To prevent sessions from expiring due to activity, set the value for this option to 0. Other methods, such as logoff routines, can still invalid sessions.
These options require restarting the CA SDM server.
Web Services Installation
Depending on your configuration type, CA SDM installs web services for the following servers:
  • Conventional: Both primary and secondary servers. For web service clients to use a URL on a secondary server, you add a web engine to the secondary server
  • Advanced Availability: Application server
Web services use the default object manager that is installed on the CA SDM server. To use any other object manager, install and set the
webservice_domsrvr
option in Options Manager.
 For information about adding and configuring object managers, web directors, and web engines, see . For information about installing and setting the 
webservice_domsrvr
 option, see the Options Manager section.
How to Activate Design-Time
The CA SDM Web Services includes a method stub configuration feature for developers in the Java version. When activated, the Web Services ignores the CA SDM server and returns simulated data for method calls so that Web Services calls can be made without running a CA SDM server.
Follow these steps:
  1. Edit deploy.wsdd to uncomment the sections for “design_mode_stubs”.
  2. Reverse the deployment and redeploy the server.
  3. Restart the application server.
    The design-time feature is activated.
The design-time feature applies to CA SDM Web Services methods only.
Web Services Security
When you deploy web services, understand the important security considerations. The default configuration when using HTTP is insecure, as it is for all information in web service calls sent between the client and the server in plain text over the network using the HTTP protocol. This includes not only application data, such as ticket descriptions and contact names, but also web service session identifiers (SID). Depending upon the web service application login methods used, it can include passwords.
We recommand that Administrators deploying web services review this information carefully, and to take additional configuration steps at the application and network levels to secure their web service environment.
The default web service configuration used with HTTP is insecure and vulnerable to security threats, which can include password discovery, session fixation, and data spying, among others.
There are three interrelated key security considerations in deploying Web Services:
  • What (application level) access authentication schemes should this deployment support?
  • What additional networking level security features does this deployment require?
  • How will these requirements be enforced through web service configuration options?
The following describes each security feature:
  • Web Service Application Level Authentication Schemes
    -- To access Web Services, a web service client application must be authenticated with the web service application. Web Services provides two schemes of access authentication. The first is by username/password, and the other is by Public Key Infrastructure (PKI) technology. Both work with the Access Control and Management component in Web Services, using access policy. Access authentication and access management are the most important security features of Web Services.
    Authentication with username/password methods may be disabled using the following security configuration command:
    disable_user_logon
    Before enabling this option, the administrator needs to determine if each web service client for which an enterprise is requesting Web Services access, can actually provide support for the alternative authentication method, which is the PKI-based login method. The key advantage to the PKI technology is that Web Services client applications do not require
    maintained
    system user accounts, that is; the maintenance, storage, and transmission of their passwords.
  • Networking Level Security Configuration
    -- In both authentication schemes, username/password and Public Key Infrastructure (PKI), notice that the session identifier returned from the specific login method (as well as all subsequent information), are transmitted in plain text when using HTTP. Furthermore, if the username/password authentication scheme is used, the password is sent unprotected (in plain text) from the web service client application to the Web Services. During product development, the W3C did not have recommended standards for web services security. Subsequently, WS-Security is not used by these Web Services implementations to provide a security context. Instead, point-to-point transport layer security (SSL/TLS) and other network level security mechanisms (for example, IPSec), are recommended to protect the otherwise plain text transmission of the application-level authentication exchange(s), and subsequent session identification and data.
    We recommend using SSL (or https) when deploying Web Services to protect the application-level authentication exchanges and subsequent transmissions of session identification and data.
  • Web Service Configuration
    -- To allow administrators to enforce communications protocol-level security at the level of the Web Services application, the following two security configuration commands are supported:
    require_secure_logon
    This security feature requires you to use SSL (or https) for calling the Login() and LoginService() methods. This feature also provides a handy method for protecting the username and password, while avoiding the overhead of SSL for the rest of the web services.
    If you use the require_secure_logon command, the Web Services application will not confirm that communications protocol-level security is enforced for methods other than Login() and LoginService(). Unless other precautions are taken, the other Web Services methods may be invoked insecurely, causing greater vulnerability to security threats.
    require_secure_connection
    This security feature requires you to use SSL to access any part of the web service. If https is required but not used, then a SOAP Fault with code UDS_SECURE_CHANNEL_REQUIRED is returned.
    For information about how to configure SSL, see your J2EE Servlet Container documentation.
Use the Web Services
The information in this section provides you with the fundamentals for using the CA SDM Web Services. Example code using the Web Services exists in the following CA SDM installation directory:
<NX_ROOT>/samples/sdk/websvc/java
The sample code is written in Java using Apache Axis for SOAP messaging.
Logins
Before any Web Services method can be used, a SID (session ID) must be obtained from one of these methods: login(), loginService(), and loginServiceManaged(). The first two methods require a username and password that are validated exactly the same as the CA SDM web interface; the contact’s Access Type specifies the validation method. The third method requires a public/private key pair, where login request encrypted with the private key can only be decrypted through the public key, and vice versa.
How to Perform Common Tasks
The Web Services provides a flexible and powerful API into CA SDM, but it requires some knowledge of the object structure used by the product as follows:
  1. Familiarize yourself with the information about objects and attributes in CA Service Desk Manager Reference Commands.
    This guide lists the attributes of each object in the system, which is essential because many of the Web Services methods require attribute names.
  2. Review the Web Services methods, especially generic ones. For example, if your application must display all the activity logs for a request, first identify how the activity logs relate to the request.
    The CA Service Desk Manager Reference Commands section
     
    shows that the request object has two lists of Activity Logs: The act_log (which shows only noninternal logs), and act_log_all (which lists all activity logs).
  3. Identify which Web Services methods you require. To get lists attached to an object, use getRelatedList() or getRelatedListValues().
Default Handles
Some default data provided by the product is frequently used. Instead of looking up handles for these objects, some of the commonly used ones are listed in the following tables.
While the handles do not change the legible symbols may be edited.
Contact Type (Object name: ctp)
Handle
Note
ctp:2307
The “Analyst” type
ctp:2310
The “Customer” type
ctp:2305
The “Employee” type
ctp:2308
The “Group” type
Impact (Object name: imp)
Handle
Note
imp:1605
Impact ‘None’
imp:1600
Low impact ‘5’
imp:1601
Medium-low impact ‘4’
imp:1602
Medium impact ‘3’
imp 1603
Medium-high impact ‘2’
imp:1604
High impact ‘1’
Priority (object name: pri)
Handle
Note
pri:505
Unassigned priority ‘None’
pri:500
Low priority ‘5’
pri:501
Medium-low priority ‘4’
pri:502
Medium priority ‘3’
pri:503
Medium-high priority ‘2’
pri:504
High priority ‘1’
Severity (object name: sev)
Handle
Note
sev:800
Low severity ‘1’
sev:801
Medium-low severity ‘2’
sev:802
Medium severity ‘3’
sev:803
Medium-high severity ‘4’`
sev:804
High severity ‘5’
Call Request Type (object name: crt)
Handle
Note
crt:180
Request
crt:181
Problem
crt:182
Incident
Query for Requests, Issues, or Change Orders Assigned to a Contact
One of the most common operations is retrieving the active requests assigned to an analyst (assignee). You can use one of several methods, such as doQuery() (to get a list reference), or doSelect() (to get the values immediately). Assuming the assignee’s handle is already known, the where clause to use is as follows:
assignee.id = U'<assigneeID>' AND active = 1
In this where clause, <assigneeID> is the id portion of a contact handle, value, such as “555A043EDDB36D4F97524F2496B35E75”.
This where clause works for requests, change orders and issues because they all have the ‘assignee’ and ‘active’ attributes, and they mean the same thing for all three object types. The ‘active = 1’ portion of the where clause restricts the search to active requests.
The Active Flag
Most CA SDM objects have a field called ‘active’ or ‘delete_flag’. This is actually an SREL pointer to the Active_Boolean_Table object or Boolean_Table object. Consider adding these fields to your queries to filter objects marked as Inactive by the system administrator. For querying purposes, search for ‘delete_flag = 0’ to find active records and ‘delete_flag = 1’ for inactive records. For example, the following pseudo-code demonstrates using doSelect() to retrieve values for all active Request Status objects:
doSelect(SID, "crs", "delete_flag = 0", -1, new String[0]);
To set an object to active or inactive, you need to pass the handle of the Boolean object representing either true or false. These handles do not change, so you can safely hard-code them. These are listed as follows:
Active_Boolean_Table
Boolean_Table
actbool:4551 = ‘Active’
bool:200 = ‘False’
actbool:4552 = ‘Inactive’
bool:201 = ‘True’
Retrieve Related List Length
When requesting attribute values from an object, such as with getObjectValues(), you can get the length of a related list by requesting the following attribute:
"<listName>.length"
For example, to get the number of Activity Logs for a certain request, pass the following to getObjectValues():
"act_log_all.length"
This is the only way you can use list names in these types of methods.