Remote Request Query and Post Configurations

Remote request is a 2 part workflow including a Query and a Post request with user selction from results. We first show the user query prompts using the definition allowing the user to input values for query prompts and trigger a search using those prompts from UI. The query request is a http request to the url formed by appending the user inputs as query parameters to the given search url defined in block. Results from this query request are then showed to the user using the detail definition specified by session datum in the . The user selection from these results is stored into the session datum to be used in the Post Request. Once the Query workflow completes with a user selection, the engine fires a post request with the session datum collected in query workflow.

You can read about specifics of remote-request suite configuration over here. This page aims to discuss some of the example workflows you can implement with this spec to suit your needs.

In the normal case query and claim workflow user gets a search button on the case list screen clicking which takes the user to the Query screen. This is achieved by defining an action in the case list detail definition -

<detail id="m1_search_short">
  ...
  <action auto_launch="false()">
      <display>
         ...
      </display>
      <stack>
        <push>
          <mark/>
          <command value="'search_command.m1'"/>
        </push>
      </stack>
  </action>
</detail>
<remote-request>
    ...
    <command id="search_command.m1">
    </command>
</remote-request>

The auto_launch flag in the action controls whether you want to launch the action without the user pressing the assisted action button. If you want to take user directly to the query screen you can define the action with auto_launch="true()" instead. Though what if instead of showing the query screen you directly want to show the results of the default query to the user. To do that you can utilize the default_search option on the query node as shown below -

<detail id="m1_search_short">
  ...
  <action auto_launch="true()">
      <display>
         ...
      </display>
      <stack>
        <push>
          <mark/>
          <command value="'search_command.m1'"/>
        </push>
      </stack>
  </action>
</detail>
<remote-request>
    ...
    <command id="search_command.m1">
    </command>
    <session>
      <query url="https://www.commcarehq.org/a/example/phone/search/119365e4d0a24a86bc9c1811a51dab67/" storage-instance="results" template="case" default_search="true">
       ...
      </query>
      <datum id="search_case_id" nodeset="instance('results')/results/case[@case_type='song'][not(commcare_is_related_case=true())]" value="./@case_id" detail-select="m1_search_short" detail-confirm="m1_search_long"/>
    </session>
</remote-request>

Now when you take the user directly to the query results screen, user might not found the desired entity in the results and would want to narrow down the search results. Therefore with this configuration, we should generally allow user to get back to query screen from the search results screen. We can configure this by again adding an action tag to the search results detail definition (m1_search_short in the above example) -

<detail id="m1_search_short">
  ...
  <action auto_launch="false()" redo_last="true">
      <display>
         ...
      </display>
      <stack>
        <push>
          <mark/>
          <command value="'search_command.m1'"/>
        </push>
      </stack>
  </action>
</detail>

Here auto_launch is set to false since we do want a manual click from the query results screen for user to go to the query screen. The redo_last flag is there to tell the engine that we want to perform the last action again overriding the default_search flag. That is with redo_last set to true the last action to take the user to query screen will be performed though user won't be taken to the search screen by default and instead they can configure the query prompts manually to narrow down the search as per their needs.