Skip to content
Action discovery & inventorySOKO Action specification (contract)Base infrastructure: SokoJobAction reference (per-action chapters)UploadToSokoConvertAndUploadToSokoUploadToDropboxZipAndUploadToDropboxUnzipAndPublishCopyToDailiesCreateThumbnailSetShotFrameRangeFromVersionHow to build a new ActionGap analysis, risks, and recommendationsExample payloads (2–3)
soko_electon_action_runner_example.js – Electron runner that writes script.py + arguments.json into a temp dir and executes Python via PythonShell with -u (unbuffered) and captures stdout lines as messages.
SokoJob.py – reads the JSON args file and creates an authenticated soko_api client.
SetShotFrameRangeFromVersion.json – defines a startFrame input with default 1001. Format appears non-standard JSON Schema (see TODO in spec).
Runner creates a temp directory and writes script.py and arguments.json.Runner executes Python with -u and passes a single argument: the JSON path (args: [argumentsFile]).Runner listens to each stdout line and classifies the line as WARNING/ERROR/INFO by substring match.At runtime, Python sees:sys.argv[0] = <script.py path>sys.argv[1] = <arguments.json path>But your in-house action pattern passes the entire sys.argv list into the action class, and SokoJob consumes that (internally) to locate the json file.Convert
Runner maintains a task queue and can run actions in parallel up to MAX_CONCURRENT_ACTION_PROCESSES.If multiple actions are submitted in one payload, they run sequentially.No explicit timeout or retry policy is visible in the provided runner sample.TODO: where/if SOKO defines action timeouts, max runtime, retry on non-zero exit, and how failureDetectionJobErrors is used (several actions set it to 3).
inputData (form results)contextData (user, project, folder)contextObjects (the selected objects)contextTypesettingspluginData (auth)pluginData.serverURL, pluginData.apiKey are required to init soko_api.One of:pluginData.apiUser + pluginData.apiUserPassword, orpluginData.userApiKey, orpluginData.jwt
must exist, else login fails.contextObjects must exist for most actions (they iterate self.arguments["contextObjects"]).
id (version UUID)versionNumber (int)components[] (list)components[].id (component UUID)components[].parsedPaths (list of OS-specific path entries)name and/or output.name (human-readable)status / statepublishedAt / published_atpublishedBy / published_byoutput.* (folderId, parentId, outputTypeId, suffix) depending on action
Actions
SOKO Actions Developer Documentation (Draft v1.2)
Scope: this document is inferred from the provided code and explicitly marks TODOs where the contract is not fully observable from code alone.
Update v1.2: added missing “contract-critical” details discovered from your in-house action pattern (notably SokoJob init signature, required InitApi() call, and canonical component path resolution).Convert
Table of contents
1) Action discovery & inventory
Execution host / runner
Base class
Important clarification (v1.2): While the runner passes one positional CLI argument (the arguments.json path), your action code convention passes sys.argv (the full argv list) into SokoJob, not only the JSON path. This affects how new actions must be written.Convert
Discovered Actions (entrypoints + files)
All actions follow the same pattern: define a class inheriting SokoJob, override Handle(), and run it under if __name__ == "__main__":.
Table 3
Action (UI label)
File
Entrypoint
Upload to Soko Media Cloud
script.py (class UploadToSoko)
UploadToSoko.Handle()
Convert to mp4 and Upload to Soko Media Cloud
ConvertAndUploadToSoko.Handle()
There are no rows in this table
Discovered Action input-form schema files
2) SOKO Action specification (contract)
2.1 Execution model (confirmed)
Where actions run: locally, on the user machine via Electron runner.
Invocation steps (confirmed):
Critical clarification (v1.2): argv contract for action authors
Canonical entrypoint pattern (MUST for compatibility):
if __name__ == "__main__":
plugin = MyAction(sys.argv)
plugin.Handle()
…and constructor:
class MyAction(SokoJob):
def __init__(self, args):
super().__init__(args)
Convert
Concurrency (confirmed):
Timeouts / retries (TODO):
2.2 Inputs: arguments.json schema (confirmed + inferred)
Top-level structure (confirmed):
The runner writes a JSON object containing at least:
Required fields (confirmed by base class / runner):
2.2.1 contextType="version" – minimum reliable schema (v1.2, PARTIALLY CONFIRMED)
Based on observed actions, a Version context object typically contains:
Optional / may exist, but not guaranteed (TODO to confirm):
Recommendation (MUST for action authors): treat anything beyond id, versionNumber, components[].parsedPaths as optional unless explicitly stated for the action.
2.2.2 Component path resolution (v1.2, CONFIRMED)
Earlier draft referenced get_component_path_for_current_os(), but your codebase convention uses:
from soko_api.utils import files
path_data = files.get_component_path_data_for_current_os(component["parsedPaths"])
local_path = path_data["path"]
Where path_data appears to be a dict (at least containing path, and possibly also prefix / prefixVariable).Convert
This is the canonical method (MUST) to resolve local file paths.
Do not hand-pick parsedPaths entries unless you have a hard reason.
Want to print your doc?
This is not the way.
This is not the way.
Try clicking the ··· in the right corner or using a keyboard shortcut (
CtrlP
) instead.