وب سرویس ورود اطلاعات حسابداری از خارج از محیط نرمافزار یکپارچه مالی نوسا (API Server)
ابزار قابل خرید آماده شده در نسخه 9.02
بدلیل پیچیدگی و گسترش اطلاعات، مستند فنی وب سرویس ورود و دریافت اطلاعات انبار و فروش از خارج از محیط نرمافزار مالی یکپارچه نوسا ارائه شده در نسخه 11.02 بصورت عام قابل ارائه نمیباشد، در صورت نیاز به این مستند لطفا با شرکت نوسا تماس حاصل فرمایید.
سرویسهای مبتنی بر Web و XML در سیستم مالی نوسا XP
یکی از پیشرفتهترین روشها برای صدور فرمان اجرای عملیات در یک سیستم نرمافزاری از یک نرمافزار مجزا، در محیط شبکه، سرویسهای مبتنی بر Web و XML (XML Web Services) هستند. همانند صفحات Web، سرویسهای مبتنی بر Web نیز بر روی یک سرور Web (مثل IIS) و با پروتکل http (یا https) اجرا میشوند. همانند صفحات Web در اینجا هم با پکتهای http سروکار داریم که دادههایی را به سرور ارسال و از آن دریافت میکنند. تفاوت در اینجا است که در این ساختار، سرور، به جای اینکه انتظار آدرس صفحات را در پکتهای ورودی داشته باشد و در پاسخ صفحاتی با ساختار html را بازگرداند، در ورودی پارامترهایی را با ساختار SOAP (مبتنی بر XML) توقع دارد + به جای ارائهی صفحهی html، یک متد (روتین) را در سرور اجرا میکند و حاصل را نیز به صورت پارامترهایی با ساختار SOAP تحویل میدهد.
در ارتباطی که در بالا معرفی کردیم، یکی از نرمافزارها در نقش ارائهدهنده سرویس قرار دارد که به آن SOAP Server میگویند و به نرمافزار دیگر، که قرار است از سرویس استفاده کند، SOAP Client گفته میشود. این Client ممکن است همان نرمافزاری باشد که کاربر به صورت مستقیم با آن کار میکند (مثل کلاینت سیستم مالی یکپارچه) و یا در مقابل ممکن است خود در مقام سرور برای یک سیستم دیگر قرار داشته باشد – مثل سرور یک سیستم گردش کار یا نرمافزار فروش Online که در نقش Client به SOAP Server سیستم مالی متصل شود و سند یا برگهی جدید تنظیم نماید.
یکی از اجزاءِ مهم سیستم مالی نوسا XP، از قبل، SOAP Server بوده است که عملا یک Web Service است – اما بیشتر با هدف استفاده توسط کلاینت نوسا طرح و پیادهسازی شده بود. وجود این نوع سرور در کنار قابلیت کلاینت نوسا برای اتصال به آن باعث شده که ارتباط کلاینت و سرور با پروتکل SOAP و به صورت Web Based میسر باشد – سرور و کلاینت نوسا، هر جای شبکهی اینترنت که قرار داشته باشند، به صرف اینکه URL سرور برای کلاینت شناخته شده باشد و کلاینت هم به اینترنت متصل باشد میتوانند به هم مرتبط شوند و به تبادل اطلاعات بپردازند.
اما به جز کاربرد متداول فوق، برای اینکه استفاده از سرویسهای برگزیدهی نوسا، نه لزوما توسط کلاینت بلکه توسط سایر نرمافزارها (و به خصوص سایر سرورها) نیز میسر باشد باید سرویسهای مزبور را به صورت متدهایی از Web Service پیاده کنیم و در اختیار سایرین قرار دهیم. این عمل به تدریج برای سرویسهای برگزیدهی نوسا انجام شد – سرویسهایی که پیشبینی میکنیم بیشترین کاربرد را داشته باشند. به عنوان شروع متدهایی برای ایجاد تفصیلی (عملا ترکیبی از اطلاعات تلفن و نشانی، تفصیلی و مرکز مصرف یا تامین کالا یا خدمات) و ایجاد سند حسابداری را در نسخه 9.02 پیادهسازی کردیم که بخشی از مستند فنی آن در اینجا در دسترس میباشد. همچنین در ویرایش 11.02 سیستم، متدهای متنوع جدیدی برای درج انواع برگههای مورد استفاده در سیسستمهای انبار و فروش و همچنین متدهایی برای پشتیبانی از سیستمهای فروش online را پیادهسازی کردهایم که همه اطلاعات فنی مربوط به آن در مستند تمکیلی در دسترس مشتریان این نرمافزارها میباشد. هر سیستم نرمافزاری که SOAP Client را به نحوی پشتیبانی نماید میتواند با اندکی عملیات آمادهسازی، از این متدها استفاده کند. نمونههایی با html/java script، php، Delphi، Python و C# آماده کردهایم که توضیح استفاده آنها در ادامه این مستند و فایلهای مرتبط به هر یک در بخش فایل و مستندات قابل دریافت میباشد. این نمونهها نحوهی اجرای متدها را برای برنامهنویسان سایر سیستمها بازنمایی میکنند.
فعالسازی و اعتبار
استفاده از سرویسهای جدیدی که در این مستند به آنها پرداختهایم نیاز به وجود وب سرور API در قفل مشتری دارد، در صورتی که مشتری از وب سرویس SOAP استفاده میکند نیازی به عملیات نصب جداگانه برای راه اندازی سرور API نخواهد بود – همانطور که پیش از این اشاره کردیم، سیستم نوسا از قبل سرور SOAP داشته و API سرور و امکانات جدید آن به همان Web Service اضافه شدهاند.
مدل ارائهی این سرویس توسط شرکت نوسا مبتنی بر 1) فعال سازی سرور API درون قفل سختافزاری و 2) خرید اعتبار (شارژ کردن تعداد تراکنش در قفل سختافزاری) است. هر یک از متدهای Web Service، حسب مورد، میزانی از اعتبار مذکور را مصرف میکنند. در حال حاضر هر سطر از سند حسابداری یک واحد از اعتبار تراکنشهای خریداری شده و هر ترکیب تلفن و نشانی، تفصیلی و مرکز 5 واحد از اعتبار تراکنشهای خریداری شده را مصرف میکند.
با کمتر شدن میزان اعتبار تراکنشها از یک حد مشخص، میزان اعتبار باقیمانده همزمان با انتخاب پایگاه (Login) به برخی از کاربران (به عنوان هشدار) اطلاع داده میشود. میزان اعتبار هشدار در Admin و به عنوان بخشی از تنظیمات سرور تعیین میشود:
مطابق آنچه در محاورهی فوق تنظیم شده است، اگر اعتبار Web Service از یکهزار واحد کمتر شود همزمان با Login هشدار داده میشود. طبیعی است که ارائهی این هشدار به همهی کاربران مطلوب نیست. برای تعیین کاربرانی که قرار است این هشدار را دریافت کنند یکی از اختیارات کاربران را پیشبینی کردهایم:
امکانات / سیستم / مدیریت (Admin) / دریافت هشدار اعتبار Web Service
احراز هویت کاربر و اختیارات وی
نرمافزارهایی که قصد دارند از Web Service استفاده کنند باید قاعدتا در SOAP Server، Login کنند. این عمل با تعیین نام کاربر و کلمهی عبور انجام میشود. در همهی زبانهای برنامهسازی (که برای نوشتن کلاینت بکار میروند) امکاناتی برای تعیین آنها تعبیه شده است. اطلاعات فنی کامل آن در مستند کامل این ابزار به مشتریان قابل ارائه میباشد.
این پارامترها (نام کاربر و کلمهی عبور) برای اتصال به Web Server (مثلا IIS) بکار میروند و در نهایت کاربر به سرور SOAP نوسا متصل خواهد شد. از اینجا به بعد کاربر تفاوتی با کاربران عادی سرور نوسا نخواهد داشت و همانند آن کاربران باید قابل شناسایی باشد؛ یعنی به عنوان کاربر رایانهی سرور یا کاربر domain تعریف شده باشد و همچنین به عنوان یکی از کاربران به پایگاه دادهها معرفی شده باشد. به این ترتیب از نظر احراز هویت و تعیین امکانات، به امنترین شیوهی ممکن عمل شده است و روش کار بسیار شبیه خواهد شد به احراز هویت کاربرانی که از کلاینت SOAP اصلی نوسا استفاده میکنند. البته افزایش امنیت ارتباط http (مثلا با استفاده از پروتکل https) هم در این عملیات مطرح است که طبق معمول کاربران را به آن توصیه میکنیم.
دیدیم که کاربرانی که قرار است از Web Service استفاده کنند باید در پایگاه دادهها تعریف شوند. در همانجا اختیارات این کاربران نیز باید به صورت عادی تعیین شود. مثلا برای ایجاد سند حسابداری، کاربر Web Service باید اختیار "تنظیم سند حسابداری جدید در تاریخ دلخواه" را داشته باشد. همچنین اگر قرار باشد سند حسابداری را در بخشهایی به جز بخشهای کاربر تنظیم کند، باید اختیار "تنظیم سند حسابداری جدید در تاریخ دلخواه برای سایر بخشها" را نیز داشته باشد.
موارد فوق شامل اختیارات مشترک بین کاربران عادی و کاربران Web Service بودند. به جز آنها، اختیارات اختصاصی برای اجرای عملیات از طریق Web Service هم پیشبینی شدهاند که عملا مشخص کنندهی این هستند که کاربر اصلا حق دارد به عنوان کلاینت Web Service ایفای نقش نماید یا خیر. مثلا برای استفاده از متد افزودن سند حسابداری کاربر باید اختیار زیر را داشته باشد:
امکانات / سیستم / مدیریت (Admin) / افزودن تفصیلی از طریق Web Service – و – افزودن سند از طریق Web Service
به صورت مشابه، برای افزودن ترکیب تلفن و نشانی، تفصیلی و مرکز، کاربر Web Service باید حسب مورد برخی یا تمامی اختیارات زیر را داشته باشد:
- افزودن تلفن و نشانی جدید
- تعریف تفصیلی جدید
- تعریف یا اصلاح تفصیلی غیروابسته به بخش (اگر قصد دارد تفصیلی مستقل از بخش تعریف کند)
- تعریف یا اصلاح تفصیلی سایر بخشها (اگر قصد دارد برای بخشهایی به جز بخشهای کاربر تفصیلی تعریف کند)
- تعریف مرکز جدید
موارد فوق شامل اختیارات مشترک بین کاربران عادی و کاربران Web Service بودند. به جز آنها، اختیارات اختصاصی برای اجرای عملیات از طریق Web Service هم پیشبینی شدهاند که عملا مشخص کنندهی این هستند که کاربر اصلا حق دارد به عنوان کلاینت Web Service ایفای نقش نماید یا خیر:
متدهای قابل اجرا (پارامترهای پایگاه اطلاعاتی و Data XML و توصیف XML حاصله)
دو متد مشابه زیر در Web Service حسابداری توسعه داده شدهاند:
function WS_AddDet(const ADBName, AData: String): String;
function WS_AddArt(const ADBName, AData: String): String;
این متدها دو پارامتر حرفی دارند و حاصل هم یک رشتهی حرفی است. پارامتر اول نام پایگاه اطلاعاتی است. اسامی پایگاههای اطلاعاتی سیستم مالی نوسا با _AccXP_ آغاز میشوند و در Admin قابل مشاهده هستند. همان نام باید عینا به عنوان پارامتر نخست داده شود – مثلا _AccXP_Main98.
پارامتر دوم یک XML است که محتویات آن بسته به متد متفاوت است. این XMLها را به دقت در بخشهای بعدی توضیح خواهیم داد. شمای کلی XML ورودی برای افزودن تفصیلی به صورت زیر است:
همانطور که مشاهده میشود، در این XML، root فاقد دادهی اختصاصی است و صرفا برای مجتمع کردن سایر nodeها تعریف میشود. هر یک از nodeها متناظر با یکی از اقلام اطلاعاتی هستند که در این متد قرار است در سیستم درج شوند:
root حاوی مشخصات عمومی سند حسابداری است. این مشخصات به صورت XML attribute تعیین میشوند. هر سطر سند (هر رخداد یا Transaction) به عنوان یک node و به صورت تکراری در داخل _Art قرار میگیرد. مشخصات رخداد نیز به صورت XML attribute داده میشوند. همانطور که گفتیم کل XML به صورت یک رشتهی حرفی به عنوان پارامتر دوم متد لحاظ میشود.
حاصل این متدها نیز به صورت XML بازگردانده میشود. این XML فقط یک node دارد (root با نام _RSLT) و شمای کلی آن به صورت زیر است:
ErrNo همیشه وجود دارد. مقدار صفر یعنی اجرای موفقیتآمیز (بدون خطا). در این وضعیت ممکن است اطلاعات دیگری هم از سرور گزارش شوند. اما مقدار مخالف صفر ErrNo به معنی خطا است. در این وضعیت عبارت توصیفکنندهی خطا در ErrStr داده خواهد شد.
سایر اطلاعات حاصله از اجرای WS_AddDet عبارتند از:
کدهای تفصیلی و مرکز از ترکیب کد سرگروه و شماره تعیین میشوند. تعداد ارقام زیرگروه (مطابق تعریف سرگروه) در تشکیل کد دخالت دارند. همچنین خواهیم دید که شمارهی تفصیلی یا مرکز ممکن است توسط سیستم تعیین شوند.
سایر اطلاعات حاصله از اجرای WS_AddArt عبارتند از:
انواع شمارهها همیشه توسط سیستم تعیین میشوند و اطلاع داده میشوند. شناسهی فراخوانی ابزاری برای ممانعت از درج سند تکراری است و اگر از ابتدا داده نشده باشد توسط سیستم تعیین و بازگردانده میشود. تاریخ سند هم ممکن است توسط سیستم تعیین شود و به همین دلیل بازگردانده هم میشود.
خطاهای احتمالی در جدول زیر مشاهده میشوند. شماره و توصیف خطا داده شدهاند. شمارهی خطا همان ErrNo است که پیش از این گفتیم. در بسیاری از موارد توصیف خطا همان ErrStr است:
تعیین تاریخ
تاریخها به صورت ترکیب سال – ماه – روز و با جداکنندهی / در XML درج میشوند. هر فیلد تاریخ به صورت یکی از دو attribute حاوی تاریخ خورشیدی یا میلادی تعبیه شده است. چنین است که اگر تاریخ خورشیدی وارد شده باشد به تاریخ میلادی توجه نمیشود. نام attributeهای حاوی تاریخ خورشیدی با FA_ و نام attributeهای حاوی تاریخ میلادی با LA_ آغاز میشوند. مثلا تاریخ سند با دو attribute به اسامی FA_Date و LA_Date قابل تعیین است:
همانطور که گفته شد فقط یکی از این دو attribute مورد توجه قرار میگیرند و اولویت با تاریخ خورشیدی است. همهی فیلدهای تاریخی در سند، رخدادهای مالی و دفتر تلفن و نشانی به همین صورت تعیین میشوند و در ادامه خواهیم دید که برای هر یک از آنها دو attribute مشاهده خواهند شد.
الگوی تعیین خودکار دادهها
به منظور تسهیل اجرای متدهای Web Service و نیز اعمال کنترل بیشتر برروی دادههایی که قرار است از این طریق به پایگاه اطلاعاتی اضافه شوند، مکانیزمی تحت عنوان "الگوی تعیین خودکار دادهها در Web Service" تعبیه شده است. تنظیم این الگو با انتخاب گزینهای به همین نام از منوی "سیستم / مدیریت (Admin)" انجام میشود:
همانطور که در شکل دیده میشود، در این محاوره، تعیین و تغییر دادهها برای مشخصات عمومی سند، سطرهای سند (رخدادهای مالی)، دفتر تلفن و نشانی، تفصیلی و مرکز میسر است. عموما برای هر فیلد یک "نحوهی عمل" مشخص میشود که یکی از حالتهای زیر است:
- تعیین نشود (که به معنی غیرفعال بودن مکانیزم برای این فیلد است)
- درصورت عدم وجود تعیین شود
- درصورت عدم وجود یا مقدار نادرست تعیین شود
- جایگزین مقدار نادرست شود
- همواره جایگزین شود
"مقدار نادرست" یعنی آنچه در XML به متد داده شده ولی توسط سیستم به عنوان مقدار صحیح شناسایی نمیشود. مثلا کد حسابی که در سیستم وجود نداشته باشد یا نوع سندی که در محدودهی صفر تا 3 (عادی تا سود و زیان) نباشد. گزینهی "همواره جایگزین شود" امکان ممانعت از درج دادههایی به جز آنچه مورد نظر است را فراهم میکند. به عنوان مثال در مورد بخش میتوان با استفاده از این گزینه ترتیبی داد که سندهای تنظیم شده از Web Service همیشه مربوط به یک بخش به خصوص (در مثال فوق، بخش مرکزی) باشند.
در اکثر موارد، علاوه بر "نحوهی عمل"، مقدار مورد نظر برای فیلد هم تعیین میشود. در موارد استثنایی مقدار مورد نظر کاملا به دلخواه کاربر تعیین نمیشود – مثلا در مورد تاریخ سند، تاریخ به خصوصی تعیین نمیشود بلکه همواره از "تاریخ روز" به عنوان تاریخ سند استفاده میشود.
در شکل قبل، تنظیمات مربوط به مشخصات عمومی سند حسابداری مشاهده میشوند. با توضیحاتی که در بالا دادیم تقریبا همهی موارد واضح هستند – در مورد وضعیت سند، چنین است که اگر سند ورودی پیشنویس نباشد و جمع مبالغ بدهکار و بستانکار آن با هم مساوی باشند، به عنوان یک سند عملیاتی در سیستم ثبت میشود (امکان ثبت سندهای تایید شده یا نهایی شده از Web Service وجود ندارد). یک دریچهی قابل انتخاب در الگوی مورد بحث وجود دارد که این مکانیزم را تغییر میدهد و باعث میشود که سند، مستقل از آنچه در Data XML تعیین شده است، در وضعیت پیشنویس ثبت شود.
تنظیمات مربوط به سطرهای سند (رخدادهای مالی) را در شکل زیر مشاهده میکنید:
دریچههایی برای واحد پول (ارز) و واحد مقدار و نیز موارد مشابهی برای حساب و تفصیلیها دیده میشوند. تغییر در واحد پول یا واحد مقدار، حسب مورد، فقط در صورتی که مبلغ ارز یا مقدار در Data XML برای رخداد داده شده باشند انجام میشود. "نحوهی عمل" همان است که پیش از این گفته بودیم و در ادامه دریچههایی برای انتخاب واحد پول (ارز) یا واحد مقدار تعبیه شدهاند. نکتهی قابل توجه این است که در این دریچهها گزینهای با عنوان "خالی" وجود دارند که در صورت انتخاب منجر به حذف ارز یا مقدار خواهند شد. به این ترتیب درصورتی که مثلا بخواهیم ترتیبی دهیم که رخدادهای مالی ثبت شده با Web Service اصلا مقدار نداشته باشند، میتوانیم مطابق شکل فوق، واحد مقدار را "همواره جایگزین" کنیم و دریچهی بعدی را روی حالت "خالی – حذف مقدار" قرار دهیم. خالی بودن واحد مقدار منجر به حذف مقدار نیز خواهد شد.
در شکل فوق، با استفاده از امکاناتی که پیش از این شرح دادهایم، ترتیبی اتخاذ شده است که حساب اصلا مورد تغییر قرار نگیرد + تفصیلی 1 کد پیشفرض داشته باشد (در صورت عدم وجود تعیین شود) و تفصیلیهای 2 تا 5 همیشه خالی شوند – یعنی امکان درج رخداد با تفصیلیهای 2 تا 5 به Web Service داده نشود.
فیلدهای دفتر تلفن و نشانی، تفصیلی و مرکز نیز به همین صورت و با استفاده از "نحوهی عمل" و مقدار مورد نظر در الگو تنظیم میشوند. تنها نکتهی قابل توجه مربوط به رفتار سیستم با شمارهی تفصیلی و شمارهی مرکز است؛ واضح است که شمارهی تفصیلی در بین تفصیلیهای سرگروه نمیتواند تکراری باشد و به همین دلیل تعیین یک شمارهی ثابت به عنوان مقدار مورد نظر کمکی به ما نخواهد کرد. به همین دلیل در محاوره گفته شده که "شمارهی تفصیلی جدید: بزرگترین شمارهی تفصیلیهای همگروه + یک". همین رفتار در تعیین شمارهی مرکز نیز پیادهسازی شده است.