Provider از نوع REST

REST Provider امکان اتصال GraphBPMS به سرویس‌های REST داخلی یا خارجی را فراهم می‌کند. در این Provider، درخواست HTTP ساخته شده و نتیجه دریافت‌شده بر اساس تنظیمات تعریف‌شده پردازش می‌شود.

ساختار Wizard در REST Provider

ایجاد REST Provider به‌صورت مرحله‌ای انجام می‌شود. در هر مرحله بخشی از اطلاعات مورد نیاز برای ساخت درخواست و مدیریت پاسخ سرویس تعریف می‌شود.

مرحله اطلاعات منبع

در مرحله اول، اطلاعات اصلی ارتباط با سرویس مشخص می‌شود. این اطلاعات مشخص می‌کند Provider به کدام سرویس REST متصل خواهد شد.

مدیریت Rest Service

در این مرحله، اطلاعات مربوط به سرویس REST شامل آدرس، نحوه ارسال درخواست و تنظیمات مرتبط با ارتباط تعریف می‌شود.

آدرس سرویس

آدرس Endpoint سرویس مقصد در این بخش تعریف می‌شود. این آدرس می‌تواند شامل Placeholderهایی باشد که در زمان اجرا با مقدار واقعی جایگزین می‌شوند.

Method درخواست

نوع درخواست HTTP مشخص می‌کند که Provider چگونه با سرویس مقصد ارتباط برقرار کند.

Query Parameter و Placeholder در URL

در REST Provider امکان تعریف پارامترهایی وجود دارد که در URL یا بخش‌های دیگر درخواست استفاده می‌شوند. Placeholderها اجازه می‌دهند مقدار مورد نیاز در زمان اجرا جایگزین شود.

https://service-url.com/customer/{CustomerId}

تنظیمات Request

در REST Provider می‌توان نحوه ارسال درخواست، نوع Content و اطلاعات مورد نیاز برای ارسال به سرویس را مشخص کرد.

پارامترهای REST Provider

در این بخش، لیست Parameterهای مورد استفاده در درخواست REST تعریف می‌شود. هر Parameter می‌تواند دارای مشخصات مختلفی مانند نام، مقدار، محل ارسال و نوع محتوا باشد.

Request Content Type

Content Type مشخص می‌کند اطلاعات ارسالی در Request با چه ساختاری به سرویس مقصد ارسال شود. انتخاب صحیح Content Type باید مطابق قرارداد سرویس مقصد انجام شود.

Parameter Location

هر Parameter در REST Provider می‌تواند در بخش مشخصی از Request قرار گیرد. محل قرارگیری Parameter تعیین می‌کند مقدار آن چگونه به سرویس مقصد ارسال شود.

URL

در این حالت مقدار Parameter در آدرس URL سرویس قرار می‌گیرد. این روش معمولاً برای پارامترهایی استفاده می‌شود که بخشی از مسیر Endpoint هستند.

https://api.example.com/customer/{CustomerId}

Query Parameter

در این حالت Parameter به‌صورت Query String به انتهای URL اضافه می‌شود.

https://api.example.com/customers?page=1

Header

در این حالت مقدار Parameter در Header درخواست ارسال می‌شود. این روش برای اطلاعاتی مانند تنظیمات درخواست یا مقادیر مورد نیاز سرویس استفاده می‌شود.

Authorization: Bearer Token

Body

در این حالت مقدار Parameter در Body درخواست قرار می‌گیرد. این روش معمولاً در درخواست‌های POST استفاده می‌شود.

Constant / Default در REST Provider

برای برخی Parameterها می‌توان مقدار پیش‌فرض یا ثابت تعریف کرد. این قابلیت باعث می‌شود در صورت ارسال نشدن مقدار توسط Caller، مقدار تعریف‌شده در Provider استفاده شود.

مثال

Parameter:
Language

Default:
fa

Call 1:
No Value
Result:
fa

Call 2:
Language = en
Result:
en

نکات اجرایی Parameterها

REST Output Fields

پس از تعریف Request و ارسال درخواست به سرویس REST، ساختار خروجی سرویس باید در Provider مشخص شود. Output Fieldها تعیین می‌کنند چه بخش‌هایی از Response به‌عنوان خروجی Provider در دسترس باشند.

تعریف Output Field

هر Output Field یک مقدار مشخص از پاسخ سرویس را نمایش می‌دهد. در زمان تعریف Output Field باید مسیر دریافت مقدار و نوع استفاده از آن مشخص شود.

ساختار Response و استخراج خروجی

Output Fieldها باید مطابق ساختار واقعی پاسخ سرویس تعریف شوند. در صورت تغییر ساختار Response سرویس، تنظیمات Output Field نیز باید بررسی شود.

Response:
{
  "id": 10,
  "name": "Customer"
}

Output Fields:
Id
Name

Output Field Script

در برخی سناریوها مقدار خروجی سرویس نیاز به پردازش دارد. در این حالت می‌توان برای Output Field یک Script تعریف کرد تا مقدار نهایی قبل از ارائه خروجی محاسبه شود.

ساختار Script

مقادیر خروجی همان رکورد از طریق args در دسترس هستند و مقدار نهایی فیلد باید در result قرار داده شود.

result = !(args.IsOk);

مثال‌های Output Field Script

تغییر مقدار Boolean

result = !(args.IsOk);

ایجاد مقدار متنی

result = args.IsOk ? 'OK' : 'NOT_OK';

ترکیب چند خروجی

result = [args.FirstName, args.LastName]
    .filter(Boolean)
    .join(' ');

محاسبه عددی

result =
    Number(args.Price || 0) *
    Number(args.Quantity || 0);

مدیریت مقدار Null

result =
    args.Value == null
        ? ''
        : String(args.Value).trim();

راهنمای Script IDE

نکات تست Output Field Script