contensis-cli 1.2.0 → 1.2.1-beta.0

package/README.md

@@ -11,7 +11,7 @@ or use your preferred installation method below
 ### Windows ([Chocolatey](https://chocolatey.org/install))
 
 ```shell
-choco install contensis-cli --pre
+choco install contensis-cli
 ```
 
 - [Choco package docs and source](https://github.com/contensis/cli/tree/main/installers/chocolatey)
@@ -242,6 +242,7 @@ contensis >
   - [Get an entry with all of its dependents](#get-an-entry-with-all-of-its-dependents)
   - [Get entries with a ZenQL statement](#get-entries-with-a-zenql-statement)
   - [Choose entry fields to output](#choose-entry-fields-to-output)
+  - [Get entries using the Delivery API](#get-entries-using-the-delivery-api)
   - [Output results to a file](#output-results-to-a-file)
 - [Format output](#format-output)
 - [Manage API keys](#manage-api-keys)
@@ -254,7 +255,7 @@ contensis >
   - [Set role details](#set-role-details)
   - [Disable role](#disable-role)
   - [Remove role](#remove-role)
-- [Manage content Blocks](#manage-content-blocks)
+- [Manage blocks](#manage-blocks)
   - [List blocks](#list-blocks)
   - [Get block](#get-block)
   - [Get block logs](#get-block-logs)
@@ -277,6 +278,12 @@ contensis >
   - [Import from a file](#import-from-a-file-1)
   - [Import entries further reading](#import-entries-further-reading)
 - [Remove entries](#remove-entries)
+- [Copy an entry field](#copy-an-entry-field)
+  - [Copy a simple entry field](#copy-a-simple-entry-field)
+  - [Limit entries when copying field content](#limit-entries-when-copying-field-content)
+  - [Copy a composer into a canvas field](#copy-a-composer-into-a-canvas-field)
+  - [Copy a field using a template](#copy-a-field-using-a-template)
+  - [Copy a field and save the entries as output](#copy-a-field-and-save-the-entries-as-output)
 
 ## Get started
 
@@ -706,7 +713,7 @@ Use a ZenQL statement to find entries with the `--zenql` or `-q` option, add you
 website t.durden@example-dev> get entries --zenql "sys.contentTypeId = plant"
   -------------------------------------
 [24/07 01:52:37] [INFO] Fetching initial entries in project 'website'
- Fetch [website]                                      >> 100% 21 0.0s/0.0s Infinityp/s
+ Fetch [website]                                      >> 100% 21 0.0s/0.0s
 
 Found 21 entries in [website]
 --------------------------------------------
@@ -771,6 +778,16 @@ Found 12 entries in [website]
 website t.durden@example-dev>
 ```
 
+### Get entries using the Delivery API
+
+By default all Contensis operations are performed using the Management API. Some data fields are only available to output when searching the Delivery API e.g. `sys.uri`
+
+To include the `sys.uri` field with the entries returned from the above example, as well as adding the `sys.uri` field to the `--fields` list, we would also include the `--delivery-api` option in the `get entries` command.
+
+```shell
+website t.durden@example-dev> get entries --delivery-api --fields sys.uri productName colour material externalPromotion --zenql "sys.contentTypeId = pot"
+```
+
 ### Output results to a file
 
 Use the `--output` or `-o` option followed by the file name you wish for command output to be written to
@@ -784,10 +801,10 @@ website t.durden@example-dev> get entries --zenql "sys.contentTypeId = pot" --ou
 website t.durden@example-dev>
 ```
 
-Combine other options and mobilise your data to consume elsewhere
+Combine other options and mobilise your data to consume elsewhere: this command will dump an entry and all of its dependents (at all link depths) to a json file creating a complete picture of the entry data and everything that is linked to it.
 
 ```shell
-get entries -d -o aloe-complete-entry.json -id 7cf921a0-ee4f-4bd6-a3f2-0fb0fe1a2ac8
+get entries --dependents --output aloe-complete-entry.json --id 7cf921a0-ee4f-4bd6-a3f2-0fb0fe1a2ac8
   -------------------------------------
 [24/07 02:16:04] [INFO] Fetching initial entries in project 'website'
  Fetch [website]                         >> 100% 1 0.0s/0.0s 100000p/s
@@ -1103,9 +1120,9 @@ website t.durden@example-dev> get webhook "Slack"
 website t.durden@example-dev>
 ```
 
-## Manage content Blocks
+## Manage blocks
 
-You can manage blocks for any Contensis project using the following commands
+You can manage deployed blocks for any Contensis project using the following commands
 
 ### List blocks
 
@@ -1229,7 +1246,7 @@ website t.durden@example-dev> execute block action release contensis-website 78
 [cli] ✅ [example-dev] Action release on contensis-website in project website requested successfully
   v78 contensis-website
     state: available
-    released: [23/11/2022 01:42] n.flatley
+    released: [23/11/2022 01:42] t.durden
     status:
       deployment: deployed
       workflow: released
@@ -1697,3 +1714,147 @@ website t.durden@example-dev>
 ```
 
 <sup><sub>Add the `--commit` option to make the changes, be very careful using this! There is no going back</sub></sup>
+
+## Copy an entry field
+
+This command allows us to copy the contents of one entry field to another, this is useful if, for example - when a field is named incorrectly, or was specified originally as one field type but we would like to curate and present this content differently in future.
+
+The required inputs for using `copy field` are:
+
+- `contentTypeId`: the content type containing the field to copy
+- `fieldId`: the field id containing the source data
+- `destinationId`: the target field id where the data will be copied to
+
+Copying field data from one field to another can only be done with fields that exist in the content type, and with the source and destination field types are metioned in the [transformation matrix](docs/copy_field_transformation_matrix.md)
+
+Similar to the `import` commands, the `copy` command is safe to run again and again for testing and reviewing the output. The changes are made to the entries permanently when the `--commit` option is added.
+
+### Copy a simple entry field
+
+To copy the contents of one field to another use the command like this:
+
+```
+copy field <contentTypeId> <fieldId> <destinationId>
+```
+
+For the next example, we will copy the contents of a field called `text` into another field called `heading`, in the `contentPage` content type
+
+```shell
+website t.durden@example-dev> copy field contentPage text heading
+  -------------------------------------
+ -- IMPORT PREVIEW --
+[07/05 16:21:40] [INFO] OK to copy contentPage[text]<string> field into contentPage[heading]<string> in website on example-dev [direct]
+[07/05 16:21:40] [INFO] Searching for initial entries in example-dev project 'website'
+[07/05 16:21:40] [INFO] Finding 2 entries in example-dev project 'website'
+[07/05 16:21:45] [INFO] Building 2 content entries
+
+2/2 entries to migrate into [website]
+
+ contentTypeId         status     total
+----------------------------------------------
+ contentPage    update     2
+----------------------------------------------
+
+ id                                    contentTypeId         status    updates  entryTitle
+--------------------------------------------------------------------------------------------------------------
+ 21818721-f03e-4e8a-9982-c83212409850  contentPage    update    -1,+1    Content page
+ 70fa7283-cdba-462d-8cd3-a1d4b30ac2e7  contentPage    update    -0,+1    Test field data
+--------------------------------------------------------------------------------------------------------------
+
+[07/05 16:21:45] [OK] Entries migration preview ready
+
+[cli] ⏩ import from project website to website
+
+  - contentPage: 2 [existing: 100%] [needs update: 100%]
+  - totalCount: 2
+
+[cli] ✅ [example-dev] Will import 2 entries
+
+[cli] ⏩ Add --commit flag to commit the previewed changes
+
+website t.durden@example-dev>
+```
+
+We can request more output for our preview by adding `--output-entries changes` option and we will see a diff of the entries that have updates applied to them.
+
+### Limit entries when copying field content
+
+If the number of entries to copy in a content type are too large to manage, or if we are testing the `copy field` command with a subset of entries we can supply one of the following options to limit the entries that are returned when we run the `copy field` command.
+
+- `--id`: copy the field contents of one entry only
+- `--zenql`: provides the finest level of control over the returned entries
+- `--search`: limits the results with a simple keyword or phrase
+
+Consult the command `copy field --help` to see all of the available options
+
+### Copy a composer into a canvas field
+
+, in order to transform the contents of a Composer field in an entry to a canvas field type, we achieve this by rendering each item in the Composer as simple HTML representation internally before parsing this markup and converting it to canvas then adding the output to our destination entry field, working in the same way as if we were copying the contents of a rich text field type (containing markup) to a canvas field.
+
+```shell
+contensis t.durden@example-dev> copy field contentPage composer canvas --output-entries changes        
+  -------------------------------------
+ -- IMPORT PREVIEW -- 
+[07/05 17:02:51] [INFO] OK to copy contentPage[composer]<objectArray> field into contentPage[canvas]<objectArray> in website on example-dev [canvas]
+[07/05 17:02:51] [INFO] Searching for initial entries in example-dev project 'website'
+[07/05 17:02:53] [INFO] Finding 1 entries in example-dev project 'website'
+[07/05 17:02:56] [INFO] Building 1 content entries
+
+1/1 entries to migrate into [website]
+
+ contentTypeId         status     total  
+----------------------------------------------
+ contentPage    update     1
+----------------------------------------------
+
+ id                                    contentTypeId         status    updates  entryTitle
+--------------------------------------------------------------------------------------------------------------
+ 401abeba-d47d-4975-8890-db4b07ad58c4  contentPage    update    -1,+1    Content page
+--------------------------------------------------------------------------------------------------------------
+
+[07/05 17:02:56] [OK] Entries migration preview ready
+
+update 401abeba-d47d-4975-8890-db4b07ad58c4 contentPage Content page
+  diff: '{'canvas':[{'id':'<->9fef6713','type':'_paragraph'}],'</-><+>c2c69573','type':'_paragraph','value':[{'id':'2edb9251','type':'_fragment','value':'This is the page content curated in a '},{'id':'fc28bf06','properties':{'decorators':['code']},'type':'_fragment','value':'markup'},{'id':'b67233b7','type':'_fragment','value':' composer item'}]},{'id':'f13ced2f','type':'_image','value':{'asset':{'sys':{'availableLanguages':['en-GB'],'id':'e7ee357f-35b1-4315-be7a-3d0cc2ff661b','isPublished':true,'language':'en-GB','metadata':{'includeInAToZ':false,'includeInMenu':false,'includeInSearch':true,'includeInSiteMap':false,'nodeId':'e7ee357f-35b1-4315-be7a-3d0cc2ff661b'},'owner':'d.mee','projectId':'contensis','properties':{'fileId':'e7ee357f-35b1-4315-be7a-3d0cc2ff661b','filename':'swiss-army-knife-blog-image1.jpeg','filePath':'/image-library/blog-images/','fileSize':48731,'height':512,'width':357},'version':{'created':'2021-09-24T10:56:10.8000819Z','createdBy':'ServicesUser','modified':'2021-09-24T10:56:10.8000819Z','modifiedBy':'ServicesUser','published':'2021-10-04T10:05:45.9434807Z','publishedBy':'ServicesUser','versionNo':'1.0'},'versionStatus':'latest','workflow':{'id':'contensisEntryBasic','state':'versionComplete'}},'title':'Swiss Army Knife - Blog image1'}}},{'id':'867aebcd','type':'_paragraph','value':'This line was curated as plain text'},{'id':'f9e378c8','properties':{'component':'iconWithText'},'type':'_component','value':{'icon':{'sys':{'id':'7d62ee24-b36a-46c3-b49f-09b32575dfbd','language':'en-GB'}},'text':'Some text curated in a component along with my icon'}}],'</+>composer':[{'type':'markup','value':'<p>This is the page content curated in a <code>markup</code> composer item</p>'},{'type':'image','value':{'altText':'An inline image in my content page','asset':{'sys':{'id':'e7ee357f-35b1-4315-be7a-3d0cc2ff661b'}}}},{'type':'text','value':'This line was curated as plain text'},{'type':'iconWithText','value':{'icon':{'sys':{'id':'7d62ee24-b36a-46c3-b49f-09b32575dfbd'}},'text':'Some text curated in a component along with my icon'}}],'heading':'This is my content heading','text':'Content page'}
+
+[cli] ⏩ import from project website to website
+
+  - contentPage: 1 [existing: 100%] [needs update: 100%]
+  - totalCount: 1
+
+[cli] ✅ [example-dev] Will import 1 entries
+
+[cli] ⏩ Add --commit flag to commit the previewed changes
+
+website t.durden@example-dev>
+```
+
+### Copy a field using a template
+
+For fine-grained control of what is rendered or copied into the target field we can supply a `--template` option with a string value that is a [LiquidJS](https://liquidjs.com/tutorials/intro-to-liquid.html) template with access to variables we can use to directly drive how the output is written into our target field
+
+The syntax for applying a template with the `copy field` command is 
+```shell
+copy field blog description kicker --template "<h2>{{ value }}</h2>"
+```
+in this example the `value` from `description` field will be wrapped in a `<h2>` tag before being added to the `kicker` field
+
+The template must be surrounded in double-quotes and be entered (or pasted) in a single line for it to be parsed correctly with the intended command.
+
+Adding a template containing html? Attributes can be wrapped in single quotes.
+
+Escape characters and new lines can be introduced inside templates when calling `contensis copy field` from your system shell as a cli command. This is OS/shell dependent and does not work in the Contensis shell (due to the combined layers of command parsing)
+
+Further documentation on using [templates](docs/copy_field_templates.md)
+
+### Copy a field and save the entries as output
+
+As we do not actually commit the output of a `copy field` command until specified we can also save the entries preview containing the new field data.
+
+With the saved output we can examine the raw output of each entry containing the copied field data before we choose to load it, or we can repurpose the saved entries output for further processing.
+
+Add the `--save-entries` option to the `copy field` command, remember to also include the `--output copy-entries.json` option, specifying the file where the output will be saved.
+
+```shell
+copy field contentPage composer canvas --save-entries --output canvas-entries.json
+```

package/dist/version.js

@@ -21,7 +21,7 @@ __export(version_exports, {
   LIB_VERSION: () => LIB_VERSION
 });
 module.exports = __toCommonJS(version_exports);
-const LIB_VERSION = "1.2.0";
+const LIB_VERSION = "1.2.1-beta.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LIB_VERSION

package/dist/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/version.ts"],
-  "sourcesContent": ["export const LIB_VERSION = \"1.2.0\";\n"],
+  "sourcesContent": ["export const LIB_VERSION = \"1.2.1-beta.0\";\n"],
   "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,MAAM,cAAc;",
   "names": []
 }

package/docs/copy_field_templates.md

@@ -0,0 +1,354 @@
+## Apply a template
+
+If your field type is not supported in the [copy field transformation matrix](copy_field_transformation_matrix.md), or you wish to modify the output value for the field we can supply a [LiquidJS](https://liquidjs.com/tutorials/intro-to-liquid.html) template where we can make use of "tags" and "filters" available in LiquidJS to perform custom transformations on our entry field data
+
+The result after parsing this template will become the new value for the destination field for every entry
+
+Templates allow us to to make some very precise adjustments to the field value we will update
+
+A number of variables are available to use in the liquid template
+
+- `value` - the value of the source field in the entry
+- `existing_value` - any existing value of the target field in the entry
+- `target_value` - the value that has been prepared to go into the destination field
+- `entry` - the entire entry object (if we need to reference another field in the entry)
+- `field` - the content type configuration of the source field
+- `target_field` - the content type configuration of the target field
+
+### Examples
+
+These are simple examples of using and chaining [LiquidJS filters](https://liquidjs.com/filters/overview.html)
+
+- `"{{ value | capitalize }}"` will capitalise the first letter of the value
+- `"{{ value | downcase }}"` will lowercase the entire value
+- `"{{ value | downcase | capitalize }}"` will lowercase the entire value then capitalise the first letter
+- `"{{ value >= 50 }}"` using logic based on a source field value we can set a boolean to true or false
+
+Use of [LiquidJS tags](https://liquidjs.com/tags/overview.html) is also available for more complex scenarios
+
+### Apply the template before any field transformation
+
+Templates are parsed and rendered after field transformations have taken place and the resulting value is set on the entry as our new field's value.
+
+A special variable is available called `source_value` (which is the same as `value`) except when used, the template is parsed and rendered *prior* to any field transformations taking place. 
+
+The result of this template when parsed will override the source field's value from each entry and this will be transformed again to the target field's type before the resulting value is set on the entry as our target field's value.
+
+This is necessary if you wish to alter the source field value prior to any internal transformations (e.g. before we convert the value to a canvas field).
+
+Using `source_value` means `target_value` and `value` variables are not available.
+
+#### Examples
+
+- `"<h1>{{ source_value }}</h1>"` allows us to surround our `source_value` with some text before it is converted into the destination field type (e.g. canvas)
+- `"{{ source_value | remove: ".aspx" }}"` will remove any instance of `.aspx` from our source value
+
+### Transform Composer content with a template
+
+Because of the near infinite flexibility provided by Composer field configurations, in order to transform parts of, or the entire contents of a Composer field in an entry to another field type (except canvas which is now supported by default), we can do this by writing our own template to configure how each item in the Composer is to be "rendered" before adding the transformation result to our destination entry field.
+
+#### Examples
+
+If we have the following Composer content in JSON containing a number of different data types or "Composer items":
+
+```JSON
+[
+  {
+    "type": "text",
+    "value": "This is my plain text"
+  },
+  {
+    "type": "markup",
+    "value": "<p>This is rich <em>text</em> with some <strong>styling</strong></p>"
+  },
+  {
+    "type": "quote",
+    "value": {
+      "source": "This is the source",
+      "text": "This is a quote"
+    }
+  },
+  {
+    "type": "number",
+    "value": 123456789
+  },
+  {
+    "type": "boolean",
+    "value": false
+  },
+  {
+    "type": "location",
+    "value": {
+      "lat": 51.584151,
+      "lon": -2.997664
+    }
+  },
+  {
+    "type": "list",
+    "value": [
+      "Plum",
+      "Orange",
+      "Banana"
+    ]
+  },
+  {
+    "type": "iconWithText",
+    "value": {
+      "icon": {
+        "sys": {
+          "id": "51639de0-a1e4-4352-b166-17f86e3558bf"
+        }
+      },
+      "text": "This is my icon text"
+    }
+  },
+  {
+    "type": "asset",
+    "value": {
+      "sys": {
+        "id": "e798df96-1de3-4b08-a270-3787b902a580"
+      }
+    }
+  },
+  {
+    "type": "image",
+    "value": {
+      "altText": "A photo of Richard Saunders.",
+      "asset": {
+        "sys": {
+          "id": "bc6435eb-c2e3-4cef-801f-b6061f9cdad6"
+        }
+      }
+    }
+  }
+]
+```
+
+We could supply a template to pull out specific item types into our destination field
+
+The example below will take the list field above and allow the content to be copied into any string type field
+
+```handlebars
+{% # use a "for" tag to iterate over our "value" variable (composer field) %}
+{% for c_item in value %}
+  {% # use an "if" tag to match a composer item type of list in the composer array %}
+  {% if c_item.type == 'list' %}
+    {% # render any list from the composer field, use a "join" filter to convert the value array to a string %}
+    {{ c_item.value | join: ', ' }}
+  {% # close the "if" tag %}
+  {% endif %}
+{% # close the "for" tag %}
+{% endfor %}
+```
+
+A short hand example similar to the above using only LiquidJS filters
+
+Taking the `value` (a composer item array), filtering just the composer item types of 'list', mapping just the 'value' taking the `first` found 'list' and concatenating the values into a comma-separated string.
+
+```handlebars
+{{ value | where: 'type', 'list' | map: 'value' | first | join: ', '  }}
+```
+
+So a composer field containing this JSON
+
+```JSON
+  [{
+    "type": "list",
+    "value": [
+      "Plum",
+      "Orange",
+      "Banana"
+    ]
+  }]
+```
+
+becomes `Plum, Orange, Banana`
+
+Or render the same list field data ready to copy into a Rich text or Canvas field, we are free to decorate any value with required markup so it is presented and transformed correctly.
+
+```handlebars
+{% for c_item in source_value %} {% if c_item.type == 'list' %}
+<ul>
+  {% for l_item in c_item.value %}
+  <li>{{l_item}}</li>
+  {% endfor %}
+</ul>
+{% endif %} {% endfor %}
+```
+
+### Transforming Composer content to Canvas
+
+To transform the above Composer content into a Canvas field, we would need to "render" each item in the Composer that we require in the Canvas field as a very simple HTML representation, and this becomes the value we pass to the HTML parser that in turn renders the JSON that allows us to store the Canvas content in Contensis.
+
+The same kind of theory can be applied to any source field we wish to convert to Canvas content
+
+We must use the `source_value` variable in the template instead of `value` variable as the template needs to alter the source value and be applied _before_ the process transforms the value into Canvas
+
+If the source field (or composer item value) is already a rich text field containing existing markup, we don't need to do any special rendering before this is parsed and converted to Canvas content
+
+```handlebars
+{% for c_item in source_value %}
+  {% if c_item.type == 'markup' %}{{ c_item.value }}
+  {% elsif c_item.type == 'quote' %}
+    <p>{{ c_item.value.source }}</p>
+    <blockquote>{{ c_item.value.text }}</blockquote>
+  {% elsif c_item.type == 'image' %}
+    <img src='{{ c_item.value.asset.sys.uri }}' alt='{{ c_item.value.altText }}'/>
+  {% else %}<p>{{ c_item.value | join: '</p><p>' | json }}</p>
+  {% endif %}
+{% endfor %}
+```
+
+### Embedding Component data in Canvas
+
+We can curate and store Component data inline with Canvas content in the Contensis editor.
+
+Component data will likely be encountered as part of a parent composer field when converting long-form composer-curated content to Canvas.
+
+Following on from the examples above, we have a component in the composer data of type `iconWithText`. We need to also know the api id of the component (which can be found in the composer field definition in the Content type editor), as the component api id is often different from how it is named in the composer field.
+
+```handlebars
+{% for c_item in source_value %}
+  {% # ... %}
+  {% elsif c_item.type == 'iconWithText' %}
+    {{ c_item.value | canvas_component: 'iconWithText' }}
+  {% # ... %}
+  {% endif %}
+{% endfor %}
+```
+
+In the above template when we encounter a composer item with a type of `iconWithText` we can render it and apply the custom filter `canvas_component` to the composer item value, supplying the component api id as an argument to this filter
+
+Rendering the component with the custom filter will produce an output that will allow the component (and its content) to be parsed and stored inline in Canvas field content:
+
+```
+<div class='component' data-component='iconWithText' data-component-value='{&quot;icon&quot;:{&quot;sys&quot;:{&quot;id&quot;:&quot;51639de0-a1e4-4352-b166-17f86e3558bf&quot;,&quot;dataFormat&quot;:&quot;entry&quot;,&quot;contentTypeId&quot;:&quot;icon&quot;}},&quot;text&quot;:&quot;This is my icon text&quot;}'></div>
+```
+
+#### Further component customisation
+
+If you need to customise the component output for the canvas content any further, you can instead not use the suggested custom filter and render the component data as markup following the example output above.
+
+```handlebars
+{% for c_item in source_value %}
+  {% # ... %}
+  {% elsif c_item.type == 'iconWithText' %}
+<div class='component' data-component='iconWithText' data-component-value='{{ c_item.value | html_encode }}'></div>
+  {% # ... %}
+  {% endif %}
+{% endfor %}
+```
+
+Another custom filter `html_encode` used here is provided to help render the `data-component-value` attribute with the correct encoding to be parsed and embedded into the canvas content
+
+#### Curate redundant components as canvas
+
+If it is preferred for any reason, instead of embedding component data inline in the canvas content, you could stop using the component field and have the content curated, stored and rendered from regular canvas content blocks going forward.
+
+You would use a template to render the data from each component field wrapped in simple appropriate markup so it will be represented like this within canvas content blocks in Contensis after the field data has been copied and converted to canvas.
+
+### Embedding Entry (and asset) links in Canvas
+
+Continuing the example above, we can embed an inline entry link from every matched composer item easily into the canvas content by applying custom filter `canvas_entry`
+
+```handlebars
+{% for c_item in source_value %}
+  {% # ... %}
+  {% elsif c_item.type == 'entry' %}
+    {{ c_item.value | canvas_entry }}
+  {% # ... %}
+  {% endif %}
+{% endfor %}
+```
+
+Produces output similar to the HTML below which can be parsed and saved inside the canvas content
+
+```
+<a class='inline-entry' data-entry='{&quot;sys&quot;:{&quot;id&quot;:&quot;eee9129e-70fc-4f70-b641-01e160af2438&quot;,&quot;dataFormat&quot;:&quot;entry&quot;,&quot;contentTypeId&quot;:&quot;person&quot;}}'></a>
+```
+
+Another example of embedding an entry link into canvas where we could be converting existing rich text content to canvas and need to link/append a certain entry at the bottom of every entry's canvas content.
+
+```handlebars
+{{ source_value }}
+{{ entry.tsAndCs | canvas_entry }}
+```
+
+If we need to hard code a specific entry id into the canvas after a rich text field:
+
+```handlebars
+{{ source_value }}
+{% capture link_entry %}
+{ "sys": { "id": "eee9129e-70fc-4f70-b641-01e160af2438", "contentTypeId": "person" } }
+{% endcapture %}
+{{ link_entry | from_json | canvas_entry }}
+```
+
+In the final output we are applying two custom filters to our `link_entry`, `from_json` allows us to use a `capture` tag and hardcode our own json, then parse this as a json object that can be read normally within the template (something which cannot be done natively in LiquidJS).
+
+Further applying `canvas_entry` filter will convert our parsed JSON object into the markup that is valid for loading with canvas content
+
+```handlebars
+{{ source_value }}
+{{ '{ "sys": { "id": "eee9129e-70fc-4f70-b641-01e160af2438", "contentTypeId": "person" } }' | from_json | canvas_entry }}
+```
+
+We can achieve the same effect by applying the filter chain to a hardcoded valid JSON string
+
+### Embedding Images in Canvas
+
+Continuing with the composer example above, we can embed an existing image into the canvas content by applying custom filter `canvas_image`
+
+We also need to ensure we have supplied the option to query the delivery api, as entries returned in the management api search do not contain the image uri in any image fields as the delivery api does.
+
+```handlebars
+{% for c_item in source_value %}
+  {% # ... %}
+  {% elsif c_item.type == 'image' %}
+    {{ c_item.value | canvas_image }}
+  {% # ... %}
+  {% endif %}
+{% endfor %}
+```
+
+Produces output similar to the HTML below which can be parsed and saved inside the canvas content
+
+```
+<img src='/image-library/people-images/richard-saunders-blog-image.x67b5a698.png' altText='A photo of Richard Saunders.'/>
+```
+
+Images from existing, external or hardcoded content can be added to the canvas by rendering the image details out into valid markup including an `<img />` tag with a completed `src=""` attribute
+
+### Complete composer example
+
+
+```handlebars
+{% for c_item in source_value %}
+  {% if c_item.type == 'markup' %}{{ c_item.value }}
+  {% elsif c_item.type == 'quote' %}
+    <p>{{ c_item.value.source }}</p>
+    <blockquote>{{ c_item.value.text }}</blockquote>
+  {% elsif c_item.type == 'iconWithText' %}{{ c_item.value | canvas_component: 'iconWithText' }}
+  {% elsif c_item.type == 'image' %}{{ c_item.value | canvas_image }}
+  {% elsif c_item.type == 'asset' or c_item.type == 'entry' %}{{ c_item.value | canvas_entry }}
+  {% elsif c_item.type == 'boolean' and c_item.value %}Boolean: Yes
+  {% else %}<p>{{ c_item.value | join: '</p><p>' | json }}</p>
+  {% endif %}
+{% endfor %}
+```
+
+### Concatenate multiple entry fields
+
+We can utilise a LiquidJS template to concatenate multiple field values together and copy to a destination field
+
+In the example below we will copy the value of the source field to the destination field but also append any existing value if it exists
+
+```handlebars
+{{value}}{% if existing_value %} - {{existing_value}}{% endif %}
+```
+
+Or we can refer to other fields in the `entry` variable
+
+```handlebars
+{{entry.text}}{% if entry.heading %} - {{entry.heading}}{% endif %}
+```

package/docs/copy_field_transformation_matrix.md

@@ -0,0 +1,65 @@
+## Copy field transformation matrix
+
+Copying field data directly from one field to another can be done directly with the source and destination field types metioned in the below table
+
+When we copy certain field types, a transformation is made to the data to make it compatible with the destination field type.
+
+Copying a field will overwrite any data in the destination field, it will not preserve or respect any data that currently exists or has been manually entered. The destination field also needs to exist in the Content Type we are targeting.
+
+Finer grained control of the field data transformation (including field types not supported directly) can be made using a [template](copy_field_templates.md)
+
+| source                       | destination                  | notes                                                                                 |
+| ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------- |
+| string                       | string                       |                                                                                       |
+|                              | stringArray                  |                                                                                       |
+|                              | canvas                       | Content is surrounded within a paragraph block (template can alter the source value)  |
+|                              | richText                     |                                                                                       |
+|                              | richTextArray                |                                                                                       |
+|                              | boolean                      | True if evaluates "truthy" (0, false or null would be false)                          |
+| stringArray                  | stringArray                  |                                                                                       |
+|                              | string                       | Multiples separated with newline                                                      |
+|                              | canvas                       | ^                                                                                     |
+|                              | richText                     | ^                                                                                     |
+|                              | richTextArray                |                                                                                       |
+| richText                     | canvas                       |                                                                                       |
+|                              | richText                     |                                                                                       |
+|                              | richTextArray                |                                                                                       |
+|                              | string                       |                                                                                       |
+|                              | stringArray                  |                                                                                       |
+| richTextArray                | richTextArray                |                                                                                       |
+|                              | richText                     | Multiples separated with newline                                                      |
+|                              | canvas                       |                                                                                       |
+| boolean                      | boolean                      |                                                                                       |
+|                              | string                       | "Yes" or "No"                                                                         |
+|                              | stringArray                  | ^                                                                                     |
+|                              | integer                      | True = 1, false = 0                                                                   |
+|                              | integerArray                 | ^                                                                                     |
+|                              | decimal                      | True = 1, false = 0                                                                   |
+|                              | decimalArray                 | ^                                                                                     |
+| integer                      | integer                      |                                                                                       |
+|                              | integerArray                 |                                                                                       |
+|                              | decimal                      |                                                                                       |
+|                              | decimalArray                 |                                                                                       |
+|                              | boolean                      | True if evaluates "truthy" (0, false or null would be false)                          |
+| decimal                      | decimal                      |                                                                                       |
+|                              | decimalArray                 |                                                                                       |
+|                              | integer                      | Truncate any decimal precision (e.g. 44.9 = 44)                                       |
+|                              | integerArray                 | ^                                                                                     |
+|                              | boolean                      | True if evaluates "truthy" (0, false or null would be false)                          |
+| dateTime                     | dateTime                     |                                                                                       |
+|                              | dateTimeArray                |                                                                                       |
+| image                        | image                        |                                                                                       |
+|                              | imageArray                   |                                                                                       |
+| imageArray                   | imageArray                   |                                                                                       |
+|                              | image                        |                                                                                       |
+| component                    | component                    | Source and destination component must contain the same fields                         |
+|                              | componentArray               | ^                                                                                     |
+| component.\<field type>      | \<field type>                | Supports the field types mentioned above                                              |
+| componentArray.\<field type> | \<field type>                | ^ at the first position in the array                                                  |
+| \<field type>                | component.\<field type>      | Adds the field to existing component object or add new component with just this field |
+|                              | componentArray.\<field type> | ^ at the first position in the array                                                  |
+| composer                     | canvas                | Renders composer content as simple HTML and parses to canvas JSON                          |
+| \<field type>                | composer                     | Not supported                                                                         |
+| canvas                       | \<field type>                | Not supported                                                                         |
+
+Key: ^ = as above

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contensis-cli",
-  "version": "1.2.0",
+  "version": "1.2.1-beta.0",
   "description": "A fully featured Contensis command line interface with a shell UI provides simple and intuitive ways to manage or profile your content in any NodeJS terminal.",
   "repository": "https://github.com/contensis/cli",
   "homepage": "https://github.com/contensis/cli/tree/main/packages/contensis-cli#readme",
@@ -40,7 +40,7 @@
     "jsonpath-mapper": "^1.1.0",
     "keytar": "^7.9.0",
     "lodash": "^4.17.21",
-    "migratortron": "^1.0.0-beta.48",
+    "migratortron": "^1.0.0-beta.50",
     "nanospinner": "^1.1.0",
     "node-fetch": "^2.6.7",
     "parse-git-config": "^3.0.0",

package/src/version.ts

@@ -1 +1 @@
-export const LIB_VERSION = "1.2.0";
+export const LIB_VERSION = "1.2.1-beta.0";