bpmnVisualizationR: Visualize Process Execution Data on 'BPMN' Diagrams

Description

To visualize the execution data of the processes on 'BPMN' (Business Process Model and Notation) diagrams, using overlays, style customization and interactions, with the 'bpmn-visualization' 'TypeScript' library.

Author(s)

Maintainer: Celine Souchet process.analytics.dev+CRAN@gmail.com

Authors:

• Thomas Bouffard

See Also

Useful links:

• https://process-analytics.github.io/bpmn-visualization-R/

• https://github.com/process-analytics/bpmn-visualization-R/

• Report bugs at https://github.com/process-analytics/bpmn-visualization-R/issues/

Shiny output binding for the bpmnVisualizationR 'HTML' widget

Description

Helper to create output function for using the bpmnVisualizationR 'HTML' widget within 'Shiny' applications and interactive 'Rmd' documents.

Usage

bpmnVisualizationROutput(outputId, width = "100%", height = "400px")

Arguments

Value

An output function that enables the use of the bpmnVisualizationR widget within 'Shiny' applications.

Create the style for BPMN edge

Description

Use this function to create the correct style structure for the edge.

Usage

create_edge_style(
  elementIds,
  stroke_color = NULL,
  stroke_width = NULL,
  stroke_opacity = NULL,
  font_color = NULL,
  font_family = NULL,
  font_size = NULL,
  font_bold = NULL,
  font_italic = NULL,
  font_strike_through = NULL,
  font_underline = NULL,
  font_opacity = NULL,
  opacity = NULL
)

Arguments

Value

A list representing the style for the BPMN edge.

Special keywords

default

• This keyword allows you to reset a style property of the BPMN element to its initial value.

• When applied to color properties, it bypasses the color specified in the 'BPMN' source if 'BPMN in Color' support is enabled. Instead, it uses the color defined in the default style of the 'BPMN' element..

inherit

Applies the value from the immediate parent element.

none

No color (used to hide strokes). Not available for font_color.

swimlane

Applies the value from the nearest parent element with type ShapeBpmnElementKind.LANE or ShapeBpmnElementKind.POOL.

Note

Opacity properties

• If the set value is less than 0, the used value is 0.

• If the set value is greater than 100, the used value is 100.

Warning: stroke_width property

Changing the stroke width of Activities may be misleading, as the default stroke widths have a meaning according to the 'BPMN' Specification.
For example, updating the stroke width of a task using the same value as the default stroke width of a Call Activity can be confusing.
In this case, you should also change another property, such as the stroke color, to allow the user to differentiate between them.

Examples

# Create a style with a blue stroke and a bold, red font.
edge_style <- create_edge_style(
  elementIds = list('id_1', 'id_2'),
  stroke_color = "blue",
  stroke_width = 2,
  font_color = "red",
  font_bold = TRUE
)

Create the style for BPMN element

Description

Internal function to create the correct style structure for the 'BPMN' element.

Usage

create_element_style(
  elementIds,
  stroke_color = NULL,
  stroke_width = NULL,
  stroke_opacity = NULL,
  font_color = NULL,
  font_family = NULL,
  font_size = NULL,
  font_bold = NULL,
  font_italic = NULL,
  font_strike_through = NULL,
  font_underline = NULL,
  font_opacity = NULL,
  opacity = NULL
)

Arguments

Value

A list representing the style for the specified BPMN elements.

Special keywords

default

• This keyword allows you to reset a style property of the BPMN element to its initial value.

• When applied to color properties, it bypasses the color specified in the 'BPMN' source if 'BPMN in Color' support is enabled. Instead, it uses the color defined in the default style of the 'BPMN' element..

inherit

Applies the value from the immediate parent element.

none

No color (used to hide strokes). Not available for font_color.

swimlane

Applies the value from the nearest parent element with type ShapeBpmnElementKind.LANE or ShapeBpmnElementKind.POOL.

Note

Opacity properties

• If the set value is less than 0, the used value is 0.

• If the set value is greater than 100, the used value is 100.

Warning: stroke_width property

Changing the stroke width of Activities may be misleading, as the default stroke widths have a meaning according to the 'BPMN' Specification.
For example, updating the stroke width of a task using the same value as the default stroke width of a Call Activity can be confusing.
In this case, you should also change another property, such as the stroke color, to allow the user to differentiate between them.

Create a gradient fill style for an element

Description

Create a gradient fill style for an element.

Usage

create_gradient_fill(direction, start_color, end_color)

Arguments

Value

A gradient fill style object.

Create an overlay

Description

An overlay can be added to existing elements in the diagram.

See the overlays argument in the display function.

Use this function to create the correct overlay structure.

Usage

create_overlay(elementId, label, style = NULL, position = NULL)

Arguments

Value

An overlay object

Examples

# Example 1: Create an overlay with shape position "top-left"
overlay_style <- create_overlay_style(
  font_color = 'DarkSlateGray',
  font_size = 23,
  fill_color = 'MistyRose',
  stroke_color = 'Red'
)

overlay <- create_overlay(
  "my-shape-id",
  "My Overlay Label",
  style = overlay_style,
  position = overlay_shape_position[1]
)

# Example 2: Create an overlay with edge position "end"
overlay_style <- create_overlay_style(
  font_color = 'DarkSlateGray',
  font_size = 23,
  fill_color = 'MistyRose',
  stroke_color = 'Red'
)

overlay <- create_overlay(
  "my-edge-id",
  "My Overlay Label",
  style = overlay_style,
  position = overlay_edge_position[2]
)

Create the style of an overlay

Description

When adding an overlay to an existing element in a diagram, it's possible to customize its style.

Refer to the style parameter in the create_overlay function for more information.

Use this function to create the correct style structure for an overlay.

Usage

create_overlay_style(
  font_color = NULL,
  font_size = NULL,
  fill_color = NULL,
  stroke_color = NULL
)

Arguments

Value

The style object of the overlay

Create the style for BPMN shape

Description

Use this function to create the correct style structure for the shape.

Usage

create_shape_style(
  elementIds,
  stroke_color = NULL,
  stroke_width = NULL,
  stroke_opacity = NULL,
  font_color = NULL,
  font_family = NULL,
  font_size = NULL,
  font_bold = NULL,
  font_italic = NULL,
  font_strike_through = NULL,
  font_underline = NULL,
  font_opacity = NULL,
  opacity = NULL,
  fill_color = NULL,
  fill_opacity = NULL
)

Arguments

Value

A list representing the style for the BPMN shape.

Special keywords

default

• This keyword allows you to reset a style property of the BPMN element to its initial value.

• When applied to color properties, it bypasses the color specified in the 'BPMN' source if 'BPMN in Color' support is enabled. Instead, it uses the color defined in the default style of the 'BPMN' element..

inherit

Applies the value from the immediate parent element.

none

No color (used to hide strokes). Not available for font_color.

swimlane

Applies the value from the nearest parent element with type ShapeBpmnElementKind.LANE or ShapeBpmnElementKind.POOL.

Note

Opacity properties

• If the set value is less than 0, the used value is 0.

• If the set value is greater than 100, the used value is 100.

Warning: stroke_width property

Changing the stroke width of Activities may be misleading, as the default stroke widths have a meaning according to the 'BPMN' Specification.
For example, updating the stroke width of a task using the same value as the default stroke width of a Call Activity can be confusing.
In this case, you should also change another property, such as the stroke color, to allow the user to differentiate between them.

See Also

create_gradient_fill

Examples

# Create a style with a blue stroke, red font, and green fill color.
shape_style <- create_shape_style(
  elementIds = list('id_1', 'id_2'),
  stroke_color = "blue",
  stroke_width = 2,
  font_color = "red",
  fill_color = "green"
)

Display 'BPMN' diagram in an 'HTML' Widget

Description

Display 'BPMN' diagram based on 'BPMN' definition in 'XML' format

Usage

display(
  bpmnXML,
  overlays = NULL,
  enableDefaultOverlayStyle = TRUE,
  bpmnElementStyles = NULL,
  width = NULL,
  height = NULL,
  elementId = NULL
)

Arguments

Value

A bpmnVisualizationR widget that will intelligently print itself into 'HTML' in a variety of contexts including the 'R' console, within 'R Markdown' documents, and within 'Shiny' output bindings.

See Also

• create_overlay to create an overlay

• create_shape_style to create the structure style for the shape

• create_edge_style to create the structure style for the edge

Examples

# Load the BPMN file
bpmn_file <- system.file("examples/Order_Management.bpmn", package = "bpmnVisualizationR")

# Example 1: Display the BPMN diagram
bpmnVisualizationR::display(bpmn_file, width='auto', height='auto')

# Example 2: Display the BPMN diagram featuring overlays with their default positions and styles
overlays <- list(
  bpmnVisualizationR::create_overlay("start_event_1_1", "42"),
  bpmnVisualizationR::create_overlay("sequence_flow_1_1", "42"),
  bpmnVisualizationR::create_overlay("task_1_1", "9"),
  bpmnVisualizationR::create_overlay("sequence_flow_1_2", "8"),
  bpmnVisualizationR::create_overlay("call_activity_1_1", "7")
)

bpmnVisualizationR::display(
  bpmn_file,
  overlays,
  width='auto',
  height='auto'
)

# Example 3: Display the BPMN diagram featuring overlays using custom styles and positions
taskStyle <- bpmnVisualizationR::create_overlay_style(
  font_color = 'DarkSlateGray',
  font_size = 23,
  fill_color = 'MistyRose',
  stroke_color = 'Red'
)

flowStyle <- bpmnVisualizationR::create_overlay_style(
  font_color = 'WhiteSmoke',
  font_size = 19,
  fill_color = 'Teal',
  stroke_color = 'SpringGreen'
)

overlays <- list(
  bpmnVisualizationR::create_overlay("start_event_1_1", "42", position = "middle-left"),
  bpmnVisualizationR::create_overlay("sequence_flow_1_1", "42", flowStyle, "end"),
  bpmnVisualizationR::create_overlay("task_1_1", "9", taskStyle),
  bpmnVisualizationR::create_overlay("sequence_flow_1_2", "8"),
  bpmnVisualizationR::create_overlay("call_activity_1_1", "7")
)
bpmnVisualizationR::display(bpmn_file, overlays, width='auto', height='auto')

# Example 4: Display the BPMN diagram featuring overlays, 
# but exclude their default styles and positions
overlays <- list(
  bpmnVisualizationR::create_overlay("start_event_1_1", "42", position = "middle-left"),
  bpmnVisualizationR::create_overlay("sequence_flow_1_1", "42", flowStyle, "end"),
  bpmnVisualizationR::create_overlay("task_1_1", "9", taskStyle, "bottom-right"),
  bpmnVisualizationR::create_overlay("sequence_flow_1_2", "8",  position = 'start')
)

bpmnVisualizationR::display(
  bpmn_file,
  overlays,
  enableDefaultOverlayStyle=FALSE,
  width='auto',
  height='auto'
)

# Example 5: Display the BPMN diagram featuring styling for BPMN elements
bpmnElementStyles <- list(
  bpmnVisualizationR::create_shape_style(
    elementIds = list("call_activity_1_1"),
    stroke_color = 'RoyalBlue',
    font_color = 'DarkOrange',
    font_family = 'Arial',
    font_size = 12,
    font_bold = TRUE,
    font_italic = TRUE,
    font_strike_through = TRUE,
    font_underline = TRUE,
    opacity = 75,
    fill_color = 'Yellow',
    fill_opacity = 50
  ),
  bpmnVisualizationR::create_edge_style(
    elementIds = list("sequence_flow_1_4"),
    stroke_color = 'DeepPink',
    stroke_width = 3,
    stroke_opacity = 70,
    font_color = 'ForestGreen',
    font_family = 'Courier New',
    font_size = 14,
    font_bold = TRUE,
    font_italic = TRUE,
    font_strike_through = FALSE,
    font_underline = FALSE,
    font_opacity = 80,
    opacity = 80
  )
)

bpmnVisualizationR::display(
  bpmn_file,
  bpmnElementStyles = bpmnElementStyles,
  width='auto',
  height='auto'
)

The overlay positions on Edge

Description

To specify the position when creating an overlay object that will be attached to BPMN Edge elements in the diagram.

Usage

overlay_edge_position

Format

An object of class character of length 3.

Details

Use these constants as the position argument in the create_overlay function.

Positions:

• start

• end

• middle

See Also

create_overlay

Examples

# Create an overlay at the starting point of an edge
overlay <- create_overlay(elementId = 1, label = "My label", position = overlay_edge_position[1])

The overlay positions on Shape

Description

To specify the position when creating an overlay object that will be attached to BPMN Shape elements in the diagram.

Usage

overlay_shape_position

Format

An object of class character of length 8.

Details

Use these constants as the position argument in the create_overlay function.

Positions:

• top-left

• top-right

• top-center

• bottom-left

• bottom-right

• bottom-center

• middle-left

• middle-right

See Also

create_overlay

Examples

# Create an overlay at the top-left corner of a shape
overlay <- create_overlay(elementId = 1, label = "My label", position = overlay_shape_position[1])

'Shiny' render binding for the bpmnVisualizationR 'HTML' widget

Description

Helper to create render function for using the bpmnVisualizationR 'HTML' widget within 'Shiny' applications and interactive 'Rmd' documents.

Usage

renderBpmnVisualizationR(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

A render function that enables the use of the bpmnVisualizationR widget within 'Shiny' applications.