Neptune DXP - Open Edition · 25.0 MTS

Trigger a process flow from an app or a script

This task runs the process flow the way it runs in production, rather than from the Test button in the designer. A process flow is usually started in one of two ways:

From an app, when a person acts, for example by selecting a button on a form. In the candidate-review scenario, an internal job-application form runs the process flow when a candidate submits their application.
From a server script, most often for a recurring or scheduled job that runs the process flow.

Either way, the caller passes the process flow its starting data in the run payload, as interface data. For running the flow inside the designer instead, see Test the process flow.

Prerequisites

You have completed Test the process flow.
You have the identifier of the process flow to run, from its General tab.

Procedure

Trigger from an app

A user action in an app starts the process flow. In the candidate-review scenario, the application form runs the flow when the candidate submits it, passing the candidate as interface data.

In the App Designer, open the file that handles the Submit button, and right-click in it to open Code Snippets.

Search for Process Flows > Run Process Flow, and copy the snippet into your handler. The snippet posts the run payload to the process flow’s run endpoint. For example:

const id =

"8A2F1C40-3B7E-4D91-A6F2-1E5C9D0B7A34"; // the process flow id, from its General tab

// OPTIONAL: add any data you want to send to the workflow inside an interfaceData object
const payload = {
  interfaceData: { firstName: "Sansa", surname: "Stark" },
  // reference it from your workflow like this: {InterfaceData>/name}
};

try {
  const {
    status,
    data: result,
    error,
  } = await neptune.Utils.request(`/api/functions/processFlows/run/${id}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: payload ? JSON.stringify(payload) : undefined,
  });
  if (status !== "ok") {
    throw error || new Error(status);
  }

  data = result;
} catch (err) {
  throw err;
}

The app posts to /api/functions/processFlows/run/:id, the process flow’s REST run endpoint. This is the same run that p9.processFlow.run performs from a script.

Trigger from a script

Trigger a process flow from a server script, for example, for a recurring or scheduled job.

In the Script Editor, create a server script.
Right-click the script and select Code Snippets. Under functions > p9 > processFlow, select run to insert the call.

Complete the call with the process flow identifier and an optional run payload:

// `result` is reserved for the script's own output, so capture the return value
// under a different name.
const id = "8A2F1C40-3B7E-4D91-A6F2-1E5C9D0B7A34" // the process flow id, from its General tab
const flowRun = await p9.processFlow.run(id, {
  interfaceData: { candidate: { firstName: "Liam", yearsOfExperience: 9 } }
})

log.info("Process flow started:", flowRun)

run starts a new execution as the script’s executing user and returns { executionId } once the start node is handled. It does not wait for the whole process flow to finish, so you monitor the execution separately in the Process Flows Overview. See Monitor a run.

The caller must be allowed to run the process flow: the flow’s owner, anyone with a role assigned on the flow, or anyone at all when Allow Public Run is enabled on it. Otherwise, the call throws a NoAccessError.

The run payload

The payload is an object passed to the run. Both of its properties are optional:

interfaceData: The initial interface data, the global store any step can read. In the candidate-review scenario, it carries the candidate the flow starts with: the Score application script reads yearsOfExperience from it, and the outcome email reads the candidate’s name. See How data moves through a process flow.

{
  interfaceData: { candidate: { firstName: "Liam", yearsOfExperience: 9 } }
}

Results

The process flow runs with the payload you provided, triggered either from an app or from a script.
The run appears in the Process Flows Overview. See Monitor a run.

Next steps

Monitor the run