Usage Documentation

ProcessPiper Usage Documentation

Usage

There are two methods to generate BPMN diagrams:

1. Use PiperFlow: This allows you to generate BPMN diagrams using English like syntax. This is useful if you want to generate BPMN diagrams from a text file or a database. The aim is to make it easier for non-technical users to generate BPMN diagrams.
2. Use python code: You generate BPMN diagrams by leveraging Processpiper library.

Method 1: Generate BPMN diagram using English like PiperFlow syntax

To create a process map using PirperFlow, you need to define the diagram using a specific syntax. Here is an example:

from processpiper.text2diagram import render

input_syntax = """
title: Sample Test Process
colourtheme: GREENTURTLE
    lane: End User
        (start) as start
        [Enter Keyword] as enter_keyword
        (end) as end
    pool: System Search
        lane: Database System
            [Login] as login
            [Search Records] as search_records
            <Result Found?> as result_found
            [Display Result] as display_result
            [Logout] as logout
        lane: Log System
            [Log Error] as log_error

    start->login->enter_keyword->search_records->result_found->display_result->logout->end
    result_found->log_error->display_result

    footer: Generated by ProcessPiper
"""

render(input_syntax, "my_diagram.png")

• Import the render function from processpiper.text2diagram
• Call the render function with the input syntax and the output file name.

Syntax

Diagram Configurations

The PiperFlow syntax for defining a process map is as follows:

• title: The title of the diagram.
• footer: The footer text to display on the diagram.
• width : (Optional) Specify the width of the diagram.
• colourtheme: The colour theme to use

Lane & Pool Configurations

• lane: The name of the lane.
• pool: The name of the pool.

Element/Shape Configurations

• To add elements to the lane, use one of the following tags. You place your element description within the tag:
  • Use ( and ) to create event element
    • use (start) to create a start event
    • use (end) to create an end event
    • use (@timer and ) to create a timer event. Example (@timer Trigger every 1 hour) as timer_event
    • use (@intermediate and ) to create an intermediate event. Example (@intermediate Message Received) as intermediate_event
    • use (@message and ) to create a message event
    • use (@signal and ) to create a signal event
    • use (@conditional and ) to create a conditional event
    • use (@link and ) to create a link event
  • Use [ and ] to create an activity. By default, the activity type is TASK. Example [Place Order] as place_order
    • use [@subprocess] to create a subprocess. Example `[@subprocess Get Approval] as get_approval``
  • Use < and > to create a gateway. By default, the gateway type is EXCLUSIVE. Example <Result Found?> as result_found
    • Use <@parallel and > to create a parallel gateway. Example <@parallel Span Out> as span_out
    • Use <@inclusive and > to create an inclusive gateway. Example <@inclusive Condition Met?> as condition_met
    • Use <@event and > to create an event gateway

Connection Configurations

• To connect two elements, use ->. You can chain multiple connections using ->:
  • Example:
    • login->enter_keyword
    • start->login->enter_keyword->search_records->result_found->display_result->logout->end
• To add label to the connection, add ":" when connecting elements. ❗ NOTE: This is a breaking change in v0.6. Versions prior to 0.6 use start-"Enter Credentials->login syntax. See this page for more information.
  • Example:
    • start->login: Enter credentials
• To specify the connection point manually, add connection side. See How to select sides for more information.
  • Example:
    • start-(bottom, top)->login
    • start-(bottom, top)->login: Enter credentials

Indentation is not required. However, it is recommended to use indentation to make the diagram easier to read.

Saving and Drawing the Diagram

To render and the diagram as a PNG file, you can use the render method:

Examples

input_syntax = """
title: Test Process
colourtheme: GREENTURTLE
pool: Pool A
    lane: Lane A
        (start) as start
        [Task 1] as task1
        <branch 1> as branch1
        [@subprocess Sub process 1] as subprocess1
        <@parallel branch 2> as branch2
        <@inclusive branch 3> as branch3
        (end) as end
pool: Pool B
    lane: Lane B
        (@timer schedule 1) as timer_schedule
        (@intermediate schedule 2) as intermediate_schedule

start->task1->branch1->subprocess1->branch2->branch3->end
branch1->timer_schedule->intermediate_schedule->end

footer: Generated by Process Piper
"""

• render() method now returns python code and generated diagram in PIL.Image format.

gen_code, img = render(input_syntax)
print(f"Generated code:\n{gen_code}")
img.save("my_diagram.png")

• If you want to see colour coded code without print it out in your code, you can do so by passing in show_code=True.

gen_code, img = render(input_syntax, show_code=True)

• To save the generated diagram in SVG format, specify the output_file parameter with a 'SVG' file name extension.

render(input_syntax, output_file = "my_diagram.svg")

• To export the diagram to .bpmn (XML) format, set the optional export_to_bpmn parameter to True.

render(input_syntax, output_file = "my_diagram.svg", export_to_bpmn = True)

The .bpmn file name will follow .svg file name. If your output_file is "my_diagram.svg", the exported .bpmn file name will be "my_diagram.bpmn"

Method 2: Generate BPMN diagram using python code

To use ProcessPiper library, you need to import the necessary classes and functions:

from processpiper import ProcessMap, EventType, ActivityType, GatewayType

Creating a Process Map

To create a process map, you need to create a ProcessMap object and specify the title of the diagram:

with ProcessMap("Sample Process Map") as my_process_map:

Note:

• By default, ProcessPiper saves diagram in PNG format. You can change it to SVG format, by specifying painter type when creating ProcessMap:

with ProcessMap("Sample Process Map", painter_type = "SVG") as my_process_map:

Adding Pool

To add a pool to the process map, you can use the add_pool method. You can also use the with statement to add a pool:

with ProcessMap("Sample Process Map") as my_process_map:
    with my_process_map.add_pool("Application") as my_pool:

Adding Lanes and Elements

To add lanes and elements to the process map, you can use the add_lane and add_element methods:

with my_process_map.add_lane("Application User") as lane1:
    start = lane1.add_element("Start", EventType.START)
    login = lane1.add_element("Login", ActivityType.TASK)
    search_records = lane1.add_element("Search Records", ActivityType.TASK)
    result_found = lane1.add_element("Result Found?", GatewayType.EXCLUSIVE)
    display_result = lane1.add_element("Display Result", ActivityType.TASK)
    logout = lane1.add_element("Logout", ActivityType.TASK)
    end = lane1.add_element("End", EventType.END)

• There are several types of elements that you can add to the diagram. You can use the EventType, ActivityType, and GatewayType classes to specify the type of the element.
  • Event types: EventType.START, EventType.END, EventType.INTERMEDIATE, EventType.TIMER, EventType.MESSAGE, EventType.SIGNAL, EventType.CONDITIONAL, EventType.LINK
  • Activity types: ActivityType.TASK, ActivityType.SUBPROCESS
  • Gateway types: GatewayType.EXCLUSIVE, GatewayType.INCLUSIVE, GatewayType.PARALLEL, GatewayType.EVENT

Connecting Elements

To connect elements, you can use the connect method:

start.connect(login).connect(search_records).connect(result_found)
result_found.connect(display_result).connect(logout).connect(end)
result_found.connect(search_records)

Adding label

To add a label to the connection, add your label as the second parameter to the connect method:

start.connect(login, "Enter Credentials")

Specifying connection sides

See How to select connection sides for more information.

Drawing and Saving the Diagram

To draw the diagram on the screen, you can use the draw method. To save the diagram as a PNG file, you can use the save method:

my_process_map.draw()
my_process_map.save("my_diagram.png")

Changing the Colour Theme

ProcessPiper comes with several colour themes that you can use to change the appearance of your diagrams. To change the colour theme, specify the colour theme name when you create the ProcessMap object:

with ProcessMap("Sample Process Map", colour_theme="GREENTURTLE") as my_process_map:

Ten colour themes are available:

• GREENTURTLE
• BlUEMOUNTAIN
• GREYWOOF
• ORANGEPEEL
• SUNFLOWER (available in v0.6)
• PURPLERAIN (available in v0.6)
• RUBYRED (available in v0.6)
• TEALWATERS (available in v0.6)
• SEAFOAMS (available in v0.6)

See Gallery for all the colour themes.

Examples

with ProcessMap(
        "Shipment Process of a Hardware Retailer", colour_theme="BLUEMOUNTAIN"
    ) as my_process_map:
        with my_process_map.add_pool("Hardware Retailer") as pool1:
            with pool1.add_lane("Logistics Manager") as lane1:
                take_insurance = lane1.add_element("Take Insurance", ActivityType.TASK)

            with pool1.add_lane("Clerk") as lane2:
                start = lane2.add_element("Goods to ship", EventType.START)
                branching1 = lane2.add_element("", GatewayType.PARALLEL)
                decide = lane2.add_element(
                    "Decide if normal post or special shipment", ActivityType.TASK
                )
                branching2 = lane2.add_element(
                    "Mode of Delivery", GatewayType.EXCLUSIVE
                )
                check_extra_insurance = lane2.add_element(
                    "Check if extra insurance is needed", ActivityType.TASK
                )
                branching3 = lane2.add_element("", GatewayType.INCLUSIVE)
                fill_in_post = lane2.add_element(
                    "Fill in a Post label", ActivityType.TASK
                )
                branching4 = lane2.add_element("", GatewayType.INCLUSIVE)

                request_quote = lane2.add_element(
                    "Request quotes from carriers", ActivityType.TASK
                )
                assign_carrier = lane2.add_element(
                    "Assign carrier & prepare paper work", ActivityType.TASK
                )
                branching5 = lane2.add_element("", GatewayType.EXCLUSIVE)

            with pool1.add_lane("Warehouse Worker") as lane3:
                package_goods = lane3.add_element("Package goods", ActivityType.TASK)
                branching6 = lane3.add_element("", GatewayType.PARALLEL)
                add_paperwork = lane3.add_element(
                    "Add paperwork to move package to pick area", ActivityType.TASK
                )
                end = lane3.add_element("Goods available for pick up", EventType.END)

            start.connect(branching1)
            branching1.connect(decide).connect(branching2)
            branching1.connect(package_goods).connect(branching6)

            branching2.connect(check_extra_insurance).connect(branching3)
            branching2.connect(request_quote).connect(assign_carrier).connect(
                branching5
            )

            branching3.connect(take_insurance).connect(branching4)
            branching3.connect(fill_in_post).connect(branching4)

            branching4.connect(branching5).connect(branching6)

            branching6.connect(add_paperwork).connect(end)

            my_process_map.set_footer("Generated by ProcessPiper")
            my_process_map.draw()
            my_process_map.save(output_file)