DMN and BPMN Editors JavaScript Libraries

The editors used in both BAMOE Canvas and BAMOE Developer Tools 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:

@ibm/bamoe-standalone-bpmn-and-dmn-editors-classic: For the classic DMN and BPMN Editors
@ibm/bamoe-standalone-dmn-editor: The new and modern DMN Editor

Classic DMN and BPMN Editors

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

Figure 1. DMN Editor classic

Figure 2. BPMN Editor classic

Installing and using the classic DMN and BPMN Editors

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:

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

npm install @ibm/bamoe-standalone-bpmn-and-dmn-editors-classic@9.1.x

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"

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"/>
```

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

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

const dmnEditor = 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

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>")}], […], […]])`

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 canvas:
getNodeIds(): Promise<string[]>: Returns a Promise that contains the ID attributes of all nodes displayed in the editor canvas.
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 canvas 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 Canvas.

New DMN Editor

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

Figure 3. New DMN Editor

Installing and using the new DMN Editor

Follow these steps to install the new DMN Editor

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

npm install @ibm/@ibm/bamoe-standalone-dmn-editor@9.1.x

Import the editor library to a JavaScript file with the following statement:
```
import * as NewDmnEditor from "@ibm/bamoe-standalone-dmn-editor/dist"
```
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"/>
```

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

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

Where the following table describes the parameters:

Parameter Description Required/Optional Examples

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>")}], […]])`

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 new DMN Editor. The classic editors do not have the concept of relative paths, so every mapped resource is available.

The returned object (newDmnEditor) 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 new DMN Editor does not expose the `canvas` property.