flows.md (8628B)
1 # Flows 2 3 Flows are a fundamental construct in the ValueFlows ontology. The types of flows form a progression from potential to scheduled to realized: 4 5 1. Intents which can lead to Commitments 6 2. Commitments which can lead to Economic Events (or Intents can lead directly to Economic Events) 7 8 ### Intent 9 10 Intents describe potential future events which have not been agreed to by other agents, such as offers and requests. Intents are often used for discovering another agent to participate in a desired event. On the process side, for example, planned work could be an Intent, but planned work that some agent committed to is a Commitment. 11 12 13 ### Commitment 14 15 Commitments describe potential future events which the involved agents have already agreed to pursue. Commitments can be considered contractual promises from one agent to another. Commitments can be thought of as plans of economic events, and Economic Events can fulfill Commitments. Commitments can satisfy Intents. 16 17 18 ### Economic Events 19 20 Economic Events describe past events, something observed, never some potential future event. They can fulfill Commitments or satisfy Intents (when there is no Commitment). 21 22 ### Claims 23 24 Claims resemble Commitments, but are initiated by the receiver, not the provider. An Economic Event can trigger a reciprocal Claim. Claims sometimes do not have to actually be saved, often they can be implied from an Economic Event and an Agreement. For example, if Alice has agreed to sell Bob some carrots for $2, then if Alice delivers the carrots to Bob, she has a claim for $2 from Bob. 25 26 ### Timeline, plans and observations 27 28 The figure below shows that Economic Events have to be observed and for that reason only appear as records of the past. Future plans get represented with Intents and Commitments. 29 30  31 32 ### Matching Intents 33 34 Often agents will start their plans independently and record their initial intents. Later once they make a Commitment with another agent, it will represent a specific shared part of their plans. For that reason any Commitment can result in Satisfaction of the providing agent's Intent as well as Satisfaction of the receiving agent's Intent. 35 36 37  38 39 ### Granularity 40 41 Intents, Commitments, and Economic Events can occur at any granularity that is needed or for which data can be obtained. So they primarily are used for all operational needs, but can also be used at higher levels for budgeting for organizations, analytical and high level planning needs for communities or regions, etc. 42 43  44 45 46 ### Actions 47 48 All flows use an action property to designate what the flow is doing and how it will affect an economic resource (or not). Actions are defined as follows. 49 50 * vf:produce - new resource created in that process or an existing stock resource added to 51 * vf:use - for example a tool used in process; after the process, the tool still exists 52 * vf:consume - for example an ingredient or component composed into the output, after the process the ingredient is gone 53 * vf:cite - for example a design file, neither used nor consumed, the file remains available at all times 54 * vf:work - labor power applied to a process 55 * vf:pickup - transported resource or person enters the process; the same resource will appear in output with *vf:dropoff* 56 * vf:dropoff - transported resource or person leaves the process; the same resource or person appeared in input with vf:pickup 57 * vf:accept - in processes like repair or modification or testing, the same resource will appear in output with *vf:modify* 58 * vf:modify - in processes like repair or modification, the same resource will appear in input with *vf:accept* 59 * vf:pack - put a resource into a container resource; the container resource is input with *vf:accept* 60 * vf:unpack - remove a resource from a container resource; the container resource is input with *vf:accept* 61 * vf:deliver-service - new service produced and delivered (a service implies that an agent actively receives the service) 62 * vf:transfer-all-rights - give full (in the human realm) rights and responsibilities to another agent, without transferring physical custody 63 * vf:transfer-custody - give physical custody and control of a resource, without full accounting or ownership rights 64 * vf:transfer - give full rights and responsibilities plus physical custody 65 * vf:move - change location and possibly identifier, if location is part of the identification, of a resource with no change of agent rights or possession 66 * vf:raise - adjusts a quantity up based on a beginning balance or inventory count 67 * vf:lower - adjusts a quantity down based on an inventory count 68 69 Action | Accounting effect | Onhand effect | I/O | Other effect | Pairs with | 70 ------ | ------ | --- | ----------------- | ---------- | --------- | 71 produce | Increment | Increment | Output | N/A | N/A | 72 consume | Decrement | Decrement | Input | N/A | N/A | 73 use | No effect(1) | No effect(1) | Input | N/A | N/A | 74 work | No effect(1) | No effect(1) | Input | N/A | N/A | 75 cite | No effect | No effect | Input | N/A | N/A | 76 deliver-service | No effect | No effect | Output(3) | N/A | N/A | 77 pickup | No effect | No effect | Input | N/A | dropoff | 78 dropoff | No effect | No effect | Output | currentLocation | pickup | 79 accept | No effect | Decrement | Input | N/A | modify | 80 modify | No effect | Increment | Output | N/A | accept | 81 pack | No effect | Decrement | Input | add containedIn | modify | 82 unpack | No effect | Increment | Output | remove containedIn | accept | 83 transfer-custody | No effect | Decr+Incr(2) | N/A | N/A | N/A | 84 transfer-all-rights | Decr+Incr(2) | No effect | N/A | N/A | N/A | 85 transfer | Decr+Incr(2) | Decr+Incr(2) | N/A | N/A | N/A | 86 move | Decr+Incr(2) |Decr+Incr(2) | N/A | currentLocation | N/A | 87 raise | Increment | Increment | N/A | N/A | N/A | 88 lower | Decrement | Decrement | N/A | N/A | N/A | 89 90 We have defined a core set of actions, but expect that this will be extended with some others. If extended, they should be defined as part of this or another formal vocabulary so that all can use them and assume the same meaning. 91 92 (1) The actions `use` and `work` are time-based actions, either with or without an explicit schedule. If the schedule is documented as part of the economic resource, then those economic events could decrement that schedule, although not the "current quantity" of the resource. 93 94 (2) The actions `transfer` and `move` can optionally define a second identified resource on the receiver side. 95 96 (3) The action `deliver-service` can sometimes be an input to another process, at the same time as it is an output from a process. This is because services imply delivery as they are created. 97 98 ### Quantities and Times 99 100 Quantities are used for counting, such as: 101 * Exchange/transfer 102 * Resource increment and decrement 103 * Recipes, how much or many goes into and out of a transformation process 104 105 Times are used for coordination and scheduling, such as: 106 * Calendar availability 107 * Planned timelines 108 109 They can be used together for analysis and reporting, such as: 110 * Accounting totals (quantity) within accounting period (time) 111 112 Quantities can be any needed unit of measure, including counts, volumes, weights, etc. Time can be a beginning/end time (an interval), or a point in time, or a due date. The flows require at least one of those. If a point in time is recorded, an application should return that time as the beginning and end time. 113 114 Note that recipes may need to scale both quantities and calendar times when used to create a plan. 115 116 Sometimes a quantity is expressed in time-based units, like "I worked 6 hours", or "we used this machine for 8 hours". These flows also will have a related time, like "I worked from 10am to 4pm", or "we used this machine from 8am to 4pm". In these examples, the quantity is used for accounting figures, exchange, recipes. The time is used to schedule and coordinate the work or machine usage. 117 118 Sometimes a situation may call for a "compound quantity", like "Number-per-Year". 119 120 Display note: The OM2 ontology defines a Unit called `one` that is used for one-dimensional units. This is confusing for many economic applications, where something like `each` would be used, or nothing at all. We recommend that user interfaces handle this by not displaying the unit `one` where it would be confusing, or substituting a more applicable name.