Görev dili (DSL)

Her Botream görevi metin olarak okunabilir ve yazılabilir: her satırda bir komut ve --name:value biçiminde parametreler. Düzenleyicinin Code görünümü bu metni gösterir; blok görünümü ise aynı görevin kartlar halinde çizilmiş halidir.

input --name:folder --type:string --default:"C:\Invoices"
set --name:count --type:number --value:0
loop --type:eachfile --folder:$folder$ --filter:*.pdf --variable:file
    log --message:"Processing $file.Name$"
    number --action:increment --name:count
endloop
log --message:"$count$ invoices processed"

Not: Metin, görevin bir görünümüdür. Botream görevi yapılandırılmış komutlar olarak saklar ve ajanlar bunları çalıştırır; metni ve blokları kendiniz eşitlemek zorunda kalmazsınız.

#Satırlar ve komutlar

• Her satırda bir komut bulunur: önce komut adı, ardından parametreleri.
• Boş satırlar ve girintiler yok sayılır. Düzenleyici blok içeriklerini dört boşlukla girintiler.
• Komut adları büyük/küçük harfe duyarlı değildir (Log, log gibi çalışır). Parametre adları, başvuru belgesindeki gibi küçük harfle yazılır; yalnızca runtask eşlemeleri çağrılan görevin girdi ve çıktı adlarını kullanır (--invoiceNo:$no$, --totalTo:total).
• Bir parametre bir satırda yalnızca bir kez yer alabilir.
• Yorum sözdizimi yoktur: satır başındaki # veya // bir hatadır. Görev çalışırken hiçbir şey yapmayan comment komutunu kullanın:

comment --text:"Log in with the service account"

Tüm komutlar ve parametreler için komut başvurusuna bakın.

#Parametreler

Bir parametre, iki nokta üst üstenin çevresinde boşluk olmadan --name:value biçiminde yazılır.

#Tırnaksız değerler

Tırnaksız bir değer satır sonuna veya bir sonraki --name: ifadesine kadar sürer; sonundaki boşluklar atılır. İçinde boşluklara izin verildiğinden koşullar ve JSON için tırnak gerekmez:

if --condition:$count$ > 5 and $status$ = "ok"
    log --message:Status ok
endif
set --name:items --type:list --value:["a", "b", 3]

--name: ardından boşluk gelmesi boş bir değerdir.

#Tırnaklı değerler

Bir değeri şu durumlarda çift tırnak içine alın:

• boşsa (--text:""),
• bir boşluk veya çift tırnakla başlıyorsa,
• başka bir parametreye benzeyen metin içeriyorsa ( --x:),
• birden fazla satıra yayılıyorsa veya sekme içeriyorsa.

Düzenleyici boşluk içeren değerleri de tırnak içine alır; bu her zaman güvenlidir. Kapanış tırnağından sonra bir boşluk ya da satır sonu gelmelidir.

Tırnak içinde ters tırnak (`) bir kaçış karakteri başlatır:

Başka herhangi bir karakterin izlediği ters tırnak, ters tırnak olarak kalır. Ters eğik çizgiler her zaman olduğu gibi yorumlanır; bu nedenle Windows yolları ve düzenli ifadeler oldukları gibi yazılır. Tırnak dışında hiçbir şey kaçış karakteriyle işlenmez.

log --message:"Line one`nLine two"
messagebox --message:"Click `"Continue`" when you are ready"
file --action:write --path:C:\Out\report.txt --content:$text$

#Bir komutu kapatma

Her komut --disabled:true taşıyabilir. Komut görevde kalır ancak çalışmaz (devre dışı bir blok içeriğini de kapatır). Düzenleyicide Ctrl+/ tuşunun yazdığı budur.

#Değerlerde değişkenler

Değişkenler dolar işaretleri arasında yazılır. $ içeren diğer her şey düz metindir; bu nedenle US$ 5 veya tek başına bir $ olduğu gibi kalır.

• Değişken adları bir harf veya _ ile başlar ve harf, rakam ve _ içerir. Görev çalışırken büyük/küçük harfe duyarlı değildir.
• Noktadan sonraki alan aynı türden bir ad olmalıdır (boşluksuz); alan adları büyük/küçük harf gözetilmeden eşleştirilir.
• Bir değer tam olarak tek bir başvuru olduğunda (--list:$items$), komut değişkenin kendisini türüyle birlikte alır: liste liste olarak, sayı sayı olarak kalır. Başvuru daha uzun bir metnin parçası olduğunda ("Total: $sum$ EUR"), değeri metnin içine yerleştirilir.
• Yazılacak bir değişkeni adlandıran parametreler (--output, set --name, döngü --variable) yalın adı alır: --output:$total$ değil, --output:total.

Veri tipleri ve sabit değerleri için Değişkenler ve veri tipleri sayfasına bakın.

#Değerlerde formüller

= ile başlayan bir değer bir formüldür ve Excel'deki gibi komut çalıştığında hesaplanır: --value:=$price$ * 1.2, --message:="Order " & $id$ & " is ready", --value:=round($total$ * 0.18, 2). Formüller boşluk içerse de tırnak gerektirmez. İşleçler ve fonksiyonlar için Formüller sayfasına bakın. = ile başlayan bir metin yazmak için başına kesme işareti koyun: --message:'=== done === (kesme işareti görev çalışırken kaldırılır).

#Eski $name sözdizimi

Bu sözdiziminden önce yazılmış görevler açık bir biçim kullanıyordu (kapanış $ işareti olmadan $name). Bunlar açıldıklarında otomatik olarak $name$ biçimine yükseltilir; değiştirmeniz gerekmez. Görevde bulunan bir değişken için $name yazarsanız düzenleyici bir uyarı gösterir, çünkü kapanış $ olmadan bu düz metindir.

#Önce tanımlar gelir

input ve output görevin parametrelerini tanımlar (bkz. görev girdileri ve çıktıları). Görevin en üstünde yer almalıdırlar; yalnızca comment satırları bunlardan önce gelebilir. Bir ad yalnızca bir kez tanımlanabilir.

comment --text:"Books one invoice"
input --name:invoiceNo --type:string
input --name:retries --type:number --default:3 --required:false
output --name:bookingNo --type:string

#Bloklar

Blok komutları başka komutları kapsar ve kendi bitiş satırlarıyla sona erer. Bitiş satırları parametre almaz.

#if / elseif / else

if --condition:$total$ > 1000
    log --message:"Needs approval"
elseif --condition:$total$ = 0
    throw --message:"Invoice $no$ has no total"
else
    log --message:"Booking directly"
endif

if ve elseif, bir ifade yerine --type ile tipli bir koşul alabilir:

if --type:string --left:$subject$ --operator:contains --right:invoice --ignorecase:true
    log --message:"Invoice mail"
endif
if --type:fileexists --path:C:\In\*.xlsx
    log --message:"New workbooks are waiting"
endif

Element ve resim koşulları ekranda ne olduğunu tek blokta denetler; capture --action:exists ile bir değişkene okuyup if --type:boolean ile sınamaya gerek kalmaz. Düzenleyicide Capture düğmesi elementi (Object properties tablosuyla birlikte), Capture picture da resmi, capture, desktop ve image komutlarındaki gibi doldurur. --timeout, karar vermeden önce elementin ya da resmin görünmesi (…exists) veya kaybolması (…notexists) için en fazla o kadar saniye bekler; verilmezse ekran bir kez denetlenir. Bulunamayan bir element, pencere ya da resim görevi asla durdurmaz: koşul yalnızca yanlış olur (not biçimlerinde doğru).

if --type:elementexists --dompath:"//div[@class='error']" --timeout:3
    capture --action:gettext --dompath:"//div[@class='error']" --output:problem
    throw --type:business --message:"The portal refused the invoice: $problem$"
elseif --type:desktopelementexists --window:$erp$ --by:name --target:"Saved"
    log --message:"Saved in the ERP"
elseif --type:imagenotexists --image:"C:\Pictures\spinner.png" --window:$citrix$ --timeout:30
    log --message:"The remote screen is ready"
endif

Eski ajanlar (bu koşullar gelmeden önce kurulanlar) da bunları çalıştırır: sunucu her koşulu gizli bir değişkene yazan bir wait ve ardından if --type:boolean olarak gönderir (yanıt hayır olduğunda günlükte bir "Gave up" uyarısı görünür). Yalnızca --timeout verilmiş imagenotexists güncel ajanı gerektirir.

#switch / case / default

switch, bir değere göre birkaç bölümden birini çalıştırır: --value değeri switch'in --value değerine eşit olan ilk case çalışır; hiçbiri eşit değilse (varsa) default bölümü çalışır. Değerler metin olarak karşılaştırılır; --ignorecase:true ile Approved ve APPROVED aynı sayılır. Bir değişken üzerindeki switch'te sayı olan bir case sayı olarak karşılaştırılır, yani 1, 1.0 ile de eşleşir.

switch --value:$status$ --ignorecase:true
case --value:Approved
    log --message:"Book the invoice"
case --value:Rejected
    log --message:"Send it back"
default
    log --message:"Unknown status $status$" --level:warning
endswitch

Komutlar bölümlerin içine yazılır: bir switch en az bir case ister ve default en sonda gelir. Düzenleyicide bölümleri bloğun özelliklerindeki ya da End satırındaki Case ekle ve Default düğmeleriyle ekleyin; değerini yazmak için bir case seçin. Switch'i her ajan çalıştırır: sunucu onu if / elseif / else olarak gönderir ve günlükle hata ayıklayıcı için switch'in ve case'lerinin satır numaralarını korur.

#loop

--type, döngünün neyin üzerinden geçeceğini seçer: range, times (belirli sayıda tur), list, datatable, condition (while), excelrows, eachfile, eachfolder, queue veya mail (bir posta klasörünün her e-postası; bkz. E-postalar üzerinde döngü). times ve condition dışındaki her tür, --variable ile bir döngü değişkeni adlandırır; range döngüsünün değişkeni bir sayıdır.

loop --type:range --from:1 --to:10 --variable:i
    log --message:"Round $i$"
endloop
loop --type:times --times:3
    log --message:"Three times"
endloop
loop --type:list --list:$customers$ --variable:customer
    log --message:"Customer $customer$"
endloop
loop --type:condition --condition:$pending$ > 0
    number --action:decrement --name:pending
endloop

--index (times, list, datatable, excelrows, eachfile, eachfolder, queue ve mail döngüleri), turun sırasını alan bir sayı değişkenini adlandırır; sıra $list[0]$ gibi 0'dan başlar. Koşul döngüsü koşulunu her turdan önce sınar; --check:after ile önce gövdeyi çalıştırır ve koşulu her turdan sonra sınar (do-while: gövde en az bir kez çalışır).

loop --type:list --list:$customers$ --variable:customer --index:i
    log --message:"Customer $i$: $customer$"
endloop
loop --type:condition --condition:"$hasNext$ = true" --check:after
    capture --action:click --dompath:"//a[@rel='next']"
    capture --action:exists --dompath:"//a[@rel='next']" --output:hasNext
endloop

--index ve --check:after güncel ajanı gerektirir: böyle bir görev eski bir ajana gönderilmez (çalıştırma, ajanı güncellemenizi söyleyen bir iletiyle reddedilir).

break en içteki döngüden çıkar, continue bir sonraki turla devam eder. Her ikisine de yalnızca bir döngü içinde izin verilir.

loop --type:datatable --table:$orders$ --variable:row
    if --condition:$row.Status$ = "cancelled"
        continue
    endif
    if --condition:$row.Id$ = $lastId$
        break
    endif
    log --message:"Order $row.Id$"
endloop

#try / catch / finally

browser --action:open --url:"https://portal.example.com" --output:portal
try
    capture --browser:$portal$ --action:click --dompath:"#export"
catch --error:err
    log --message:"Export failed at line $err.CommandLine$: $err.Message$" --level:error
finally
    browser --action:close --browser:$portal$
endtry

Bkz. Hata yönetimi ve yeniden denemeler.

#retry

retry, içindeki komutlardan biri başarısız olduğunda komutları yeniden çalıştırır: toplam en fazla --times deneme (varsayılan 3), denemeler arasında --interval saniye bekleyerek (varsayılan 1). --until verilirse, komutlar çalıştıktan sonra bu koşul yanlış olduğu sürece de yeniden dener. Son denemeden sonra hata olağan şekilde devam eder, böylece çevresindeki bir try onu yakalayabilir.

retry --times:3 --interval:5
    browser --action:open --url:"https://portal.example.com" --output:portal
    capture --browser:$portal$ --action:click --dompath:"#login"
endretry

Bkz. Hata yönetimi ve yeniden denemeler.

#step

step komutları bir açıklama altında gruplar. Nasıl çalıştıklarına dair hiçbir şeyi değiştirmez.

step --description:"Read the input file"
    csv --action:read --file:C:\In\orders.csv --output:orders
endstep

#Koşul ifadeleri

if, elseif ve loop --type:condition komutlarının --condition değeri bir ifadedir:

if --condition:$amount$ >= 100 and ($country$ = "DE" or $country$ = "AT")
    log --message:"EU invoice above limit"
endif
if --condition:$customer$ != null and $customer.Name$ startswith "ACME"
    log --message:"ACME order"
endif
if --condition:!$isApproved$
    log --message:"Not approved yet"
endif

Değerlerin nasıl karşılaştırıldığı:

• İki sayı sayı olarak, iki tarih zamana göre karşılaştırılır; diğer her şey büyük/küçük harfe duyarlı olarak metin şeklinde karşılaştırılır.
• contains, startswith, endswith ve matches büyük/küçük harfe duyarlıdır. Büyük/küçük harfi yok saymak için tipli bir koşul (--type:string --ignorecase:true) kullanın.
• null, eksik bir değere ve boş metne eşittir; yalnızca = ve != ile kullanılabilir.
• Tek başına bir değer; false, 0, boş metin, boş liste veya null olmadığı sürece doğrudur.
• and ve or sonuç belli olur olmaz durur; bu nedenle $x$ != null and $x.Name$ = "a" eksik bir değerin alanını asla okumaz.
• Anahtar sözcükler (and, or, contains…) büyük/küçük harfe duyarlı değildir.
• Bir ifadedeki tırnaklı metinde kaçış karakteri yoktur; içindeki başvurular doldurulur ("INV-$no$").

İpucu: Koşulu tırnaksız yazın. --condition değerinin tamamını tırnak içine alırsanız, içindeki her çift tırnak `" olarak yazılmalıdır.

#Düzenleyici metni nasıl denetler

Code görünümü siz yazarken sorunları işaretler; aynı denetimler blok görünümünde de çalışır:

• bilinmeyen komutlar ve parametreler ("bunu mu demek istediniz" ipucuyla), eksik zorunlu parametreler, yanlış türde değerler (bir sayı, true/false, bir seçenek listesinden biri, bir değişken adı, bir $variable$ başvurusu);
• kapatılmamış bloklar, eşleşmeyen bitiş satırları, yanlış yerdeki bölümler;
• diğer komutların altındaki input/output, döngü dışındaki break/continue, catch bölümü dışında --message içermeyen throw;
• tipine uymayan tipli değerler (örneğin set --type:number --value:abc);
• kapanış $ işareti olmayan $name için ve değişkeni hiçbir zaman browser --action:open ile açılmayan bir --browser:$page$ için uyarılar.

Hata içeren bir görev kaydedilemez. Uyarılar kaydetmeyi engellemez.