Since version 9.1.1 the BPMN and DMN Editors used in both BAMOE Canvas and BAMOE Developer Tools for VS Code are also available as standalone JavaScript libraries that can be embedded into any frontend web application.

They are available by importing the following libraries from NPM:

BPMN Editor

The BPMN Editor, built with React, is faster and aims to be retro-compatible with BPMN Editor (classic), supporting the BPMN 2.0 specifications while maintaining the same simple-to-use API.

new bpmn editor
Figure 1. BPMN Editor

Installing and using the BPMN Editor

  1. Add the library to the project’s package.json:

    npm install @ibm/bamoe-standalone-bpmn-editor@9.5.0-ibm-0005

  2. Import the editor library to a JavaScript file with the following statement:

    import * as BpmnEditor from "@ibm/bamoe-standalone-bpmn-editor/dist"

  3. Add a 'div' element for the Editor in the HTML; the library uses this 'div' as a container to load an iFrame with the Editor’s resources:

    <div id="new-bpmn-editor-container"/>

  4. Load the Editor by passing the reference to the div container as follows:

    const bpmnEditor = BpmnEditor.open({
  container: document.getElementById("bpmn-editor-container"),
  initialContent: Promise.resolve(""),
  initialFileNormalizedPosixPathRelativeToTheWorkspaceRoot: "model.bpmn",
  readOnly: false,
  origin: "*",
  onError: () => {},
  resources: new Map([
    [
      "MyDecision.dmn",
      {
        contentType: "text",
        content: Promise.resolve("")
      }
    ]
  ])
});

Where the following table describes the parameters:

Parameter Description Required/Optional Examples

container

Specifies the HTML element that the Editor is appended to.

Mandatory

initialFileNormalizedPosixPathRelativeToTheWorkspaceRoot

Specifies the POSIX path relative to the workspace root which is / by default, including the file name. The path is useful for locating the file in the workspace, especially in relation to other resources (defined by the resources parameters).

Mandatory

* model.dmn

* myPath/model.dmn

* parent/child/filename.dmn

initialContent

Accepts a Promise that resolves to the contents of a .dmn file. It can be an empty.

Mandatory

* Promise.resolve("")

* Promise.resolve("<DMN_CONTENT_DIRECTLY_HERE>")

* fetch("MyDecision.dmn").then(content ⇒ content.text())

readOnly

You can use false for content edition and true for read-only mode, where the editor does not allow changes. Default is false.

Optional

origin

If accessing the application via the file:// protocol, it defaults to *; otherwise, it defaults to window.location.origin.

Optional

onError

Accepts a function that is called when the Editor encounters an error at any moment. This parameter defaults to () ⇒ {}).

Optional

resources

This parameter defaults to an empty Map; Map of resources that will be provided for the Editor. For instance, this parameter can be used to provide included models for the BPMN Editor. Each entry in the map has the resource POSIX path (similar to the initialFileNormalizedPosixPathRelativeToTheWorkspaceRoot parameter) as the key and an object that contains the contentType (text or binary), and the resource content (Promise similar to the initialContent parameter) as its value. The resources are located in a parent directory (in relation to the current content path, defined by the initialFileNormalizedPosixPathRelativeToTheWorkspaceRoot) which will not be listed to be used as an Included Model.

Optional

* resources: new Map([["types.dmn", { contentType: "text", content: Promise.resolve("<DMN_CONTENTS_HERE>")}], […​], […​]])

* resources: new Map([["/types/typeA.dmn", { contentType: "text", content: Promise.resolve("<DMN_CONTENTS_HERE>")}], ["/extras/decision.dmn", { contentType: "text", content: Promise.resolve("<DMN_CONTENTS_HERE>")}], […​]])
Note
 The initialFileNormalizedPosixPathRelativeToTheWorkspaceRoot parameter is only available for the BPMN and DMN Editors. BPMN and DMN Editors (classic) do not have the concept of relative paths, so every mapped resource is available.

The returned object (bpmnEditor) will contain the following methods needed to manipulate the Editor:

getContent(): Promise<string>

Returns a Promise that contains the Editor’s content.

setContent(normalizedPosixPathRelativeToTheWorkspaceRoot: string, content: string): Promise<void>

Sets the content of the editor. The returning Promise will be rejected if setting the content fails.

getPreview(): Promise<string>

Returns a Promise that resolves to the SVG string of the current diagram.

subscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): (isDirty: boolean) ⇒ void

Setup a callback function that is automatically called on every content change in the Editor. It returns the same function that needs to be used for unsubscription.

unsubscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): void

Unsubscribes the callback function from being called when the content changes.

markAsSaved(): void

Resets the editor state by signaling that the content is saved. It also fires the subscribed callbacks for content changes.

undo(): void

Undo the last change in the Editor. It will also fire the subscribed callbacks of content changes.

redo(): void

Redo the last undone change in the Editor. It will also fire the subscribed callbacks of content changes.

close(): void

Closes the Editor.

envelopeApi: MessageBusClientApi<KogitoEditorEnvelopeApi>

An Advanced Editor API.

Note
 As of now, the BPMN Editor does not expose the canvas property.

DMN Editor

The modern DMN Editor, built with React, is faster and supports up to DMN 1.6 specifications while maintaining the same simple-to-use API.

new dmn editor
Figure 2. DMN Editor

Installing and using the DMN Editor

  1. Add the library to the project’s package.json:

    npm install @ibm/bamoe-standalone-dmn-editor@9.5.0-ibm-0005

  2. Import the editor library to a JavaScript file with the following statement:

    import * as DmnEditor from "@ibm/bamoe-standalone-dmn-editor/dist"

  3. Add a 'div' element for the Editor in the HTML; the library uses this 'div' as a container to load an iFrame with the Editor’s resources:

    <div id="new-dmn-editor-container"/>

  4. Load the Editor by passing the reference to the div container as follows:

    const dmnEditor = DmnEditor.open({
  container: document.getElementById("new-dmn-editor-container"),
  initialFileNormalizedPosixPathRelativeToTheWorkspaceRoot: "model.dmn",
  initialContent: Promise.resolve(""),
  readOnly: false,
  origin: "*",
  onError: () => {},
  resources: new Map([
    [
      "MyDecision.dmn",
      {
        contentType: "text",
        content: Promise.resolve("")
      }
    ]
  ])
});

Where the following table describes the parameters:

Parameter Description Required/Optional Examples

container

Specifies the HTML element that the Editor is appended to.

Mandatory

initialFileNormalizedPosixPathRelativeToTheWorkspaceRoot

Specifies the POSIX path relative to the workspace root which is / by default, including the file name. The path is useful for locating the file in the workspace, especially in relation to other resources (defined by the resources parameters).

Mandatory

* model.dmn

* myPath/model.dmn

* parent/child/filename.dmn

initialContent

Accepts a Promise that resolves to the contents of a .dmn file. It can be an empty.

Mandatory

* Promise.resolve("")

* Promise.resolve("<DMN_CONTENT_DIRECTLY_HERE>")

* fetch("MyDecision.dmn").then(content ⇒ content.text())

readOnly

You can use false for content edition and true for read-only mode, where the editor does not allow changes. Default is false.

Optional

origin

If accessing the application via the file:// protocol, it defaults to *; otherwise, it defaults to window.location.origin.

Optional

onError

Accepts a function that is called when the Editor encounters an error at any moment. This parameter defaults to () ⇒ {}).

Optional

resources

This parameter defaults to an empty Map; Map of resources that will be provided for the Editor. For instance, this parameter can be used to provide included models for the DMN Editor. Each entry in the map has the resource POSIX path (similar to the initialFileNormalizedPosixPathRelativeToTheWorkspaceRoot parameter) as the key and an object that contains the contentType (text or binary), and the resource content (Promise similar to the initialContent parameter) as its value. The resources are located in a parent directory (in relation to the current content path, defined by the initialFileNormalizedPosixPathRelativeToTheWorkspaceRoot) which will not be listed to be used as an Included Model.

Optional

* resources: new Map([["types.dmn", { contentType: "text", content: Promise.resolve("<DMN_CONTENTS_HERE>")}], […​], […​]])

* resources: new Map([["/types/typeA.dmn", { contentType: "text", content: Promise.resolve("<DMN_CONTENTS_HERE>")}], ["/extras/decision.dmn", { contentType: "text", content: Promise.resolve("<DMN_CONTENTS_HERE>")}], […​]])
Note
 The initialFileNormalizedPosixPathRelativeToTheWorkspaceRoot parameter is only available for the DMN Editor. The BPMN and DMN Editors (classic) do not have the concept of relative paths, so every mapped resource is available.

The returned object (dmnEditor) will contain the following methods needed to manipulate the Editor:

getContent(): Promise<string>

Returns a Promise that contains the Editor’s content.

setContent(normalizedPosixPathRelativeToTheWorkspaceRoot: string, content: string): Promise<void>

Sets the content of the editor. The returning Promise will be rejected if setting the content fails.

getPreview(): Promise<string>

Returns a Promise that resolves to the SVG string of the current diagram.

subscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): (isDirty: boolean) ⇒ void

Setup a callback function that is automatically called on every content change in the Editor. It returns the same function that needs to be used for unsubscription.

unsubscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): void

Unsubscribes the callback function from being called when the content changes.

markAsSaved(): void

Resets the editor state by signaling that the content is saved. It also fires the subscribed callbacks for content changes.

undo(): void

Undo the last change in the Editor. It will also fire the subscribed callbacks of content changes.

redo(): void

Redo the last undone change in the Editor. It will also fire the subscribed callbacks of content changes.

close(): void

Closes the Editor.

envelopeApi: MessageBusClientApi<KogitoEditorEnvelopeApi>

An Advanced Editor API.

Note
 As of now, the DMN Editor does not expose the canvas property.

BPMN and DMN Editors (classic)

The following classic GWT-based editors are available as JavaScript file for each Editor.

dmn editor classic
Figure 3. DMN Editor (classic)
bpmn editor classic
Figure 4. BPMN Editor (classic)

Installing and using BPMN and DMN Editors (classic)

Installing and using each Editor is the same, as they are built to expose the same generic API to set and get content, export preview SVGs, undo and redo edits, and more. Follow these steps to install the editors:

  1. Add the following library to the project’s package.json:

    npm install @ibm/bamoe-standalone-bpmn-and-dmn-editors-classic@9.5.0-ibm-0005

  2. Import each Editor to a JavaScript file with the following statements:

    import * as BpmnEditor from "@ibm/bamoe-standalone-bpmn-and-dmn-editors-classic/dist/bpmn"
import * as DmnEditor from "@ibm/bamoe-standalone-bpmn-and-dmn-editors-classic/dist/dmn"

  3. Add a 'div' element for the Editor in the HTML; the library uses this 'div' as a container to load an iFrame with the Editor’s resources:

    <div id="bpmn-editor-container"/>
<div id="dmn-editor-container"/>

  4. Load each Editor by passing the reference to the respective div container as follows:

    const bpmnEditorClassic = BpmnEditor.open({
  container: document.getElementById("bpmn-editor-container"),
  initialContent: Promise.resolve(""),
  readOnly: false,
  origin: "*",
  onError: () => {},
  resources: new Map([])
});

const dmnEditorClassic = DmnEditor.open({
  container: document.getElementById("dmn-editor-container"),
  initialContent: Promise.resolve(""),
  readOnly: false,
  origin: "*",
  onError: () => {},
  resources: new Map([])
});

Where the following table describes the parameters:

Parameter Description Required/Optional Examples

container

Specifies the HTML element that the Editor is appended to.

Mandatory

initialContent

Accepts a Promise that resolves to the contents of a .bpmn file for the BPMN Editor or the contents of a .dmn file for the DMN Editor. It can be an empty.

Mandatory

* Promise.resolve("")

* Promise.resolve ("<BPMN_OR_DMN_CONTENT_DIRECTLY_HERE>")

* fetch("MyBpmnFile.bpmn").then(content ⇒ content.text())

readOnly

You can use false for content edition and true for read-only mode, where the editor does not allow changes. Default is true.

Optional

origin

If accessing the application via the file:// protocol, it defaults to *; otherwise, it defaults to window.location.origin.

Optional

onError

Accepts a function that is called when the Editor encounters an error at any moment. This parameter defaults to () ⇒ {}).

Optional

resources

This parameter defaults to an empty Map; Map of resources that will be provided for the Editor. For instance, this parameter can be used to provide included models for the DMN Editor or Work Item Definitions for the BPMN Editor. Each entry in the map has the resource name as the key and an object that contains the contentType(text or binary), and the resource content(Promise similar to the initialContent parameter) as its value.

Optional

* resources: new Map([["myWid.wid", { contentType: "text", content: Promise.resolve("<WID_CONTENTS_HERE>")}], […​], […​]])

* resources: new Map([["types.dmn", { contentType: "text", content: Promise.resolve("<DMN_CONTENTS_HERE>")}], […​], […​]])

The returned objects, (bpmnEditor and dmnEditor) will contain the following methods needed to manipulate the Editor:

getContent(): Promise<string>

Returns a Promise that resolves to the Editor’s BPMN or DMN content.

setContent(normalizedPosixPathRelativeToTheWorkspaceRoot: string, content: string): Promise<void>

Sets the content of the editor. The returning Promise will be rejected if setting the content fails.

getPreview(): Promise<string>

Returns a Promise that resolves to the SVG string of the current diagram.

subscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): (isDirty: boolean) ⇒ void

Setup a callback function that is automatically called on every content change in the Editor. It returns the same function that needs to be used for unsubscription.

unsubscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): void

Unsubscribes the callback function from being called when the content changes.

markAsSaved(): void

Resets the editor state by signaling that the content is saved. It also fires the subscribed callbacks for content changes.

undo(): void

Undo the last change in the Editor. It will also fire the subscribed callbacks of content changes.

redo(): void

Redo the last undone change in the Editor. It will also fire the subscribed callbacks of content changes.

close(): void

Closes the Editor.

envelopeApi: MessageBusClientApi<KogitoEditorEnvelopeApi>

An Advanced Editor API.

canvas

An API that exposes the following methods to manipulate the diagram:

getNodeIds(): Promise<string[]>

Returns a Promise that contains the ID attributes of all nodes displayed in the editor diagram.

getBackgroundColor(uuid: string): Promise<string>

Returns a Promise that contains the background color of a node with the provided UUID.

setBackgroundColor(uuid: string, backgroundColor: string): Promise<void>

Sets the background color of a node with the provided UUID.

getBorderColor(uuid: string): Promise<string>

Returns a Promise that contains the border color of a node with the provided UUID.

setBorderColor(uuid: string, borderColor: string): Promise<void>

Sets the border color of a node with the provided UUID.

getLocation(uuid: string): Promise<number[]>

Returns a Promise that contains the diagram location of a node with the provided UUID.

getAbsoluteLocation(uuid: string): Promise<number[]>

Returns a Promise that contains the window location of a node with the provided UUID.

getDimensions(uuid: string): Promise<number[]>

Returns a Promise that contains the dimensions of a node with the provided UUID.

applyState(uuid: string, state: string): Promise<void>

Applies state to a node given the UUID [None, Selected, Highlight, Invalid].

centerNode(uuid: string): Promise<void>

Centers node on the viewable diagram.