Space banner

 

This documentation supports the 19.08 version of Remedy IT Service Management Suite.

To view an earlier version, select the version from the Product version menu.

Testing web services using soapUI

Testing web services requires the use of a web services client. Although any typical development environment (for example, Java, .Net, or Perl) has some capability to consume web services, BMC recommends that you use soapUI for testing. soapUI is a widely used open-source tool for testing web services. To download soapUI, go to http://www.soapui.org/.

Acquiring the WSDL description

Web services testing and development is based on the use of the Web Services Description Language (WSDL) description for a web service and its various inputs and outputs. Each web service in BMC Remedy has an associated WSDL description. Most of the out-of-the-box web services in BMC Remedy are password protected, which prevents you from directly downloading the WSDL from within soapUI or a development environment.

To acquire the WSDL description for a web service

  1. Open a browser and log on to your BMC Remedy AR System environment.
  2. After accessing the BMC Remedy home page, change the URL in the address bar to https://<midtierServer>/arsys/WSDL/protected/list.
    A list of the web services that are exposed by the BMC Remedy platform is displayed.
  3. Click the link for the required web service to download the WSDL description to your browser.
  4. Save the resulting XML content to a file.

Creating a project in soapUI

  1. In the soapUI menu, select File > New soapUI project.
  2. Assign a name to the project.
  3. In the Initial WSDL text box, navigate to the saved WSDL file that you have already downloaded. If the BMC Remedy web service is marked as public, you can enter the URL for the WSDL in the Initial WSDL text box. Most services are marked as protected in BMC Remedy, requiring a separate download.

After you create the project, a sample request for each method exposed by the web service is displayed under the project in the left-side navigator.

Modifying and submitting the web services request

Now that you have a prebuilt request, perform the following steps to modify and submit the request:

  1. Supply any required values by replacing the ? in each field with the appropriate value.
    Fields that are not required are prefixed with an XML comment of optional. If you do not supply a value for an optional field, delete or comment it out from the XML request.

    The following example is for the HelpDesk_Query_Service for the HPD_IncidentInterface web service:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:HPD_IncidentInterface_WS">
       <soapenv:Header>
          <urn:AuthenticationInfo>
             <urn:userName>?</urn:userName>
             <urn:password>?</urn:password>
             <!--Optional:-->
             <urn:authentication>?</urn:authentication>
             <!--Optional:-->
             <urn:locale>?</urn:locale>
             <!--Optional:-->
             <urn:timeZone>?</urn:timeZone>
          </urn:AuthenticationInfo>
       </soapenv:Header>
       <soapenv:Body>
          <urn:HelpDesk_Query_Service>
             <urn:Incident_Number>?</urn:Incident_Number>
          </urn:HelpDesk_Query_Service>
       </soapenv:Body>
    </soapenv:Envelope>


    To submit the request, you must supply values for userName, password, and Incident_Number, and then remove the optional values, which results in the following XML:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:HPD_IncidentInterface_WS">
       <soapenv:Header>
          <urn:AuthenticationInfo>
             <urn:userName>YOUR_REMEDY_USER_NAME</urn:userName>
             <urn:password>YOUR_REMEDY_PASSWORD</urn:password>
          </urn:AuthenticationInfo>
       </soapenv:Header>
       <soapenv:Body>
          <urn:HelpDesk_Query_Service>
             <urn:Incident_Number>INC0000009999</urn:Incident_Number>
          </urn:HelpDesk_Query_Service>
       </soapenv:Body>
    </soapenv:Envelope>
  2. Click Submit (green arrow) to send the request to the BMC Remedy web service.
    The resulting content is displayed in the right-hand side of the request.

Setting up a web services request to create an incident

The main web service in BMC Remedy ITSM for creating incidents is HPD_IncidentInterface_Create_WS. This web service has just one method, which is HelpDesk_Submit_Service, and it allows you to create a new incident. 

Individual customer sites might overlay or modify this standard service, so different customer sites might have different services.

Set up a project in soapUI using the WSDL for this web service, and open the generated request. Following is an example.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:HPD_IncidentInterface_Create_WS">
   <soapenv:Header>
      <urn:AuthenticationInfo>
         <urn:userName>?</urn:userName>
         <urn:password>?</urn:password>
         <!--Optional:-->
         <urn:authentication>?</urn:authentication>
         <!--Optional:-->
         <urn:locale>?</urn:locale>
         <!--Optional:-->
         <urn:timeZone>?</urn:timeZone>
      </urn:AuthenticationInfo>
   </soapenv:Header>
   <soapenv:Body>
      <urn:HelpDesk_Submit_Service>
         <!--Optional:-->
         <urn:Assigned_Group>?</urn:Assigned_Group>
         <!--Optional:-->
         <urn:Assigned_Group_Shift_Name>?</urn:Assigned_Group_Shift_Name>
         <!--Optional:-->
         <urn:Assigned_Support_Company>?</urn:Assigned_Support_Company>
         <!--Optional:-->
         <urn:Assigned_Support_Organization>?</urn:Assigned_Support_Organization>
         <!--Optional:-->
         <urn:Assignee>?</urn:Assignee>
         <!--Optional:-->
         <urn:Categorization_Tier_1>?</urn:Categorization_Tier_1>
         <!--Optional:-->
         <urn:Categorization_Tier_2>?</urn:Categorization_Tier_2>
         <!--Optional:-->
         <urn:Categorization_Tier_3>?</urn:Categorization_Tier_3>
         <!--Optional:-->
         <urn:CI_Name>?</urn:CI_Name>
         <!--Optional:-->
         <urn:Closure_Manufacturer>?</urn:Closure_Manufacturer>
         <!--Optional:-->
         <urn:Closure_Product_Category_Tier1>?</urn:Closure_Product_Category_Tier1>
         <!--Optional:-->
         <urn:Closure_Product_Category_Tier2>?</urn:Closure_Product_Category_Tier2>
         <!--Optional:-->
         <urn:Closure_Product_Category_Tier3>?</urn:Closure_Product_Category_Tier3>
         <!--Optional:-->
         <urn:Closure_Product_Model_Version>?</urn:Closure_Product_Model_Version>
         <!--Optional:-->
         <urn:Closure_Product_Name>?</urn:Closure_Product_Name>
         <!--Optional:-->
         <urn:Department>?</urn:Department>
         <urn:First_Name>?</urn:First_Name>
         <urn:Impact>?</urn:Impact>
         <urn:Last_Name>?</urn:Last_Name>
         <!--Optional:-->
         <urn:Lookup_Keyword>?</urn:Lookup_Keyword>
         <!--Optional:-->
         <urn:Manufacturer>?</urn:Manufacturer>
         <!--Optional:-->
         <urn:Product_Categorization_Tier_1>?</urn:Product_Categorization_Tier_1>
         <!--Optional:-->
         <urn:Product_Categorization_Tier_2>?</urn:Product_Categorization_Tier_2>
         <!--Optional:-->
         <urn:Product_Categorization_Tier_3>?</urn:Product_Categorization_Tier_3>
         <!--Optional:-->
         <urn:Product_Model_Version>?</urn:Product_Model_Version>
         <!--Optional:-->
         <urn:Product_Name>?</urn:Product_Name>
         <urn:Reported_Source>?</urn:Reported_Source>
         <!--Optional:-->
         <urn:Resolution>?</urn:Resolution>
         <!--Optional:-->
         <urn:Resolution_Category_Tier_1>?</urn:Resolution_Category_Tier_1>
         <!--Optional:-->
         <urn:Resolution_Category_Tier_2>?</urn:Resolution_Category_Tier_2>
         <!--Optional:-->
         <urn:Resolution_Category_Tier_3>?</urn:Resolution_Category_Tier_3>
         <urn:Service_Type>?</urn:Service_Type>
         <urn:Status>?</urn:Status>
         <urn:Action>?</urn:Action>
         <!--Optional:-->
         <urn:Create_Request>?</urn:Create_Request>
         <urn:Summary>?</urn:Summary>
         <!--Optional:-->
         <urn:Notes>?</urn:Notes>
         <urn:Urgency>?</urn:Urgency>
         <!--Optional:-->
         <urn:Work_Info_Summary>?</urn:Work_Info_Summary>
         <!--Optional:-->
         <urn:Work_Info_Notes>?</urn:Work_Info_Notes>
         <!--Optional:-->
         <urn:Work_Info_Type>?</urn:Work_Info_Type>
         <!--Optional:-->
         <urn:Work_Info_Date>?</urn:Work_Info_Date>
         <!--Optional:-->
         <urn:Work_Info_Source>?</urn:Work_Info_Source>
         <!--Optional:-->
         <urn:Work_Info_Locked>?</urn:Work_Info_Locked>
         <!--Optional:-->
         <urn:Work_Info_View_Access>?</urn:Work_Info_View_Access>
         <!--Optional:-->
         <urn:Middle_Initial>?</urn:Middle_Initial>
         <!--Optional:-->
         <urn:Status_Reason>?</urn:Status_Reason>
         <!--Optional:-->
         <urn:Direct_Contact_First_Name>?</urn:Direct_Contact_First_Name>
         <!--Optional:-->
         <urn:Direct_Contact_Middle_Initial>?</urn:Direct_Contact_Middle_Initial>
         <!--Optional:-->
         <urn:Direct_Contact_Last_Name>?</urn:Direct_Contact_Last_Name>
         <!--Optional:-->
         <urn:TemplateID>?</urn:TemplateID>
         <!--Optional:-->
         <urn:ServiceCI>?</urn:ServiceCI>
         <!--Optional:-->
         <urn:ServiceCI_ReconID>?</urn:ServiceCI_ReconID>
         <!--Optional:-->
         <urn:HPD_CI>?</urn:HPD_CI>
         <!--Optional:-->
         <urn:HPD_CI_ReconID>?</urn:HPD_CI_ReconID>
         <!--Optional:-->
         <urn:HPD_CI_FormName>?</urn:HPD_CI_FormName>
         <!--Optional:-->
         <urn:WorkInfoAttachment1Name>?</urn:WorkInfoAttachment1Name>
         <!--Optional:-->
         <urn:WorkInfoAttachment1Data>cid:114727192956</urn:WorkInfoAttachment1Data>
         <!--Optional:-->
         <urn:WorkInfoAttachment1OrigSize>?</urn:WorkInfoAttachment1OrigSize>
      </urn:HelpDesk_Submit_Service>
   </soapenv:Body>
</soapenv:Envelope>

The BMC Remedy Impact, Reported_Source, Service_Type, Status, and Urgency fields must be populated with values appropriate to the form. You can provide any suitable values as long as they are in the selection lists in the form. The allowed values are also viewable in the downloaded WSDL.

You can also reduce this request to the minimum required fields that are required to create an incident by removing all of the Optional fields from this XML, which results in the following XML:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:HPD_IncidentInterface_Create_WS">
   <soapenv:Header>
      <urn:AuthenticationInfo>
         <urn:userName>YOUR_REMEDY_USERNAME</urn:userName>
         <urn:password>YOUR_REMEDY_PASSWORD</urn:password>
      </urn:AuthenticationInfo>
   </soapenv:Header>
   <soapenv:Body>
      <urn:HelpDesk_Submit_Service>
         <urn:First_Name>YOUR_REMEDY_FIRSTNAME</urn:First_Name>
         <urn:Impact>4-Minor/Localized</urn:Impact>
         <urn:Last_Name>YOUR_REMEDY_LASTNAME</urn:Last_Name>
         <urn:Reported_Source>Other</urn:Reported_Source>
         <urn:Service_Type>User Service Request</urn:Service_Type>
         <urn:Status>New</urn:Status>
         <urn:Action>CREATE</urn:Action>
         <urn:Summary>YOUR_SUMMARY_NOTES</urn:Summary>
         <urn:Urgency>4-Low</urn:Urgency>
      </urn:HelpDesk_Submit_Service>
   </soapenv:Body>
</soapenv:Envelope>

Submitting and viewing response data

Submit this completed web services request to generate an incident. The resulting return content is similar to the followning example:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <ns0:HelpDesk_Submit_ServiceResponse xmlns:ns0="urn:HPD_IncidentInterface_Create_WS">
         <ns0:Incident_Number>INC000000104613</ns0:Incident_Number>
      </ns0:HelpDesk_Submit_ServiceResponse>
   </soapenv:Body>
</soapenv:Envelope>

The response value has the generated incident number for the newly created incident.

Handling group assignment

A common issue that might occur is group assignment. You might receive an error message instead of an incident number, indicating that no automatic group assignment could occur. In some customer environments, automatic routing of incidents to groups is not enabled, so the web services request must include additional fields to assign the incident to a group. The additional fields are Assigned_Group, Assigned_Support_Company, and Assigned_Support_Organization:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:HPD_IncidentInterface_Create_WS">
   <soapenv:Header>
      <urn:AuthenticationInfo>
         <urn:userName>YOUR_REMEDY_USERNAME</urn:userName>
         <urn:password>YOUR_REMEDY_PASSWORD</urn:password>
      </urn:AuthenticationInfo>
   </soapenv:Header>
   <soapenv:Body>
      <urn:HelpDesk_Submit_Service>
         <urn:Assigned_Group>YOUR_REMEDY_ASSIGN_GROUP</urn:Assigned_Group>
         <urn:Assigned_Support_Company>YOUR_REMEDY_ASSIGN_COMPANY</urn:Assigned_
Support_Company>
         <urn:Assigned_Support_Organization>YOUR_REMEDY_ASSIGN_ORGANIZATION</urn:Assigned_
Support_Organization>
         <urn:First_Name>YOUR_REMEDY_FIRSTNAME</urn:First_Name>
         <urn:Impact>4-Minor/Localized</urn:Impact>
         <urn:Last_Name>YOUR_REMEDY_LASTNAME</urn:Last_Name>
         <urn:Reported_Source>Other</urn:Reported_Source>
         <urn:Service_Type>User Service Request</urn:Service_Type>
         <urn:Status>New</urn:Status>
         <urn:Action>CREATE</urn:Action>
         <urn:Summary>YOUR_SUMMARY_NOTES</urn:Summary>
         <urn:Urgency>4-Low</urn:Urgency>
      </urn:HelpDesk_Submit_Service>
   </soapenv:Body>
</soapenv:Envelope>

Adding more fields

You can add any additional fields to the web services call as required, but the fields must stay in exactly the same order as defined in the WSDL (original request). For example, to add the optional Notes field, you can see that Notes appears after Summary and before Urgency in the original request, which results in the following XML:

<soapenv:Envelope   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:HPD_IncidentInterface_Create_WS">
   <soapenv:Header>
      <urn:AuthenticationInfo>
         <urn:userName>YOUR_REMEDY_USERNAME</urn:userName>
         <urn:password>YOUR_REMEDY_PASSWORD</urn:password>
      </urn:AuthenticationInfo>
   </soapenv:Header>
   <soapenv:Body>
      <urn:HelpDesk_Submit_Service>
         <urn:Assigned_Group>YOUR_REMEDY_ASSIGN_GROUP</urn:Assigned_Group>
         <urn:Assigned_Support_Company>YOUR_REMEDY_ASSIGN_COMPANY</urn:Assigned_
Support_Company>
         <urn:Assigned_Support_Organization>YOUR_REMEDY_ASSIGN_ORGANIZATION</urn:Assigned_
Support_Organization>
         <urn:First_Name>YOUR_REMEDY_FIRSTNAME</urn:First_Name>
         <urn:Impact>4-Minor/Localized</urn:Impact>
         <urn:Last_Name>YOUR_REMEDY_LASTNAME</urn:Last_Name>
         <urn:Reported_Source>Other</urn:Reported_Source>
         <urn:Service_Type>User   Service Request</urn:Service_Type>
         <urn:Status>New</urn:Status>
         <urn:Action>CREATE</urn:Action>
         <urn:Summary>YOUR_SUMMARY_NOTES</urn:Summary>
         <urn:Notes>YOUR_ADDITIONAL_NOTES</urn:Notes>
         <urn:Urgency>4-Low</urn:Urgency>
      </urn:HelpDesk_Submit_Service>
   </soapenv:Body>
</soapenv:Envelope>

Using Perl to create an incident

To use the Perl environment to create an incident through web services, you must install the SOAP::Lite, XML::Writer, and XML::Writer::String modules in the Perl environment. These modules are available from the Comprehensive Perl Archive Network (CPAN) at www.cpan.org.

Following is an example of a Perl script that creates an incident for the BMC Remedy OnDemand environment:

#!/usr/bin/perl -w

use SOAP::Lite
# trace=>'all'
;
use XML::Writer;
use XML::Writer::String;

my $username = "YOUR_REMEDY_USERNAME";
my $password = "YOUR_REMEDY_PASSWORD";
my $timeZone = "";

my $incident_first_name         = "YOUR_REMEDY_FIRSTNAME";
my $incident_last_name          = "YOUR_REMEDY_LASTNAME";
my $incident_impact             = "4-Minor/Localized";
my $incident_urgency            = "4-Low";
my $incident_reported_source    = "Other";
my $incident_service_type       = "Infrastructure Event";
my $incident_summary            = "YOUR_REMEDY_SUMMARY_NOTES";

my $create_proxy = "https://midtierServer/arsys/services/ARService?server=onbmc-s&webService=HPD_IncidentInterface_Create_WS";

onbmc_create();

sub onbmc_create {
  my @logininfo = (
    SOAP::Header->name('userName' => $username)->type(''),
    SOAP::Header->name('password' => $password)->type(''),
    SOAP::Header->name('timeZone' => $timeZone)->type('')
  );

  my $header = SOAP::Header->name('AuthenticationInfo' => \SOAP::Header->value(@logininfo));

  my @data = (
    SOAP::Data->name(First_Name                       => $incident_first_name)->type('xsd:string'),
    SOAP::Data->name(Impact                           => $incident_impact)->type('xsd:string'),
    SOAP::Data->name(Last_Name                        => $incident_last_name)->type('xsd:string'),
    SOAP::Data->name(Reported_Source                  => $incident_reported_source)->type('xsd:string'),
    SOAP::Data->name(Service_Type                     => $incident_service_type)->type('xsd:string'),
    SOAP::Data->name(Status                           => "New")->type('xsd:string'),
    SOAP::Data->name(Action                           => "CREATE")->type('xsd:string'),
    SOAP::Data->name(Summary                          => $incident_summary)->type('xsd:string'),
    SOAP::Data->name(Urgency                          => $incident_urgency)->type('xsd:string')
  );

  my $soap = new SOAP::Lite proxy=>$create_proxy;
  my $result=$soap->HelpDesk_Submit_Service($header, @data);

  if ($result->fault) {
    print "faultcode=" . $result->fault->{'faultcode'} . "\n";
    print "faultstring=" . $result->fault->{'faultstring'} . "\n";
    print "detail=" . $result->fault->{'detail'} . "\n";
  }

  if ($result->body && $result->body->{'HelpDesk_Submit_ServiceResponse'}) {
    my %keyHash = %{ $result->body->{'HelpDesk_Submit_ServiceResponse'} };
    foreach my $k (keys %keyHash) {
        print "name=$k   value=$keyHash{$k}\n";
    }
  }
}


Was this page helpful? Yes No Submitting... Thank you

Comments