×
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')
 
 
  •  

 

This documentation supports the 21.3 version of BMC Helix ITSM.

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

BMC Helix ITSM 21.3 ... Developing Developing integrations by using SOAP web services

Testing web services by using SoapUI

You can test web services by using a web services client. Although any typical development environment has some capability to consume web services, we recommend 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/.

To acquire 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 AR System has an associated WSDL description. Most of the out-of-the-box web services in AR System are password protected, which prevents you from directly downloading the WSDL from within SoapUI or a development environment.

  1. Open a browser and log on to your AR System environment.
  2. After accessing the AR System 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 AR System 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.

To create 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 AR System 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 AR System 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 navigator.

To modify and submit the web services request

Perform the following steps to modify and submit the request:

  1. Provide 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 provide 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_ARS_USER_NAME</urn:userName>
         <urn:password>YOUR_ARS_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 to send the request to the AR System web service.
    The resulting content is displayed in the request.

To set up a web services request to create an incident

The main web service in BMC Helix ITSM for creating incidents is HPD_IncidentInterface_Create_WS. This web service has HelpDesk_Submit_Service method that enables 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 by using the WSDL for this web service, and open the generated request; for 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 ITSM Impact, Reported_Source, Service_Type, Status, and Urgency fields must be populated with values that are appropriate to the form and that are available in the selection lists of the form. The allowed values are viewable in the downloaded WSDL.

You can also reduce this request to the minimum required fields 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_ARS_USERNAME</urn:userName>
         <urn:password>YOUR_ARS_PASSWORD</urn:password>
      </urn:AuthenticationInfo>
   </soapenv:Header>
   <soapenv:Body>
      <urn:HelpDesk_Submit_Service>
         <urn:First_Name>YOUR_ARS_FIRSTNAME</urn:First_Name>
         <urn:Impact>4-Minor/Localized</urn:Impact>
         <urn:Last_Name>YOUR_ARS_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>

To submit and view response data

Submit this completed web services request to generate an incident. The resulting return content is similar to the following 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.

To handle 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_ARS_USERNAME</urn:userName>
         <urn:password>YOUR_ARS_PASSWORD</urn:password>
      </urn:AuthenticationInfo>
   </soapenv:Header>
   <soapenv:Body>
      <urn:HelpDesk_Submit_Service>
         <urn:Assigned_Group>YOUR_ARS_ASSIGN_GROUP</urn:Assigned_Group>
         <urn:Assigned_Support_Company>YOUR_ARS_ASSIGN_COMPANY</urn:Assigned_
Support_Company>
         <urn:Assigned_Support_Organization>YOUR_ARS_ASSIGN_ORGANIZATION</urn:Assigned_
Support_Organization>
         <urn:First_Name>YOUR_ARS_FIRSTNAME</urn:First_Name>
         <urn:Impact>4-Minor/Localized</urn:Impact>
         <urn:Last_Name>YOUR_ARS_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>

To add 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_ARS_USERNAME</urn:userName>
         <urn:password>YOUR_ARS_PASSWORD</urn:password>
      </urn:AuthenticationInfo>
   </soapenv:Header>
   <soapenv:Body>
      <urn:HelpDesk_Submit_Service>
         <urn:Assigned_Group>YOUR_ARS_ASSIGN_GROUP</urn:Assigned_Group>
         <urn:Assigned_Support_Company>YOUR_ARS_ASSIGN_COMPANY</urn:Assigned_
Support_Company>
         <urn:Assigned_Support_Organization>YOUR_ARS_ASSIGN_ORGANIZATION</urn:Assigned_
Support_Organization>
         <urn:First_Name>YOUR_ARS_FIRSTNAME</urn:First_Name>
         <urn:Impact>4-Minor/Localized</urn:Impact>
         <urn:Last_Name>YOUR_ARS_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>

To use 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.

The following example is of a Perl script that creates an incident for the BMC Helix ITSM environment:

#!/usr/bin/perl -w

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

my $username = "YOUR_ARS_USERNAME";
my $password = "YOUR_ARS_PASSWORD";
my $timeZone = "";

my $incident_first_name         = "YOUR_ARS_FIRSTNAME";
my $incident_last_name          = "YOUR_ARS_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_ARS_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
Last modified by Jyoti Nerkar on Sep 08, 2021
reference web_services soapui wsdl_descriptions

Comments

Log in or register to comment.

BMC Helix ITSM integrations
Troubleshooting
© Copyright 1991 - 2022 BMC Software, Inc. © Copyright 1991 - 2022 BladeLogic, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2023 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.