Answer
How a brief a brand sends to our team is received, tracked and delivered, and who on our side moves it on.
Today
Sending
- A jam ends with Share the brief. To the brand's own team the brief is copied with a link to the full read only brief, and nothing is sent. To our team it is sent by email and tracked. brew/jam-brief.js:361-363; brew/SCOPE.md:20
- The team brief's Send to sheet lists who it is for: your team, your agency, a designer, a media buyer, a creator, a video editor, or our team. brew/team-brief.js:20; brew/public/app.js:4585-4590
- Picking our team shows one line and one button, Send to our team: our team gets the brief and the files by email, makes it and runs it, and the brand sees where it stands in the top bar. brew/public/app.js:4590
- Anything still missing from the brief, and anything the checks still flag, is asked once before it goes. It never blocks. brew/jam-brief.js:370-373
- Each sent brief gets a ticket, BR followed by a number from 1042 up. brew/feed-service.js:376-384
- The same brief sent twice within ten minutes is not emailed twice. brew/jam-brief.js:379-381
- The demo site never emails a brief. If the email fails, the brief is not marked sent and stays ready to paste. brew/jam-brief.js:392-394; brew/feed-service.js:356-359
What we receive
- One email per send to the inbox in
SHOPOS_EMAIL, hello@joinsquareup.com by default. brew/jam-mail.js:113-118 - It carries who sent it, where it runs, the deliverables, the brief itself, the assets with images inline, how a reference is made, the rules and when it is done, plus buttons to open the jam and read the brief. brew/jam-mail.js:120-133
- Staff sign in with their own staff Google account to open the jam. brew/jam-mail.js:102
Tracking
| Status | Label the brand sees | Can go to | Source |
|---|---|---|---|
| sent | Sent | received, in progress, needs info, delivered | brew/brief-status.js:8-12 |
| received | Received | in progress, needs info, delivered | brew/brief-status.js:11 |
| in_progress | In progress | needs info, delivered | brew/brief-status.js:11 |
| needs_info | Needs info from you | in progress, delivered | brew/brief-status.js:11 |
| delivered | Delivered | in progress, to reopen | brew/brief-status.js:11 |
Only staff move a brief on, through
POST /api/work/:wid/brief/status. Anyone else gets a 403 that says "Only our team moves a brief on." brew/jam-brief.js:406-408; brew/docs/handover/engineering/12-ui2-service-api.md:18, 30Needs info must say what we need. A status with a note folds into the brief; a bare status does not change it. brew/brief-status.js:26; brew/jam-brief.js:411-412
Each status change writes a line in the jam and emails the sender. Delivered and Needs info also email everyone in the jam, within their mail settings. brew/jam-mail.js:135-149
The top bar shows a pill with how many briefs are with our team, and flags any that need info. brew/public/app.js:1448, 2892-2894; brew/brief-status.js:32-37
Staff now have status controls in the jam, in the studio's ship bar and the jam room's ship row. They show the ticket and where the brief is, one main button for the usual next step and the other allowed steps in a small menu. brew/public/brief-staff.js:1-31; brew/public/app.js:4150-4151; brew/public/jam-room.js:164
Status now Main button In the menu Source Sent Mark received Start work, Ask for info, Mark delivered brew/public/brief-staff.js:7-11 Received Start work Ask for info, Mark delivered brew/public/brief-staff.js:7-11 In progress Mark delivered Ask for info brew/public/brief-staff.js:7-11 Needs info Back to work Mark delivered brew/public/brief-staff.js:7-11 Delivered none; a quiet Reopen it button brew/public/brief-staff.js:8-9, 31 Ask for info opens a box first, "What do you need from them?", and Send the question sends it as the note. brew/public/brief-staff.js:25-27, 37
After a change the work is refreshed, so the brand's top bar pill follows, and a toast says the brand sees it now. brew/public/brief-staff.js:39-43
Only our own people see the controls (
LIVE.full). Brand members, guests and the demo site never do, and a brief copied for the brand's own team has none. The route checks staff again. brew/public/brief-staff.js:2, 13-16; brew/test/brief-staff.test.js:60Tests keep the client's steps the same as the server's, and refuse a brand member every status. brew/test/brief-staff.test.js:31, 40, 52
The controls are on brew origin/main and going to staging now. Production has not been promoted with them yet. brew commits 2eed121, d6154b3; deploy state 26 Oct
Tomorrow
| Version | Tag | Item |
|---|---|---|
| v1 | Stays | Status buttons for staff in the jam, built on origin/main: Mark received, Start work, Ask for info with a question, Mark delivered, Reopen it. Reach production with the next promote. |
| v1 | New | A named owner on our side for every brief, set when it is received. |
| v1 | New | Response times for briefs: received within one working day, a first version or a question within three. Proposed. |
| v1 | Stays | The brief emails and refusals say our team, never ShopOS. Done on origin/main. |
| v1 | Stays | Sent to our team is tracked; copied to the brand's own team is not. |
| v1 | Changes | Briefs to our team are paid per brief and never in a plan, once pricing is unparked. Pricing is parked today. |
How we do it
Every morning, open hello@joinsquareup.com and find new emails titled
New brief from <brand>, with their BR ticket.Open the jam from the email with a staff Google account.
Move it to Received the same working day with Mark received in the jam's ship bar. On a site not yet promoted with the buttons, an engineer calls the route:
POST /api/work/<wid>/brief/status { "status": "received" }The call needs a staff session and the brand workspace in the
x-tenantheader.If anything is missing, press Ask for info and type one plain question. The brand answers in the jam.
Press Start work when work starts, and Mark delivered when the files are in the jam.
If the brand asks for a change after delivery, press Reopen it.
Numbers
| Metric | Definition | Where measured | State |
|---|---|---|---|
| Briefs received | Briefs sent to our team per week, by brand | jamBrief.history sent lines |
Proposed |
| Time to received | Hours from sent to received | jamBrief.history |
Proposed |
| Time to delivered | Working days from sent to delivered | jamBrief.history |
Proposed |
| Needs info rate | Share of briefs that went to needs info | jamBrief.history |
Proposed |
| Open with our team | Sent and not delivered right now | the top bar pill, withTeam |
Proposed |
Open
- Who on our team picks up briefs? Proposal: Param until the first ten, then a rota.
- What do we promise on time? Proposal: received within one working day, a first version or a question within three working days.
- Do briefs to our team cost money during the design partnership? Proposal: free until pricing is unparked, then paid per brief as the 26 Oct pricing note says.