كيف تبني إضافة SAP Business One: ‏UI API أم DI API أم Service Layer، وكيف تسلّمها

يغطي SAP Business One العمليات القياسية جيدًا، لكن لكل شركة بضع خطوات لا تتعامل معها الشاشات القياسية: مسح الأصناف ضوئيًا إلى مذكرة تسليم، أو موافقة مخصصة، أو احتساب عمولة، أو ربط بالفوترة الإلكترونية، أو سجل مكالمات بجانب بطاقة العميل. الإضافة هي الطريقة التي تضيف بها هذه الخطوات دون مغادرة SAP Business One.

يشرح هذا الدليل كيف تُبنى الإضافات اليوم، وأي واجهة برمجية تُستخدم لأي غرض، وكيف تسلّم إضافة يثق بها المستخدمون.

ما هي الإضافة

الإضافة برنامج منفصل يشغّله SAP Business One عندما يسجّل المستخدم دخوله. يتصل بالعميل أثناء تشغيله ويمكنه:

• إضافة قوائم وشاشات أصلية تبدو وتعمل مثل نماذج SAP القياسية،
• التفاعل مع الأحداث في الشاشات القياسية، مثلًا عندما يضيف مستخدم أمر بيع،
• قراءة بيانات العمل وكتابتها عبر كائنات العمل الخاصة بـ SAP، مع الفحوص نفسها التي يجريها العميل.

لا يثبّت المستخدمون أي شيء بأنفسهم. تُسجَّل الإضافة مرة واحدة ويوزّعها SAP Business One على كل محطة عمل.

الواجهات البرمجية الثلاث ومتى تستخدم كلًّا منها

تستخدم إضافة العميل النموذجية UI API للشاشة وDI API للبيانات، وتحصل على اتصال DI من UI API فتتشارك جلسة المستخدم وترخيصه. أما المنطق الذي يجب أن يعمل دون تسجيل دخول مستخدم (مزامنة ليلية، أو بوابة، أو طابور فوترة إلكترونية) فمكانه الخادم، ويتعامل مع Service Layer بدلًا من ذلك.

قراءة البيانات باستعلامات SQL مقبولة، وغالبًا هي أسرع طريقة لملء الشاشة. أما الكتابة فيجب أن تمر عبر DI API أو Service Layer ليبقى المخزون وقيود اليومية والموافقات وسجل التغييرات صحيحة.

شاشات أصلية، لا نوافذ منفصلة

يتوقع المستخدمون أن تبدو شاشة الإضافة مثل SAP: الحقول نفسها، وقائمة الاختيار (Choose From List) نفسها، وسلوك لوحة المفاتيح نفسه. تبني UI API نماذج بشبكات وحقول تحرير وقوائم منسدلة وأزرار يرسمها العميل بنفسه. أما نافذة Windows منفصلة تفتحها الإضافة فتبدو غريبة، ولا تتبع إعدادات SAP للمستخدم، وكثيرًا ما يرفضها المستخدمون.

تفصيلتان تجعلان الشاشات الأصلية تبدو صحيحة:

• قائمة الاختيار (Choose From List) في حقول مثل العميل أو الصنف أو الطلب، مصفّاة بما هو منطقي (الطلبات المفتوحة فقط، أو مستندات هذا العميل فقط).
• تجميد النموذج أثناء بنائه أو تحديثه، ليظهر دفعة واحدة بدل أن يُرسم عنصرًا عنصرًا.

خزّن بياناتك في UDF و UDT

تحتاج معظم الإضافات إلى بضعة حقول أو جداول إضافية. يدعم SAP Business One ذلك دون تغيير جداوله:

• الحقول المعرّفة من قِبل المستخدم (UDF) تضيف أعمدة إلى الكائنات الموجودة، مثل حالة الفاتورة الإلكترونية في فاتورة المبيعات أو نسبة العمولة لموظف المبيعات.
• الجداول المعرّفة من قِبل المستخدم (UDT) تحفظ بيانات الإضافة الخاصة، مثل جدول قفل أو سجل أو جدول إعدادات.

أنشئها من الإضافة عند بدء التشغيل (وتجاوز الموجود منها)، لتحصل عليها أي شركة جديدة تلقائيًا. اجعل الأسماء قصيرة: تحدّ SAP أوصاف UDT بـ 30 حرفًا، وقد يمنع الوصف الأطول إنشاء الجدول.

الأحداث: حيث تعيش معظم أخطاء الإضافات

تتفاعل الإضافة مع الأحداث: نقرة على قائمة، أو ضغطة زر، أو تغيير قيمة، أو إضافة مستند. ثلاث قواعد تمنع معظم المشكلات:

1. تعامل مع كل حدث تسجّل له، وصفِّ بحذر. مرشّح الأحداث الذي يستبعد نقرات القوائم يجعل كل قوائم الإضافة تتوقف عن العمل بصمت.
2. ألغِ في حدث «قبل» (before)، ونفّذ في حدث «بعد» (after). لمنع إجراء أو التحقق منه، ألغِه قبل أن يعالجه SAP؛ ولإضافة عمل لاحق، انتظر حتى ينتهي SAP.
3. تذكّر أن البيانات المضافة عبر DI API لا تطلق أحداث الشاشة. إذا كانت إضافة أخرى تتفاعل عندما يضيف مستخدم فاتورة على الشاشة، فلن ترى الفواتير التي ترحّلها إضافتك بالكود.

ترحيل المستندات بأمان

عندما تنشئ الإضافة مستندات، مثل فاتورة من مذكرة تسليم ممسوحة ضوئيًا، فافعل ذلك كما يفعل SAP:

• أسّس المستند الجديد على المستند المصدر (أمر ← تسليم ← فاتورة) لتنتقل الأسعار والضرائب والكميات المفتوحة تلقائيًا.
• استخدم حركة (Transaction) عندما ينشئ إجراء واحد عدة مستندات، فإما أن تُرحَّل كلها أو لا شيء.
• اقرأ كل ما تحتاجه قبل بدء الحركة. البحث الفاشل داخل حركة DI API قد يُفشل التثبيت النهائي (Commit).
• افحص كل رمز إرجاع واعرض رسالة الخطأ الخاصة بـ SAP للمستخدم، لا رسالة عامة مثل «حدث خطأ ما». معنى الرموز الشائعة (-5002 و-1029 و-2035 و-5006) مشروح في رموز أخطاء DI API في SAP B1.

التغليف والنشر عبر Extension Manager

تُسلَّم الإضافات كـ امتدادات (Extensions):

1. ابنِ الإضافة بمعمارية البت نفسها للعميل (64 بت لعملاء SAP Business One 10.0 الحاليين).
2. غلّفها بأداة ExtensionPackage.exe من SDK. الحزمة ملف zip يضم البرنامج وملفاته وملف تسجيل (.ard). ويصبح اسم ملف zip هو اسم الامتداد.
3. في Extension Manager ‏(System Landscape Directory)، استورد ملف zip، وعيّنه للشركة، واختر ما إذا كان يبدأ تلقائيًا للمستخدمين.
4. لإصدار جديد، استورد ملف zip بالاسم نفسه ورقم إصدار أعلى. يعامله Extension Manager كترقية ويحتفظ بالإصدار القديم للتراجع.

استخدم رقم إصدار يتزايد دائمًا، مثل 2026.1021.1530 (السنة والشهر واليوم، ثم الوقت). ولا تغيّر اسم الامتداد أبدًا بعد أول استيراد، وإلا حصل المستخدمون على نسخة ثانية من كل قائمة.

الاختبار قبل أن يراها المستخدمون

• اختبر على نسخة من الشركة، لا على بيئة الإنتاج وحدها أبدًا.
• اختبر بـ مستخدم عادي، لا بحساب المدير فقط؛ فالصلاحيات تغيّر ما يستطيع المستخدمون فعله.
• إذا كنت تدعم قاعدتي البيانات، فاختبر على SQL Server و SAP HANA: يقارن HANA النصوص بحساسية لحالة الأحرف ويستخدم لهجة SQL مختلفة، ما يكسر استعلامات تعمل على SQL Server.
• اكتب ملف سجل على كل محطة عمل. عندما يقول مستخدم «الزر لا يفعل شيئًا»، يجيب السجل خلال دقائق.
• بعد كل ترقية لـ SAP Business One، أعد اختبار الإضافة على النسخة قبل ترقية بيئة الإنتاج.

الأخطاء الشائعة

كيف نبني الإضافات في كودينوفا

نبني إضافات SAP Business One على SQL Server و SAP HANA: شاشات أصلية عبر UI API، وترحيل عبر DI API، وحزم Extension Manager، وسجل على كل محطة عمل. من الأمثلة إضافة اتصالات هاتفية لمصنّع ألماني، وجسر فوترة إلكترونية لـ ZATCA، وبوابة عمولات مبيعات. لكل مشروع سعر ثابت لكل مرحلة، وثلاثة أشهر من الدعم المجاني بعد الإطلاق.

إذا كان العمل ينتمي إلى خارج العميل، مثل بوابة عملاء أو تطبيق جوال، فراجع تطوير SAP Business One ودليل Service Layer.

المصادر

• بوابة SAP Help: توثيق SAP Business One ‏(SDK و DI API و UI API)
• بوابة SAP Help: العمل مع SAP Business One Service Layer ‏(PDF)
• SAP Learning: الاستفادة من SAP Business One Service Layer

خدمات ذات صلة

• تطوير SAP Business One