Değişkenler ve veri tipleri

Değişkenler, bir görevin üzerinde çalıştığı verileri tutar: bir sayfadan okunan metin, toplanacak bir sayı, bir dosya listesi, bir veritabanından gelen tablo, üzerinde işlem yapılacak bir pencere veya tarayıcı sayfası. Bu sayfa veri tiplerini, değişkenlerin nasıl tanımlanıp doldurulacağını ve görevlerin birbirine nasıl değer aktardığını listeler.

#Değişken tanımlama

Bir değişkeni set ile, --type değerini ve isterseniz bir başlangıç değeri vererek tanımlayın:

set --name:customer --type:string --value:"ACME Ltd"
set --name:total --type:number --value:0
set --name:today --type:datetime --value:now

Düzenleyicide VARIABLES sekmesindeki Add variable seçeneğini veya Insert variable penceresindeki (F2) New variable seçeneğini kullanın: Botream set komutunu sizin için görevin en üstüne ekler.

• Adlar bir harf veya _ ile başlar ve yalnızca harf, rakam ve _ içerir (orderId, _temp2). Görev çalışırken adlar büyük/küçük harfe duyarlı değildir.
• --type olmadan set, zaten var olan bir değişkeni değiştirir ve türünü korur: set --name:total --value:42.
• Birçok komut --output ile, döngüler ise --variable ile değişkenleri kendileri oluşturur. Bunları önceden tanımlamanız gerekmez.

Bir değişkeni adını dolar işaretleri arasına yazarak okuyun: $customer$. Alanlar ($order.Total$), öğeler ($items[0]$), .Count ve .Length için Değerlerde değişkenler bölümüne bakın.

#Veri tipleri

Sabit bir değer yerine, herhangi bir başlangıç değeri başka bir değişkene yapılan tek bir başvuru olabilir (--value:$other$); görev çalışırken tanımlanan tipe dönüştürülür. Düzenleyici sabit değerleri siz yazarken denetler: set --type:number --value:abc bir hatadır.

#Metin, sayılar, mantıksal değerler ve tarihler

set --name:greeting --type:string --value:"Hello $customer$"
set --name:rate --type:number --value:0.18
set --name:isTest --type:boolean --value:true
set --name:deadline --type:datetime --value:"2026-12-31 17:00"

Sayılarda ondalık ayırıcı olarak nokta kullanılır. Metni dönüştürmek için string komutunu kullanın: --action:tonumber, --action:todatetime --format:dd.MM.yyyy, --action:toboolean; number --action:tostring ve datetime --action:format değerleri yeniden metne çevirir.

#Listeler

set --name:countries --type:list --value:["DE", "AT", "CH"]
list --action:add --name:countries --value:FR
log --message:"First: $countries[0]$, total: $countries.Count$"
loop --type:list --list:$countries$ --variable:country
    log --message:$country$
endloop

JSON sabit değerleri, içlerinde boşluk olsa bile değerin tamamı tırnak içine alınmadan yazılır. İçlerinde başvurular yer alabilir: ["$first$", "b"].

#Sözlükler ve kayıtlar

Her ikisi de bir JSON nesnesi olarak yazılır ve nokta ile okunur: $config.env$, $person.Name$. Bir sözlük serbest bir anahtar kümesidir; bir kayıt ise Excel satırları, veri tabloları, dosyalar ve kuyruk öğeleri üzerindeki döngülerin size verdiği gibi adlandırılmış alanlardan oluşan tek bir satırdır. Alan adları büyük/küçük harf gözetilmeden eşleştirilir.

set --name:config --type:dictionary --value:{"env": "prod", "retries": 3}
set --name:person --type:record --value:{"Name": "Ali", "Age": 30}
dictionary --action:addkey --name:config --key:region --value:eu-west
log --message:"$person.Name$ ($person.Age$) on $config.env$"

Boşluk veya başka karakterler içeren bir anahtar noktadan sonra yazılamaz; onu getvalue ile okuyun:

dictionary --action:getvalue --name:config --key:"Order No" --output:orderNo

#Veri tabloları

Bir veri tablosunun adlandırılmış sütunları ve satırları vardır. Onu sütunlar ve satırlar olarak ya da aynı anahtarlara sahip nesnelerden oluşan bir liste olarak yazın:

set --name:people --type:datatable --value:{"columns": ["Name", "Age"], "rows": [["Ali", 30], ["Veli", 25]]}
set --name:prices --type:datatable --value:[{"Item": "Pen", "Price": 1.5}, {"Item": "Pad", "Price": 3}]

Sütun adları benzersiz olmalıdır. Düzenleyicide Create table, tipli sütunlar ve Paste from Excel seçeneği içeren bir tablo açar.

• $people[0].Name$ bir hücreyi, $people[1]$ bir satırı (bir kayıt), $people.Count$ satır sayısını okur.
• loop --type:datatable --table:$people$ --variable:row her satır için bir kez çalışır; hücreleri $row.Name$ olarak okuyun.
• capture --action:gettable, database --action:query, csv --action:read, excel --action:readrange ve json --action:todatatable veri tablosu döndürür.
• Bunları datatable eylemleriyle birleştirin, gruplayın, arayın ve toplayın; bkz. Veri tablolarını birleştirme, gruplama ve arama.

#Dosyalar

Bir file değişkeni bir yol tutar. loop --type:eachfile her dosyayı Name, NameWithoutExtension, Extension, Path, Directory, Size, CreatedDate ve ModifiedDate alanlarına sahip bir kayıt olarak verir; loop --type:eachfolder ise Name, Path, Parent, FileCount ve CreatedDate verir.

set --name:report --type:file --value:C:\Reports\daily.xlsx
loop --type:eachfile --folder:C:\In --filter:*.pdf --variable:pdf
    log --message:"$pdf.Name$ is $pdf.Size$ bytes"
endloop

#Pencereler

Bir pencere değişkeni, komutların hangi masaüstü penceresi üzerinde işlem yapacağını tanımlar. Onu bir başlık ve/veya program yolu ile tanımlayın; her ikisinde de * bir joker karakterdir:

set --name:notepad --type:window --path:"C:\Windows\notepad.exe" --title:"*Notepad*"
sendkeys --window:$notepad$ --keys:"Hello[ENTER]"

Ya da bir programı başlatın veya ona bağlanın ve pencereyi alın:

window --action:open --path:C:\Apps\erp.exe --output:erp
window --action:attach --title:"*Invoice*" --output:invoiceWindow
window --action:getproperty --window:$erp$ --property:Title --output:erpTitle

window --action:getproperty; Title, Path, ProcessId, X, Y, Width, Height, IsMinimized, IsMaximized ve Handle değerlerini okur. Düzenleyicide bir pencere alanının yanındaki New, ajan makinesinde açık olan pencerelerden birinden bir pencere değişkeni oluşturur. Bkz. Masaüstü otomasyonu.

#Tarayıcı sayfaları

browser --action:open --output:shop bir tarayıcı açar ve sayfasını $shop$ içine koyar; ardından her web komutu --browser:$shop$ ile onu hedefler. --browser olmadan bir web komutu en son kullanılan sayfayı kullanır.

browser --action:open --url:"https://shop.example.com" --output:shop
capture --browser:$shop$ --action:click --dompath:"#login"

Uyarı: Tek başına set --type:browser hiçbir sayfa tutmaz. Bir --browser:$page$ değişkeni hiçbir zaman browser --action:open --output ile doldurulmadığında düzenleyici uyarır. Bkz. Web otomasyonu.

#Kimlik bilgileri

Bir kimlik bilgisi değişkeni, set komutu çalıştığında bir kasadan kullanıcı adı ve parola okur:

set --name:login --type:credential --vault:Production --credential:PortalUser
capture --browser:$portal$ --action:settext --dompath:"#user" --value:$login.Username$
capture --browser:$portal$ --action:settext --dompath:"#password" --value:$login.Password$

Parola asla günlüklere yazılmaz: görüneceği her yerde (günlük satırları, hata mesajları, bir catch'in hata değişkeni, görev çıktıları) *** ile değiştirilir. --credential parametresi olan komutlar (örneğin mail ve restapi) değişkenin tamamını alır: --credential:$login$; mail ayrıca kasayı ve kimlik bilgisinin adını doğrudan alır (--vault:"Mail" --credential:"Robot mailbox"). Bir çalıştırmanın bir kasayı okuyup okuyamayacağı, onu başlatan kullanıcıya bağlıdır; bkz. Kasalar.

#Komut çıktıları

Bir değer üreten komutlar onu --output ile adlandırılan değişkene yazar. Tip, komuta bağlıdır:

restapi --action:get --url:"https://api.example.com/orders/$id$" --output:response
if --condition:$response.IsSuccess$
    log --message:"Status $response.StatusCode$ in $response.ElapsedMs$ ms"
endif

Her komutun çıktısı için komut başvurusuna bakın.

#Değişkenlerle çalışma: string, number, list…

Her değişken tipinin yalnızca ona uyan eylemleri içeren kendi komutu vardır: string, number, boolean, list, dictionary (kayıtlar için de), datetime ve datatable. --name üzerinde çalışılan değişkendir; düzenleyicide listesi yalnızca o tipteki değişkenleri gösterir. --output ile sonuç başka bir değişkene gider; olmadan değişken yerinde güncellenir. Başka bir şey döndüren eylemler (bir uzunluk, doğru/yanlış, bir öğe) --output ister.

number --action:increment --name:count
number --action:increment --name:count --by:5
string --action:uppercase --name:code
string --action:replace --name:text --old:";" --new:"," --output:cleaned
string --action:split --name:line --separator:";" --output:parts
datetime --action:adddays --name:today --value:-1 --output:yesterday
datatable --action:filter --name:orders --column:Total --operator:">" --value:1000 --output:bigOrders

Komut başvurusu her eylemin parametrelerini listeler. Eski, her tipi tek komutta toplayan variable komutuyla (variable --action:uppercase …) yazılmış görevler değişmeden çalışmaya devam eder; yeni bloklar yukarıdaki komutları kullanır.

#Veri tablolarını birleştirme, gruplama ve arama

Raporlar ve mutabakatlar — bölge bazında satışlar, ödemelerle eşleştirilen faturalar, yöneticisi olmayan çalışanlar — birkaç datatable bloğundan ibarettir. Her biri yeni bir veri tablosu (ya da bir değer) verir; --output olmadan tablonun yerini alır.

datatable --action:join --name:orders --with:$customers$ --on:"CustomerId=Id" --type:left --output:ordersWithCustomers
datatable --action:distinct --name:applicants --columns:"Email" --output:uniqueApplicants
datatable --action:groupby --name:sales --columns:"Region" --aggregates:"Total=sum(Amount), Orders=count(), Average=avg(Amount)" --output:summary
datatable --action:addcolumn --name:lines --column:Total --value:=$row.Price$ * $row.Qty$
datatable --action:lookup --name:rates --column:Currency --value:$invoice.Currency$ --return:Rate --default:1 --output:rate
datatable --action:aggregate --name:sales --function:sum --column:Amount --output:totalSales

Değerler nasıl karşılaştırılır: sütun adlarında büyük/küçük harf fark etmez; sayılar, biri metin olarak yazılmış olsa da sayılarla eşleşir (1 ve "1.0"), ancak 007 gibi başında sıfır olan kodlar metin olarak kalır; metinlerde büyük/küçük harf ve baştaki/sondaki boşluklar dikkate alınmaz; birleştirmede boş değerler hiçbir zaman eşleşmez. Hesaplamalar boş hücreleri atlar; hiç değer yoksa sum ve count 0, avg, min ve max boş olur.

İpucu: addcolumn --value içindeki $row$, hesaplanmakta olan satırdır ve tablonun sütunları alanlarıdır (formül oluşturucu bunları listeler). Görevin row adlı kendi değişkeni varsa değerini korur.

Düzenleyicide sütun alanları, tablonun bilinen sütunlarını listeler — Create table, Veri çıkarma sihirbazı ya da daha önceki bir join veya group by'dan — ve başka bir ad da yazılabilir. Bu eylemler bu sürümden bir agent gerektirir; eski bir agent'a görev, onu güncellemenizi isteyen bir mesajla reddedilir.

#Excel çalışma kitapları

excel komutu bir çalışma kitabını bir oturum adıyla açar; sonraki her excel bloğu (ve loop --type:excelrows) bu adı kullanır:

excel --action:open --file:"C:\Reports\Sales.xlsx" --session:Sales
excel --action:readrange --session:Sales --output:sales
excel --action:writerange --session:Sales --range:"H1" --data:$summary$
excel --action:close --session:Sales --save:true

readrange, sütunları ilk satır olan bir veri tablosu verir (--header:false ile satırlardan oluşan bir liste). writerange bir veri tablosunu sütun adları ve satırlarıyla yazar; böylece readrange → datatable blokları → writerange bir sayfayı baştan sona işler.

Bir çalışma kitabını açmanın iki yolu vardır (open üzerinde --engine):

excel --action:open --file:"C:\Reports\Sales.xlsm" --session:Sales --engine:excel --visible:false
excel --action:refreshall --session:Sales
excel --action:runmacro --session:Sales --macro:"Module1.FormatReport" --args:"2026, 10"
excel --action:autofit --session:Sales --range:"A:F"
excel --action:exportpdf --session:Sales --file:"C:\Reports\Sales.pdf" --scope:workbook
excel --action:close --session:Sales --save:true

• runmacro çalışma kitabının bir VBA makrosunu çalıştırır (Module1.FormatReport ya da yalnızca FormatReport); --args ona değer geçirir (bir liste değişkeni ya da virgülle ayrılmış değerler) ve --output bir Function'ın döndürdüğünü alır.
• refreshall her veri bağlantısını, sorguyu ve pivot tabloyu yeniler ve Excel bitirene kadar bekler.
• exportpdf etkin sayfayı (--scope:sheet, varsayılan) ya da tüm sayfaları (--scope:workbook) PDF olarak kaydeder.
• autofit sütunları içerikleri kadar genişletir.

Botream her oturum için kendi Excel'ini başlatır, Excel'in sorularını ("Bağlantılar güncellensin mi?" gibi) kapatır ve onu her zaman yeniden kapatır — close sonrasında, görev bittiğinde ve başarısız olduğunda — böylece arka planda çalışan bir Excel kalmaz. Değişiklikler yalnızca save, saveas ya da close --save:true ile kaydedilir.

Not: excel motoru, agent makinesinde Microsoft Excel'in kurulu olmasını ve agent'ın oturum açılmış bir Windows oturumunda çalışmasını gerektirir. --engine:excel içeren bir görev bu sürümden bir agent gerektirir. Makrolar yalnızca Excel dosya için onlara izin verdiğinde çalışır (Güven Merkezi).

#Görev girdileri ve çıktıları

Bir görev, kendisini çağırandan değer alabilir ve ona değer geri verebilir. Bunları görevin en üstünde input ve output ile tanımlayın:

input --name:invoiceNo --type:string
input --name:maxRetries --type:number --default:3 --required:false
output --name:bookingNo --type:string

• --required (varsayılan true): çağıran bir değer vermediğinde ve --default yoksa çalıştırma "Required input … was not provided" hatasıyla başarısız olur.
• --default, set --value gibi yazılır.
• Bir çıktıya diğer değişkenler gibi değer verin; örneğin set --name:bookingNo --value:$result.Number$.

Görevi düzenleyiciden başlattığınızda, çalıştırma penceresi girdileri INPUTS altında varsayılan değerleriyle doldurulmuş olarak ister.

#Başka bir görevi çağırma

runtask bir görevi adıyla (veya birden fazla klasörde bu adda görev olduğunda Finance/Invoices/Import gibi klasör yoluyla) çağırır. Girdileri --<input>:value olarak aktarın, çıktıları --<output>To:variable olarak alın:

runtask --name:BookInvoice --invoiceNo:$row.InvoiceNo$ --maxRetries:5 --bookingNoTo:booking
log --message:"Booked as $booking$"

Çağrılan görev kendi değişkenleriyle çalışır; yalnızca eşlenen çıktılar geri gelir. Özellikler panelinde Choose task görevi seçer, Mappings ise girdilerini ve çıktılarını listeler; Auto map boş eşlemeleri aynı adlı değişkenlerden doldurur. Çağrılan görevdeki bir hata, türü korunarak runtask komutunu başarısız kılar (bkz. Hata yönetimi).

#Sistem değişkenleri

Her görevde, tanımlamaya gerek kalmadan yerleşik $System$ bulunur; diğer RPA araçlarındaki sistem değişkenleri gibi. Alanları kullanıldıkları anda okunur, bu yüzden $System.Date$ her zaman o anki zamandır.

log --message:"Started on $System.Machine$ as $System.UserName$ at $System.Hour$:$System.Minute$"
file --action:copy --source:C:\In\report.xlsx --destination:"$System.DesktopFolder$\report-$System.Year$-$System.Month$.xlsx"

$System$ salt okunurdur ve hiçbir değişkene System adı verilemez. Düzenleyici, $System. yazıldıktan sonra alanlarını önerir.

#Global değerler

Birçok görevin paylaştığı değerler — bir klasör, bir web adresi, bir limit, bir alıcı listesi — Global values sayfasında (Manage global values yetkisi, varsayılan olarak Developer) bir kez tutulur ve herhangi bir görevde $Global.Ad$ olarak okunur:

loop --type:eachfile --folder:$Global.InvoiceFolder$ --filter:*.pdf --variable:file
    if --condition:"$file.Size$ > $Global.MaxFileSize$"
        mail --action:send --to:$Global.SupportMail$ --subject:"Invoice too large: $file.Name$"
    endif
endloop

• Her değerin bir adı, bir türü (string, number, boolean, datetime, list, dictionary, record veya data table), değeri ve açıklaması vardır. Değer, bir değişkenin başlangıç değeriyle aynı düzenleyicilerle girilir.
• Bir çalıştırma, başladığı andaki değerleri alır; bir değişiklik, hiçbir görevi düzenlemeden veya yayınlamadan sonraki çalıştırmalarda geçerli olur.
• $Global$ görev içinde salt okunurdur (set --name:Global reddedilir) ve hiçbir değişkene Global adı verilemez. Düzenleyici, $Global. yazıldıktan sonra adları önerir.
• Global değerleri oluşturmak, değiştirmek ve silmek denetim kaydına yazılır.

Not: Global değerler gizli değildir: Manage global values yetkisine sahip herkes bunları görür ve günlüklerde görünebilirler. Parolaları ve anahtarları kasalarda tutun.

#catch'in hatası

Yerleşik bir hata değişkeni yoktur: bir catch, hatayı alacak değişkene ad verir (ör. catch --error:err); ardından $err.Message$, $err.Type$, $err.CommandLine$, $err.CommandType$ ve $err.Timestamp$ hatayı tanımlar. Bkz. Hata yönetimi ve yeniden denemeler.

#Değişkenleri inceleme

• Hata ayıklama sırasında, çalıştırma durduğunda VARIABLES bölmesi tüm değişkenleri gösterir.
• Bir çalıştırma başarısız olduğunda, çalıştırma sayfası hata anındaki değişkenleri gösterir. Her ikisinde de parolalar maskelenir ve uzun değerler kısaltılır.