We are currently working on the forum. For the short-term, all forum content will be in read-only format. We apologize for the interruption and look forward to collaborating with you shortly. All the best in your research!

Has anyone been able to get OC Participate (i.e., OC + Enketo or ODK) working?



  • toskriptoskrip Posts: 279 ✭✭✭
    Hallo Krikor,

    not sure if this is a bug, in EnketoAPI.java when formulating URL to communicate with enketo you are using "/api/v1" convention to versionate the REST interfaces, but as far as I can see (and enketo documentation says the same) it should be "/api_v1" instead.

  • toskriptoskrip Posts: 279 ✭✭✭
    Ok guys,

    I was able to reproduce the workflow that Krikor suggested. I got to the last point that is the submission of data back to OC and there I currently stopped (I will explain why later). I have to say that I am happy with the API (considering that it is still very experimental). And I can imagine building my own participate portal that will provide necessary security and authentication for our use (which will be limited in clinic with our own input devices - so to speak now contact our sms required).

    After disabling the authorisation to use the Participate (these mayProceed methods that Krikor pointed out). It is possible to setup the enketo URL as portalURL and define the participateURL as a convention studyIdentifier.portalURL. Afterwards it is possible to edit the event definition details and enable participate form collection for certain CRFs. Also in CRF management it is possible to preview the CRF over enketo (in EnketoAPI.java the api call have to by fixed as I described in above post).

    So this seems to work fine enketo can obtain the CRF definition from OC via the OpenRosa API.

    The next step is possibility to show CRF for selected subject and scheduled event. This is normally done via ParticipatePortal so OC does not have UI element that will allow you to show patient CRF. You need to have your own application, e.g. your own participate portal, this app can use OC rest API to obtain the enketo form URL and redirect there to show the form.

    the API you have to use is:

    you see the parameters are study OID and subject OID
    this will give you ODM XML file with reference to enketo form URL... the enketo form URL looks like this:

    your application (custom participate portal) needs to redirect to this URL, and there you go, you will have your form rendered via enketo with submit button.

    And this is where I hit, the submission from the enketo form is not working. Now I am talking about the Model 2 not the anonymous submission. I think the submission OpenRosa API of OC in not ready yet. The service expect to receive query parameter context, that is null and which should be later use to lookup for HashMap storing OIDs of ODM entities where the data from the form should be imported.

    That is it for now... I am looking forward to see how this api is going to evolve. So far it looks very promising.

    Krikor, thank you for technical details, without this info my small experiment will take my much more time :)


  • sdibonasdibona Posts: 10
    Hello again,

    I wanted to provide some additional information for working with enketo-express. Here are some useful API commands that can be run from the command line using curl (assuming you are running the enketo-express-oc fork of enketo-express).

    The examples use "http://sdibona.local:8006/" as the enketo server and "http://sdibona.local:8081/OpenClinica-web/" as the OpenClinica instance.
    "YYYY" represents the the value for "account manager api key" defined in enketo's config.json and is required for managing accounts on enketo.
    "XXXXXXXXXXXXXXXXXXXX" represents the API key that gets associated with each OpenClinica account created and is required for requesting form URLs.

    // List accounts (specific to enketo-express-oc)
    curl --user YYYY: http://sdibona.local:8006/accounts/api/v1/list

    // Add an account (specific to enketo-express-oc)
    curl --user YYYY: -d "server_url=http://sdibona.local:8081/OpenClinica-web/rest2/openrosa/S_ABC123&api_key=XXXXXXXXXXXXXXXXXXXX" http://sdibona.local:8006/accounts/api/v1/account

    // Delete account (specific to enketo-express-oc)
    curl -X DELETE --user YYYY: -d "server_url=http://sdibona.local:8081/OpenClinica-web/rest2/openrosa/S_ABC123" http://sdibona.local:8006/accounts/api/v1/account

    //Preview form
    curl --user XXXXXXXXXXXXXXXXXXXX: -d "server_url=http://sdibona.local:8081/OpenClinica-web/rest2/openrosa/S_ABC123&form_id=F_FORMNAME" http://sdibona.local:8006/api/v1/survey/preview

    //Get form URL
    curl --user XXXXXXXXXXXXXXXXXXX: -d "server_url=http://sdibona.local:8081/OpenClinica-web/rest2/openrosa/S_ABC123&form_id=F_FORMNAME" http://sdibona.local:8006/api/v1/survey

    Regarding config.json, the "query parameter to pass to submission" field must be set to "ecid" to work with OpenClinica. This parameter is used to pass context information back and forth between Enketo and OpenClinica.

    Every study that is to be connected to enketo-express-oc needs to have a study specific account with an API key created on the enketo server. Normally OC Participate would do this, but without it these curl commands can be used.

    Please let me know if you have any questions.

    -Steve DiBona
  • toskriptoskrip Posts: 279 ✭✭✭
    Hi Steve,

    thanks for your post, indeed I have missed the ecid query parameter configuration in enketo.

    But I still have troubles with data submission. I do not understand how should the enketo submit request create a new userAccount in OC. Without the user account it is not possible to submit however the createUserAccount method is commented within PformSubmissionService (I am working with the latest master).

    Was this replaces with different API dedicated from user account creation?


  • toskriptoskrip Posts: 279 ✭✭✭
    Actually I was searching for it in jira (had a feeling that I have read something about the change in github pull request) and indeed there is a new API:


    I suppose participate is using this prior the data submission to create participate specific user account (concating studyOID + "." + studySubjectOID) necessary for data submission.

  • toskriptoskrip Posts: 279 ✭✭✭
    Ok, so finally I have got the data submission to OpenClinica working. But I still need a little help with one issue. After the successful submission OC tries to notify the participate with an email. We have a little bit different workflow for data collection and do not need this step so I commented the NotificationActionProcessor run method body.

    But for some reason the enketo does not receive or cannot pass the confirmation about successful submission from OC. And that is why it shows error message that some error occured (which is not completely true because the data have been stored). Log file of OC also does not indicate any problem (no exception was triggered).

    Any idea why this is happening?

  • ccollinsccollins Posts: 383 admin
    Hi Tomas,
    Great to hear you have something working! The first problem is odd; OC shouldn't trigger an email on every submission unless there's a rule set up with a NotificationAction to do so.

    Regarding the second issue, enketo needs to know where to go after submission. I don't have much knowledge of that area, @sdibona any insights?

    FYI we're working on overhauling the API documentation and getting it up-to-date. It shouldn't be too long :smile: For now, looking through Jira is the best source for the newer calls.
  • toskriptoskrip Posts: 279 ✭✭✭
    Thanks Cal, I will look into it. BTW if you are looking for a feedback regarding usability of some of these new webAPI of OC, I have one tiny observation.

    It would be nice if this service:

    will accept both StudySubject OID as well as StudySubject ID, the same way as current RESTfull URLs do.


  • toskriptoskrip Posts: 279 ✭✭✭
    Just a short update. The latest commits to OC git master have resolved the issues with data submission (wrong http response code). So now I have an actual working prototype (no more errors).

    The other thing (redirect after submit) from what I have read it is not implemented in enketo yet (please correct me if I am wrong in this), however it would be very very useful feature to have.


  • kristiakkristiak Posts: 1,340 ✭✭✭
    Great Tomas, when do you think it will be so far that we amateurs can start testing?
    Best regards
Sign In or Register to comment.