Function API'leri

Function API'leri, workflow instance'ları için sistem seviyesi operasyonlar sağlar. Bu yerleşik fonksiyonlar, client'ların workflow engine dahili yapılarına doğrudan erişmeden instance durumunu sorgulamasına, veri almasına, view bilgisi elde etmesine ve transition şemalarına erişmesine olanak tanır.

Genel Bakış

vNext Runtime platformu, her workflow instance'ı için otomatik olarak kullanılabilir olan dört temel function API'si sağlar:

Fonksiyon	Amaç	Endpoint Deseni
State	Instance durumu için long-polling	`GET /{domain}/workflows/{workflow}/instances/{instance}/functions/state`
Data	Instance verisini alma	`GET /{domain}/workflows/{workflow}/instances/{instance}/functions/data`
View	View içeriğini alma	`GET /{domain}/workflows/{workflow}/instances/{instance}/functions/view`
Schema	Transition schema içeriğini alma	`GET /{domain}/workflows/{workflow}/instances/{instance}/functions/schema`

Not: Kullanıcı tanımlı fonksiyonlar için bkz. Custom Functions.

Bu fonksiyonlar şunları sağlar:

Gerçek zamanlı durum izleme (long-polling)
ETag desteği ile verimli veri alma
Platforma özel içerik ile dinamik view render etme
Transition şemalarına erişim ile dinamik form üretimi

State Fonksiyonu

State fonksiyonu, bir workflow instance'ı hakkında gerçek zamanlı durum bilgisi sağlar. Client'ların instance durum değişikliklerini izlemesi gereken long-polling senaryoları için tasarlanmıştır.

Endpoint

GET /{domain}/workflows/{workflow}/instances/{instance}/functions/state

Parametreler

Parametre	Konum	Tip	Gerekli	Açıklama
`domain`	Path	string	Evet	Domain adı
`workflow`	Path	string	Evet	Workflow key
`instance`	Path	string	Evet	Instance ID or Key

Response

{
  "data": {
    "href": "/core/workflows/oauth-flow/instances/f410f37d-dc4b-4442-af84-e3a4707bd949/functions/data"
  },
  "view": {
    "hasView": true,
    "loadData": true,
    "href": "/core/workflows/oauth-flow/instances/f410f37d-dc4b-4442-af84-e3a4707bd949/functions/view"
  },
  "state": "active",
  "status": "A",
  "activeCorrelations": [
    {
      "href": "/core/workflows/oauth-flow/instances/f410f37d-dc4b-4442-af84-e3a4707bd949/functions/data",
      "correlationId": "corr-123",
      "parentState": "parent-state",
      "subFlowInstanceId": "sub-instance-456",
      "subFlowType": "SubFlow",
      "subFlowDomain": "core",
      "subFlowName": "approval-subflow",
      "subFlowVersion": "1.0.0",
      "isCompleted": false,
      "status": "Running",
      "currentState": "pending-approval"
    }
  ],
  "transitions": [
    {
      "href": "/core/workflows/oauth-flow/instances/f410f37d-dc4b-4442-af84-e3a4707bd949/transitions/approve",
      "name": "approve",
      "view": {
        "hasView": false,
        "loadData": true,
        "href": "/core/workflows/oauth-flow/instances/f410f37d-dc4b-4442-af84-e3a4707bd949/functions/view?transitionKey=approve"
      },
      "schema": {
        "hasSchema": true,
        "href": "/core/workflows/oauth-flow/instances/f410f37d-dc4b-4442-af84-e3a4707bd949/functions/schema?transitionKey=approve"
      }
    },
    {
      "href": "/core/workflows/oauth-flow/instances/f410f37d-dc4b-4442-af84-e3a4707bd949/transitions/reject",
      "name": "reject",
      "view": {
        "hasView": false,
        "loadData": true,
        "href": "/core/workflows/oauth-flow/instances/f410f37d-dc4b-4442-af84-e3a4707bd949/functions/view?transitionKey=reject"
      },
      "schema": {
        "hasSchema": true,
        "href": "/core/workflows/oauth-flow/instances/f410f37d-dc4b-4442-af84-e3a4707bd949/functions/schema?transitionKey=reject"
      }
    }
  ],
  "eTag": "W/\"abc123def456\""
}

Response Alanları

Alan	Tip	Açıklama
`data`	`object`	Instance verisini almak için link
`data.href`	`string`	Data fonksiyon endpoint URL'i
`view`	`object`	Mevcut state için view bilgisi
`view.hasView`	`boolean`	Mevcut state için view olup olmadığı
`view.href`	`string`	View fonksiyon endpoint URL'i
`view.loadData`	`boolean`	View'ın instance data'ya ihtiyaç duyup duymadığı
`state`	`string`	Instance'ın mevcut durumu
`status`	`string`	Instance durum kodu (A=Active, C=Completed, vb.)
`activeCorrelations`	`array`	Aktif sub-flow'lar ve correlation'lar
`transitions`	`array`	Mevcut durumdan kullanılabilir transition'lar (+ role grant'a göre filtrelenir)
`transitions[].view`	`object`	Transition için view bilgisi
`transitions[].view.hasView`	`boolean`	Bu transition için view olup olmadığı
`transitions[].schema`	`object`	Transition için şema linki (tanımlıysa)
`transitions[].schema.hasSchema`	`boolean`	Bu transition için şema olup olmadığı
`transitions[].schema.href`	`string`	transitionKey ile Schema fonksiyon endpoint URL'i
`eTag`	`string`	Cache doğrulama için ETag

Transition'ların role grant'a göre filtrelenmesi

State fonksiyonunun döndürdüğü transitions dizisi transition role grant'larına göre filtrelenir. Yalnızca çağıranın izinli rolü olduğu transition'lar dahil edilir. Roller statik (örn. kimlik sağlayıcınızdan) veya ön tanımlı sistem rolleri $InstanceStarter (instance'ı başlatan actor) ve $PreviousUser (bir önceki transition'ı tetikleyen actor) olabilir. Gereksiz view veya schema istekleri ve 404'leri önlemek için view.hasView ve schema.hasSchema kullanın.

Aktif Correlation'lar

Bir workflow aktif sub-flow'lara veya correlation'lara sahip olduğunda, bunlar response'a dahil edilir:

Alan	Açıklama
`correlationId`	Benzersiz correlation tanımlayıcısı
`parentState`	Parent workflow durumu
`subFlowInstanceId`	Sub-flow instance ID
`subFlowType`	Sub-flow tipi (SubFlow, SubProcess)
`subFlowDomain`	Sub-flow'un domain'i
`subFlowName`	Sub-flow workflow'un adı
`subFlowVersion`	Sub-flow'un versiyonu
`isCompleted`	Sub-flow'un tamamlanıp tamamlanmadığı
`status`	Sub-flow'un mevcut durumu
`currentState`	Sub-flow'un mevcut state'i

Kullanım Alanları

Long-Polling: Client'lar durum değişikliklerini tespit etmek için bu endpoint'i poll edebilir
Durum İzleme: Workflow ilerlemesini izleyen dashboard uygulamaları
Transition Keşfi: Kullanılabilir kullanıcı eylemlerini dinamik olarak keşfetme
Sub-Flow Takibi: Paralel sub-workflow'ların ilerlemesini izleme

Subflow tamamlanma penceresi

Subflow tamamlanması üst instance'a henüz tam yansımamışken State yanıtı, üst instance status bilgisini doğru gösterir; böylece erken Completed gösterimi önlenir.

Telemetry

Runtime genelinde yapılandırılmış loglar daha tutarlıdır; TaskCoordinator yürütmesi span ile izlenir ve ParentInstanceId ile birlikte gözlem arka ucunda ilişkilendirilebilir.

Trace ve logda ParentInstanceId

Trace ve loglarda ParentInstanceId alanı kullanılır; böylece parent instance ile başlatılan veya tetiklenen (subflow, cross-domain) child instance'ların log ve trace'leri parent instance id ile ilişkilendirilerek takip edilebilir.

Örnek İstek

GET /core/workflows/oauth-authentication-workflow/instances/f410f37d-dc4b-4442-af84-e3a4707bd949/functions/state HTTP/1.1
Host: api.example.com
Accept: application/json

Data Fonksiyonu

Data fonksiyonu, bir workflow instance'ının mevcut verisini alır. Verimli veri senkronizasyonu için ETag tabanlı önbellekleme destekler.

Filtreleme: GraphQL-stil sorgular, mantıksal operatörler ve aggregation'lar dahil gelişmiş filtreleme yetenekleri için bkz. Instance Filtreleme Kılavuzu.

Endpoint

GET /{domain}/workflows/{workflow}/instances/{instance}/functions/data

Parametreler

Parametre	Konum	Tip	Gerekli	Açıklama
`domain`	Path	string	Evet	Domain adı
`workflow`	Path	string	Evet	Workflow key
`instance`	Path	string	Evet	Instance ID

Header'lar

Header	Tip	Gerekli	Açıklama
`If-None-Match`	string	Hayır	Koşullu istek için ETag değeri

Response (200 OK)

{
  "data": {
    "userId": "user123",
    "amount": 1000,
    "currency": "TRY",
    "authentication": {
      "success": true,
      "method": "otp",
      "timestamp": "2025-11-11T10:30:00Z"
    },
    "approval": {
      "status": "pending",
      "requestedAt": "2025-11-11T10:35:00Z"
    }
  },
  "eTag": "W/\"xyz789abc123\"",
  "extensions": {
    "userProfile": {
      "name": "Ahmet Yılmaz",
      "email": "ahmet.yilmaz@example.com"
    },
    "accountLimits": {
      "dailyLimit": 5000,
      "remainingLimit": 4000
    }
  }
}

Response (304 Not Modified)

Eğer If-None-Match header'ı mevcut ETag ile eşleşirse, sunucu şunu döndürür:

HTTP/1.1 304 Not Modified
ETag: W/"xyz789abc123"

Body döndürülmez, bu da bant genişliği ve işlem süresinden tasarruf sağlar.

Response Alanları

Alan	Tip	Açıklama
`data`	`object`	Mevcut instance verisi (camelCase özellikler); Master şemada roleGrant kullanıldığında Alan bazlı görünürlük bölümüne bakın
`eTag`	`string`	Cache doğrulama için ETag
`extensions`	`object`	Kayıtlı extension'lardan ek veriler

Instance zarfı ve metadata

GetInstance ve GetInstances yanıtları, instance zarfı bilgisini içerebilir: id, key, flow, domain, flowVersion, etag, tags, metadata (örn. currentState, effectiveState, status, createdAt, modifiedAt, createdBy, modifiedBy, createdByBehalfOf, modifiedByBehalfOf), attributes ve extensions. Böylece veri yüküyle birlikte instance kimliği ve audit bilgisi sunulur.

ETag Desteği

Data fonksiyonu, verimli önbellekleme için ETag pattern'i uygular:

İlk İstek:

GET /core/workflows/payment-flow/instances/123/functions/data

Response:

HTTP/1.1 200 OK
ETag: "W/\"v1\""
Content-Type: application/json

{
  "data": { ... },
  "eTag": "W/\"v1\""
}

Sonraki İstek:

GET /core/workflows/payment-flow/instances/123/functions/data
If-None-Match: "W/\"v1\""

Response (Veri Değişmedi):

HTTP/1.1 304 Not Modified
ETag: "W/\"v1\""

Response (Veri Değişti):

HTTP/1.1 200 OK
ETag: "W/\"v2\""
Content-Type: application/json

{
  "data": { ...güncellenmiş veri... },
  "eTag": "W/\"v2\""
}

Authorization-aware ETag

Data endpoint'leri yetkilendirme kullandığında yanıt çağırana göre değişebilir. itibarıyla ETag stratejisi şöyle ayrılır:

etag — Yanıt (veya istek bağlamı, örn. yetkilendirme) değiştiğinde değişir. Genel yanıt önbelleği ve If-None-Match koşullu istekler için kullanın.
entityETag — Entity verisi değiştiğinde değişir. Gerçek veri değişimini (örn. senkronizasyon veya invalidation) tespit etmek için kullanın.

Her iki değer hem response body'de hem header'larda yer alır:

Body alanı	Response header	Anlamı
`etag`	`ETag`	Yanıt/istek değişimi
`entityEtag`	`X-Entity-ETag`	Entity veri değişimi

Örnek response body:

{
  "etag": "\"Hko5JI4fDcAOOnf-KGFNA7Xo_MpuxcLl1_hg5j2Sua8\"",
  "entityEtag": "\"01KK8Q8N5T6H49T8AENYT6Z6ZQ\""
}

Örnek response header'ları:

ETag: "Hko5JI4fDcAOOnf-KGFNA7Xo_MpuxcLl1_hg5j2Sua8"
X-Entity-ETag: "01KK8Q8N5T6H49T8AENYT6Z6ZQ"

Extension'lar

Extension'lar, instance verisini zenginleştiren ek bağlam verisi sağlar:

Extension'lar view referans konfigürasyonunda tanımlanır
Her extension harici kaynaklardan veri alır
Extension verisi extensions objesine merge edilir
Extension'lar şunlar için kullanışlıdır:
- Kullanıcı profil bilgisi
- Referans veri lookup'ları
- Gerçek zamanlı hesaplanan değerler
- Harici sistem verileri

Instance Verilerini Filtreleme

Data fonksiyonu, attribute'lara göre instance verilerini sorgulamak için güçlü filtreleme yetenekleri destekler. Bu, kriterlerinize uyan belirli instance'ları filtrelemenize ve almanıza olanak tanır.

Filtre Söz Dizimi

Filtreler şu formatı kullanır: filter=attributes={alan}={operatör}:{değer}

Kullanılabilir Operatörler

Operatör	Açıklama	Örnek
`eq`	Eşittir	`filter=attributes=clientId=eq:122`
`ne`	Eşit değildir	`filter=attributes=status=ne:inactive`
`gt`	Büyüktür	`filter=attributes=amount=gt:100`
`ge`	Büyük veya eşittir	`filter=attributes=score=ge:80`
`lt`	Küçüktür	`filter=attributes=count=lt:10`
`le`	Küçük veya eşittir	`filter=attributes=age=le:65`
`between`	İki değer arasında	`filter=attributes=amount=between:50,200`
`like`	Alt dize içerir	`filter=attributes=name=like:john`
`startswith`	İle başlar	`filter=attributes=email=startswith:test`
`endswith`	İle biter	`filter=attributes=email=endswith:.com`
`in`	Liste içinde değer	`filter=attributes=status=in:active,pending`
`nin`	Liste dışında değer	`filter=attributes=type=nin:test,debug`

Filtre Örnekleri

Tek Filtre:

GET /core/workflows/payment-flow/instances/abc-123/functions/data?filter=attributes=amount=gt:1000 HTTP/1.1
Host: api.example.com
Accept: application/json

Çoklu Filtre (VE mantığı):

GET /core/workflows/order-processing/instances/123/functions/data?filter=attributes=status=eq:active&filter=attributes=priority=eq:high HTTP/1.1
Host: api.example.com
Accept: application/json

Aralık Filtresi:

GET /core/workflows/payment-flow/instances/abc-123/functions/data?filter=attributes=amount=between:100,500 HTTP/1.1
Host: api.example.com
Accept: application/json

Dize İşlemleri:

GET /core/workflows/customer/instances/123/functions/data?filter=attributes=email=endswith:@company.com HTTP/1.1
Host: api.example.com
Accept: application/json

Not: Filtreleme, instance attribute'ları üzerinde çalışır ve büyük veri kümeleri için pagination ile birleştirildiğinde özellikle kullanışlıdır. Instance filtreleme hakkında daha fazla bilgi için Instance Filtreleme bölümüne bakın.

Kullanım Alanları

Veri Senkronizasyonu: Client-side veriyi sunucu ile senkronize tutma
Verimli Polling: Gereksiz veri transferlerinden kaçınmak için ETag kullanma
View Veri Binding: View'ları mevcut instance verisi ile doldurma
Audit ve Loglama: Audit için tam instance durumunu alma
Filtrelenmiş Veri Alma: Attribute değerlerine göre belirli instance'ları sorgulama

Örnek İstek

GET /core/workflows/payment-flow/instances/abc-123/functions/data HTTP/1.1
Host: api.example.com
Accept: application/json
If-None-Match: "W/\"previous-etag\""

View Fonksiyonu

View fonksiyonu, mevcut workflow durumu için uygun view tanımını alır. Platforma özel içerik, transition'a özel view'lar ve uzak (cross-domain) view'lar desteklenir: başka bir domain'de host edilen view'lar referans verilerek kullanılabilir; böylece ortak view'ların yeniden kullanımı, versiyonlama ve dağıtımı tek merkezden yönetilebilir.

Endpoint

GET /{domain}/workflows/{workflow}/instances/{instance}/functions/view

Parametreler

Parametre	Konum	Tip	Gerekli	Açıklama
`domain`	Path	string	Evet	Domain adı
`workflow`	Path	string	Evet	Workflow key
`instance`	Path	string	Evet	Instance ID
`transitionKey`	Query	string	Hayır	View alınacak belirli transition
`platform`	Query	string	Hayır	Hedef platform (mobile, web, tablet, vb.)

Response

İçerik tipi: content, view type'ına göre tiplenir: type Json ise content bir object veya array; type Html (ve benzeri) ise content bir string'dir.

Json view örneği:

{
  "key": "account-type-selection-view",
  "content": {
    "type": "form",
    "title": { "en-US": "Choose Your Account Type", "tr-TR": "Hesap Türünüzü Seçin" },
    "fields": [...]
  },
  "type": "Json",
  "display": "full-page",
  "label": "Hesap Tipi Seç"
}

Html view örneği: content bir string'dir (örn. "<div>...</div>").

Response Alanları

Alan	Tip	Açıklama
`key`	`string`	View key tanımlayıcısı
`content`	`string` veya `object`/`array`	View içeriği: Json tipi → object/array; Html ve benzeri → string
`type`	`string`	İçerik tipi (Json, Html, vb.)
`display`	`string`	Gösterim modu (full-page, popup, vb.)
`label`	`string`	View için lokalize edilmiş etiket

Query Parametreleri

transitionKey

Hangi transition'ın view'ının alınacağını belirtir:

Sağlandı: O belirli transition için tanımlanan view'ı döndürür (varsa)
Sağlanmadı: State view'ını döndürür

Örnek:

GET /core/workflows/account-opening/instances/123/functions/view?transitionKey=confirm-creation

Bu, "confirm-creation" transition'ı için onay view'ını döndürür.

platform

View içeriği için hedef platformu belirtir. Desteklenen değerler: web, ios, android

Sistem, platforma özel içerik seçimini otomatik olarak yönetir:

İstenen platform için bir platform override varsa → override içeriğini döndürür
Override yoksa → orijinal view içeriğini döndürür
Client platform seçim mantığını uygulamak zorunda değildir

Örnek:

GET /core/workflows/account-opening/instances/123/functions/view?platform=ios

Sistem, view tanımına göre iOS'a özel içerik mi yoksa varsayılan içerik mi döndüreceğini otomatik olarak belirler.

View Seçim Mantığı

Fonksiyon, hangi view'ın döndürüleceğini belirlemek için bu mantığı izler:

Kural tabanlı view'lar: State veya transition bir views dizisi (kural tabanlı view seçimi) tanımlıyorsa, ilk eşleşen kural view'ı belirler. Detay için Kural Tabanlı View Seçimi dokümanına bakın.
Tek view / eski kullanım: transitionKey sağlandıysa transition view'ı (tanımlıysa), değilse state view kullanılır; sağlanmadıysa state view kullanılır.
Platform: platform sağlandıysa ve view'da platform override varsa o içerik ve display kullanılır; yoksa varsayılan.
Dil: Accept-Language uygulanır ve view'ın labels dizisinden uygun etiket döndürülür.

1. State/transition'da "views" dizisi (kural tabanlı) var mı?
   ├─ Evet: Kuralları sırayla değerlendir; ilk eşleşen view'ı döndür (veya kuralı olmayan varsayılan giriş)
   └─ Hayır: Aşağıdaki tek view mantığına geç

2. transitionKey sağlandı mı?
   ├─ Evet: Transition'ın tanımlı bir view'ı var mı kontrol et
   │   ├─ Evet: Transition view'ını kullan
   │   └─ Hayır: State view'ını kullan (veya state view yoksa boş döndür)
   └─ Hayır: State view'ını kullan

3. platform sağlandı mı?
   ├─ Evet: View'ın bu platform için platform override'ı var mı kontrol et
   │   ├─ Evet: Override içeriğini ve display ayarlarını kullan
   │   └─ Hayır: Orijinal içeriği ve display ayarlarını kullan
   └─ Hayır: Orijinal içeriği ve display ayarlarını kullan

4. Accept-Language header'ına göre dil seçimi uygula
   └─ View'ın labels dizisinden uygun etiketi döndür

Kullanım Alanları

State View Render Etme: Mevcut workflow durumu için view alma (sistem platform seçimini yönetir)
Transition Onayı: Client, transition submit öncesi view var mı diye transitionKey ile sorgular
Platforma Özel UI: Sistem, web, iOS veya Android için optimize edilmiş view'ları otomatik olarak sunar
Çoklu Dil Desteği: View'ları kullanıcının tercih ettiği dilde gösterme
Wizard Flow'ları: Adım adım input formları alma

Önemli: Sistem, tüm platform ve transition tabanlı view seçim mantığını yönetir. Client'ın yapması gerekenler:

Transition submit öncesi transition view kontrolü için transitionKey parametresini sağlamak
Platforma özel içerik için isteğe bağlı olarak platform parametresini (web/ios/android) sağlamak
Sistem, hangi view içeriğinin döndürüleceğini otomatik olarak belirler

Örnek İstekler

State View Al:

GET /core/workflows/account-opening/instances/123/functions/view HTTP/1.1
Host: api.example.com
Accept: application/json
Accept-Language: tr-TR

Transition View Al:

GET /core/workflows/account-opening/instances/123/functions/view?transitionKey=final-confirmation HTTP/1.1
Host: api.example.com
Accept: application/json

Mobil'e Özel View Al:

GET /core/workflows/account-opening/instances/123/functions/view?platform=mobile HTTP/1.1
Host: api.example.com
Accept: application/json
Accept-Language: tr-TR

Mobil Transition View Al:

GET /core/workflows/account-opening/instances/123/functions/view?transitionKey=submit&platform=mobile HTTP/1.1
Host: api.example.com
Accept: application/json

Schema Fonksiyonu

Schema fonksiyonu, bir transition için tanımlanmış JSON Schema içeriğini döndürür. View fonksiyonu ile aynı mantıkta çalışır; ancak view yerine transition'a ait şema tanımını sunar. Client'lar bu bilgiyi form oluşturma, input doğrulama ve dinamik UI üretimi için kullanabilir.

Endpoint

GET /{domain}/workflows/{workflow}/instances/{instance}/functions/schema

Parametreler

Parametre	Konum	Tip	Gerekli	Açıklama
`domain`	Path	string	Evet	Domain adı
`workflow`	Path	string	Evet	Workflow key
`instance`	Path	string	Evet	Instance ID
`transitionKey`	Query	string	Evet	Schema alınacak belirli transition

Response

{
  "key": "account-type-selection",
  "type": "workflow",
  "schema": {
    "$id": "https://schemas.vnext.com/banking/account-type-selection.json",
    "type": "object",
    "title": "Account Type Selection Schema",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "required": ["accountType"],
    "properties": {
      "accountType": {
        "type": "string",
        "oneOf": [
          {
            "const": "demand-deposit",
            "description": "Vadesiz Hesap - Demand Deposit Account"
          },
          {
            "const": "time-deposit",
            "description": "Vadeli Hesap - Time Deposit Account"
          }
        ],
        "title": "Account Type",
        "description": "Type of account to be opened"
      }
    },
    "description": "Schema for account type selection input",
    "additionalProperties": false
  }
}

Response Alanları

Alan	Tip	Açıklama
`key`	`string`	Schema key tanımlayıcısı
`type`	`string`	Schema tipi (örn. `workflow`)
`schema`	`object`	JSON Schema içeriği (JSON Schema 2020-12 formatında)

Kullanım Alanları

Dinamik Form Üretimi: Transition'a ait şemadan otomatik form oluşturma
Input Doğrulama: Transition submit öncesi client-side validation
UI Bileşen Seçimi: Schema tiplerine göre uygun UI bileşenlerini render etme

Örnek İstekler

Transition Schema Al:

GET /core/workflows/account-opening/instances/123/functions/schema?transitionKey=select-demand-deposit HTTP/1.1
Host: api.example.com
Accept: application/json

İpucu: State fonksiyonu yanıtındaki transitions[].schema.hasSchema alanını kontrol ederek, gereksiz schema istekleri ve 404 hatalarından kaçının.

Yetkilendirme (Authorization)

Workflow'larda fonksiyon, flow, state ve transition seviyesinde roles ve queryRoles tanımlanabilir. Aşağıdaki sistem fonksiyon endpoint'leri yetki bilgilerini ve yetkilendirme kontrolünü sunar.

Ön tanımlı sistem rolleri

Instance yetkilendirmesi için (örn. transition roles, state/flow queryRoles veya Master şema alan görünürlüğünde) iki statik sistem rolü kullanılabilir:

Rol	Açıklama
$InstanceStarter	Instance'ı başlatan actor
$PreviousUser	Bir önceki transition'ı tetikleyen actor

Transition veya roleGrant örneği:

{
  "roles": [
    { "role": "$InstanceStarter", "grant": "allow" },
    { "role": "$PreviousUser", "grant": "allow" }
  ]
}

Instance verisi JSONPath yetkilendirmesi

roleGrant içindeki role değerleri JSONPath tarzı ifadeler kullanabilir; runtime token değerlerini ScriptContext'ten ( Instance.Data dahil) okunan değerlerle karşılaştırır:

Prefix	Karşılaştırılan token	Karşılaştırılan bağlam değeri
`$user.<jsonpath>`	Actor	Bağlamdaki `<jsonpath>` değeri
`$role.<jsonpath>`	Rol	Bağlamdaki `<jsonpath>` değeri
`$userBehalfOf.<jsonpath>`	Subject (adına işlem)	Bağlamdaki `<jsonpath>` değeri

Adına işlem anlamları için ek sistem rolleri:

Rol	Açıklama
`$InstanceBehalfOfStarter`	Instance'ı başlatan subject (adına işlem yapılan token)
`$PreviousBehalfOfUser`	Bir önceki transition'ı tetikleyen subject (adına işlem yapılan token)

Örnek yollar (workflow veri şemanıza uymalıdır):

$user.$.context.Instance.Data.customer.ownerUserId
$user.$.context.Instance.Data.assignedUsers[*].userId
$userBehalfOf.$.context.Instance.Data.customer.behalfOfUserId
$role.$.context.Instance.Data.permissions.requiredRole
$role.$.context.Transition.Key

Bu kalıplar available transition ve data yetkilendirmesinin geçerli olduğu her yerde değerlendirilir (Master şema alan görünürlüğü dahil).

Referans: #469

Master şema alan bazlı görünürlük

Flow Master şeması, şema property'lerinde roleGrant (roles) özelliği ile alan bazlı görünürlük tanımlayabilir. Data fonksiyonu ve veri dönen endpoint'ler (Get Instance, GetInstances vb.) authorize katmanını çalıştırır ve yalnızca çağıranın görmesine izinli olduğu alanları döndürür. roles tanımı olmayan property'ler tüm yetkili çağıranlara görünür. Vocabulary ve araç uyumluluğu için roles-vocab.json kullanılabilir.

Flow Authorize

Verilen rolün, flow üzerinde verilen transition (veya function) için izinli olup olmadığını kontrol eder. İsteğe bağlı version; verilmezse latest kullanılır.

GET /api/v1/{domain}/workflows/{workflow}/functions/authorize?transitionKey=submit-account-details&role=morph-idm.maker&version=1.0.0

Yanıt 200: { "allowed": true }
Yanıt 403: { "allowed": false }

Instance Authorize

Flow Authorize ile aynı yanıt. queryRoles=true ile yetki, instance'ın mevcut state'ine (flow ve state queryRoles) göre değerlendirilir. Subflow içindeki instance'larda aktif subflow instance kullanılır.

GET /api/v1/{domain}/workflows/{workflow}/instances/{instanceId}/functions/authorize?queryRoles=true&role=morph-idm.viewer

Authorize Query Parametreleri

Parametre	Açıklama
`role`	Kontrol edilecek rol.
`version`	İsteğe bağlı. Flow versiyonu; varsayılan latest.
`transitionKey`	Kontrol edilecek transition (transition seviye roles).
`functionKey`	Kontrol edilecek fonksiyon (function seviye roles).
`queryRoles`	true ise instance'ın mevcut state'i için flow ve state queryRoles kontrol edilir (subflow bağlamı varsa ona göre).

En iyi Uygulamalar

1. Long-Polling'i Verimli Kullanın

Başarısız istekler için exponential backoff uygulayın
Makul polling aralıkları belirleyin (3-10 saniye)
Workflow final state'e ulaştığında polling'i durdurun
Gereksiz veri transferlerinden kaçınmak için ETag kullanın

2. ETag Önbelleklemesinden Yararlanın

Her zaman saklanan ETag ile If-None-Match header'ı gönderin
304 response'larını düzgün şekilde handle edin
Her başarılı 200 response'unda ETag'leri güncelleyin
Transition'larda optimistic locking için ETag'leri kullanın

3. Platform Parametresini Doğru Kullanın

Client tipine göre platform parametresi (web/ios/android) gönderin
Sistem platforma özel içerik seçimini otomatik olarak yönetir
Fallback mantığı uygulamaya gerek yok - sistem handle eder
Platforma özel view'ları uygun şekilde önbellekleyin

4. View Render Etmeyi Optimize Edin

Muhtemel sonraki state'ler için view'ları önceden alın
View tanımlarını yerel olarak önbellekleyin
Mümkün olduğunda view içeriğini lazy-load edin
Tekrarlanan view'lar için view render pooling uygulayın

5. Performansı İzleyin

Şu metrikler için takip yapın:

Fonksiyon başına ortalama response süresi
ETag istekleri için cache hit oranı
Polling aralığı verimliliği
View render etme performansı

6. Güvenlik Değerlendirmeleri

Function çağrıları için her zaman HTTPS kullanın
Header'larda authentication token'ları dahil edin
Render etmeden önce view içeriğini doğrulayın (XSS önleme)
Client tarafında rate limiting uygulayın
İstek takibi için correlation ID'leri kullanın

Ilgili Dökümanlar

Custom Functions - Kullanıcı tanımlı fonksiyonlar
Instance Filtreleme - GraphQL-stil filtreleme kılavuzu
View - View tanımları ve gösterim stratejileri
Kural Tabanlı View Seçimi - Kurallara göre dinamik view seçimi
Workflow - Workflow state'lerini anlama
Transition Yönetimi - Mapping ve transition'lar
Versiyonlama ve ETag (Phase 2) - ETag pattern detayları

İçindekiler​

Genel Bakış​

State Fonksiyonu​

Endpoint​

Parametreler​

Response​

Response Alanları​

Transition'ların role grant'a göre filtrelenmesi​

Aktif Correlation'lar​

Kullanım Alanları​

Subflow tamamlanma penceresi​

Telemetry​

Trace ve logda ParentInstanceId​

Örnek İstek​

Data Fonksiyonu​

Endpoint​

Parametreler​

Header'lar​

Response (200 OK)​

Response (304 Not Modified)​

Response Alanları​

Instance zarfı ve metadata​

ETag Desteği​

Authorization-aware ETag​

Extension'lar​

Instance Verilerini Filtreleme​

Filtre Söz Dizimi​

Kullanılabilir Operatörler​

Filtre Örnekleri​

Kullanım Alanları​

Örnek İstek​

View Fonksiyonu​

Endpoint​

Parametreler​

Response​

Response Alanları​

Query Parametreleri​

transitionKey​

platform​

View Seçim Mantığı​

Kullanım Alanları​

Örnek İstekler​

Schema Fonksiyonu​

Endpoint​

Parametreler​

Response​

Response Alanları​

Kullanım Alanları​

Örnek İstekler​

Yetkilendirme (Authorization)​

Ön tanımlı sistem rolleri​

Instance verisi JSONPath yetkilendirmesi​

Master şema alan bazlı görünürlük​

Flow Authorize​

Instance Authorize​

Authorize Query Parametreleri​

En iyi Uygulamalar​

1. Long-Polling'i Verimli Kullanın​

2. ETag Önbelleklemesinden Yararlanın​

3. Platform Parametresini Doğru Kullanın​

4. View Render Etmeyi Optimize Edin​

5. Performansı İzleyin​

6. Güvenlik Değerlendirmeleri​

Ilgili Dökümanlar​

İçindekiler

Genel Bakış

State Fonksiyonu

Endpoint

Parametreler

Response

Response Alanları

Transition'ların role grant'a göre filtrelenmesi

Aktif Correlation'lar

Kullanım Alanları

Subflow tamamlanma penceresi

Telemetry

Trace ve logda ParentInstanceId

Örnek İstek

Data Fonksiyonu

Endpoint

Parametreler

Header'lar

Response (200 OK)

Response (304 Not Modified)

Response Alanları

Instance zarfı ve metadata

ETag Desteği

Authorization-aware ETag

Extension'lar

Instance Verilerini Filtreleme

Filtre Söz Dizimi

Kullanılabilir Operatörler

Filtre Örnekleri

Kullanım Alanları

Örnek İstek

View Fonksiyonu

Endpoint

Parametreler

Response

Response Alanları

Query Parametreleri

transitionKey

platform

View Seçim Mantığı

Kullanım Alanları

Örnek İstekler

Schema Fonksiyonu

Endpoint

Parametreler

Response

Response Alanları

Kullanım Alanları

Örnek İstekler

Yetkilendirme (Authorization)

Ön tanımlı sistem rolleri

Instance verisi JSONPath yetkilendirmesi

Master şema alan bazlı görünürlük

Flow Authorize

Instance Authorize

Authorize Query Parametreleri

En iyi Uygulamalar

1. Long-Polling'i Verimli Kullanın

2. ETag Önbelleklemesinden Yararlanın

3. Platform Parametresini Doğru Kullanın

4. View Render Etmeyi Optimize Edin

5. Performansı İzleyin

6. Güvenlik Değerlendirmeleri

Ilgili Dökümanlar