https://ampath-forms.vercel.app/_next/static/chunks/pages/docs/adv…/generating-payloads-5fee99ed1693d50f.js

1(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[78],{7799:function(e,s,n){(window.__NEXT_P=window.__NEXT_P||[]).push(["/docs/advanced-topics/generating-payloads",function(){return n(3234)}])},3234:function(e,s,n){"use strict";n.r(s),n.d(s,{__toc:function(){return a}});var r=n(1527),o=n(1872),t=n(148),i=n(2569);let a=[{depth:2,value:"Populating a form from an existing encounter",id:"populating-a-form-from-an-existing-encounter"},{depth:2,value:"Generating a submission payload",id:"generating-a-submission-payload"},{depth:2,value:"The individual adapters",id:"the-individual-adapters"}];function l(e){let s=Object.assign({h1:"h1",blockquote:"blockquote",p:"p",strong:"strong",code:"code",a:"a",pre:"pre",span:"span",h2:"h2",ul:"ul",li:"li",table:"table",thead:"thead",tr:"tr",th:"th",tbody:"tbody",td:"td"},(0,t.a)(),e.components);return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(s.h1,{children:"Populating Forms and Generating Payloads"}),"\n",(0,r.jsxs)(s.blockquote,{children:["\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.strong,{children:"Angular Form Engine scope."})," This page documents population and payload behavior in ",(0,r.jsx)(s.code,{children:"@openmrs/ngx-formentry"}),". The React Form Engine may produce or consume data differently. See ",(0,r.jsx)(s.a,{href:"/docs/about-this-documentation",children:"About this documentation"}),"."]}),"\n"]}),"\n",(0,r.jsxs)(s.p,{children:["The Form Engine converts between REST payloads and form values through a set of ",(0,r.jsx)(s.strong,{children:"value adapters"}),". They work in both directions: ",(0,r.jsx)(s.code,{children:"populateForm"})," writes values from an existing encounter into the form's controls, and ",(0,r.jsx)(s.code,{children:"generateFormPayload"})," reads the form back out into a payload you can POST to the OpenMRS REST API."]}),"\n",(0,r.jsxs)(s.p,{children:["All adapters are provided by ",(0,r.jsx)(s.code,{children:"FormEntryModule"}),", so you can inject them directly:"]}),"\n",(0,r.jsx)(s.pre,{"data-language":"ts","data-theme":"default",hasCopyCode:!0,children:(0,r.jsxs)(s.code,{"data-language":"ts","data-theme":"default",children:[(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"import"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" {"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  EncounterAdapter"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  ObsValueAdapter"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  OrderValueAdapter"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  PersonAttributeAdapter"})}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"} "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"from"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'@openmrs/ngx-formentry'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:";"})]}),"\n",(0,r.jsx)(s.span,{className:"line",children:" "}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"constructor"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"(private encounterAdapter: EncounterAdapter) {}"})]})]})}),"\n",(0,r.jsx)(s.h2,{id:"populating-a-form-from-an-existing-encounter",children:"Populating a form from an existing encounter"}),"\n",(0,r.jsxs)(s.p,{children:["Pass a REST-representation encounter to the ",(0,r.jsx)(s.code,{children:"EncounterAdapter"}),":"]}),"\n",(0,r.jsx)(s.pre,{"data-language":"ts","data-theme":"default",hasCopyCode:!0,children:(0,r.jsx)(s.code,{"data-language":"ts","data-theme":"default",children:(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"this"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"."}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"encounterAdapter"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".populateForm"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"this"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:".form"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" encounter);"})]})})}),"\n",(0,r.jsxs)(s.p,{children:["The adapter sets the ",(0,r.jsx)(s.code,{children:"encounterDatetime"}),", ",(0,r.jsx)(s.code,{children:"encounterProvider"}),", and ",(0,r.jsx)(s.code,{children:"encounterLocation"})," questions from the encounter's fields, then delegates the encounter's ",(0,r.jsx)(s.code,{children:"obs"}),", ",(0,r.jsx)(s.code,{children:"orders"}),", and ",(0,r.jsx)(s.code,{children:"diagnoses"})," arrays to the corresponding child adapters. Each populated control also records its initial value, which is what makes diff-based editing work when the form is submitted again."]}),"\n",(0,r.jsx)(s.h2,{id:"generating-a-submission-payload",children:"Generating a submission payload"}),"\n",(0,r.jsxs)(s.p,{children:["Before generating, set the form's ",(0,r.jsx)(s.code,{children:"valueProcessingInfo"})," — contextual values that the form itself doesn't capture:"]}),"\n",(0,r.jsx)(s.pre,{"data-language":"ts","data-theme":"default",hasCopyCode:!0,children:(0,r.jsxs)(s.code,{"data-language":"ts","data-theme":"default",children:[(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"this"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"."}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"form"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:".valueProcessingInfo "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" {"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  patientUuid"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'patient-uuid'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  visitUuid"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'visit-uuid'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  encounterTypeUuid"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'encounter-type-uuid'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  formUuid"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'form-uuid'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  encounterUuid"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'encounter-uuid'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-comment)"},children:"// when editing an existing encounter"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  utcOffset"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'+0300'"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-punctuation)"},children:","})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  locationUuid"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:":"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-string-expression)"},children:"'location-uuid'"})]}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"};"})}),"\n",(0,r.jsx)(s.span,{className:"line",children:" "}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"if"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" ("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"this"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"."}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"form"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:".valid) {"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"const"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"payload"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-keyword)"},children:"="}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:" "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"this"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:"."}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"encounterAdapter"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-function)"},children:".generateFormPayload"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"("}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-constant)"},children:"this"}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:".form);"})]}),"\n",(0,r.jsxs)(s.span,{className:"line",children:[(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"  "}),(0,r.jsx)(s.span,{style:{color:"var(--shiki-token-comment)"},children:"// POST payload to the encounter REST endpoint"})]}),"\n",(0,r.jsx)(s.span,{className:"line",children:(0,r.jsx)(s.span,{style:{color:"var(--shiki-color-text)"},children:"}"})})]})}),"\n",(0,r.jsxs)(s.p,{children:[(0,r.jsx)(s.code,{children:"generateFormPayload"})," assembles:"]}),"\n",(0,r.jsxs)(s.ul,{children:["\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"encounterDatetime"}),": the encounter date question's value, formatted with the configured ",(0,r.jsx)(s.code,{children:"utcOffset"})," (defaults to ",(0,r.jsx)(s.code,{children:"+0300"}),")."]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"encounterProviders"}),': the provider question\'s value, with the default "unknown provider" encounter role.']}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"location"}),": the location question's value."]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"patient"}),", ",(0,r.jsx)(s.code,{children:"visit"}),", ",(0,r.jsx)(s.code,{children:"encounterType"}),", ",(0,r.jsx)(s.code,{children:"form"}),", and the encounter ",(0,r.jsx)(s.code,{children:"uuid"}),", taken from ",(0,r.jsx)(s.code,{children:"valueProcessingInfo"}),"."]}),"\n",(0,r.jsxs)(s.li,{children:[(0,r.jsx)(s.code,{children:"obs"}),", ",(0,r.jsx)(s.code,{children:"orders"}),", and ",(0,r.jsx)(s.code,{children:"diagnoses"})," arrays, generated by the child adapters."]}),"\n"]}),"\n",(0,r.jsxs)(s.p,{children:["For a form that was populated from an existing encounter, the obs adapter diffs each control's current value against its initial value: new answers become new obs, changed answers carry the existing obs ",(0,r.jsx)(s.code,{children:"uuid"})," with the new value, and cleared answers are emitted with ",(0,r.jsx)(s.code,{children:"voided: true"}),"."]}

1),"\n",(0,r.jsx)(s.h2,{id:"the-individual-adapters",children:"The individual adapters"}),"\n",(0,r.jsx)(s.p,{children:"You can also use each adapter on its own when you only need part of the payload:"}),"\n",(0,r.jsxs)(s.table,{children:[(0,r.jsx)(s.thead,{children:(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.th,{children:"Adapter"}),(0,r.jsx)(s.th,{children:"Generates"})]})}),(0,r.jsxs)(s.tbody,{children:[(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:(0,r.jsx)(s.code,{children:"EncounterAdapter"})}),(0,r.jsx)(s.td,{children:"The complete encounter payload, delegating to the obs, orders, and diagnoses adapters"})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:(0,r.jsx)(s.code,{children:"ObsValueAdapter"})}),(0,r.jsxs)(s.td,{children:["The ",(0,r.jsx)(s.code,{children:"obs"})," array, including obs groups and voiding for cleared values"]})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:(0,r.jsx)(s.code,{children:"OrderValueAdapter"})}),(0,r.jsxs)(s.td,{children:["The ",(0,r.jsx)(s.code,{children:"orders"})," array"]})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:(0,r.jsx)(s.code,{children:"DiagnosisValueAdapter"})}),(0,r.jsxs)(s.td,{children:["The ",(0,r.jsx)(s.code,{children:"diagnoses"})," array assembled from ",(0,r.jsx)(s.code,{children:'type: "diagnosis"'})," questions. Not part of the package's public exports, so use it via ",(0,r.jsx)(s.code,{children:"EncounterAdapter"}),", which includes its output in the encounter payload"]})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:(0,r.jsx)(s.code,{children:"PersonAttributeAdapter"})}),(0,r.jsxs)(s.td,{children:["Person attribute values from ",(0,r.jsx)(s.code,{children:"personAttribute"})," questions"]})]}),(0,r.jsxs)(s.tr,{children:[(0,r.jsx)(s.td,{children:(0,r.jsx)(s.code,{children:"PatientIdentifierAdapter"})}),(0,r.jsxs)(s.td,{children:["Patient identifiers — takes the location UUID as a second argument: ",(0,r.jsx)(s.code,{children:"generateFormPayload(form, locationUuid)"})]})]})]})]}),"\n",(0,r.jsx)(i.UW,{emoji:"ℹ️",type:"info",children:(0,r.jsxs)(s.p,{children:["The Form Engine's ",(0,r.jsx)(s.a,{href:"https://github.com/openmrs/openmrs-ngx-formentry/blob/main/src/app/app.component.ts",children:"demo app"}),"\nshows populating a form from a mock encounter on load. For executable\npayload-generation examples, see the\n",(0,r.jsx)(s.a,{href:"https://github.com/openmrs/openmrs-ngx-formentry/blob/main/projects/ngx-formentry/src/form-entry/value-adapters/encounter.adapter.spec.ts",children:"EncounterAdapter spec"}),",\nwhich exercises ",(0,r.jsx)(s.code,{children:"generateFormPayload"})," end to end."]})})]})}s.default=(0,o.j)({MDXContent:function(){let e=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{},{wrapper:s}=Object.assign({},(0,t.a)(),e.components);return s?(0,r.jsx)(s,{...e,children:(0,r.jsx)(l,{...e})}):l(e)},pageOpts:{filePath:"pages/docs/advanced-topics/generating-payloads.mdx",route:"/docs/advanced-topics/generating-payloads",timestamp:1790191883e3,title:"Populating Forms and Generating Payloads",headings:a},pageNextRoute:"/docs/advanced-topics/generating-payloads"})}},function(e){e.O(0,[872,888,774,179],function(){return e(e.s=7799)}),_N_E=e.O()}]);