چنانچه در هریک از مراحل نصب یا کاربری نرم‌افزارها به مشکلی برخورد کرده‌اید یا هر سوال، اشکال یا ابهامی در این زمینه دارید، می‌توانید پاسخ خود را ابتدا در مطالب موجود جستجو و در صورت لزوم به عنوان یک مبحث جدید مطرح کنید، تا کارشناسان پشتیبانی به آن پاسخ دهند.

به منظور ثبت سوال جدید و یا پاسخ به موضوعات موجود، ابتدا می بایست از طریق صفحه مربوطه به سامانه وارد شوید. چنانچه نام کاربری دریافت نکرده اید، به صورت رایگان و از طریق صفحه مربوطه، ابتدا در سامانه ثبت نام نمایید.

قبليقبلي Go to previous topic
بعديبعدي Go to next topic
آخرين ارسال 07 مرداد 1399 04:36 ب.ظ توسط روزبه
وب سرویس ورود اطلاعات از خارج از محیط نرم‌افزار یکپارچه مالی نوسا (API Server) - ابزار جدید در نسخه 9.02
�4 پاسخ
مرتب:
شما مجاز به پاسخ به اين پست نمي باشيد.
مولف پيغام ها
روزبه
کاربر با تجربه
کاربر با تجربه

--
06 مرداد 1399 12:32 ب.ظ

    وب سرویس ورود اطلاعات از خارج از محیط نرم‌افزار یکپارچه مالی نوسا (API Server)

    ابزار قابل خرید آماده شده در نسخه 9.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 ممکن است همان نرم‌فاف

    افزاری باشد که کاربر به صورت مستقیم با آن کار می‌کند (مثل کلاینت سیستم مالی یکپارچه) و یا در مقابل ممکن است خود در مقام سرور برای یک سیستم دیگر قرار داشته باشد – مثل سرور یک سیستم گردش کار که در نقش Client به SOAP Server سیستم مالی متصل شود و سند جدید تنظیم نماید.

    یکی از اجزاءِ مهم سیستم مالی نوسا XP، از قبل، SOAP Server بوده است که عملا یک Web Service است – اما بیشتر با هدف استفاده توسط کلاینت نوسا طرح و پیاده‌سازی شده بود. وجود این نوع سرور در کنار قابلیت کلاینت نوسا برای اتصال به آن باعث شده که ارتباط کلاینت و سرور با پروتکل SOAP و به صورت Web Based میسر باشد – سرور و کلاینت نوسا، هر جای شبکه‌ی اینترنت که قرار داشته باشند، به صرف اینکه URL سرور برای کلاینت شناخته شده باشد و کلاینت هم به اینترنت متصل باشد می‌توانند به هم متصل شوند و به تبادل اطلاعات بپردازند.

    اما به جز کاربرد متداول فوق، برای اینکه استفاده از سرویس‌های برگزیده‌ی نوسا، نه لزوما توسط کلاینت بلکه توسط سایر نرم‌افزارها (و به خصوص سایر سرورها) نیز میسر باشد باید سرویس‌های مزبور را به صورت متدهایی از Web Service پیاده کنیم و در اختیار سایرین قرار دهیم. این عمل به تدریج برای سرویس‌های برگزیده‌ی نوسا انجام خواهد شد – سرویس‌هایی که پیش‌بینی می‌کنیم بیشترین کاربرد را داشته باشند. به عنوان شروع متدهایی برای ایجاد تفصیلی (عملا ترکیبی از اطلاعات تلفن و نشانی، تفصیلی و مرکز مصرف یا تامین کالا یا خدمات) و ایجاد سند حسابداری را پیاده‌سازی کرده‌ایم و در این مستند شرح خواهیم داد. این متدها اسامی و پارامترهای استانداردی دارند که در بخش‌های بعدی شرح داده خواهد شد. هر سیستم نرم‌افزاری که SOAP Client را به نحوی پشتیبانی نماید می‌تواند با اندکی عملیات آماده‌سازی از این متدها استفاده کند. نمونه‌هایی با html/java script، php، Delphi و C# آماده کرده‌ایم که توضیح استفاده آن‌ها در ادامه این مستند و فایل‌های مرتبط به هر یک در بخش فایل و مستندات قابل دریافت می‌باشد. این نمونه‌ها نحوه‌ی اجرای متدها را برای برنامه‌نویسان سایر سیستم‌ها بازنمایی می‌کنند.

     

    فعال‌سازی و اعتبار

    استفاده از سرویس‌های جدیدی که در این مستند به آنها پرداخته‌ایم نیاز به وجود وب سرویس SOAP و وب سرور API در قفل مشتری دارد و در صورتی که مشتری ار SOAP استفاده می‌کند نیازی به عملیات نصب جداگانه ندارد – همانطور که پیش از این اشاره کردیم، سیستم نوسا از قبل سرور SOAP داشته است و امکانات جدید صرفا به همان سرور اضافه شده‌اند.

    مدل ارائه‌ی این سرویس توسط شرکت نوسا مبتنی بر 1) فعال سازی قفل سخت‌افزاری و 2) خرید اعتبار (شارژ کردن قفل سخت‌افزاری) است. هر یک از متدهای Web Service، حسب مورد، به میزانی از اعتبار مذکور را مصرف می‌کنند. در حال حاضر هر سطر از سند حسابداری یک واحد اعتبار و هر ترکیب تلفن و نشانی، تفصیلی و مرکز 5 واحد اعتبار مصرف می‌کند.

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

    با کمتر شدن میزان اعتبار از یک حد مشخص، میزان اعتبار باقی‌مانده همزمان با انتخاب پایگاه (Login) به برخی از کاربران (به عنوان هشدار) اطلاع داده می‌شود. میزان اعتبار هشدار در Admin و به عنوان بخشی از تنظیمات سرور تعیین می‌شود:

     

     

    مطابق آنچه در محاوره‌ی فوق تنظیم شده است، اگر اعتبار Web Service از یک‌هزار واحد کمتر شود همزمان با Login هشدار داده می‌شود. طبیعی است که ارائه‌ی این هشدار به همه‌ی کاربران مطلوب نیست. برای تعیین کاربرانی که قرار است این هشدار را دریافت کنند یکی از اختیارات کاربران را پیش‌بینی کرده‌ایم:

    امکانات / سیستم / مدیریت (Admin) / دریافت هشدار اعتبار Web Service

     

    احراز هویت کاربر و اختیارات وی

    نرم‌افزارهایی که قصد دارند از Web Service استفاده کنند باید قاعدتا در SOAP Server، Login کنند. این عمل با تعیین نام کاربر و کلمه‌ی عبور انجام می‌شود. در همه‌ی زبان‌های برنامه‌سازی (که برای نوشتن کلاینت بکار می‌روند) امکاناتی برای تعیین آنها تعبیه شده است:

     

    Java Script:
      sendSoapRequest(
        document.getElementById("edt_ServerURL").value,
        document.getElementById("edt_UserName").value,
        document.getElementById("edt_Password").value,
        "WS_AddDet", AParams, true,
        function (ARes) {
          document.getElementById("lbl_Result").innerText = ARes;
        });
    
    php:
        function callAccXPSoap()
        {
        :
          $userName = $_POST['edt_UserName'];
          $password = $_POST['edt_Password'];
          :
          $options = array(
            'login' => $userName,
            'password' => $password
          );
          :
          $client = new SoapClient($srvUri, $options);
          $callResult = $client->__soapCall($_POST['edt_Method'], $params);
        }
    
    Delphi:
      with TAccXPSoapCltCaller.Create(cb_Https.Checked, edt_Host.Text) do
      try
        InitConn(edt_UserName.Text, edt_Password.Text);
        try
        :
        finally
          DoneConn;
        end;
      finally
        Free;
      end;
    
    C#:
    using (AccXpSoapClient soapClient = new AccXpSoapClient(cb_Https.Checked, tb_Host.Text))
    {
      soapClient.Initialize(tb_UserName.Text, tb_Password.Text);
      :
    }
    

     

    این پارامترها (نام کاربر و کلمه‌ی عبور) برای اتصال به Web Server (مثلا IIS) بکار می‌روند و در نهایت کاربر به سرور SOAP نوسا متصل خواهد شد. از اینجا به بعد کاربر تفاوتی با کاربران عادی سرور نوسا نخواهد داشت و همانند آن کاربران باید قابل شناسایی باشد؛ یعنی به عنوان کاربر رایانه‌ی سرور یا کاربر domain تعریف شده باشد و همچنین به عنوان یکی از کاربران به پایگاه اطلاعاتی معرفی شده باشد. به این ترتیب از نظر احراز هویت و تعیین امکانات، به امن‌ترین شیوه‌ی ممکن عمل شده است و روش کار بسیار شبیه خواهد شد به احراز هویت کاربرانی که از کلاینت SOAP اصلی نوسا استفاده می‌کنند. البته افزایش امنیت ارتباط http (مثلا با استفاده از پروتکل https) هم در این عملیات مطرح است که طبق معمول کاربران را به آن توصیه می‌کنیم.

    دیدیم که کاربرانی که قرار است از Web Service استفاده کنند باید در پایگاه اطلاعاتی تعریف شوند. در همانجا اختیارات این کاربران نیز باید به صورت عادی تعیین شود. مثلا برای ایجاد سند حسابداری، کاربر Web Service باید اختیار " تنظیم سند حسابداری جدید در تاریخ دلخواه " را داشته باشد. همچنین اگر قرار باشد سند حسابداری را در بخش‌هایی به جز بخش‌های کاربر تنظیم کند، باید اختیار " تنظیم سند حسابداری جدید در تاریخ دلخواه برای سایر بخش‌ها " را نیز داشته باشد.

    به صورت مشابه، برای افزودن ترکیب تلفن و نشانی، تفصیلی و مرکز، کاربر Web Service باید حسب مورد برخی یا تمامی اختیارات زیر را داشته باشد:

    • افزودن تلفن و نشانی جدید
    • تعریف تفصیلی جدید
    • تعریف یا اصلاح تفصیلی غیروابسته به بخش (اگر قصد دارد تفصیلی مستقل از بخش تعریف کند)
    • تعریف یا اصلاح تفصیلی سایر بخش‌ها (اگر قصد دارد برای بخش‌هایی به جز بخش‌های کاربر تفصیلی تعریف کند)
    • تعریف مرکز جدید

    موارد فوق شامل اختیارات مشترک بین کاربران عادی و کاربران Web Service بودند. به جز آنها، اختیارات اختصاصی برای اجرای عملیات از طریق Web Service هم پیش‌بینی شده‌اند که عملا مشخص کننده‌ی این هستند که کاربر اصلا حق دارد به عنوان کلاینت Web Service ایفای نقش نماید یا خیر:

    امکانات / سیستم / مدیریت (Admin) / افزودن تفصیلی از طریق 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 است:

     

     

    تعیین تاریخ

    نرم‌افزارهایی که قصد دارند از Web Service استفاده کنند باید قاعدتا در SOAP Server، Login کنند. این عمل با تعیین نام کاربر و کلمه‌ی عبور انجام می‌شود. در همه‌ی زبان‌های برنامه‌سازی (که برای نوشتن کلاینت بکار می‌روند) امکاناتی برای تعیین آنها تعبیه شده است:

     

     

    همانطور که گفته شد فقط یکی از این دو 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 داده نشود.

    فیلدهای دفتر تلفن و نشانی، تفصیلی و مرکز نیز به همین صورت و با استفاده از "نحوه‌ی عمل" و مقدار مورد نظر در الگو تنظیم می‌شوند. تنها نکته‌ی قابل توجه مربوط به رفتار سیستم با شماره‌ی تفصیلی و شماره‌ی مرکز است؛ واضح است که شماره‌ی تفصیلی در بین تفصیلی‌های سرگروه نمی‌تواند تکراری باشد و به همین دلیل تعیین یک شماره‌ی ثابت به عنوان مقدار مورد نظر کمکی به ما نخواهد کرد. به همین دلیل در محاوره گفته شده که "شماره‌ی تفصیلی جدید: بزرگترین شماره‌ی تفصیلی‌های هم‌گروه + یک". همین رفتار در تعیین شماره‌ی مرکز نیز پیاده‌سازی شده است.

    روزبه
    کاربر با تجربه
    کاربر با تجربه

    --
    06 مرداد 1399 02:55 ب.ظ

    تعریف اطلاعات تلفن و نشانی، تفصیلی و مرکز مصرف یا تامین کالا و خدمات

    متد WS_AddDet در Web Service ارائه شده و قابل اجرا است. این متد می‌تواند ترکیبی از همه‌ی اطلاعاتی که برای یک "شخص" در سیستم مالی نوسا پیش‌بینی شده‌اند را دریافت کند و داده‌های مربوط را در پایگاه اطلاعاتی درج نماید. همانطور که پیش از این اشاره کردیم، اطلاعات ورودی به صورت یک XML با شمای کلی زیر دریافت می‌شوند:

     

     

    همانطور که مشاهده می‌شود، در این XML، root فاقد داده‌ی اختصاصی است و صرفا برای مجتمع کردن سایر nodeها تعریف می‌شود. هر یک از nodeها متناظر با یکی از اقلام اطلاعاتی هستند که در این متد قرار است در سیستم درج شوند:

     

     

    هر 3 node حالت اختیاری دارند – یعنی فقط داده‌های متناظر با nodeهای موجود تعریف می‌شوند. بنابراین از همین متد می‌توان مثلا فقط برای تعریف تفصیلی جدید (بدون مرکز یا اطلاعات تلفن و نشانی) هم استفاده کرد. در صورتی که بیش از یک node وجود داشته باشد، ارتباطات قابل تصور در بین داده‌ها به صورت زیر توسط سیستم برقرار می‌شوند:

    • اگر هر دو node دفتر تلفن و نشانی و تفصیلی وجود داشته باشند، تفصیلی ایجاد شده به سطر دفتر تلفن و نشانی ایجاد شده مربوط خواهد شد.
    • اگر هر دو node تفصیلی و مرکز وجود داشته باشند، مرکز ایجاد شده به تفصیلی ایجاد شده مربوط خواهد شد.

    اختیارات کاربران برای استفاده از این متد قبلا در فصل احراز هویت کاربران توضیح داده شده است.

    تغییراتی که این متد در پایگاه اطلاعاتی اعمال می‌کند حالت "همه یا هیچ" دارند؛ یعنی اگر در خلال اجرای متد، مثلا پس از درج سطر دفتر تلفن و نشانی، در حین درج تفصیلی با خطایی مواجه شویم، سطر دفتر تلفن و نشانی نیز حذف (Undo) خواهد شد. به عبارت دیگر اگر در مراحل مختلف عملیات با خطا مواجه شویم هیچ تغییری در داده‌ها ایجاد نخواهد شد (حتی تغییرات مربوط به مراحل قبلی). خطاهایی که ممکن است در این متد گرفته شوند قبلا در فصل اجرای متدها ذکر شده‌اند.

    attributeهای هر یک از nodeهایی که در این متد دخالت دارند در ادامه شرح داده می‌شوند. موارد مربوط به سطر دفتر تلفن و نشانی (_ABRec) به صورت زیر هستند:

     

     

    attributeهای IsFirm، Gender، FirmKind، GeoLocCode و Kind169 تحت تاثیر الگوی تعیین خودکار داده‌ها قرار می‌گیرند.

    _DetL شامل attributeهای زیر است:

     

     

    attributeهای ParentCode، Num، DeptF و DeptCode تحت تاثیر الگوی تعیین خودکار داده‌ها قرار می‌گیرند. در این داده‌ها نکات زیر قابل توجه هستند:

    • ParentCode باید کد یک تفصیلی غیرعملیاتی موجود باشد.
    • خالی بودن ParentCode (پس از تاثیر الگو) به معنی تعریف تفصیلی در ریشه‌ی درخت تفصیلی‌ها است؛ یعنی به صورت تفصیلی عملیاتی بدون سرگروه. این تفصیلی از کلاس "متفرقه" خواهد بود.
    • شماره‌ی تفصیلی حتما باید تعیین شود – خواه در XML و خواه توسط الگو.
    • اگر تفصیلی سرگروه تعیین شده باشد و آن تفصیلی وابسته به بخش باشد، به DeptF و DeptCode توجه نمی‌شود: تفصیلی جدید نیز همواره وابسته به بخش خواهد بود و کد بخش تفصیلی سرگروه به جای DeptCode برای تفصیلی جدید لحاظ می‌شود.

     

    _ICL شامل attributeهای زیر است:

     

     

    attributeهای ParentCode، Num، موارد مربوط به نقش، SalesCGCode و DebSide تحت تاثیر الگوی تعیین خودکار داده‌ها قرار می‌گیرند. در این داده‌ها نکات زیر قابل توجه هستند:

    • ParentCode باید کد یک مرکز غیرعملیاتی موجود باشد.
    • خالی بودن ParentCode (پس از تاثیر الگو) به معنی تعریف مرکز در ریشه‌ی درخت مراکز است؛ یعنی به صورت مرکز عملیاتی بدون سرگروه.
    • شماره‌ی مرکز حتما باید تعیین شود – خواه در XML و خواه توسط الگو.
    • اگر هیچیک از نقش‌ها (در XML و پس از تاثیر الگو) علامت‌گذاری نشده باشند به صورت پیش‌فرض نقش‌های مصرف و تامین کالا برای مرکز لحاظ خواهد شد.
    روزبه
    کاربر با تجربه
    کاربر با تجربه

    --
    07 مرداد 1399 04:04 ب.ظ

    درج سند حسابداری

    متد WS_AddArt در Web Service ارائه شده و قابل اجرا است. این متد همه‌ی اطلاعات یک سند حسابداری را به صورت یک XML دریافت می‌کند و همزمان سند و سطرهای آن (رخدادهای مالی) را در پایگاه اطلاعاتی درج می‌کند. همانطور که پیش از این اشاره کردیم، اطلاعات ورودی به صورت یک XML با شمای کلی زیر دریافت می‌شوند:

     

     

     

    همانطور که مشاهده می‌شود، در این XML، root در نقش سند حسابداری است و به همین دلیل مشخصات عمومی سند به صورت attributeهای همین node ذکر می‌شوند. به ازای هر یک از سطرهای سند یک node به نام _Trans وجود خواهد داشت. یک سند می‌تواند به تعداد دلخواهی سطر داشته باشد.

     

     

    اختیارات کاربران برای استفاده از این متد قبلا در فصل احراز هویت کاربران توضیح داده شده است.

    تغییراتی که این متد در پایگاه اطلاعاتی اعمال می‌کند حالت "همه یا هیچ" دارند؛ یعنی اگر در خلال اجرای متد، در مراحل مختلف عملیات با خطا مواجه شویم هیچ تغییری در داده‌ها ایجاد نخواهد شد (خود سند یا سطرهای قبلی که خطا نداشته‌اند باقی نخواهند ماند). خطاهایی که ممکن است در این متد گرفته شوند قبلا در فصل اجرای متدها ذکر شده‌اند.

    attributeهای مربوط به خود سند (_Art) به صورت زیر هستند:

     

     

    attributeهای Date، DeptCode، Kind و State تحت تاثیر الگوی تعیین خودکار داده‌ها قرار می‌گیرند. نکات زیر قابل توجه هستند:

    • با استفاده از الگو صرفا می‌توان تاریخ سند را به تاریخ روز تبدیل کرد.
    • اگر سند در وضعیت عملیاتی به Web Service معرفی شود ولی جمع مبالغ بدهکار و بستانکار سطرهای آن با هم برابر نباشند به وضعیت پیش‌نویس تبدیل می‌شود.
    • یک گزینه برای ایجاد سند، همیشه در وضعیت پیش‌نویس (مستقل از State) در الگو تعبیه شده است.
    • ImpId یک عدد غیرتکراری است که به صورت اختیاری در سند درج می‌شود. از این عدد می‌توان برای ممانعت از تنظیم سند تکراری استفاده کرد. به این منظور نرم‌افزاری که از Web Service استفاده می‌کند می‌تواند مکانیزمی برای تعیین ImpId فراهم کند و حاصل را به سرور نوسا ارسال نماید. اگر یک سند با همان ImpId از قبل در پایگاه اطلاعاتی درج شده باشد عملیات با خطای "سند تکراری" مواجه خواهد شد. اگر ImpId داده نشود، سیستم یک عدد تصادفی را تولید و به عنوان ImpId در سند درج می‌کند. همان عدد به عنوان بخشی از نتیجه در <_RSLT/> (XML حاصله) گزارش می‌شود تا احیانا توسط نرم‌افزارمبداء سند (برای شناسایی سند و ممانعت از افزودن تکراری آن) مورد استفاده قرار گیرد.‌فزا

    attributeهای موجود در هر یک از سطرهای سند (رخدادهای مالی) به صورت زیر هستند:

     

     

    attributeهای AccCode، Det1-5Code، CurrCode و UnitCode تحت تاثیر الگوی تعیین خودکار داده‌ها قرار می‌گیرند. کدهای واحد پول و واحد مقدار فقط درصورتی مورد توجه قرار می‌گیرند که مبلغ ارز یا مقدار (تعداد) تعیین شده باشند. همچنین اگر به هر دلیلی (در XML یا تحت تاثیر الگو) کدهای واحد پول و یا مقدار حذف یا صفر شوند مبلغ ارز یا مقدار (تعداد) هم در سطر سند درج نخواهند شد.

    روزبه
    کاربر با تجربه
    کاربر با تجربه

    --
    07 مرداد 1399 04:22 ب.ظ

    Html / Java Script Client

    به عنوان نمونه‌ی اجرای متدهای Web Service از کد Java Script، فایل‌های زیر آماده شده و در بخش فایل و مستندات قابل دریافت می‌باشد:

     

    AccXPSoapClt.js                 کدهای کتابخانه‌ای به زبان js برای اجرای متدها

    AccXPSoapAddDet.html     یک پیاده سازی کامل از افزودن ترکیب دفتر تلفن و نشانی، تفصیلی و مرکز

    AccXPSoapAddArt.html      پیاده‌سازی افزودن سند حسابداری به صورت نمونه با 1 تا 4 سطر

     

     

    بدیهی است که هر دو فایل html حاوی اندکی کد Java Script نیز هستند و در نهایت با استفاده از توابع نوشته شده در فایل js اقدام به اجرا می‌کنند. سعی شده که تمامی attributeها در این پیاده‌سازی لحاظ شوند. توجه کنید که فایل‌های فوق صرفا به عنوان نمایش قابلیت‌های استفاده از Web Service آماده شده‌اند و اگرچه با استفاده از آنها می‌توان اقدام به تعریف اشخاص جدید یا تنظیم سند حسابداری نمود اما هدف اصلی این نبوده است – بلکه بازنمایی روش اجرا از کدهای Java Script مد نظر بوده است؛ با این پیش‌بینی که شاید برخی از سرورها یا نرم‌افزارهایی که قرار است از سیستم ما استفاده کنند، مثلا با node.js پیاده‌سازی شده باشند. به جز این، در سایر نمونه‌هایی که در ادامه ذکر کرده‌ایم (php، دلفی، C#) از قبل توابع کتابخانه‌ای مناسب برای ارتباط با سرورهای SOAP در زبان برنامه‌سازی موجود بوده‌اند – اما Java Script چنین مشخصه‌ای ندارد. توابع کتابخانه‌ای سوم شخص موجود هم بسیار پیچیده بوده‌اند. به همین دلیل سعی کردیم که یک محیط ساده ولی کارآمد برای اجرا از Java Script آماده کنیم و نمونه‌هایی از نحوه‌ی استفاده از آنرا هم ایجاد کنیم.

    فایل‌های html فوق کامل‌ترین پیاده‌سازی از بین نمونه‌های ما هستند – همه‌ی فیلدها به تفکیک در ui آمده‌اند و XML از روی آنها تولید شده است (همان XMLای که به عنوان Data باید به سرور SOAP ارسال شود). در نمونه‌هایی که با سایر زبان‌ها آماده کرده‌ایم چنین رویکردی را نداشته‌ایم و کل XML را در یک متن از کاربر دریافت کرده‌ایم.

    شکل‌های زیر htmlهای پیش‌گفته را در یک مرورگر نشان می‌دهند:

     

     

     

    همانطور که در شکل‌ها دیده می‌شود، تعداد زیادی المان html برای دریافت اطلاعات تعبیه شده‌اند و یک پانل برای اجرا در قسمت پایین سمت چپ دیده می‌شود. این پانل را در شکل زیر در اندازه‌ی بزرگتر مشاهده می‌کنید:

     

     

    آدرس سرور در شروع کار به صورت خودکار ایجاد می‌شود؛ پروتکل (http یا https) و نام Host (در اینجا localhost) از آدرسی که در ابتدا برای باز شدن html وارد شده است استخراج می‌شوند. به صورت پیش‌فرض سرور SOAP نوسا در یک فولدر به نام AccXPSOAP نصب می‌شود که همان پیش‌فرض در اینجا هم آمده است.

    همانطور که پیش از این اشاره کردیم، برای اجرای متد از Web Service نیاز به احراز هویت کاربر داریم. نام کاربر و کلمه‌ی عبور به همین منظور باید در اینجا وارد شوند. به یاد داریم که این کاربر باید کاربر رایانه‌ی سرور یا کاربر domain باشند و قبلا در پایگاه اطلاعاتی مقصد به عنوان یک کاربر تعریف شده باشد و امکانات و اختیارات وی نیز تعیین شده باشند. آخرین دریچه برای تعیین نام پایگاه تعبیه شده است. نام همه‌ی پایگاه‌های سیستم مالی نوسا با _AccXP_ آغاز می‌شود.

    تکمه‌هایی برای اجرای متد و پاک کردن فیلدها هم در پنل فوق تعبیه شده‌اند. پس از اجرا، نتیجه‌ی عملیات (همان _RSLT XML) در ناحیه‌ای که به همین منظور پیش‌بینی شده است بازنمایی خواهد شد.

    تکمه‌ی "اجرا (افزودن)" در html افزودن تفصیلی منجر به اجرای تابع زیر می‌شود:

     

    function Run()
    {
      var AParams = new Array();
    
      addParam(AParams, "ADBName", document.getElementById("edt_DBName").value);
      addParam(AParams, "AData", XMLData());
    
      sendSoapRequest(
        document.getElementById("edt_ServerURL").value,
        document.getElementById("edt_UserName").value,
        document.getElementById("edt_Password").value,
        "WS_AddDet", AParams, true,
        function (ARes) {
          document.getElementById("lbl_Result").innerText = ARes;
        });
    }
    
    روزبه
    کاربر با تجربه
    کاربر با تجربه

    --
    07 مرداد 1399 04:36 ب.ظ

    اصل عملیات در تابع sendSoapRequest انجام می‌شود (که در AccXPSoapClt.js نوشته شده است). این تابع URL سرور، نام کاربر، کلمه عبور، نام متدی که قرار است اجرا شود و پارامترهای متد را دریافت می‌کند. پارامتر بعدی که به صورت true در کد فوق مشاهده می‌شود تعیین کننده‌ی Async بودن اجرای متد است. در این شیوه‌ی اجرا، مرورگر تا بازگشت نتیجه از سرور مکث نمی‌کند و به جای آن یک تابع دریافت می‌کند تا هر زمان که نتیجه آماده شد آن تابع را با همان نتیجه اجرا کند. در اینجا صرفا متن نتیجه (که حاوی _RSLT XML است) را در المان lbl_Result بازنمایی کرده‌ایم.

    متد WS_AddDet دو پارامتر دارد که به صورت یک array آماده شده‌اند. پارامتر اول نام پایگاه اطلاعاتی و پارامتر دوم XML Data است. تابع XMLData به صورت زیر در همین فایل html نوشته شده است:

     

    function XMLData()
    {
      var AnABRecXML =
        _FieldAttr('Name', 'edt_ABName') +
        _FieldAttr('Surname', 'edt_SurnameFirm') +
        _FieldAttr('OSurname', 'edt_OSurnameFirm') +
        _FieldAttr('OName', 'edt_ABOName') +
        _FieldAttr('IsFirm', 'edt_IsFirm') +
        :
    
      var ADetXML =
        _FieldAttr('ParentCode', 'edt_ParentCode') +
        _FieldAttr('Num', 'edt_Num') +
        _FieldAttr('Name', 'edt_Name') +
        _FieldAttr('OName', 'edt_OName') +
        :
    
      var AnICXML =
        _FieldAttr('ParentCode', 'edt_ICParentCode') +
        _FieldAttr('Num', 'edt_ICNum') +
        _FieldAttr('Name', 'edt_ICName') +
        _FieldAttr('OName', 'edt_ICOName') +
        :
    
      var AnXML = '<Data>\n';
    
      if (AnABRecXML != '') AnXML += '<_ABRec ' + AnABRecXML + '/>\n';
      if (ADetXML != '') AnXML += '<_DetL ' + ADetXML + ' />\n';
      if (AnICXML != '') AnXML += '<_ICL ' + AnICXML + '/>\n';
      AnXML += '</Data>';
    
      return AnXML;
    }

     

    آماده کردن XML با کمک تابع _FieldAttr (از AccXPSoapClt.js) انجام شده است که محتوای یک input را به یک attribute تبدیل می‌کند. به صورت مشابه در اجرای تنظیم سند حسابداری به صورت زیر عمل شده است:

     

    function Run()
    {
      : همان
      sendSoapRequest(
        :
        "WS_AddArt", AParams, true,...);
    }
    

     

    تشکیل XML سند هم به صورت مشابهی با استفاده از توابع زیر انجام شده است:

     

    function TransXMLData(N)
    {
      var aTransXML =
        _FieldAttr('AccCode', 'edt_Acc_' + N) +
        _FieldAttr('Det1Code', 'edt_Det1_' + N) +
        :
    
      return aTransXML;
    }
    
    function XMLData()
    {
      var AnArtXML =
        _FieldAttr('FA_Date', 'edt_FADate') +
        _FieldAttr('LA_Date', 'edt_LADate') +
        _FieldAttr('Desc', 'edt_Desc') +
        :
    
      var AnXML = '';
      var ATransXML = '';
      var i;
    
      if (AnArtXML != '')
      {
        AnXML += '<_Art ' + AnArtXML + '>\n';
        for (i = 1; i <= 4; i++) {
          ATransXML = TransXMLData(i);
          if (ATransXML != '') AnXML += '<_Trans ' + ATransXML + ' />\n';
        }
    
        AnXML += '</_Art>';
      }
      return AnXML;
    }

     

    برای استفاده از این پیاده‌سازی نمونه لازم است تا فایل‌های html و js را در همان سرور Webی که سرور SOAP نوسا در آن نصب شده است قرار دهید و با پروتکل http (یا https) آنها را در مرورگر باز کنید. این وضعیت ناشی از ویژگی مرورگرها در ممانعت از عملیات Cross Origin است (همان ویژگی که منجربه خطای CORS می‌شود – که احتمالا برنامه‌نویسان Web بسیار با آن برخورد کرده‌اند). چنین است که اگر از یک سرور (host name) یک صفحه html را باز کنیم و از داخل آن بخواهیم داده‌هایی را از یک سرور دیگر (با host name متفاوت) مثلا با پروتکل SOAP بخوانیم خطای CORS پیش می‌آید.

    یادآوری می‌کنیم که محتویات فایل‌های html صرفا برای بازنمایی امکانات، آماده شده‌اند – اما فایل AccXPSoapClt.js و توابع موجود در آن به احتمال زیاد کاربرد عمومی‌تری خواهند داشت.

    شما مجاز به پاسخ به اين پست نمي باشيد.