Merge pull request #7837 from mandy-chessell/code2023

Enhance omag-server-platform assembly (#7766)

open-metadata-distribution/omag-server-platform/README.md

@@ -7,6 +7,12 @@ The **OMAG Server Platform** module creates a distribution **tar** file that can
 and used to install Egeria's OMAG Server Platform.   For further information see
 [Installing Egeria Tutorial](https://egeria-project.org/education/tutorials/installing-egeria-tutorial).
 
+The diagram below shows the file layout for the OMAG Server Platform. The directories show in white are built by this assembly.  The ones shown in blue are created during the platform operation.
+
+![File layout for the omag-server-platform assembly](docs/fileLayout.png)
+
+Each of the directories created by the assembly includes a `README.md` file that describes its content and how to use it.
+
 ----
 License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/),
 Copyright Contributors to the ODPi Egeria project.

open-metadata-distribution/omag-server-platform/docs/README.md

@@ -1,7 +1,9 @@
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 <!-- Copyright Contributors to the Egeria project. -->
 
+# Documentation files
 
+This is the documentation and diagrams that are inserted into the omag-server-platform assembly.
 
 
 

open-metadata-distribution/omag-server-platform/docs/docker-build/README.md

@@ -1,27 +1,33 @@
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 <!-- Copyright Contributors to the Egeria project. -->
 
-# Egeria's install image
+# Egeria's assembly
 
 The contents of this directory were initially created by the gradle build script
 from the [egeria.git](https://github.com/odpi/egeria) repository.
 It has two parts to it:
 
-* All the files and built images for egeria are under the `deployment` directory.  
-  Each directory contains a readme that describes its contents.
-* A `Docker` build file used to create a docker image
+* All the files and built images for egeria are under the `assembly` directory.  
+  Each directory contains a `README.md` that describes its contents.
+* A `Docker` build file used to create a docker image.
 * A directory called `dist` that contains the start up script run when a docker image built
   from this directory is run.
 
 ## Creating a docker image
 
-The Docker file creates a docker image based on the files in the deployment directory.
+The `Docker` file provides the context for creating a docker image based on the files in the `assembly` directory. 
 
-First add or remove the files from under the `deployment` directory to suit your needs.
-Then run `docker build -t egeria-platform:{myversion} -f Dockerfile .` in this
-directory to create the image, replacing `{myversion}` with a name or date as a tag for this version of the docker image.
+First add or remove the files from under the `platform` directory to suit your needs.
+Then run `docker build -t egeria-platform:{tagName} -f Dockerfile .` in this
+directory to create the image, replacing `{tagName}` with a name or date as a tag for this version of the docker image.
+The docker build packages everything under `platform` into the docker image.
 
-To run the resulting image use `docker run  -p 9443:9443  odpi/egeria-platform:{myversion}`.
+The docker build is created by a remote docker daemon and the resulting image is
+found under the images managed by that daemon.  For example, if you are using
+[Docker Desktop](https://www.docker.com/products/docker-desktop/),
+the docker image is located in the **Images** tab.
+
+To run the resulting image from the command line, use `docker run -p 9443:9443  odpi/egeria-platform:{tagName}`, again replacing `{tagName}` with your chosen tag.
 
 
 

open-metadata-distribution/omag-server-platform/docs/platform/README.md

@@ -6,7 +6,7 @@
 The omag-server-platform.jar file holds the main runtime for Egeria,  To start the platform, enter:
 
 ```bash
-java -Dloader.path=lib,extra omag-server-platform*.jar
+java -Dloader.path=lib,extra -jar omag-server-platform*.jar
 ```
 
 You will see the platform logo plus other messages describing its startup configuration.

open-metadata-distribution/omag-server-platform/docs/sample-clients/README.md

@@ -4,7 +4,48 @@
 # Sample clients
 
 The open metadata samples illustrate how to use the various APIs of Egeria.
-If you run them, they display help information to control the parameters
+When you run them, they display help information describing the parameters
+needed to run them successfully.
+
+* **asset-create-avro-sample** catalogues an Apache Avro file in the open metadata ecosystem as an Asset.  This sample uses the [Asset Owner OMAS](https://egeria-project.org/services/omas/asset-owner/overview/).
+* **asset-create-csv-sample** catalogues a CSV file in the open metadata ecosystem as an Asset.  This sample also uses the [Asset Owner OMAS](https://egeria-project.org/services/omas/asset-owner/overview/).
+* **asset-deploy-sample** illustrates the use of the [IT Infrastructure OMAS](https://egeria-project.org/services/omas/it-infrastructure/overview/) APIs to catalog different types of infrastructure.
+* **asset-look-up-sample** illustrates the use of the [Asset Consumer OMAS](https://egeria-project.org/services/omas/asset-consumer/overview/) APIs to search for and display the metadata linked to an Asset.
+* **asset-reader-avro-sample** illustrates the use of the [Asset Consumer OMAS](https://egeria-project.org/services/omas/asset-consumer/overview/) APIs to create connectors to Avro files.
+* **asset-reader-csv-sample** illustrates the use of the [Asset Consumer OMAS](https://egeria-project.org/services/omas/asset-consumer/overview/) APIs to create connectors to CSV files.
+* **asset-set-up-sample** illustrates the use of a variety of [OMASs](https://egeria-project.org/services/omas/) APIs to catalog files.
+* **config-metadata-server-sample** illustrates the use of the [Administration Services](https://egeria-project.org/services/admin-services/overview) APIs to create a configuration document for a Metadata Access Store.
+* **glossary-workflow-samples** show different styles of managing changes to glossary terms.
+They are illustrated through the [Asset Manager OMAS glossary management API](https://odpi.github.io/egeria/org/odpi/openmetadata/accessservices/assetmanager/api/management/GlossaryManagementInterface.html).
+This interface is used by [Glossary Workflow OMVS](https://egeria-project.org/services/omvs/glossary-workflow/overview) to provide the backend services for UI that provide complex management interfaces.
+* **governance-leadership-sample** shows the appointment of different types of governance officers over time.  It uses the APIs from [Governance Program OMAS](https://egeria-project.org/services/omas/governance-program/overview/).
+* **governance-subject-area-sample** shows the creation of Coco Pharmaceuticals' subject area definitions.  It uses the APIs from [Governance Program OMAS](https://egeria-project.org/services/omas/governance-program/overview/).
+* **governance-zone-create-sample** shows the creation of Coco Pharmaceuticals' governance zone definitions.  It uses the APIs from [Governance Program OMAS](https://egeria-project.org/services/omas/governance-program/overview/).
+* **subject-area-categories-sample** shows how to create a hierarchy of categories using the [Subject Area OMAS](https://egeria-project.org/services/omas/subject-area/overview/).
+
+
+These sample clients need access to certifications to validate the platform
+they are calling.  Copy the JAR files for the samples into the `platform` directory:
+
+```bash
+cp *.jar ../../platform
+```
+Change to the `platform` directory.
+```bash
+cd ../../platform
+```
+
+Then, once you have the platform running, you can run the samples with the following command:
+
+```bash
+java -Djavax.net.ssl.keyStore=keystore.p12 -Djavax.net.ssl.keyStorePassword=egeria -Djavax.net.ssl.trustStore=truststore.p12 -Djavax.net.ssl.trustStorePassword=egeria -jar {jarFileName}
+```
+Replace {jarFileName} with then name of sample's JAR file that you wish to run.
+For example, to run the `asset-set-up-sample` enter:
+
+```bash
+java -Djavax.net.ssl.keyStore=keystore.p12 -Djavax.net.ssl.keyStorePassword=egeria -Djavax.net.ssl.trustStore=truststore.p12 -Djavax.net.ssl.trustStorePassword=egeria -jar asset-set-up-sample.jar
+```
 
 
 ----

open-metadata-distribution/open-metadata-assemblies/build.gradle

@@ -58,7 +58,7 @@ dependencies {
     implementation project(':open-metadata-resources:open-metadata-samples:access-services-samples:governance-program-client-samples:governance-leadership-sample')
     implementation project(':open-metadata-resources:open-metadata-samples:access-services-samples:governance-program-client-samples:governance-subject-area-sample')
     implementation project(':open-metadata-resources:open-metadata-samples:access-services-samples:governance-program-client-samples:governance-zone-create-sample')
-    implementation project(':open-metadata-resources:open-metadata-samples:access-services-samples:subject-area-client-samples:subject-area-definition-sample')
+    implementation project(':open-metadata-resources:open-metadata-samples:access-services-samples:subject-area-client-samples:subject-area-categories-sample')
     implementation project(':open-metadata-implementation:access-services:asset-catalog:asset-catalog-client')
     implementation project(':open-metadata-implementation:access-services:asset-consumer:asset-consumer-client')
     implementation project(':open-metadata-implementation:access-services:asset-lineage:asset-lineage-client')
@@ -99,7 +99,7 @@ dependencies {
     implementation project(':open-metadata-implementation:admin-services:admin-services-client')
     implementation project(':open-metadata-implementation:user-interfaces:ui-chassis:ui-chassis-spring')
     implementation project(':open-metadata-conformance-suite:open-metadata-conformance-suite-client')
-    implementation project(':open-metadata-resources:open-metadata-samples:admin-services-samples:admin-services-config-metadata-server-sample')
+    implementation project(':open-metadata-resources:open-metadata-samples:admin-services-samples:config-metadata-server-sample')
     implementation project(':open-metadata-resources:open-metadata-archives:open-metadata-types-utility')
     implementation project(':open-metadata-resources:open-metadata-archives:open-connector-archives')
     implementation project(':open-metadata-resources:open-metadata-archives:design-model-archives:glossary-canonical-model')
@@ -216,8 +216,8 @@ distributions {
                 from { project(':open-metadata-resources:open-metadata-samples:access-services-samples:governance-program-client-samples:governance-leadership-sample').shadowJar }
                 from { project(':open-metadata-resources:open-metadata-samples:access-services-samples:governance-program-client-samples:governance-subject-area-sample').shadowJar }
                 from { project(':open-metadata-resources:open-metadata-samples:access-services-samples:governance-program-client-samples:governance-zone-create-sample').shadowJar }
-                from { project(':open-metadata-resources:open-metadata-samples:access-services-samples:subject-area-client-samples:subject-area-definition-sample').shadowJar }
-                from { project(':open-metadata-resources:open-metadata-samples:admin-services-samples:admin-services-config-metadata-server-sample').shadowJar }
+                from { project(':open-metadata-resources:open-metadata-samples:access-services-samples:subject-area-client-samples:subject-area-categories-sample').shadowJar }
+                from { project(':open-metadata-resources:open-metadata-samples:admin-services-samples:config-metadata-server-sample').shadowJar }
                 fileMode = 0755
             }
             into('user-interface') {