Osysharp.HumanRequests — something put to a person, and their answer coming back

`Osysharp.HumanRequests` puts a question, an approval of one exact thing, or a form to a person, and brings the answer back typed to whatever waits for it — a person, a process or an agent — however long it takes.

You are here: Building with agents › The kits › HumanRequests

Summary#

Osysharp.HumanRequests puts a question, an approval of one exact thing, or a form to a person, and brings the answer back typed to whatever waits for it — a person, a process or an agent — however long it takes.

A request is an item of the inbox. It has a deadline, reminders and somebody it goes to next. Somebody with no account can answer through a link that opens that one request and nothing else.


Package	`Osysharp.HumanRequests`, version 1.4.0
You add it with	`use Osysharp.HumanRequests;` in the app's manifest.
It sits on	[[agent-kit-work-queues\|WorkQueues]]
It also uses	`Identity`, `Ui`, `Workflow` — parts of the platform's own library
Bridges that arrive when it meets another kit	[[agent-kit-agents-human-requests\|Agents.HumanRequests]], [[agent-kit-assignments-work-queues\|Assignments.WorkQueues]], [[agent-kit-human-requests-processes\|HumanRequests.Processes]], [[agent-kit-privacy-human-requests\|Privacy.HumanRequests]]
Its own test app	A boatyard — `kits/human-requests/tests`

Description#

What do you get without writing anything?#

The request's sheet in the inbox: what is asked, about what, the buttons to answer.
A form generated from a class you declare.
Reminders, a deadline, and what happens when nobody answers.
An approval that covers one exact version: if the thing changed, it is asked again.
"Waiting on people" for a record: who a process or an agent is waiting for.

When do you need it?#

From shape 2 on. Also by itself, with no agent anywhere: a process that needs a person's approval.

What does it expose?#

The tables below are generated from the kit itself, not written by hand: osy kits Osysharp.HumanRequests --surface lists each of them with the code of the kit's own test app that uses it, and the tests that show it working.

Settings — one line in the app, each field with a default.

You write	It says
`app.Requests = new RequestsSetup { Queue, Within, RemindAfter, RemindEvery, MaxReminders, LinkGoodFor, Words }`	How this app asks people.

Policies you answer — each is a question the kit asks your app: policy Name => …;

Policy	The question	Until the app says otherwise
`AsksPeople`	Who may put a request to a person.	nobody
`OverseesRequests`	Who reads every request, calls one off and gives it more time.	nobody
`ErasesRequestRecords`	Who may erase who a request was put to and what they answered — nobody, until the app says.	the kit's own default

Functions you call, those its own tests show most first.

Function	What it does	Tests that show it
`AnswerRequest(HumanRequest request, RequestAnswer answer)`	Answer a request, as whoever is signed in — the person it was put to, the person it went on to, whoever holds it, or anybody who works its queue when it names nobody.	39
`UseApproval(HumanRequest request, string versionNow)`	Use an approval — once, for the version that was approved.	38
`PutRequest(NewRequest ask)`	Put a request to somebody.	38
`CancelRequest(HumanRequest request, string why)`	Call a request off.	38
`ExtendRequest(HumanRequest request, TimeSpan within, string why, TimeSpan? expireAfter = …)`	Give a request more time (or less): how long it may now wait from when it was put before it is late, and — when given — how long it may wait at all.	38
`Closed(HumanRequest request, string? cancelledWhy)`	The request has closed: the inbox's item is done (or cancelled), and whatever waited for the answer goes on.	38
`OutcomeOf(HumanRequest request)`	What a request has come to, read now.	15
`AnswerLinkFor(HumanRequest request)`	The text of the link for a request sent to somebody outside — what the app puts in the mail it sends them: `$"{App.BaseUrl}/answer/{AnswerLinkFor(request)}"`.	5
`ApprovalCovers(HumanRequest request, string versionNow)`	Whether `request` is an approval that covers acting on `versionNow`: it was given, it has not been used, and what it approved is the version in hand.	4
`ViewByLink(AnswerLink link)`	The request a link opens, as its holder reads it.	4
`ViewRequest(Guid id)`	A request as whoever is signed in reads it.	3
`AnswerByLink(AnswerLink link, RequestAnswer answer, string name = …)`	Answer through the link that was sent to somebody with no account.	2
`RevokeAnswerLink(HumanRequest request)`	Take back every link ever made for a request: none of them opens it any more.	1
`ReplaceRequest(HumanRequest old, NewRequest ask, string why)`	Ask again, about the thing as it is now.	1

Screens and components you mount — each is one line in a page of yours.

Component	What it draws
`RequestSheet(request, onAnswered, titled)`	A request's sheet.
`RequestItemDetail(item)`	A request in the inbox: the sheet, under the item's own head.
`RequestSkeleton()`	The shape of a sheet while it loads: a line of who asks, the question, two facts, the buttons.
`RequestHead(view, titled)`	Who asks, what is waiting on the answer — and the question, the biggest thing on the sheet.
`RequestBody(view, withSubject, changed)`	What is known: the context in a reading width, the facts as a short table, and what it is about as its owner draws it.
`RequestTime(view)`	How its time stands, in a line: when it is wanted by, and that late is not closed.
`RequestCovers(view)`	What a yes to an approval covers: this, exactly as shown — and nothing it turns into afterwards.
`RequestWaitsFor(view)`	For somebody who reads the request and is not the one asked: who it waits for, and why they cannot answer.
`RequestOutcomeBlock(view, said)`	What came back: the answer with who gave it and when — or why there is none.
`RequestLateAnswers(view)`	Answers that came after the request was closed: kept, shown, applied to nothing.
`AnswerControls(view, send, problem)`	The answer, as the request asks for it — drawn from what the request offers: a button per option (the one that says no stands apart, and opens a place to say why), a field per member of the class asked for, or a box to write in when it offers nothing.
`AnswerField(field, typed)`	One field of the form, as its kind asks: a line, a paragraph, a number, a yes or no, a choice, a date.
`ExternalAnswer(link)`	The page somebody with no account answers on.
`WaitingOnPeople(askedByName, waitingType, waitingId, open, requests)`	Who is being waited on — every open request behind one piece of work, or put by one process or agent: what is asked, of whom, since when, and whether it is late.
`WaitRow(line, open)`	One line of it: a lamp that is steady while the request is in time and turns when it is late, what is asked, of whom, and how long it has waited.
`ApproveManyRequests(kind, ids, done)`	"Approve all" on the inbox's bulk bar — only while every picked item is an approval.

Slots you can fill — a place on the kit's screens where your app, or another kit, adds a section.

Slot	What goes there
`RequestSubject(string subjectType, Guid subjectId, Guid request, Action changed)`	What a request is about, drawn by whoever owns that kind of thing — the place on a request's sheet, between the question and the answer, where a kit (or the app) shows the record the request is abo…

Events your app can hear — [On] void Heard(EventName e) { … }

Event	When
`HumanRequestPut`	A request was put to somebody.
`HumanRequestAnswered`	A request has its answer.
`HumanRequestReminded`	The person asked was reminded: `Number` is which reminder it was, `Words` what to tell them.
`HumanRequestOverdue`	A request is late: its date passed and nobody had answered.
`HumanRequestExpired`	A request ran out of the time it could wait at all, unanswered.
`HumanRequestCancelled`	A request was called off.
`HumanRequestRetimed`	A request was given more time, or less: its dates as they are now, and why.
`HumanRequestAnsweredLate`	An answer came after the request was closed.
`HumanRequestErased`	Who a request was put to and what they answered were erased, at their request.

Go deeper#

Requests to people — a question, an approval, a form, and the answer coming back (HumanRequests kit) — questions, approvals, forms; who is asked; time; late answers
The WorkQueues kit — queues, who holds what, and the service levels promised on any item — the inbox it lands in