تربط مرّة، وتوجّه لكل مشروع
الاعتماد يُدخَل مرّة وحدة للحساب كله. وبعدها كل مشروع يرتبط فيه، ويقدر يشير لمستودع أو فريق أو مشروع Jira مختلف.
أغلب التقارير اللي تعدّي الفرز تتحوّل لشغل. وتكامل متتبّع المهام يسدّ الفجوة بين «انلقطت الملاحظة» و«انجدول الشغل»: تربط GitHub Issues أو Linear أو Jira مرّة وحدة، توجّهه للمشاريع اللي تحتاجه، ومن أي تقرير يقدر المُفرِز يفتح تذكرة حقيقية بضغطة. والتقرير يحتفظ برابط رجوع حيّ. وأول ما توجّه webhook متتبّعك لـuMarker، قفل التذكرة ينقل التقرير معها.
تربط مرّة، وتوجّه لكل مشروع
الاعتماد يُدخَل مرّة وحدة للحساب كله. وبعدها كل مشروع يرتبط فيه، ويقدر يشير لمستودع أو فريق أو مشروع Jira مختلف.
تذكرة بضغطة
من التقرير، زرّ إنشاء تذكرة ينقل العنوان والوصف ورابط لقطة موقّع (وعلى GitHub التسميات كمان) لتذكرة جديدة.
الحالة ترجع لك
webhook من المتتبّع ينقل تقرير uMarker مع التذكرة: done ← محلول، reopened ← قيد التنفيذ، و— في GitHub وLinear — cancelled ← مؤرشف.
ما يكرّر، ويفشل نظيف
التقرير المرتبط ما ينربط مرّتين. ولو رفض المتتبّع الطلب، ما ينحفظ شي ناقص، والتقرير يقول لك كذا بكلام واضح. وسبب المتتبّع نفسه ينحفظ على الاتصال.
افتح صفحة التكاملات بالحساب، اختر المزوّد، واتبع الخطوات الموجَّهة. فيه طريقين، واللوحة ما تعرض إلا اللي يشتغل على منصّتك:
وبالطريقين، الوجهة (المشروع ونوع التذكرة، أو المستودع، أو الفريق) تختارها من قائمة تنجاب بدخولك، وما تكتبها أبداً. وuMarker تفحص اختيارك، وتخزّن الاعتماد مشفّراً، وتعلّم الاتصال active.
لمّا يكون مشغّل منصّتك ضابط تسجيل الدخول عند المزوّد (شوف للمشغّلين)، تطلع لك على البطاقة اربط عبر Jira أو اربط عبر GitHub أو اربط عبر Linear:
اضغط اربط عبر …. النافذة تروح لصفحة تسجيل الدخول عند المزوّد.
سجّل دخولك ووافق على الوصول. ترجع للوحة، ومكتوب فيها تم تسجيل الدخول عبر …. اختر أين تُفتح التذاكر.
اختر الوجهة من القوائم:
اضغط اختبر الاتصال، وبعدها ربط.
ولو ما تبغى تسجّل دخول، استخدم رمز API بدلاً من ذلك ينقلك لطريق الرمز تحت. ولو المزوّد مو مضبوط على منصّتك، الزرّ ببساطة ما يطلع، وطريق الرمز هو الوحيد.
uMarker تصادق بتوكن أو مفتاح API تعطيه إيّاه (personal access token، أو مفتاح Linear، أو توكن Jira). اختر مزوّدك عشان تشوف وش ينطلب منك ومن وين تجيب الاعتماد:
| الحقل | القيمة |
|---|---|
| الاعتماد | personal access token (classic أو fine-grained) بصلاحية إنشاء تذاكر في المستودع المطلوب. يُرسَل كـbearer token. |
المستودع (repo) |
تختاره من قائمة المستودعات اللي يوصلها الرمز (وفيها بحث)، مثل acme/webapp. |
التذاكر تُنشأ عبر POST https://api.github.com/repos/{owner}/{name}/issues (نسخة REST API رقم 2022-11-28). والتذكرة الراجعة مفتاحها #<number> ورابطها html_url.
وGitHub هو المزوّد الوحيد اللي ينقل كمان تسميات التقرير للتذكرة (شوف وش ينتقل للتذكرة).
| الحقل | القيمة |
|---|---|
| الاعتماد | مفتاح Linear API. يُرسَل في ترويسة Authorization كما هو (بلا بادئة Bearer). |
الفريق (team_id) |
تختاره من قائمة الفرق اللي يشوفها المفتاح. |
التذاكر تُنشأ عبر GraphQL API حقّ Linear (https://api.linear.app/graphql) بطفرة issueCreate مع عنوان التقرير ووصفه. والتذكرة الراجعة مفتاحها identifier حقّ Linear (مثل ENG-142) ورابطها url.
| الحقل | القيمة |
|---|---|
| الاعتماد | توكن Jira API. يُستخدم مع البريد لمصادقة HTTP Basic. |
البريد (email) |
بريد حساب Atlassian اللي يتبع له التوكن. يجيك معبّى ببريدك في uMarker؛ غيّره بس لو التوكن تابع لحساب Atlassian ثاني. |
موقع Jira (base_url) |
رموز Atlassian ما تقول أي موقع تتبع له، فهذا الشي الوحيد اللي تكتبه. acme يكفي، وacme.atlassian.net أو العنوان كامل يمشون بعد، واللوحة تعرض لك العنوان اللي بتسجّل الدخول عليه. |
المشروع (project_key) |
اضغط اعرض مشاريعي، واختر من قائمة المشاريع اللي يشوفها الرمز. |
نوع التذكرة (issue_type) |
اختياري، تختاره من أنواع التذاكر حقّ ذاك المشروع. يرجع لـTask لو تركته فاضي. |
التذاكر تُنشأ عبر POST {base_url}/rest/api/3/issue بالملخّص ونوع التذكرة ووصف بصيغة Atlassian Document Format. والتذكرة الراجعة مفتاحها مفتاح Jira (مثل MD-45) ورابطها {base_url}/browse/{key}. والاتصال اللي انربط بضغطة ينادي نفس الـAPI عبر https://api.atlassian.com/ex/jira/{cloudId} برمز تسجيل الدخول بدل التوكن.
اللوحة تمشّيك خطوة بخطوة، وبنفس الطريقة لكل مزوّد. وكل خطوة تحتاج الخدمة الثانية فيها رابط مباشر للصفحة بالضبط:
من صفحة التكاملات بالحساب، اضغط ربط على بطاقة المتتبّع. تنفتح اللوحة على خطوات الربط.
اتبع خطوات مزوّدك:
acme يكفي. اضغط اعرض مشاريعي واختر المشروع، ونوع التذكرة لو تبغى.اضغط اختبر الاتصال. uMarker تسوّي فحص دخول حقيقي على المتتبّع باللي قدامك على الشاشة بالضبط (نفس الفحص اللي تحت)، وما تحفظ شي. ولو نجح يظهر تم تسجيل الدخول باسم ومعه اللي وصله: موقع Jira حقّك، أو المستودع، أو Linear.
اضغط ربط. يتفعّل بعد ما ينجح الاختبار؛ ولو غيّرت حقلاً بعد الاختبار، اللوحة تطلب تختبر مجدداً. وفيه احفظ دون اختبار ناجح لو احتجته. الاتصال ينحفظ active والاعتماد مشفّر عند التخزين.
ولو فشل الاختبار، اللوحة تقول لك السبب بلغتك: السبب، وسطر ما العمل: (مثلاً إن الرمز انرفض ويحتاج تستبدله، أو إن المستودع أو المشروع ما انلقى)، ونصّ المتتبّع نفسه مطويّ تحت التفاصيل كما أرسلتها الخدمة، والرمز ممسوح منه.
الاتصال لحاله ما يفتح أي تذكرة. أرفقه بالمشاريع اللي المفروض تستخدمه:
افتح المشروع وروح لتبويب التوزيع.
أرفِق اتصال المتتبّع.
اختيارياً اضبط هدفاً: مستودعاً أو فريق Linear أو مفتاح مشروع Jira ونوع تذكرة غير الافتراضي حقّ الاتصال. الشي الوحيد القابل للتجاوز هو الوجهة؛ أمّا الاعتماد والرابط الأساسي فيبقون على الاتصال. المسار يعني «وين في متتبّعك»، ما يعني أبداً «متتبّع مين».
اختيارياً شغّل الإنشاء التلقائي، فيفتح التقرير الجديد بهذا المشروع تذكرة بلا ما يضغط أحد زرّ. وخلّ تقرير جديد مؤشّراً تحت يستقبل أيّ أحداث — هو مؤشّر افتراضياً، وهو الحدث اللي ينطلق عليه الإنشاء التلقائي.
والاتصال الواحد يخدم أي عدد من المشاريع، وكل واحد يشير لمكان مختلف. وهذا بالضبط اللي تحتاجه وكالة عندها موقع Jira واحد وعشرة مشاريع عملاء.
الاختبار يشتغل في لوحة الربط قبل ما تحفظ (اختبر الاتصال)، ومن إدارة على أي اتصال محفوظ بأي وقت (اختبار الاتصال). ولمّا يحتاج الاتصال مراجعة، بطاقته وإدارة يقولون السبب بكلام واضح مع سطر ما العمل:، والزرّ يصير اختبر مجدداً. وبكل الأحوال يسوّي نداء خفيف للقراءة بس، يتأكّد إن uMarker توصل المتتبّع والوجهة:
| المزوّد | فحص الصحّة |
|---|---|
| GitHub | GET /repos/{owner}/{name}: يتأكّد إن المستودع يوصل بالتوكن. |
| Linear | استعلام GraphQL باسم viewer: يتأكّد إن المفتاح صالح. |
| Jira | GET /rest/api/3/myself: يتأكّد إن البريد والتوكن يصادقون. |
الفصل يحذف الاعتماد المحفوظ. ولو فيه مشاريع توجّه عبره، uMarker ترفض المحاولة الأولى وتسمّيها لك، عشان ما تسكت تذاكر أحد بلا تحذير. أكّد، وينحذف الاتصال ومساراته مع بعض.
والتذاكر المُنشأة سابقاً تبقى مرتبطة: روابط الرجوع على التقارير تظلّ سليمة وقابلة للنقر. اللي يتوقّف هو الإنشاء الجديد بس.
أول ما يصير للمشروع اتصال موجَّه ونشط، افتح أي تقرير واضغط إنشاء تذكرة. والزرّ ما يظهر إلا لمّا يكون للمشروع متتبّع موجَّه فعلاً، لأن زرّاً وظيفته الوحيدة إنه يفشل أسوأ من ما يكون فيه زرّ.
افتح التقرير في صفحة التقرير.
اضغط إنشاء تذكرة. uMarker تبني التذكرة من التقرير وترسلها للمتتبّع الموجَّه.
مع النجاح، يعرض التقرير مفتاح التذكرة الجديدة كـرابط رجوع (مثل #142 أو ENG-142 أو MD-45) يفتح التذكرة الخارجية مباشرة.
| حقل التقرير | وين ينزل |
|---|---|
| العنوان | عنوان GitHub/Linear، وملخّص Jira. الافتراضي: التعليق مقصوصاً على 80 محرف. |
| الوصف / النصّ | نصّ التذكرة (وفي Jira بصيغة Atlassian Document Format). يحمل التعليق ورابط الصفحة ورابط لقطة موقّع ورابط اللوحة. |
| اللقطة | رابط موقّع مضمّن بالنصّ، وما ينحطّ إلا لو كانت اللقطة لا تزال موجودة. وفي الباقة اللي لها نافذة احتفاظ وسائط، الرابط ينتهي معها؛ شوف تحت. |
| التسميات | تسميات التقرير، على GitHub بس. تذاكر Linear وJira ما تستقبل تسميات. |
والنصّ الافتراضي شكله كذا:
Reported via uMarker.
<the report's comment>
Page: https://site/checkoutScreenshot: https://api.umarker.com/… (link valid until 2027-01-12)Open in uMarker: https://app.umarker.com/s/8f2c…/feedback/42سطرا Page وScreenshot ما يظهرون إلا لمّا يكون للتقرير هذي القيم.
uMarker تفحص وجود ارتباط قبل الإرسال، وتعيد الفحص تحت قفل صفّ داخل معاملة قاعدة بيانات، فـما ينربط التقرير بتذكرتين أبداً. ولو ضغط اثنان الزرّ في نفس اللحظة تطلع تذكرة واحدة — الضغطة الثانية تنتظر الأولى وتلقى التقرير مرتبطاً أصلاً. أمّا الإنشاء التلقائي وهو ينطلق بينما أحد يضغط الزرّ فهو الاستثناء الضيّق: الاثنان يقدرون يوصلون للمتتبّع، وما تنربط إلا واحدة من التذكرتين، والثانية تبقى يتيمة تقفلها بيدك. والتقرير المرتبط أصلاً يرجّع لك المفتاح الموجود بدل ما ينشئ غيره.
ولو رفض المتتبّع الطلب، ما ينحفظ شي ناقص (لا مفتاح ولا رابط)، ويقول التقرير للمُفرِز إن التذكرة ما انرفعت، وأي متتبّع رفض، وهل إعادة المحاولة تنفع ولا لا. أمّا سبب المزوّد بالضبط فينحفظ على الاتصال نفسه تحت التكاملات، ويقرأه المدير هناك كآخر خطأ للاتصال:
| ردّ المتتبّع | السبب المحفوظ على الاتصال |
|---|---|
401 / 403 |
<Provider> rejected the credential — reconnect needed. |
404 |
<Provider> destination not found — check your configuration. |
429 |
<Provider> rate limit hit — try again shortly. |
| غيرها | <Provider> returned HTTP <status>. |
واختبار الاتصال لمّا يفشل يسجّل نفس السبب بنفس المكان، فيقدر المدير يعيد إنتاج المشكلة بلا ما ينتظر التقرير الجاي — أو، لو ما جاوب المتتبّع أصلاً، وش منعنا نوصله.
هذا مو ارتباطاً باتجاه واحد. وجّه webhook متتبّعك للرابط المعروض على الاتصال، وقفل التذكرة ينقل تقرير uMarker:
| حدث المتتبّع | التقرير يصير |
|---|---|
تذكرة GitHub closed |
resolved، أو archived لو انقفلت كـnot planned |
تذكرة GitHub reopened |
in_progress |
حالة Linear completed / started / canceled |
resolved / in_progress / archived |
فئة حالة Jira done / indeterminate |
resolved / in_progress |
وJira هي اللي تحتاج تقرأ صفّها مرّتين: هاتان الفئتان هما الوحيدتان اللي تربطهما uMarker، وJira ما فيها فئة cancelled أصلاً. فلو كان سير عملك يحطّ «Cancelled» تحت فئة done، ترجع لك التذكرة resolved مو archived.
ورابط الـwebhook يحمل رمزاً خاصّاً بالاتصال، وما فيه شي في الحمولة يقرّر بيانات مين تنمسّ: الحساب ومجموعة المشاريع يجون من الاتصال، ويتحلّون على الخادم. أمّا من الحمولة نفسها فتقرأ uMarker شيئين: مفتاح التذكرة، وحالة المتتبّع لها. يعني اللي يمسك هذا الرابط يقدر ينقل التقارير المرتبطة بمشاريع ذاك الاتصال، ولا شي وراها. تعامل معه كسرّ: الرمز يُسَكّ وقت إنشاء الاتصال وما فيه زرّ تدوير له، فالطريقة الوحيدة لاستبدال رمز تسرّب هي إنك تفصل المتتبّع وتربطه من جديد — وهذا يحذف مسارات مشاريعه معه. والرمز المجهول يجيه 404؛ والحدث اللي ما تتصرّف عليه uMarker يُقبَل ويُتجاهَل، فما يدخل متتبّعك أبداً في عاصفة إعادة محاولات.
issue_linkedالإنشاء الناجح (غير المكرّر) يُطلق حدث issue_linked لكل وجهة يوجّه لها المشروع (سلاك، تيليجرام، Teams، أو webhook موقّع مشترك بالحدث)، ويرفع كمان إشعاراً داخل المنتج، فالتذكرة اللي تُفتح تلقائياً ما تصير بصمت. شوف Webhooks الصادرة للحمولة، والقنوات والتوجيه للاشتراك.
هذا الجزء لمن يشغّل منصّة uMarker نفسها، مو للمستأجرين. زرّ اربط عبر Jira / GitHub / Linear ما يطلع إلا بعد ما تسجّل تطبيق OAuth عند ذاك المزوّد وتفعّله من كونسول المشغّل. وقبلها، المستأجرين يربطون بالرمز، وما ينعرض لهم شي ميّت.
افتح التكاملات في كونسول المشغّل، ودوّر على تطبيقات OAuth — ربط بنقرة واحدة. كل مزوّد له رابط إعادة التوجيه للتسجيل (كما هو حرفياً) وجنبه زرّ نسخ؛ سجّل هذا الرابط عند المزوّد حرف بحرف. وشكله {APP_URL}/api/integrations/oauth/{provider}/callback.
developer.atlassian.com/console/myapps.read:jira-work وwrite:jira-work وread:jira-user. أمّا offline_access فتطلبه uMarker وقت تسجيل الدخول عشان تقدر تجدّد الرمز.github.com/settings/applications/new.repo.linear.app/settings/api/applications/new.وبعدها فعّل إتاحته للمستأجرين واحفظ. الصفّ يصير مُفعَّل — يظهر الزرّ للمستأجرين؛ والتطبيق المضبوط اللي ما انعرض يصير مضبوط، غير مُتاح، واللي ما له تطبيق غير مضبوط — بالرمز فقط. وسرّ العميل للكتابة فقط: اتركه فاضي بالحفظ اللي بعده عشان يبقى المحفوظ. وكل تغيير ينكتب بسجلّ التدقيق.