meadow-integration 1.0.5 → 1.0.6

package/docs/api/clone-rest-client.md

@@ -0,0 +1,278 @@
+# MeadowCloneRestClient
+
+REST client for communicating with a remote Meadow API server. Provides authentication, session management, CRUD operations, and paginated entity set downloads for the data-clone pipeline.
+
+**Source:** `source/services/clone/Meadow-Service-RestClient.js`
+
+**Extends:** `fable-serviceproviderbase`
+
+**Service Type:** `MeadowCloneRestClient`
+
+## Constructor
+
+```js
+const restClient = fable.serviceManager.instantiateServiceProvider('MeadowCloneRestClient', pOptions);
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `DownloadBatchSize` | `number` | `100` | Number of records per page when downloading entity sets. |
+| `ServerURL` | `string` | `'https://localhost:8080/1.0/'` | Base URL for all API requests. |
+| `UserID` | `string\|false` | `false` | Username for authentication. If `false`, `authenticate()` is a no-op. |
+| `Password` | `string\|false` | `false` | Password for authentication. If `false`, `authenticate()` is a no-op. |
+| `SessionToken` | `string` | *(none)* | Optional pre-existing session token to use instead of authenticating. |
+
+## Properties
+
+### `session`
+
+*Getter* -- Returns the current session data object, or `false` if not authenticated.
+
+### `loggedIn`
+
+*Getter* -- Returns `boolean`. `true` after a successful call to `authenticate()`, `false` after `deauthenticate()` or before login.
+
+### `serverURL`
+
+The base URL string used for all API requests.
+
+### `cache`
+
+Object map of per-entity `ObjectCache` instances. Populated automatically by `getEntity()` and `getEntitySet()`.
+
+## Methods
+
+### `authenticate(fCallback)`
+
+Authenticates with the Meadow API server using the configured `UserID` and `Password`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | `function(pError, pSessionData)` | Callback with the session data on success. |
+
+Posts to `{ServerURL}/Authenticate` with `{ UserName, Password }`. On success, stores session data and sets a `UserSession` cookie for subsequent requests.
+
+If `UserID` or `Password` is falsy, authentication is skipped and the callback is invoked immediately.
+
+### `deauthenticate(fCallback)`
+
+Logs out from the Meadow API server and clears session data.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | `function(pError, pSessionData)` | Callback invoked after logout. `pSessionData` will be `false`. |
+
+### `getJSON(pURL, fCallback)`
+
+Performs a GET request for JSON data at the given URL path (appended to `ServerURL`).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pURL` | `string` | URL path appended to `ServerURL`. |
+| `fCallback` | `function(pError, pResponse, pBody)` | Standard REST callback. |
+
+### `createEntity(pEntity, pRecord, fCallback)`
+
+Creates a new entity record on the server via POST.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name (e.g. `'Animal'`). |
+| `pRecord` | `object` | Record data to create. |
+| `fCallback` | `function(pError, pBody)` | Callback with the created record body. |
+
+### `updateEntity(pEntity, pRecord, fCallback)`
+
+Updates an existing entity record on the server via PUT.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pRecord` | `object` | Record data to update (must include the identifier). |
+| `fCallback` | `function(pError, pBody)` | Callback with the updated record body. |
+
+### `upsertEntity(pEntity, pRecord, fCallback)`
+
+Creates or updates an entity record on the server via PUT to the `/Upsert` endpoint.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pRecord` | `object` | Record data to upsert. |
+| `fCallback` | `function(pError, pBody)` | Callback with the upserted record body. |
+
+### `deleteEntity(pEntity, pIDRecord, fCallback)`
+
+Deletes an entity record by ID from the server via DELETE.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pIDRecord` | `number\|string` | The ID of the record to delete. |
+| `fCallback` | `function(pError, pBody)` | Callback with the response body. |
+
+### `getEntity(pEntity, pIDRecord, fCallback)`
+
+Retrieves a single entity record by ID. Uses an in-memory cache (max age 30s, max 10000 entries) to avoid redundant requests.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pIDRecord` | `number\|string` | The ID of the record to retrieve. |
+| `fCallback` | `function(pError, pBody)` | Callback with the record body (from cache or server). |
+
+### `getEntitySet(pEntity, pMeadowFilterExpression, fCallback)`
+
+Downloads a full set of entity records matching a Meadow filter expression. Automatically paginates using `DownloadBatchSize`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pMeadowFilterExpression` | `string` | Meadow filter expression (e.g. `'FBV~Deleted~EQ~0'`). |
+| `fCallback` | `function(pError, pEntitySet)` | Callback with the full array of records. |
+
+**Algorithm:**
+1. Requests the count from `{Entity}s/Count/FilteredTo/{Filter}`.
+2. Generates paginated URL fragments based on `DownloadBatchSize`.
+3. Downloads each page sequentially and concatenates results.
+
+### `setSessionToken(pSessionToken)`
+
+Manually sets the session token for subsequent requests. The token is appended as a `SessionToken` query parameter when no session data cookie is present.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pSessionToken` | `string` | The session token string. |
+
+### `setSessionData(pSessionData)`
+
+Sets session data and configures the `UserSession` cookie on the underlying REST client.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pSessionData` | `object` | Session data object. If it has a `SessionID` property, that value is used as the cookie. |
+
+### `resetSessionData()`
+
+Clears all session data and cookies. Called internally by `deauthenticate()`.
+
+## Usage Examples
+
+### Authentication and Reading Entities
+
+```js
+const libFable = require('fable');
+const libRestClient = require('meadow-integration/source/services/clone/Meadow-Service-RestClient');
+
+const fable = new libFable({ Product: 'CloneApp' });
+
+fable.serviceManager.addServiceType('MeadowCloneRestClient', libRestClient);
+const restClient = fable.serviceManager.instantiateServiceProvider('MeadowCloneRestClient',
+	{
+		ServerURL: 'https://api.example.com/1.0/',
+		UserID: 'sync_user',
+		Password: 'sync_password',
+		DownloadBatchSize: 250
+	});
+
+restClient.authenticate(
+	(pError, pSessionData) =>
+	{
+		if (pError)
+		{
+			console.error('Auth failed:', pError.message);
+			return;
+		}
+		console.log('Logged in:', restClient.loggedIn);
+		console.log('Session ID:', pSessionData.SessionID);
+	});
+```
+
+### Reading a Single Entity
+
+```js
+restClient.getEntity('Animal', 42,
+	(pError, pRecord) =>
+	{
+		if (pError)
+		{
+			console.error('Read failed:', pError.message);
+			return;
+		}
+		console.log('Animal name:', pRecord.Name);
+	});
+```
+
+### Downloading a Filtered Entity Set
+
+```js
+restClient.getEntitySet('Animal', 'FBV~Deleted~EQ~0',
+	(pError, pRecords) =>
+	{
+		if (pError)
+		{
+			console.error('Download failed:', pError.message);
+			return;
+		}
+		console.log(`Downloaded ${pRecords.length} animals.`);
+
+		for (const tmpRecord of pRecords)
+		{
+			console.log(`  ${tmpRecord.IDAnimal}: ${tmpRecord.Name}`);
+		}
+	});
+```
+
+### Using a Pre-existing Session Token
+
+```js
+const restClient = fable.serviceManager.instantiateServiceProvider('MeadowCloneRestClient',
+	{
+		ServerURL: 'https://api.example.com/1.0/',
+		SessionToken: 'abc-123-def-456'
+	});
+
+// No need to call authenticate() -- the token is appended automatically
+restClient.getJSON('Animal/1',
+	(pError, pResponse, pBody) =>
+	{
+		console.log('Record:', pBody);
+	});
+```
+
+### Upserting and Deleting Records
+
+```js
+// Upsert
+restClient.upsertEntity('Animal', { GUIDAnimal: 'ANIMAL-001', Name: 'Felix', Type: 'Cat' },
+	(pError, pBody) =>
+	{
+		console.log('Upserted:', pBody);
+	});
+
+// Delete
+restClient.deleteEntity('Animal', 42,
+	(pError, pBody) =>
+	{
+		console.log('Deleted:', pBody);
+	});
+```
+
+### Deauthentication
+
+```js
+restClient.deauthenticate(
+	(pError) =>
+	{
+		console.log('Logged out. Session:', restClient.session); // false
+	});
+```
+
+## Related Services
+
+- [MeadowConnectionManager](./connection-manager.md) -- Manages the local database connection pool.
+- [MeadowSync](./sync.md) -- Orchestrator that uses this REST client to download records from the server.
+- [MeadowSyncEntityInitial](./sync-entity-initial.md) -- Uses this client to fetch max IDs, counts, and paginated record sets.
+- [MeadowSyncEntityOngoing](./sync-entity-ongoing.md) -- Uses this client for update-based differential sync.

package/docs/api/connection-manager.md

@@ -0,0 +1,179 @@
+# MeadowConnectionManager
+
+Database connection manager supporting MySQL and MSSQL providers for the meadow data-clone services.
+
+**Source:** `source/services/clone/Meadow-Service-ConnectionManager.js`
+
+**Extends:** `fable-serviceproviderbase`
+
+**Service Type:** `MeadowConnectionManager`
+
+## Constructor
+
+```js
+const connectionManager = fable.serviceManager.instantiateServiceProvider('MeadowConnectionManager', pOptions);
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `Provider` | `string` | `'MySQL'` | Database provider to use. Supported values: `'MySQL'`, `'MSSQL'`. |
+| `MySQL` | `object` | *(see below)* | MySQL-specific connection configuration. |
+| `MySQL.server` | `string` | `'127.0.0.1'` | MySQL server hostname. |
+| `MySQL.port` | `number` | `3306` | MySQL server port. |
+| `MySQL.user` | `string` | `'root'` | MySQL authentication user. |
+| `MySQL.password` | `string` | `''` | MySQL authentication password. |
+| `MySQL.database` | `string` | `'meadow'` | MySQL database name. |
+| `MySQL.connectionLimit` | `number` | `20` | Maximum number of connections in the MySQL pool. |
+| `MSSQL` | `object` | *(see below)* | MSSQL-specific connection configuration. |
+| `MSSQL.server` | `string` | `'127.0.0.1'` | MSSQL server hostname. |
+| `MSSQL.port` | `number` | `1433` | MSSQL server port. |
+| `MSSQL.user` | `string` | `'sa'` | MSSQL authentication user. |
+| `MSSQL.password` | `string` | `''` | MSSQL authentication password. |
+| `MSSQL.database` | `string` | `'meadow'` | MSSQL database name. |
+| `MSSQL.ConnectionPoolLimit` | `number` | `20` | Maximum number of connections in the MSSQL pool. |
+
+## Properties
+
+### `connected`
+
+*Getter* -- Returns `boolean`.
+
+Indicates whether the connection manager has successfully established a connection to the database.
+
+### `ConnectionPool`
+
+The underlying database connection pool object. Set to `false` before `connect()` is called. After a successful connection, holds the provider-specific pool instance.
+
+### `Provider`
+
+The active database provider string (`'MySQL'` or `'MSSQL'`).
+
+## Methods
+
+### `connect(fCallback)`
+
+Establishes a connection to the database using the configured provider.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | `function(pError, pConnectionPool)` | Callback invoked when the connection attempt completes. On success, `pConnectionPool` is the active pool. |
+
+**Behavior:**
+- For `MySQL`: Requires the `meadow-connection-mysql` package. Registers and instantiates a `MeadowMySQLProvider` service, then calls `connectAsync`. Also applies `connectionLimit` to `fable.settings`.
+- For `MSSQL`: Requires the `meadow-connection-mssql` package. Registers and instantiates a `MeadowMSSQLProvider` service, then calls `connectAsync`.
+- For unsupported providers: Calls back with an `Error`.
+
+### `createIndex(pEntitySchema, pColumn, pIsUnique, fCallback)`
+
+Creates a database index on the specified column for the given entity, if the index does not already exist.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntitySchema` | `object` | Entity schema object. Must have a `TableName` property. |
+| `pColumn` | `object` | Column descriptor object. Must have a `Column` property (string). |
+| `pIsUnique` | `boolean` | If `true`, creates a unique index. |
+| `fCallback` | `function(pError)` | Callback invoked when the index creation attempt completes. |
+
+**Index naming convention (MySQL):** `AK_{TableName}_{ColumnName}`
+
+**Provider-specific behavior:**
+- **MySQL:** Checks `INFORMATION_SCHEMA.STATISTICS` for an existing index before creating. Silently ignores `ER_DUP_KEYNAME` errors.
+- **MSSQL:** Uses `IF NOT EXISTS(SELECT * FROM sys.indexes ...)` to conditionally create. Errors are logged but not passed to the callback (the callback always succeeds).
+
+## Usage Examples
+
+### MySQL Connection
+
+```js
+const libFable = require('fable');
+const libConnectionManager = require('meadow-integration/source/services/clone/Meadow-Service-ConnectionManager');
+
+const fable = new libFable({ Product: 'MyApp' });
+
+fable.serviceManager.addServiceType('MeadowConnectionManager', libConnectionManager);
+const connectionManager = fable.serviceManager.instantiateServiceProvider('MeadowConnectionManager',
+	{
+		Provider: 'MySQL',
+		MySQL:
+		{
+			server: 'db.example.com',
+			port: 3306,
+			user: 'app_user',
+			password: 'secret',
+			database: 'production',
+			connectionLimit: 10
+		}
+	});
+
+connectionManager.connect(
+	(pError, pConnectionPool) =>
+	{
+		if (pError)
+		{
+			console.error('Connection failed:', pError.message);
+			return;
+		}
+		console.log('Connected:', connectionManager.connected); // true
+		// pConnectionPool is now available for queries
+	});
+```
+
+### MSSQL Connection
+
+```js
+const fable = new libFable({ Product: 'MyApp' });
+
+fable.serviceManager.addServiceType('MeadowConnectionManager', libConnectionManager);
+const connectionManager = fable.serviceManager.instantiateServiceProvider('MeadowConnectionManager',
+	{
+		Provider: 'MSSQL',
+		MSSQL:
+		{
+			server: 'sql.example.com',
+			port: 1433,
+			user: 'sa',
+			password: 'secret',
+			database: 'production',
+			ConnectionPoolLimit: 20
+		}
+	});
+
+connectionManager.connect(
+	(pError, pConnectionPool) =>
+	{
+		if (pError)
+		{
+			console.error('MSSQL connection failed:', pError.message);
+			return;
+		}
+		console.log('Connected to MSSQL:', connectionManager.connected);
+	});
+```
+
+### Creating an Index
+
+```js
+const entitySchema = { TableName: 'Animal' };
+const guidColumn = { Column: 'GUIDAnimal', DataType: 'GUID' };
+
+connectionManager.createIndex(entitySchema, guidColumn, true,
+	(pError) =>
+	{
+		if (pError)
+		{
+			console.error('Index creation failed:', pError.message);
+			return;
+		}
+		// Index AK_Animal_GUIDAnimal now exists
+		console.log('Index created successfully.');
+	});
+```
+
+## Related Services
+
+- [MeadowCloneRestClient](./clone-rest-client.md) -- REST client for communicating with the remote Meadow API server.
+- [MeadowSync](./sync.md) -- Orchestrates full entity synchronization using a ConnectionManager pool.
+- [MeadowSyncEntityInitial](./sync-entity-initial.md) -- Initial sync uses the connection pool for table and index creation.
+- [MeadowSyncEntityOngoing](./sync-entity-ongoing.md) -- Ongoing sync uses the connection pool for table and index creation.

package/docs/api/guid-map.md

@@ -0,0 +1,234 @@
+# MeadowGUIDMap
+
+In-memory bidirectional mapping service between Meadow GUIDs, Meadow IDs, and external system GUIDs. Used by the integration adapter to resolve entity references across system boundaries.
+
+**Source:** `source/Meadow-Service-Integration-GUIDMap.js`
+
+**Extends:** `fable-serviceproviderbase`
+
+**Service Type:** `MeadowGUIDMap`
+
+## Constructor
+
+```js
+const guidMap = fable.addAndInstantiateServiceType('MeadowGUIDMap', libMeadowGUIDMap);
+```
+
+The `MeadowGUIDMap` is typically instantiated automatically by `MeadowIntegrationAdapter` if one does not already exist on the Fable instance.
+
+### Options
+
+The default options object is empty. No configuration is currently required.
+
+## Internal Data Structures
+
+The GUIDMap maintains three parallel in-memory maps, each keyed by entity name:
+
+| Map | Description |
+|-----|-------------|
+| `_GUIDMap` | `{ Entity: { MeadowGUID: MeadowID } }` -- Maps Meadow GUIDs to numeric IDs. |
+| `_IDMap` | `{ Entity: { MeadowID: MeadowGUID } }` -- Reverse map of numeric IDs to Meadow GUIDs. |
+| `_ExternalGUIDMap` | `{ Entity: { ExternalGUID: MeadowGUID } }` -- Maps external system GUIDs to Meadow GUIDs. |
+
+## Methods
+
+### `addEntity(pEntity)`
+
+Initializes the mapping tables for a given entity if they do not already exist.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name (e.g. `'Customer'`). |
+
+**Returns:** `true`
+
+Called automatically by other methods when an entity is encountered for the first time.
+
+### `mapGUIDToID(pEntity, pGUID, pID)`
+
+Stores a bidirectional mapping between a Meadow GUID and its numeric ID.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pGUID` | `string` | The Meadow GUID value. |
+| `pID` | `number\|string` | The numeric ID value. |
+
+**Returns:** `true`
+
+Updates both `_GUIDMap[Entity][GUID] = ID` and `_IDMap[Entity][ID] = GUID`.
+
+### `getIDFromGUID(pEntity, pGUID)`
+
+Looks up the numeric ID for a given Meadow GUID.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pGUID` | `string` | The Meadow GUID to look up. |
+
+**Returns:** `number|string|false` -- The ID if found, or `false` if the GUID is not mapped.
+
+### `getIDFromGUIDAsync(pEntity, pGUID, fCallback)`
+
+Asynchronous version of `getIDFromGUID`. If the GUID is not in the local map, attempts to fetch the record from the server via `fable.MeadowRestClient.getEntityByGUID()`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pGUID` | `string` | The Meadow GUID to look up. |
+| `fCallback` | `function(pError, pID)` | Callback with the ID if found, or `false`. |
+
+If the record is fetched from the server, the GUID-to-ID mapping is stored for future lookups.
+
+### `getGUIDFromID(pEntity, pID)`
+
+Looks up the Meadow GUID for a given numeric ID.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pID` | `number\|string` | The numeric ID to look up. |
+
+**Returns:** `string|false` -- The GUID if found, or `false` if the ID is not mapped.
+
+### `mapExternalGUIDtoMeadowGUID(pEntity, pExternalGUID, pMeadowGUID)`
+
+Stores a one-directional mapping from an external system GUID to a Meadow GUID.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pExternalGUID` | `string` | The external system's GUID value. |
+| `pMeadowGUID` | `string` | The corresponding Meadow GUID. |
+
+**Returns:** `true`
+
+### `getMeadowGUIDFromExternalGUID(pEntity, pExternalGUID)`
+
+Looks up the Meadow GUID for a given external system GUID.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pExternalGUID` | `string` | The external system's GUID to look up. |
+
+**Returns:** `string|false` -- The Meadow GUID if found, or `false`.
+
+### `getMeadowIDFromExternalGUID(pEntity, pExternalGUID)`
+
+Resolves an external system GUID all the way to a Meadow numeric ID by chaining `getMeadowGUIDFromExternalGUID()` and `getIDFromGUID()`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pEntity` | `string` | Entity name. |
+| `pExternalGUID` | `string` | The external system's GUID to resolve. |
+
+**Returns:** `number|string|false` -- The Meadow ID if both mappings exist, or `false`.
+
+## Usage Examples
+
+### Basic GUID-to-ID Mapping
+
+```js
+const libFable = require('fable');
+const libGUIDMap = require('meadow-integration/source/Meadow-Service-Integration-GUIDMap');
+
+const fable = new libFable({ Product: 'Mapper' });
+const guidMap = fable.addAndInstantiateServiceType('MeadowGUIDMap', libGUIDMap);
+
+// Store a mapping
+guidMap.mapGUIDToID('Customer', 'INTG-CUST-001', 42);
+
+// Look up by GUID
+const id = guidMap.getIDFromGUID('Customer', 'INTG-CUST-001');
+console.log(id); // 42
+
+// Look up by ID (reverse)
+const guid = guidMap.getGUIDFromID('Customer', 42);
+console.log(guid); // 'INTG-CUST-001'
+```
+
+### External GUID Resolution Chain
+
+```js
+// Step 1: Map external GUID to Meadow GUID
+guidMap.mapExternalGUIDtoMeadowGUID('Customer', 'CRM-42', 'INTG-DEF-E-Customer-CRM-42');
+
+// Step 2: Map Meadow GUID to Meadow ID (done by the adapter after server upsert)
+guidMap.mapGUIDToID('Customer', 'INTG-DEF-E-Customer-CRM-42', 100);
+
+// Step 3: Resolve external GUID directly to Meadow GUID
+const meadowGUID = guidMap.getMeadowGUIDFromExternalGUID('Customer', 'CRM-42');
+console.log(meadowGUID); // 'INTG-DEF-E-Customer-CRM-42'
+
+// Step 4: Resolve external GUID all the way to Meadow ID
+const meadowID = guidMap.getMeadowIDFromExternalGUID('Customer', 'CRM-42');
+console.log(meadowID); // 100
+```
+
+### Cross-Entity Reference Resolution
+
+```js
+// After integrating Customers, their mappings exist
+guidMap.mapExternalGUIDtoMeadowGUID('Customer', 'CRM-42', 'INTG-DEF-E-Customer-CRM-42');
+guidMap.mapGUIDToID('Customer', 'INTG-DEF-E-Customer-CRM-42', 100);
+
+// When integrating Orders, resolve the Customer reference
+const customerID = guidMap.getMeadowIDFromExternalGUID('Customer', 'CRM-42');
+console.log(customerID); // 100
+
+// The adapter uses this to set IDCustomer on the Order record
+const orderRecord = {
+	GUIDOrder: 'INTG-DEF-E-Order-ORD-500',
+	IDCustomer: customerID,
+	Total: 99.99
+};
+```
+
+### Async GUID Lookup (Server Fallback)
+
+```js
+guidMap.getIDFromGUIDAsync('Customer', 'INTG-DEF-E-Customer-CRM-99',
+	(pError, pID) =>
+	{
+		if (pError)
+		{
+			console.error('Lookup failed:', pError.message);
+			return;
+		}
+		if (pID)
+		{
+			console.log('Found Customer ID:', pID);
+		}
+		else
+		{
+			console.log('Customer not found on server.');
+		}
+	});
+```
+
+## Mapping Flow Diagram
+
+```
+External System              MeadowGUIDMap                 Meadow Server
+---------------              -------------                 -------------
+CRM-42          --mapExternalGUIDtoMeadowGUID-->
+                INTG-DEF-E-Customer-CRM-42
+                              --mapGUIDToID-->
+                              GUID: INTG-DEF-E-Customer-CRM-42  =>  ID: 100
+
+Later lookups:
+getMeadowGUIDFromExternalGUID('Customer', 'CRM-42')
+  => 'INTG-DEF-E-Customer-CRM-42'
+
+getMeadowIDFromExternalGUID('Customer', 'CRM-42')
+  => 100
+
+getGUIDFromID('Customer', 100)
+  => 'INTG-DEF-E-Customer-CRM-42'
+```
+
+## Related Services
+
+- [MeadowIntegrationAdapter](./integration-adapter.md) -- The primary consumer; uses GUIDMap for all GUID resolution during record marshaling and upsert.