Yardımcı (Utilities) node'ları

Bu rehberde: İş akışını insanlara ve diğer sistemlere bağlayan kutuları öğrenirsiniz: onay isteme, ekibe bildirim, rapor kaydetme, webhook gönderme ve başka bir iş akışını çalıştırma.

⏱ 10 dakika

Kısaca#

Yardımcı kutular iş akışının "iletişim" tarafıdır. Onay size sorar, Bildir haber verir, Rapor sonucu Raporlar sayfasına kaydeder, Webhook gönder başka bir sisteme iletir.

Teknik ayrıntılar#

Yardımcı node'lar iş akışını insanlara ve diğer sistemlere bağlar: onay ister, bildirir, rapor kaydeder, webhook gönderir, alt iş akışı çalıştırır.

Request approval (utility.approval)#

Her gelen item için Onaylar (Approvals) sayfasında bir görev oluşturur; run WAITING olur. Onayda item approved, redde rejected handle'ından devam eder.

Çıktı: approved → item (düzenlenmişse güncel) + approval: { id, approvedBy, approvedAt, comment }; rejected → item + rejectionComment. Olaylar: approval.requested, approval.resolved. Yetki: MEMBER ve üstü.

Örnek (şablon): title "Approve {{ $json.platform }} post", description {{ $json.body }}, allowEdit true → approved → agent.socialPublisher; rejected → utility.notify.

Örnek – yalnızca riskli içerik onaya: logic.if ({{ $json.contentType === "promotional" }}) → true → utility.approval; false ve approved → logic.merge (append) → yayın.

Ayrıntı: Onaylar ve insan denetimi.

Notify team (utility.notify)#

Proje üyelerine uygulama içi bildirim gönderir; isteğe bağlı e-posta, Slack, Telegram.

Çıktı: item + notificationId. Alıcılar: projenin üyeleri (organizasyon üyeliği + proje erişimi); e-posta platform SMTP ayarıyla gönderilir. Tek çalıştırmada aynı başlıkla 20'den fazla bildirim birleştirilir ("ve 17 tane daha").

Örnek: trigger.event (lead.qualified, filter {{ $json.score >= 85 }}) → utility.notify (title "Sıcak lead: {{ $json.name }} ({{ $json.company }})", body "Skor {{ $json.score }} – {{ $json.scoreReason }}", channels [inapp, slack], link {{ $json.url }}).

Create report (utility.report)#

Raporlar (Reports) sayfasında görünen bir rapor kaydeder; agent.report.created olayı yayınlanır.

Gelen tüm item'lar için tek rapor oluşturulur (ilk item bağlam olarak kullanılır); item'lar değişmeden geçer, reportId ve reportUrl eklenir. Ajanların kendi raporları ayrıca kaydedilir; bu node ajan olmayan akışlar veya birden fazla node'un çıktısını derlemek içindir.

Örnek (şablon): type LEAD_LIST, title "Leads – week {{ $today }}", contentMarkdown {{ $node["Müşteri Adayı Puanlayıcı"].json.reportMarkdown }}.

Örnek – GA4 özeti:

contentMarkdown: |
  # Haftalık trafik
  | Kanal | Oturum | Dönüşüm |
  |---|---|---|
  {{ $node["Kanal toplamları"].all().map(i => `| ${i.json.channel} | ${i.json.sessions} | ${i.json.conversions} |`).join("\n") }}
metrics: { "sessions": {{ $node["GA4 son 7 gün"].json.totals.sessions }} }

Send webhook (utility.webhookOut)#

Item'ları HMAC imzalı JSON olarak dış URL'ye POST eder.

Gönderilen gövde:

{
  "id": "evt_01J…",
  "type": "workflow.output",
  "organizationId": "org_…",
  "projectId": "prj_…",
  "at": "2026-09-26T09:00:00Z",
  "payload": {
    "workflowId": "wf_…", "runId": "run_…", "nodeName": "Send webhook",
    "items": [ { "json": { … } } ]
  }
}

Başlıklar: Content-Type: application/json, X-AgentFlow-Event, X-AgentFlow-Timestamp (Unix saniye), X-AgentFlow-Signature: sha256=<hex> (entegrasyonun Signing secret alanı ile ham gövdenin HMAC-SHA256'sı; secret boşsa gönderilmez) ve entegrasyondaki Extra headers. 10 saniye zaman aşımı; 2xx dışı yanıt retryable hatadır (node retry politikasıyla tekrar). Çıktı: item + webhook: { status, durationMs }; hatada error handle'ı.

Örnek: agent.leadQualifier → utility.webhookOut (event lead.qualified.batch) → CRM'inizde toplu işleme. Doğrulama kodu: Custom Webhook, Giden webhook'lar.

Run another workflow (utility.runWorkflow)#

Alt iş akışını gelen item'larla başlatır (triggerType: API).

Alt iş akışı ACTIVE veya DRAFT olabilir (ARCHIVED reddedilir); tetikleyicisi ne olursa olsun gelen item'lar tetikleyici çıktısı sayılır. Alt akışın maliyeti üst çalıştırmanın budgetUsd toplamına eklenir. Derinlik en fazla 5; kendini çağırma doğrulamada reddedilir.

Örnek – ortak yayın alt akışı:

Ana akış: agent.contentCreator → utility.runWorkflow (workflowId "Yayın standardı", waitForResult true) → utility.report
Alt akış: trigger.manual → data.set (utm ekle) → utility.approval → agent.socialPublisher

Birden fazla ana akış aynı yayın standardını paylaşır; değişiklik tek yerde yapılır.

No operation (utility.noop)#

Parametresi yoktur; item'ları değiştirmeden geçirir. Kullanım: logic.switch'in default dalını kapatmak, iki dalı görsel olarak birleştirmek (gerçek birleştirme için logic.merge), ileride doldurulacak yer tutucu, logic.if'in kullanılmayan dalını belirgin bırakmak.

İpuçları ve sınırlar#

• utility.approval ve logic.wait (approval) farkı: ilki iki dallı yönlendirme, ikincisi tek dal + approved alanı.
• Bildirim kanallarında email platform SMTP ayarını (SMTP_*) kullanır; tanımlı değilse yalnızca uygulama içi bildirim gider ve logda uyarı görünür.
• utility.report gövdesi 200 KB ile sınırlıdır; büyük veriyi metrics/data yerine CRM veya Sheets'e yazın.
• utility.webhookOut test modunda dry-run'dır (istek gönderilmez, webhook.dryRun: true).
• utility.runWorkflow ile waitForResult: true kullanıyorsanız alt akışta onay node'u olmasın; üst run da WAITING kalır.

Sık sorulan sorular#

Onay kutusu ile Bekle (onay) farkı ne? Onay iki dallıdır (onaylandı / reddedildi). Bekle (onay) tek dal döner ve kararı öğeye yazar.

Bildirim e-postası neden gelmedi? E-posta kanalı platform SMTP ayarını kullanır; tanımlı değilse yalnızca uygulama içi bildirim gider.

Onayı kimler verebilir? Üye ve üstü roller. İzleyici yalnızca görür.

Sonraki adım#

• Onaylar
• Raporlar ve istatistikler
• Custom Webhook