Unexpected behaviour when using com.adobe.granite.workflow.exec.Route API

Hello @johnagordon83-1 ,

your step is advancing twice.

In your custom Process step (“Reassign to Publish”) you call
wfSession.complete(workItem, specificRoute), and the step has Handler Advance = unchecked.
When Handler Advance is unchecked, AEM automatically advances the step on the default route after your execute() returns. Because you also call complete() manually, the engine:

1. reroutes back to “Continue to Unpublish?” (your complete()), and then

2. auto-advances along the original branch to “Email Authors About Broken Links”.

That’s why it looks like the reroute “didn’t stick”.

As a fix:

• Open the “Reassign to Publish” step and check Handler Advance.

• Keep your code that finds the back route and call exactly one wfSession.complete(workItem, specificRoute).

• Do not return any additional complete() or let the engine auto-advance.
  
  

Alternatively:

If you prefer the built-in GoTo step and a server-calculated flag:

- In your process step (right before GoTo), set a workflow variable:
workItem.getWorkflowData().getMetaDataMap().put("loopBack", true);
- Then in the GoTo ECMA script:
var loop = workItem.getWorkflowData().getMetaDataMap().get("loopBack");
if (loop === true) {
route = "Continue to Unpublish?"; // the transition name to that step
} else {
route = "Next"; // whatever your forward route is called
}

- (Use the transition names as they appear in the model.)

That’s it, enable Handler Advance for manual routing, or don’t call complete() if you leave Handler Advance off.

Hello @johnagordon83-1 

- To share variables between steps, use:
workItem.getWorkflow().getMetaDataMap()
NOT workItem.getWorkflowData().getMetaDataMap() (which is step-local).

- In ECMA script steps (like GoTo), access variables as:
workflow.metaDataMap["yourVariableName"]

- For conditional GoTo behavior:
Set the variable in your custom process step and check it in your GoTo ECMA script.

- If using Route API (wfSession.complete(workItem, specificRoute)):
> Disable "Handler Advance" in the step; otherwise all routes may auto-advance.
> Make sure you select the exact route name you want to loop to (case sensitive).

Reference :
https://experienceleague.adobe.com/en/docs/experience-manager-65/content/implementing/developing/extending-aem/extending-workflows/workflows-step-ref

​@johnagordon83-1 Checking back on this thread, were you able to find a solution? If so, please consider sharing what worked for you so others facing the same issue can learn from it. And if one of the replies guided you to the fix, marking it as accepted helps keep our community knowledge clear and easy to navigate. Every update helps!

Hi ​@johnagordon83-1 - 

Have you tried any alternative approach ; Instead of trying to programmatically route backward, use a custom process step to set a flag, then let an OR Split handle the routing decision.

Hi ​@johnagordon83-1 ,

The most robust, repeatable way to implement a conditional loop in AEM workflows is:

• Share data between steps via workflowData’s MetaDataMap
• Let an OR Split / GoTo decide routing based on that flag
• Don’t manually route backward with Route unless you absolutely must

Below is a minimal, working pattern.

1. In your custom process step: set workflow-wide flags Use workflowData metadata, not workItem-local metadata, and not a workflow variable in ECMA.

Java process step (before the OR Split / GoTo):

@Override
public void execute(WorkItem workItem,
                    WorkflowSession wfSession,
                    MetaDataMap args) throws WorkflowException {

    MetaDataMap wfMeta = workItem.getWorkflowData().getMetaDataMap();

    // Decide if you need to loop
    boolean needsReassignment = /* your logic here */ true;

    wfMeta.put("needsReassignment", needsReassignment);

    // Optional: loop counter to avoid infinite loop
    Integer loopCount = wfMeta.get("loopCount", Integer.class);
    loopCount = (loopCount == null) ? 1 : loopCount + 1;
    wfMeta.put("loopCount", loopCount);

    if (loopCount > 5) {               // hard safety cap
        wfMeta.put("needsReassignment", false);
    }
}

This metadata is available to all later steps as workflowData.getMetaDataMap() in ECMA scripts. See the official docs on workflow metadata and variables:
https://experienceleague.adobe.com/en/docs/experience-manager-65/content/implementing/developing/extending-aem/extending-workflows/workflows-customizing-extending

https://experienceleague.adobe.com/en/docs/experience-manager-65/content/implementing/developing/extending-aem/extending-workflows/workflows-step-ref

https://experienceleague.adobe.com/en/docs/experience-manager-65/content/implementing/developing/extending-aem/extending-workflows/using-variables-in-aem-workflows

2. OR Split (recommended): ECMA branch back vs forward

Right after your “Reassign to Publisher / Check” process step, add an OR Split:

• Branch 1 -> goes back to the “Continue to Unpublish?” participant step.
• Branch 2 -> goes forward (e.g., Email Authors About Broken Links).

In the OR Split, for the loop branch, use ECMA Script routing:

// OR Split branch that loops back to "Continue to Unpublish?"
function check() {
    var meta = workflowData.getMetaDataMap();
    var flag = meta.get("needsReassignment");
    var loopCount = meta.get("loopCount");

    // stop looping if safety limit hit
    if (loopCount != null && parseInt(loopCount, 10) > 5) {
        return false;
    }

    // treat both boolean true and string "true" as true
    return flag === true || flag == "true";
}

• Keep Handler Advance ON for normal steps.
• Do not call wfSession.complete() yourself for routing; the engine follows the OR Split decision automatically.

This avoids the timing/race issues you observed with Route and is exactly how the docs recommend doing loops (see the “Simulating a for loop” and OR Split sections in https://experienceleague.adobe.com/en/docs/experience-manager-65/content/implementing/developing/extending-aem/extending-workflows/workflows-step-ref

3. If you must use GoTo instead

If you prefer the built‑in GoTo Step, the pattern is the same: use workflowData metadata.
Process step (Java) before GoTo:

workItem.getWorkflowData().getMetaDataMap().put("loopBack", true);

GoTo ECMA script (Routing Expression):

function check() {
    var meta = workflowData.getMetaDataMap();
    var loop = meta.get("loopBack");

    // true or "true" → execute Target Step (your earlier step)
    return loop === true || loop == "true";
}

Note: In dynamic.ecma and GoTo scripts, there is no workflow variable – only workItem, workflowSession, workflowData, args, metaData, etc. https://experienceleague.adobe.com/en/docs/experience-manager-65/content/implementing/developing/extending-aem/extending-workflows/workflows-customizing-extending

4. Why not wfSession.complete(workItem, Route)?
Your original behavior (step where both the loop and the forward path executed) is exactly the kind of subtle race-condition and handler‑advance interaction that makes Route-based manual back‑routing fragile.

Using metadata + OR Split / GoTo:

• All routing is declarative and visible in the model.
• The engine advances each step once, deterministically.
• You can easily guard with a loopCount to prevent infinite loops.

Thanks,
Amit

Hey ​@johnagordon83-1 , 

The issue is that 

wfSession.complete(workItem, specificRoute)

 doesn't stop the original workflow path from continuing. Both paths execute in parallel.

Fix:

1. Use Route ID instead of Route Name:

if (route.getId().equals("continue-to-unpublish")) {

2. Return immediately after completing:

wfSession.complete(workItem, specificRoute);
return; // Add this

3. Verify Handler Advance is OFF for the "Reassign to Publish" step in your workflow model.

If this still doesn't work, the Route API has limitations. Use the GoTo step instead:

In your custom process before GoTo:

workItem.getWorkflowData().getMetaDataMap().put("shouldLoop", true);
wfSession.updateWorkflowData(workItem.getWorkflow(), workItem.getWorkflowData());

In GoTo step's ECMA script:

workflowData.getMetaDataMap().get("shouldLoop", false);