What is the use of {@url} in actions.xml app action URL templates?

Question

In my actions.xml file, I can provide inventory for my intent's parameters using <entity-set> tags. For each <entity>, the docs indicate that I can specify a value for either identifier or url. What's the difference between identifier and url? Why do I need a <parameter-mapping> tag if I use identifier, but not if I use url?

Answer 1

The key difference is that identifier values are URL-escaped. For example:

<intent name="actions.intent.SOME_INTENT">
  <parameter name="param.name">
    <entity-set-reference entitySetId="identifier_entity_set">
  </parameter>
  <fulfillment urlTemplate="https://app.com/{param_value}">
    <parameter-mapping intentParameter="param.name" urlParameter="param_value" />
  </fulfillment>
</intent>
<entity-set entitySetId="identifier_entity_set">
  <entity identifier="escaped/url/path" name="hi">
</entity-set>

If the user says "hi" for param.name, the resolved urlTemplate will be: https://app.com/escaped%2Furl%2Fpath.

<intent name="actions.intent.SOME_INTENT">
  <parameter name="param.name">
    <entity-set-reference entitySetId="url_entity_set">
  </parameter>
</intent>
  <fulfillment urlTemplate="{@url}" />
<entity-set entitySetId="url_entity_set">
  <entity url="https://app.com/not/esacaped/url/path" name="bye">
</entity-set>

If the user says "bye" for param.name, the resolved urlTemplate will be: https://app.com/not/esacaped/url/path.

Also, note that if you have {@url} in your urlTemplate, you shouldn't include a <parameter-mapping> for it; it's assumed that you have exactly one <entity-set> with url values.