com.alarmpoint.servicemanager.cm
Class ServiceManagerScriptObject

java.lang.Object
  extended by com.alarmpoint.servicemanager.cm.ServiceManagerScriptObject

public class ServiceManagerScriptObject
extends java.lang.Object

Interfaces with the Service Manager SOAP web service in order to query, create and update records.

Author:
bneate/amagi

Constructor Summary
ServiceManagerScriptObject()
          Construct a uninitialized object.
ServiceManagerScriptObject(java.lang.String url, java.lang.String user, java.lang.String password)
          Construct a new ServiceManagerScriptObject with the specified url and user/password combination
 
Method Summary
 void annotateChange(java.lang.String changeId, org.dom4j.Element instance)
          Retract a Service Manager Change with the specified fields and values
 void annotateChange(java.lang.String changeId, java.util.Map<java.lang.String,java.lang.Object> fields)
          Retract a Service Manager Change with the specified fields and values
 void annotateChange(java.lang.String changeId, java.lang.String description)
          Annotate the Service Manager Change identified by the Change No.
 void annotateChange(java.lang.String changeId, java.lang.String type, java.lang.String operator, java.lang.String description)
          Annotate the Service Manager Change identified by the Change No.
 java.util.List<java.lang.String> approveChange(java.lang.String changeId, org.dom4j.Element instance)
          Approve a Service Manager Change with the specified fields and values
 java.util.List<java.lang.String> approveChange(java.lang.String changeId, java.util.Map<java.lang.String,java.lang.Object> fields)
          Approve a Service Manager Change with the specified fields and values
 java.util.List<java.lang.String> approveChange(java.lang.String changeId, java.lang.String message)
          Approve a Service Manager Change
 void closeChange(java.lang.String changeId, org.dom4j.Element instance)
          Close the Service Manager Change identified by the Change No.
 void closeChange(java.lang.String changeId, java.util.Map<java.lang.String,java.lang.Object> fields)
          Close the Service Manager Change identified by the Change No.
 void closeChange(java.lang.String changeId, java.lang.String resolution, java.lang.String fixType)
          Close the Service Manager incident identified by the Change No.
 java.util.List<java.lang.String> denyChange(java.lang.String changeId, org.dom4j.Element instance)
          Deny a Service Manager Change with the specified fields and values
 java.util.List<java.lang.String> denyChange(java.lang.String changeId, java.util.Map<java.lang.String,java.lang.Object> fields)
          Deny a Service Manager Change with the specified fields and values
 java.util.List<java.lang.String> denyChange(java.lang.String changeId, java.lang.String message)
          Deny a Service Manager Change
 java.util.List<ServiceManagerChange> getChangeRecords(java.lang.String changeID, java.lang.String action)
          Retrieves the related records for a particular change and returns a list of the related records in a ServiceManagerChange object depending on the called Webservice
 java.util.List<ServiceManagerChange> getChangeRecords(java.lang.String changeID, java.lang.String action, java.lang.String idTokenName)
          Retrieves the related records for a particular change and returns a list of the related records in a ServiceManagerChange object depending on the called Webservice This is necessary since the Approval records use "ChangeNumber" to identify them while Change uses "ChangeID".
 java.util.Map<java.lang.String,java.util.Collection<java.lang.String>> getGroupedList(java.lang.String operation, java.lang.String queryString, java.lang.String valueElement, java.lang.String groupElement)
          Retrieve a list of strings from Service Manager and group them based on a field on that object
 java.util.SortedSet<java.lang.String> getSortedList(java.lang.String operation, java.lang.String queryString, java.lang.String elementName)
          Retrieve a list of strings from Service Manager
 java.util.Collection<java.util.Map<java.lang.String,java.lang.String>> getValueMap(java.lang.String operation, java.lang.String queryString)
          Retrieve a list of all fields and values from Service Manager for a specified object
 void initializeClient(java.lang.String url, java.lang.String user, java.lang.String password)
          Initialize this class with the specified url and user/password combination
 java.util.List<ServiceManagerChange> queryChange(ServiceManagerQuery query)
          Retrieve a list of Changes from Service Manager
 java.util.List<ServiceManagerChange> queryChange(java.lang.String queryString)
          Retrieve a list of changes from Service Manager
 void retractChange(java.lang.String changeId, org.dom4j.Element instance)
          Retract a Service Manager Change with the specified fields and values
 void retractChange(java.lang.String changeId, java.util.Map<java.lang.String,java.lang.Object> fields)
          Retract a Service Manager Change with the specified fields and values
 void retractChange(java.lang.String changeId, java.lang.String message)
          Retract a Service Manager Change
 org.dom4j.Node sendReceive(java.lang.String action, org.dom4j.Element payload)
          Send a SOAP request to the Service Manager server and return the contents ot the returned SOAP body
 void updateChange(java.lang.String changeId, org.dom4j.Element instance)
          Update the Service Manager incident identified by the Change No.
 void updateChange(java.lang.String changeId, java.util.Map<java.lang.String,java.lang.Object> fields)
          Update the Service Manager incident identified by the Change No.
 void updateChange(java.lang.String changeId, java.lang.String message)
          Update the Service Manager Change identified by the Change No.
 void updateChange(java.lang.String changeId, java.lang.String message, java.lang.String status)
          Update the Service Manager incident identified by the incidentID with a journal update and status
 void updateChange(java.lang.String changeId, java.lang.String message, java.lang.String status, java.lang.String assignee)
          Update the Service Manager Change identified by the Change No.
 java.util.List<ServiceManagerChange> validateCredentials(java.lang.String operation, java.lang.String queryString)
          Given a List Operation this method will return null if the initialized credentials are valid and a string detailing the error otherwise
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ServiceManagerScriptObject

public ServiceManagerScriptObject()
Construct a uninitialized object. Make sure to run the initializeClient method before you use it


ServiceManagerScriptObject

public ServiceManagerScriptObject(java.lang.String url,
                                  java.lang.String user,
                                  java.lang.String password)
Construct a new ServiceManagerScriptObject with the specified url and user/password combination

Parameters:
url - The URL of the Service Manager web services
user - The user name to use for the Service Manager web services
password - The password to use for the Service Manager web services
Method Detail

initializeClient

public void initializeClient(java.lang.String url,
                             java.lang.String user,
                             java.lang.String password)
Initialize this class with the specified url and user/password combination

Parameters:
url - the url of the Service Manager web services
user - the user for the Service Manager web services
password - the password for the Service Manager web services

approveChange

public java.util.List<java.lang.String> approveChange(java.lang.String changeId,
                                                      java.lang.String message)
                                               throws ServiceManagerException
Approve a Service Manager Change
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
Returns:
Collection of user messages returned by the approve request
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

approveChange

public java.util.List<java.lang.String> approveChange(java.lang.String changeId,
                                                      java.util.Map<java.lang.String,java.lang.Object> fields)
                                               throws ServiceManagerException
Approve a Service Manager Change with the specified fields and values
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
fields - The Map used to construct the instance XML element
Returns:
Collection of user messages returned by the approve request
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

approveChange

public java.util.List<java.lang.String> approveChange(java.lang.String changeId,
                                                      org.dom4j.Element instance)
                                               throws ServiceManagerException
Approve a Service Manager Change with the specified fields and values
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
instance - the XML instance element for the create request
Returns:
Collection of user messages returned by the approve request
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

denyChange

public java.util.List<java.lang.String> denyChange(java.lang.String changeId,
                                                   java.lang.String message)
                                            throws ServiceManagerException
Deny a Service Manager Change
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
Returns:
Collection of user messages returned by the deny request
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

denyChange

public java.util.List<java.lang.String> denyChange(java.lang.String changeId,
                                                   java.util.Map<java.lang.String,java.lang.Object> fields)
                                            throws ServiceManagerException
Deny a Service Manager Change with the specified fields and values
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
fields - The Map used to construct the instance XML element
Returns:
Collection of user messages returned by the deny request
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

denyChange

public java.util.List<java.lang.String> denyChange(java.lang.String changeId,
                                                   org.dom4j.Element instance)
                                            throws ServiceManagerException
Deny a Service Manager Change with the specified fields and values
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
instance - the XML instance element for the create request
Returns:
Collection of user messages returned by the deny request
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

retractChange

public void retractChange(java.lang.String changeId,
                          java.lang.String message)
                   throws ServiceManagerException
Retract a Service Manager Change
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

retractChange

public void retractChange(java.lang.String changeId,
                          java.util.Map<java.lang.String,java.lang.Object> fields)
                   throws ServiceManagerException
Retract a Service Manager Change with the specified fields and values
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
fields - The Map used to construct the instance XML element
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

retractChange

public void retractChange(java.lang.String changeId,
                          org.dom4j.Element instance)
                   throws ServiceManagerException
Retract a Service Manager Change with the specified fields and values
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
instance - the XML instance element for the create request
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

annotateChange

public void annotateChange(java.lang.String changeId,
                           java.lang.String description)
                    throws ServiceManagerException
Annotate the Service Manager Change identified by the Change No. with a message. The type of change will default to AlarmPoint and the operator will default to the user used to make the request.
 Note: This method assumes that a extaccess record exists with the following values:
   Name: activitycm3r
   Object Name: ChangeActivity
   Data Policy:
     number field must have the ChangeID API Caption
     type field must have the Type API Caption
     operator field must have the Operator API Caption
     description field must have the Description API Caption
 

Parameters:
changeId - Change id identifying the incident to update
description - The update description
Throws:
ServiceManagerException - if the annotation was not successful

annotateChange

public void annotateChange(java.lang.String changeId,
                           java.lang.String type,
                           java.lang.String operator,
                           java.lang.String description)
                    throws ServiceManagerException
Annotate the Service Manager Change identified by the Change No. with a message
 Note: This method assumes that a extaccess record exists with the following values:
   Name: activitycm3r
   Object Name: ChangeActivity
   Data Policy:
     number field must have the ChangeID API Caption
     type field must have the Type API Caption
     operator field must have the Operator API Caption
     description field must have the Description API Caption
 

Parameters:
changeId - Change id identifying the incident to update
type - The type of this history item
operator - The operator updating this history item
description - The update description
Throws:
ServiceManagerException - if the annotation was not successful

annotateChange

public void annotateChange(java.lang.String changeId,
                           java.util.Map<java.lang.String,java.lang.Object> fields)
                    throws ServiceManagerException
Retract a Service Manager Change with the specified fields and values
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
fields - The Map used to construct the instance XML element
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

annotateChange

public void annotateChange(java.lang.String changeId,
                           org.dom4j.Element instance)
                    throws ServiceManagerException
Retract a Service Manager Change with the specified fields and values
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - change number
instance - the XML instance element for the create request
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

updateChange

public void updateChange(java.lang.String changeId,
                         java.lang.String message)
                  throws ServiceManagerException
Update the Service Manager Change identified by the Change No. with a journal update
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
     update.action field must have the JournalUpdates API Caption and Exclude false
 

Parameters:
changeId - Change ID identifying the change to update
message - The message to be added to the JournalUpdates
Throws:
ServiceManagerException - if the update was not successful

updateChange

public void updateChange(java.lang.String changeId,
                         java.lang.String message,
                         java.lang.String status)
                  throws ServiceManagerException
Update the Service Manager incident identified by the incidentID with a journal update and status
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
     update.action field must have the JournalUpdates API Caption and Exclude false
     problem.status field must have the IMTicketStatus API Caption and Exclude false
 

Parameters:
changeId - incident id identifying the incident to update
message - The message to be added to the JournalUpdates
status - The status to update the incident with
Throws:
ServiceManagerException - if the update was not successful

updateChange

public void updateChange(java.lang.String changeId,
                         java.lang.String message,
                         java.lang.String status,
                         java.lang.String assignee)
                  throws ServiceManagerException
Update the Service Manager Change identified by the Change No. with a journal update, status and assignee
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
     update.action field must have the JournalUpdates API Caption and Exclude false
     problem.status field must have the IMTicketStatus API Caption and Exclude false
     assignee.name field must have the AssigneeName API Caption and Exclude false
 

Parameters:
changeId - Change id identifying the incident to update
message - The message to be added to the JournalUpdates
status - The status to update the incident with
assignee - The assignee to update the incident with
Throws:
ServiceManagerException - if the update was not successful

updateChange

public void updateChange(java.lang.String changeId,
                         java.util.Map<java.lang.String,java.lang.Object> fields)
                  throws ServiceManagerException
Update the Service Manager incident identified by the Change No. with the specified fields and values
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - Change id identifying the incident to update
fields - The Map used to construct the instance XML element
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

updateChange

public void updateChange(java.lang.String changeId,
                         org.dom4j.Element instance)
                  throws ServiceManagerException
Update the Service Manager incident identified by the Change No. with the specified instance
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - Change id identifying the incident to update
instance - the XML instance element for the update request
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

closeChange

public void closeChange(java.lang.String changeId,
                        java.lang.String resolution,
                        java.lang.String fixType)
                 throws ServiceManagerException
Close the Service Manager incident identified by the Change No. with a resolution
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
     resolution field must have the Resolution API Caption and Exclude false
 

Parameters:
incidentId - Change id identifying the incident to close
resolution - The message to be added to the Resolution
fixType - Temporary or Permanent
Throws:
ServiceManagerException - if the update was not successful

closeChange

public void closeChange(java.lang.String changeId,
                        java.util.Map<java.lang.String,java.lang.Object> fields)
                 throws ServiceManagerException
Close the Service Manager Change identified by the Change No. with the specified fields and values
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - Change id identifying the incident to close
fields - The Map used to construct the instance XML element
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

closeChange

public void closeChange(java.lang.String changeId,
                        org.dom4j.Element instance)
                 throws ServiceManagerException
Close the Service Manager Change identified by the Change No. with the specified instance
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
   Data Policy:
     number field must have the Change No. API Caption and Exclude false
 

Parameters:
changeId - Change id identifying the incident to close
instance - the XML instance element for the close request
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

queryChange

public java.util.List<ServiceManagerChange> queryChange(ServiceManagerQuery query)
                                                 throws ServiceManagerException
Retrieve a list of Changes from Service Manager
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
 

Parameters:
query - A ServiceManagerQuery object used to construct the Service Manager query
Returns:
A list of ServiceManagerChange objects representing the incidents retrieved from Service Manager
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

queryChange

public java.util.List<ServiceManagerChange> queryChange(java.lang.String queryString)
                                                 throws ServiceManagerException
Retrieve a list of changes from Service Manager
 Note: This method assumes that a extaccess record exists with the following values:
   Name: cm3r
   Object Name: Change
 

Parameters:
queryString - The search query passed to Service Manager
Returns:
A list of ServiceManagerChange objects representing the Changes retrieved from Service Manager
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

getChangeRecords

public java.util.List<ServiceManagerChange> getChangeRecords(java.lang.String changeID,
                                                             java.lang.String action,
                                                             java.lang.String idTokenName)
                                                      throws ServiceManagerException
Retrieves the related records for a particular change and returns a list of the related records in a ServiceManagerChange object depending on the called Webservice This is necessary since the Approval records use "ChangeNumber" to identify them while Change uses "ChangeID". The numbers are the same, just the ID is different.

Parameters:
ChangeID - unique key used to identify the change
action - String identifying the webservice request that will be made
idTokenName - String identifying the Change ID token in the Web Service request
Returns:
A list of ServiceManagerChange records matching the related query
Throws:
ServiceManagerException

getChangeRecords

public java.util.List<ServiceManagerChange> getChangeRecords(java.lang.String changeID,
                                                             java.lang.String action)
                                                      throws ServiceManagerException
Retrieves the related records for a particular change and returns a list of the related records in a ServiceManagerChange object depending on the called Webservice

Parameters:
ChangeID - unique key used to identify the change
action - String identifying the webservice request that will be made
Returns:
A list of ServiceManagerChange records matching the related query
Throws:
ServiceManagerException

getSortedList

public java.util.SortedSet<java.lang.String> getSortedList(java.lang.String operation,
                                                           java.lang.String queryString,
                                                           java.lang.String elementName)
                                                    throws ServiceManagerException
Retrieve a list of strings from Service Manager

Parameters:
operation - The name of the root element of the request ("RetrieveCategoryListRequest" for example)
queryString - The query used to select the values
elementName - the API Caption of the field to return the values for
Returns:
A list of strings retrieved from Service Manager
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

getValueMap

public java.util.Collection<java.util.Map<java.lang.String,java.lang.String>> getValueMap(java.lang.String operation,
                                                                                          java.lang.String queryString)
                                                                                   throws ServiceManagerException
Retrieve a list of all fields and values from Service Manager for a specified object

Parameters:
operation - The name of the root element of the request ("RetrieveCategoryListRequest" for example)
queryString - The query used to select the values
Returns:
A list of maps where the key is the field name and the value is the field value
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

getGroupedList

public java.util.Map<java.lang.String,java.util.Collection<java.lang.String>> getGroupedList(java.lang.String operation,
                                                                                             java.lang.String queryString,
                                                                                             java.lang.String valueElement,
                                                                                             java.lang.String groupElement)
                                                                                      throws ServiceManagerException
Retrieve a list of strings from Service Manager and group them based on a field on that object

Parameters:
operation - The name of the root element of the request ("RetrieveCategoryListRequest" for example)
queryString - The query used to select the values
valueElement - the API Caption of the field to return the values for
groupElement - the API Caption of the field to group the returned values by
Returns:
A map of strings to a list of strings where the key is the value of the groupElement and the value is list of valueElements associated with the groupElement
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

validateCredentials

public java.util.List<ServiceManagerChange> validateCredentials(java.lang.String operation,
                                                                java.lang.String queryString)
                                                         throws ServiceManagerException
Given a List Operation this method will return null if the initialized credentials are valid and a string detailing the error otherwise

Parameters:
operation - The name of the root element of the request ("RetrieveCategoryListRequest" for example)
queryString - String containing the query to pass into the operation
Returns:
Collection of Groups the user belongs to
Throws:
ServiceManagerException - if a error occurs with a message detailing that error

sendReceive

public org.dom4j.Node sendReceive(java.lang.String action,
                                  org.dom4j.Element payload)
                           throws ServiceManagerException
Send a SOAP request to the Service Manager server and return the contents ot the returned SOAP body

Parameters:
action - The SOAP Action to perform in Service Manager. The possible values are defined on the extaccess table
payload - A dom4j Element that will be the payload of the SOAP request
Returns:
A dom4j Node containing the contents of the returned SOAP body element
Throws:
ServiceManagerException - if a error occurs with a message detailing that error