Quick Start

Here, we will demonstrate how to create a simple “Hello, world” application using Viewflow.

In this example, one person initiates a “Hello, world” request, another approves it, and when approved, the request is sent out. To follow this tutorial, we assume that you have already completed the initial part of the tutorial, configured Viewflow, and created a simple helloworld Django application.

To begin open the demo/settings.py and add viewflow.workflow into INSTALLED_APPS setting

INSTALLED_APPS = [
    ...
    'viewflow',
    'viewflow.workflow',
    'helloworld',
]

Define models

To define a process model with text and approved fields in Viewflow, navigate to helloworld/models.py and add the following code:

from django.db import models
from viewflow import jsonstore
from viewflow.workflow.models import Process


class HelloWorldProcess(Process):
    text = jsonstore.CharField(max_length=150)
    approved = jsonstore.BooleanField(default=False)

    class Meta:
        proxy = True

This creates a model that captures the process state during execution. The data field, which is a JSONField, is automatically included in the base process model, and the jsonstore package enables a part of the JSON to be exposed as normal Django fields.

Viewflow also supports models that inherit from the base Process model as well as proxy models. Proxy models can work more efficiently because they do not require additional joins during database requests.

Define flow

Now, let’s dive into the flow BPMN diagram and map each shape to its corresponding flow node definition.

Then open the demo/helloworld/flows.py file and define the following:

• Import the necessary modules and classes.
• Define the HelloWorldFlow class that represents the flow and inherit from viewflow.workflow.flow.Flow.
• Specify the process class that the flow will use.
• Define each attribute that represents a flow task and use the special this object to connect them together.

from viewflow import this
from viewflow.workflow import flow, lock, act
from viewflow.workflow.flow import views

from .models import HelloWorldProcess


class HelloWorldFlow(flow.Flow):
    process_class = HelloWorldProcess

    start = (
        flow.Start(views.CreateProcessView.as_view(fields=["text"]))
        .Annotation(title="New message")
        .Permission(auto_create=True)
        .Next(this.approve)
    )

    approve = (
        flow.View(views.UpdateProcessView.as_view(fields=["approved"]))
        .Permission(auto_create=True)
        .Next(this.check_approve)
    )

    check_approve = (
        flow.If(act.process.approved)
        .Then(this.send)
        .Else(this.end)
    )

    send = (
        flow.Function(this.send_hello_world_request)
        .Next(this.end)
    )

    end = flow.End()

    def send_hello_world_request(self, activation):
        print(activation.process.text)

For example, the flow.Start represents a task that is performed by a person in a Django view, and we use the built-in CreateProcessView for the tutorial purpose. The approve attribute represents a user task for an existing process that requires approval, and so on.

To control the flow, we use the simple exclusive gateway represented by the flow.If task. It selects an outcome depending on a callable result. If the request is approved, the flow.Script task will be executed. This task is performed by synchronous Python code call, and a this-reference could be used to point to a flow instance method or any Python callable.

Finally, flow.End marks the process as completed. Viewflow proceeds all application flows from the flows.py file, so you can add more flows as needed.

Expose the flow

In this step, we’ll expose the HelloWorldFlow we’ve created earlier. it contains URL patterns for nodes execution, details, and management actions like undo/redo. We’ll also combine it with views for Inbox/Queue/Archive list views for end-users from FlowAppViewset.

To start, open config/urls.py and add the FlowAppViewset to your application. Here’s a code snippet you can use as a reference:

from django.urls import path
from viewflow.contrib.auth import AuthViewset
from viewflow.urls import Application, Site, ModelViewset
from viewflow.workflow.flow import FlowAppViewset
from helloworld.flows import HelloWorldFlow


site = Site(title="ACME Corp", viewsets=[
    Application(
        title='Sample App', icon='people', app_name='sample', viewsets=[
            FlowAppViewset(HelloWorldFlow, icon="assignment"),
        ]
    ),
])

urlpatterns = [
    path('accounts/', AuthViewset(with_profile_view=False).urls),
    path('', site.urls),
]

Once you’ve added the FlowAppViewset to your application, you’re ready to run and explore your workflow.

Run and explore

To see the workflow in action, create migrations for the helloworld app by running the following command in your terminal:

./manage.py makemigrations helloworld

Then, apply the migrations by running:

./manage.py migrate

Finally, run the server by executing:

./manage.py runserver

Once the server is up and running, go to http://127.0.0.1:8000 in your web browser and explore your workflow. You should see the hello world process listed and ready to be initiated.