Access Control and Management

This article contains the following topics:
casm1401
This article contains the following topics:
To minimize the potential problem of web services ticket flooding and to maintain the stability of the CA SDM server, this version of CA SDM Web Services uses an Access Control and Management system. It works primarily to handle the excessive service activities initiated by trusted user applications that can result from programming errors or exceptions. It also works as a barrier for controlling access to CA SDM Web Services from malicious attackers. An administrator of a web service application is able to create and define an access policy in CA SDM that controls access to CA SDM Web Services from a web service application.
A default access policy with a code of DEFAULT is provided. The default access policy contains no access restrictions and is only applied to sessions authenticated through username and password.
Define an Access Policy
To create any SOAP web services access policy, an administrator defines an access policy.
Follow these steps:
  1. Click the Administration tab.
  2. In the tree on the left, click SOAP Web Services Policy, Policies.
    The SOAP Web Services Access Policy List page appears.
  3. Click Create New.
    The Create New SOAP Web Services Access Policy dialog appears.
  4. Enter the information for the new access policy:
    The defaultvalue of -1 in any operation counter indicates that no restrictions apply to the corresponding operation. A value of 0 (zero) indicates that the corresponding operation is not allowed.
    • Symbol
      (Required) Identifies a symbolic name of the access policy.
    • Code
      (Required) Indicates the unique text that identifies this access policy.
    • Status
      (Required) Identifies the status of an access policy. An inactive policy is not used.
    • Proxy Contact
      Identifies the contact to use for all web services operations and CA SDM security.
    • Default
      Identifies the default policy. Set this policy as the default policy. Only one active default policy is allowed to exist. Creating a default policy automatically sets the current default policy to a nondefault status.
    • Has Key
      (Read-Only) indicates whether a public key has been associated with this policy. This field is updated when a public key is associated with a policy through the pdm_pki utility.
    • Allow Impersonate
      Identifies the allow impersonate permission. When you set this field, the policyholder can invoke the impersonate() web services method and create a web services session in the name of the user to be impersonated. Additional access authentication is not performed when creating the session. However, only when the access_level of the new access type for the user is less than or equal to the grant_level of the proxy access type for the user can this method be successfully called.
    • Description
      Indicates the detailed description of this access policy.
    • Ticket Creation
      Indicates the number of ticket (call request, change order, and issue) insertion operations allowed per hour.
    • Object Creation
      Indicates the number of CA SDM object (other than ticket object) insertion operations allowed per hour.
    • Object Updates
      Indicates the number of CA SDM object update operations allowed per hour.
    • Attachments
      Indicates the number of attachment-related operations allowed per hour.
    • Data Queries
      Indicates the number of data query operations allowed per hour.
    • Knowledge
      Indicates the number of knowledge-related operations allowed per hour.
  5. Click Save.
    The SOAP web services policy is defined.
Web Services Methods by Category
Each CA SDM Web Services method belongs to a specific category. The following lists each category and their corresponding methods:
  • Ticket Creation
  • Object Creation
  • Object Updates
  • Attachments
  • Data Queries
  • Knowledge
When an access policy is updated by CA SDM, Web Services dynamically updates the corresponding policy information. Active Web Services sessions controlled under this policy remain controlled with configurations in the policy. New Web Services sessions for this policy to manage and control, take the latest configurations in effect.
For information about each method, see the CA Service Desk Manager Reference Commands section.
Define an Error Type
Error types
are assigned when creating tickets and an access policy defines one set of these error types. A CA SDM Web Services user application may use low-level web methods to create a ticket (request, change order or issue), specifying one of these types to categorize the error addressed in the ticket. Error types can be used only with the high-level createTicket() method. Low-level methods, such as createRequest(), do not use error types.
Web Services Error Types
CA SDM Web Services also provides a defined set of default error types, which are created for
every
policy. These default types, designated as
internal
error types, can be deactivated, but cannot be deleted. In the product, you can use the Web Services Access Policy Detail page to see the default error types provided when a new policy is created.
The following information describes each internal error type:
  • ACCESS_ERROR
    Indicates that the system failed to connect to or find a resource, such as a file, website, and so on.
  • EXCEPTION_FATAL
    Indicates that the application is shutting down unexpectedly.
  • EXCEPTION_RUNTIME
    Indicates that the application code encountered an exception.
  • LOGIN_ERROR
    Indicates that the operator failed to gain access to the application.
Additional Error Types
The administrator of an access policy can add additional error types as described in the following information:
Error Type
Description
Ticket Template
Identifies a template of a Incident or Error, issue, or change order that you use to create a ticket when this error type is reported.
Note:
The owning policy’s contact is used as the end user.
The Ticket Type and Ticket Template Name define the ticket template.
Default
Indicates if this error type is the default for the policy. Only one default is allowed per policy.
Note:
A new default error type overwrites the existing default error type associated with the policy.
Active
Represents an active error type.
Note:
An inactive type does not create tickets.
Internal
Identifies the field as read-only, which indicates whether this error type is an internal, default error type.
Symbol
Indicates the symbolic name of the error type.
Code
Identifies the unique text identifier of the error type.
Description
Describes the detailed description of the error type.
Duplicate Handling
Defines the action to take when the product detects that an identical ticket already exists.
Return Data
Identifies the user-defined return message you can specify for the web method “createTicket()” to return to client applications. Return data might be used for indicating an action the application should take (Application Data Return), or a message (User Data Return) to display to the end user.
Duplicate Ticket Handling
The Web Service Access Policy can detect and handle duplicate tickets, which is helpful for preventing ticket flooding. A ticket created with the potential of being a duplicate applies if all of the following conditions are true:
  • At least one ticket of the same type (cr, iss, or chg) already exists and is ACTIVE.
  • The existing ticket was created by the web service.
  • The existing ticket was created with the same Policy and Error Type as the ticket being created.
  • The “create date” of the existing ticket is within a specified threshold (for example, it was opened less than 2 days ago).
    The create date field is configured using the Maximum time interval for searching duplicates.
  • The duplicate ID matches the one provided by users when invoking the createTicket() method.
Users can also assist in preventing duplicates by classifying tickets as being unique or different, based on criteria known to the user. To do this, add an optional string parameter to the createTicket Web Services call. If duplicate handling is on, the string parameter is inspected after other duplicate handling criteria match to determine whether this is a unique or duplicate call to this method.
Duplicate Ticket Results
If the create ticket action results in a duplicate, the existing Error Type may be configured to do one of the following:
Reconfigured Error Type
Results
Create the New Ticket and Ignore Duplicates
A new ticket handle and number are returned (default).
Do Not Create a New Ticket; Add an Activity Log to the Existing Duplicate Instead
The ticket handle and existing ticket number are returned.
Do Not Create a New ticket; Add an Entry to the CA SDM Standard Log Instead
A ticket handle and existing ticket number are returned.
Create a New Ticket and Attach it as a Child to the Duplicate
A new ticket handle and number are returned.
 
Simplified Web Services Access
CA SDM Web Services provides an abbreviated set of high-level web services methods that are simplified versions of existing web services methods. The majority of users applications do not have to completely rely on a large set of web services methods before requesting service desk services through CA SDM Web Services. Working closely with user-defined access policies and using default parameters defined in the policies, this set of high-level web services methods can function with little knowledge of the CA SDM object schema. Also, the high-level methods cover a common set of CA SDM functionalities that most service-aware applications need.
The following describes the use of these high-level web services methods:
  • createTicket (SID, Description, Error_Type, Userid, Asset, DuplicationID)
    You must specify an error type for the reported error if you use this method. The error type should contain the ticket template appropriate for the ticket you want to create. It should define the action to take in the case of a duplicate ticket, specify the data outputs, and finally, it must be associated to the access policy that is defined for the user application.
    When this method is invoked, CA SDM Web Services locates the current access policy and the error type required for the ticket creation. The following shows the sequence that CA SDM Web Services uses for locating the proper error type:
    • If a specific error type code is provided as input and it matches a error type that is associated to the policy, this error type is used, regardless of whether it is internal.
    • If an error type is not specified or the previous step fails to locate an error type, the default error type is used if there is one defined for the policy.
    • If a default error type is not defined for the policy or the previous step fails, the default error type defined for internal error types is used.
    After an error type is defined, CA SDM Web Services uses it to create a ticket. The proxy user defined in the access policy is used for the ticket creation if the userid is empty, and asset information is added to the ticket (if the input is not empty). After the ticket is created, CA SDM Web Services returns both user data and application data, as specified by the error type.
  • closeTicket (SID, Description, TicketHandle)
    Users can call this function to close an open ticket. It simply sets the status of an open ticket to ‘close’ and adds the input description to the activity log.
  • logComment (SID, TicketHandle, Comment, Internal_Flag)
    Adds an entry with the input comment to the activity log for the open ticket.
  • getPolicyInfo (SID)
    Lets users obtain the policy information that controls the current web services session. You can use this information as an indicator of server capacity for this user application. Users may want to adjust their web services calls to fit into the capacity.
By having this set of simplified Web Services APIs, a majority of users are spared the tremendous effort of understanding the complete set of web services API and CA SDM schema. Using them simplifies and accelerates the process of creating service-aware enabled applications for these users.