Upload module to OpenMRS using REST

Week 2 [ June 07,2017 — June 13,2017]

I have completed week 01. But still I have so much of problems with OpenMRS :-(. I am new to the OpenMRS environment and want to study so much to find the solutions for some problems. I faced a lot of problems while developing Manage Modules Open Web App.

I have completed most parts of the Manage Module Section during Week 01 of Coding period. I couldn’t work so much for my project this week because of my semester examinations. Anyway, I have updated my works through IRC and talk thread also.

I allocated a short time to complete Search and Install Module part during this week 02. But I struggle to manage the Upload module part to complete. Because It hasn’t any proper documentations for REST usage. So I want to analyze the code base to implement the functionalities.

There are no more documentations for file upload through Module REST API. So I just asked my mentor about the problem. He advised me to check the code base and suggested to use Module REST API. So then I spent some time to analyze the code base of REST module, and finally found the base class ModuleResource1_8 for Module REST API. It contains all necessary methods for the Module management including File upload also.

@Resource parameter expresses the REST API name like “/module”. So I can understand, I want to use module REST API to achieve this file upload.
File upload function in ModuleResource1_8 class requires Multi-part file to continue the upload function.

After the understanding of REST API, I started to working with Angular to implement file upload. But I have to expend so of time to find some solutions for problems. I have mentioned the problems which ate my a lot of working hours,

  1. Form upload type should be multi-part type. So I created the header with ‘Content-Type’: ‘multipart/form-data’ . According to this content-type definition in the header, the server replied as boundary missed . So I searched about this problem and find out the solution as mention boundary=<boundary_code> in your header. So finally I created the header with ‘Content-Type’: ‘multipart/form-data;boundary=gc0p4Jq0M2YtjU534c0p’ . Again I received the response as [Required MultipartFile parameter ‘file’ is not present] .
  2. After some search about the problem, I got some points about the browser submits. It says me, If we define as ‘Content-Type’: undefined , then the browser will automatically replace the support content-type to the header. So I just changed the header and try to upload the module.
    Now I got the response as Could not write to JSON . Initially, I didn’t get this error explanation. but after some alterations, I understood that file had been uploaded but Server could not write the response to the client. Server doesn’t reply with the usual format(JSON). Server failed to write the response in some different form(XML).
  3. So I mentioned the accept type in header to accept all the type of response from headers. Finally I have modified my header as
    headers: {‘Content-Type’: undefined , ‘Accept’: ‘text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8’}
  4. Now I can get the response from the server and able to upload the module to the server, But the response was in XML based type. So I want to convert the response to JSON format to access it easily.

Solved File Upload Workflow using REST API

Architecture of the File Upload via module management through REST API will be like follows,

File upload architecture using REST API

According to above diagram Work flows of the Module Uploading are,

  1. Submit the uploaded file as multipart file format using POST request to the server. Header should contain accept part to receive the responses.
  2. Server will catch the uploaded file and load to the server. After the process it will response to the Client about the status
  3. If the response contains Success/Errors, then It will be XML format. So our request should contain Accept header to accept the XML format as the response. If we didn’t include those Accept in the POST request, then we want to face some exceptions like Could not write to JSON.
  4. Finally, I want to convert the XML to JSON using some internal libraries to display the response data to the user. (Other most REST responses are JSON based replies)

Module Uploading Development

So according to the requirments, I have designed the upload form with “Multipart/Form-data” type.

<form name="myForm" enctype="multipart/form-data">
<table class="display" style="border: 0px; widtd: 80%;">
<tr style="border: 0px;">
<th style="border: 0px;">
<input type="file" ngf-select ng-model="myFile" file-model="myFile" name="file" file="file"
accept=".omod" ngf-max-size="10MB" required
ngf-model-invalid="errorFile" style="border: 0px;">
<th ng-show="myFile" style="border: 0px;">
<button ng-click="myFile = null" ng-show="myFile">Remove</button>

Then after, I used Angular to receive the file from Form and submit to the server. Here I have used below code at the initial stage of the uploading.

Here I have included Accept in the Header. So our request is ready to accept all these formats as the response. I have mentioned Content-type as “undefined”. Because when I submit the file, It will submit as multipart/form data to the Angular Service. then after our browser will define the content-type to the file if we define as “undefined” in code.

myApp.service('fileUpload', ['$http', function ($http) {
this.uploadFileToUrl = function(file, uploadUrl){
var fd = new FormData();
fd.append('file', file);
$http.post(uploadUrl, fd, {
transformRequest: angular.identity,
headers: {
'Content-Type': undefined ,
'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8'}


After the submission, I want to convert the server response from XML to JSON format. For this purpose, I have used X2JS library.

success(function (data, status, headers, config) {
var x2js = new X2JS();
var JSResponse = x2js.xml_str2json(data);

var moduleName = JSResponse["org.openmrs.module.Module"].name;

Final Development of the Module

I have completed following part during Week 02,

  1. File Upload to OpenMRS and Error tracking of the file upload
  2. Search and Install the Module to OpenMRS and error tracking of file installation.

Check my GitHub repository for the updated development work ,

I think, I couldn’t allocate more time to my project in the following week also because of examinations. Anyway I am going to start my work section 2 — System Information Open Web App development.

Kailayapathy Suthagar

Written by

Software Engineer @ Sysco Labs, Google Summer of Code Intern @ OpenMRS

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade