Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[SUPPORTENG-394] docs(cli): Add information about how to return line items #620

Merged
merged 3 commits into from
Feb 16, 2023
Merged

[SUPPORTENG-394] docs(cli): Add information about how to return line items #620

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5e23059
Add information about how to return line items
armchairlinguist Feb 9, 2023
c916b18
avoid close uses of for example
armchairlinguist Feb 9, 2023
3ebfda9
Remove old core version mention
armchairlinguist Feb 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 65 additions & 5 deletions docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,10 @@
</ul>
</li>
<li><a href="#triggerssearchescreates">Triggers/Searches/Creates</a><ul>
<li><a href="#return-types">Return Types</a></li>
<li><a href="#return-types">Return Types</a><ul>
<li><a href="#returning-line-items-array-of-objects">Returning Line Items (Array of Objects)</a></li>
</ul>
</li>
<li><a href="#fallback-sample">Fallback Sample</a></li>
</ul>
</li>
Expand Down Expand Up @@ -474,7 +477,10 @@ <h2 id="table-of-contents">Table of Contents</h2>
</ul>
</li>
<li><a href="#triggerssearchescreates">Triggers/Searches/Creates</a><ul>
<li><a href="#return-types">Return Types</a></li>
<li><a href="#return-types">Return Types</a><ul>
<li><a href="#returning-line-items-array-of-objects">Returning Line Items (Array of Objects)</a></li>
</ul>
</li>
<li><a href="#fallback-sample">Fallback Sample</a></li>
</ul>
</li>
Expand Down Expand Up @@ -1853,7 +1859,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">
<p>Each of the 3 types of function expects a certain type of object. As of core v1.0.11, there are automated checks to let you know when you&apos;re trying to pass the wrong type back. For reference, each expects:</p>
<p>Each of the 3 types of function should return a certain data type for use by the platform. As of core v1.0.11, there are automated checks to let you know when you&apos;re trying to pass the wrong type back. For reference, each expects:</p>
</div>
<div class="col-md-7 col-sm-12 col-height is-empty docs-code">

Expand All @@ -1874,15 +1880,15 @@ <h3 id="return-types">Return Types</h3>
<tr>
<td>Trigger</td>
<td>Array</td>
<td>0 or more objects; passed to the <a href="https://zapier.com/developer/documentation/v2/deduplication/">deduper</a> if polling</td>
<td>0 or more objects; passed to the <a href="https://platform.zapier.com/docs/dedupe/">deduper</a> if polling</td>
</tr>
<tr>
<td>Search</td>
<td>Array</td>
<td>0 or more objects. Only the first object will be returned, so if len &gt; 1, put the best match first</td>
</tr>
<tr>
<td>Action</td>
<td>Create</td>
<td>Object</td>
<td>Return values are evaluated by <a href="https://lodash.com/docs#isPlainObject"><code>isPlainObject</code></a></td>
</tr>
Expand All @@ -1903,6 +1909,60 @@ <h3 id="return-types">Return Types</h3>
</div>
</div>
</div><div class="row">
<div class="row-height">
<div class="col-md-5 col-sm-12 col-height docs-primary">
<h4 id="returning-line-items-array-of-objects">Returning Line Items (Array of Objects)</h4>
</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>In some cases, you may want to include multiple items in the data you return for Searches or Creates. To do that, return the set of items as an array of objects under a descriptive key. This may be as part of another object (like items in an invoice) or as multiple top-level items.</p><p>For example, a Create Order action returning an order with multiple items might look like this:</p>
</div>
<div class="col-md-7 col-sm-12 col-height docs-code">
<pre><code>order = {
name: &apos;Zap Zaplar&apos;,
total_cost: 25.96,
items: [
{ name: &apos;Zapier T-Shirt&apos;, unit_price: 11.99, quantity: 3, line_amount: 35.97, category: &apos;shirts&apos; },
{ name: &apos;Orange Widget&apos;, unit_price: 7.99, quantity: 10, line_amount: 79.90, category: &apos;widgets&apos; },
{ name:&apos;Stuff&apos;, unit_price: 2.99, quantity: 7, line_amount: 20.93, category: &apos;stuff&apos; },
{ name: &apos;Allbird Shoes&apos;, unit_price: 2.99, quantity: 7, line_amount: 20.93, category: &apos;shoes&apos; },
],
zip: 01002
}
</code></pre>
</div>
</div>
</div><div class="row">
<div class="row-height">
<div class="col-md-5 col-sm-12 col-height docs-primary">
<p>While a Find Users search could return multiple items under an object key within an array, like this:</p>
</div>
<div class="col-md-7 col-sm-12 col-height docs-code">
<pre><code>result = [{
users: [
{ name: &apos;Zap Zaplar&apos;, age: 12, city: &apos;Columbia&apos;, region: &apos;Missouri&apos; },
{ name: &apos;Orange Crush&apos;, age: 28, city: &apos;West Ocean City&apos;, region: &apos;Maryland&apos; },
{ name: &apos;Lego Brick&apos;, age: 91, city: &apos;Billund&apos;, region: &apos;Denmark&apos; },
],
}];
</code></pre>
</div>
</div>
</div><div class="row">
<div class="row-height">
<div class="col-md-5 col-sm-12 col-height docs-primary">
<p>A standard search would return just the inner array of users, and only the first user would be provided as a final result. Returning line items instead means that the &quot;first result&quot; return is the object containing all the user details within it.</p><p>Using the standard approach is recommended, because not all Zapier integrations support line items directly, so users may need to take additional actions to reformat this data for use in their Zaps. More detail on that at <a href="https://zapier.com/help/create/basics/use-line-items-in-zaps">Use line items in Zaps</a>. However, there are use cases where returning multiple results is helpful enough to outweigh that additional effort.</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="fallback-sample">Fallback Sample</h3>
Expand Down
42 changes: 39 additions & 3 deletions packages/cli/README-source.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -529,16 +529,52 @@ You can find more details on the definition for each by looking at the [Trigger
> To add a trigger, search, or create to an existing integration, run `zapier scaffold [trigger|search|create] [noun]` to create the necessary files to your project. For example, `zapier scaffold trigger post` will create a new trigger called "New Post".
### Return Types

Each of the 3 types of function expects a certain type of object. As of core v1.0.11, there are automated checks to let you know when you're trying to pass the wrong type back. For reference, each expects:
Each of the 3 types of function should return a certain data type for use by the platform. There are automated checks to let you know when you're trying to pass the wrong type back. For reference, each expects:

| Method | Return Type | Notes |
|---------|-------------|----------------------------------------------------------------------------------------------------------------------|
| Trigger | Array | 0 or more objects; passed to the [deduper](https://zapier.com/developer/documentation/v2/deduplication/) if polling |
| Trigger | Array | 0 or more objects; passed to the [deduper](https://platform.zapier.com/docs/dedupe/) if polling |
| Search | Array | 0 or more objects. Only the first object will be returned, so if len > 1, put the best match first |
| Action | Object | Return values are evaluated by [`isPlainObject`](https://lodash.com/docs#isPlainObject) |
| Create | Object | Return values are evaluated by [`isPlainObject`](https://lodash.com/docs#isPlainObject) |
Comment on lines +536 to +538
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catches!


When a trigger function returns an empty array, the Zap will not trigger. For REST Hook triggers, this can be used to filter data if the available subscription options are not specific enough for the Zap's needs.

#### Returning Line Items (Array of Objects)

In some cases, you may want to include multiple items in the data you return for Searches or Creates. To do that, return the set of items as an array of objects under a descriptive key. This may be as part of another object (like items in an invoice) or as multiple top-level items.

For example, a Create Order action returning an order with multiple items might look like this:

```
order = {
name: 'Zap Zaplar',
total_cost: 25.96,
items: [
{ name: 'Zapier T-Shirt', unit_price: 11.99, quantity: 3, line_amount: 35.97, category: 'shirts' },
{ name: 'Orange Widget', unit_price: 7.99, quantity: 10, line_amount: 79.90, category: 'widgets' },
{ name:'Stuff', unit_price: 2.99, quantity: 7, line_amount: 20.93, category: 'stuff' },
{ name: 'Allbird Shoes', unit_price: 2.99, quantity: 7, line_amount: 20.93, category: 'shoes' },
],
zip: 01002
}
```

While a Find Users search could return multiple items under an object key within an array, like this:

```
result = [{
users: [
{ name: 'Zap Zaplar', age: 12, city: 'Columbia', region: 'Missouri' },
{ name: 'Orange Crush', age: 28, city: 'West Ocean City', region: 'Maryland' },
{ name: 'Lego Brick', age: 91, city: 'Billund', region: 'Denmark' },
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

    _ 
   [_] 
 /;   :\
()'---' C
  | | |
  [=|=]

],
}];
```

A standard search would return just the inner array of users, and only the first user would be provided as a final result. Returning line items instead means that the "first result" return is the object containing all the user details within it.

Using the standard approach is recommended, because not all Zapier integrations support line items directly, so users may need to take additional actions to reformat this data for use in their Zaps. More detail on that at [Use line items in Zaps](https://zapier.com/help/create/basics/use-line-items-in-zaps). However, there are use cases where returning multiple results is helpful enough to outweigh that additional effort.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like that link!


### Fallback Sample
In cases where Zapier needs to show an example record to the user, but we are unable to get a live example from the API, Zapier will fallback to this hard-coded sample. This should reflect the data structure of the Trigger's perform method, and have dummy values that we can show to any user.

Expand Down
43 changes: 40 additions & 3 deletions packages/cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ This doc describes the latest CLI version (**13.0.0**), as of this writing. If y
* [Resource Definition](#resource-definition)
- [Triggers/Searches/Creates](#triggerssearchescreates)
* [Return Types](#return-types)
+ [Returning Line Items (Array of Objects)](#returning-line-items-array-of-objects)
* [Fallback Sample](#fallback-sample)
- [Input Fields](#input-fields)
* [Custom/Dynamic Fields](#customdynamic-fields)
Expand Down Expand Up @@ -1021,16 +1022,52 @@ You can find more details on the definition for each by looking at the [Trigger
> To add a trigger, search, or create to an existing integration, run `zapier scaffold [trigger|search|create] [noun]` to create the necessary files to your project. For example, `zapier scaffold trigger post` will create a new trigger called "New Post".
### Return Types

Each of the 3 types of function expects a certain type of object. As of core v1.0.11, there are automated checks to let you know when you're trying to pass the wrong type back. For reference, each expects:
Each of the 3 types of function should return a certain data type for use by the platform. As of core v1.0.11, there are automated checks to let you know when you're trying to pass the wrong type back. For reference, each expects:

| Method | Return Type | Notes |
|---------|-------------|----------------------------------------------------------------------------------------------------------------------|
| Trigger | Array | 0 or more objects; passed to the [deduper](https://zapier.com/developer/documentation/v2/deduplication/) if polling |
| Trigger | Array | 0 or more objects; passed to the [deduper](https://platform.zapier.com/docs/dedupe/) if polling |
| Search | Array | 0 or more objects. Only the first object will be returned, so if len > 1, put the best match first |
| Action | Object | Return values are evaluated by [`isPlainObject`](https://lodash.com/docs#isPlainObject) |
| Create | Object | Return values are evaluated by [`isPlainObject`](https://lodash.com/docs#isPlainObject) |

When a trigger function returns an empty array, the Zap will not trigger. For REST Hook triggers, this can be used to filter data if the available subscription options are not specific enough for the Zap's needs.

#### Returning Line Items (Array of Objects)

In some cases, you may want to include multiple items in the data you return for Searches or Creates. To do that, return the set of items as an array of objects under a descriptive key. This may be as part of another object (like items in an invoice) or as multiple top-level items.

For example, a Create Order action returning an order with multiple items might look like this:

```
order = {
name: 'Zap Zaplar',
total_cost: 25.96,
items: [
{ name: 'Zapier T-Shirt', unit_price: 11.99, quantity: 3, line_amount: 35.97, category: 'shirts' },
{ name: 'Orange Widget', unit_price: 7.99, quantity: 10, line_amount: 79.90, category: 'widgets' },
{ name:'Stuff', unit_price: 2.99, quantity: 7, line_amount: 20.93, category: 'stuff' },
{ name: 'Allbird Shoes', unit_price: 2.99, quantity: 7, line_amount: 20.93, category: 'shoes' },
],
zip: 01002
}
```

While a Find Users search could return multiple items under an object key within an array, like this:

```
result = [{
users: [
{ name: 'Zap Zaplar', age: 12, city: 'Columbia', region: 'Missouri' },
{ name: 'Orange Crush', age: 28, city: 'West Ocean City', region: 'Maryland' },
{ name: 'Lego Brick', age: 91, city: 'Billund', region: 'Denmark' },
],
}];
```

A standard search would return just the inner array of users, and only the first user would be provided as a final result. Returning line items instead means that the "first result" return is the object containing all the user details within it.

Using the standard approach is recommended, because not all Zapier integrations support line items directly, so users may need to take additional actions to reformat this data for use in their Zaps. More detail on that at [Use line items in Zaps](https://zapier.com/help/create/basics/use-line-items-in-zaps). However, there are use cases where returning multiple results is helpful enough to outweigh that additional effort.

### Fallback Sample
In cases where Zapier needs to show an example record to the user, but we are unable to get a live example from the API, Zapier will fallback to this hard-coded sample. This should reflect the data structure of the Trigger's perform method, and have dummy values that we can show to any user.

Expand Down
Loading