D5

uml2es/README.md

@@ -8,11 +8,11 @@ UML2ES is a toolkit to support modeling MarkLogic data in UML and mapping that U
 - <http://developer.marklogic.com/blog/uml-modeling-marklogic-entity-services>
 - <http://developer.marklogic.com/blog/uml-modeling-marklogic-entity-services-semantics>
 
-Also watch the following video:
+Also watch the following video (it's a little out of date):
 
 - <https://www.youtube.com/watch?v=VkpH3LgMz3M&feature=youtu.be>
 
-It works like this:
+UML2ES works like this:
 
 ![toolkit](toolkit.png)
 
@@ -24,7 +24,7 @@ The toolkit consists of the following parts:
 - [umlProfile](umlProfile): A UML profile containing stereotypes for MarkLogic Entity Services. Use this profile to include Entity Services configuration to your UML model.
 - [excel](excel): You can build your model in Excel as an alternative to UML! Maybe we should rename this toolkit *Excel2ES*! The toolkit provides an [Excel template](excel/uml2es-excel-template.xlsx) for this purpose. See [examples/hrexcel](examples/hrexcel) for a detailed example of how to use it. Also included is a [mapping spreadsheet](excel.uml2es-excel-mapping-template.xlsx). See [tutorials/employeeCradleToGrave.md](tutorials/employeeCradleToGrave.md) and [examples/hr](examples/hr) for detailed examples of how to use it. 
 - [tutorials](tutorial): Step-by-step tutorials on how to use UML2ES ranging from simple -- [tutorials/papyrus_model_edit.md](tutorials/papyrus_model_edit.md) -- to epic: [tutorials/employeeCradleToGrave.md](tutorials/employeeCradleToGrave.md).
-- [examples](examples): Numerous examples showing the use of UML (and Excel) data models for MarkLogic. Highlights: modeling for Entity Services and Template-Driven Extraction; modeling complex document relationships using UML relationships; the UML toolkit and Data Hub; the Data Hub "cookie cutter"; mixed models (documents + semantics); logical vs. physical; generating MarkLogic code from the UML model; using ml-gradle to run the transformation of UML to Entity Services as part of your build. 
+- [examples](examples): Numerous examples showing the use of UML (and Excel) data models for MarkLogic and its Data Hub framework. 
 
 ## How We Expect You Will Use This Toolkit
 As a user, you want to design a data model using UML and then ingest data into MarkLogic that conforms to this model. Put differently, you plan to put significant data into MarkLogic and want to ensure that the structure of this data follows a well considered model. 
@@ -39,7 +39,7 @@ If that's you, we think this toolkit is for you. You will need the following ing
 ## Where To Begin
 Start with the [tutorials](tutorials). If want to build a really simple model and see it through to MarkLogic, try [tutorials/papyrus_model_edit.md](tutorials/papyrus_model_edit.md) or [tutorials/magicdraw_model_edit.md](tutorials/magicdraw_model_edit.md). If you want to have more fun and explore how a team would deliver a more interesting model, try [tutorials/employeeCradleToGrave.md](tutorials/employeeCradleToGrave.md).
 
-Then dive into the [examples](examples). The [movies example](examples/movies) is a good place to start. If you are planning to use MarkLogic's data hub framework, or if you are interested in semantics, begin with the [hr example](examples/hr). 
+Then dive into the [examples](examples). The [movies example](examples/movies) is a good place to start if you want to explore how MarkLogic represents UML classes and relationships. If you are planning to use MarkLogic's data hub framework, or if you are interested in semantics, begin with the [hrHub5 example](examples/hrHub5). 
 
 ## Going Deeper
 Once you get deeper into the toolkit, refer to the [docs](docs/README.md) to learn about: the profile and its stereotypes; how the transform maps UML to Entity Services; how the toolkit supports semantics; how to include the transform in your build process.

uml2es/docs/build.md

@@ -3,166 +3,79 @@
 The toolkit supports a gradle build process. Gradle is the most widely used build tool for MarkLogic implementations. 
 The toolkit includes common gradle tasks to deploy your UML model and generate harmonization/conversion code from it. You use these tasks, as well as common [ml-gradle](https://github.com/marklogic-community/ml-gradle/wiki) and [data hub](https://marklogic.github.io/marklogic-data-hub/refs/gradle-tasks/) tasks, to deploy your application.
 
-The toolkit provides a gradle build file containing all model deployment and code generation tasks: [../uml2esTransform/uml2es.gradle](../uml2esTransform/uml2es.gradle). Actually, it also includes a similar build file for use for DHF: [../uml2esTransform/uml2es4dhf.gradle](../uml2esTransform/uml2es4dhf.gradle).  Here is a summary of the tasks from that build file:
+The toolkit provides a gradle build file containing all model deployment and code generation tasks. Actually, it provides three versions of this build file: 
+
+- One for DHF 5.x applications [../uml2esTransform/uml2es4dhf5.gradle](../uml2esTransform/uml2es4dhf5.gradle)
+- One for DHF 4.1 applications [../uml2esTransform/uml2es4dhf4.gradle](../uml2esTransform/uml2es4dhf4.gradle)
+- One for vanilla, non-DHF, applications [../uml2esTransform/uml2es.gradle](../uml2esTransform/uml2es.gradle)
+
+Here is a summary of the tasks from that build file:
 
 ## Build Tasks
 
 ### uDeployModel
 
 *Purpose*: Load your UML model into MarkLogic and convert it to ES.
 
-*DHF/Vanilla*: Both
+*Architectures* : Vanilla, DHF 4.1, DHF 5.x
 
 *Input:* 
-- modelName (XMI or Excel filename without suffix)
-- lax: true/false. Default: false (Use lax mode when transforming from UML to ES.)
+- modelFile: Full or relative path to your UML/XMI or Excel filename
+- lax: true/false. Default: false. (Use lax=true if model is missing attribute types or has other missing info.)
 
 *Dependencies:*
-- Your gradle project has the folder data/model
-- Your model is in that folder
-- Your model is XMI
-- Your model ends in .xml
 - Standard ml-gradle environment properties: mlAppServicesHost, mlAppServicesPort. OR ...
-- Standard DHF environment properties: mlHost, mlFinalPort
+- Standard DHF environment properties: mlHost, mlFinalPort. ...
+- UML2ES transform deployed to your modules database
 
 *Effects:*
-- Target database has the UML model, the ES model, the ES extensions, findings, generated code
-- Target database has the ES model and its extended triples deployed
+- Target database has the original UML model and the outputs of transforming it to ES: the ES model, the ES extensions, findings, some generated code
 - Your gradle project has entity-services, entity-services-dump, entity-services-extension folders
-- You will see generated code in src/main/ml-config, src/main/ml-modules, src/main/ml-schemas
+- Vanilla architecture: The model is fully deployed, meaning MarkLogic is aware of the model and allows you to introspect the model using semantic queries. If you want to generate code/artifacts from it, run built-in non-UML2ES gradle task mlGenerateModelArtifacts
+- In the DHF architecture, the model is "deployed" in the loose sense it can be semantically introspected. But in DHF no entities have yet been created. 
 
 ### uCreateDHFEntities
 
-*Purpose*: Create DHF plugin entities based on classes in your model.
+*Purpose*: Create DHF entities based on classes in your model.
+
+*Architectures* : DHF 4.1, DHF 5.x
 
 *DHF/Vanilla*: DHF
 
 *Input:* 
-- modelName - name of UML module file without .xml suffix
-- entities (optional) - CSV of class names representing entities to create
-- entitySelect (optional) - Possible values:
-	* "infer" - Have the cookie cutter infer which classes are entities. Ignore entities specified. (This works well for tree-based models where the candidate classes are parents but not children, such as [../examples/hr](../examples/hr). It does not always work. For example, in the graph-like model [../examples/movies](../examples/movies), the Movie class cannot be inferred to be *entity worthy*.
-	* "all" - All classes are considered entities. Ignore entities specified.
+- modelFile: Full or relative path to your UML/XMI or Excel filename
+- entitySelect (optional) - Instructions on which classes in the model should become DHF entities. Possible values:
+	* "infer" - Infer which classes are entities. Ignore entities specified. (This works well for tree-based models where the candidate classes are parents but not children, such as [../examples/hr](../examples/hr). It does not always work. For example, in the graph-like model [../examples/movies](../examples/movies), the Movie class cannot be inferred to be *entity worthy*.
+	* "all" - All classes are considered entities. 
+	* "stereotyped" - Classes stereotyped xDHFEntity are considered entities.
+- entities (optional) - A list of class names (comma-separated) representing entities to create. Use this if you want to specify your own list of entities and none of the entitySelect options works for you. 
 
 *Dependencies:* 
-- Your gradle project is DHF 4.1. If you prefer to use a more recent DHF 4.x release, make sure to change the DHF version in any *.gradle or gradle*.properties files you obtain from this toolkit.
-- You have deployed your UML model
-- Standard DHF environment properties: mlHost, mlFinalPort
+- You have already run uDeployModel successfully
 
 *Effects:*
-- New plugins created under plugins/entities folder
+- DHF 5.x - New entities created under entities folder
+- DHF 4.1 - New plugins created under plugins/entities folder
 
 ### uCreateDHFHarmonizeFlow
 
-*Purpose:*: Generate a harmonization flow based on your model. This conversion is smart, if you ask it to be.
-
-*DHF/Vanilla*: DHF
-
-*Input:* 
-- modelName - name of UML module file without .xml suffix
-- entityName - name of the entity. You must already have created this using uCreateDHFEntities
-- dataFormat: xml, json
-- pluginFormat: xqy, sjs
-- flowName: the harmonization flow name
-- contentMode: possible values
-	* es - Entity Services mode. The cookie cutter generates ES-conversion style code and 
-          incorporates hints from the data model and the mapping spec. This is like a souped up -useES option.
-    * dm - Declarative Mapper mode. *This feature is not ready yet.*
-- mappingSpec: previously uploaded Excel mapping spec; refer to it by the Excel URI
-- overwrite: true/false. If true and harmonization already exists, overwrite it. If you don't want to clobber, set to false.
-
-*Dependencies:*
-- Your gradle project is DHF 4.1. If you prefer to use a more recent DHF 4.x release, make sure to change the DHF version in any *.gradle or gradle*.properties files you obtain from this toolkit.
-- You have deployed your UML model
-- You have created the entity in question using uCreateDHFEntities
-- Standard DHF environment properties: mlHost, mlFinalPort
-
-*Effects:*
-- New harmonization flow plugins/entities/entityName/harmonize folder
+EOL. For DHF 4.1 only. See [../examples/hr](../examples/hr) and [../tutorials/employeeCradleToGrave.md](../tutorials/employeeCradleToGrave.md) for examples of use.
 
 ### uLoadMappingSpec
 
-*Purpose:*: Load an Excel mapping spec, which indicates how to map source data to the model. Used in the above tasks.
-
-*Input:* 
-- specName = mandatory (Excel filename without suffix)
-- discover = true/false; default false. *This is an experimental feature.*
-- discoveryDB = default: content DB (non-DHF), staging DB (DHF0). *This is an experimental feature.*
-
-*Dependencies:*
-- Your gradle project has the folder data/mapping
-- Your mapping spec is in that folder
-- Standard ml-gradle environment properties: mlAppServicesHost, mlAppServicesPort. OR ...
-- Standard DHF environment properties: mlHost, mlFinalPort
-
-*Effects:*
-- Target database has the mapping spec (original Excel plus transformed json)
+EOL. Used with DHF 4.1 architecture to generate helpful mapping/harmonization code. In DHF 5, mapping is declarative; the need for the capability is diminished. If you are still on DHF 4.1 and are interested in using this capability, refer to [../examples/hr](../examples/hr).  
 
 ### uCreateConversionModule
 
-*Purpose:* Creates a harmonize flow for the specified entity. A souped up es.instanceConverterGenerate.
-
-*Input:* 
-- modelName - name of UML module file without .xml suffix
-- entityName - name of the entity. 
-- dataFormat: xml, json
-- pluginFormat: xqy, sjs
-- moduleName the module name
-- contentMode: possible values
-	* es - Entity Services mode. The cookie cutter generates ES-conversion style code and 
-          incorporates hints from the data model and the mapping spec. This is like a souped up -useES option.
-     * dm - Declarative Mapper mode. This feature is not ready yet.
-- mappingSpec: previously uploaded Excel mapping spec; refer to it by the Excel URI
-- overwrite: true/false. If true and the module already exists, overwrite it. If you don't want to clobber, set to false.
-
-*Dependencies:*
-- You have deployed your UML model
-- Standard ml-gradle environment properties: mlAppServicesHost, mlAppServicesPort. OR ...
-- Standard DHF environment properties: mlHost, mlFinalPort. BUT WE RECOMMEND USING uCreateDHFHarmonizeFlow IF YOU ARE ON DHF.
-
-*Effects:*
-- New conversion module in src/main/ml-modules/root/modelName/entityName folder
-
-## Model/Conversion/Harmonization Workflow
-
-How do you string these tasks together to build useful code from a model? Here are a few scenario workflows:
-
-1. DHF environment with harmonization created by out-of-the-box DHF code generator. Example: [../tutorials/employeeCradleToGrave.md](../tutorials/employeeCradleToGrave.md).
-
-	- Make a copy of [../uml2esTransform/uml2es4dhf.gradle](../uml2esTransform/uml2es4dhf.gradle) into your local gradle project. 
-	- Run task uDeployModel. 
-	- Generate entities using uCreateDHFEntities.
-	- Generate harmonizations using the out-of-the-box DHF createHarmonizeFlow task. These are created in the plugins/entities folder.
-
-2. DHF environment with harmonization created by UML2ES with mapping spec details and hints from the extended model. Example: [../examples/hr](../examples/hr). 
-
-	- Make a copy of [../uml2esTransform/uml2es4dhf.gradle](../uml2esTransform/uml2es4dhf.gradle) into your local gradle project. 
-	- Run task uDeployModel. 
-	- Deploy the mapping spec: uLoadMappingSpec
-	- Generate entities using uCreateDHFEntities
-	- Generate harmonizations using uCreateDHFHarmonizationFlow. The harmonization is created in plugins/entities.
-
-3. Vanilla environment with out-of-the-box ES code generation from the model, as in the [../examples/movies](../examples/movies) example:
-
-	- Make a copy of [../uml2esTransform/uml2es.gradle](../uml2esTransform/uml2es.gradle) into your local gradle project. At the bottom of that file, set one of more generate flags to true. For example, to use ES to generate an instance converter and TDE template, set the following to true:
-		- generateInstanceConverter=true
-		- generateExtractionTemplate=true
-	- Run task uDeployModel. As a result of this, the generated instance converter is in src/main/ml-modules/ext. The generated TDE template is in src/main/ml-schemas.
-
-4. Vanilla environment with generation of UML2ES conversion module with mapping spec details and hints from the extended model. Example: [../examples/gentest/vanilla](../examples/gentest/vanilla)
-
-	- Make a copy of [../uml2esTransform/uml2es.gradle](../uml2esTransform/uml2es.gradle) into your local gradle project. 
-	- Run task uDeployModel. 
-	- Load the mapping spec using uLoadMappingSpec.
-	- Generate the conversion module using uCreateConversionModule with contentMode=es. As a result of this, the generated conversion module is in src/main/ml-modules/root/esconversion. 
+EOL and not tested. Meant for vanilla architectures. Generates souped-up conversion code, more comprehensive that what ES generates out of the box. 
 
 ## Build Tips
 
 The [../examples](../examples) and [../tutorials](../tutorials) of this toolkit show this gradle build in action. There are several ways to use it:
 
-- Move it into your gradle project as a build script solely for UML2ES. Keep a separate build script for your main build work. The examples and tutorials take this approach. When using it this way, edit plugin versions if needed. 
+- Move it into your gradle project as a build script solely for UML2ES. Keep a separate build script for your main build work. The examples and tutorials take this approach. When using it this way, you might need to edit plugin versions in your copy of the UML2ES build file. For example, you might need to change the MLCP version or the version of the DHF plugin.
 - Copy its tasks into your existing gradle build file. 
-- Copy it into your gradle project and use it as your main gradle build file. Add app-specific build tasks to it as needed.
+- Copy it into your gradle project and use it as your main gradle build file. Add app-specific build tasks to it for your own needs.
 
 The mega tutorial [../tutorials/employeeCradleToGrave.md](../tutorials/employeeCradleToGrave.md) demonstrates the gradle build as key ingredient in a soup-to-nuts modeling example for DHF. Please go through this tutorial to see how to:
 

uml2es/docs/envelope.md

@@ -21,3 +21,5 @@ The toolkit's code generation feature builds code that persists your business da
 The following diagram shows how this works:
 
 ![Envelope](envelope.png)
+
+