Integrate > Service Manager integration methods and tools > Web Services > SOAP API > Consuming a Service Manager Web Service > Attachment operations using the SOAP API

Attachment operations using the SOAP API

Service Manager supports all typical attachment operations using its web services (SOAP API) or REST API. These operations include: get attachment information, get (single) attachment, delete (single) attachment, insert attachment, and so on.

The following topics describes how to perform typical attachment operations by using the web services (SOAP) API. It provides information about the services published by Service Manager, and explains requests of an external application being sent to Service Manager, as well as the responses to expect.

Tip This topic describes attachment operations that you can perform using the Service Manager web services (SOAP API). For information about attachment operations using the REST API, see Attachment operations using the RESTful API.

When writing Web services requests, the WSDL files published by Service Manager on the published services contain the API information. These files are auto-generated from the extaccess dbdict. They can be displayed in a browser using a URL like any one of the following:

  • http://localhost:13080/sc62server/PWS/IncidentManagement.wsdl
  • http://localhost:13080/SM/7/IncidentManagement.wsdl

Note When the sc62server URL is used, the attachment format is MIME; when the SM/7 URL is used, the attachment format is MTOM.

Tip Testing web services with tools is quite easy. To avoid unnecessary complexity, the SoapUI tool is used for the example below.

Both the request and response tag names include the operation name (for example, Retrieve or Update), and the target object name (for example, Incident) in name space http://schemas.hp.com/SM/7.

The following is an example of a request tag (the prefix ns refers to the namespace definition in the <soapenv> tag):

<ns:RetrieveIncidentRequest>

The following is an example of a response tag:

<RetrieveIncidentResponse>

The operation is also reflected in the HTTP header property named SOAPAction. For example:

SOAPAction: "Update"

If the request tag and the SOAPAction header do not match, the response shows an error message:

<faultstring>A CXmlApiException was raised in native code : error 16 : scxmlapi(16) - Invalid or missing file name in XML request</faultstring>

Retrieve attachment information

Set up a Retrieve request and set the attachmentInfo attribute in the request tag to true.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://schemas.hp.com/SM/7" xmlns:com="http://schemas.hp.com/SM/7/Common" xmlns:xm="http://www.w3.org/2005/05/xmlmime">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:RetrieveIncidentRequest attachmentInfo="true">
         <ns:model>
            <ns:keys><ns:IncidentID>IM10003</ns:IncidentID></ns:keys>
            <ns:instance></ns:instance>
         </ns:model>
      </ns:RetrieveIncidentRequest>
   </soapenv:Body>
</soapenv:Envelope>

The response contains the complete Incident data (shortened in the example below) and the attachment information:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <RetrieveIncidentResponse message="Success" returnCode="0" schemaRevisionDate="2016-05-10" schemaRevisionLevel="0" status="SUCCESS" xsi:schemaLocation="http://servicecenter.peregrine.com/PWS http://bra03sm25.eu.hpecorp.net:13080/sc62server/Incident.xsd" xmlns="http://servicecenter.peregrine.com/PWS" xmlns:cmn="http://servicecenter.peregrine.com/PWS/Common" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <model>
            <keys>
               <IncidentID type="String">IM10003</IncidentID>
            </keys>
            <instance recordid="IM10003 - Not able to print" uniquequery="number=&quot;IM10003&quot;">
               <IncidentID type="String">IM10003</IncidentID>
[..]
               <attachments>
                  <cmn:attachment href="cid:551bb5d00003a005805a1278" len="19779" name="cwc_labels_ru.utf8" type="application/octet-stream" upload.by="falcon" upload.date="04/01/15 03:09:36"/>
                  <cmn:attachment href="cid:551bb5d00008c006805a1278" len="12842" name="cwc_labels_en.properties" type="application/octet-stream" upload.by="falcon" upload.date="04/01/15 03:09:36"/>
                  <cmn:attachment href="cid:551bb5d0000b8007805a1278" len="14606" name="cwc_labels_de.utf8" type="application/octet-stream" upload.by="falcon" upload.date="04/01/15 03:09:36"/>
                  <cmn:attachment href="cid:5668051d000e901f808612a0" len="21579" name="cimultirel.unl" type="application/octet-stream" upload.by="falcon" upload.date="12/09/15 03:40:29"/>
                  <cmn:attachment href="cid:566808350013605b809bd6c0" len="27944" name="cimultirel_v2.1.unl" type="application/octet-stream" upload.by="falcon" upload.date="12/09/15 03:53:41"/>
               </attachments>
            </instance>
         </model>
      </RetrieveIncidentResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In the attachment information section, the href attribute contains the content id for each attachment.

Note When the attachmentData attribute in the request tag is set to true, the response contains all file attachments. If attachmentData is set to true, the attachment information is always included in the response, regardless of the attachmentInfo attribute.

Retrieve a single attachment

In the attachments tag, specify the attachment using the href attribute and set the attribute action to get. In the request tag, the attachmentData attribute must exist and must be set to true.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://schemas.hp.com/SM/7" xmlns:com="http://schemas.hp.com/SM/7/Common" xmlns:xm="http://www.w3.org/2005/05/xmlmime">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:RetrieveIncidentRequest attachmentData="true">
         <ns:model>
            <ns:keys><ns:IncidentID>IM10003</ns:IncidentID></ns:keys>
            <ns:instance>
               <attachments>
                  <attachment href="cid:551bb5d00003a005805a1278" action="get"/>
               </attachments>
            </ns:instance>
         </ns:model>
      </ns:RetrieveIncidentRequest>
   </soapenv:Body>
</soapenv:Envelope>

Now the attachment appears below the XML response in Soap UI.

The raw message showing the file contents is put into a separate HTTP message part:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=7A8FB01D34C0CF736842A48724DF3FB5; Path=/sc62server/; HttpOnly
Keep-Alive: timeout=1200000, max=1000
Connection: Keep-Alive
Content-Encoding: gzip
Content-Type: multipart/related; boundary="----=_Part_56_30479565.1495112821461"; type="text/xml"
Transfer-Encoding: chunked
Date: Thu, 18 May 2017 13:07:01 GMT
 
------=_Part_56_30479565.1495112821461
Content-Type: text/xml; charset=utf-8
 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Body><RetrieveIncidentResponse message="Success" returnCode="0"  
[..]
------=_Part_56_30479565.1495112821461
Content-Type: application/octet-stream
Content-Location: cwc_labels_ru.utf8
Content-ID: cid:551bb5d00003a005805a1278
 
# <!-- (C) Copyright Hewlett-Packard Company, L.P. All Rights Reserved. -->
AboutPage.Title=О программном обе�печении HP
[..]

Delete an attachment

To remove an attachment, set the action for the attachment to remove.

Any manipulation of an attached file requires a successful update to the target record, and therefore all validations must be passed. For this reason, the example request updates some incidents field as well.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://schemas.hp.com/SM/7" xmlns:com="http://schemas.hp.com/SM/7/Common" xmlns:xm="http://www.w3.org/2005/05/xmlmime">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:UpdateIncidentRequest attachmentInfo="true" attachmentData="false">
         <ns:model>
            <ns:keys>
               <ns:IncidentID>IM10003</ns:IncidentID>
            </ns:keys>
            <ns:instance>
 
               <Category>incident</Category>
               <Area>hardware</Area>
               <Subarea>hardware failure</Subarea>
 
               <JournalUpdates>
                  <JournalUpdates>Drop attachment</JournalUpdates>
               </JournalUpdates>
 
               <ns:attachments>
                  <com:attachment href="cid:551bb5d00003a005805a1278" action="remove"/>
               </ns:attachments>
               
            </ns:instance>
         </ns:model>
      </ns:UpdateIncidentRequest>
   </soapenv:Body>
</soapenv:Envelope>

Attach a new file to an incident

Attaching a file also uses the attachments tag. The action attribute is set to add. The href attribute refers to the HTTP message of the request itself. Therefore, the href attribute received in the response may differ from that.

The file name for the attachment is set by the name attribute, and the content type by the type attribute. Therefore, the actual file name on the source system is not sent in the request.

An update request looks like the following:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://schemas.hp.com/SM/7" xmlns:com="http://schemas.hp.com/SM/7/Common" xmlns:xm="http://www.w3.org/2005/05/xmlmime">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:UpdateIncidentRequest attachmentInfo="true">
         <ns:model>
            <ns:keys>
               <ns:IncidentID>IM10003</ns:IncidentID>
            </ns:keys>
            <ns:instance>
 
               <Category>incident</Category>
               <Area>hardware</Area>
               <Subarea>hardware failure</Subarea>
 
               <JournalUpdates>
                  <JournalUpdates>Attach a file</JournalUpdates>
               </JournalUpdates>
 
               <ns:attachments>
                  <com:attachment href="cid:soapui.log" name="soapui.log" type="application/octet-stream" action="add"/>
               </ns:attachments>
               
            </ns:instance>
         </ns:model>
      </ns:UpdateIncidentRequest>
   </soapenv:Body>
</soapenv:Envelope>

 

Then, you receive the following attachment information in the response, which lists both the previously existing attachments and the new file attachment:

[..]
               <attachments>
                  <cmn:attachment href="cid:551bb5d00008c006805a1278" len="12842" name="cwc_labels_en.properties" type="application/octet-stream" upload.by="falcon" upload.date="04/01/15 03:09:36"/>
                  <cmn:attachment href="cid:551bb5d0000b8007805a1278" len="14606" name="cwc_labels_de.utf8" type="application/octet-stream" upload.by="falcon" upload.date="04/01/15 03:09:36"/>
                  <cmn:attachment href="cid:5668051d000e901f808612a0" len="21579" name="cimultirel.unl" type="application/octet-stream" upload.by="falcon" upload.date="12/09/15 03:40:29"/>
                  <cmn:attachment href="cid:566808350013605b809bd6c0" len="27944" name="cimultirel_v2.1.unl" type="application/octet-stream" upload.by="falcon" upload.date="12/09/15 03:53:41"/>
                  <cmn:attachment href="cid:591da42c0029800280680d00" len="79002" name="soapui.log" type="application/octet-stream" upload.by="falcon" upload.date="05/18/17 07:39:56"/>
               </attachments>
[..]

Send Help Center feedback