Welcome Serena Central users! CLICK HERE
The migration of the Serena Central community is currently underway. Be sure to read THIS MESSAGE to get your new login set up to access your account.
Highlighted
Micro Focus Expert
Micro Focus Expert
895 views

(SM) Support Tip: Attachment operations using Service Manager’s REST and Web service API

Service Manager supports all typical attachment operations (like get attachment information, get (single) attachment, delete (single) attachment, insert attachment) using web service (SOAP, REST, see Service Manager integration methods and tools > Web Services).
This document covers the services Service Manager publishes – so it explains requests of an external application being sent to Service Manager, and the responses to expect.


 
Handling attachment with REST


When an external system sends REST request, then you can first look at the service document:

 http://<server>:<port>/SM/9/rest


Here information of REST service of all available objects can be found in the document retrieved. The table below contains the part returned for Incident.

Incident
Resource type             Supported Methods             URI
Resource Collection    GET/POST                             http://localhost:13080/SM/9/rest/incidents
Single Resource           GET/POST/PUT                    http://localhost:13080/SM/9/rest/incidents/{number}
Resource Attachment Collection    

                                      GET/POST/DELETE             http://localhost:13080/SM/9/rest/incidents/{number}/attachments
Resource Single Attachment 

  •                                       GET/PUT/DELETE               http://localhost:13080/SM/9/rest/incidents/{number}/attachments/{id}

     
    The target object of the request depends on the URI, the operation executed depends on the HTTP method of the request. The table lists the valid methods.


Examples:

  • A GET request on the Resource Attachment Collection URI returns a JSON document with all the attachments ids.
  • A GET request on the Resource Single Attachment URI will download the attached file identified by id.
  • A DELETE request on the Resource Single Attachment URI will delete the file attachment identified by id.

 

Tip:    GET HTTP message can be input into address bar of the browser which is comfortable for testing. In order that Service Manager accepts these requests, activate restaccessviabrowser:1 parameter for the servlet.
For REST requests using other HTTP method like GET, testing in browser address bar is not possible. Tools for web services testing or browser plugins available can be used for testing.

Retrieve attachment information

Execute a GET request on the Resource Attachment Collection of an incident identified by number.

http://localhost:13080/SM/9/rest/incidents/IM10003/attachments


The response received is a JSON document and looks similar to this:

{
  "@count": 29,
  "@start": 1,
  "@totalcount": 29,
  "Messages": [
    "1: undefined",
    "0: undefined",
    "vars.$smtestmessages: [C++ object Datum] - ",
    "vars.$smtestresult: [C++ object Datum] - {NULL, NULL, NULL}"
  ],
  "ResourceName": "attachment",
  "ReturnCode": 0,
  "content": [
    {"attachment": {
      "href": "cid:58ac7b3200242211802b29a8",
      "len": 23146,
      "name": "error.log",
      "type": "multipart/form-data; boundary=\"----=_Part_32_596452009.1487698738148\"",
      "xmime:contentType": "multipart/form-data; boundary=\"----=_Part_32_596452009.1487698738148\""
}},


    [ .. ]

}

In this example incident IM10003 has 29 attachments, and for each the JSON document contains information like attachment id (href), length in bytes (len), file name (name), file type (type), and xmime type (xmime:contentType).

Download an attached file

With the attachment information retrieved, we know the attachment id (href attribute) and send a GET request to download the attachment file.

http://localhost:13080/SM/9/rest/incidents/IM10001/attachments/58ac7b3200242211802b29a8


If tested using browser, it should show a file being downloaded.

Delete an attachment


When sending the same URI with HTTP method DELETE instead of GET, the attachment is deleted.
This is not possible by browser address bar, so either a tool or plugin is required, or implementation like HTML page with JavaScript implementation.
This is a demonstration HTML page to demonstrate deleting an attachment by REST request.
Note: Browser may now allow access because security restrictions. Refer to Cross-Origin Resource Sharing.

<!DOCTYPE html>
<html>

<head>
  <script language="javascript">

function sendrequest(method, url, contenttype, user, password, sync, request, callback)
{

 // Create a XMLHttpRequest object
  var ajax = null;
  if(window.XMLHttpRequest){          //Google Chrome, Mozilla Firefox, Opera, Safari, IE 10
    ajax = new XMLHttpRequest();
  }
  else
  {
       return;
  }

  // Add data to ajax object
  ajax.open( method, url, sync, user, password );

  if (contenttype) ajax.setRequestHeader("Content-Type", contenttype);

  if (!sync)
  {
      // Define how response will be processed
      ajax.onreadystatechange = function()
      {
         var result = {};

         switch (this.readyState)
     {
           case 0: result.status = "ReadyState: " + this.readyState; break;
           case 1: result.status = "ReadyState: " + this.readyState; break;
           case 2: result.status = "ReadyState: " + this.readyState; break;
           case 3: result.status = "ReadyState: " + this.readyState; break;
           case 4:
            {
               var result = {};
               result.status = ajax.status;
               result.response = ajax.responseText;

               if (callback) callback(result);

               break;
            }
         }

         updatePage(result.status, result.response);

         return result;
      }
  }

  // send the request
  if (request)  ajax.send( request );
  else ajax.send();

  if (sync)
  {
      var result = {};
      result.status = ajax.status;
      result.response = ajax.responseText;

      updatePage(result.status, result.response);
      if (callback) callback(result);
  }
}

function updatePage(status, response)
{
   document.getElementById("status").innerHTML=status;
   document.getElementById("response").value=response;
}

</script>
</head>

<body>

  <h1>Test SM RestfulAPI</h1>



  Request: <textarea id="request" width="80" height="60"></textarea>

  <p></p>

  Status: <p id="status"></p>

  Response: <textarea id="response" width="80" height="60"></textarea>



  <script language="javascript">



// Defaults

    var method = "GET"

    var request = null;

    var contenttype = null;

    var sync = false;



// Credentials

    var user = "falcon";

    var password = "";



// TEST

    var method = "DELETE";

    var URL = "http://localhost:13080/SM/9/rest/incidents/IM10001/attachments/58ac7b3200242211802b29a8";



    sendrequest(method, URL, contenttype, user, password, sync, request);



  </script>

</body>

</html>

 

Attachments with SM web services


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 extaccess dbdict. They can be displayed in browser using for URL like this:

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

If the sc62server URL is used, the attachment format is MIME, when SM/7 URL is used, the attachment format is MTOM.
Testing web services is with tools available much easier. To avoid unnecessary complexity, used SoapUI tool for the example below.
The request and response tag name includes the operation name (i.e. Retrieve or Update), and the target object name (i.e. Incident) in name space http://schemas.hp.com/SM/7:
Here an example for a request tag (the prefix ns refers to the namespace definition in <soapenv> tag):

<ns:RetrieveIncidentRequest>
and an example for a response tag:
<RetrieveIncidentResponse>
The operation is also reflected in the HTTP header property SOAPAction. For example:
SOAPAction: "Update"
If request tag and SOAPAction header do not match, the response will show 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 attachmentInfo attribute in 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>


 
Response will contain the complete Incident data (shortened in 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://server.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 the href attribute contains the content id for each attachment.
When setting the attribute attachmentData attribute in request tag to true, the response will contain all file attachments. If attachmentData is set to true, the attachment information is always included in the response, independently of attachmentInfo attribute.
 

Retrieve a single attachment

In attachments tag specify the attachment using the href attribute and set the attribute action to get. The request tag must contain attachmentData attribute 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 like this:

SM attachment_SOAPUI1.PNG

 

Looking at the raw message shows 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 require a successful update to the target record, and therefore all validations must be passed. For this reason, the example request update 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 uses as well the attachments tag. The action attribute is set to add. The href refers to the HTTP message of the request itself. Therefore the href attribute received in the response may vary from that.
The file name in set for the attachment is set using the name attribute as well as the content type by type attribute. So the actual file name on the source system is not send in the request.
The update request looks like that:

<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>



This is then the attachment information as we receive in the response with the previously existing and the new file attachment:

SM attachment_SOAPUI2.PNG

 

 

 

 

 

 

 

 

 

[..]
               <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> [..]


 

Labels (1)
0 Likes
1 Reply
Krithik Contributor.
Contributor.

Re: (SM) Support Tip: Attachment operations using Service Manager’s REST and Web service API

Hi All,

I could able to create the incident successfully through SOAP UI but not able to add the attachments successfully(Through create/update incident methods in webservice). Can any one share me the sample SOAP file on how to add the attachments to the incidents?. Your help would be greatly appreciated.

Regards,

Krithik 

 

0 Likes
The opinions expressed above are the personal opinions of the authors, not of Micro Focus. By using this site, you accept the Terms of Use and Rules of Participation. Certain versions of content ("Material") accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.