GithubHelp home page GithubHelp logo

flow's Introduction

Build Status Go Report Card GoDoc

STATUS

flow is usable in its current state, even though it hasn't acquired all the desired functionality.

N.B. Those who intend to use flow should always use the most recent release. DO NOT use master!

flow

flow is a tiny open source (Apache 2-licensed) workflow engine written in Go (golang).

What flow is

As a workflow engine, flow intends to help in defining and driving "front office" <---> "back office" document flows. Examples of such flows are:

  • customer registration and verification of details,
  • assignment of work to field personnel, and its follow-up,
  • review and approval of documents, and
  • trouble ticket life cycle.

flow provides value in scenarios of type "programming in the large", though it is not (currently) distributed in nature. As such, it addresses only orchestration, not choreography!

flow - at least currently - aims to support only graph-like regimes (not hierarchical).

What flow is not

flow is a library, not a full-stack solution. Accordingly, it cannot be downloaded and deployed as a ready-to-use service. It has to be used by an application that programs workflow definitions and processing. The only "programming in the small" language supported is Go! Of course, you could employ flow in a microservice architecture by wrapping it in a thin service. That can enable you to use your favourite programming language to drive flow.

Express non-goals

flow is intended to be small! It is expressly not intended to be an enterprise-grade workflow engine. Accordingly, import from - and export to - workflow modelling formats like BPMN/XPDL are not supported. Similarly, executable specifications like BPEL and Wf-XML are not supported. True enterprise-grade engines already exist for addressing such complex workflows and interoperability as require high-end engines.

flow Concepts

Let us familiarise ourselves with the most important concepts and moving parts of flow. Even as you read the following, it is highly recommended that you read the database table definitions in sql directory, as well as the corresponding object definitions in their respective *.go files. That should help you in forming a mental model of flow faster.

Users

flow neither creates nor manages users. It assumes that an external identity provider is in charge of user management. Similarly, flow does not deal with user authentication, nor does it manage authorisation of tasks not flowing (pun intended) though it!

Accordingly, users in flow are represented only by their unique IDs, names and unique e-mail addresses. The identity provider has to also provide the status of the user: active vs. inactive.

Groups

flow, similar to most UNIXes, implicitly creates a group for each defined user. This is a singleton group: its only member is the corresponding user.

In addition, arbitrary general (non-singleton) groups can be defined by including one or more users as members. The relationship between users and groups is M:N.

Roles

Sets of document actions permitted for a given document type, can be grouped into roles. For instance, some users should be able to raise a request, but not approve it. Some others should be able to, in turn, approve or reject it. Roles make it convenient to group logically related sets of permissions.

See Document Types and Document Actions for more details.

Access Contexts

An access context is a namespace that defines jurisdictions of permissions granted to users and groups. Examples of such jurisdictions include departments, branches, cost centres and projects.

Within an access context, a given user (though the associated singleton group) or group can be assigned one or more roles. The effective set of permissions available to a user - in this access context - is the union of the permissions granted through all roles assigned to this user, through all groups the user is included in.

Document Types

Each type of document, whose workflow is managed by flow, has a unique DocType that is defined by the consuming application. Document types are one of the central concepts in flow. They serve as namespaces for several other types of entities.

A document type is just a string. flow does not assume anything about the specifics of any document type. Nonetheless, it is highly recommended, but not necessary, that document types be defined in a system of hierarchical namespaces. For example:

PUR:RFQ

could mean that the department is 'Purchasing', while the document type is 'Request For Quotation'. As a variant,

PUR:ORD

could mean that the document type is 'Purchase Order'.

Document States

Every document has various stages in its life. The possible stages in the life of a document are encoded as a set of DocStates specific to its document type.

A document state is just a string. flow does not assume anything about the specifics of any document state.

Document Actions

Given a document in a particular state, each legal (for that state) action on the document could result in a new state. DocActions enumerate possible actions that affect documents.

A document action is just a string. flow does not assume anything about the specifics of any document action.

Documents

A document comprises:

  • title,
  • body (usually, text),
  • enclosures/attachments (optional),
  • tags (optional) and
  • children documents (optional).

Thus, Document is a recursive structure. As a document transitions from state to state, a child document is created and attached to it. Thus, documents form a hierarchy, much like an e-mail thread, a discussion forum thread or a trouble ticket thread.

Only root documents have their own titles. Similarly, only root documents participate in workflows. Children documents follow their root documents along.

Workflows

Each DocType defined in flow should have an associated Workflow defined. This workflow handles the lifecycle of documents of that type.

A workflow is begun when a document of a particular type is created. This workflow then tracks the document as it transitions from one document state to another, in reponse to either user actions or system events. These document states and their transitions constitute the defining graph of this workflow.

Document Events

A DocEvent represents a user (or system) DocAction on a particular document that is in a particular DocState. They record the agent casuing them (system/which user), as well as the time when the action was performed.

Nodes

A document in a particular state in its workflow, is sent to a Node. There, it awaits an action to take place that moves it along the workflow, to a different state. Thus, nodes are receivers of document events.

A DocAction on a document in a DocState may require some processing to be performed before a possible state transition. Accordingly, applications can register custom processing functions with nodes. Such functions are invoked by the respective nodes when an action is received by them. These NodeFuncs generate the messages that are dispatched to applicable mailboxes.

Mailboxes and Messages

Every defined user has a Mailbox of virtually no size limit. Documents that transition into specific states trigger notifications for specific users. These notifications are delivered to the mailboxes of such users.

The actual content of a notification constitutes a Message. The most essential details include the document reference, the Node in the workflow at which the document is, and the time at which the message was sent.

Upon getting notified, users open the corresponding documents, and take appropriate actions.

Example Structure

The following is a simple example structure.

Document Type : docType1
Document States : [
    docState1, docState2, docState3, docState4 // for example
]
Document Actions : [
    docAction12, docAction23, docAction34 // for the above document states
]
Document Type State Transitions : [
    docState1 --docAction12--> docState2,
    docState2 --docAction23--> docState3,
    docState3 --docAction34--> docState4,
]

Access Contexts : [
    accCtx1, accCtx2 // for example
]

Workflow : {
    Name : wFlow1,
    Initial State : docState1
}
Nodes : [
    node1: {
        Document Type : docType1,
        Workflow : wFlow1,
        Node Type : NodeTypeBegin, // note this
        From State : docState1,
        Access Context : accCtx1,
    },
    node2: {
        Document Type : docType1,
        Workflow : wFlow1,
        Node Type : NodeTypeLinear, // note this
        From State : docState2,
        Access Context : accCtx2, // a different context
    },
    node3: {
        Document Type : docType1,
        Workflow : wFlow1,
        Node Type : NodeTypeEnd, // note this
        From State : docState3,
        Access Context : accCtx1,
    },
]

With the above setup, we can dispatch document events to the workflow appropriately. With each event, the workflow moves along, as defined.

flow's People

Contributors

js-ojus avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

flow's Issues

Hi,can you help me a example?

I am trying like these:

dtID1, err := flow.DocTypes.New(tx, "图纸设计") //dtID1
	if err != nil {
		fmt.Println(err)
	}
	// dtID2, err := flow.DocTypes.New(tx, "图纸校核") //dtID1
	// if err != nil {
	// 	fmt.Println(err)
	// }
	_, err = flow.DocTypes.New(tx, "变更立项") //dtID2
	if err != nil {
		fmt.Println(err)
	}
	dsID1, err := flow.DocStates.New(tx, "设计中...") //初始化
	if err != nil {
		fmt.Println(err)
	}
	dsID2, err := flow.DocStates.New(tx, "校核中...") //委托创建
	if err != nil {
		fmt.Println(err)
	}
	_, err = flow.DocStates.New(tx, "审查中...")
	if err != nil {
		fmt.Println(err)
	}
	flow.DocStates.New(tx, "批注中...")
	flow.DocStates.New(tx, "申报中...")
	flow.DocStates.New(tx, "评估中...")
	flow.DocStates.New(tx, "审批中...")
	// flow.DocStates.New(tx, "DataApproved")
	// flow.DocStates.New(tx, "ReportGen")
	// flow.DocStates.New(tx, "ReportApproved")

	daID1, err := flow.DocActions.New(tx, "提交设计", false) //改变状态设计中...为校核中...
	if err != nil {
		fmt.Println(err)
	}
	daID2, err := flow.DocActions.New(tx, "校核", false)
	if err != nil {
		fmt.Println(err)
	}
	daID3, err := flow.DocActions.New(tx, "审查", false)
	if err != nil {
		fmt.Println(err)
	}
	daID4, err := flow.DocActions.New(tx, "核定", true)
	if err != nil {
		fmt.Println(err)
	}
	daID5, err := flow.DocActions.New(tx, "评估", true)
	if err != nil {
		fmt.Println(err)
	}
	daID6, err := flow.DocActions.New(tx, "审批", false)
	if err != nil {
		fmt.Println(err)
	}
	daID7, err := flow.DocActions.New(tx, "立项", false)
	if err != nil {
		fmt.Println(err)
	}

	workflowID1, err := flow.Workflows.New(tx, "图纸设计流程", dtID1, dsID1) //初始状态是“设计中...”
	if err != nil {
		fmt.Println(err)
	}
	// workflowID2, err := flow.Workflows.New(tx, "图纸校核流程", dtID2, dsID2) //初始状态是“设计中...”
	// if err != nil {
	// 	fmt.Println(err)
	// }

	accessContextID1, err := flow.AccessContexts.New(tx, "Context")
	if err != nil {
		beego.Error(err)
	}
	// AddNode maps the given document state to the specified node.  This
	// map is consulted by the workflow when performing a state transition
	// of the system.nodeID1
	// _, err = flow.Workflows.AddNode(tx, dtID1, dsID1, accessContextID1, workflowID1, "图纸三角校审流程-设计", flow.NodeTypeLinear)
	// if err != nil {
	// 	fmt.Println(err)
	// }
	_, err = flow.Workflows.AddNode(tx, dtID1, dsID2, accessContextID1, workflowID1, "图纸三角校审流程-校核", flow.NodeTypeEnd)
	if err != nil {
		fmt.Println(err)
	}

	res, err := tx.Exec(`INSERT INTO users_master(first_name, last_name, email, active)
			VALUES('秦', '晓川-1', '[email protected]', 1)`)
	if err != nil {
		log.Fatalf("%v\n", err)
	}
	uid, _ := res.LastInsertId()
	uID1 := flow.UserID(uid)
	_, err = flow.Groups.NewSingleton(tx, uID1)

	res, err = tx.Exec(`INSERT INTO users_master(first_name, last_name, email, active)
			VALUES('秦', '晓川-2', '[email protected]', 1)`)
	if err != nil {
		log.Fatalf("%v\n", err)
	}
	uid, _ = res.LastInsertId()
	uID2 := flow.UserID(uid)
	_, err = flow.Groups.NewSingleton(tx, uID2)

	res, err = tx.Exec(`INSERT INTO users_master(first_name, last_name, email, active)
			VALUES('秦', '晓川-3', '[email protected]', 1)`)
	if err != nil {
		log.Fatalf("%v\n", err)
	}
	uid, _ = res.LastInsertId()
	uID3 := flow.UserID(uid)
	_, err = flow.Groups.NewSingleton(tx, uID3)

	res, err = tx.Exec(`INSERT INTO users_master(first_name, last_name, email, active)
			VALUES('秦', '晓川-4', '[email protected]', 1)`)
	if err != nil {
		log.Fatalf("%v\n", err)
	}
	uid, _ = res.LastInsertId()
	uID4 := flow.UserID(uid)
	_, err = flow.Groups.NewSingleton(tx, uID4)

	gID1 := fatal1(flow.Groups.New(tx, "设计人员组", "G")).(flow.GroupID)
	gID2 := fatal1(flow.Groups.New(tx, "校核人员组", "G")).(flow.GroupID)
	fatal0(flow.Groups.AddUser(tx, gID1, uID1))
	fatal0(flow.Groups.AddUser(tx, gID1, uID2))
	fatal0(flow.Groups.AddUser(tx, gID1, uID3))

	fatal0(flow.Groups.AddUser(tx, gID2, uID2))
	fatal0(flow.Groups.AddUser(tx, gID2, uID3))
	fatal0(flow.Groups.AddUser(tx, gID2, uID4))
	roleID1 := fatal1(flow.Roles.New(tx, "设计人员角色")).(flow.RoleID)
	roleID2 := fatal1(flow.Roles.New(tx, "校核人员角色")).(flow.RoleID)
	//给角色赋予action权限
	fatal0(flow.Roles.AddPermissions(tx, roleID1, dtID1, []flow.DocActionID{daID1, daID2, daID3, daID4}))
	fatal0(flow.Roles.AddPermissions(tx, roleID2, dtID1, []flow.DocActionID{daID1, daID2, daID3, daID4, daID5, daID6, daID7}))
	//给用户组赋予角色
	err = flow.AccessContexts.AddGroupRole(tx, accessContextID1, gID1, roleID1)
	if err != nil {
		beego.Error(err)
	}
	err = flow.AccessContexts.AddGroupRole(tx, accessContextID1, gID2, roleID2)
	if err != nil {
		beego.Error(err) 
	}

	tx.Commit()

and then:

dtID1, err := flow.DocTypes.GetByName("图纸设计")
	if err != nil {
		beego.Error(err)
	}
	beego.Info(dtID1)
	//查询context
	accessContextID1, err := flow.AccessContexts.List("Context", 0, 0)
	if err != nil {
		beego.Error(err)
	}
	beego.Info(accessContextID1[0].ID)
	beego.Info(flow.GroupID(1))
	docNewInput := flow.DocumentsNewInput{
		DocTypeID:       dtID1.ID,
		AccessContextID: accessContextID1[0].ID,
		GroupID:         5, //groupId,
		Title:           "厂房布置图",
		Data:            "设计、制图: 秦晓川1, 校核: 秦晓川2",
	}
	// flow.Documents.New(tx, &docNewInput)
	DocumentID1, err := flow.Documents.New(tx, &docNewInput)
	if err != nil {
		beego.Error(err)
	}
	// tx.Commit() 
	beego.Info(DocumentID1)
	dsID2, err := flow.DocStates.GetByName("校核中...")
	if err != nil {
		fmt.Println(err)
	}
	beego.Info(dsID2)
	daID2, err := flow.DocActions.GetByName("提交设计")
	if err != nil {
		fmt.Println(err)
	}
	beego.Info(daID2)
	beego.Info(flow.GroupID(2))
	docEventInput := flow.DocEventsNewInput{
		DocTypeID:   dtID1.ID, //flow.DocTypeID(1),
		DocumentID:  DocumentID1,
		DocStateID:  dsID2.ID,
		DocActionID: daID2.ID, //flow.DocActionID(2),
		GroupID:     6,
		Text:        "校核",
	}

	docEventID1, err := flow.DocEvents.New(tx, &docEventInput)
	if err != nil {
		beego.Error(err)
	}
	tx.Commit() 
	beego.Info(docEventID1)
	myDocEvent, err := flow.DocEvents.Get(docEventID1)
	if err != nil {
		beego.Error(err)
	}
	beego.Info(myDocEvent)
	// myWorkflow, err := flow.Workflows.Get(workflowId.ID)
	// if err != nil {
	// 	beego.Error(err)
	// }
	myWorkflow, err := flow.Workflows.GetByName("图纸设计流程")
	if err != nil {
		beego.Error(err)
	}
	beego.Info(myWorkflow)
	//给出接受的组groupids
	groupIds := []flow.GroupID{flow.GroupID(6)}
	beego.Info(groupIds)
	newDocStateId, err := myWorkflow.ApplyEvent(tx, myDocEvent, groupIds)
	if err != nil {
		beego.Error(err)
	}
	tx.Commit() 
	fmt.Println("newDocStateId=", newDocStateId, err)

I don't know how to use the flow. Can you give me some advice?

Stalled

Is this project stalled.
Are you going to put any examples in the repo.

I ask because it's quite useful code base for BPM

flow-ui online

flow-ui online #113
In order to facilitate everyone to understand and use flow, I wrote a demo with vue.js+element+vue-element-extends+beego and put it on tencent cloud. It is just a preliminary one,at present it has the function of adding, but cant delete and modify.
Snap3
Snap5

Can't delete groups which received messages

If a group received messages and a mailbox created for it, then an error would be raised if you try to delete it.

update or delete on table "wf_groups_master" violates foreign key constraint "wf_mailboxes_group_id_fkey" on table "wf_mailboxes"

Maybe Groups.Delete should also delete the Group mailbox, or Mailboxes should provide a Delete method?

Can you perfect the example again?

Thank you very much for the previous example.
Can you perfect the example again?

For example, when I create a new documents, do I create their events at the same time? Or create a new event and apply it to workflow when I clicks the action button?

In the list of documents presented to the user, for each document, is it right to list all possible actions and next states according to transition? When the user clicks on the action button, do I just create a new event and then apply it to workflow?

When I create a new event, it returns DocEventID, but what workflow applyevent needs is an DocEvent. Feel that I do is not correct.

Can you make a easy turtorial?

Hi the information of flow is too little。can you make a turtorial that a blog or a website? i think is very useful for some people who is new beginner of flow.

The node which belongs to NodeTypeEnd should refuse the requests to apply event.

Hi, I think the node should refuse the request to apply event if it is in NodeTypeEnd. How do you think so?

the code:

func (n *Node) applyEvent(otx *sql.Tx, event *DocEvent, recipients []GroupID) (DocStateID, error) {
    ...
    switch tnode.NodeType {
    ...
    case NodeTypeBegin, NodeTypeEnd, NodeTypeLinear, NodeTypeBranch:
        ....
    }
}

Check group id is singleton when create a new event?

Hi, I have read your code and has a little confused. When creating a new event without check the group id is singleton, that may be will cause we do not know who create this event if the group is type of 'G' and has more than one user. Yeah, the workflow also do not check the group type, so the event can be applied. Is there a problem?

good job~

This workflow is what I need, and I'm going to make it in beego.Thanks.

Why is unique(doctype_id, docstate_id), but not unique(doctype_id, docstate_id, ac_id)?

Hi, I have some question about workflow node after reading wf_workflow_nodes.sql. If I want to create two workflows for the same doctype, for example, A -> B -> C and E -> B -> F. Now, since the constraints of table wf_workflow_nodes.sql, the two flows on the node B will has the same ac_id and will have the same access context which means the same permission. So, why not change to unique(doctype_id, docstate_id, ac_id), so we can give the different permission to node B in the two or more wrokflows?

Tx is nil bug!!

@js-ojus

Hi, I have found that the following code is a bug:

	var tx *sql.Tx
	if otx == nil {
		tx, err := db.Begin()
		if err != nil {
			return 0, err
		}
		defer tx.Rollback()
	} else {
		tx = otx
	}

here tx, err := db.Begin() will make a temporary variable tx, so out of the if statement, tx also will be a nil value. Thus, when you call the interface which need parameter *sql.Tx and you give a nil to it, it will cause a panic. For example:

        gid, err := flow.Groups.New(nil, "nike", "G")

I give nil to Groups.New because I have called RegisterDB to make db is not null.

We can use this code to fix it:

    var tx *sql.Tx
    if otx == nil {
        var err error
        tx, err = db.Begin()
        if err != nil {
            return 0, err
        }
        defer tx.Rollback()
    } else {
        tx = otx
    }

Do you have plans to provide a version that supports sqlite databases?

Do you have plans to provide a version that supports sqlite databases? I tried to change your code to support sqlite. The original SQL language is a bit different for mysql and sqlite. If you are considering using a golang orm library like xorm, the flow may have extensive database support.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.