# Datasource Excerpts > Create and edit datasource excerpts, the sample JSON that fills the template editor's merge field and merge block lists and its preview, and learn their format. - **Product:** ReportingCloud - **Section:** Documentation - **Kind:** Topic - **Path:** ReportingCloud > Portal > Datasource Excerpts - **1417 words** - **Web URL:** https://docs.textcontrol.com/reporting-cloud/portal/datasource-excerpts/ - **LLMs URL:** https://docs.textcontrol.com/reporting-cloud/portal/datasource-excerpts/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/reporting-cloud/portal/datasource-excerpts/llms-full.txt --- Which merge fields can a template use, and what will the merged document look like? The template editor answers both questions from a datasource excerpt: a small sample of your JSON data that you keep in the ReportingCloud portal. The excerpt fills the editor's lists of fields and blocks with the names your data uses, and it provides the values for the preview. Read on to understand what an excerpt is and to create, edit and structure one on the **My Datasource Excerpts** page. ### What a Datasource Excerpt Is An excerpt is a JSON file in the portal that describes your data to the [template editor](https://docs.textcontrol.com/reporting-cloud/portal/template-editor/llms-full.txt): - **It names the fields and blocks.** The editor reads the excerpt and lists its tables and fields in the **Merge Field** and **Merge Block** drop-downs, so the names in the template match the names in your data. - **It provides the preview data.** **Preview Merge Results** merges the template with the values of the excerpt. - **It is not your merge data.** The Web API never reads an excerpt: your application sends the real data with each merge request, as [Merge Data](https://docs.textcontrol.com/reporting-cloud/mail-merge/data-sources/llms-full.txt) describes. There are no endpoints for excerpts; they exist only in the portal. Because the editor only needs the structure, an excerpt holds a record or two with made-up values and a few items in each array, not your production data. ### The Format An excerpt has the format of the merge data that [POST /v1/document/merge](https://docs.textcontrol.com/reporting-cloud/reference/web-api/document/merge/post/llms-full.txt) accepts: a JSON array of objects, one object per record. The editor turns the structure into tables: | In the JSON | In the editor | |---|---| | A property with a value at the top level of a record | A field of the table **master** | | An array of objects | A table named like the property, which you insert as a merge block | | A nested object | A table named like the property, with the object's properties as fields | | A Base64 string | Image data that an image placeholder can be bound to | This excerpt is a shortened version of the data for the demo template `sample_invoice.tx`: ```json [ { "yourcompany_companyname": "Text Control, LLC", "invoice_no": "778723", "billto_name": "Joey Montana", "item": [ { "qty": "1", "item_description": "Item description 1", "item_total": "2130.40" }, { "qty": "1", "item_description": "Item description 2", "item_total": "5543" } ], "total": "8210.538" } ] ``` In the editor, **master** has the fields `yourcompany_companyname`, `invoice_no`, `billto_name` and `total`, and the table **item** has `qty`, `item_description` and `item_total`, which you insert as a merge block for the invoice lines. The preview repeats the block twice. The array around the records is required, even for one record. When you copy a single serialized object, enclose it in square brackets. [Merge Data](https://docs.textcontrol.com/reporting-cloud/mail-merge/data-sources/llms-full.txt) describes the format in detail, and [Images](https://docs.textcontrol.com/reporting-cloud/mail-merge/images/llms-full.txt) shows an excerpt with image data. ### Create an Excerpt 1. Click **My Datasource Excerpts** in the side menu. 2. In the **New Datasource Excerpt File** box, enter a **Name**, such as *invoice\_data*. 3. Paste the JSON into **Datasource Excerpt**. Below the box, the portal checks the JSON and shows "JSON object is valid" when it can be parsed. 4. Click **Create Excerpt**. The portal stores the excerpt as a file with the extension *.json*, *invoice\_data.json* in this example. Under this name, it appears in the **Select datasource excerpt file:** list when you open a template in the editor. ### Edit an Excerpt When your data gets new fields, change the excerpt, so that the editor offers them. **My Datasource Excerpts** lists your excerpts under **All Datasource Excerpt Files**, each with **Edit** and **Delete**. **Edit** opens the **Edit Datasource Excerpt** page: ![Edit Datasource Excerpt page with the sample JSON data](https://docs.textcontrol.com/assets/img/reporting-cloud/portal-datasource-excerpt.3ceffe42.webp) - **Name** is the name of the excerpt, *sample\_data* in the screenshot, whose data belongs to the demo template `sample_invoice.tx`. - **Datasource Excerpt** is a code editor with line numbers, syntax highlighting and error checking. The arrows beside the line numbers fold and unfold objects and arrays, which helps with long excerpts. - **Save Excerpt** stores the changes, and **Cancel** discards them. The editor loads an excerpt when you click **Edit Template**. A template that is open in the editor gets the new fields when you open it again with the changed excerpt. ### Make an Excerpt From Your Own Data The most reliable excerpt is the JSON your application will send, cut down to a sample: 1. Serialize the objects that your application merges, the same way it will serialize them for the Web API, for example with a JSON serializer in .NET. 2. Keep one or two records and two or three items in each array. Replace confidential values with sample values. 3. Make sure that the result is an array, and create the excerpt from it. [Template Design](https://docs.textcontrol.com/reporting-cloud/mail-merge/template-design/llms-full.txt) walks through this with .NET classes for an invoice, and [Nested Blocks](https://docs.textcontrol.com/reporting-cloud/mail-merge/nested-blocks/llms-full.txt) does it for a sales report with blocks inside blocks. Templates that you add from the [Sample Template Gallery](https://docs.textcontrol.com/reporting-cloud/portal/templates/#add-templates-from-the-sample-template-gallery) bring an excerpt of their own, linked to the template. ### Next Steps - [Template Editor](https://docs.textcontrol.com/reporting-cloud/portal/template-editor/llms-full.txt): open a template with an excerpt and insert fields and blocks. - [Merge Data](https://docs.textcontrol.com/reporting-cloud/mail-merge/data-sources/llms-full.txt): the JSON format of the data your application merges. - [Template Design](https://docs.textcontrol.com/reporting-cloud/mail-merge/template-design/llms-full.txt): from .NET classes to an excerpt and an invoice template. --- ## Nearby - **Previous:** [Template Editor](https://docs.textcontrol.com/reporting-cloud/portal/template-editor/llms-full.txt) - **Next:** [Manage Account](https://docs.textcontrol.com/reporting-cloud/portal/account/llms-full.txt)