@zohodesk/i18n 1.0.0-beta.34 → 1.0.0-beta.35-murphy

package/docs/murphy/03-MURPHY_BACKEND_CONFIG.md

@@ -0,0 +1,337 @@
+# Murphy Backend Configuration
+
+## Overview
+
+Murphy configuration originates from the Java backend and flows to the JavaScript client through server-rendered HTML. This ensures each datacenter uses the correct Murphy instance automatically.
+
+---
+
+## Configuration Flow Diagram
+
+```
++-------------------------------------------------------------------+
+|                    BACKEND CONFIGURATION FLOW                      |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Step 1: Properties File (Region-specific credentials)            |
+|  +--------------------------------------------------------------+ |
+|  |  /product_package/conf/ZohoSupport/dcurl.properties          | |
+|  |                                                               | |
+|  |  # US Datacenter                                              | |
+|  |  dcurl.desk.murphy.appkey_US = 755747375                     | |
+|  |  dcurl.desk.murphy.appdomain_US = murphy.zoho.com            | |
+|  |  dcurl.desk.murphy.authKey_US = BPEEOUVxexAB...              | |
+|  |                                                               | |
+|  |  # JP Datacenter                                              | |
+|  |  dcurl.desk.murphy.appkey_JP = 90001069766                   | |
+|  |  dcurl.desk.murphy.appdomain_JP = murphy.zoho.jp             | |
+|  |  dcurl.desk.murphy.authKey_JP = TNYW...                      | |
+|  |                                                               | |
+|  |  # IN Datacenter                                              | |
+|  |  dcurl.desk.murphy.appkey_IN = 60013588960                   | |
+|  |  dcurl.desk.murphy.appdomain_IN = murphy.zoho.in             | |
+|  |  dcurl.desk.murphy.authKey_IN = ...                          | |
+|  |                                                               | |
+|  +--------------------------------------------------------------+ |
+|                              |                                     |
+|                              v                                     |
+|  Step 2: Constants Class (Load into Java constants)               |
+|  +--------------------------------------------------------------+ |
+|  |  MurphyConstants.java                                        | |
+|  |  /com/adventnet/support/common/util/MurphyConstants.java     | |
+|  |                                                               | |
+|  |  public class MurphyConstants {                              | |
+|  |    public static final String APP_KEY =                      | |
+|  |      Configuration.getString("dcurl.desk.murphy.appkey");    | |
+|  |    public static final String AUTH_KEY =                     | |
+|  |      Configuration.getString("dcurl.desk.murphy.authKey");   | |
+|  |    public static final String APP_DOMAIN =                   | |
+|  |      Configuration.getString("dcurl.desk.murphy.appdomain"); | |
+|  |  }                                                            | |
+|  +--------------------------------------------------------------+ |
+|                              |                                     |
+|                              v                                     |
+|  Step 3: Client Injection (Embed in HTML response)                |
+|  +--------------------------------------------------------------+ |
+|  |  ClientInitUtil.java                                         | |
+|  |  /com/zoho/desk/client/util/ClientInitUtil.java              | |
+|  |                                                               | |
+|  |  public static JSONObject getDeskUrls(HttpServletRequest) {  | |
+|  |    JSONObject deskUrls = new JSONObject();                   | |
+|  |    deskUrls.put("murphyAppKey", MurphyConstants.APP_KEY);    | |
+|  |    deskUrls.put("murphyAppDomain", MurphyConstants.APP_DOMAIN);|
+|  |    deskUrls.put("murphyAuthKey", MurphyConstants.AUTH_KEY);  | |
+|  |    return deskUrls;                                          | |
+|  |  }                                                            | |
+|  +--------------------------------------------------------------+ |
+|                              |                                     |
+|                              v                                     |
+|  Step 4: HTML Output (Server-rendered script tag)                 |
+|  +--------------------------------------------------------------+ |
+|  |  index.html (generated)                                      | |
+|  |                                                               | |
+|  |  <script nonce="abc123">                                     | |
+|  |    var desk_urls = {                                         | |
+|  |      murphyAppKey: "755747375",                              | |
+|  |      murphyAppDomain: "murphy.zoho.com",                     | |
+|  |      murphyAuthKey: "BPEEOUVxexAB..."                        | |
+|  |    };                                                         | |
+|  |  </script>                                                    | |
+|  +--------------------------------------------------------------+ |
+|                                                                    |
++--------------------------------------------------------------------+
+```
+
+---
+
+## 1. dcurl.properties
+
+The `dcurl.properties` file stores Murphy credentials for each datacenter:
+
+### File Location
+```
+/product_package/conf/ZohoSupport/dcurl.properties
+```
+
+### Configuration Format
+```properties
+# Murphy Configuration Pattern:
+# dcurl.desk.murphy.<property>_<DATACENTER> = <value>
+
+# US Datacenter
+dcurl.desk.murphy.appkey_US = 755747375
+dcurl.desk.murphy.appdomain_US = murphy.zoho.com
+dcurl.desk.murphy.authKey_US = BPEEOUVxexABKEY...
+
+# Japan Datacenter
+dcurl.desk.murphy.appkey_JP = 90001069766
+dcurl.desk.murphy.appdomain_JP = murphy.zoho.jp
+dcurl.desk.murphy.authKey_JP = TNYWExampleKey...
+
+# India Datacenter
+dcurl.desk.murphy.appkey_IN = 60013588960
+dcurl.desk.murphy.appdomain_IN = murphy.zoho.in
+dcurl.desk.murphy.authKey_IN = INExampleKey...
+
+# Europe Datacenter
+dcurl.desk.murphy.appkey_EU = ...
+dcurl.desk.murphy.appdomain_EU = murphy.zoho.eu
+dcurl.desk.murphy.authKey_EU = ...
+
+# Australia Datacenter
+dcurl.desk.murphy.appkey_AU = ...
+dcurl.desk.murphy.appdomain_AU = murphy.zoho.com.au
+dcurl.desk.murphy.authKey_AU = ...
+
+# Canada Datacenter
+dcurl.desk.murphy.appkey_CA = ...
+dcurl.desk.murphy.appdomain_CA = murphy.zoho.ca
+dcurl.desk.murphy.authKey_CA = ...
+
+# China Datacenter
+dcurl.desk.murphy.appkey_CN = ...
+dcurl.desk.murphy.appdomain_CN = murphy.zoho.com.cn
+dcurl.desk.murphy.authKey_CN = ...
+
+# Saudi Arabia Datacenter
+dcurl.desk.murphy.appkey_SA = ...
+dcurl.desk.murphy.appdomain_SA = murphy.zoho.sa
+dcurl.desk.murphy.authKey_SA = ...
+```
+
+### Key Properties
+
+| Property | Description |
+|----------|-------------|
+| `appkey` | Unique application identifier in Murphy |
+| `appdomain` | Murphy server domain for the region |
+| `authKey` | Base64 encoded authentication token |
+
+---
+
+## 2. MurphyConstants.java
+
+This class reads the properties file and exposes them as Java constants:
+
+### File Location
+```
+/com/adventnet/support/common/util/MurphyConstants.java
+```
+
+### Code Structure
+```java
+package com.adventnet.support.common.util;
+
+import com.zoho.conf.Configuration;
+
+public class MurphyConstants {
+
+    /**
+     * Murphy application key for this datacenter.
+     * Automatically selects the correct key based on deployment region.
+     */
+    public static final String APP_KEY =
+        Configuration.getString("dcurl.desk.murphy.appkey");
+
+    /**
+     * Murphy authentication key (Base64 encoded).
+     */
+    public static final String AUTH_KEY =
+        Configuration.getString("dcurl.desk.murphy.authKey");
+
+    /**
+     * Murphy server domain for this datacenter.
+     */
+    public static final String APP_DOMAIN =
+        Configuration.getString("dcurl.desk.murphy.appdomain");
+}
+```
+
+### How Region Selection Works
+
+```
++----------------------------------------------------------------+
+|  AUTOMATIC REGION SELECTION                                     |
++----------------------------------------------------------------+
+|                                                                 |
+|  Configuration.getString("dcurl.desk.murphy.appkey")            |
+|                          |                                      |
+|                          v                                      |
+|  +----------------------------------------------------------+  |
+|  |  Zoho Configuration API:                                 |  |
+|  |                                                          |  |
+|  |  1. Detects current datacenter from environment         |  |
+|  |  2. Appends datacenter suffix (_US, _JP, _IN, etc.)     |  |
+|  |  3. Reads dcurl.desk.murphy.appkey_<DC> from properties |  |
+|  +----------------------------------------------------------+  |
+|                          |                                      |
+|                          v                                      |
+|  US Server: Returns "755747375"                                |
+|  JP Server: Returns "90001069766"                              |
+|  IN Server: Returns "60013588960"                              |
+|                                                                 |
++----------------------------------------------------------------+
+```
+
+The developer writes ONE line of code, but it returns DIFFERENT values based on where the server is deployed.
+
+---
+
+## 3. ClientInitUtil.java
+
+This utility class injects Murphy configuration into the HTML response:
+
+### File Location
+```
+/com/zoho/desk/client/util/ClientInitUtil.java
+```
+
+### Code Structure
+```java
+package com.zoho.desk.client.util;
+
+import com.adventnet.support.common.util.MurphyConstants;
+import org.json.JSONObject;
+
+public class ClientInitUtil {
+
+    /**
+     * Creates the desk_urls object that gets embedded in HTML.
+     * This object is accessible to JavaScript as window.desk_urls
+     */
+    public static JSONObject getDeskUrls(HttpServletRequest request) {
+        JSONObject deskUrls = new JSONObject();
+
+        // ... other configuration ...
+
+        // Murphy configuration injection
+        deskUrls.put("murphyAppKey", MurphyConstants.APP_KEY);
+        deskUrls.put("murphyAppDomain", MurphyConstants.APP_DOMAIN);
+        deskUrls.put("murphyAuthKey", MurphyConstants.AUTH_KEY);
+
+        // ... other configuration ...
+
+        return deskUrls;
+    }
+}
+```
+
+### HTML Generation (JSP/Servlet)
+```jsp
+<%@ page import="com.zoho.desk.client.util.ClientInitUtil" %>
+<%
+  JSONObject deskUrls = ClientInitUtil.getDeskUrls(request);
+  String encodedUrls = IAMEncoder.encodeForJavaScript(deskUrls.toString());
+%>
+<script nonce="<%= cspNonce %>">
+  var desk_urls = <%= encodedUrls %>;
+</script>
+```
+
+---
+
+## Security Considerations
+
+### XSS Protection
+```java
+// Values are encoded to prevent XSS attacks
+String encodedUrls = IAMEncoder.encodeForJavaScript(deskUrls.toString());
+```
+
+### Content Security Policy
+```html
+<!-- Script tag uses nonce for CSP compliance -->
+<script nonce="abc123">
+  var desk_urls = {...};
+</script>
+```
+
+### Auth Key Encoding
+```
++------------------------------------------------+
+|  AUTH KEY HANDLING                              |
++------------------------------------------------+
+|                                                 |
+|  Storage:   Base64 encoded in properties file  |
+|  Transport: Embedded in HTML (HTTPS only)      |
+|  Usage:     SDK handles authentication         |
+|                                                 |
++------------------------------------------------+
+```
+
+---
+
+## Summary
+
+```
++-------------------------------------------------------------------+
+|  BACKEND CONFIG SUMMARY                                            |
++-------------------------------------------------------------------+
+|                                                                    |
+|  dcurl.properties                                                  |
+|  +-- Stores credentials per datacenter                            |
+|  +-- Region suffix pattern: _US, _JP, _IN, _EU, etc.              |
+|                                                                    |
+|  MurphyConstants.java                                              |
+|  +-- Reads properties via Configuration API                       |
+|  +-- Auto-detects datacenter from environment                     |
+|  +-- Exposes as static final constants                            |
+|                                                                    |
+|  ClientInitUtil.java                                               |
+|  +-- Creates desk_urls JSON object                                |
+|  +-- Injects Murphy config into HTML response                     |
+|  +-- Handles XSS encoding                                         |
+|                                                                    |
+|  Result: Client JavaScript gets correct Murphy config             |
+|          without knowing which datacenter it's in!                |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Related Documents
+
+- [01-MURPHY_OVERVIEW.md](./01-MURPHY_OVERVIEW.md) - What is Murphy
+- [02-MURPHY_ARCHITECTURE.md](./02-MURPHY_ARCHITECTURE.md) - Full architecture
+- [04-MURPHY_FRONTEND_INIT.md](./04-MURPHY_FRONTEND_INIT.md) - Client initialization