DHFPROD-1604 QuickStart tutorial for 4.x - code complete, but still hidden.

_assets/css/bundle.scss

@@ -363,6 +363,10 @@ h2 {
   margin-top: 40px;
 }
 
+h3 {
+  font-size: 150%;
+}
+
 .smaller {
   font-size: 80%;
 }
@@ -404,6 +408,11 @@ h2 {
   vertical-align: middle;
 }
 
+.bg-gray {
+  background-color: #ccc;
+  color: black;
+}
+
 .inline-button {
   background-color: #496276;
   color: white;
@@ -552,6 +561,12 @@ h2 {
   font-size: 85%;
   line-height: 0.85;
 }
+.tut-nav {
+  padding: 0;
+  margin: 0;
+  font-size: 85%;
+  line-height: 0.85;
+}
 
 .list-group-item.active, .list-group-item.active:hover,
 .list-group-item.active:focus {
@@ -635,6 +650,9 @@ details {
   > img {
     padding-bottom: 10px;
   }
+  > pre {
+    padding-bottom: 10px;
+  }
 }
 details > summary:before {
   content: "► ";

_data/sidenav.yml

@@ -157,7 +157,7 @@ main:
           { url: '/refs/gradle-tasks/', text: 'DHF Gradle Tasks' },
           { url: '/refs/server-side-library/', text: 'Server Side API Library' },
           { url: '/refs/security/', text: 'Security' },
-          # { url: '/refs/index-settings/', text: 'Index Settings' },
+          { url: '/refs/index-settings/', text: 'Index Settings' },
         ]
       }
     - { url: '/refs/faqs/', text: 'FAQs' }

_data/tut4xentprops.yml

@@ -0,0 +1,46 @@
+'Product': [
+  {
+    name: 'sku',
+    type: 'string',
+    indexes: [ 'key' ],
+  },
+  {
+    name: 'price',
+    type: 'decimal',
+  },
+]
+
+'Order': [
+  {
+    name: 'id',
+    type: 'string',
+    indexes: [ 'key', 'element range' ],
+  },
+  {
+    name: 'total',
+    type: 'decimal',
+  },
+  {
+    name: 'products',
+    entitytype: 'Product',
+    cardinality: '1..∞',
+  },
+]
+
+'Customer': [
+  {
+    name: 'id',
+    type: 'string',
+    indexes: [ 'key' ],
+  },
+  {
+    name: 'billing_address',
+    type: 'string',
+    indexes: [ 'pii' ],
+  },
+  {
+    name: 'shipping_address',
+    type: 'string',
+    indexes: [ 'pii' ],
+  },
+]

_data/tut4xtoc.yml

@@ -3,42 +3,33 @@
     text: 'Install the Data Hub Framework',
   }
 - {
-    text: 'Loading the Raw Data',
+    text: 'Load the Raw Data',
     childPages: [
       { url: '/tutorial/4x/create-entities/', text: 'Create the Entities' },
-      { url: '/tutorial/4x/create-input-flows/', text: 'Create the Input Flows' },
-      { url: '/tutorial/4x/config-run-input-flows/', text: 'Configure and Run the Input Flows' },
+      { url: '/tutorial/4x/create-run-input-flows/', text: 'Create and Run the Input Flows' },
     ]
   }
 - {
-    text: 'Viewing Jobs, Traces, and Data',
+    text: 'View Jobs, Traces, and the Data',
     childPages: [
       { url: '/tutorial/4x/view-jobs/', text: 'View the Jobs Log' },
       { url: '/tutorial/4x/view-traces/', text: 'View the Traces Log' },
       { url: '/tutorial/4x/browse-data/', text: 'Browse the Data' },
     ]
   }
 - {
-    text: 'Harmonizing Data',
+    text: 'Harmonize the Data',
     childPages: [
-      { url: '/tutorial/4x/modeling-product-entity/', text: 'Model the Product Entity' },
-      { url: '/tutorial/4x/mapping-product-entity/', text: 'Create a Product Source-to-Entity Mapping' },
-      { url: '/tutorial/4x/harmonizing-product-data/', text: 'Harmonize the Product Data' },
+      { url: '/tutorial/4x/harmonize-product-data-by-mappings/', text: 'Harmonize the "Product" Data by Mappings' },
+      { url: '/tutorial/4x/harmonize-order-data-by-custom-code/', text: 'Harmonize the "Order" Data by Custom Code' },
+      { url: '/tutorial/4x/secure-pii-in-customer-data/', text: 'Secure PII in the "Customer" Data' },
     ]
   }
 - {
-    text: 'Harmonizing Orders',
-    childPages: [
-      { url: '/tutorial/4x/modeling-order-entity/', text: 'Model the Order Entity' },
-      { url: '/tutorial/4x/harmonizing-order-data/', text: 'Harmonize the Order Data' },
-      { url: '/tutorial/4x/securing-pii/', text: 'Securing PII' },
-    ]
-  }
-- {
-    url: '/tutorial/4x/serve-data/',
-    text: 'Serve the Data Out of MarkLogic',
+    url: '/tutorial/4x/access-data/',
+    text: 'Access the Data from MarkLogic Server',
   }
 - {
-    url: '/tutorial/4x/wrapping-up/',
-    text: 'Wrapping Up',
+    url: '/tutorial/4x/takeaways/',
+    text: 'Takeaways',
   }

_includes/conrefs/conref-qs-4x-browse-data.md

@@ -1,16 +1,17 @@
-{% assign pickdb="the STAGING database or the FINAL database" %}
-{% if include.pickdb %}{% assign pickdb=include.pickdb %}{% endif %}
+{% assign pickdbphrase="the STAGING database or the FINAL database" %}
+{% if include.pickdb %}{% assign pickdbphrase="the **" | append: include.pickdb | append: "** database" %}{% endif %}
 
 {% assign pickitem="the dataset item you want to view" %}
 {% if include.pickitem %}{% assign pickitem=include.pickitem %}{% endif %}
 
-
-{% assign full-imgpath=include.imgpath | append: "qs-4x-browse-data-full.png" %}
-{% include thumbnail.html imgfile=full-imgpath alttext="Browse Data view" imgclass="screenshot" tab="  " %}
+{% assign pref="qs-4x-browse-data" %}
+{% if include.pickdb %}{% assign suf="-" | append: include.pickdb %}{% else %}{% assign suf="" %}{% endif %}
+{% assign full-imgpath=include.imgpath | append: pref | append: suf | append: ".png" %}
+{% include thumbnail.html imgfile=full-imgpath alttext="Browse Data" imgclass="screenshot" tab="  " %}
 
 1. In the QuickStart menu, click **Browse Data**{:.uimenuitem}.
-1. From the database selection dropdown, choose {{ pickdb }}.
-1. To narrow the list to include entities only, check the **Entities Only**{:.uilabel} box.
+1. From the database selection dropdown, choose {{ pickdbphrase }}.
+1. (Optional) To narrow the list to include entities only, check the **Entities Only**{:.uilabel} box.
     {% include note-in-list.html type="TIP" content="You can further filter the list by using the free-text search field or the faceted search filters." %}
 1. In the list, click the row of {{ pickitem }}.
 {:.ol-steps}

_includes/conrefs/conref-qs-4x-create-entity.md

@@ -2,7 +2,7 @@
 To create an entity named `{{ include.entityname }}`,
 
 {% assign pref="qs-4x-entities-create-complete" %}
-{% if include.entityname %}{% assign suf="-" | append: include.entityname %}{% endif %}
+{% if include.entityname %}{% assign suf="-" | append: include.entityname %}{% else %}{% assign suf="" %}{% endif %}
 {% assign full-imgpath=include.imgpath | append: pref | append: suf | append: ".png" %}
 {% include thumbnail.html imgfile=full-imgpath alttext="New Entities form" imgclass="screenshot" tab="  " %}
 

_includes/conrefs/conref-qs-4x-create-run-harmonize-flow.md

@@ -0,0 +1,32 @@
+{% if include.create %}
+{% if include.fullsteps %}
+To create a harmonization flow for the `{{ include.entityname }}` entity,
+
+{% assign pref="qs-4x-flows-create-harmonize-flow" %}
+{% if include.entityname %}{% assign suf="-" | append: include.entityname %}{% else %}{% assign suf="" %}{% endif %}
+{% assign full-imgpath=include.imgpath | append: pref | append: suf | append: ".png" %}
+{% include thumbnail.html imgfile=full-imgpath alttext="Create Harmonize Flow form" imgclass="screenshot" tab="  " %}
+
+1. In QuickStart's navigation bar, click **Flows**{:.uimenuitem}.{% endif %}
+1. {% assign full-text = "Expand **" | append: include.entityname | append: "**{:.uilabel} in the left panel." %}{{ full-text }}
+1. Click the **+**{:.uilabel} for **Harmonize Flows**{:.uilabel}.
+1. {% assign full-text = "In the **Create Harmonize Flow**{:.uilabel} dialog, set **Harmonize Flow Name**{:.uilabel} to <code>" | append: include.harmonizeflowname | append: "</code>." %}{{ full-text }}
+{% if include.mappingname %}1. Under **Mapping Generation**{:.uilabel}, check **{{ include.mappingname }}** .{% endif %}
+1. Click **CREATE**{:.inline-button}.
+{:.ol-steps}
+{% endif %}
+
+{% if include.run %}
+{% if include.fullsteps %} When you create a flow with mapping, QuickStart automatically generates harmonization code based on the entity model and the mapping and then deploys the code to MarkLogic Server.
+
+To run the harmonization flow,{% endif %}
+
+{% assign pref="qs-4x-flows-run-harmonize-flow" %}
+{% if include.entityname %}{% assign suf="-" | append: include.entityname %}{% else %}{% assign suf="" %}{% endif %}
+{% assign full-imgpath=include.imgpath | append: pref | append: suf | append: ".png" %}
+{% include thumbnail.html imgfile=full-imgpath alttext="Run Flow form" imgclass="screenshot" tab="  " %}
+
+1. Click the **Flow Info**{:.uilabel} tab.
+1. Click **Run Harmonize**{:.inline-button}.
+{:.ol-steps}
+{% endif %}

_includes/conrefs/conref-qs-4x-config-run-input-flows.md → _includes/conrefs/conref-qs-4x-create-run-input-flow.md

@@ -1,17 +1,33 @@
-{% if include.fullsteps %}
-To configure and run the `{{ include.jobname }}` input flow,
+### 1 - Create an input flow for the **{{ include.entityname }}** entity.
 
-{% assign pref="qs-4x-flows-load-data" %}
-{% if include.entityname %}{% assign suf="-" | append: include.entityname %}{% endif %}
+{% if include.fullsteps %}
+{% assign pref="qs-4x-flows-create-input-flow" %}
+{% if include.entityname %}{% assign suf="-" | append: include.entityname %}{% else %}{% assign suf="" %}{% endif %}
 {% assign full-imgpath=include.imgpath | append: pref | append: suf | append: ".png" %}
-{% include thumbnail.html imgfile=full-imgpath alttext="" imgclass="screenshot" tab="  " %}
-{% endif %}
+{% include thumbnail.html imgfile=full-imgpath alttext="Create Input Flow form" imgclass="screenshot" tab="  " %}
 
+1. In QuickStart's navigation bar, click **Flows**{:.uimenuitem}.{% endif %}
 1. {% assign full-text = "Expand **" | append: include.entityname | append: "**{:.uilabel} in the left panel." %}{{ full-text }}
-1. Click **{{ include.jobname }}**{:.uilabel} under **Input Flows**{:.uilabel}.
+1. Click the **+**{:.uilabel} for **Input Flows**{:.uilabel}.
+1. {% assign full-text = "In the **Create Input Flow**{:.uilabel} dialog, set **Input Flow Name**{:.uilabel} to <code>" | append: include.inputflowname | append: "</code>." %}{{ full-text }}
+1. Click **CREATE**{:.inline-button}.
+{:.ol-steps}
+
+{% if include.fullsteps %}
+**Result**
+
+  - Your new flow appears under **Input Flows**{:.uilabel} in the left panel.
+  - The **Run Input Flow**{:.uilabel} wizard appears on the right.
+{% endif %}
+
+
+### 2 - Configure and run the **{{ include.inputflowname }}** flow.
 
 {% if include.fullsteps %}
-    **Result:** The **Run Input Flow**{:.uilabel} wizard appears.
+{% assign pref="qs-4x-flows-load-data" %}
+{% if include.entityname %}{% assign suf="-" | append: include.entityname %}{% else %}{% assign suf="" %}{% endif %}
+{% assign full-imgpath=include.imgpath | append: pref | append: suf | append: ".png" %}
+{% include thumbnail.html imgfile=full-imgpath alttext="" imgclass="screenshot" tab="  " %}
 {% endif %}
 
 {% assign full-imgpath=include.imgpath | append: "qs-4x-flows-load-raw-input-files" | append: suf | append: ".png" %}

_includes/conrefs/conref-qs-4x-define-entity-model-add-props.md

@@ -0,0 +1,32 @@
+<li>{% if include.counter == 0 %}In the <span class="uilabel">{{ include.entityname }}</span> entity editor, click <span class="circle-button">+</span> in the <span class="uilabel">Properties</span> section to add a new property.
+{% else %}Click <span class="circle-button">+</span> again to add another property.{% endif %}
+
+  <ol class="ol-substeps">
+
+    <li>Set <span class="uilabel">Name</span> to <code>{{ include.propname }}</code>.</li>
+
+    {% if include.propentitytype %}
+      <li>
+        {% assign pref="qs-4x-entities-add-properties-type-entities" %}
+        {% if include.entityname %}{% assign suf="-" | append: include.entityname %}{% else %}{% assign suf="" %}{% endif %}
+        {% assign full-imgpath=include.imgpath | append: pref | append: suf | append: ".png" %}
+        {% assign full-text="Set <span class='uilabel'>Type</span> to the entity <span class='uilabel'>" | append: include.propentitytype | append: "</span>." %}
+        {% include step-collapsed.html steptext=full-text stepimg=full-imgpath imgclass="screenshot" nonum=true %}
+      </li>
+    {% else %}
+      <li>Set <span class="uilabel">Type</span> to <code>{{ include.proptype }}</code>.</li>
+    {% endif %}
+
+    {% if include.propindexes contains "key" %}<li>To make <code>{{ include.propname }}</code> the primary key, click the area in the key <span><i class='fa fa-key'></i></span> column for the <code>{{ include.propname }}</code> row.</li>{% endif %}
+
+    {% if include.propindexes contains "element range" %}<li>To specify that <code>{{ include.propname }}</code> needs an element range index, click the area in the lightning bolt <span><i class='fa fa-bolt'></i></span> column for the <code>{{ include.propname }}</code> row.</li>{% endif %}
+
+    {% if include.propindexes contains "pii" %}<li>To mark <code>{{ include.propname }}</code> as PII, click the area in the key <span><i class='fa fa-lock'></i></span> column for the <code>{{ include.propname }}</code> row.</li>{% endif %}
+
+    {% if include.propcardinality %}
+      <li>To indicate that a(n) <span class="uilabel">{{ include.entityname }}</span> instance can have multiple instances of this property, set <span class="uilabel">Cardinality</span> to <span class="uilabel">1..∞</span>.</li>
+    {% endif %}
+
+  </ol>
+
+</li>

_includes/conrefs/conref-qs-4x-define-entity-model.md

@@ -0,0 +1,45 @@
+{% if include.fullsteps %}
+To define the `{{ include.entityname }}` entity model,
+
+{% assign pref="qs-4x-entities-add-properties" %}
+{% if include.entityname %}{% assign suf="-" | append: include.entityname %}{% else %}{% assign suf="" %}{% endif %}
+{% assign full-imgpath=include.imgpath | append: pref | append: suf | append: ".png" %}
+{% include thumbnail.html imgfile=full-imgpath alttext="entity properties" imgclass="screenshot" tab="  " %}
+{% endif %}
+
+<ol class="ol-steps">
+
+  {% if include.fullsteps %}<li>In QuickStart's navigation bar, click <span class="uimenuitem">Entities</span>.</li>{% endif %}
+
+  <li>At the top of the <span class="uilabel">{{ include.entityname }}</span> entity card, click the pencil icon <span><i class='fa fa-pencil-alt'></i></span> to edit the <span class="uilabel">{{ include.entityname }}</span> entity definition.</li>
+
+  {% assign counter = 0 %}
+  {% for prop in site.data.tut4xentprops.[include.entityname] %}
+    {% include conrefs/conref-qs-4x-define-entity-model-add-props.md
+      entityname=include.entityname
+      propname=prop.name
+      proptype=prop.type
+      propentitytype=prop.entitytype
+      propcardinality=prop.cardinality
+      propindexes=prop.indexes
+      imgpath=include.imgpath
+      counter=counter
+    %}
+    {% assign counter = counter | plus: 1 %}
+  {% endfor %}
+
+  <li>Click <span class="inline-button">SAVE</span>.</li>
+
+  <li>
+  {% assign full-imgpath=include.imgpath | append: "qs-4x-update-indexes-yes.png" %}
+  {% assign full-text="If prompted to update the index, click <span class='inline-button'>Yes</span>." %}
+  {% include step-collapsed.html steptext=full-text stepimg=full-imgpath imgclass="img-small" nonum=true %}
+  </li>
+
+  <li>
+  {% assign full-imgpath=include.imgpath | append: "qs-4x-entities-resize-card.png" %}
+  {% assign full-text="Drag the bottom-right corner of the entity card to resize it and see the newly added properties." %}
+  {% include step-collapsed.html steptext=full-text stepimg=full-imgpath imgclass="img-small" nonum=true %}
+  </li>
+
+</ol>