{"type":"doc","content":[{"type":"paragraph","content":[{"type":"inlineExtension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"multiexcerpt-include-macro","parameters":{"macroParams":{"macro_uuid":{"value":"77a79df7-a5d1-4f8f-828d-6c8d8a40e9b2"},"name":{"value":"Software Plan - Pro"},"templateData":{"value":"eJyLjgUAARUAuQ=="},"page":{"value":"CommCare Help Site Design Guidance"},"addpanel":{"value":"false"}},"macroMetadata":{"macroId":{"value":"f345059a-caac-41b4-a970-0568905b5033"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"icon","data":{"url":"https://raw.githubusercontent.com/fuegokit/appfire-design-systems-brand-svg/main/single-color-brand-icons/af-logo-multi-excerpt-24.svg"}}],"title":"MultiExcerpt Include"}},"localId":"99144a53-9517-4b24-9f80-957475a70e2a"}},{"text":" ","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Setting up a remote API connection","type":"text"}]},{"type":"paragraph","content":[{"text":"CommCare HQ manages remote API services and credentials under ","type":"text"},{"text":"Project Settings","type":"text","marks":[{"type":"strong"}]},{"text":" > ","type":"text"},{"text":"Connection Settings","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1071,"id":"949936b5-dc56-46f7-ae97-9f1128677894","collection":"contentId-2143945549","type":"file","height":552}}]},{"type":"paragraph","content":[{"text":"Give your connection a name.","type":"text"}]},{"type":"paragraph","content":[{"text":"Provide one or more addresses to send notifications to if something unexpected happens when forwarding data.","type":"text"}]},{"type":"paragraph","content":[{"text":"Specify the URL that CommCare will be sending data to.","type":"text"}]},{"type":"paragraph","content":[{"text":"And then select how CommCare must authenticate with the remote API, and provide credentials as required.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Setting up Data Forwarding","type":"text"}]},{"type":"paragraph","content":[{"text":"You can configure your project to forward any incoming forms and/or cases to a specified URL. To do so, in CommCare HQ navigate to ","type":"text"},{"text":"Project","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"Settings","type":"text","marks":[{"type":"strong"}]},{"text":" and then to ","type":"text"},{"text":"Data Forwarding","type":"text","marks":[{"type":"strong"}]},{"text":". It will look something like this:","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":762,"id":"8726150d-da25-4a46-a766-bf3cdfb2e539","collection":"contentId-2143945549","type":"file","height":886}}]},{"type":"paragraph","content":[{"text":"There are no current limitations on the number of repeaters you can add to your project, but if you set up a repeater and notice a delay in record forwarding times, please contact our support team.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Payloads","type":"text"}]},{"type":"paragraph","content":[{"text":"When a payload is created a repeat record is registered. A repeat record represents a place in the repeat record queue, and points to the payload. On registration, its status is set to \"pending\" and HQ tries to send the payload immediately. If sending succeeds, its status is changed to \"succeeded\" and the process is complete.","type":"text"}]},{"type":"paragraph","content":[{"text":"If sending fails, its status is changed to \"failed\" and it will be retried. There are multiple retries, and each time the interval between tries is increased. This improves the chances of a successful send, because it gives the endpoint more time to recover.","type":"text"}]},{"type":"paragraph","content":[{"text":"Whether a record is queued for its first or fourth attempt, it enters the same queue. Consequently, any delays in this queue impact all records, regardless of their status.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the record is still not successfully sent after multiple retries, its state is changed to \"cancelled.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"You can follow the status of the payload by clicking on Responses.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1077,"alt":"image-20240819-145700.png","id":"eca5369f-996b-4c51-8f15-fc9ad95e8a28","collection":"contentId-2143945549","type":"file","height":263}}]},{"type":"paragraph","content":[{"text":"You are able to select payloads within the table to be resent, requeued, or canceled by checking the box for the row of the payload, or by making use of the report filters and making a bulk selection. In order to perform a bulk action a specific repeater or payload must be selected. ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":760,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":869,"alt":"image-20250515-031450.png","id":"d6481492-80a3-44f4-bc68-0f38dceabcba","collection":"contentId-2143945549","type":"file","height":311}}]},{"type":"paragraph","content":[{"text":"The actions performed are as follows:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Resend - Asynchronously resends the repeat record immediately","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Requeue - If not already in the queue (failed or pending), puts the record back into the queue","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Cancel - Immediately cancels the repeat record, preventing it from being sent","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Please note, if making a bulk payload selection, be sure to select all records you’ve filtered to within the table, rather than only select the ones shown on the current page of the report. You can do this with the button that appears under the bulk actions. ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":453,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":453,"alt":"image-20250515-031800.png","id":"90995e9c-535f-47c3-8563-184b9abd43f4","collection":"contentId-2143945549","type":"file","height":69}}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"What to have your server expect","type":"text"}]},{"type":"paragraph","content":[{"text":"Data will be forwarded, and the contents of what is forwarded will be in the body of the HTTP POST. This does not use HTML form-style parameters.","type":"text"}]},{"type":"paragraph","content":[{"text":"In the examples below, we'll show you what HTTP Headers and POST body to expect. All newlines and indentation is for clarity only below; in the actual post any newline + indentation will be a single space.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Forward Form","type":"text"}]},{"type":"paragraph","content":[{"text":"You get the complete form (one POST per form)","type":"text"}]},{"type":"paragraph","content":[{"text":"In addition to the form there will be an extra header '","type":"text"},{"text":"received-on","type":"text","marks":[{"type":"code"}]},{"text":"' that is the time the form was received by CommCare HQ.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example HTTP Request to your server","type":"text"}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"QUERYSTRING","type":"text"}]},{"type":"paragraph","content":[{"text":"app_id: db9f874f0219444ee7848ddd023e292e\n","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"HEADERS","type":"text"}]},{"type":"paragraph","content":[{"text":"Accept-Encoding: identity\nHost: requestb.in\nTotal-Route-Time: 0\nContent-Type: text/xml\nX-Request-Id: 42863ab1-1dfb-49cb-b0ed-33f924f6cd3b\nReceived-On: 2015-04-17T20:14:34.046462Z\nConnection: close\nContent-Length: 1135\nVia: 1.1 vegur\nConnect-Time: 5\n","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"RAW BODY","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n\n Trees\n \n Trees\n d0e472a6b36dfd3ee5059222e12b8c1b\n mscase\n \n \n \n 990005013558458\n 2015-04-17T16:04:42.383-04\n 2015-04-17T16:04:54.950-04\n danny\n d0e472a6b36dfd3ee5059222e12b8c1b\n afcb3026-c4b3-463f-85ec-0cb9a2737fc5\n CommCare ODK, version \"2.19.8\"(350848). App v10. CommCare Version 2.19. Build 1000, built on: January-22-2015\n \n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Forward Cases","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"You get a case block representing the latest state of any cases affected by the form (one POST per case).","type":"text"}]},{"type":"paragraph","content":[{"text":"When you turn on case forwarding, every time a case changes on HQ, it will forward the case ","type":"text"},{"text":"in its entirety","type":"text","marks":[{"type":"em"}]},{"text":" to your URL (not just the last change). We expect that you will receive the case, look to see if there's a case with the same id already in your system, and then either create or update the case with all the information given. If the case has been closed, we will send the case with just a close block.","type":"text"}]},{"type":"paragraph","content":[{"text":"The URL you set up to deal with the in-coming information can expect to receive one case block at a time, in the format specified below (XML or JSON).","type":"text"}]},{"type":"paragraph","content":[{"text":"In addition to the case there will be an extra header '","type":"text"},{"text":"server-modified-on","type":"text","marks":[{"type":"code"}]},{"text":"' that is the last time the case was modified in CommCare HQ.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example HTTP Request to your server","type":"text"}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"HEADERS","type":"text"}]},{"type":"paragraph","content":[{"text":"Server-Modified-On: 2015-04-17T20:14:34.139959Z\nHost: requestb.in\nAccept-Encoding: identity\nVia: 1.1 vegur\nX-Request-Id: 30926e2a-397a-45e4-83f2-a792c5775c7e\nTotal-Route-Time: 1\nContent-Length: 324\nConnection: close\nConnect-Time: 2\nContent-Type: text/xml\n","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"RAW BODY (XML)","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"\n \n mscase\n Trees\n d0e472a6b36dfd3ee5059222e12b8c1b\n \n","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":6},"content":[{"text":"RAW BODY (JSON)","type":"text","marks":[{"type":"textColor","attrs":{"color":"#707070"}}]}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"{ \"case_id\" : \"b0916685-7247-4c44-b712-633d3d64e0c0\", \n \"closed\" : false,\n \"date_closed\" : null,\n \"date_modified\" : \"2015-04-17T16:04:54.950000Z\",\n \"domain\" : \"demo\",\n \"indices\" : { },\n \"properties\" : {\n \"case_name\" : \"Trees\",\n \"case_type\" : \"mscase\",\n \"date_opened\" : \"2012-03-13T18:21:52Z\",\n \"owner_id\" : \"d0e472a6b36dfd3ee5059222e12b8c1b\",\n },\n \"server_date_modified\" : \"2012-04-05T23:56:41Z\",\n \"server_date_opened\" : \"2012-04-05T23:56:41Z\",\n \"user_id\" : \"d0e472a6b36dfd3ee5059222e12b8c1b\",\n \"version\" : \"2.0\",\n \"xform_ids\" : [ \"3HQEXR2S0GIRFY2GF40HAR7ZE\" ]\n }","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Forward Form Stub","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"You get a timestamp (GMT), the form's id, and the ids of any affected cases","type":"text"}]},{"type":"paragraph","content":[{"text":"This works especially well in conjunction with our ","type":"text"},{"text":"Data APIs","type":"text","marks":[{"type":"link","attrs":{"href":"https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143957366"}}]},{"text":"; you can get notified of a change using Form Stub Forwarding and then use the Data APIs to look up the form and cases affected, either right away or at a later date.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example HTTP Request to your server","type":"text"}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"HEADERS","type":"text"}]},{"type":"paragraph","content":[{"text":"Host: requestb.in\nAccept-Encoding: identity\nVia: 1.1 vegur\nReceived-On: 2015-04-17T20:14:34.046462Z\nX-Request-Id: 244433bd-85d8-4444-8cea-a56fcc30d6b2\nTotal-Route-Time: 0\nContent-Length: 151\nConnection: close\nConnect-Time: 2\nContent-Type: text/xml\n","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"RAW BODY ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"{\n \"received_on\": \"2015-04-17T20:14:34.046462Z\",\n \"form_id\": \"afcb3026-c4b3-463f-85ec-0cb9a2737fc5\",\n \"case_ids\": [\"b0916685-7247-4c44-b712-633d3d64e0c0\"]\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Forward App Schema Changes","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Description","type":"text"}]},{"type":"paragraph","content":[{"text":"You get notified of the app id whenever an app change is saved and the \"build id\" whenever a new version is built.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example HTTP Request to your server","type":"text"}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"HEADERS","type":"text"}]},{"type":"paragraph","content":[{"text":"Host: requestb.in\nAccept-Encoding: identity\nVia: 1.1 vegur\nX-Request-Id: 9f211dd8-19d0-49be-980d-3c7f879336a5\nTotal-Route-Time: 0\nContent-Length: 32\nConnection: close\nConnect-Time: 0\nContent-Type: text/xml\n","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"RAW BODY","type":"text"}]},{"type":"paragraph","content":[{"text":"193b28e58f335f165cb3e2bbe02b3ed8","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Error notifications","type":"text"}]},{"type":"paragraph","content":[{"text":"CommCare will send error notifications to the email addresses specified for the remote API connection under Connection Settings. This will happen for errors raised by the remote API, like server errors, authentication errors, response timeouts, or network connection failures.","type":"text"}]},{"type":"paragraph","content":[{"text":"The notification will show the error message as given by the remote API, and will include the name of the project space, the URL that the request was sent to, and, if applicable, the ID of the form or case that was sent, so that the recipient has the information they need to follow up.","type":"text"}]},{"type":"paragraph","content":[{"text":"The email will also include instructions on how to stop getting notification in the future. All remote API connections should have at least one email address for notifications so that if data forwarding stops working for any reason, someone is aware of that.","type":"text"}]}],"version":1}