Use cases to cover decision on event vs resource model

[fosterlynn]

We have been discussing how to model events (just looking at process related events right now) and how they work in relation to resources. We think we need to look at several use cases to make sure we are picking the simplest and most consistent model. I think we need to include all the data we could support in each use case, including agents and quantities.

The proposals thus far:

1. An event refers primarily to the resource at the end that it either increments or decrements (or neither), depending on its action. We can also refer to other resources inside a process secondarily and optionally, as needed by the process. The event holds the quantity to decrement or increment.
2. An event refers primarily to a resource that is inside the process and is split from its beginning resource in a separate process, or will be merged with its end resource in another process. The resource held by the event holds the quantity. @elf-pavlik please re-word if this is not right.

Here is a first attempt at a smallish list that would cover the discussion. Feel free to add or modify!

1. Serialized resources contained within a stock resource. Some of the serialized resources are transported, and added to a different stock resource on the other end.
   a. Different context agents for receiver, carrier, provider.
   b. All same context agent.
2. Input part of a stock type resource to a manufacturing process to be consumed. Resource is logically identified only by resource type and context agent. Input another resource to be used, a serialized one. Produce an item that is added to an existing stock resource, logically identified by context, resource type, and location. Also produce a new resource (perhaps a by-product), logically identified by context and resource type. All within one context.
3. Workflow with 3 processes, first one creates a resource, the next 2 improve that resource. Include some work. Resource is a knowledge resource, not worrying about its binary representation. All within one context.
4. Return all the events (of different types) for a resource and put in a uniform table report format showing all info. Events which increment or decrement should show the quantities.
5. Return a list of all inventory that needs to be managed by an inventory manager for a context.
6. Visualize how resources flow between stocks through processes. See subsequent comment for details.

[fosterlynn]

I made a few edits to the above. I'm going to start trying them out, but can modify if people want to change the cases. We could use @elf-pavlik 's most recent bike use case for 1., https://github.com/valueflows/process/issues/9#issuecomment-238034369, if people like. For 2., maybe a FabLab type use case or Sensorica one, with different projects within the network who work closely together. For 3., maybe a translation?

[fosterlynn]

From gitter chat, @elf-pavlik will start with 1, using the bike use case. I'll start with 2, using the 3d printer use case, simplified.

YAML will include all beginning resource states, process and events, all ending resource states.

[elf-pavlik]

1. Serialized resources contained within a stock resource. Some of the serialized resources are transported, and added to a different stock resource on the other end.
   • a. Different context agents for receiver, carrier, provider.

Transporting two bicycles based on https://github.com/valueflows/process/issues/9#issuecomment-238034369. Here without bundling them together to load & unload.

Before

Only CoHouse has access to information about https://cohouse.example/inventory/bicycles#stock

'@context': https://w3id.org/valueflows/v1
'@id': https://cohouse.example/inventory/bicycles#stock
'@type':
  - vf:Resource
  - prodont:Bicycle
'skos:note': our shared pool of bicycles
'vf:currentLocation': https://cohouse.example/bikeshed#location
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Each
  'qudt:numericValue': 5
'vf:contains':
  - https://cohouse.example/inventory/0030b345-c9f9-4e3a-a5a6-b45a8137aa05#resource
  - https://cohouse.example/inventory/49fc39ff-be2b-4653-87ff-b18e2f20063b#resource
  - https://cohouse.example/inventory/a64f0db3-4a62-404e-b46e-4753fb886ea3#resource
  - https://cohouse.example/inventory/40f5148b-710c-4215-ab4d-fee66d8d4f96#resource
  - https://coride.example/inventory/24129b9b-c684-4ca9-a98e-72704ba2e26e#resource

Only CoRide has access to information about https://cohouse.example/inventory/bicycles#stock

'@context': https://w3id.org/valueflows/v1
'@id': https://coride.example/inventory/bikes-at-station-12#stock
'@type':
  - vf:Resource
  - prodont:Bicycle
'skos:note': shed for shared bikes
'vf:currentLocation':  https://coride.example/station-12#location
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Each
  'qudt:numericValue': 1
'vf:contains':
  - https://coride.example/inventory/b93e2c05-bee4-4e45-a63c-aae043cb5938#resource

Also each bike has it's own "record", for example:

@context': https://w3id.org/valueflows/v1
'@id': https://coride.example/inventory/b93e2c05-bee4-4e45-a63c-aae043cb5938#resource
'@type':
  - vf:Resource
  - prodont:Bicycle
  - openbike:miniroller
'skos:note': one of the bikes - model: miniroller by openbike
'vf:currentLocation':  https://coride.example/station-12#location
'@reverse':
  'vf:contains': https://coride.example/inventory/bikes-at-station-12#stock

Processes

Check out

'@context': https://w3id.org/valueflows/v1
'@id': https://cohouse.example/2e09a9c8-801b-4d60-8583-686bc242a0e8#process
'@type': vf:Process
'skos:note': check out bikes for transportation
'vf:io':
- '@id': '#input-1'
    '@type': vf:InputOrOutput
    'vf:action': vf:outflow
    'vf:stock': https://cohouse.example/inventory/bicycles#stock
    'vf:resource': https://cohouse.example/inventory/0030b345-c9f9-4e3a-a5a6-b45a8137aa05#resource
  - '@id': '#input-2'
    '@type': vf:InputOrOutput
    'vf:action': vf:outflow
    'vf:stock': https://cohouse.example/inventory/bicycles#stock
    'vf:resource': https://coride.example/inventory/24129b9b-c684-4ca9-a98e-72704ba2e26e#resource
  - '@id': '#output-1'
    '@type': vf:InputOrOutput
    'vf:action': vf:inflow
    'vf:resource': https://cohouse.example/inventory/0030b345-c9f9-4e3a-a5a6-b45a8137aa05#resource
  - '@id': '#output-2'
    '@type': vf:InputOrOutput
    'vf:action': vf:inflow
    'vf:resource': https://coride.example/inventory/24129b9b-c684-4ca9-a98e-72704ba2e26e#resource

outputs here don't provide any useful information and I think we could simply omit them!

Transportation

'@context': https://w3id.org/valueflows/v1
'@id': https://wemove.example/818f30f4-c119-4024-b4c3-abd7bea4920b#process
'@type': vf:Transportation
'skos:note': moving bicycle between two sheds
'vf:io':
  - '@id': '#input-1'
    '@type': vf:InputOrOutput
    'vf:action': vf:load
    'vf:resource': https://cohouse.example/inventory/0030b345-c9f9-4e3a-a5a6-b45a8137aa05#resource
    'vf:location': https://cohouse.example/bikeshed#location
  - '@id': '#input-2'
    '@type': vf:InputOrOutput
    'vf:action': vf:load
    'vf:resource': https://coride.example/inventory/24129b9b-c684-4ca9-a98e-72704ba2e26e#resource
    'vf:location': https://cohouse.example/bikeshed#location
  - '@id': '#output-1'
    '@type': vf:InputOrOutput
    'vf:action': vf:unload
    'vf:resource': https://cohouse.example/inventory/0030b345-c9f9-4e3a-a5a6-b45a8137aa05#resource
    'vf:location': https://coride.example/station-12#location
  - '@id': '#output-2'
    '@type': vf:InputOrOutput
    'vf:action': vf:unload
    'vf:resource': https://coride.example/inventory/24129b9b-c684-4ca9-a98e-72704ba2e26e#resource
    'vf:location': https://coride.example/station-12#location
  - '@id': '#output-3'
    '@type': vf:InputOrOutput
    'vf:action': vf:create
    'vf:resource':
      '@id`: https://wemove.example/cee4518b-e5d8-4313-acb3-df0f9d3dc75d#service
      '@type`: vf:Service
      'skos:note': transportation service of 2 bicycles

Check In

'@context': https://w3id.org/valueflows/v1
'@id': https://coride.example/1c933999-2f37-49a5-afb6-7f82361c9506#process
'@type': vf:Process
'skos:note': check in bikes from transportation
'vf:io':
- '@id': '#input-1'
    '@type': vf:InputOrOutput
    'vf:action': vf:outflow
    'vf:resource': https://cohouse.example/inventory/0030b345-c9f9-4e3a-a5a6-b45a8137aa05#resource
  - '@id': '#input-2'
    '@type': vf:InputOrOutput
    'vf:action': vf:outflow
    'vf:resource': https://coride.example/inventory/24129b9b-c684-4ca9-a98e-72704ba2e26e#resource
  - '@id': '#output-1'
    '@type': vf:InputOrOutput
    'vf:action': vf:inflow
    'vf:stock':  https://coride.example/inventory/bikes-at-station-12#stock
    'vf:resource': https://cohouse.example/inventory/0030b345-c9f9-4e3a-a5a6-b45a8137aa05#resource
  - '@id': '#output-2'
    '@type': vf:InputOrOutput
    'vf:action': vf:inflow
    'vf:stock':  https://coride.example/inventory/bikes-at-station-12#stock
    'vf:resource': https://coride.example/inventory/24129b9b-c684-4ca9-a98e-72704ba2e26e#resource

inputs here don't provide any useful information and I think we could simply omit them!

After

'@context': https://w3id.org/valueflows/v1
'@id': https://cohouse.example/inventory/bicycles#stock
'@type':
  - vf:Resource
  - prodont:Bicycle
'skos:note': our shared pool of bicycles
'vf:currentLocation': https://cohouse.example/bikeshed#location
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Each
  'qudt:numericValue': 3
'vf:contains':
  - https://cohouse.example/inventory/49fc39ff-be2b-4653-87ff-b18e2f20063b#resource
  - https://cohouse.example/inventory/a64f0db3-4a62-404e-b46e-4753fb886ea3#resource
  - https://cohouse.example/inventory/40f5148b-710c-4215-ab4d-fee66d8d4f96#resource

'@context': https://w3id.org/valueflows/v1
'@id': https://coride.example/inventory/bikes-at-station-12#stock
'@type':
  - vf:Resource
  - prodont:Bicycle
'skos:note': shed for shared bikes
'vf:currentLocation':  https://coride.example/station-12#location
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Each
  'qudt:numericValue': 3
'vf:contains':
  - https://coride.example/inventory/b93e2c05-bee4-4e45-a63c-aae043cb5938#resource
  - https://coride.example/inventory/24129b9b-c684-4ca9-a98e-72704ba2e26e#resource
  - https://cohouse.example/inventory/0030b345-c9f9-4e3a-a5a6-b45a8137aa05#resource

'@context': https://w3id.org/valueflows/v1
'@id`: https://wemove.example/cee4518b-e5d8-4313-acb3-df0f9d3dc75d#service
'@type`: vf:Service
'skos:note': transportation service of 2 bicycles
'@reverse':
  'vf:resource': https://coride.example/1c933999-2f37-49a5-afb6-7f82361c9506#output-3

WeMove agent and transportation process don't even have knowledge about
https://cohouse.example/inventory/bicycles#stock and https://coride.example/inventory/station-12#stock. Only CoRide and CoHouse have knowledge about how they stock bicycles in their inventories! In simpler case it could work without check out and check in:

Transportation

'@context': https://w3id.org/valueflows/v1
'@id': https://wemove.example/818f30f4-c119-4024-b4c3-abd7bea4920b#process
'@type': vf:Transportation
'skos:note': moving bicycle between two sheds
'vf:io':
  - '@id': '#input-1'
    '@type': vf:InputOrOutput
    'vf:action': vf:load
    'vf:stock': https://cohouse.example/inventory/bicycles#stock
    'vf:resource': https://cohouse.example/inventory/0030b345-c9f9-4e3a-a5a6-b45a8137aa05#resource
    'vf:location': https://cohouse.example/bikeshed#location
  - '@id': '#input-2'
    '@type': vf:InputOrOutput
    'vf:action': vf:load
    'vf:stock': https://cohouse.example/inventory/bicycles#stock
    'vf:resource': https://coride.example/inventory/24129b9b-c684-4ca9-a98e-72704ba2e26e#resource
    'vf:location': https://cohouse.example/bikeshed#location
  - '@id': '#output-1'
    '@type': vf:InputOrOutput
    'vf:action': vf:unload
    'vf:stock':  https://coride.example/inventory/bikes-at-station-12#stock
    'vf:resource': https://cohouse.example/inventory/0030b345-c9f9-4e3a-a5a6-b45a8137aa05#resource
    'vf:location': https://coride.example/station-12#location
  - '@id': '#output-2'
    '@type': vf:InputOrOutput
    'vf:action': vf:unload
    'vf:stock':  https://coride.example/inventory/bikes-at-station-12#stock
    'vf:resource': https://coride.example/inventory/24129b9b-c684-4ca9-a98e-72704ba2e26e#resource
    'vf:location': https://coride.example/station-12#location
  - '@id': '#output-3'
    '@type': vf:InputOrOutput
    'vf:action': vf:create
    'vf:resource':
      '@id`: https://wemove.example/cee4518b-e5d8-4313-acb3-df0f9d3dc75d#service
      '@type`: vf:Service
      'skos:note': transportation service of 2 bicycles

[fosterlynn]

Use case 2, proposal 1: Input part of a stock type resource to a manufacturing process to be consumed. Resource is logically identified only by resource type and context agent. Input another resource to be used, a serialized one. Produce an item that is added to an existing stock resource, logically identified by context, resource type, and location. Also produce a new resource (perhaps a by-product), logically identified by context and resource type. All within one context.

Beginning resources:

'@context': https://w3id.org/valueflows/v1
'@id': https://fablab.example/f03962211#stock
'@type': vf:Resource
'vf:category':  prodont:3D-Filament-Red
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Grams
  'qudt:numericValue': 1000

'@context': https://w3id.org/valueflows/v1
'@id': https://fablab.example/d8f97d89#stock
'@type': vf:Resource
'vf:model': ord:ORD-FDM-3D-printer
'vf:serialNumber': d8f97d89
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Each
  'qudt:numericValue': 1

'@context': https://w3id.org/valueflows/v1
'@id': https://fablab.example/df89asf89asd#stock
'@type': vf:Resource
'vf:model': fablab:3D-Design-Cool-Item-44
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Each
  'qudt:numericValue': 1

'@context': https://w3id.org/valueflows/v1
'@id': https://fablab.example/d89adsf89ads#stock
'@type': vf:Resource
'vf:model': fablab:Cool-Item-44
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Each
  'qudt:numericValue': 15
'vf:currentLocation': https://fablab.example/fablab-side-room#location

Process:

'@context': https://w3id.org/valueflows/v1
'@id': https://fablab.example/818f30f4-c119#process
'@type': vf:Transformation
'skos:note': making a 3d printed part
'vf:contextAgent': https://fablab.example/OhioFabLab#agent
'vf:io':
  - '@id': '#input-1'
    '@type': vf:ResourceEvent
    'vf:action': vf:consume
    'vf:eventDate': 2016-08-10
    'vf:resource': https://fablab.example/f03962211#stock
    'vf:eventQuantity':
        '@type': qudt:QuantityValue
        'qudt:unit': unit:Grams
        'qudt:numericValue': 530
  - '@id': '#input-2'
    '@type': vf:ResourceEvent
    'vf:action': vf:use
    'vf:eventDate': 2016-08-10
    'vf:resource': https://fablab.example/d8f97d89#stock
    'vf:eventQuantity':
        '@type': qudt:QuantityValue
        'qudt:unit': unit:Hours
        'qudt:numericValue': 2.5
  - '@id': '#input-3'
    '@type': vf:ResourceEvent
    'vf:action': vf:cite
    'vf:eventDate': 2016-08-10
    'vf:resource': '@id': https://fablab.example/df89asf89asd#stock
    'vf:eventQuantity':
        '@type': qudt:QuantityValue
        'qudt:unit': unit:Percent
        'qudt:numericValue': 20
  - '@id': '#input-4'
    '@type': vf:ResourceEvent
    'vf:action': vf:work
    'vf:eventDate': 2016-08-10
    'vf:resource':  '@id': https://fablab.example/3d-printing#typeOfWork
    'vf:fromAgent': '@id': https://fablab.example/FredFlintstone#agent
    'vf:eventQuantity':
        '@type': qudt:QuantityValue
        'qudt:unit': unit:Hours
        'qudt:numericValue': 2.5
    'skos:note': This went smoothly except for one suggestion to make for the design....
  - '@id': '#output-1'
    '@type': vf:ResourceEvent
    'vf:action': vf:create
    'vf:eventDate': 2016-08-10
    'vf:resource': https://fablab.example/d89adsf89ads#stock
    'vf:quantity':
        '@type': qudt:QuantityValue
        'qudt:unit': unit:Each
        'qudt:numericValue': 5
  - '@id': '#output-2'
    '@type': vf:ResourceEvent
    'vf:action': vf:create
    'vf:date': 2016-08-10
    'vf:resource': https://fablab.example/ejreqw8j8#stock
    'vf:quantity':
        '@type': qudt:QuantityValue
        'qudt:unit': unit:Grams
        'qudt:numericValue': 78

Resources after process:

'@context': https://w3id.org/valueflows/v1
'@id': https://fablab.example/f03962211#stock
'@type': vf:Resource
'vf:category': prodont:3D-Filament-Red
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Grams
  'qudt:numericValue': 470

'@context': https://w3id.org/valueflows/v1
'@id': https://fablab.example/d8f97d89#stock
'@type': vf:Resource
'vf:model': ord:ORD-FDM-3D-printer
'vf:serialNumber': d8f97d89
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Each
  'qudt:numericValue': 1

'@context': https://w3id.org/valueflows/v1
'@id': https://fablab.example/df89asf89asd#stock
'@type': vf:Resource
'vf:model': fablab:3D-Design-Cool-Item-44
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Each
  'qudt:numericValue': 1

'@context': https://w3id.org/valueflows/v1
'@id': https://fablab.example/d89adsf89ads#stock
'@type': vf:Resource
'vf:model': fablab:Cool-Item-44
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Each
  'qudt:numericValue': 20
'vf:currentLocation': https://fablab.example/fablab-side-room#location

'@context': https://w3id.org/valueflows/v1
'@id': https://fablab.example/ejreqw8j8#stock
'@type': vf:Resource
'vf:category': prodont:3D-Filament
'vf:quantity':
  '@type': qudt:QuantityValue
  'qudt:unit': unit:Grams
  'qudt:numericValue': 78
'vf:currentLocation': https://fablab.example/fablab-back-room#location
'skos:note': Scrap filament of different colors for use in training.

[elf-pavlik]

As we discussed in chatroom, in:

  - '@id': '#input-3'
    '@type': vf:InputOrOutput
    'vf:action': vf:cite
    'vf:date': 2016-08-10
    'vf:stock': '@id': https://fablab.example/df89asf89asd#stock
    'vf:quantity':
        '@type': qudt:QuantityValue
        'qudt:unit': unit:Percent
        'qudt:numericValue': 20

IMO 'vf:quantity' gets heavily overloaded and used for attributing / creating shares of rights to the outcome 👎 from me to such use of that property

[elf-pavlik]

3. Return all the events (of different types) for a resource and put in a uniform table report format showing all info. Events which increment or decrement should show the quantities.

4. Return a list of all inventory that needs to be managed by an inventory manager for a context.

5. Visualize how resources flow between stocks through processes

I think about using something like http://the-grid.github.io/the-graph/the-graph-editor/index.html

Instances of vf:Stock and vf:Process (recipes) would get represented by nodes in the graph. The resources would flow through edges based on timestamps in events. And process recipe node would represent multiple execution of processes based on that recipe.

[fosterlynn]

5. Visualize how resources flow between stocks through processes

Great addition 👍

[fosterlynn]

I added it to the first outline at the top of this issue.

[fosterlynn]

I updated my yaml above https://github.com/valueflows/process/issues/21#issuecomment-238099929 for discussion since. Nothing revolutionary since no transfers. :)