GSoD 2020 - OpenMRS REST API Documentation

Community Google Season of Docs
21

@ayesh I did look up the swagger documentation and all the wiki posts I could find and I have almost finished the forms section of the doc I will raise a PR once I have tested all the curl examples . but I need some help in defining the formfield (subresource), for which I could just get a resource here

apart from that I fiddled with the forms on the refApp and came up with this short definition for the form

  • The concept dictionary is a central part of OpenMRS. Concepts can commonly be thought of as questions and possible answers which are on forms (although they have other uses too).
  • so forms in OpenMRS can be thought of as data collecting means for various concepts in this dictionary , where corresponding to the questions these concepts pose answers are fetched via these forms.
  • forms in OpenMRS can be of many types for e.g. observation forms which help in capturing observations during an encounter e.t.c

@dkayiwa can you please help us refine these definitions a bit :smiley: thanks!!

22

Hi @saurabh it looks ok to me. Let get the view from @burke and @dkayiwa :smiley:

1 Like
23

Forms are data collection tools. Nearly all implementations of forms in OpenMRS represent encounter forms, where data are collected during a clinical encounter with a patient (sometimes retrospectively after the encounter is over). Forms can contain various fields including the date of collection, patient demographics, medications, allergies, and clinical observations. The majority of data collected are modeled as clinical observations.

2 Likes
24

Thanks alot @burke

@saurabh I would like to suggest you to send a PR with what you have also since burke replied you hve clear idea now :slightly_smiling_face:

25

@burke thank you for making things more clear now :grinning:, @ayesh I have opened PR I will make changes to that now and request a review again :slight_smile:

26

@ayesh I sent a pr

Fixed some broken links in several files.

Do you have a priority for resources that havenā€™t been put on the docs page? I can start to work on some.

Thanks!

27

@rainbow sure I reviewed it great work :slightly_smiling_face:

28

@ayesh For the undocumented resources, do you have a priority? Or I can start work on anyone?

29

So from the boundary we had last year on resources what left was the form resource. Since @saurabh picked it up. Maybe you can give it a try to add a new tab for Java samples in the docs and work on few samples?

30

@ayesh I will thanks. :slightly_smiling_face:

31

@ayesh while documenting the properties of the formFields subresource I coulnt figure out the exact descriptions of these attributes of formField and

I also couldnt figure out if we need to supply the parent formsā€™ UUID to the form as well as parent attribute of the formField subresource since in examples on the demo swagger documentation it had UUID for both the fields.

*form* | `String` | UUID of the parent form resource
*field* | `String` | UUID of the formField to be created for the parent form
*required* | `String` | if this field is required for the form to be submitted or not
*parent* | `String` | should UUID be duplicated here or form name should be here ??
*fieldNumber* | `integer` | description needed
*fieldPart* | `String` | description needed
*PageNumber* | `String` | description needed
*minOccurs* | `integer` | description needed
*maxOccurs* | `integer` | description needed
*sortWeight* | `boolean` | description needed

and the last 2 attributes of form resource as well

*name* | `String` | name of the form resource to be created
*description* | `String` | description of the form resource to be created
*version* | `String` | current version of the form resource to be created
*encouterType* | `String` | the specific encounter type where this form is designed to collect data
*published* | `boolean` | whether the form has been published or not
*formFields* | `Array[]: formFields` | list of formFields associated with this form
*xslt* | `String` | description needed
*template* | `String` | description needed

@dkayiwa ,@gcliff, @reagan ,@sharif please help me in getting some insight into these attributes and if anything I have inferred is wrong in the attributes I have described !! thanks :grinning:

and is there some resource maybe in the webServicesAPI repo where I can get some hints about resources and their properties .

32

@saurabh the formFiled is a subresource of FormResource and it references a form and a field in its implementation of the getGETModel(Representation rep) and getCREATEModel(Representation rep) swagger methods which help describe the attributes of the resource in the openmrs swagger spec ,so ideal it will have use the form and filed uuids and you can not have a formfield with out a form thats why .property("parent", new StringProperty().example("uuid")) appears.

1 Like
33

@ayesh for java request examples, are they generated by Swagger as well? How do I access them?

34

@ayesh never mind. I figured it out. Just use swagger.json. :slightly_smiling_face:

1 Like
35

@gcliff really thanks for replying what I can infer from your post is that formField has references to a field and a form (like the parent form which the formField is a part of), and I dint get clearly what exactly is a field inside a formField ??

I know that only 3 attributes are required for creating a formField via a POST call , but while documenting I have to document them all so can you help me with those attributes whose descripitions I m not really sure about :slightly_smiling_face: thanks !!

36

Hi @ayesh,

Do we have to write java code? The java code generated by Swagger doesnā€™t seem right. Hereā€™s Swagger code for Create Person:

import io.swagger.client.; import io.swagger.client.auth.; import io.swagger.client.model.*; import io.swagger.client.api.PersonApi;

import java.io.File; import java.util.*;

public class PersonApiExample {

public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    
    // Configure HTTP basic authorization: basic_auth
    HttpBasicAuth basic_auth = (HttpBasicAuth) defaultClient.getAuthentication("basic_auth");
    basic_auth.setUsername("YOUR USERNAME");
    basic_auth.setPassword("YOUR PASSWORD");

    PersonApi apiInstance = new PersonApi();
    PersonCreate resource = ; // PersonCreate | Resource to create
    try {
        apiInstance.createPerson(resource);
    } catch (ApiException e) {
        System.err.println("Exception when calling PersonApi#createPerson");
        e.printStackTrace();
    }
}

}

37

yes

2 Likes
38

@gcliff it helps :smiley:

and can you tell me a bit more about the field attribute inside the formfield subresource , thanks

39

@ayesh I was looking through the swagger documentation for the resources which are yet to be documented I found something like this which I didnā€™t understand

appointmentscheduling/appointmentstatushistory

what does a resource like this means? does it mean that appointmentscheduling is a resource and appointmentstatushistory is a subresource ? but then I didnt find appointmentscheduling as a seperate section in the swagger API docs it always came in conjunctions like this with various other terms , what does it really mean ?? :slightly_smiling_face: thanks !!

40

@ayesh I compiled about 80 resources from the swagger API docs :sweat_smile: , could you tell me which one should I pick up to document next up to Forms ,

I will update the form attribute definitions as I get clear about them with the help of community and request for your review again when I complete it !!