Posting report to records API

Technical Support Development
1

What is the correct form code referred to in the docs?

_meta.form	The form code.

I am met with the Form not found: FF_TASK_TRIGGER when trying to push the following content to the api/v2/records api:

{
  "nurse": "Sam",
  "week": 23,
  "year": 2015,
  "visit": "ANC",
  "_meta": {
    "form": "ff_task_trigger"
  }
}

I’ve checked the form in the db and the api/v1/forms api to make sure I’m using the correct reference:

{
  "_id": "form:ff_task_trigger",
  "_rev": "29-cc4640add12ef189bc66cb284d4424fc",
  "type": "form",
  "internalId": "ff_task_trigger",
  "xmlVersion": {
    "time": 1728030649647,
    "sha256": "3b86b78776726516a815dfbc18c4361a6a9e12850a7350cf627a5a9cdba08458"
  },
...

[
    ...
    "death_report.xml",
    "ff_task_trigger.xml",
    "intermediary.xml"
    ...
]
2

Hello,

It looks like ff_task_trigger is an XML form?

the records api can only be used with JSON forms

So something like this in forms in app_settings:

"FF_TASK_TRIGGER": {
  "meta": {
    "code": "ff_task_trigger",
  },
  "fields": { },
  "public_form": true
}
1 Like
3

Thank you @twier ! For interest sake, have you ever managed to kick off a task by submitting one of these JSON forms?

4

Yes, tasks can be created from JSON forms in the same way as for XML forms.

5

Fantastic. How would we link the pushed json form content to a hierarchy contact?

Speaking under correction, I believe it’s the patient_id that normally links an xlsx app form to a specific contact.

We’ve tried including the patient_id in the object root and in the fields, but it did not have the intended effect.

Form config:

{
    "YYYZ": {
      "meta": {
        "code": "YYYZ"
      },
      "fields": { 
        "patient_id": {
            "labels": {
                "short": {
                    "translation_key": "form.flag.patient_id.short"
                },
                "tiny": "pid"
            },
            "position": 0,
            "type": "string",
            "length": [
            5,
            13
            ],
            "required": true
        }
      },
      "public_form": true
    }
}

Input:

{
  "patient_id": "7ed34748-33df-45a1-a294-e0d852a415f9",
  "form": "YYYZ",
  "nurse": "Sam",
  "week": 23,
  "year": 2015,
  "visit": "ANC",
  "fields": {
    "patient_id": "7ed34748-33df-45a1-a294-e0d852a415f9"
  },
  "_meta": {
    "form": "YYYZ",
    "reported_date": 1725001661000
  }
}

Output:

{
  "_id": "f999aad6-ca71-4908-a024-84ec97738758",
  "_rev": "1-fa424342e0013267174fdca0c649265b",
  "type": "data_record",
  "form": "YYYZ",
  "errors": [],
  "tasks": [],
  "fields": {
    "patient_id": "7ed34748-33df-45a1-a294-e0d852a415f9"
  },
  "reported_date": 1725001661000,
  "sms_message": {
    "form": "YYYZ",
    "reported_date": 1725001661000
  }
}

Expected output:

{
  "_id": "051e7d21-a148-403b-bf60-16dd297ef64b",
  "_rev": "2-592dd7539549315372f282367278896a",
  "form": "YYYZ",
  "type": "data_record",
  "reported_date": 1725001661000,
  "contact": {
    "_id": "7ed34748-33df-45a1-a294-e0d852a415f9",
    "parent": {
      "_id": "8d761a66-e0ee-40b5-a8b1-352da70bfe4c",
      "parent": {
        "_id": "89a4b5d2-5cbe-4f5c-8e8c-961c7af38d8d",
        "parent": {
          "_id": "f91ed047-9a1f-4863-b365-88ec0ab2bce1"
        }
      }
    }
  },
....

For context, we’re stress-testing our purge script, and we’re also evaluating the performance impact of scheduling many targets at the same time for a single CHW.

6

Hi @Anro

The patient_id should be the patient’s shortcode, as in the patient_id field in the contact document, not the uuid of the contact document. We have workarounds in case this happens, but for SMS forms I believe you need to use the actual patient_id.

This patient_id field is unique and is populated by a sentinel transition called generate_shortcode_on_contacts.

Can you please try using the shortcode instead of the uuid?

Also, from your expected output, it seems that you want the contact property to be populated.
This field does not represent the patient, this field represents the submitter and, for sms forms, is populated by the update_clinics sentinel transition based on the sender phone number.

7

Hi @diana,

Thank you for taking the time to explain.

I don’t believe we generate short codes, at least not to my knowledge (see '‘hhm’ below). We don’t really use the SMS driven forms feature. What problem could we run into if we continue down this path? Does the generate_shortcode_on_contacts run retroactively should we enable it now?

it seems that you want the contact property to be populated.
This field does not represent the patient, this field represents the submitter

Thank you for clarifying. It also seems like we would need a rc_code on the contact if we’re to match on the facility_reference. We don’t generate rc_codes either. There’s mention of matching on a phone number as a fallback, but we tried the “from” property without success. Is there another property we should consider?

Patient (hhm) db doc:

{
  "_id": "c94df39f-ec4f-4b87-bf87-3256a91d2cd2",
  "_rev": "1-f02c13a0bb6a9380799f3f5b5d78a531",
  "type": "contact",
  "first_name": "Member 1",
  "middle_name": "",
  "last_name": "Test",
  "maiden_name": "",
  "name": "Member 1 Test",
  "resident": "yes",
  "dpersist_excl_1_": {
    "phone_raw": "",
    "phone_raw_alt": ""
  },
  "obtained_personal_details": "no",
  "pmi_number": "",
  "sex": "other",
  "date_of_birth": "2000-02-01",
  "dob_method": "dob_confirmed",
  "dpersist_excl_2_": {
    "weeks": "1294",
    "months": "297",
    "years": "24",
    "age_unit": "Years",
    "age": "24"
  },
  "when_member": "at_birth",
  "contact_type": "hhm",
  "meta": {
    "created_by": "anro-chw-8309",
    "created_by_person_uuid": "7ed34748-33df-45a1-a294-e0d852a415f9",
    "created_by_place_uuid": "8d761a66-e0ee-40b5-a8b1-352da70bfe4c"
  },
  "form_start": "2024-11-21T13:52:08.760+02:00",
  "reported_date": 1732189958038,
  "parent": {
    "_id": "03bd34f4-f100-4540-9bbf-61c91d6534ca",
    "parent": {
      "_id": "9b064c77-d707-4582-a68c-a7babab5cf25",
      "parent": {
        "_id": "8d761a66-e0ee-40b5-a8b1-352da70bfe4c",
        "parent": {
          "_id": "89a4b5d2-5cbe-4f5c-8e8c-961c7af38d8d",
          "parent": {
            "_id": "f91ed047-9a1f-4863-b365-88ec0ab2bce1"
          }
        }
      }
    }
  },
  "form_version": {
    "time": 1732188691388,
    "sha256": "9f54ee9d4c64e6f83c71e927bf834e300fc31024f841aa6400ebb47ec0650257"
  }
}

We may have experienced the “workaround” you mentioned after adding the “patient_id” to our posts, and outputting the purge results in the sentinel logs (the large list of grouped reports).
Notice the “unallocated reports” at the bottom prior to adding the patient_id property.

2024-11-29 11:40:00 2024-11-29T09:40:00.920 INFO: Running purging 
2024-11-29 11:40:00 2024-11-29T09:40:00.954 INFO: Purging: Starting contacts batch: key "", doc id "", batch size 1000 
2024-11-29 11:40:01 2024-11-29T09:40:01.011 INFO: Found 1118 records 
2024-11-29 11:40:01 Reports to purge:  [
2024-11-29 11:40:01   '001330ff-e203-4026-9461-169fbb4414b2',
2024-11-29 11:40:01   '0047c865-b8c1-446e-812c-acd18c1927e2',
2024-11-29 11:40:01   '00b2af72-6cb5-4169-8341-2f7fb481bd7e',
2024-11-29 11:40:01   '00e06797-5c5e-43e4-80c2-311790677834',
2024-11-29 11:40:01   '01013af9-a8ef-497c-865b-9535a139adb8',
2024-11-29 11:40:01   '018d5440-cee0-4ea8-9745-5d445b946c87',
2024-11-29 11:40:01   '01c4db45-c588-4f43-b0da-a88ec94f4c04',
2024-11-29 11:40:01   '01ca3686-e35c-4048-926b-53a37c65e18c',
2024-11-29 11:40:01   '01d7f7e3-4fdc-40f5-9302-45f9f95c51b7',
2024-11-29 11:40:01   '0220b0d3-c343-4422-bd0f-b066231623be',
2024-11-29 11:40:01   '024c65e3-73ba-4888-afaf-1b7d524432ac',
2024-11-29 11:40:01   '029337d1-8330-48c0-884f-74a08d449cca',
2024-11-29 11:40:01   '02fbbc59-785c-4822-8140-900463bb5deb',
2024-11-29 11:40:01   '030f25f7-dc22-429c-bbd9-70b01cc91826',
2024-11-29 11:40:01   '033fd85a-ea1c-43ac-8a36-794e13b2c9e7',
2024-11-29 11:40:01   '03632190-53e4-4eff-9f8d-a7d63debaf5c',
2024-11-29 11:40:01   '03a527c0-542e-4c8d-bcf5-5dd5401eb900',
2024-11-29 11:40:01   '04dace28-cc48-4f1d-bfa7-f2161b8a030c',
2024-11-29 11:40:01   '059c182a-f668-4285-82e1-50341cf3b4e4',
2024-11-29 11:40:01   '05c3f7d1-807e-4446-8b89-eb9a5b1f8b6d',
2024-11-29 11:40:01   '05d499a5-7cf5-4482-9103-721f7adcbe70',
2024-11-29 11:40:01   '05e17e98-2d0b-4c41-8a2e-7bb9d833791d',
2024-11-29 11:40:01   '0611f0b6-b617-4bdd-8287-2cbad24a7b55',
2024-11-29 11:40:01   '06262f5a-48ce-4372-a5c4-89efb21da937',
2024-11-29 11:40:01   '063fafe3-13c4-4cea-b3ea-49729b6f5b84',
2024-11-29 11:40:01   '068d88d7-3ab3-4256-9e1b-cab4ad529e14',
2024-11-29 11:40:01   '0730ee0b-2a8c-4cb0-94ab-26ec36b6956d',
2024-11-29 11:40:01   '0754d165-f9c2-49b6-8f1b-5615156cefdf',
2024-11-29 11:40:01   '079a8453-d3d1-4640-87e6-36af5d3e90e3',
2024-11-29 11:40:01   '079f63d9-bcd1-4c07-8180-21b2d045098d',
2024-11-29 11:40:01   '07dc67e5-c554-49c9-acbe-928f8728e6eb',
2024-11-29 11:40:01   '07ffdc3f-441b-4f25-a727-ff4cb238f046',
2024-11-29 11:40:01   '082113d1-26b5-433b-87e9-5aaebb2d9b05',
2024-11-29 11:40:01   '08830f0e-9587-42c1-8681-5835927348e4',
2024-11-29 11:40:01   '08aa9f72-e56d-4c53-ba15-005973dd81cf',
2024-11-29 11:40:01   '08b5f73d-e6d2-49e8-86c3-4601f582343f',
2024-11-29 11:40:01   '090ac5f5-dbc3-4658-9dc5-dc9841210b86',
2024-11-29 11:40:01   '09ec7823-0989-430d-b73b-a8af1ed547f6',
2024-11-29 11:40:01   '0a62d6bc-d54d-4eb0-8660-5b6999b71eb3',
2024-11-29 11:40:01   '0ad4d868-924b-4134-9ac2-4b7c14f175e3',
2024-11-29 11:40:01   '0b170439-cdf4-4b31-8221-9fce7da368bf',
2024-11-29 11:40:01   '0b2d6b87-4209-4239-8b92-fd1c482fc949',
2024-11-29 11:40:01   '0b4cef44-0cc4-4b1b-88b1-55f83f720370',
2024-11-29 11:40:01   '0b85ff71-9f25-4f7c-84eb-f5a14cf6ebdc',
2024-11-29 11:40:01   '0bb368ee-3a9b-4ed9-8cb6-c7a6c328fe30',
2024-11-29 11:40:01   '0c448679-768b-4da7-971d-103c8893c942',
2024-11-29 11:40:01   '0c7d73a6-b342-4f31-9c16-ea6f553494b4',
2024-11-29 11:40:01   '0cc50f72-05b6-47d9-bcab-2048e08f5abb',
2024-11-29 11:40:01   '0cea1764-f6d8-49db-848f-a89d3729cf10',
2024-11-29 11:40:01   '0d00a106-b6fd-4c69-b1b1-d48ab9898a82',
2024-11-29 11:40:01   '0d013350-87fd-46cf-b467-853e7d324285',
2024-11-29 11:40:01   '0d6e8862-0c0e-47b8-92b1-e02336faf4bb',
2024-11-29 11:40:01   '0da28089-eeff-428a-aa6a-44bb9fb3a5b5',
2024-11-29 11:40:01   '0de13aa0-6d37-417d-8f5c-6266cc3d5c95',
2024-11-29 11:40:01   '0eb85b4c-61e8-4972-81cd-f77128e93cd0',
2024-11-29 11:40:01   '0ebc5043-9424-49b7-99f5-9cf7112564cf',
2024-11-29 11:40:01   '0ecaabef-3994-49bc-819e-8a908c19d61f',
2024-11-29 11:40:01   '0ef91261-cc8c-4514-8e4f-537e583c4bcd',
2024-11-29 11:40:01   '0f2f25fe-db05-4b75-b712-c92309583e02',
2024-11-29 11:40:01   '0f54ddd2-5c83-43ae-8952-f3dbaa3e03f8',
2024-11-29 11:40:01   '1007c856-ce98-497d-bc63-5dd90d0eee0a',
2024-11-29 11:40:01   '10938009-8487-4c88-aa46-3883e5032b01',
2024-11-29 11:40:01   '117a2d4a-2d98-4ced-94a0-1f090276f1c7',
2024-11-29 11:40:01   '11e08237-bbba-44b5-90aa-8d6268c85847',
2024-11-29 11:40:01   '1246c08d-e45a-439c-a7be-f5587df16bfc',
2024-11-29 11:40:01   '1256789f-0c12-46e2-90c1-1fc75a21078d',
2024-11-29 11:40:01   '12bac02a-6a33-464a-8a66-72e6b372a166',
2024-11-29 11:40:01   '12c23fb3-54f1-44a3-9945-503228ddbb38',
2024-11-29 11:40:01   '1312e4eb-0c0c-477b-8680-6b0e3052d87f',
2024-11-29 11:40:01   '13338241-b125-44fd-9a7d-9d2fa11cbdf7',
2024-11-29 11:40:01   '137c4238-1f63-42d9-87d4-eaa2f4036578',
2024-11-29 11:40:01   '13a52063-2415-476c-8385-c2ea387ba1cb',
2024-11-29 11:40:01   '13bcc54d-b16e-4d6e-b804-8b40aa35722b',
2024-11-29 11:40:01   '13d89519-f99b-4150-a936-14bc25f15193',
2024-11-29 11:40:01   '14a01fcd-1981-42f7-aaf6-2b59f1e059b3',
2024-11-29 11:40:01   '14aa5c4c-6e34-49d7-840f-0d8c7bc3c53b',
2024-11-29 11:40:01   '1516ccf6-cd36-4e0c-ba18-4653d904449a',
2024-11-29 11:40:01   '151f6cd8-605f-4697-8b09-7fd070183e45',
2024-11-29 11:40:01   '15870dee-77d5-4f96-83c0-256666be8a9d',
2024-11-29 11:40:01   '1597a99a-3521-41b1-a62a-0e6723849905',
2024-11-29 11:40:01   '15a6746d-a072-4c3a-8224-76438ebc78e6',
2024-11-29 11:40:01   '15ecb288-4e97-4b10-8822-750dff36b872',
2024-11-29 11:40:01   '15eedf4b-7dcd-4282-9446-7b4e3f822172',
2024-11-29 11:40:01   '161cb093-cdf8-497d-bf79-e0d64ed2823a',
2024-11-29 11:40:01   '1644ec6c-1f47-4e80-ae78-c9c00bdf1c6b',
2024-11-29 11:40:01   '1693e576-2a22-430c-9934-7d7303f0b526',
2024-11-29 11:40:01   '16e66243-7b01-4445-aec2-b96676c08d91',
2024-11-29 11:40:01   '16ec2003-7021-4035-9747-64cfbd70e9ff',
2024-11-29 11:40:01   '16fb9a33-4953-415b-be1e-2fe7bcbeaebf',
2024-11-29 11:40:01   '1738bdf4-6c1d-4b3c-8a87-59b1d45a16c8',
2024-11-29 11:40:01   '17685639-0e99-44a7-84c2-76cac4115222',
2024-11-29 11:40:01   '1773f9b9-e58b-4d5d-a769-3270a61ebb6d',
2024-11-29 11:40:01   '17aced2c-2364-4aa6-9360-ef0ebdae304f',
2024-11-29 11:40:01   '17d89449-a62d-4296-8b4b-aac85a03411c',
2024-11-29 11:40:01   '18403251-fef8-4b42-a47f-66a7ebbe338f',
2024-11-29 11:40:01   '185e9d7b-d1d1-47fc-8dd3-2a66a17cb271',
2024-11-29 11:40:01   '18c92ede-f7af-42b0-82cd-7d0cfbbc677b',
2024-11-29 11:40:01   '18d484df-a360-4533-8a76-3ed3a5fc0260',
2024-11-29 11:40:01   '1915b12a-c449-4031-878b-e0cab959b6d1',
2024-11-29 11:40:01   '192a2796-a540-4c7e-a899-d9db08d49679',
2024-11-29 11:40:01   ... 1005 more items
2024-11-29 11:40:01 ]
2024-11-29 11:40:01 Amount:  1105
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  [ '051e7d21-a148-403b-bf60-16dd297ef64b' ]
2024-11-29 11:40:01 Amount:  1
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 Reports to purge:  []
2024-11-29 11:40:01 Amount:  0
2024-11-29 11:40:01 2024-11-29T09:40:01.318 INFO: Purging: Starting contacts batch: key "team_lead", doc id "69604907-a31d-4f93-a7c0-99ce6797035d", batch size 1000 
2024-11-29 11:40:01 2024-11-29T09:40:01.324 INFO: Purging: Starting "unallocated reports" purge batch with id "" 
2024-11-29 11:40:01 Reports to purge:  [ '0091e5dd-067d-49cf-bc84-fe1db9b6d3d5' ]
2024-11-29 11:40:01 Amount:  1
2024-11-29 11:40:01 Reports to purge:  [ '012890f6-8a2a-4177-9e4e-17fd95fd7866' ]
2024-11-29 11:40:01 Amount:  1
2024-11-29 11:40:01 Reports to purge:  [ '012d076b-41c4-4408-ad60-c088a49deb0f' ]
... many more
8

rc_code are ancient, I don’t remember of anyone using these in the past 7 years.
The from field should suffice, but it has to match the phone number of a contact and you need to have update_clinics enabled and then push a new doc.

1 Like