JuliuS – API Documentation

Introduzione

JuliuS espone un server HTTP locale basato su Indy TIdHTTPServer che consente il controllo remoto del motore di scripting e del browser embedded (Chromium CEF). Tutti gli endpoint usano una singola rotta con parametri in query string.

Gli endpoint sono divisi in tre macro-aree: Browser CEF (operazioni dentro il browser embedded), Ispezione pagina / DevTools (lettura del DOM, frame, network), OS (mouse e tastiera a livello sistema operativo, per finestre native fuori dal browser).

Base URL & Autenticazione

http://<host>:<port>/

⚠ Attenzione: Al momento JuliuS non prevede autenticazione. Esporre il server solo su localhost o reti fidate.

Carica script da file

GET/?loadscript={filename}Carica uno script dal disco

Carica un file di script dalla cartella configurata in Settings.Data.scriptPath e lo apre nell'editor grafico di JuliuS. Usare questo endpoint quando lo script da eseguire risiede già sul disco della macchina che ospita JuliuS. L'estensione .js viene aggiunta automaticamente se il file non viene trovato senza di essa, rendendo opzionale specificarla nella chiamata. Il caricamento è asincrono: la risposta arriva immediatamente, ma l'apertura dell'editor avviene nel thread principale poco dopo.

async

200OK

200*Errore, file non trovato [...]

GET /?loadscript=login_flow HTTP/1.1

Carica script da stream

POST/?operation=readscritpfromstreamInvia uno script via body

Invia il sorgente dello script direttamente nel body della richiesta POST, senza necessità di un file su disco. È la modalità ideale per sistemi di orchestrazione esterni (es. ScrapManager) che generano o modificano gli script a runtime prima di inviarli a JuliuS. Lo script viene aperto nell'editor con il titolo "Script from remote". Se il body è assente o la lettura fallisce, viene restituito un messaggio di errore ma il server non va in eccezione.

async

200OK

200*Errore nello scritp — body assente o errore lettura

POST /?operation=readscritpfromstream HTTP/1.1
Content-Type: text/plain

// script remoto
var x = doSomething();

Leggi script corrente

GET/?operation=getscriptRitorna il sorgente dello script caricato nell'editor

Restituisce nel body della risposta il testo dello script attualmente presente nell'editor di frmScript. La lettura avviene direttamente da SynSynaScript.Text via TThread.Synchronize, quindi include anche le eventuali modifiche fatte manualmente dall'utente nell'editor dopo il caricamento iniziale, e non solo l'ultimo valore impostato via loadscript o readscritpfromstream. È un endpoint di pura lettura: non modifica lo stato dell'editor né l'esecuzione in corso. Utile per verificare cosa sta per essere eseguito prima di un start, per fare un backup veloce dell'editor remoto o per confrontare lo script in memoria con il file su disco.

sync

Parametro	Obbligatorio	Descrizione
operation	✓	Deve essere `getscript`

Header risposta	Valore
Content-Type	`text/plain; charset=utf-8`

200Body con il sorgente completo dello script (UTF-8)

200Body vuoto — nessuno script aperto in frmScript o errore durante la lettura

GET /?operation=getscript HTTP/1.1
Host: 127.0.0.1:8080

# Salva su file lo script attualmente caricato
curl "http://127.0.0.1:8080/?operation=getscript" --output current_script.js

Leggi linea corrente

GET/?operation=getcurrentlineRitorna il numero della linea corrente del cursore

Restituisce nel body della risposta il numero (1-based) della riga in cui si trova attualmente il cursore dell'editor SynSynaScript in frmScript. Questa è esattamente la riga che verrebbe usata come punto di partenza dal prossimo ?operation=start: l'esecuzione dello script inizia infatti dalla posizione corrente del caret nell'editor. Utile per monitorare a che punto è arrivata l'esecuzione di uno script, sincronizzare interfacce esterne con il puntatore di esecuzione, o verificare la riga di partenza prima di lanciare uno start. Endpoint puramente di lettura: non altera lo stato dell'editor.

sync

Parametro	Obbligatorio	Descrizione
operation	✓	Deve essere `getcurrentline`

Header risposta	Valore
Content-Type	`text/plain; charset=utf-8`

200Numero della riga corrente come stringa (es. 42)

2000 — frmScript non inizializzato o errore di lettura

GET /?operation=getcurrentline HTTP/1.1
Host: 127.0.0.1:8080

→ 42

Imposta linea di partenza

GET/?operation=setcurrentline&line={N}Sposta il cursore alla riga indicata per il prossimo start

Sposta il cursore dell'editor SynSynaScript alla riga indicata (1-based), che diventerà la riga di partenza usata dal prossimo ?operation=start. La colonna del caret viene riportata a 1. Se il valore richiesto supera il numero di righe presenti nello script, viene applicato un clamp sull'ultima riga disponibile. L'operazione è protetta: se uno script è già in esecuzione la chiamata viene rifiutata per evitare di alterare il puntatore di esecuzione corrente. Più flessibile rispetto a reset cursore, che riporta sempre il caret alla riga 1.

sync

Parametro	Obbligatorio	Descrizione
operation	✓	Deve essere `setcurrentline`
line	✓	Numero di riga (intero ≥ 1, 1-based). Valori oltre il numero massimo di righe vengono limitati all'ultima riga disponibile.

Header risposta	Valore
Content-Type	`text/plain; charset=utf-8`

200line_set_N — conferma con il numero di riga effettivamente impostato (può differire da quello richiesto se è stato applicato il clamp)

200*ERROR: parametro line mancante o non numerico

200*ERROR: line deve essere >= 1

200*ERROR: script in esecuzione, impossibile cambiare la linea corrente

200*ERROR: frmScript non inizializzato

GET /?operation=setcurrentline&line=42 HTTP/1.1
Host: 127.0.0.1:8080

→ line_set_42

Flusso tipico: chiamare ?operation=status per verificare che il sistema sia idle, poi ?operation=setcurrentline&line=N, poi ?operation=start per avviare l'esecuzione dalla riga scelta.

Avvia esecuzione

GET/?operation=start[&params...]Avvia lo script corrente

Avvia l'esecuzione dello script attualmente caricato nell'editor di JuliuS, a partire dalla riga indicata da currentLine. Prima di chiamare questo endpoint è buona pratica verificare lo stato con ?operation=status: se un processo è già in esecuzione la chiamata viene rifiutata con un messaggio esplicito, evitando esecuzioni concorrenti. I parametri excelLine e remoteVirtualPath impostano il contesto di logging e upload degli screenshot, usati dallo script durante l'esecuzione.

async

Parametro	Obbligatorio	Descrizione
operation	✓	Deve essere `start`
currentLine		Riga di partenza dell'esecuzione
excelLine		Nome base della riga nel log Excel, usato per nominare i file di screenshot
remoteVirtualPath		Path virtuale remoto per l'upload degli screenshot (`_` viene sostituito con `/`). Il trailing `/` viene aggiunto automaticamente.

200started

200*Already Running, check status before try to start another process

200*Script is not already initiated — nessun form di script aperto

Ferma esecuzione

GET/?operation=stopInterrompe lo script in esecuzione

Interrompe lo script in esecuzione richiamando frmScript.stopExecution nel thread principale. L'operazione gestisce correttamente sia lo stato running che lo stato paused, rimuovendo entrambi i flag di stato. Viene inoltre chiusa ogni finestra popup figlia aperta durante l'esecuzione. Se non è in corso alcuna esecuzione la chiamata è un no-op silenzioso.

async

GET /?operation=stop HTTP/1.1

Reset cursore

GET/?operation=resetRiporta il cursore dell'editor a riga 1

Sposta il cursore dell'editor SynEdit alla prima riga dello script, preparando una nuova esecuzione dall'inizio. Utile nei flussi automatizzati per garantire che lo script riparta sempre dall'inizio dopo un ciclo completato. L'operazione è protetta: se uno script è attualmente in esecuzione (IsRunning = true) la chiamata viene ignorata silenziosamente senza restituire errori, evitando interferenze con il processo in corso.

async

Nota: Ignorato silenziosamente se uno script è in esecuzione (IsRunning = true).

Status

GET/?operation=statusVerifica lo stato del motore di scripting

Restituisce lo stato corrente del motore di scripting di JuliuS. È l'endpoint di polling fondamentale da chiamare prima di ogni start per evitare avvii multipli, e durante l'esecuzione per rilevare quando uno script è terminato. Lo stato tiene conto sia dell'esecuzione attiva dello script che del caricamento della pagina nel browser (MainBrowserFrm.FPageLoading): se la pagina è ancora in caricamento il sistema risulta occupato anche se lo script è tecnicamente in pausa.

sync

200on working — script in esecuzione o pagina in caricamento

200no operation progress — sistema idle, pronto per un nuovo start

Get Result (funzione fissa)

GET/?operation=getresultEsegue preventivo() e ritorna il risultato

Chiama nel browser la funzione JavaScript preventivo() — la funzione di estrazione del risultato per convenzione negli script JuliuS — e restituisce il suo valore serializzato come JSON di TOperationResult. Il JSON include il risultato grezzo, l'ID operazione, la data di avvio e la lista degli screenshot catturati. Da usare al termine di uno script di preventivazione per recuperare il valore calcolato. Per funzioni con nome diverso usare l'endpoint Get Result variabile.

sync

Get Result (funzione variabile)

GET/?getresult={functionName}Esegue una funzione JS arbitraria e ritorna il risultato

Versione generalizzata di getresult: esegue nel browser la funzione JavaScript il cui nome viene passato come parametro, aggiungendo automaticamente le parentesi (). Restituisce il valore in formato JSON TOperationResult, esattamente come l'endpoint fisso. Usare questo endpoint quando lo script espone funzioni di estrazione con nomi personalizzati (es. getOrderTotal, calcolaPremio) invece della funzione standard preventivo(). La funzione deve essere già definita nel contesto JS del browser al momento della chiamata.

sync

Parametro	Descrizione
getresult	Nome della funzione JS da eseguire, senza parentesi. Le `()` vengono aggiunte automaticamente.

GET /?getresult=getOrderTotal HTTP/1.1

Navigate

GET/?navigate={url}Forza la navigazione del browser verso un URL

Forza il browser CEF embedded a navigare verso l'URL specificato richiamando frmScript.navigateUrl nel thread principale. Utile per reindirizzare il browser dall'esterno senza caricare né eseguire uno script, ad esempio per posizionarlo su una pagina specifica prima di avviare un'operazione. La navigazione è asincrona: la risposta arriva immediatamente ma la pagina sarà ancora in caricamento. Per attendere il completamento del caricamento usare in seguito ?operation=waitpageload o un ritardo fisso.

async

GET /?navigate=https%3A%2F%2Fwww.example.com HTTP/1.1

Click (CEF)

GET/?operation=click&X={x}&Y={y}Simula un click nel browser CEF

Invia un click sintetico al browser Chromium embedded nelle coordinate pixel specificate, relative al pannello CEF. È utile per interagire con elementi non facilmente raggiungibili via JavaScript (canvas, WebGL, elementi con gestori di eventi custom). Le coordinate devono essere calibrate rispetto alla risoluzione impostata con SCREEN_SIZE. Per click su finestre native Windows o dialog di sistema usare invece gli endpoint OS Mouse, che agiscono a livello sistema operativo.

sync

Parametro	Descrizione
X	Coordinata X in pixel relativa al pannello CEF
Y	Coordinata Y in pixel relativa al pannello CEF

GET /?operation=click&X=320&Y=240 HTTP/1.1

Snapshot (CEF)

GET/?operation=snapshotScreenshot del browser CEF come stream JPG

Cattura lo stato visuale corrente del browser CEF embedded e lo restituisce come stream binario JPG. L'header custom scalefactor indica il fattore di scala DPI del monitor e va usato dal client per interpretare correttamente le dimensioni dell'immagine in ambienti con display ad alta densità (HiDPI). Questo endpoint cattura solo il pannello del browser, non l'intera finestra di JuliuS né il desktop. Per screenshot dell'intero desktop usare osscreenshotjpg.

syncbinary stream

Header risposta	Valore
Content-Type	`image/jpg`
scalefactor	Fattore DPI del monitor (es. `1.25` per display 125%)

curl "http://127.0.0.1:8080/?operation=snapshot" --output screenshot.jpg

Restart Chromium

GET /?operation=restartchromium Reset sessione Chromium in memoria

Azzera la sessione Chromium embedded senza riavviare l'applicazione. Tramite DevTools Protocol cancella cache HTTP, cookie, localStorage, sessionStorage e IndexedDB, poi naviga su about:blank. Risponde solo quando il reset è completato.

sync

Risposta

200 chromium_restarted — reset completato

200* ERROR: ... — messaggio di errore

Esempio

GET /?operation=restartchromium HTTP/1.1
Host: 127.0.0.1:8080

→ chromium_restarted

Delete Chromium Cache

GET /?operation=deletechromiumcache Pulizia profonda: memoria + file su disco

Esegue un reset completo della cache Chromium: svuota cache HTTP, cookie e storage tramite DevTools Protocol, poi cancella fisicamente la directory GlobalCEFApp.RootCache su disco. Più lenta di restartchromium — usare per cache corrotta o per garantire una sessione indistinguibile da un avvio a freddo.

sync

Confronto con restartchromium

Azione	restartchromium	deletechromiumcache
Cache HTTP in memoria	✅	✅
Cookie in memoria	✅	✅
LocalStorage / IndexedDB	✅	✅
File cache su disco	❌	✅
Tempo medio	~3 s	~5 s

Risposta

200 chromium_cache_deleted — pulizia completata

200* ERROR: ... — messaggio di errore

Esempio

GET /?operation=deletechromiumcache HTTP/1.1
Host: 127.0.0.1:8080

→ chromium_cache_deleted

Get DOM

GET/?operation=getdomRestituisce l'outerHTML completo della pagina

Ritorna il sorgente HTML completo della pagina attualmente caricata nel browser, ottenuto tramite document.documentElement.outerHTML. È utile per analisi offline del DOM, debug di pagine con rendering dinamico o per verificare lo stato attuale della pagina prima di eseguire interazioni. Poiché restituisce il DOM live (post JavaScript, non il sorgente originale del server), riflette lo stato effettivo della pagina incluse le modifiche apportate dagli script già eseguiti.

sync

200HTML completo della pagina — text/html; charset=utf-8

200*ERROR: ... — eccezione interna

Get Form Fields

GET/?operation=getformfieldsElenca tutti i campi form della pagina in JSON

Analizza il DOM della pagina corrente e restituisce un array JSON con tutti gli elementi interattivi dei form: input, select, textarea e button. Per ogni elemento vengono incluse proprietà come id, name, type, value e visible. Particolarmente utile in fase di sviluppo di uno script, per identificare gli ID degli elementi da usare nei comandi WRITETO senza dover ispezionare manualmente il sorgente della pagina.

sync

200JSON array dei campi form — application/json; charset=utf-8

200*ERROR: ... — eccezione interna

Get Page Info

GET/?operation=getpageinfoMetadati sulla pagina corrente

Restituisce un oggetto JSON con le informazioni essenziali sulla pagina attualmente caricata: URL corrente, titolo del documento, readyState e lista degli iframe presenti con i relativi URL. È l'endpoint ideale per verificare rapidamente su quale pagina si trova il browser, controllare che il caricamento sia completo (readyState === "complete") e identificare la struttura dei frame prima di usare TARGET_FRAME negli script.

sync

200JSON con url, title, readyState, lista iframes — application/json; charset=utf-8

200*ERROR: ... — eccezione interna

Get Console Log

GET/?operation=getconsolelogRecupera i messaggi della console JavaScript

Installa automaticamente un listener sulla console JavaScript del browser (se non già attivo) e restituisce tutti i messaggi console.log, console.warn ed console.error accumulati fino a quel momento. Indispensabile per il debug dei blocchi SNIPPET negli script, che tipicamente usano console.log() per tracciare l'esecuzione. I messaggi vengono accumulati in memoria e restituiti ad ogni chiamata senza essere svuotati, salvo reset esplicito.

sync

200JSON array dei messaggi console — application/json; charset=utf-8

200*ERROR: ... — eccezione interna

EvalJS (via API)

GET/?evaljs={expression}Valuta un'espressione JavaScript arbitraria nel browser

Esegue una singola espressione JavaScript nel contesto del browser CEF e ne restituisce il valore come testo semplice. A differenza di ?operation=getresult, il risultato non viene registrato nel TOperationResult corrente ma restituito direttamente nella risposta HTTP. L'espressione deve essere URL-encoded. Utile per interrogazioni rapide del DOM o per verificare lo stato di variabili JS senza dover definire una funzione dedicata nello script.

sync

200Risultato dell'espressione come stringa — text/plain; charset=utf-8

200*ERROR: ... — eccezione interna o errore JS

# Legge il titolo della pagina
GET /?evaljs=document.title

# Verifica la visibilità di un elemento (selettore URL-encoded)
GET /?evaljs=%24('%23btnAvanti').is('%3Avisible')

Find Element

GET/?findelement={css_selector}Verifica l'esistenza di un elemento CSS nel DOM

Verifica se un selettore CSS è presente nel DOM della pagina corrente e restituisce un oggetto JSON con le proprietà dell'elemento trovato, tra cui id, tagName, value, visible e boundingRect. Utile per implementare logica condizionale nei flussi di automazione: verificare che un pulsante sia presente prima di cliccare, attendere la comparsa di un elemento di risultato o rilevare messaggi di errore nella pagina. Il selettore deve essere URL-encoded.

sync

200JSON con le proprietà dell'elemento trovato — application/json; charset=utf-8

200*ERROR: ... — eccezione interna

# Cerca per ID (# URL-encoded = %23)
GET /?findelement=%23btnAvanti
# Cerca per classe
GET /?findelement=.risultato-finale

Get Frame List

GET/?operation=getframelistLista di tutti i frame aperti nel browser

Restituisce un array JSON con tutti i frame attualmente aperti nel browser CEF: frame principale, iframe e frame figlio. Per ogni frame vengono forniti name, id, url, il flag isMain e il flag isFocused. È l'endpoint di riferimento da consultare prima di usare la direttiva TARGET_FRAME=POPUP negli script, per identificare esattamente il nome o l'URL del frame target. Particolarmente utile con pagine che aprono popup o usano frame annidati.

sync

200JSON array con name, id, url, isMain, isFocused

200*{"error":"..."}

Get Frame Source

GET/?operation=getframesource[&frame={name}]HTML sorgente di un frame specifico

Legge e restituisce l'HTML sorgente di un frame specifico identificato per nome, includendo il supporto per frame cross-origin che normalmente non sarebbero accessibili via JavaScript standard per policy di sicurezza. Se il parametro frame viene omesso, viene restituito il sorgente del frame principale. Utile per ispezionare il contenuto di iframe di terze parti, form caricati in frame separati o popup figlio aperti durante la navigazione.

sync

Parametro	Obbligatorio	Descrizione
frame		Nome del frame target. Se omesso → frame principale.

200HTML del frame — text/html; charset=utf-8

200*ERROR: ... — frame non trovato o errore interno

GET /?operation=getframesource&frame=contentFrame HTTP/1.1

Wait Page Load

GET/?operation=waitpageload[&timeout={ms}]Attende il completamento del caricamento della pagina

Blocca la risposta HTTP finché la pagina nel browser non ha terminato il caricamento (o finché non scade il timeout). A differenza dei WAIT fissi negli script, questo endpoint si adatta ai tempi reali del server: restituisce la risposta non appena la pagina è pronta, riducendo i tempi di attesa inutili. La richiesta gira nel thread HTTP senza bloccare il main thread dell'applicazione. Il timeout predefinito è 15 secondi e può essere aumentato per pagine particolarmente lente.

sync (bloccante)

Parametro	Default	Descrizione
timeout	15000	Timeout massimo di attesa in millisecondi

200loaded — pagina caricata correttamente entro il timeout

200*timeout — il timeout è scaduto prima del completamento del caricamento

GET /?operation=waitpageload&timeout=20000 HTTP/1.1

DevTools Protocol

GET/?devtools={method}[&params={json}]Esegue un comando Chrome DevTools Protocol

Permette di eseguire qualsiasi comando del Chrome DevTools Protocol (CDP) direttamente sul browser CEF, aprendo l'accesso a funzionalità avanzate non esposte dalle API standard: emulazione di dispositivi, intercettazione di richieste di rete, profiling, accesso al DOM a basso livello e molto altro. Il parametro params accetta un oggetto JSON URL-encoded con i parametri specifici del comando CDP. Consultare la documentazione CDP ufficiale per la lista completa dei metodi disponibili.

sync

Parametro	Obbligatorio	Descrizione
devtools	✓	Metodo CDP da eseguire (es. `Network.enable`, `DOM.getDocument`)
params		Parametri del comando come JSON URL-encoded

200JSON con la risposta del comando CDP

200*{"error":"..."} — metodo non valido o errore CDP

# Abilita il tracking delle richieste di rete
GET /?devtools=Network.enable

# Valuta un'espressione tramite Runtime CDP
GET /?devtools=Runtime.evaluate¶ms=%7B%22expression%22%3A%22document.title%22%7D

Start Network Log

GET/?operation=startnetworklogAvvia il logging delle chiamate di rete

Svuota il buffer del log di rete precedente e abilita Network.enable tramite il Chrome DevTools Protocol per intercettare tutte le richieste HTTP/HTTPS effettuate dal browser: XHR, fetch, caricamento di risorse. Va chiamato prima di navigare verso la pagina da monitorare, in modo da non perdere le prime richieste. I dati raccolti sono poi recuperabili con ?operation=getnetworklog. Utile per analizzare le API chiamate da una pagina web o per identificare endpoint da replicare.

sync

200network log started

200*ERROR: ... — eccezione interna

Get Network Log

GET/?operation=getnetworklogRecupera il log delle richieste di rete intercettate

Restituisce il log accumulato delle richieste di rete intercettate dopo una chiamata a startnetworklog. Il log è un array JSON in cui ogni entry contiene il metodo HTTP (method), l'URL completo (url) e il tipo di risorsa (type, es. XHR, Fetch, Document). Chiamare questo endpoint più volte non azzera il log: il buffer cresce fino al prossimo startnetworklog. Ideale per reverse engineering delle API di una pagina web o per verificare le chiamate effettuate durante l'esecuzione di uno script.

sync

200JSON array con method, url, type per ogni richiesta — application/json; charset=utf-8

200*{"error":"..."}

OS Mouse — Move

GET/?operation=osmousemove&x={x}&y={y}Sposta il cursore del mouse a coordinate assolute di schermo

Sposta il cursore del mouse alle coordinate assolute di schermo usando le API native del sistema operativo Windows (TCrossSO.SetMousePos). A differenza dell'endpoint click CEF che agisce dentro il browser embedded, questo endpoint controlla il cursore a livello SO ed è in grado di interagire con qualsiasi finestra visibile sul desktop: dialog nativi Windows, popup di sistema, finestre di altre applicazioni o la stessa interfaccia di JuliuS. Usare in combinazione con osmouseclick per eseguire click precisi su elementi nativi.

syncOS

200moved

200*ERROR: ...

GET /?operation=osmousemove&x=500&y=300 HTTP/1.1

OS Mouse — Click sinistro

GET/?operation=osmouseclickSimula un click sinistro nella posizione corrente del cursore

Simula la pressione e il rilascio del tasto sinistro del mouse nella posizione corrente del cursore di sistema, tramite TCrossSO.MouseLClick. Deve essere preceduto da una chiamata a osmousemove per posizionare correttamente il cursore. Agisce a livello sistema operativo, quindi funziona su qualsiasi finestra attiva sul desktop, non solo sul browser CEF. Per spostamento e click in un'unica operazione atomica usare osmousemoveclick.

syncOS

200clicked

OS Mouse — Move + Click

GET/?operation=osmousemoveclick&x={x}&y={y}Sposta il cursore e clicca in un'unica operazione

Combina spostamento del cursore e click sinistro in una singola chiamata API, con una pausa di 50ms tra le due operazioni per consentire al sistema operativo di aggiornare la posizione del cursore prima del click. È l'endpoint più efficiente per click su coordinate fisse, in quanto riduce il numero di round-trip HTTP rispetto a due chiamate separate. Ideale per automazioni veloci che devono cliccare su molti elementi in sequenza.

syncOS

200moved_and_clicked

GET /?operation=osmousemoveclick&x=640&y=480 HTTP/1.1

OS Mouse — Click destro

GET/?operation=osmouserclickSimula un click destro nella posizione corrente del cursore

Simula la pressione e il rilascio del tasto destro del mouse nella posizione corrente del cursore, tramite TCrossSO.MouseRClick. Utile per aprire menu contestuali nativi del sistema operativo o di applicazioni Windows che non espongono i propri elementi tramite interfaccia web. Come gli altri endpoint OS mouse, agisce a livello di sistema operativo e non è vincolato al browser CEF.

syncOS

200right_clicked

OS Mouse — Get posizione

GET/?operation=osmouseposRestituisce la posizione corrente del cursore di sistema

Legge e restituisce le coordinate assolute di schermo del cursore del mouse come oggetto JSON {"x": N, "y": N}. Utile durante lo sviluppo e il debug di automazioni per calibrare le coordinate da usare negli endpoint osmousemove e osmousemoveclick, o per verificare che il cursore si trovi nella posizione attesa prima di eseguire un click.

syncOS

200{"x":320,"y":240} — application/json; charset=utf-8

200*{"error":"..."}

OS Tastiera — Key Press

GET/?operation=oskeypress&key={keycode}Simula la pressione di un tasto tramite keycode numerico

Invia la pressione di un tasto alla finestra attiva del sistema operativo tramite il suo keycode Virtual Key (VK). A differenza di WRITETO che scrive nel browser CEF, questo endpoint agisce a livello SO e può controllare qualsiasi finestra attiva: dialog nativi Windows, form non web, applicazioni desktop. Per tasti comuni (ENTER, ESC, TAB) sono disponibili gli shortcut dedicati più leggibili; usare questo endpoint quando si ha bisogno di un tasto specifico non coperto dagli shortcut.

syncOS

Keycode	Tasto	Keycode	Tasto
13	ENTER	27	ESC
9	TAB	32	SPAZIO
8	BACKSPACE	46	DELETE
37	← LEFT	38	↑ UP
39	→ RIGHT	40	↓ DOWN
112–123	F1–F12	65–90	A–Z

200key_pressed

GET /?operation=oskeypress&key=13 HTTP/1.1
# preme ENTER sulla finestra attiva

OS Tastiera — Shortcut tasti comuni

GET/?operation={oskeyXXX}Shortcut nominativi per i tasti più utilizzati

Alias nominativi per i tasti più frequentemente usati nelle automazioni, più leggibili rispetto ai keycode numerici di oskeypress. Ogni endpoint esegue esattamente la stessa operazione del corrispondente keycode numerico, ma rende i log e le sequenze di automazione immediatamente comprensibili. Usare questi shortcut ogni volta che è possibile; ricorrere a oskeypress con keycode numerico solo per tasti non coperti da questi alias.

syncOS

Operation	Tasto	Risposta
oskeyenter	ENTER (↵)	`enter`
oskeyesc	ESC	`esc`
oskeytab	TAB (⇥)	`tab`
oskeybackspace	BACKSPACE (⌫)	`backspace`

GET /?operation=oskeyenter HTTP/1.1
GET /?operation=oskeyesc HTTP/1.1

OS Tastiera — Arrow Keys

GET/?operation=oskeyarrow&dir={up|down|left|right}Simula la pressione dei tasti freccia direzionali

Invia la pressione di uno dei quattro tasti freccia direzionali alla finestra attiva del sistema operativo. Utile per navigare in dropdown nativi, scorrere liste, muoversi tra campi di un form Windows o controllare applicazioni desktop che rispondono ai tasti freccia. Il parametro dir accetta i valori up, down, left, right in minuscolo; valori non riconosciuti vengono ignorati silenziosamente.

syncOS

dir	Tasto
up	↑ Freccia su
down	↓ Freccia giù
left	← Freccia sinistra
right	→ Freccia destra

200arrow_down / arrow_up / ecc.

GET /?operation=oskeyarrow&dir=down HTTP/1.1

OS Tastiera — Key Combo

GET/?operation=oskeycombо&combo={modifier+key}Combinazione di tasti SO (Ctrl/Shift/Alt + tasto)

Simula una combinazione di tasti a livello sistema operativo tramite keybd_event delle API Windows. Il parametro combo accetta la sintassi modificatore+tasto in minuscolo, URL-encoded se necessario. Il modificatore può essere ctrl, shift o alt; il tasto può essere una lettera singola (a–z) oppure un tasto speciale per nome. Disponibile solo su piattaforma Windows: su altre piattaforme l'endpoint risponde con un messaggio di errore esplicito senza generare eccezioni.

syncOS

Campo combo	Valori accettati
modifier	`ctrl`, `shift`, `alt`
key	Lettera singola (`a`–`z`), oppure: `f4`–`f6`, `f10`–`f12`, `tab`, `enter`, `esc`, `del`, `home`, `end`, `pageup`, `pagedown`

200combo_ctrl+c — conferma della combinazione eseguita

200*ERROR: formato combo non valido, usare modifier+key

200*ERROR: tasto non riconosciuto [...]

200*ERROR: oskeycombо not implemented on this platform

# Copia (Ctrl+C)
GET /?operation=oskeycombо&combo=ctrl+c

# Incolla (Ctrl+V)
GET /?operation=oskeycombо&combo=ctrl+v

# Chiudi finestra (Alt+F4)
GET /?operation=oskeycombо&combo=alt+f4

# Seleziona tutto (Ctrl+A)
GET /?operation=oskeycombо&combo=ctrl+a

# Tab inverso (Shift+Tab)
GET /?operation=oskeycombо&combo=shift+tab

OS Screenshot (PNG)

GET/?operation=osscreenshotScreenshot dell'intero desktop Windows in formato PNG

Cattura l'intero desktop Windows — inclusi taskbar, popup nativi, dialog di sistema e qualsiasi finestra aperta — e lo restituisce come stream binario PNG. A differenza di snapshot che cattura solo il pannello del browser CEF, questo endpoint fotografa tutto ciò che è visibile sullo schermo. L'header scalefactor indica il fattore DPI del monitor. Usare la variante osscreenshotjpg quando la dimensione del file è prioritaria rispetto alla qualità.

syncOSbinary stream

Header risposta	Valore
Content-Type	`image/png`
scalefactor	Fattore DPI del monitor

200Stream PNG dell'intero desktop

200*ERROR: screenshot failed

curl "http://127.0.0.1:8080/?operation=osscreenshot" --output desktop.png

OS Screenshot (JPG)

GET/?operation=osscreenshotjpgScreenshot dell'intero desktop Windows in formato JPG

Variante JPG dell'endpoint osscreenshot: cattura l'intero desktop Windows e lo restituisce compresso in JPEG con qualità 45 (la stessa usata per lo snapshot del browser CEF). Produce file significativamente più leggeri rispetto al PNG, al costo di una lieve perdita qualitativa sulle aree di testo. È la variante consigliata per i flussi di debug e monitoraggio frequente, dove la velocità di trasferimento è più importante della fedeltà dell'immagine.

syncOSbinary stream

Header risposta	Valore
Content-Type	`image/jpg`
scalefactor	Fattore DPI del monitor

200Stream JPG dell'intero desktop

200*ERROR: screenshot failed

curl "http://127.0.0.1:8080/?operation=osscreenshotjpg" --output desktop.jpg

Get Browser Window Info

GET/?operation=getbrowserwindowinfoPosizione e dimensioni della finestra JuliuS e del pannello CEF

Restituisce un oggetto JSON con la posizione e le dimensioni sia della finestra principale di JuliuS (mainForm) che del pannello browser CEF (browser), compresi i valori assoluti di schermo (screenLeft, screenTop). Il campo scaleFactor indica il fattore DPI del monitor. Questo endpoint è fondamentale per convertire coordinate relative al browser in coordinate assolute di schermo da usare con gli endpoint OS mouse, in modo che le automazioni funzionino correttamente indipendentemente da dove è posizionata la finestra di JuliuS sul desktop.

sync

Struttura risposta JSON

{
  "mainForm": {
    "left": 100, "top": 50,
    "width": 1200, "height": 800
  },
  "browser": {
    "left": 0, "top": 60,
    "width": 1024, "height": 768,
    "screenLeft": 100, "screenTop": 110,
    "clientWidth": 1024, "clientHeight": 768
  },
  "scaleFactor": 1.25
}

200JSON con mainForm, browser e scaleFactor — application/json; charset=utf-8

200*{"error":"..."}

Uso tipico: Chiamare questo endpoint una volta prima di una sequenza di click OS per ricavare browser.screenLeft e browser.screenTop, poi sommarli alle coordinate relative del browser per ottenere le coordinate assolute di schermo da passare a osmousemoveclick.

Browser Move Click

GET/?operation=browsermoveclick&x={x}&y={y}Click OS a coordinate relative al pannello browser

Esegue un click sinistro a livello sistema operativo usando coordinate relative al pannello browser CEF (stessa origine di snapshot e MOUSE_CLICK), delegando internamente a ClickOnBrowserRelative la conversione in coordinate assolute di schermo. È più affidabile di osmousemoveclick con coordinate assolute perché funziona correttamente indipendentemente dalla posizione della finestra JuliuS sul desktop e dal fattore di scala DPI, senza che il chiamante debba calcolare la conversione manualmente.

syncOS

Parametro	Descrizione
x	Coordinata X in pixel CSS relativa all'angolo superiore sinistro del pannello browser
y	Coordinata Y in pixel CSS relativa all'angolo superiore sinistro del pannello browser

200clicked_at_browser_320_240 — conferma con le coordinate usate

200*ERROR: ...

# Click a X=320, Y=240 relativi al browser
GET /?operation=browsermoveclick&x=320&y=240 HTTP/1.1

Differenza rispetto a click CEF e osmousemoveclick: ?operation=click invia un evento sintetico CEF interno. osmousemoveclick usa coordinate assolute di schermo. browsermoveclick usa coordinate relative al browser ma agisce a livello SO — è il punto di equilibrio tra semplicità d'uso e affidabilità cross-posizione.

Rewrite Variabili Globali

POST/?globalv=rewriteSovrascrive le variabili globali dello script corrente

Invia un nuovo set di variabili globali nel body POST e le inietta direttamente nel blocco GLOBALV dello script attualmente caricato, sovrascrivendo i valori precedenti. Il contenuto viene caricato in frmScript.GlobalV tramite LoadFromStream e poi updateGlobalV aggiorna fisicamente le righe del blocco GLOBALV=BEGIN/END nell'editor. Utile nei sistemi di orchestrazione per parametrizzare uno script già caricato con dati diversi (es. cliente diverso, pratica diversa) senza ricaricare l'intero file. Il body deve contenere coppie var nome="valore"; nel formato del blocco GLOBALV.

async

POST /?globalv=rewrite HTTP/1.1
Content-Type: text/plain

var USERNAME="mario.rossi";
var TARGET_URL="https://example.com/dashboard";
var MAX_RETRIES="3";

API Logging — Panoramica

Ogni richiesta HTTP ricevuta dal server JuliuS viene registrata automaticamente come una riga JSON Lines nel file di log dell'applicazione. Il logging si appoggia all'unit synaLog (singleton globale thLog, scrittura asincrona con thread writer dedicato, rotazione automatica a 100 MB, archiviazione zip dei vecchi log con retention di 7 giorni). Il file di log è lo stesso usato dal motore di scripting (wLog), quindi richieste API e log di esecuzione script appaiono nella stessa sequenza temporale.

Formato di una riga di log

{"ts":"2026-05-22T14:03:21.421","tag":"API","reqId":"A3F1B2C7","client":"127.0.0.1","method":"GET","uri":"/","op":"start","durMs":3,"params":{"operation":"start","currentLine":"42"},"response":"started"}

Campi presenti in ogni entry

Campo	Descrizione
ts	Timestamp locale ISO 8601 con millisecondi
tag	Sempre `"API"` — distingue le righe API dagli altri log di sistema
reqId	ID a 8 caratteri (primi 8 hex di un GUID) per correlare entry/exit della stessa request
client	IP del chiamante (`AContext.Binding.PeerIP`)
method	Metodo HTTP (`GET`, `POST`)
uri	URI richiesto (sempre `/` per JuliuS, parametri in query string)
op	Operazione identificata: valore di `?operation=` se presente, altrimenti dedotta da `loadscript`, `globalv`, `navigate`, `evaljs`, `getresult`, `findelement`, `devtools`
durMs	Durata della request in millisecondi (dal ricevimento alla composizione della risposta)
params	Oggetto con tutti i parametri query string e form
bodyBytes	(solo se `logBodies=true` e c'è body POST) — dimensione in byte del body
bodyPreview	(solo se `logBodies=true`) — anteprima testuale del body fino a `maxBodyPreview` caratteri, oppure `<REDACTED>` per operazioni sensibili
response	Anteprima della risposta troncata a `maxBodyPreview` caratteri, oppure `<binary>` se il content-type è image/*

Operazioni sensibili (mascherate se `maskSensitive=true`)

Il body delle seguenti operazioni viene sostituito con <REDACTED> per evitare di scrivere su disco credenziali o dati personali contenuti nelle variabili globali, e per non far esplodere il log con script di grandi dimensioni:

POST /?operation=readscritpfromstream — body con sorgente script (potenzialmente MB)
POST /?globalv=rewrite — body con variabili globali (potenzialmente credenziali)

Configurazione

I quattro toggle sono in Settings.Data.ApiLog e modificabili a caldo tramite setapilog senza riavviare il server:

Parametro	Tipo	Default	Descrizione
Enabled	boolean	true	Master switch: se false, nessuna richiesta viene loggata
LogBodies	boolean	false	Se true, include `bodyPreview` e `bodyBytes` nelle entry
MaskSensitive	boolean	true	Se true, redact dei body di operazioni sensibili anche con `LogBodies=true`
MaxBodyPreview	integer	500	Caratteri massimi per `bodyPreview` e `response`

Lettura del log: Le entry sono in formato JSON Lines, perfettamente compatibile con jq, grep, importazione in Splunk/ELK. Esempio rapido per filtrare gli errori:
grep '"response":"ERROR' app.log | jq -r '[.ts,.op,.response] | @tsv'

Status del log

GET/?operation=getapilogstatusRitorna lo stato corrente del log API

Restituisce un oggetto JSON con la configurazione corrente del log API e il percorso del file di log fisico in uso. Endpoint puramente di lettura, non modifica nulla. Utile per verificare a runtime quale file viene scritto e quali sono i flag attivi.

sync

Header risposta	Valore
Content-Type	`application/json; charset=utf-8`

Struttura risposta

{
  "enabled": true,
  "logBodies": false,
  "maskSensitive": true,
  "maxBodyPreview": 500,
  "logFile": "C:\\JuliuS\\JuliuS.log",
  "thLogActive": true
}

GET /?operation=getapilogstatus HTTP/1.1

Toggle a caldo

GET/?operation=setapilog[&enabled=...&logbodies=...&masksensitive=...&maxpreview=...]Modifica a runtime i flag del log API

Modifica uno o più toggle del log API senza dover riavviare il server. I parametri sono tutti opzionali e combinabili: i parametri non specificati restano invariati. Le modifiche sono effettive immediatamente sulla request successiva ma non vengono persistite sul file di configurazione: al prossimo riavvio del server tornano ai default. La risposta è la stessa di getapilogstatus e riflette lo stato dopo l'applicazione delle modifiche.

sync

Parametro	Valori	Descrizione
enabled	`true` / `false` / `1` / `0`	Master switch del log
logbodies	`true` / `false`	Logga body POST e response
masksensitive	`true` / `false`	Redact dei body di operazioni sensibili
maxpreview	intero > 0	Caratteri massimi nelle anteprime

Esempi

# Disabilita temporaneamente il log durante un load test
GET /?operation=setapilog&enabled=false

# Modalità debug: log completi con body e niente masking
GET /?operation=setapilog&logbodies=true&masksensitive=false&maxpreview=2000

# Torna ai default produzione
GET /?operation=setapilog&enabled=true&logbodies=false&masksensitive=true&maxpreview=500

Non persistente: le modifiche vivono solo per la sessione corrente del server. Per cambiamenti permanenti, modificare i default in uSettings.pas → TApiLogSettings.Initialize.

Leggi ultime righe

GET/?operation=getapilog[&lines={N}]Ritorna le ultime N righe del file di log

Forza un flush a disco di tutto il buffer in coda nel thread writer di thLog, poi legge il file di log e restituisce le ultime N righe nel body della risposta come testo plain UTF-8. Il default è 200 righe, il limite massimo è 5000. Utile per debug remoto senza dover accedere al filesystem della macchina JuliuS, o per integrazione con cruscotti di monitoring.

sync

Parametro	Default	Descrizione
lines	200	Numero di righe finali da restituire. Valori < 1 → 1, valori > 5000 → 5000.

Header risposta	Valore
Content-Type	`text/plain; charset=utf-8`

200Le ultime N righe del log separate da CRLF

200Body vuoto — file di log non ancora creato

200*ERROR: thLog non attivo — il logger globale non è inizializzato

200*ERROR: ... — file in uso esclusivo dal writer o I/O error

# Ultime 200 righe (default)
GET /?operation=getapilog HTTP/1.1

# Ultime 50 righe
GET /?operation=getapilog&lines=50

# Pipe a jq per filtrare gli errori da remoto
curl "http://127.0.0.1:8080/?operation=getapilog&lines=1000" | grep '"response":"ERROR' | jq .

Performance: per file di log molto grandi (vicini al limite di 100 MB) la lettura carica l'intero file in memoria e poi taglia le ultime N righe. È una scelta semplice e thread-safe; per scenari ad altissima frequenza considerare la lettura diretta dal filesystem.

Flush a disco

GET/?operation=flushapilogForza il flush del buffer di log a disco

Chiama thLog.FlushLog per scaricare immediatamente su disco tutte le righe ancora bufferizzate nel thread writer di synaLog. In condizioni normali il writer fa il flush automaticamente ogni 200 righe (se FdoFlush=true) o all'arresto del thread; questo endpoint serve quando si vuole garantire che il file su disco contenga tutto fino a quel momento, ad esempio prima di copiarlo via per analisi.

sync

200flushed

200*ERROR: thLog non attivo

200*ERROR: ... — eccezione durante il flush

GET /?operation=flushapilog HTTP/1.1

Forza rotazione

GET/?operation=rotateapilogForza la rotazione del file di log

Chiama thLog.RequestRotate per innescare la rotazione manuale del file: thLog chiude il file corrente, lo rinomina con un nome unico e lo zippa in background tramite txtUtils.ZipAndDeleteAsync, poi apre un file nuovo e pulito. L'operazione è asincrona: il flag di rotazione viene impostato e processato dal thread Execute di thLog alla prossima iterazione, tipicamente entro un secondo. Indipendentemente da questa chiamata, la rotazione automatica per dimensione (default 100 MB, check ogni 30 secondi) resta sempre attiva.

async

200rotate_requested — flag impostato, il thread writer effettuerà la rotazione

200*ERROR: thLog non attivo

GET /?operation=rotateapilog HTTP/1.1

Uso tipico: all'avvio di una sessione di test estesa, chiamare rotateapilog per partire con un file fresco, eseguire i test, poi flushapilog e raccogliere il file di log "pulito" che contiene solo quella sessione.

Introduzione

Base URL & Autenticazione

Carica script da file

Carica script da stream

Leggi script corrente

Leggi linea corrente

Imposta linea di partenza

Avvia esecuzione

Ferma esecuzione

Reset cursore

Status

Get Result (funzione fissa)

Get Result (funzione variabile)

Navigate

Click (CEF)

Snapshot (CEF)

Restart Chromium

Risposta

Esempio

Delete Chromium Cache

Confronto con restartchromium

Risposta

Esempio

Get DOM

Get Form Fields

Get Page Info

Get Console Log

EvalJS (via API)

Find Element

Get Frame List

Get Frame Source

Wait Page Load

DevTools Protocol

Start Network Log

Get Network Log

OS Mouse — Move

OS Mouse — Click sinistro

OS Mouse — Move + Click

OS Mouse — Click destro

OS Mouse — Get posizione

OS Tastiera — Key Press

OS Tastiera — Shortcut tasti comuni

OS Tastiera — Arrow Keys

OS Tastiera — Key Combo

OS Screenshot (PNG)

OS Screenshot (JPG)

Get Browser Window Info

Struttura risposta JSON

Browser Move Click

Rewrite Variabili Globali

API Logging — Panoramica

Formato di una riga di log

Campi presenti in ogni entry

Operazioni sensibili (mascherate se maskSensitive=true)

Configurazione

Status del log

Struttura risposta

Toggle a caldo

Esempi

Leggi ultime righe

Flush a disco

Forza rotazione

Operazioni sensibili (mascherate se `maskSensitive=true`)