Design functionality for listing offers

We need to decide what the offer broadcast form looks like and how the optional elements can open out as needed.

CommonsPub's looks like this:

create_offer

For the generic case, I think I want a little more.

Ability to define name & note for the Proposal grouping the requests, if the proposal is composed of more than 1 intent. Or should these options always be made available? Should the Proposal record always be created, or only in some cases?
Automatic generation of Proposal data if it's only an offer composed of a single Intent? Something else for the simple case?
Which actions are possible for the offer Intent? Should there be options, or should marketplaces always use transfer?
Should the provider of the offer Intent always be the current agent?
Should the receiver of the reciprocal Intent always be the current agent?
What does the UI for selecting increasing resource specificity look like? (resourceClassifiedAs -> resourceConformsTo -> resourceInventoriedAs)
- Display resource classifications in the UI based on the selected resource spec? Combine autocompletes to list specs & classifications?
- Display similarities between classifications / specifications / inventory items?
Under what conditions would effortQuantity be input? What about availableQuantity?
When might unitBased proposals be used? How would the user make that decision in their workflow?
Input styles for due dates, time ranges & specific times.
Map input for location search & input

I am also assuming that we'll want varying numbers of offers & requests per listing. So the form should start with fields for a single offer, with "add more" so that more Intents can be created to go into the Proposal. I think something like a checkbox that says "Ask for something in exchange" to start adding reciprocal Intents sounds sensible too.

I am also assuming that we'll want varying numbers of offers & requests per listing. So the form should start with fields for a single offer, with "add more" so that more Intents can be created to go into the Proposal. I think something like a checkbox that says "Ask for something in exchange" to start adding reciprocal Intents sounds sensible too.

I suspect that VF has more flexibility than most "marketplace" kinds of apps will need, which is by design so it can support other methods of coordinating matching "supply" and "demand". I would suggest we can assume that there is one primary intent, and most often one reciprocal intent. Second most often, no reciprocal intents, it is a gift. Occasionally more than one reciprocal intent, which is an "and". Like "I am offering a regular CSA veggie box, and in return I want $ plus some work hours" (2 reciprocal intents). Whether we want to put that last one in the UI is a question.

Ability to define name & note for the Proposal grouping the requests, if the proposal is composed of more than 1 intent. Or should these options always be made available? Should the Proposal record always be created, or only in some cases?

My suggestion is to always record the Proposal, even if only one Intent. Also to use the name and note in Proposal, and then maybe skip the names and notes in the Intents to keep it simpler (?).

Which actions are possible for the offer Intent? Should there be options, or should marketplaces always use transfer?

Tentatively suggest (pending discussion): use (or maybe always this is a transfer-custody?), work, deliver-service, transfer, transfer-custody (borrow or rent).

Should the provider of the offer Intent always be the current agent? Should the receiver of the reciprocal Intent always be the current agent?

No, I think we should support both offers and requests as primary intents. This goes beyond most traditional marketplaces that just support offers. I think I might give a dropdown up top and then fill in the provider and receiver data to match that? And think a bit more if there is anything that is not primarily one or the other.

(Posting and will continue in next comment.)

What does the UI for selecting increasing resource specificity look like? (resourceClassifiedAs -> resourceConformsTo -> resourceInventoriedAs)

Display resource classifications in the UI based on the selected resource spec? Combine autocompletes to list specs & classifications?

Display similarities between classifications / specifications / inventory items?

This is a hard one, will offer some random thoughts. For starters, I think that having an actual resourceInventoriedAs will be the exception unless it is a situation of a lot of re-use and used items being offered. Also I don't see really ever there being a request for a resourceInventoriedAs, if you want a specific Van Gogh painting or something, you probably won't be requesting in a marketplace. And used items could be described in detail in the note without actually referencing the economic resource, if we want to simplify and not offer that option at all, but I don't know, maybe it will be useful, say in different batches of bio-fertilizer with different inputs or something.

I think for requests people could choose either a resourceConformsTo (like the kind you would encounter in e-commerce of new items, like the ISBN of a book, or specific title and author), or a set of resourceClassifiedAs's, hopefully from a selected set from a taxonomy (like "novel", "young adult", "mystery"). I honestly don't know where the latter changes into just search with freeform tags or key words. For offers, it might make sense to include both a resourceConformsTo and some resourceClassifiedAs's (which possibly could be found on the ResourceSpecification record) so that requesters can get matches.

I don't have personal experience on this, the VF use case input came from others. One small observation from people trying to create interoperability between existing mutual credit / marketplace applications, was that they had different small sets of "categories" (== resourceClassifiedAs) in each system, which they had to try to sync up, and which were way too limited in the first place.

Under what conditions would effortQuantity be input? What about availableQuantity?

effortQuantity is for work and use; and would have to see if it would ever apply to deliver-service, although right now I don't think so. So it might be workable to just have one input field for effortQuantity and resourceQuantity, not sure. Using them together could show up in something like "I request to use 100 shovels for 8 hours", which might happen - and maybe also for transfer-custody? But there is a trade-off of simplicity for the majority of scenarios.

availableQuantity would be very optional, and only apply to offers, for cases where it might matter to someone responding to an offer, usually if the offerer can't get hold of more, or can't get hold of more soon. (Or Amazon uses it as a come-on.) Like you can order any number of these, up to x and then they're gone.

When might unitBased proposals be used? How would the user make that decision in their workflow?

unitBased is for people offering (or possibly requesting?) resources by the minimum unit sold. So most of e-commerce for things more-or-less mass produced to the same specification is this. Like I get price lists from local farmers selling wholesale to a buying club I belong to. These are like "25 lb carrots" (one case), reciprocal intent is "$30". You can order however many cases you might realistically want (usually, otherwise they might also post an availableQuantity), but the offer is per case.

Map input for location search & input

Yeah, let's get some input from users on this. Some apps have done this as a "look within 50 miles of my location" kind of thing. But I also think a lot of marketplace "instances" might be location-specific, like a city. There might be a lot of different scenarios depending on the type of resource (even seeds vs bio-fertilizer, not to mention electronic resources), and type of marketplace.

[edit] Just to note, that CommonsPub mockup was very preliminary, just a sketch prior to discussion.

These are great, thanks! I think I can get most of the way there now. Some minor responses:

agree in not using "use", I think if you're putting things through a marketplace then you're doing "transfer-custody".

I might give a dropdown up top and then fill in the provider and receiver data to match that

Sounds good. So "make an offer" = provider is me, receiver unknown; "request something" = receiver is me, provider unknown?

I'll put together an offer form for a gift, offer for a trade & request for a trade as 3 different flavours of the same form.

RE effortQuantity I forsee UI elements that open out, "☐ Only for a while..." and then you fill out the number of hours / minutes / seconds.

RE availableQuantity & unitBased, these feel linked. Maybe the option is like "☐ I'm offering many of these" (enables unitBased); then a limit quantity can be entered to assign availableQuantity? Are there any interplays between availableQuantity and EconomicResource.accountingQuantity that need to be implemented?

Interested to hear your thoughts, will ping some designers too...

Sounds good. So "make an offer" = provider is me, receiver unknown; "request something" = receiver is me, provider unknown?

Yup!

RE availableQuantity & unitBased, these feel linked.

Probably so, but I don't feel like we know enough yet. I would also guess though that most people who do unit based offers don't need available quantity. They will just make more or get more of what they generally offer as part of their business or organization, and they are fine with people ordering more than they have at the moment.

Are there any interplays between availableQuantity and EconomicResource.accountingQuantity that need to be implemented?

I don't think I would do so unless we run into it from a user. Not even sure we want to implement availableQuantity until we know someone wants it? It would be interesting to talk to SeedShare, it might be useful there. Maybe we need more of a process around talking to anyone who might use the marketplace about their requirements, or how they imagine their requirements right now?

@pospi I wrote some test queries with some specs for the Reflow project, thought they might be useful here. I'm copying the relevant ones here. Feedback welcome of course!

Note there are some new query methods and filter parameters I discovered, will do a PR in the vf-graphql repo for those soon.
Note they are not really doing a full marketplace, so this probably doesn't include everything we need for complete VF coverage.
Note I haven't tested any of the graphql queries or mutations!!! Happy to test them on holo-rea if we can set that up.

Publish offers & needs

Proposal

A Proposal is the publication of an offer or need, along with any reciprocal needs and offers. Proposal, Intent, and ProposedIntent form a unit of work that will be published together for this use case. (Intent can live on its own too, as part of other use cases that won't be included here.)

A possible UI might display the Proposal plus main intent fields; then ask if they want something in return, and if so, then display fields for a reciprocal intent. To keep it simple, we could only support one reciprocal intent per proposal, although more are allowed, with an implied "and". Some discussion here: https://github.com/holo-rea/app-offers-needs-marketplace/issues/1.

Create a new proposal

[ ] create proposal

mutation { 
createProposal (
proposal:{
name: "title",
note:"general_description", 
hasEnd: "datetime",
eligibleLocation: "a_spatial_thing",
inScopeOf: "an_agent_or_group",
unitBased: "true_or_false"
})
{
proposal {
id
name
note
hasEnd
eligibleLocation {
   name
}
inScopeOf {
   name
}
unitBased
}
}}

Edit a proposal

[ ] update proposal

mutation { 
updateProposal (
proposal:{
name: "title",
note:"general_description", 
hasEnd: "datetime",
eligibleLocation: "a_spatial_thing",
inScopeOf: "an_agent_or_group",
unitBased: "true_or_false"
})
{
proposal {
id
name
note
hasEnd
eligibleLocation {
   name
}
inScopeOf {
   name
}
unitBased
}
}}

Delete a proposal

[ ] Delete the proposal Backend spec: Delete the proposal and any proposed intents related to it.
```
deleteProposal(id: "proposal_id") -> true
```
Intent and ProposedIntent

Create a new intent for a proposal

Actions that could be used: transfer, deliver-service, transfer-custody (for lending or renting). Provider is populated if the proposal is basically an offer; receiver is populated if basically a request/need; and the opposite if this is the reciprocal intent.

[ ] create the intent

mutation { 
createIntent (
intent:{
action: "an_action"
resourceQuantity: {
hasNumericValue: number,
hasUnit: "unit_id"
},
image: "http://example.images.com/my-image.png",
provider: "provider_id",
receiver: "receiver_id",
resourceClassifiedAs: "list_of_taxonomy_hashtags",
})
{
intent {
id
action
resourceQuantity {
  hasUnit {
    label
  }
  hasNumericValue
}
image
provider {
  name
}
receiver {
  name
}
resourceClassifiedAs
}
}}

[ ] create a proposed intent

mutation { 
createProposedIntent (
proposedIntent:{
publishedIn: "proprosal_id",
publishes: "intent_id",
reciprocal: true_or_false
})
{
proposedIntent {
id
publishedIn {
   name
}
publishes {
   action
   resourceClassifiedAs
}
reciprocal
}
}}

Edit the Intent

[ ] update the intent

mutation { 
updateIntent (
intent:{
action: "an_action"
resourceQuantity: {
hasNumericValue: number,
hasUnit: "unit_id"
},
image: "http://example.images.com/my-image.png",
provider: "provider_id",
receiver: "receiver_id",
resourceClassifiedAs: "list_of_taxonomy_hashtags",
})
{
intent {
id
action
resourceQuantity {
  hasUnit {
    label
  }
  hasNumericValue
}
image
provider {
  name
}
receiver {
  name
}
resourceClassifiedAs
}
}}

[ ] update the proposed intent

mutation { 
updateProposedIntent (
proposedIntent:{
reciprocal: true_or_false
})
{
proposedIntent {
id
reciprocal
}
}}

Delete the Intent

[x] Delete the intent by its id
```
deleteIntent(id: "intent_id") -> true
```

[ ] Delete the proposed intent by its id

deleteProposedIntent(id: "proposed_intent_id") -> true

Start and reply on a thread on a Proposal

[ ] Create a new discussion thread on a proposal, add comment to an existing discussion (should be working)

Proposal Queries

[ ] Query one proposal with its intents

[ ] Backend spec: Note primaryIntents and reciprocalIntents use the reciprocal flag on the ProposedIntent.

query {
proposal (id: "proposal_id") {
id
name
note
hasEnd
eligibleLocation {
   name
}
inScopeOf {
   name
}
unitBased
primaryIntents {
  id
  action
  resourceQuantity {
    hasUnit {
      label
    }
    hasNumericValue
  }
  image
  provider {
    name
  }
  receiver {
    name
  }
  resourceClassifiedAs    
}
reciprocalIntents {
  id
  action
  resourceQuantity {
    hasUnit {
      label
    }
    hasNumericValue
  }
  image
  provider {
    name
  }
  receiver {
    name
  }
  resourceClassifiedAs        
}
}
}

[ ] category Backend spec: Return "offer" if the non-reciprocal intent has a provider. Return "request" if the non-reciprocal intent has a receiver. (Note there will be other possibilities for more complex use cases later, like barter with no reciprocal intent, but there doesn't seem like a need for now.)
```
query {
proposal (id: "proposal_id") {
id
category
}
}
```
[ ] deletable Backend spec: Proposal is deletable if there are no discussion threads attached to it. (There will be more rules when planning is implemented.)
```
query {
proposal (id: "proposal_id") {
id
deletable
}
}
```

[ ] Query proposals with their intents, with optional filters Backend spec: I don't know if all of those parameters are required for now? Unless includeExpired is there and true, then return only proposals still active, check hasEnd. Location could be complex, not sure what is required for this project, in terms of locations within locations, etc. Scope is meant for proposals just for an organization or group. Using scope may mean we don't need location? Note primaryIntents and reciprocalIntents use the reciprocal flag on the ProposedIntent.

query {
proposal (offersOnly: true,
requestsOnly: true,
includeExpired: true,
inScopeOf: "agent_or_group_id",
location: "geolocation"
) {
id
name
note
hasEnd
eligibleLocation {
   name
}
inScopeOf {
   name
}
unitBased
primaryIntents {
  id
  action
  resourceQuantity {
    hasUnit {
      label
    }
    hasNumericValue
  }
  image
  provider {
    name
  }
  receiver {
    name
  }
  resourceClassifiedAs    
}
reciprocalIntents {
  id
  action
  resourceQuantity {
    hasUnit {
      label
    }
    hasNumericValue
  }
  image
  provider {
    name
  }
  receiver {
    name
  }
  resourceClassifiedAs        
}
}
}

Some other thoughts, from the initial work done. :heart:

Due: From other discussion, recording here for the record.

I think we could skip Due for this. I think it would come into play more when operational planning is being done and is feeding the requests.

So do you think it's a case of ignoring due in the marketplace's own controls & inputs, but still facilitating some display if there happens to be a due set on an intent so that intents created from operational planning contexts are presented with all expected metadata?

That sounds good, pending getting actual experience with it. Could also be left off for now and added later when we have that use case, your choice.

'Lend a resource' should perhaps be 'Lend or rent a resource'? Although I see the following. Would be interested in examples. Also seems perhaps that that level of configuration might seem like a lot for a marketplace? (Although I don't know, maybe need input from potential users.)

// action labels are configurable since they depend on the context agent type...

Dates: Note VF doesn't have before and after any more, discussion here https://github.com/valueflows/valueflows/pull/590 (due replaced before). Maybe just have 'Any time', 'At precisely', 'Between'? Maybe leave it a bit looser than 'At precisely', sounds a bit exact? Just 'At'? Also, is a time required? I don't think it needs to be.

TODO: should "deliver-service" give the option for time-based & unitless measures? What about other unit types?

I don't know, maybe we should not be so helpful at first?

For how long?

I see where you are going with this; but effortQuantity was more for use and work, where this implies how long will you have it, like a library book for 3 weeks. So use is one event.; transfer-custody will involve 2 events, one to transfer it, one to transfer it back. I can see this is confusing; and maybe the vocabulary has some deficiency there, don't know....

TODO: agreement

I don't think we need this.

TODO: attachments

Curious what this one is for?

Hey! Sorry for the delay on these, I just found them accidentally filtered into the wrong email folder ><

There's some good fodder for considering vf-graphql changes, I've taken that discussion to https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/85

The other questions here are specific to this particular UI. Some replies:

Also seems perhaps that that level of configuration might seem like a lot for a marketplace?

Agree with that. Breaking options down more may alleviate this- for example, we could have "lend a resource" and "rent a resource" as two different options, the latter providing inputs for effortQuantity and the reciprocal "payment" intent.

Note VF doesn't have before and after any more

I understand that, but Intents do have hasBeginning and hasEnd. So what are the friendly names for intents which only fill one of those properties? I have been presuming an intent with only hasEnd means "an intent that something happens before this time", for example. But maybe I have misinterpreted.

is a time required?

No, it's not. Many of the fields in the form are optional, but need to be better indicated as such.

use is one event.; transfer-custody will involve 2 events, one to transfer it, one to transfer it back. I can see this is confusing; and maybe the vocabulary has some deficiency there, don't know....

If it does for you, it still makes semantic sense for me to use a single intent with a range as the initiating one. Multiple transfer events with specific hasPointInTime could be logged to satisfy a single intent which has both a hasBeginning and a hasEnd. To me that reads, "I would like to offer something between these times"; "I lent it on date X"; "it was returned on date Y". Thoughts?

Attachments

These will be from an auxilliary DNA which manages file uploads that can be associated with any other record type. Allows folks to provide supporting documentation etc that underpins a proposal.

I understand that, but Intents do have hasBeginning and hasEnd. So what are the friendly names for intents which only fill one of those properties? I have been presuming an intent with only hasEnd means "an intent that something happens before this time", for example. But maybe I have misinterpreted.

Hmmmm. OK, let's try it. I feel like I'm not in touch enough with actual use cases, haven't worked on a marketplace. I suppose most don't have any dates really?

If it does for you, it still makes semantic sense for me to use a single intent with a range as the initiating one. Multiple transfer events with specific hasPointInTime could be logged to satisfy a single intent which has both a hasBeginning and a hasEnd.

I hesitate to make things work differently for intents and commitments/events in terms of dates and actions. Maybe due should come back? Definitely I agree we don't want 2 transfer intents. But again, I think a bunch of real scenarios would help, and I'm not sure much really happens with dates. Let's talk to everyone we are working with who might use a marketplace?

Note there are some new query methods and filter parameters I discovered, will do a PR in the vf-graphql repo for those soon.

Still need to do this, sorry!

I hesitate to make things work differently for intents and commitments/events in terms of dates and actions

How do the hasBeginning and hasEnd fields work for commitments and events? It'd be good to have a list of the specific meanings of these fields in different record types.

For ease of access, here are the spec definitions.

"The planned or actual beginning of a flow or process." "The planned or actual end of a flow or process."

Not sure what would be the implications of different record types, do you have examples or specific questions?

Could say one thing, these are about scheduling and coordination, not accounting, in terms of quantities. So for example an event or commitment could say that someone planned or worked for effortQuantity of 6 hours, but the times are 8am to 5pm on a specific day. Dates do affect accounting, in terms of accounting period though. Suggest using end time if point in time is not used.

Yeah, that makes sense. So for the UI, you don't want these fields to be shown as a range indicative of "when the thing must occur", more like "where the thing may occur".

I think as an additional sane default and time-saver, we could probably first ask for input in hasBeginning and hasEnd, then prefill the duration for effortQuantity next to it in whatever period fits based on those fields (but still allow editing after the fact). Good idea?

I think as an additional sane default and time-saver, we could probably first ask for input in hasBeginning and hasEnd, then prefill the duration for effortQuantity next to it in whatever period fits based on those fields (but still allow editing after the fact). Good idea?

Doesn't seem good to me, because it might add to confusion about scheduling vs quantities. And how do you know there will be an effortQuantity? But also, I don't feel like I know. We need users! :)

h-REA / app-offers-needs-marketplace