Named actions: your app as an API
8 min read
Clicking a button works for any app. Calling a function works only for yours. A named action is a function in your app that Onscryn can call by name, with JSON in and JSON out. It is the difference between a workflow that moves the mouse and one that asks your app a question.
Why actions matter
A workflow built from clicks and typing has to find controls, wait for screens and survive layout changes. A workflow that calls an action skips all of that: it asks for order SO-10046 and gets the order back as data. Actions are also the only way for a workflow to read structured data out of the app.
They run in a headless session too. A webhook or a schedule can start a session with no browser attached, call an action, collect the result and shut the session down.
The picture and the people
01
Your app, with the SDK
Draws its own window and hands the picture over.
02
Onscryn on your host
Streams it and applies your clipboard, file and watermark rules.
03
A browser tab
Shows the app. Mouse, keys, uploads and drops go back.
Automation
01
A workflow, webhook or schedule
Runs on demand or on a timer.
02
Onscryn
Starts a session, even with no browser attached.
03
A named action in your app
A function you registered. Returns JSON.
Register an action
Call Onscryn_RegisterAction once for each action, after Onscryn_Start. Give it a name, a one-line description for people building workflows, a handler and optional user data. Names are plain ASCII, and the name __actions is reserved.
The handler receives a correlation id and the parameters as a JSON string, which may be null. When it has finished, it must call Onscryn_SendActionResult with the same id, a success flag and a JSON result. Reply exactly once, even when something fails.
[UnmanagedFunctionPointer(CallingConvention.Cdecl)]
delegate void ActionFn(IntPtr user,
[MarshalAs(UnmanagedType.LPStr)] string id,
[MarshalAs(UnmanagedType.LPWStr)] string paramsJson);
[DllImport("Onscryn.Capture", CallingConvention = CallingConvention.Cdecl)]
static extern int Onscryn_RegisterAction(
[MarshalAs(UnmanagedType.LPStr)] string name,
[MarshalAs(UnmanagedType.LPStr)] string description,
ActionFn fn, IntPtr user);
[DllImport("Onscryn.Capture", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Unicode)]
static extern int Onscryn_SendActionResult(
[MarshalAs(UnmanagedType.LPStr)] string id, int ok,
[MarshalAs(UnmanagedType.LPWStr)] string resultJson);
// Keep the delegate in a field for the life of the process.
static readonly ActionFn GetOrderAction = (user, id, paramsJson) =>
{
try
{
string orderId = ReadJsonString(paramsJson, "id"); // your own JSON helper
string json = Orders.ToJson(orderId); // your own data layer
Onscryn_SendActionResult(id, 1, json);
}
catch (Exception ex)
{
Onscryn_SendActionResult(id, 0, "\"" + ex.Message.Replace("\"", "'") + "\"");
}
};
void RegisterActions()
{
Onscryn_RegisterAction("getOrder", "One order with its lines (params: id)", GetOrderAction, IntPtr.Zero);
}What the SDK does for you
Once you register at least one action, the SDK owns the catalog and the dispatch. It answers the reserved __actions request with the names and descriptions you registered, sends each call to the matching handler, and replies with a failure for any name that is not registered. You write no switch statement and no catalog JSON.
The catalog is what lets the workflow builder offer your actions by name when you add a step.
Threading rules
Handlers are called on an SDK dispatch thread, not on your UI thread. That has consequences, and they are the usual source of actions that hang.
- Do not open modal dialogs from a handler. A dialog runs a message loop and blocks the thread that is waiting for your reply.
- Do not wait on work you have posted to the UI thread. In the reference app, posted messages did not run while no viewer was attached, so a handler that waited for them never replied.
- Read and write controls in a way that is safe across threads, or better, put your data in a model your handlers can read directly.
- Long work can finish later. Return from the handler, do the work on another thread, and call Onscryn_SendActionResult when it is done.
Where actions are called from
In the workflow builder, add a run-action step and choose one of your actions. The step passes its parameters, which can use variables from earlier steps, and the result is available to later steps and to conditions. The same workflow can then run on a schedule, from a webhook URL, or on demand, and every run is recorded in the run history.
Design good actions
The reference app registers actions such as getState, signIn, getDashboard, listOrders, getOrder, listInvoices and resetDemo. They follow a few habits worth copying.
- Make them small and named for what they return or do. listOrders with an optional status is more reusable than a single getEverything.
- Return JSON objects, not formatted text, so a workflow can read fields.
- Make reads side-effect free. Make writes safe to repeat where you can, or return enough to tell whether they already ran.
- Fail with a clear message. A result with the success flag off and a sentence of explanation is easy to branch on.
- Offer a reset. An action that restores known data makes workflows and demos repeatable.