Hand a live newsroom role to your own system

The live newsroom is the demo newsroom played by separate processes: each system, the newsroom system (NCS), the media store, graphics, the standards desk, playout, the web CMS, automation and the skill executor, is a live actor on its own connection to your house. An actor is a simulated system. It publishes and reacts through the bus as a vendor's system would, and everything it sends is synthetic and marked as demo traffic.

Each role in your house is played by its actor until you hand it to one of your own systems. Then that role's actor stays silent, and the other actors go on reacting to what your system sends. You can give the role back to the actor at any time.

What a system needs to take a role

A connection can take a role when:

• it is a producer connection of this house, yours or a vendor's that the house granted;
• it is active, not revoked or disconnected;
• it is granted every message type the role publishes.

Role	Publishes
Newsroom system	story.context
Media store	delivery.media_available, story.context
Skill executor	skill.warning.raised
Graphics	link.committed, link.withdrawn
Standards desk	link.gate_changed, system.audit
Playout	telling.started, telling.ended
Web CMS	link.committed, telling.started, telling.ended
Automation	system.audit

To react to the other systems as the actor did, your system also needs a consumer connection in the house that receives the message types the role reacts to.

Hand a role over, and back

On the Demo newsroom page in your house, the Live newsroom panel lists each role:

• Played by actor, with the actor's name, or
• Held by your connection's app.

Developers, admins and owners of the house can change it. Everyone else in the house sees who holds what.

1. Find the role, for example Newsroom system.
2. Choose one of your connections in Choose a connection…. The list offers only the connections that can take that role.
3. Press Hand over. The role shows Held by your app, and the change is recorded in the house's audit log.

To give it back, press Give back to the actor on that role.

If the connection holding a role is revoked or disconnected, or loses a grant the role needs, the role goes back to its actor by itself. The panel says which connection held it and why it no longer can.

What changes when your system holds a role

• The role's actor sends nothing more in that role.
• Your system publishes in its place, through the bus like any other connection.
• The other actors react to your system's messages as they did to the actor's. For example, with your newsroom system in the NCS role, the media store answers your first snapshot of a story with media, and graphics, playout and the web CMS follow your story as they followed the actor's.

Your system's messages are yours, not the demo's: they are not marked as demo traffic unless your system marks them.

For actors: who holds each role

An actor asks the bus before each beat and each reaction, with the bearer token of either of its own connections:

GET /v1/jwt/live/roles
Authorization: Bearer <access token>

The answer is for the house the token's connection belongs to, and never names another house:

{
  "house": "w…",
  "roles": {
    "ncs": { "held_by": "real", "connection_id": "c…" },
    "mam": { "held_by": "actor" },
    "skill": { "held_by": "actor" },
    "graphics": { "held_by": "actor" },
    "standards": { "held_by": "actor" },
    "playout": { "held_by": "actor" },
    "cms": { "held_by": "actor" },
    "automation": { "held_by": "actor" }
  }
}

An actor stays silent in a role whose held_by is real. A 401 means the token is not an active connection's. A 503 with live.roles_unavailable means the roles could not be read just now: keep to the roles you read last and retry after Retry-After.