How to send attachments via the Remedy REST API

Version 36
    Share This:

    This document contains official content from the BMC Software Knowledge Base. It is automatically updated when the knowledge article is modified.


    PRODUCT:

    Remedy AR System Server


    COMPONENT:

    AR System Mid Tier


    APPLIES TO:

    REST API AR System v9.1



    DETAILS:

    USING POSTMAN (Important: POSTMAN must be Version 7.6.0 or newer to do this)

    To send attachments using Postman either creating an entry (POST) or updating an existing one (PUT) you must follow this instructions:

    1. Set your url and method, in this case an attachment is going to be uploaded to an existing incident 

    User-added image

    2. Set your authentication header as in any other call, you can use Postman variables like in this case {{token}} replaces the full token provided by AR Server

    User-added image

    3.  Create a file with the JSON content that you want to send over the body, in this case a file named data_entry.txt was created with the following content. 

    {
            "values": {
                    "z1D_Details": "Affected Hosts Updated by Tenable Automation. See attachment",
                    "z1D_WorklogDetails": "The IPs affected have changed",
                    "z1D Action": "MODIFY",
                    "z1D_View_Access": "Internal",
                    "z1D_Secure_Log": "Yes",
                    "z1D_Activity_Type": "Incident Task/Action",
                    "Detailed Decription": "Updated description",
                    "z2AF_Act_Attachment_1":"sample.xml"
            }
    }

    Make sure the attachment field (in this case z2AF_Act_Attachment_1) has a value with the name of the file you want to attach

    4. In POSTMAN, change the body to use Form-Data option, this is needed because the request will consist of 2 parts, JSON, which contains the request and Octet-stream which will contain the binary content of the file. Click the 3 dots at the end of the table below and make sure Content-Type is checked.

    User-added image        User-added image

    5. You will need two keys (one for the JSON content and one for the attachment) for both keys you must change the type from text to file 

    User-added image
    6. Open the file where you save your JSON content for the first key (data_entry.txt in this example) and set the content type as application/json the key name can be whatever you want. for the second key select the attachment you want to upload, set the content type as application/octet-stream and the structure of the name of the key should be attach-fieldname in this case attach-z2AF_Act_Attachment_1, the field it's very important always use attach- and then the exact name of the attachment field otherwise your attachment won't upload. This is how the section will look like.

    User-added image

    7. Submit the request.

    JAVA EXAMPLE
    If you are looking for a Java example, use the attached file - RESTAttachmentExample.java. This example assumes the use of a form called frmTest which has an attachment pool with one attachment field.

    The other RESTAttachmentWorkInfo.zip gives an example of creating an entry with an attachment to the WOI:WorkInfo form of an existing WorkOrder. . The zip file contains the .java file and a readme file that provides guidance on what needs to be updated in the .java file along with instructions on how to execute it.

    CURL EXAMPLE (Note Token was trunkated for explanation purposes)

    We created a sample form ZtestRestAttach


    curl -v -XPOST -F "entry=@/directory/entry_data;type=application/json" -F "attach-Attachment__c=@/directory/file.txt;type=application/octet-stream" -H 'Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.eyJz...I' -H 'Content-Type: multipart/form-data' 'http://servername:8008/api/arsys/v1/entry/ztestRestAttach'

    This example would need 2 files, the path to this files is added after the @ signs
    entry_data with the following content
     {"values":{"Short Description__c":"REST TEST","Submitter__c":"REST TEST","Status__c":"New","Attachment__c":"file.txt"}}

    and file.txt (any content) 

    There are 2 parts that should match for any attachment 
    in the entry_data make sure that Attachment__c matches the attachment Name "attach_Attachment__c"

    in that way each attachment would be saved with the proper filename and in the proper attachment location.

    As there are 2 filenames (the actual filename and the filename specified in the Json data) the one that would be saved is the one on the json structure.

    NodeJS EXAMPLE
    The attachment, TextAndBinaryWorkInfo_And_fiddler.zip contains two NodeJS examples:  attachmentBinaryWorkInfo.js and attachmentTextWorkinfo.js

    Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine. In order to use the attached js examples, Node.js needs to be installed and configured in test environment.   Downloads and documentation can be found here: https://nodejs.org

    The node JS example will handle 2 types of attachments, text and images. Text attachments sent in binary format look just like the text on the file

    File screenshot
     text used in example

    When these characters are inspected in the http traffic, they look like this

    HTTP request traffic 
    characters in binary inspected in http request

    Note that base64 encoding is not required while transferring this file.  The same thing would happen for other types of files.  A PNG would look like this when transferred

    User-added image

    The extra headers like Content-Disposition, Content-Type and Content-Transfer-Encoding are required.

    Fiddler capture/compose
    Fiddler is able to replay and edit HTTP request with certain limitations. It cannot change the binary file contents, that should be done by a program like java or node.   However, if the interest is on sending text files for testing, Fiddler should meet the need

    The attachment, Text AndBinaryWorkInfo_And_fiddler.zip contains a Fiddler capture called attachments_to_WOIWorkOrder.saz.  This Fiddler capture contains two requests.  The first one marked in red is in binary; it is there for inspection purposes only and modifying it in Fiddler is discouraged.   The second request includes a simple text file and it can be edited.

    Here are instructions on how to edit and execute the request in Fiddler.
    Note:  it is assumed that the Fiddler tool is installed.  If not, it can be downloaded from https://www.telerik.com/download/fiddler.

      1.  Open the attachments_to_WOIWorkOrder.saz in Fiddler.  
    2.  Drag the second request to the "Composer" tab   
    3.  Change the following as it relates to your environment/request: URL, Host, AR-JWT token  
     
    The syntax of the request body is very sensitive.  Be very cautious when modifying.   The text in the marked line (pictured below) may be changed to see how various characters are transferred.  
     
    4.  Click the Execute button to submit the request 
      
    fiddler composer

    Here is the raw text of the request:against a form called frmTest     
      Authorization: AR-JWT …
    Content-Type: multipart/form-data; boundary=123456
    User-Agent: Java/1.8.0_77
    Host: clm-pun-030535.bmc.com:8008
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Connection: keep-alive
    Content-Length: 543
     
    --123456
    Content-Disposition: form-data; name="entry"
    Content-Type: application/json; charset=UTF-8
    Content-Transfer-Encoding: 8bit
     
    {"values":{"Short Description__c":"REST TEST","Submitter__c":"REST TEST","Status__c":"New","Attachment__c":"file.txt"}}
    --123456
    Content-Disposition: form-data; name="attach-Attachment__c"; filename="file.txt"
    Content-Type: application/octet-stream
    Content-Transfer-Encoding: binary
     
    now is the time for all good men to come to the aid of their country
    --123456--
     
      

     


    Article Number:

    000131309


    Article Type:

    Product/Service Description



      Looking for additional information?    Search BMC Support  or  Browse Knowledge Articles