Update IAM SDK and detect iframe CSP blocking for IDV workflows

client/src/api/index.js

@@ -88,5 +88,9 @@ export const api = Object.freeze({
         return error.response;
       }
     },
+    getWorkflowInstance: async (workflowId, instanceId) => {
+      const response = await instance.get(`/workflows/${workflowId}/instances/${instanceId}`);
+      return response;
+    },
   },
 });

client/src/assets/text.json

@@ -93,7 +93,8 @@
     "triggerNewWorkflow": "Trigger new workflow ->",
     "getStarted": "Get started",
     "moreInfo": "More info",
-    "backHome": "← Back to workflows"
+    "backHome": "← Back to workflows",
+    "done": "Done"
   },
   "links": {
     "github": "https://github.com/docusign/sample-app-workflows-node",

client/src/components/Popups/WorkflowTriggerResult/WorkflowTriggerResult.jsx

@@ -22,7 +22,7 @@ const WorkflowTriggerResult = ({ workflowInstanceUrl }) => {
       <h2>{textContent.popups.workflowTriggered.title}</h2>
       <br />  
       <p className={styles.popupMessageContainer}>
-        See <a href='https://developers.docusign.com/docs/maestro-api/maestro101/embed-workflow/#embedded-workflow-instance-recommendations-and-restrictions' target='_blank'>Embedded workflow instance recommendations and restrictions</a> for more information.
+        See <a href='https://developers.docusign.com/docs/workflow-builder-api/workflow-builder101/embed-workflow/#embedded-workflow-instance-recommendations-and-restrictions' target='_blank'>Embedded workflow instance recommendations and restrictions</a> for more information.
       </p>
       <a href={workflowInstanceUrl} target="_blank" rel="noreferrer" onClick={handleFinishTrigger}>
         {textContent.buttons.continue}

client/src/components/TriggerForm/TriggerForm.jsx

@@ -103,27 +103,17 @@ const TriggerForm = ({ workflowId, templateType }) => {
     }
 
     const { data: triggeredWorkflow } = await api.workflows.triggerWorkflow(workflowId, templateType, body);
-    setWorkflowInstanceUrl(triggeredWorkflow.instanceUrl);
-
-    if (triggeredWorkflow.instanceUrl !== undefined) {
-      navigate(`${ROUTE.TRIGGERFORM}/${workflowId}?type=${templateType}&triggerUrl=${encodeURIComponent(triggeredWorkflow.instanceUrl)}`)
-    }
 
     if (triggeredWorkflow === WorkflowTriggerResponse.TRIGGER_ISSUE) {
-      // Update workflowDefinitions. "...workflow" creates new workflow-object to avoid mutation in redux
-      const updatedWorkflowDefinitions = workflows.map(w => {
-        if (w.id !== workflowId) return { ...w };
-
-        return {
-          ...w,
-          instanceId: triggeredWorkflow.instanceId,
-          isTriggered: true,
-        };
-      });
-
-      dispatch(updateWorkflowDefinitions(updatedWorkflowDefinitions));
       setDataSending(false);
       dispatch(openPopupWindow());
+      return;
+    }
+
+    setWorkflowInstanceUrl(triggeredWorkflow.instanceUrl);
+
+    if (triggeredWorkflow.instanceUrl !== undefined) {
+      navigate(`${ROUTE.TRIGGERFORM}/${workflowId}?type=${templateType}&triggerUrl=${encodeURIComponent(triggeredWorkflow.instanceUrl)}`)
     }
   };
 

client/src/pages/TriggerWorkflowForm/TriggerWorkflowForm.jsx

@@ -1,4 +1,5 @@
-import { useParams, useLocation } from 'react-router-dom';
+import { useState, useRef, useEffect, useCallback } from 'react';
+import { useParams, useLocation, useNavigate } from 'react-router-dom';
 import styles from './TriggerWorkflowForm.module.css';
 import Header from '../../components/Header/Header.jsx';
 import Footer from '../../components/Footer/Footer.jsx';
@@ -8,32 +9,107 @@
 import TriggerBehindTheScenes from '../../components/WorkflowDescription/BehindTheScenes/TriggerBehindTheScenes.jsx';
 import TriggerForm from '../../components/TriggerForm/TriggerForm.jsx';
 import { ROUTE } from '../../constants.js';
+import { buttons } from '../../assets/text.json';
 
 const TriggerWorkflowForm = () => {
   const { workflowId } = useParams();
+  const navigate = useNavigate();
+  const [embeddingFailed, setEmbeddingFailed] = useState(false);
+  const hasOpenedNewTab = useRef(false);
+  const childWindowRef = useRef(null);
 
   const location = useLocation();
   const searchParams = new URLSearchParams(location.search);
   const type = searchParams.get('type');
   const triggerUrl = searchParams.get('triggerUrl');
 
-  const triggerUrlPattern = /^https:\/\/(?!.*javascript)[^()]+$/i;
-
-function isValidTriggerUrl(url) {
-  try {
-    const decoded = decodeURIComponent(url);
-    const parsedUrl = new URL(decoded);
-    // Only allow https and the exact hostname
-    return (
-      parsedUrl.protocol === 'https:' &&
-      parsedUrl.hostname === 'apps-d.docusign.com'
-    );
-  } catch {
-    return false;
+  function isValidTriggerUrl(url) {
+    try {
+      const decoded = decodeURIComponent(url);
+      const parsedUrl = new URL(decoded);
+      return (
+        parsedUrl.protocol === 'https:' &&
+        parsedUrl.hostname === 'apps-d.docusign.com'
+      );
+    } catch {
+      return false;
+    }
   }
-}
-
+
+  const handleIframeLoad = useCallback((e) => {
+    try {
+      const href = e.target.contentWindow.location.href;
+      if (href === 'about:blank') {
+        setEmbeddingFailed(true);
+      }
+    } catch {
+      // Cross-origin SecurityError — handled by ReportingObserver for CSP blocks
+    }
+  }, []);
+
+  // Detect CSP frame-ancestors violations via ReportingObserver
+  useEffect(() => {
+    if (!triggerUrl) return;
+
+    let observer;
+    if (typeof ReportingObserver !== 'undefined') {
+      observer = new ReportingObserver((reports) => {
+        const blocked = reports.some(
+          (report) => report.body && report.body.effectiveDirective === 'frame-ancestors'
+        );
+        if (blocked) {
+          setEmbeddingFailed(true);
+        }
+      }, { types: ['csp-violation'], buffered: false });
+      observer.observe();
+    }
+
+    return () => {
+      if (observer) observer.disconnect();
+    };
+  }, [triggerUrl]);
+
+  // Open new tab when embedding fails
+  useEffect(() => {
+    if (embeddingFailed && triggerUrl && !hasOpenedNewTab.current) {
+      hasOpenedNewTab.current = true;
+      childWindowRef.current = window.open(triggerUrl, '_blank');
+    }
+  }, [embeddingFailed, triggerUrl]);
+
   if (triggerUrl !== null && isValidTriggerUrl(triggerUrl)) {
+    // Embedding failed — workflow opened in new tab
+    if (embeddingFailed) {
+      return (
+        <div className="page-box">
+          <Header />
+          <div className={styles.contentContainer}>
+            <WorkflowDescription
+              title={textContent.pageTitles.completeWorkflow}
+              behindTheScenesComponent={<TriggerBehindTheScenes />}
+              backRoute={ROUTE.TRIGGER}
+            />
+            <p>This workflow cannot be embedded and has been opened in a new tab.</p>
+            <p>Complete your tasks in the new tab, then click Done to return.</p>
+            <a href={triggerUrl} target="_blank" rel="noopener noreferrer">
+              Open workflow in new tab
+            </a>
+            <button className={styles.doneButton} onClick={() => {
+              if (childWindowRef.current) {
+                childWindowRef.current.close();
+                childWindowRef.current = null;
+              }
+              navigate(ROUTE.TRIGGER);
+            }}>
+              {buttons.done}
+            </button>
+          </div>
+          <Footer withContent={false} />
+        </div>
+      );
+    }
+
+    // Iframe embedding
     return (
       <div className="page-box">
         <Header />
@@ -44,10 +120,11 @@
             backRoute={ROUTE.TRIGGER}
           />
 
-          <div className={styles.formContainer}>
-            <iframe src={triggerUrl} width="800" height="600">
-            </iframe>
-          </div>
+          <iframe src={triggerUrl} width="800" height="600" onLoad={handleIframeLoad}>
+          </iframe>
+          <button className={styles.doneButton} onClick={() => navigate(ROUTE.TRIGGER)}>
+            {buttons.done}
+          </button>
         </div>
         <Footer withContent={false} />
       </div>

client/src/pages/TriggerWorkflowForm/TriggerWorkflowForm.module.css

@@ -8,4 +8,23 @@
         display: flex;
         flex-direction: row;
     }
-}
+}
+
+.doneButton {
+    margin-top: 1.5rem;
+    height: 40px;
+    border-radius: 2px;
+    color: var(--white-main);
+    background-color: var(--primary-main);
+    font-size: 16px;
+    font-weight: 500;
+    line-height: 24px;
+    align-self: end;
+    border: none;
+    padding: 0 1.5rem;
+    cursor: pointer;
+}
+
+.doneButton:hover {
+    background-color: var(--secondary-main);
+}

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "sample-app-maestro-node",
+  "name": "sample-app-workflows-node",
   "version": "1.0.0",
   "private": true,
   "scripts": {

server/constants.js

@@ -18,10 +18,10 @@ const ISSUES = {
   TRIGGER_ISSUE: 'Incompatible workflow',
 };
 
-const MAESTRO_SCOPES = ['signature', 'aow_manage', 'impersonation'];
+const WORKFLOW_BUILDER_SCOPES = ['signature', 'aow_manage'];
 
 module.exports = {
-  scopes: MAESTRO_SCOPES,
+  scopes: WORKFLOW_BUILDER_SCOPES,
   BACKEND_ROUTE,
   TEMPLATE_TYPE,
   METHOD,

server/controllers/workflowsController.js

@@ -83,6 +83,22 @@ class WorkflowsController {
     }
   };
 
+  static getWorkflowInstance = async (req, res) => {
+    try {
+      const args = {
+        workflowId: req.params.definitionId,
+        instanceId: req.params.instanceId,
+        accessToken: req?.user?.accessToken || req?.session?.accessToken,
+        accountId: req.session.accountId,
+      };
+
+      const result = await WorkflowsService.getWorkflowInstance(args);
+      res.status(200).send(result);
+    } catch (error) {
+      this.handleErrorResponse(error, res);
+    }
+  };
+
   static handleErrorResponse(error, res) {
     this.logger.error(`handleErrorResponse: ${error}`);
 

server/package.json

@@ -11,7 +11,7 @@
   },
   "author": "",
   "dependencies": {
-    "@docusign/iam-sdk": "1.0.0-beta.3",
+    "@docusign/iam-sdk": "1.0.0-beta.8",
     "axios": "^1.11.0",
     "body-parser": "^1.20.3",
     "chalk": "^4.1.2",

server/routes/workflowsRouter.js

@@ -5,6 +5,7 @@ const authMiddleware = require('../middlewares/authMiddleware');
 const router = Router();
 
 router.put('/:definitionId/trigger', authMiddleware, workflowsController.triggerWorkflow);
+router.get('/:definitionId/instances/:instanceId', authMiddleware, workflowsController.getWorkflowInstance);
 router.get('/definitions', authMiddleware, workflowsController.getWorkflowDefinitions);
 router.get('/:definitionId/requirements', authMiddleware, workflowsController.getWorkflowTriggerRequirements);
 

server/server.js

@@ -27,7 +27,7 @@ const app = express()
   .use(
     session({
       secret: config.sessionSecret,
-      name: 'my-maestro-session',
+      name: 'my-workflow-builder-session',
       cookie: { maxAge: maxSessionAge },
       saveUninitialized: true,
       resave: true,

server/services/workflowsService.js

@@ -1,6 +1,6 @@
 /**
  * @file
- * This file handles work with docusign maestro and esign services.
+ * This file handles work with docusign workflow builder and esign services.
  * Scenarios implemented:
  * - Workflow definition triggering, which create workflow instance.
  * - Workflow definitions fetching.
@@ -12,14 +12,14 @@ const iam = require('@docusign/iam-sdk');
 class WorkflowsService {
   static getWorkflowDefinitions = async args => {
     const client = new iam.IamClient({ accessToken: args.accessToken });
-    const definitions = await client.maestro.workflows.getWorkflowsList({ accountId: args.accountId });
+    const definitions = await client.workflowBuilder.workflows.getWorkflowsList({ accountId: args.accountId });
 
     return definitions;
   };
 
   static getWorkflowTriggerRequirements = async args => {
     const client = new iam.IamClient({ accessToken: args.accessToken });
-    const triggerRequirements = await client.maestro.workflows.getWorkflowTriggerRequirements({
+    const triggerRequirements = await client.workflowBuilder.workflows.getWorkflowTriggerRequirements({
       accountId: args.accountId,
       workflowId: args.workflowId,
     });
@@ -33,14 +33,24 @@ class WorkflowsService {
       instanceName: 'test',
       triggerInputs: payload,
     };
-    const triggerResponse = await client.maestro.workflows.triggerWorkflow({
+    const triggerResponse = await client.workflowBuilder.workflows.triggerWorkflow({
       accountId: args.accountId,
       workflowId: args.workflowId,
       triggerWorkflow: triggerPayload,
     });
 
     return triggerResponse;
   };
+
+  static getWorkflowInstance = async args => {
+    const client = new iam.IamClient({ accessToken: args.accessToken });
+
+    return await client.workflowBuilder.workflowInstanceManagement.getWorkflowInstance({
+      accountId: args.accountId,
+      workflowId: args.workflowId,
+      instanceId: args.instanceId,
+    });
+  };
 }
 
 module.exports = WorkflowsService;