Merge pull request #830 from mandy-chessell/dev-dojo

Extend external identifiers

site/docs/release-notes/4-3.md

@@ -4,8 +4,7 @@
 
 ## Release 4.3 (expected September 2023)
 
-_**These are DRAFT release notes, initially copied from the previous release
-The notes will be updated until & when 4.3 is released**_
+_**These are DRAFT release notes.  The notes will be updated until & when 4.3 is released**_
 
 ??? functional "Open Metadata Types"
     * The  [*HostClusterMember*](/types/0/0035-Complex-Hosts) relationship has new properties *memberRole* and *additionalProperties* to improve ability to describe a host cluster operation.

site/docs/types/0/0017-External-Identifiers.md

@@ -3,18 +3,23 @@
 
 # 0017 External Identifiers
 
-External identifiers are used to correlate the identifiers used in third party metadata catalogs with open metadata elements.
+External identifiers are used to correlate the identifiers used in third party systems with open metadata elements.  
 
 ![UML](0017-External-Identifiers.svg)
 
-## ExternalId
+## ExternalId entity
 
-The *`ExternalId`* entity describes an external identifier from a specific third party metadata repository. It includes:
+The *ExternalId* entity describes an external identifier from a specific third party system. It includes:
 
-- The identifier value itself in `identifier`.
-- The pattern used for the identifier (how it is generated and managed) is stored in `keyPattern`. 
+* *identifier* - the unique identifier of the element in the third party metadata repository.
+* *keyPattern* - The pattern used for the identifier (how it is generated and managed) is stored in the *KeyPattern* enumeration. 
+* *externalInstanceCreatedBy* - the username of the person or process that created the instance in the external system.
+* *externalInstanceCreationTime* - the date/time when the instance in the external system was created.
+* *externalInstanceLastUpdatedBy* - the username of the person or process that last updated the instance in the external system.
+* *externalInstanceLastUpdateTime* - the date/time that the instance in the external system was last updated.
+* *externalInstanceVersion* - the latest version of the element in the external system.
 
-## KeyPattern
+## KeyPattern enumeration
 
 *KeyPattern* describes the pattern used for the identifier (how it is generated and managed). These are the values it can take, with the default (and most used) being `LOCAL_KEY`:  
 
@@ -30,17 +35,17 @@ The *`ExternalId`* entity describes an external identifier from a specific third
 | OTHER         | 99    | "Other"          | Another key pattern.                                                                                          |
 
 
-## ExternalIdLink
+## ExternalIdLink relationship
 
-The mapping of identifiers can be many-to-many, which is why you see that the *`ExternalIdLink`* relationship between the [`OpenMetadataRoot`](/types/0/0010-Base-Model/#openmetadataroot) (open metadata resources) and the `ExternalId` is also many-to-many.
+The mapping of identifiers can be many-to-many, which is why you see that the *ExternalIdLink* relationship between the [*OpenMetadataRoot*](/types/0/0010-Base-Model/#openmetadataroot) (open metadata resources) and the *ExternalId* entity is also many-to-many.
 
-This relationship includes properties to help to map the `OpenMetadataRoot` to the external identifier.
+This relationship includes properties to help to map the *OpenMetadataRoot* entity to the external identifier.
 
-## ExternalIdScope
+## ExternalIdScope relationship
 
-There is no guarantee that external identifiers from a third party metadata catalog are globally unique and so the *`ExternalIdScope`* relationship links the external identifier to the [`Referenceable`](/types/0/0010-Base-Model/#referenceable) that represents the third party metadata catalog. Typically, this is a type of [`SoftwareCapability`](/types/0/0042-Software-Capabilities/#softwarecapability), for example, [`AssetManager`](/types/0/0056-Resource-Managers/#assetmanager).
+There is no guarantee that external identifiers from a third party metadata catalog are globally unique and so the *ExternalIdScope* relationship links the external identifier to the [Referenceable](/types/0/0010-Base-Model/#referenceable) that represents the third party system. Typically, this is a type of [SoftwareCapability](/types/0/0042-Software-Capabilities/#softwarecapability), for example, [AssetManager](/types/0/0056-Resource-Managers/#assetmanager).
 
-## PermittedSynchronization
+## PermittedSynchronization enumeration
 
 *PermittedSynchronization* defines the direction of flow of metadata.
 
@@ -51,6 +56,22 @@ There is no guarantee that external identifiers from a third party metadata cata
 | FROM_THIRD_PARTY | 2     | "From Third Party" | The third party technology is logically upstream (the originator and owner of the metadata).  Any updates made in open metadata are not passed to the third party technology and the third party technology is requested to refresh the open metadata version.                              |
 | OTHER            | 99    | "Other"          | Another type of synchronization rule - see description property.                                                                                                                                                                                                                            |
 
+## Example
+
+The picture below shows the value of the external identifiers in providing traceability between metadata elements in different systems.  
+
+Starting on the left-hand side of the diagram is a [SoftwareCapability](/types/0/0042-Software-Capabilies) entity representing an Apache Atlas server.  
+
+Following the *ExternalIdScope* relationships takes you to the identifiers of all the Apache Atlas entities that have been synchronized into the open metadata ecosystem.  
+
+From one of the *ExternalId* entities it is possible to navigate to the open metadata entity/entities that store the equivalent metadata by following the *ExternalIdLink* relationships.  
+
+An open metadata ecosystem entity may have been synchronized with multiple third party systems.  Following all the *ExternalIdLink* relationships from such an open metadata entity creates a list of external identifiers for each of the third party systems it has been synchronized with.  In this example, the glossary term has been synchronized with Apache Atlas and DataHub servers.  The *lastSynchronized* property in the *externalIdLink* documents when Egeria last checked for updates from the associated third party system.  The other properties in the *ExternalId* entity provide more detail about the element in the third party system.
+
+![Example](external-identifier-example.svg)
+
+
+
 ??? education "Further information"
     There is an article on [managing external identifiers](/features/external-identifiers/overview) to correlate metadata elements from different types of technologies.