Hooks and events
React to changes in Solo. A hook runs before a core write and can refuse it. An event handler runs after a change. Live updates and background work let your extension act on its own.
Which one to use
| You want to | Use |
|---|---|
| Refuse or change a core write | A hook |
| Do work after a core change | An event handler |
| Tell open pages that your data changed | Live updates |
| Do work on a schedule, as a user | Background work |
| Add a line to audit entries | An audit contributor |
| Revoke your tokens when an admin signs a user out | A credential issuer |
Hooks
A hook runs around a core write operation, such as a status change of a task. Each operation has a fixed name. Reference lists the names.
public sealed class MilestoneFreezeHook(RoadmapDbContext db) : ISoloOperationHook
{
public IReadOnlySet<string> Operations { get; } =
new HashSet<string> { Solo.Extensibility.Operations.TaskSetStatus };
public int Order => 10;
public async ValueTask<HookOutcome> OnBeforeAsync(OperationContext context, CancellationToken ct)
{
if (context.Target.TaskId is not { } taskId)
{
return HookOutcome.Proceed;
}
return await db.Milestones.AnyAsync(m => m.TaskId == taskId && m.IsFrozen, ct)
? HookOutcome.Reject(409, "Milestone frozen", "This task's milestone is frozen.")
: HookOutcome.Proceed;
}
}
To use a hook, do these two steps:
-
Register it in
ConfigureServices:services.AddOperationHook<MilestoneFreezeHook>(); -
List its operations in the manifest:
"hooks": ["task.setStatus"]
Solo ignores a hook for an operation that the manifest does not list.
Before the write
OnBeforeAsync runs after authorization and before the core action. It returns one of two results:
HookOutcome.Proceedlets the operation continue.HookOutcome.Reject(status, title, detail)stops it. The caller gets that status and text. Use a4xxstatus.
OperationContext gives you:
| Member | Content |
|---|---|
Operation |
The name of the operation. |
Caller |
The signed-in caller. |
Target |
The IDs from the route: ProjectId, BoardId, EpicId, TaskId, SubTaskId. Each can be null. |
Arguments |
The arguments of the action, by parameter name. |
Request<T>() |
The request body, when the action has one. |
A hook can change a value in Arguments. Later hooks and the action then get the changed value.
After the write
OnAfterAsync is optional. It runs after the action, with the status code and the response body.
Before this method runs, Solo saves the change and sends it to the open boards. An exception in OnAfterAsync cannot undo the change.
Rules for hooks
- The record can be absent. Solo looks for the task or epic in the action, after your hook. Do not assume that the ID in
Targetexists. - A hook can only restrict. Hooks run after authorization. A hook cannot give access that the caller does not have.
- A slow or failed hook stops the request. If
OnBeforeAsyncthrows an exception or takes longer than 2 seconds, the request fails. The error names your extension. To change this, see failOpen. - Order. Hooks run in ascending
Order. Hooks with the sameOrderrun by extension ID. - Two operations can do one job. A limit on work in progress for each person needs
task.setStatusandtask.setAssignees. With only the first, a person can get an assignment to a task that is already in progress.
Events
An event handler runs after Solo saved a change. It cannot refuse the change.
public sealed class TaskRollupHandler(RoadmapDbContext db, ISoloQuery query) : ISoloEventHandler
{
public IReadOnlySet<string> EntityTypes { get; } = new HashSet<string> { "task" };
public async ValueTask HandleAsync(SoloDomainEvent domainEvent, CancellationToken ct)
{
if (domainEvent.Kind != ChangeKind.Deleted)
{
return;
}
// A move to a different board also sends Deleted for the old board.
if (await query.TaskAsync(domainEvent.EntityId, ct) is null)
{
await db.Milestones
.Where(m => m.TaskId == domainEvent.EntityId)
.ExecuteDeleteAsync(ct);
}
}
}
Register it in ConfigureServices:
services.AddEventHandler<TaskRollupHandler>();
EntityTypes selects the types that the handler gets. An empty set selects all types. The types are:
project, board, epicGroup, epic, task, subtask, label, comment
SoloDomainEvent gives you:
| Member | Content |
|---|---|
EntityType, EntityId |
The record that changed. |
Kind |
Created, Updated or Deleted. |
ChangedFields |
The names of the fields that changed. |
ActorUserId |
The user who made the change. |
ProjectId, BoardId |
The project and the board, when the record has them. |
An event contains IDs only. To get the text of a comment, call ISoloQuery.CommentAsync.
Rules for events
- Delivery is not guaranteed. Solo delivers events in its own process and does not store them. If the instance stops at the wrong time, a handler does not get the event. Do not build a feature that must get each event.
- A failure stays in your handler. Solo logs an exception and continues. An exception cannot fail the core write.
- Time limit. Solo stops waiting for a handler after 10 seconds.
- A move between boards sends
Deleted. When a task moves to a different board, Solo sends aDeletedevent for the old board. CallISoloQuery.TaskAsyncto learn if the task still exists.
Live updates
Solo sends its own changes to open boards. To keep your pages current when your own data changes, publish on a topic. Contract 1.4 added topics.
A topic is a short text key that you select, such as plans:3f2a…. Put a prefix of your own at the start, so two extensions cannot use the same key.
Publish from the server half
Inject ISoloLiveUpdates. Publish after you save the change.
public sealed class PlansController(PlansDbContext db, ISoloLiveUpdates live) : ControllerBase
{
[HttpPut("projects/{projectId:guid}/plans/{id:guid}")]
[Authorize(Policy = SoloPolicies.ProjectWrite)]
public async Task<IActionResult> Update(
Guid projectId, Guid id, UpdatePlanRequest request, CancellationToken ct)
{
// Save the change here.
await live.PublishAsync(projectId, $"plans:{id:N}", "changed", ct: ct);
return NoContent();
}
}
Subscribe in the client half
Inject ISoloLiveTopics. Dispose the subscription when the component goes away.
[Inject] private ISoloLiveTopics Live { get; set; } = null!;
private IAsyncDisposable? _live;
protected override async Task OnInitializedAsync()
{
_live = await Live.SubscribeAsync(Project.Id, $"plans:{PlanId:N}",
message => InvokeAsync(ReloadAsync));
}
public async ValueTask DisposeAsync()
{
if (_live is not null)
{
await _live.DisposeAsync();
}
}
Rules for topics
- A message is a signal, not data. Send what changed. The page then gets the new data from your API, which checks access.
PublishAsyncdoes not check access. - Only members can subscribe. A person can subscribe to the topics of a project only with read access to that project.
- The sender gets no message. The page that made the change does not get its own message. It has the change already.
- Delivery is not guaranteed. A page must still work when it gets no message.
- Reconnection. After a lost connection, Solo subscribes to the same topics again.
- Callbacks. A callback runs outside the render cycle. Call
InvokeAsyncin it. - Limits. A topic has 200 characters or less. One connection can hold 64 topics.
Presence
Presence shows who else is on a topic. It is optional.
_live = await Live.SubscribeAsync(Project.Id, topic,
message => InvokeAsync(ReloadAsync),
others => InvokeAsync(() => { _others = others; StateHasChanged(); }));
await Live.SetPresenceAsync(Project.Id, topic, PresenceMode.Viewing);
SetPresenceAsyncreports the current user asViewingorEditing.PresenceMode.Noneclears the report.- The second callback gets the other people on the topic, one entry for each user. The current user is not in the list.
- When you dispose the subscription, Solo clears the presence.
User topics
Each member of a project can subscribe to each topic of that project. For data that belongs to one person, such as a count of unread messages, use a user topic. Contract 1.8 added user topics.
// Server half
await live.PublishToUserAsync(recipientId, "inbox", "unread", count.ToString(), ct);
// Client half
_inbox = await Live.SubscribeUserAsync("inbox", message => InvokeAsync(ReloadAsync));
Solo subscribes the signed-in user to their own topic. A page cannot subscribe to the topic of a different user. A user topic has no presence.
Background work
Outside a request, your code has no caller. ISoloQuery then returns no data, and you have no credential for the API.
ISoloBackground lets scheduled work run as a user who permitted it. Contract 1.8 added it. Inject it with your extension ID as the key.
1. Get the permission of the user
Call GrantAsync in a request that the user makes, such as the request that enables your feature.
[HttpPost("projects/{projectId:guid}/digest")]
[Authorize(Policy = SoloPolicies.ProjectRead)]
public async Task<IActionResult> Enable(
Guid projectId, [FromKeyedServices("digest")] ISoloBackground background, CancellationToken ct)
{
await background.GrantAsync(ct);
// Save the subscription in your own schema.
return NoContent();
}
GrantAsync has no user parameter. It records the caller of the current request. It fails outside a request and for a caller with no sign-in.
2. Do the work as that user
public sealed class DigestService(
[FromKeyedServices("digest")] ISoloBackground background) : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken stopping)
{
foreach (var userId in await SubscribersAsync(stopping))
{
var ran = await background.RunAsAsync(userId, async (scope, ct) =>
{
var projects = await scope.Query.ProjectsAsync(ct);
// Change core data through scope.Api.
}, stopping);
if (!ran)
{
// The user has no grant now. Delete the subscription.
}
}
}
}
RunAsAsync returns false when the user has no grant. The scope gives you:
| Member | Content |
|---|---|
Caller |
The user that the work runs as. |
Query |
An ISoloQuery for that user. |
Api |
An HttpClient for the Solo API, authenticated as that user. |
Services |
A service scope for your own services. |
Rules for background work
- The work has the access of the user at that time. If the user left a project, the work cannot reach that project.
- The work is never a super admin.
scope.Caller.IsSuperAdminisfalse, and the endpoints of the Admin settings refuse the work. - Write through
scope.Api. A change then goes through authorization, the hooks of each extension, the audit log and live updates. - Enums are text. The Solo API reads and writes enum values as text. Use a
JsonStringEnumConverterwhen you serialize a request. - Solo owns the grants. Sign out everywhere deletes the grants of a user. The deletion of your extension data deletes all grants of your extension. Call
RevokeAsyncwhen your feature no longer needs a grant. - Address.
scope.Apiconnects to the address that Solo listens on. If the container cannot connect to that address, the administrator setsExtensions__ApiBaseUrl.
A request from background work has the claim SoloBackgroundClaims.ExtensionId. An audit contributor can use it to mark the change as the work of your extension.
Audit annotations
An ISoloAuditContributor adds a line of text to core audit entries. The MCP extension uses it to mark changes as LLM via MCP. Contract 1.2 added it.
| Member | Purpose |
|---|---|
ShouldRecord |
Return true for a request that needs an annotation. |
RecordAsync(entries, connection, transaction, ct) |
Solo calls this with the new audit IDs before it commits. Write your rows with the connection and the transaction that you get. |
ReadAsync(auditIds, ct) |
Return the text for the audit IDs of one page. |
Rules:
- In
RecordAsync, write only to your own schema. - Do not commit or dispose the connection or the transaction. They belong to Solo.
- If
RecordAsyncfails, Solo does not save the core change. - If
ReadAsyncfails, Solo logs the failure and shows the audit page with no annotation.
McpAuditContributor in the MCP extension is the example.
Credentials that you issue
If your extension issues tokens or keys for users, register an ISoloCredentialIssuer. Contract 1.7 added it.
When a super admin selects Sign out everywhere for a user, Solo revokes its own sessions. Solo then calls each credential issuer. Without an issuer, your tokens stay valid.
public sealed class TokenIssuer(MyDbContext db) : ISoloCredentialIssuer
{
public Task<int> RevokeAllAsync(CredentialHolder holder, CancellationToken ct) =>
db.Tokens
.Where(t => t.Issuer == holder.Issuer && t.Subject == holder.Subject && t.RevokedAt == null)
.ExecuteUpdateAsync(u => u.SetProperty(t => t.RevokedAt, DateTimeOffset.UtcNow), ct);
}
Register it in ConfigureServices:
services.AddCredentialIssuer<TokenIssuer>();
Rules:
- Return the number of revoked credentials. Solo shows the number to the admin.
- A failure is visible. If the method throws an exception, Solo tells the admin that your extension did not revoke its credentials. The sessions of Solo stay revoked.
- Find the user by issuer and subject. An email address can change. The issuer and subject cannot.
- Put only the issuer and subject on a principal. When your authentication handler creates a principal, give it the
issandsubclaims only. Solo treats anemailclaim as the current, verified address from the identity provider.