@itentialopensource/adapter-metaswitch 1.0.3 → 1.2.1

package/TAB2.md

@@ -11,7 +11,17 @@
 ## Specific Adapter Information
 ### Authentication
 
-This document will go through the steps for authenticating the Metaswitch adapter with Basic Authentication. Properly configuring the properties for an adapter in Itential Platform is critical for getting the adapter online. You can read more about adapter authentication <a href="https://docs.itential.com/opensource/docs/authentication" target="_blank">HERE</a>. 
+This document will go through the steps for authenticating the Metaswitch adapter with Basic Authentication. Properly configuring the properties for an adapter in Itential Platform is critical for getting the adapter online. You can read more about adapter authentication <a href="https://docs.itential.com/opensource/docs/authentication" target="_blank">HERE</a>.
+
+#### Overview
+
+**Version 1.1.0+** includes automatic SOAP envelope wrapping with WS-Security credentials. The adapter now:
+- Automatically wraps XML payloads in SOAP envelopes
+- Embeds credentials using WS-Security UsernameToken standard
+- Removes the need for workflows to handle SOAP envelopes or credentials
+- Maintains 100% backward compatibility with existing workflows
+
+**Security Enhancement**: Credentials are never exposed in workflow payloads. They are securely stored in adapter configuration and automatically embedded at the adapter level.
 
 #### Basic Authentication
 The Metaswitch adapter requires Basic Authentication. If you change authentication methods, you should change this section accordingly and merge it back into the adapter repository.
@@ -32,7 +42,56 @@ STEPS
 ```
 you can leave all of the other properties in the authentication section, they will not be used when the auth_method is basic user_password.
 
-4. Restart the adapter. If your properties were set correctly, the adapter should go online. 
+4. Restart the adapter. If your properties were set correctly, the adapter should go online.
+
+#### Automatic SOAP Envelope Wrapping (v1.1.0+)
+
+The adapter automatically wraps all XML payloads in SOAP envelopes with WS-Security credentials. This happens transparently at the adapter level.
+
+##### How It Works
+
+**Workflows send XML only:**
+```xml
+<UserDataRequest>
+  <UserId>12345</UserId>
+  <DataReference>RepositoryData</DataReference>
+</UserDataRequest>
+```
+
+**Adapter automatically wraps with SOAP + Credentials:**
+```xml
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+                  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
+  <soapenv:Header>
+    <wsse:Security soapenv:mustUnderstand="1">
+      <wsse:UsernameToken>
+        <wsse:Username>admin</wsse:Username>
+        <wsse:Password Type="...#PasswordText">password</wsse:Password>
+      </wsse:UsernameToken>
+    </wsse:Security>
+  </soapenv:Header>
+  <soapenv:Body>
+    <UserDataRequest>
+      <UserId>12345</UserId>
+      <DataReference>RepositoryData</DataReference>
+    </UserDataRequest>
+  </soapenv:Body>
+</soapenv:Envelope>
+```
+
+##### Key Features
+
+- **Automatic Detection**: If your workflow already sends a SOAP envelope, the adapter detects it and skips wrapping
+- **Zero Migration**: Existing workflows continue working without changes
+- **Secure Credentials**: Username/password from adapter config are automatically embedded
+- **API-Specific**: Correct namespaces applied based on API type (EAS, NSeries, Metaview, NWSAP)
+
+##### Security Best Practices
+
+1. **Always use HTTPS**: Credentials are sent as PasswordText in WS-Security headers
+2. **Restrict adapter access**: Only authorized workflows should call the adapter
+3. **Rotate credentials**: Change passwords periodically in adapter configuration
+4. **Monitor logs**: Review adapter logs for authentication failures
 
 #### Troubleshooting
 - Make sure you copied over the correct username and password.
@@ -45,6 +104,34 @@ you can leave all of the other properties in the authentication section, they wi
 - Credentials should be ** masked ** by the adapter so make sure you verify the username and password - including that there are erroneous spaces at the front or end.
 - Remember when you are done to turn auth_logging off as you do not want to log credentials.
 
+##### SOAP Wrapper Troubleshooting (v1.1.0+)
+
+If you encounter issues with the automatic SOAP wrapping:
+
+**Error: "Empty payload body provided"**
+- The adapter received an empty or null payload
+- Verify your workflow is sending XML content in the body parameter
+
+**Error: "Missing authentication credentials in adapter configuration"**
+- The adapter cannot find username or password in properties.authentication
+- Verify the authentication section is configured correctly (see above)
+
+**Error: "SOAP Envelope Error"**
+- General SOAP wrapping failure
+- Check adapter logs for detailed error messages
+- Verify the XML payload is well-formed
+
+**Existing SOAP envelope not detected:**
+- If your workflow sends a SOAP envelope and it's being double-wrapped:
+  - Ensure the envelope uses one of these prefixes: `soapenv:`, `soap:`, or `SOAP-ENV:`
+  - The detection looks for `<soapenv:Envelope`, `<soap:Envelope`, or `<SOAP-ENV:Envelope`
+
+**Testing SOAP wrapper:**
+- Send a simple XML payload through the adapter
+- Check the FULL REQUEST log to see the generated SOAP envelope
+- Verify credentials are properly embedded in the wsse:Security header
+- Confirm the Metaswitch API accepts the request
+
 ### Sample Properties
 
 Sample Properties can be used to help you configure the adapter in the Itential Platform. You will need to update connectivity information such as the host, port, protocol and credentials.

package/adapter.js

@@ -97,7 +97,12 @@ class Metaswitch extends AdapterBaseCl {
 
     // The generic adapter functions should already be ignored (e.g. healthCheck)
     // you can add specific methods that you do not want to be workflow functions to ignore like below
-    // myIgnore.push('myMethodNotInWorkflow');
+    // Exclude SOAP utility methods from workflow functions
+    myIgnore.push('wrapBodyInSoapEnvelope');
+    myIgnore.push('getSoapNamespaces');
+    myIgnore.push('buildOriginHost');
+    myIgnore.push('injectOriginHost');
+    myIgnore.push('escapeXml');
 
     return super.iapGetAdapterWorkflowFunctions(myIgnore);
   }
@@ -645,6 +650,193 @@ class Metaswitch extends AdapterBaseCl {
     return super.iapGetAdapterInventory(callback);
   }
 
+  /* SOAP SECURITY UTILITY METHODS */
+  /**
+   * @function wrapBodyInSoapEnvelope
+   * @summary Wraps request body in SOAP envelope and injects OriginHost with credentials
+   *
+   * @param {string} body - The inner XML payload (without SOAP envelope and OriginHost)
+   * @param {string} apiType - API type (EAS, NSeries, Metaview, NWSAP) for namespace handling
+   *
+   * @returns {object} Object containing the updated SOAP payload
+   * @returns {string} returns.payload - The complete SOAP envelope with credentials
+   * @returns {Error} returns.error - Error object if parsing or serialization fails
+   */
+  wrapBodyInSoapEnvelope(body, apiType = 'EAS') {
+    const meth = 'adapter-wrapBodyInSoapEnvelope';
+    const origin = `${this.id}-${meth}`;
+    log.trace(origin);
+
+    try {
+      // Validate body is present (before any processing)
+      if (!body || body.trim() === '') {
+        return { error: new Error('Empty payload body provided') };
+      }
+
+      // Detect if payload is already a SOAP envelope (skip wrapping)
+      const trimmedBody = body.trim();
+      if (trimmedBody.includes('<soapenv:Envelope')
+          || trimmedBody.includes('<soap:Envelope')
+          || trimmedBody.includes('<SOAP-ENV:Envelope')) {
+        log.debug(`${origin}: Payload already contains SOAP envelope, skipping wrap`);
+        return { payload: body, alreadyWrapped: true };
+      }
+
+      // Build OriginHost with credentials from adapter properties
+      const originHostResult = this.buildOriginHost();
+      if (originHostResult.error) {
+        return { error: originHostResult.error };
+      }
+
+      // Inject OriginHost into the body XML (append before any closing tags)
+      const bodyWithOriginHost = this.injectOriginHost(body, originHostResult.originHost);
+
+      // Determine namespace based on API type
+      const namespaces = this.getSoapNamespaces(apiType);
+
+      // Construct SOAP envelope with minimal header (Metaswitch pattern)
+      const soapEnvelope = `<soapenv:Envelope ${namespaces}>
+  <soapenv:Header/>
+  <soapenv:Body>${bodyWithOriginHost}</soapenv:Body>
+</soapenv:Envelope>`;
+
+      return { payload: soapEnvelope };
+    } catch (ex) {
+      log.error(`${origin}: Exception wrapping SOAP envelope: ${ex.message}`);
+      return { error: ex };
+    }
+  }
+
+  /**
+   * @function getSoapNamespaces
+   * @summary Returns SOAP namespace declarations for specific Metaswitch API
+   *
+   * @param {string} apiType - API type (EAS, NSeries, Metaview, NWSAP)
+   * @returns {string} Namespace declaration string
+   */
+  // eslint-disable-next-line class-methods-use-this
+  getSoapNamespaces(apiType) {
+    const commonNamespaces = 'xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"';
+
+    // API-specific namespaces based on Metaswitch documentation
+    const apiNamespaces = {
+      EAS: 'xmlns:sh="http://www.metaswitch.com/sdp/soap/sh"',
+      NSeries: 'xmlns:sh="http://www.metaswitch.com/nsrs/soap/sh"',
+      Metaview: 'xmlns:sh="http://www.metaswitch.com/ems/soap/sh"',
+      NWSAP: 'xmlns:sh="http://www.metaswitch.com/srb/soap/sh"'
+    };
+
+    return `${commonNamespaces} ${apiNamespaces[apiType] || apiNamespaces.EAS}`;
+  }
+
+  /**
+   * @function buildOriginHost
+   * @summary Builds OriginHost XML element with credentials from adapter properties
+   *          Following Metaswitch pattern: server@domain?clientVersion=X.X&adminName=XXX&password=YYY
+   *
+   * @returns {object} Object containing the OriginHost XML or error
+   * @returns {string} returns.originHost - The OriginHost XML element
+   * @returns {Error} returns.error - Error object if credentials are missing
+   */
+  buildOriginHost() {
+    const meth = 'adapter-buildOriginHost';
+    const origin = `${this.id}-${meth}`;
+    log.trace(origin);
+
+    try {
+      // Get credentials and connection info from adapter properties
+      const auth = this.allProps.authentication || {};
+      const conn = this.allProps.properties || {};
+
+      // Validate required credentials
+      if (!auth.username || !auth.password) {
+        return { error: new Error('Missing username or password in adapter authentication configuration') };
+      }
+
+      // Build OriginHost value following Metaswitch sample pattern
+      // Format: server@domain?clientVersion=X.X&adminName=XXX&password=YYY&ignoreSequenceNumber=true
+      const server = conn.host || 'server';
+      const domain = conn.domain || 'domain';
+      const clientVersion = conn.clientVersion || '1.0';
+
+      // URL-encode credentials to handle special characters
+      const adminName = encodeURIComponent(auth.username);
+      const password = encodeURIComponent(auth.password);
+
+      const originHostValue = `${server}@${domain}?clientVersion=${clientVersion}&adminName=${adminName}&password=${password}&ignoreSequenceNumber=true`;
+
+      // Return as XML element (will be inserted into SOAP body)
+      const originHostXml = `<OriginHost>${this.escapeXml(originHostValue)}</OriginHost>`;
+
+      log.debug(`${origin}: Built OriginHost for ${server}@${domain} with user ${auth.username}`);
+
+      return { originHost: originHostXml };
+    } catch (ex) {
+      log.error(`${origin}: Exception building OriginHost: ${ex.message}`);
+      return { error: ex };
+    }
+  }
+
+  /**
+   * @function injectOriginHost
+   * @summary Injects OriginHost element into the body XML before closing tags
+   *          Metaswitch expects OriginHost as the last element in ShPull/ShUpdate
+   *
+   * @param {string} body - The XML body content (ShPull or ShUpdate operation)
+   * @param {string} originHost - The OriginHost XML element to inject
+   * @returns {string} Body XML with OriginHost injected
+   */
+  // eslint-disable-next-line class-methods-use-this
+  injectOriginHost(body, originHost) {
+    const meth = 'adapter-injectOriginHost';
+    const origin = `${this.id}-${meth}`;
+    log.trace(origin);
+
+    try {
+      // Find the closing tag of the root element (ShPull, ShUpdate, etc.)
+      // OriginHost should be inserted just before this closing tag
+      const closingTagMatch = body.match(/<\/(sh:)?(ShPull|ShUpdate|ShSubs|ShNotif)>/);
+
+      if (closingTagMatch) {
+        const closingTag = closingTagMatch[0];
+        const insertPosition = body.lastIndexOf(closingTag);
+
+        // Insert OriginHost before the closing tag with proper indentation
+        const modifiedBody = `${body.substring(0, insertPosition)}  ${originHost}\n${body.substring(insertPosition)}`;
+
+        log.debug(`${origin}: Injected OriginHost before ${closingTag}`);
+        return modifiedBody;
+      }
+
+      // If no recognized Metaswitch operation tag found, append at the end
+      // This handles cases where the body is a simple XML fragment
+      log.warn(`${origin}: No recognized Metaswitch operation tag found, appending OriginHost to body`);
+      return `${body}\n${originHost}`;
+    } catch (ex) {
+      log.error(`${origin}: Exception injecting OriginHost: ${ex.message}`);
+      // Return original body if injection fails (fail gracefully)
+      return `${body}\n${originHost}`;
+    }
+  }
+
+  /**
+   * @function escapeXml
+   * @summary Escapes special XML characters in strings
+   *
+   * @param {string} str - String to escape
+   * @returns {string} XML-safe string
+   */
+  // eslint-disable-next-line class-methods-use-this
+  escapeXml(str) {
+    if (!str) return '';
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+
   /**
    * @callback healthCallback
    * @param {Object} result - the result of the get request (contains an id and a status)
@@ -703,11 +895,18 @@ class Metaswitch extends AdapterBaseCl {
       return callback(null, errorObj);
     }
 
+    // Wrap body in SOAP envelope with credentials
+    const soapResult = this.wrapBodyInSoapEnvelope(body, 'EAS');
+    if (soapResult.error) {
+      log.error(`${origin}: SOAP envelope wrapping failed - ${soapResult.error.message}`);
+      const errorObj = this.requestHandlerInst.formatErrorObject(this.id, meth, 'SOAP Envelope Error', null, null, null, soapResult.error);
+      return callback(null, errorObj);
+    }
+
     /* HERE IS WHERE YOU SET THE DATA TO PASS INTO REQUEST */
     const queryParamsAvailable = {};
     const queryParams = {};
     const pathVars = [];
-    const bodyVars = body;
 
     // loop in template. long callback arg name to avoid identifier conflicts
     Object.keys(queryParamsAvailable).forEach((thisKeyInQueryParamsAvailable) => {
@@ -720,7 +919,7 @@ class Metaswitch extends AdapterBaseCl {
     // set up the request object - payload, uriPathVars, uriQuery, uriOptions, addlHeaders, authData, callProperties, filter, priority, event
     // see adapter code documentation for more information on the request object's fields
     const reqObj = {
-      payload: bodyVars,
+      payload: soapResult.payload,
       uriPathVars: pathVars,
       uriQuery: queryParams
     };
@@ -785,11 +984,18 @@ class Metaswitch extends AdapterBaseCl {
       return callback(null, errorObj);
     }
 
+    // Wrap body in SOAP envelope with credentials
+    const soapResult = this.wrapBodyInSoapEnvelope(body, 'NSeries');
+    if (soapResult.error) {
+      log.error(`${origin}: SOAP envelope wrapping failed - ${soapResult.error.message}`);
+      const errorObj = this.requestHandlerInst.formatErrorObject(this.id, meth, 'SOAP Envelope Error', null, null, null, soapResult.error);
+      return callback(null, errorObj);
+    }
+
     /* HERE IS WHERE YOU SET THE DATA TO PASS INTO REQUEST */
     const queryParamsAvailable = {};
     const queryParams = {};
     const pathVars = [];
-    const bodyVars = body;
 
     // loop in template. long callback arg name to avoid identifier conflicts
     Object.keys(queryParamsAvailable).forEach((thisKeyInQueryParamsAvailable) => {
@@ -802,7 +1008,7 @@ class Metaswitch extends AdapterBaseCl {
     // set up the request object - payload, uriPathVars, uriQuery, uriOptions, addlHeaders, authData, callProperties, filter, priority, event
     // see adapter code documentation for more information on the request object's fields
     const reqObj = {
-      payload: bodyVars,
+      payload: soapResult.payload,
       uriPathVars: pathVars,
       uriQuery: queryParams
     };
@@ -867,11 +1073,18 @@ class Metaswitch extends AdapterBaseCl {
       return callback(null, errorObj);
     }
 
+    // Wrap body in SOAP envelope with credentials
+    const soapResult = this.wrapBodyInSoapEnvelope(body, 'Metaview');
+    if (soapResult.error) {
+      log.error(`${origin}: SOAP envelope wrapping failed - ${soapResult.error.message}`);
+      const errorObj = this.requestHandlerInst.formatErrorObject(this.id, meth, 'SOAP Envelope Error', null, null, null, soapResult.error);
+      return callback(null, errorObj);
+    }
+
     /* HERE IS WHERE YOU SET THE DATA TO PASS INTO REQUEST */
     const queryParamsAvailable = {};
     const queryParams = {};
     const pathVars = [];
-    const bodyVars = body;
 
     // loop in template. long callback arg name to avoid identifier conflicts
     Object.keys(queryParamsAvailable).forEach((thisKeyInQueryParamsAvailable) => {
@@ -884,7 +1097,7 @@ class Metaswitch extends AdapterBaseCl {
     // set up the request object - payload, uriPathVars, uriQuery, uriOptions, addlHeaders, authData, callProperties, filter, priority, event
     // see adapter code documentation for more information on the request object's fields
     const reqObj = {
-      payload: bodyVars,
+      payload: soapResult.payload,
       uriPathVars: pathVars,
       uriQuery: queryParams
     };
@@ -949,11 +1162,18 @@ class Metaswitch extends AdapterBaseCl {
       return callback(null, errorObj);
     }
 
+    // Wrap body in SOAP envelope with credentials
+    const soapResult = this.wrapBodyInSoapEnvelope(body, 'NWSAP');
+    if (soapResult.error) {
+      log.error(`${origin}: SOAP envelope wrapping failed - ${soapResult.error.message}`);
+      const errorObj = this.requestHandlerInst.formatErrorObject(this.id, meth, 'SOAP Envelope Error', null, null, null, soapResult.error);
+      return callback(null, errorObj);
+    }
+
     /* HERE IS WHERE YOU SET THE DATA TO PASS INTO REQUEST */
     const queryParamsAvailable = {};
     const queryParams = {};
     const pathVars = [];
-    const bodyVars = body;
 
     // loop in template. long callback arg name to avoid identifier conflicts
     Object.keys(queryParamsAvailable).forEach((thisKeyInQueryParamsAvailable) => {
@@ -966,7 +1186,7 @@ class Metaswitch extends AdapterBaseCl {
     // set up the request object - payload, uriPathVars, uriQuery, uriOptions, addlHeaders, authData, callProperties, filter, priority, event
     // see adapter code documentation for more information on the request object's fields
     const reqObj = {
-      payload: bodyVars,
+      payload: soapResult.payload,
       uriPathVars: pathVars,
       uriQuery: queryParams
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itentialopensource/adapter-metaswitch",
-  "version": "1.0.3",
+  "version": "1.2.1",
   "description": "This adapter integrates with system described as: Metaswitch.",
   "main": "adapter.js",
   "wizardVersion": "3.12.1",

package/propertiesSchema.json

@@ -11,6 +11,25 @@
         "systemx.customer.com"
       ]
     },
+    "domain": {
+      "type": "string",
+      "description": "domain name for OriginHost parameter (Metaswitch authentication)",
+      "default": "domain",
+      "examples": [
+        "customer.com",
+        "metaswitch.local"
+      ]
+    },
+    "clientVersion": {
+      "type": "string",
+      "description": "client version for OriginHost parameter (Metaswitch API version)",
+      "default": "1.0",
+      "examples": [
+        "1.0",
+        "1.6",
+        "2.0"
+      ]
+    },
     "port": {
       "type": "integer",
       "description": "port on which to connect to the server",

package/report/adapterInfo.json

@@ -1,10 +1,10 @@
 {
-  "version": "0.4.6",
-  "configLines": 4658,
-  "scriptLines": 2498,
-  "codeLines": 2492,
-  "testLines": 4001,
-  "testCases": 171,
-  "totalCodeLines": 8991,
+  "version": "1.2.0",
+  "configLines": 4722,
+  "scriptLines": 2523,
+  "codeLines": 2750,
+  "testLines": 4416,
+  "testCases": 200,
+  "totalCodeLines": 9689,
   "wfTasks": 29
 }

package/report/auto-adapter-openapi.json

@@ -116,12 +116,12 @@
           }
         },
         "requestBody": {
-          "description": "indeterminate body object",
           "content": {
             "application/json": {
               "schema": {
                 "type": "object"
-              }
+              },
+              "example": {}
             }
           }
         }
@@ -247,12 +247,12 @@
           }
         },
         "requestBody": {
-          "description": "indeterminate body object",
           "content": {
             "application/json": {
               "schema": {
                 "type": "object"
-              }
+              },
+              "example": {}
             }
           }
         }
@@ -520,12 +520,12 @@
           }
         },
         "requestBody": {
-          "description": "indeterminate body object",
           "content": {
             "application/json": {
               "schema": {
                 "type": "object"
-              }
+              },
+              "example": {}
             }
           }
         }
@@ -812,12 +812,12 @@
           }
         },
         "requestBody": {
-          "description": "indeterminate body object",
           "content": {
             "application/json": {
               "schema": {
                 "type": "object"
-              }
+              },
+              "example": {}
             }
           }
         }