Document outputFields

README-source.md

@@ -441,9 +441,9 @@ Each of the 3 types of function expects a certain type of object. As of core `v1
 | Search | Array | 0 or more objects. If len > 0, put the best match first |
 | Action | Object | Return values are evaluated by [`isPlainObject`](https://lodash.com/docs#isPlainObject) |
 
-## Fields
+## Input Fields
 
-On each trigger, search, or create in the `operation` directive - you can provide an array of objects as fields under the `inputFields`. Fields are what your users would see in the main Zapier user interface. For example, you might have a "create contact" action with fields like "First name", "Last name", "Email", etc.
+On each trigger, search, or create in the `operation` directive - you can provide an array of objects as fields under the `inputFields`. Input Fields are what your users would see in the main Zapier user interface. For example, you might have a "create contact" action with fields like "First name", "Last name", "Email", etc.
 
 You can find more details on each and every field option at [Field Schema](https://zapier.github.io/zapier-platform-schema/build/schema.html#fieldschema).
 
@@ -509,6 +509,28 @@ In OAuth and Session Auth, you might want to store fields in `bundle.authData` (
 
 For those situations, you need a computed field. It's just like another field, but with a `computed: true` property (don't forget to also make it `required: false`). You can see examples in the [OAuth](#oauth2) or [Session Auth](#session) example sections.
 
+## Output Fields
+
+On each trigger, search, or create in the operation directive - you can provide an array of objects as fields under the `outputFields`. Output Fields are what your users would see when they select a field provided by your trigger, search or create to map it to another.
+
+Output Fields are optional, but can be used to:
+
+- Define friendly labels for the returned fields. By default, we will *humanize* for example `my_key` as *My Key*.
+- Mark certain fields as `important` to sort them higher in the list of available fields to map.
+- Make sure that custom fields that may not be found in every live sample and - since they're custom to the connected account - cannot be defined in the static sample, can still be mapped.
+
+The [schema](https://zapier.github.io/zapier-platform-schema/build/schema.html#fieldschema) for `outputFields` is shared with `inputFields` but only the `key`, `required` and `important` properties are relevant.
+
+Custom/Dynamic Output Fields are defined in the same way as [Custom/Dynamic Input Fields](#customdynamic-fields).
+
+### Nested & Children (Line Item) Fields
+
+To define an Output Field for a nested field use `{{parent}}__{{key}}`. For children (line item) fields use `{{parent}}[]{{key}}`.
+
+```js
+[insert-file:./snippets/output-fields.js]
+```
+
 ## Z Object
 
 We provide several methods off of the `z` object, which is provided as the first argument to all function calls in your app.

README.md

@@ -47,11 +47,13 @@ Zapier is a platform for creating integrations and workflows. This CLI is your g
   * [Resource Definition](#resource-definition)
 - [Triggers/Searches/Creates](#triggerssearchescreates)
   * [Return Types](#return-types)
-- [Fields](#fields)
+- [Input Fields](#input-fields)
   * [Custom/Dynamic Fields](#customdynamic-fields)
   * [Dynamic Dropdowns](#dynamic-dropdowns)
   * [Search-Powered Fields](#search-powered-fields)
   * [Computed Fields](#computed-fields)
+- [Output Fields](#output-fields)
+  * [Nested & Children (Line Item) Fields](#nested--children-line-item-fields)
 - [Z Object](#z-object)
   * [`z.request([url], options)`](#zrequesturl-options)
   * [`z.console`](#zconsole)
@@ -837,9 +839,9 @@ Each of the 3 types of function expects a certain type of object. As of core `v1
 | Search | Array | 0 or more objects. If len > 0, put the best match first |
 | Action | Object | Return values are evaluated by [`isPlainObject`](https://lodash.com/docs#isPlainObject) |
 
-## Fields
+## Input Fields
 
-On each trigger, search, or create in the `operation` directive - you can provide an array of objects as fields under the `inputFields`. Fields are what your users would see in the main Zapier user interface. For example, you might have a "create contact" action with fields like "First name", "Last name", "Email", etc.
+On each trigger, search, or create in the `operation` directive - you can provide an array of objects as fields under the `inputFields`. Input Fields are what your users would see in the main Zapier user interface. For example, you might have a "create contact" action with fields like "First name", "Last name", "Email", etc.
 
 You can find more details on each and every field option at [Field Schema](https://zapier.github.io/zapier-platform-schema/build/schema.html#fieldschema).
 
@@ -1070,6 +1072,74 @@ In OAuth and Session Auth, you might want to store fields in `bundle.authData` (
 
 For those situations, you need a computed field. It's just like another field, but with a `computed: true` property (don't forget to also make it `required: false`). You can see examples in the [OAuth](#oauth2) or [Session Auth](#session) example sections.
 
+## Output Fields
+
+On each trigger, search, or create in the operation directive - you can provide an array of objects as fields under the `outputFields`. Output Fields are what your users would see when they select a field provided by your trigger, search or create to map it to another.
+
+Output Fields are optional, but can be used to:
+
+- Define friendly labels for the returned fields. By default, we will *humanize* for example `my_key` as *My Key*.
+- Mark certain fields as `important` to sort them higher in the list of available fields to map.
+- Make sure that custom fields that may not be found in every live sample and - since they're custom to the connected account - cannot be defined in the static sample, can still be mapped.
+
+The [schema](https://zapier.github.io/zapier-platform-schema/build/schema.html#fieldschema) for `outputFields` is shared with `inputFields` but only the `key`, `required` and `important` properties are relevant.
+
+Custom/Dynamic Output Fields are defined in the same way as [Custom/Dynamic Input Fields](#customdynamic-fields).
+
+### Nested & Children (Line Item) Fields
+
+To define an Output Field for a nested field use `{{parent}}__{{key}}`. For children (line item) fields use `{{parent}}[]{{key}}`.
+
+```js
+const recipeOutputFields = (z, bundle) => {
+  const response = z.request('http://example.com/api/v2/fields.json');
+  // json is like [{"key":"field_1","label":"Label for Custom Field"}]
+  return response.then(res => res.json);
+};
+
+const App = {
+  //...
+  triggers: {
+    new_recipe: {
+      //...
+      operation: {
+        perform: () => {},
+        sample: {
+          id: 1,
+          nested_parent: {
+            key: 'Nested Field'
+          },
+          children_parent: [
+            {
+              key: 'Children Field'
+            }
+          ]
+        },
+        // an array of objects is the simplest way
+        outputFields: [
+          {
+            key: 'id',
+            label: 'Label for Simple Field',
+          },
+          {
+            key: 'nested_parent__key',
+            label: 'Label for Nested Field',
+            important: true,
+          },
+          {
+            key: 'children_parent[]key',
+            label: 'Label for Children Field',
+            important: true,
+          },
+          recipeOutputFields // provide a function inline - we'll merge the results!
+        ],
+      }
+    }
+  }
+};
+
+```
+
 ## Z Object
 
 We provide several methods off of the `z` object, which is provided as the first argument to all function calls in your app.

docs/cli.html

@@ -754,7 +754,7 @@ <h2 id="init">init</h2>
 <p>Note: this doesn&apos;t register or deploy the app with Zapier - try <code>zapier register &quot;Example&quot;</code> and <code>zapier push</code> for that!</p>
 </blockquote><p><strong>Arguments</strong></p><ul>
 <li><code>path [value]</code> -- <strong>required</strong>,</li>
-<li><code>--template={minimal,resource,trigger,create,search,middleware,basic-auth,custom-auth,oauth2,session-auth,babel,rest-hooks,files,github,search-or-create,typescript}</code> -- <em>optional</em>, select a starting app template. Default is <code>minimal</code></li>
+<li><code>--template={minimal,trigger,search,create,basic-auth,custom-auth,oauth2,session-auth,dynamic-dropdown,files,middleware,resource,rest-hooks,search-or-create,babel,typescript,github}</code> -- <em>optional</em>, select a starting app template. Default is <code>minimal</code></li>
 </ul>
     </div>
     <div class="col-md-7 col-sm-12 col-height  docs-code">

docs/cli.md

@@ -429,7 +429,7 @@ After running this, you'll have a new example app in your directory. If you re-r
 **Arguments**
 
 * `path [value]` -- **required**,
-* `--template={minimal,resource,trigger,create,search,middleware,basic-auth,custom-auth,oauth2,session-auth,babel,rest-hooks,files,github,search-or-create,typescript}` -- _optional_, select a starting app template. Default is `minimal`
+* `--template={minimal,trigger,search,create,basic-auth,custom-auth,oauth2,session-auth,dynamic-dropdown,files,middleware,resource,rest-hooks,search-or-create,babel,typescript,github}` -- _optional_, select a starting app template. Default is `minimal`
 
 ```bash
 $ zapier init example-app --template=minimal

docs/index.html

@@ -280,13 +280,17 @@ <h2 class="docs-header__platform-title">Developer Platform</h2>
 <li><a href="#return-types">Return Types</a></li>
 </ul>
 </li>
-<li><a href="#fields">Fields</a><ul>
+<li><a href="#input-fields">Input Fields</a><ul>
 <li><a href="#customdynamic-fields">Custom/Dynamic Fields</a></li>
 <li><a href="#dynamic-dropdowns">Dynamic Dropdowns</a></li>
 <li><a href="#search-powered-fields">Search-Powered Fields</a></li>
 <li><a href="#computed-fields">Computed Fields</a></li>
 </ul>
 </li>
+<li><a href="#output-fields">Output Fields</a><ul>
+<li><a href="#nested--children-line-item-fields">Nested &amp; Children (Line Item) Fields</a></li>
+</ul>
+</li>
 <li><a href="#z-object">Z Object</a><ul>
 <li><a href="#zrequesturl-options"><code>z.request([url], options)</code></a></li>
 <li><a href="#zconsole"><code>z.console</code></a></li>
@@ -463,13 +467,17 @@ <h2 id="table-of-contents">Table of Contents</h2>
 <li><a href="#return-types">Return Types</a></li>
 </ul>
 </li>
-<li><a href="#fields">Fields</a><ul>
+<li><a href="#input-fields">Input Fields</a><ul>
 <li><a href="#customdynamic-fields">Custom/Dynamic Fields</a></li>
 <li><a href="#dynamic-dropdowns">Dynamic Dropdowns</a></li>
 <li><a href="#search-powered-fields">Search-Powered Fields</a></li>
 <li><a href="#computed-fields">Computed Fields</a></li>
 </ul>
 </li>
+<li><a href="#output-fields">Output Fields</a><ul>
+<li><a href="#nested--children-line-item-fields">Nested &amp; Children (Line Item) Fields</a></li>
+</ul>
+</li>
 <li><a href="#z-object">Z Object</a><ul>
 <li><a href="#zrequesturl-options"><code>z.request([url], options)</code></a></li>
 <li><a href="#zconsole"><code>z.console</code></a></li>
@@ -1697,7 +1705,7 @@ <h3 id="return-types">Return Types</h3>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <h2 id="fields">Fields</h2>
+      <h2 id="input-fields">Input Fields</h2>
     </div>
     <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
 
@@ -1706,7 +1714,7 @@ <h2 id="fields">Fields</h2>
 </div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
-      <p>On each trigger, search, or create in the <code>operation</code> directive - you can provide an array of objects as fields under the <code>inputFields</code>. Fields are what your users would see in the main Zapier user interface. For example, you might have a &quot;create contact&quot; action with fields like &quot;First name&quot;, &quot;Last name&quot;, &quot;Email&quot;, etc.</p><p>You can find more details on each and every field option at <a href="https://zapier.github.io/zapier-platform-schema/build/schema.html#fieldschema">Field Schema</a>.</p><p>Those fields have various options you can provide, here is a succinct example:</p>
+      <p>On each trigger, search, or create in the <code>operation</code> directive - you can provide an array of objects as fields under the <code>inputFields</code>. Input Fields are what your users would see in the main Zapier user interface. For example, you might have a &quot;create contact&quot; action with fields like &quot;First name&quot;, &quot;Last name&quot;, &quot;Email&quot;, etc.</p><p>You can find more details on each and every field option at <a href="https://zapier.github.io/zapier-platform-schema/build/schema.html#fieldschema">Field Schema</a>.</p><p>Those fields have various options you can provide, here is a succinct example:</p>
     </div>
     <div class="col-md-7 col-sm-12 col-height  docs-code">
       <pre><code class="lang-js"><span class="hljs-keyword">const</span> App = {
@@ -1999,6 +2007,93 @@ <h3 id="computed-fields">Computed Fields</h3>
     </div>
   </div>
 </div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <h2 id="output-fields">Output Fields</h2>
+    </div>
+    <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
+
+    </div>
+  </div>
+</div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <p>On each trigger, search, or create in the operation directive - you can provide an array of objects as fields under the <code>outputFields</code>. Output Fields are what your users would see when they select a field provided by your trigger, search or create to map it to another.</p><p>Output Fields are optional, but can be used to:</p><ul>
+<li>Define friendly labels for the returned fields. By default, we will <em>humanize</em> for example <code>my_key</code> as <em>My Key</em>.</li>
+<li>Mark certain fields as <code>important</code> to sort them higher in the list of available fields to map.</li>
+<li>Make sure that custom fields that may not be found in every live sample and - since they&apos;re custom to the connected account - cannot be defined in the static sample, can still be mapped.</li>
+</ul><p>The <a href="https://zapier.github.io/zapier-platform-schema/build/schema.html#fieldschema">schema</a> for <code>outputFields</code> is shared with <code>inputFields</code> but only the <code>key</code>, <code>required</code> and <code>important</code> properties are relevant.</p><p>Custom/Dynamic Output Fields are defined in the same way as <a href="#customdynamic-fields">Custom/Dynamic Input Fields</a>.</p>
+    </div>
+    <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
+
+    </div>
+  </div>
+</div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <h3 id="nested--children-line-item-fields">Nested &amp; Children (Line Item) Fields</h3>
+    </div>
+    <div class="col-md-7 col-sm-12 col-height is-empty docs-code">
+
+    </div>
+  </div>
+</div><div class="row">
+  <div class="row-height">
+    <div class="col-md-5 col-sm-12 col-height  docs-primary">
+      <p>To define an Output Field for a nested field use <code>{{parent}}__{{key}}</code>. For children (line item) fields use <code>{{parent}}[]{{key}}</code>.</p>
+    </div>
+    <div class="col-md-7 col-sm-12 col-height  docs-code">
+      <pre><code class="lang-js"><span class="hljs-keyword">const</span> recipeOutputFields = <span class="hljs-function">(<span class="hljs-params">z, bundle</span>) =&gt;</span> {
+  <span class="hljs-keyword">const</span> response = z.request(<span class="hljs-string">&apos;http://example.com/api/v2/fields.json&apos;</span>);
+  <span class="hljs-comment">// json is like [{&quot;key&quot;:&quot;field_1&quot;,&quot;label&quot;:&quot;Label for Custom Field&quot;}]</span>
+  <span class="hljs-keyword">return</span> response.then(<span class="hljs-function"><span class="hljs-params">res</span> =&gt;</span> res.json);
+};
+
+<span class="hljs-keyword">const</span> App = {
+  <span class="hljs-comment">//...</span>
+  triggers: {
+    <span class="hljs-attr">new_recipe</span>: {
+      <span class="hljs-comment">//...</span>
+      operation: {
+        <span class="hljs-attr">perform</span>: <span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {},
+        <span class="hljs-attr">sample</span>: {
+          <span class="hljs-attr">id</span>: <span class="hljs-number">1</span>,
+          <span class="hljs-attr">nested_parent</span>: {
+            <span class="hljs-attr">key</span>: <span class="hljs-string">&apos;Nested Field&apos;</span>
+          },
+          <span class="hljs-attr">children_parent</span>: [
+            {
+              <span class="hljs-attr">key</span>: <span class="hljs-string">&apos;Children Field&apos;</span>
+            }
+          ]
+        },
+        <span class="hljs-comment">// an array of objects is the simplest way</span>
+        outputFields: [
+          {
+            <span class="hljs-attr">key</span>: <span class="hljs-string">&apos;id&apos;</span>,
+            <span class="hljs-attr">label</span>: <span class="hljs-string">&apos;Label for Simple Field&apos;</span>,
+          },
+          {
+            <span class="hljs-attr">key</span>: <span class="hljs-string">&apos;nested_parent__key&apos;</span>,
+            <span class="hljs-attr">label</span>: <span class="hljs-string">&apos;Label for Nested Field&apos;</span>,
+            <span class="hljs-attr">important</span>: <span class="hljs-literal">true</span>,
+          },
+          {
+            <span class="hljs-attr">key</span>: <span class="hljs-string">&apos;children_parent[]key&apos;</span>,
+            <span class="hljs-attr">label</span>: <span class="hljs-string">&apos;Label for Children Field&apos;</span>,
+            <span class="hljs-attr">important</span>: <span class="hljs-literal">true</span>,
+          },
+          recipeOutputFields <span class="hljs-comment">// provide a function inline - we&apos;ll merge the results!</span>
+        ],
+      }
+    }
+  }
+};
+
+</code></pre>
+    </div>
+  </div>
+</div><div class="row">
   <div class="row-height">
     <div class="col-md-5 col-sm-12 col-height  docs-primary">
       <h2 id="z-object">Z Object</h2>