חיבור הכלים שלכם בסטודיו, צעד אחר צעד (בלי קוד)

המדריך הזה נכתב לבעלי עסקים שלא עשו את זה מעולם. לא צריך לכתוב קוד. כן צריך להכיר כמה מושגים, ולכן כל מושג מוסבר בפעם הראשונה שהוא מופיע.

כל צילומי המסך הם מהסטודיו (Studio) של הארגון של קו עצמה, בעותק בדיקה, ולכן שום דבר כאן לא שייך ללקוח. נתוני דוגמה. להמחשה בלבד.

צילומי המסך הם מהסטודיו באנגלית. שמות הכפתורים והלשוניות מופיעים כאן באנגלית ובמרכאות, ולידם הסבר בעברית.

התמונה הגדולה בחמש שורות

1. אדם שואל את העוזר שלכם שאלה, באתר או בערוץ אחר.
2. העוזר לא נוגע במערכות שלכם. הוא בוחר יכולת (capability), עבודה קטנה עם שם, כמו "חיפוש הזמנה".
3. היכולת משתמשת במחבר (connector), שהוא קו הטלפון אל הכלי שלכם.
4. הכלי שלכם עונה. התשובה חוזרת כנתונים, ותבנית הופכת את הנתונים למשפט שהאדם קורא.
5. שלושה כללים אף פעם לא זזים. שום דבר מעל שכבת היכולות לא פונה ישירות למערכת שלכם. מי האדם נקבע לפי ההתחברות שלו, לא לפי מה שהוא מקליד בצ'אט. והעוזר לעולם לא כותב מספר בעצמו: סכומים, תאריכים ומספרי אסמכתה מגיעים מהנתונים שלכם.

מי עושה איזה שלב

אנשים שונים מחזיקים במפתחות שונים בסטודיו, וזה מכוון. כך זה נראה בסטודיו עצמו.

שלב	מי יכול לבצע
ליצור מחבר, להפעיל אותו ולשייך אליו יכולת	מהנדס אינטגרציה (integration engineer) או מנהל העיר (city administrator)
לשמור את הסיסמה או המפתח של מחבר	מנהל העיר בלבד. לא מהנדס האינטגרציה
לכתוב כלל כטיוטה	מהנדס אינטגרציה או מנהל העיר
לפרסם כלל	מנהל העיר
מודל העוזר, מדיניות התשובות ותקרת ההוצאה	מנהל העיר (הגדרות הארגון)
להגדיר יכולת חדשה לגמרי, או לשנות מה יכולת אומרת	צוות קו (מפעיל הפלטפורמה)
לכתוב הגדרת מחבר לסוג מערכת חדש	צוות קו

אם כפתור אפור ולא לחיץ, הסטודיו אומר במילים איזו הרשאה חסרה. העבירו את השורה הזאת למי שמנהל את התפקידים בארגון שלכם.

שלב 1. המחבר: קו הטלפון אל הכלי שלכם

מחבר (connector) הוא החיבור השמור לאחת המערכות שלכם: איפה היא נמצאת (הכתובת) ואיך נכנסים אליה (פרטי גישה). מופע (instance) של מחבר הוא העותק שלכם.

לפני שמתחילים, צריך לדעת שלושה דברים: איזה שם תרצו לתת לו, מהי הכתובת של ה-API של הכלי שלכם, ומי ישמור את הסיסמה.

1. פתחו את Connectors (מחברים) בתפריט הימני ולחצו על New instance (מופע חדש). האשף נפתח.
2. Step 1 of 3, choose a connector (שלב 1 מתוך 3, בחירת מחבר). הרשימה מציגה כל סוג מערכת שהפלטפורמה כבר יודעת לדבר איתו. בחרו את זה שמתאים לכלי שלכם.
3. Step 2 of 3, connection details (שלב 2 מתוך 3, פרטי החיבור). מלאו את שלוש התיבות שבתמונה.
   • Instance slug (מזהה המופע). שם קצר באותיות לטיניות קטנות, ספרות ומקפים, למשל example-bookings-tool. הוא אף פעם לא משתנה, אז בחרו היטב.
   • Base URL (כתובת הבסיס). הכתובת של ה-API של הכלי שלכם. היא חייבת להתחיל ב-http:// או ב-https://. זה המקום היחיד שבו שגיאת הקלדה מגיעה לכתובת אמיתית ברשת, ולכן הכתובת נבדקת שלוש פעמים.
   • Vault key (מפתח כספת). זה רק השם של המקום שבו הסיסמה תישמר. זו לא הסיסמה. בשום מקום בסטודיו אין תיבה שבה מקלידים סיסמה בטופס של מחבר.
4. Step 3 of 3, review (שלב 3 מתוך 3, סקירה). קראו פעם אחת, ואז צרו את המופע.

שלב 2 באשף, עם ערכי דוגמה. שום דבר לא נשמר.

מה אמורים לראות. המופע החדש מופיע ברשימת המחברים עם התוויות Draft (טיוטה) ו-Mock (דמה). זה תקין ובטוח. מופע חדש לא יכול לקרוא לשום דבר, וזה מכוון.

אם לא רואים את סוג המערכת שלכם בשלב 1. הפלטפורמה מציגה רק מערכות שיש להן כבר הגדרה. סוג מערכת חדש צריך הגדרה שנכתבת על ידי צוות קו, כי הגדרה היא קוד ולא טופס. פנו אלינו. אל תנסו לעקוף.

להפעיל, בכוונה

פתחו את המופע שלכם. בפאנל Lifecycle (מחזור חיים) יש שתי בחירות נפרדות.

• Status (סטטוס): Draft (טיוטה), Active (פעיל) או Suspended (מושהה). רק מופע Active יכול לבצע קריאה בכלל.
• Mode (מצב): Mock עונה מתשובות לדוגמה ששמורות מראש. Record פונה לכלי שלכם ושומר מה שהוא עונה. Live פונה לכלי שלכם באמת.

פאנל Lifecycle. כדי לעבור לחי צריך Active ומצב שאינו Mock.

מעבר לחי פירושו Active ומצב שאינו Mock. הסטודיו מסרב לשילוב הזה אם הוא לא מוצא פרטי גישה שמורים למופע. כל שינוי נשמר כפעולה עם שם וזמן ברשומת הביקורת.

הסיסמה, ולמה אף פעם לא תראו אותה שוב

פתחו את Credentials (פרטי גישה) במופע. תראו שלוש עובדות: שם מפתח הכספת, איפה הוא שמור, וטביעת אצבע (fingerprint) עם זמן שימוש אחרון. טביעת אצבע היא קוד קצר שמוכיח איזה סוד שמור, בלי להציג אותו.

מגירת Credentials. כאן טביעת האצבע היא Not set (לא הוגדר), ולחשבון הזה אסור לשמור ערך.

כדי להכניס את הסוד, מנהל העיר פותח את המגירה הזאת ומשתמש ב-Install or rotate the credential (התקנה או החלפה של פרטי הגישה). הערך נשלח פעם אחת, חתום, ונשמר מוצפן תחת המפתח של הארגון שלכם. אף אחד לא יכול לקרוא אותו בחזרה, ברמת הרשאה כלשהי. החלפה בהמשך רק מציגה לכם טביעת אצבע חדשה.

מה אמורים לראות. טביעת אצבע וזמן "שימוש אחרון" אחרי שמנהל העיר שמר את הערך. Not set אומר שעוד לא נשמר כלום, והמופע לא יכול לפעול ב-Live.

אם זה לא עובד. אם המופע מסרב לעבור ל-Live, פתחו קודם את Credentials. לרוב טביעת האצבע היא Not set. קראו עוד בהפנייה לפרטי גישה שלעולם לא תראו שוב ובמחזור החיים של מחבר.

שלב 2. היכולת: עבודה קטנה אחת שהעוזר יודע לעשות

יכולת (capability) היא עבודה עם שם, קלט ברור ופלט ברור. יש לה שלושה חלקים, שנקראים פנים. רק השלישי הוא שלכם.

1. מה היא אומרת (הניסוח שהעוזר קורא). זהה לכל הארגונים.
2. החוזה (מה נכנס ומה יוצא). זהה לכל הארגונים.
3. איך היא מגיעה לכלי שלכם (איזה מחבר, איזו פעולה). החלק הזה שונה בכל ארגון.

פתחו את Modules and capabilities (מודולים ויכולות), בחרו יכולת, ותראו חמש לשוניות: Semantic (משמעות), Contract (חוזה), Execution (ביצוע), Policy (מדיניות) ו-Compiled tool (הכלי המהודר).

פנים 1, מה היא אומרת

לשונית Semantic מציגה את התקציר ושתי הערות קצרות: Use when (להשתמש כש...) ו-Do not use when (לא להשתמש כש...). את זה העוזר קורא כדי להחליט אם זו העבודה הנכונה.

לשונית Semantic. עריכת הניסוח הזה היא הרשאה של צוות קו.

אפשר לקרוא את הלשונית הזאת, אבל שינוי הניסוח דורש הרשאה שיש רק לצוות קו. זה מכוון: המשמעות של יכולת זהה בכל עיר, ולכן שינוי אחד היה משפיע על כולן.

פנים 2, החוזה

לשונית Contract מציגה מה האדם צריך לתת (הקלט) ומה חוזר (הפלט). זו רשימה קפדנית של שדות עם סוגים ותיאורים קצרים.

לשונית Contract. ההערה בתחתית היא הבטחה: זהות היא אף פעם לא שדה שהמודל ממלא.

שימו לב להערה בתחתית: identity is injected server-side (הזהות מוזרקת בצד השרת). אם יכולת צריכה לדעת מי שואל, זה בא מההתחברות. אין לזה שדה קלט, ולכן אף אחד לא יכול לשאול על אדם אחר בהקלדת מספר זהות אחר.

פנים 3, איך היא מגיעה לכלי שלכם

זה החלק שלכם. פתחו את לשונית Execution ולחצו על Edit binding (עריכת שיוך), או על Create binding (יצירת שיוך) אם אין. שיוך (binding) מצמיד יכולת אחת לפעולה אחת במופע מחבר אחד שלכם.

לשונית Execution וטופס השיוך. השיוך כאן הוא טיוטה.

1. Connector instance (מופע מחבר). בחרו את שלכם. הרשימה מציגה את הסטטוס והמצב שלו, כי שיוך למופע שהוא עדיין Draft לא מפיק תשובה.
2. Operation (פעולה). קריאה אחת עם שם שהכלי שלכם מציע, כמו GET לנתיב מסוים. הרשימה מציגה רק פעולות שמתאימות ליכולת הזאת.
3. Request template (תבנית בקשה). פתק JSON קטן שאומר אילו שדות של הכלי שלכם למלא מתוך הקלט. כתבו {{ input.fieldName }} בשביל משהו שהאדם סיפק.
4. Response mapping (מיפוי תשובה). הכיוון ההפוך: פתק JSON שאומר איפה בתשובה של הכלי שלכם נמצא כל שדה פלט, למשל "balance": "data.balanceDue".
5. Fields this vendor cannot supply (שדות שהספק הזה לא יכול לספק). אם בכלי שלכם פשוט אין שדה, אמרו את זה כאן. המשפט הזה מתווסף למה שהעוזר קורא, כדי שלא יעמיד פנים. השרת מסרב לשיוך שמשאיר שדה חובה ריק.
6. Publish immediately (פרסום מיידי). השאירו את התיבה לא מסומנת כל עוד אתם עוד בונים. כשהיא לא מסומנת, השיוך נשמר כטיוטה והעוזר אף פעם לא מגיע לטיוטה.

מה אמורים לראות. לשונית Execution מציגה עכשיו את המופע שלכם, את הפעולה ואת הסטטוס. ברשימת היכולות התווית משתנה מ-Unbound (לא משויכת) ל-Bound (משויכת).

אם זה לא עובד. קראו את ההודעה האדומה בטופס. שתי הסיבות הנפוצות הן שיוך למופע שעדיין Draft, ומיפוי תשובה ששם שדה שהכלי שלכם לא מחזיר.

קריאה או כתיבה, ושלב האישור

פתחו את לשונית Policy. היא אומרת עד כמה העוזר חייב להיות זהיר.

לשונית Policy של יכולת כתיבה. האישור פעיל, וזה לא מתג שאפשר לכבות.

• Required assurance (רמת אימות נדרשת) אומרת כמה בטוחים אנחנו שאנחנו יודעים מי האדם, מ-A0 (כל אחד) עד A4. שיוך יכול להעלות אותה, אף פעם לא להוריד.
• יכולות קריאה (Read) רק מחפשות מידע.
• יכולות כתיבה (Write) משנות משהו. הן תמיד דורשות תור של אישור מפורש ("להזמין את זה?"), ויש להן חלון מניעת כפילות (idempotency window), שעון שמונע מאותה בקשה להתבצע פעמיים בטעות.
• בתיבה Rendering (תצוגה) המספרים נשארים ישרים. המודל לא כותב את המספר. התבנית מדפיסה אותו מהנתונים שלכם, ומספר שהמודל מקליד בעצמו בתוך המשפט שלו נמחק לפני שהאדם רואה אותו.

קראו עוד בשלושת הפנים של יכולת, בבחירת רמז תצוגה ובמודול ה-AI, שדה אחר שדה.

לראות את זה כמו שהעוזר רואה

לשונית Compiled tool מציגה בדיוק מה שהעוזר מקבל עבור הארגון שלכם. בדקו אותה אחרי כל שינוי.

לשונית Compiled tool. התווית אומרת אם אפשר לפרסם את הכלי.

מה אמורים לראות. תווית ירוקה Publishable (ניתן לפרסום). אם מופיעה שגיאה במקומה, שום דבר לא נכתב, וההודעה מציינת איזה שדה לתקן. ראו תצוגה מקדימה של יכולת כפי שהמודל רואה אותה.

שלב 3. כללים: החלטות שה-AI לא צריך לנחש

יש תשובות שלעולם לא משאירים ל-AI: מי זכאי להנחה, מי מקבל איזה מחיר, לאן בקשה מגיעה. בשביל אלה כותבים כלל (rule). כלל עונה על שאלה אחת עם שם, כמו "האם האדם הזה זכאי להנחה?", מתוך עובדות כמו גיל או מקום מגורים.

1. פתחו את Rules (כללים) בתפריט הימני ובחרו נקודת החלטה (decision point), שהיא שאלה עם שם. כל אחת היא טבלה.
2. בתצוגת Table (טבלה), כל שורה היא כלל אחד. מלאו את התנאים ואת ההחלטה. תא ריק פירושו "כל ערך".
3. אם שתי שורות יכולות להתאים, קבעו את הסדר ביניהן. אתם מחליטים מי מנצחת.
4. הסתכלו על Declared fallback (ברירת מחדל מוצהרת). זו התשובה כשאף שורה לא מתאימה.

מסך כלל לשאלה לדוגמה, עדיין ריק. ההערה בפינה הימנית התחתונה אומרת מי מפרסם.

שני דברים שכדאי לדעת.

• כלל שאי אפשר לחשב לא מתאים. אם עובדה חסרה או לא ברורה, הכלל אומר לא. הוא אף פעם לא מנחש "כן". גם בשאלות של כסף המערכת נכשלת בצד הבטוח (fail closed).
• כלל מחזיר החלטה. הוא לא עושה שום דבר בעצמו. הפלטפורמה מיישמת את ההחלטה אחר כך, ולכן הסכמה, שעות שקט ורשומת הביקורת ממשיכות לחול.

כדי לבדוק את העבודה, השתמשו בלשונית Test עם אדם לדוגמה, אחר כך ב-Impact (השפעה) כדי לראות מה ישתנה, וב-Conflicts (התנגשויות) כדי לראות שורות שמסתירות זו את זו. ההרצה נשלחת לאותו מנוע שהייצור משתמש בו, ולכן התצוגה המקדימה היא האמת.

מי מפרסם. אתם (כמהנדס אינטגרציה) יכולים לשמור טיוטה. פרסום כלל עבור העיר נעשה על ידי מנהל העיר. כך לכל החלטה יש מי שיצר ומי שבדק. הפרסום גם חסום עד שכל שגיאות הניתוח, בדיקות שנכשלות, מקרה לא מכוסה בלי ברירת מחדל וסיבה חסרה נפתרו. קראו את כלל הזכאות הראשון שלכם ואת בדיקת כלל לפני פרסום.

שלב 4. העוזר וההגדרות שלו

יש לכם עכשיו מחבר, יכולת משויכת ואולי כלל. עוד שלושה דברים קובעים איך העוזר מתנהג.

באילו יכולות מותר לו להשתמש. יכולת שייכת למודול, ומודול צריך להיות מותקן בארגון שלכם. פתחו Install a module (התקנת מודול) כדי להוסיף אחד. הוא נוסף במצב כבוי, מקובע לגרסה המפורסמת החדשה ביותר. העוזר יכול להשתמש רק ביכולת שמותקנת, מופעלת ומשויכת. הפעלת יכולת עבור העוזר היא שלב שהצוות שלנו עושה יחד איתכם, ולכן אם יכולת משויכת לא נראית כאילו היא עובדת, פנו לצוות קו.

מדיניות תשובות (Answer policy). בהגדרות העיר, Answer policy קובעת עד כמה העוזר חייב להיות בטוח לפני שהוא עונה מהידע שלכם. כל שורה מציגה את הערך שבשימוש ואם הוא הגיע מהפלטפורמה או מכם. הורדת רף הביטחון פירושה תשובות על סמך פחות ראיות, ולכן הסטודיו מבקש שתאשרו את זה במילים. ראו קביעת מדיניות התשובות שלכם.

מודל העוזר ותקרת ההוצאה. בהגדרות העיר, Assistant model (מודל העוזר) הוא המקום שבו הארגון שלכם רושם את ספק המודל שלו. גם כאן נותנים את השם של רשומה בכספת, אף פעם לא מפתח. בוחרים מודל זול לשלבים פשוטים ומודל חזק לשימוש בכלים ולשאלות קשות, והפלטפורמה עוברת מאחד לשני לפי רמת ביטחון. תקרה קשיחה מגבילה את ההוצאה, ו-Spend against the ceiling (ההוצאה מול התקרה) מראה את המספר מתמלא. ראו רמות מודל ותקרות הוצאה.

מאיפה המספרים מגיעים. בחזרה בלשונית Policy של היכולת, התיבה Rendering מחזיקה את רמז התצוגה (render hint: Text, Card list, Table, Detail או Confirmation, כלומר טקסט, רשימת כרטיסים, טבלה, פרטים או אישור) ואת השדות המספריים. כך סכום, תאריך או מספר אסמכתה מגיעים אל התושב מהנתונים שלכם ולא מהדמיון של המודל.

שלב 5. בודקים, ואז מפרסמים

עבדו בסדר הזה. אל תדלגו על שלב.

1. קודם Mock. כשהמחבר Active ו-Mock, הריצו שאלה אמיתית דרך העוזר ובדקו את התשובה. שום מערכת אמיתית לא נפגעת.
2. בדקו את הכלי המהודר. הוא אמור להראות Publishable.
3. בדקו את הכלל עם אדם לדוגמה, וקראו את לשונית Impact.
4. נסו שיחה שלמה. אם היכולת נמצאת בתוך זרימה, עברו עליה בסימולטור. ראו בדיקת זרימה בסימולטור.
5. עוברים ל-Live. דאגו שפרטי הגישה שמורים (טביעת האצבע מופיעה), ואז העבירו את המחבר ל-Active ול-Live. אחר כך פרסמו את השיוך, או שייכו אותו כשהתיבה Publish immediately מסומנת.
6. בקשו ממנהל העיר לפרסם את הכלל.
7. בדקו שוב ב-Live. שאלו שאלה אמיתית אחת ובדקו את פאנל Health במחבר.

טיוטה ומפורסם, במילים פשוטות

טיוטה היא עותק העבודה שלכם. העוזר אף פעם לא מגיע אליה. מפורסם הוא מה שהתושבים שלכם מקבלים. שמירת טיוטה מותרת תמיד ויכולה להיות לא גמורה. פרסום הוא הרגע שנחשב, ויש לו שערים.

אין כפתור ביטול בלחיצה אחת שאנחנו יכולים להבטיח. אם משהו משתבש, מתקנים קדימה: מחזירים את המחבר ל-Mock או ל-Suspended כדי לעצור קריאות אמיתיות מיד, מתקנים את הטיוטה ומפרסמים שוב.

Dev, test ו-prod

התווית בראש הסטודיו מראה באיזו סביבה אתם: dev, test או prod. בנו ובדקו ב-dev או ב-test, ואז העבירו את העבודה ל-prod באמצעות Promotion (קידום).

Environment Promotion (קידום בין סביבות). מייצאים מסביבה אחת, מדביקים בבאה.

Discover and export everything (גלה וייצא הכול) אוסף את מופעי המחברים, ערכות הכללים, הזרימות, התורים וקודי הסיכום שלכם למסמך אחד. מדביקים אותו בסטודיו של הסביבה השנייה ומייבאים. שיוכים לא נמצאים ברשימה הזאת, ולכן בדקו אותם בסביבת היעד אחרי הייבוא.

איפה רואים מי עשה מה

כל שינוי במחזור החיים של מחבר הוא פעולה עם אדם וזמן, ונשמר ברשומת הביקורת. גם הקריאה שלה נרשמת: קודם שואלים אתכם מה המטרה. ראו קריאת יומן הביקורת.

איזו חבילה צריך בשביל זה?

בסטודיו אין מתג חבילה. הוא לא בודק אם אתם ב-Starter, ב-Plus או ב-Pro לפני שהוא נותן לכם לפתוח את מסכי המחברים, לשייך יכולת או לכתוב כלל. מה שהוא בודק הוא התפקיד שלכם, כמו בטבלה בתחילת המדריך.

שלוש מגבלות שכדאי להכיר.

• מערכות שהפלטפורמה כבר מכירה. אפשר להוסיף ולהגדיר בעצמכם, בסטודיו, מחבר לכל סוג מערכת שכבר יש לו הגדרה. סוג מערכת חדש לגמרי צריך הגדרה ויכולת שנכתבות על ידי צוות קו.
• חבילות מודולים וחבילות רישיון. חלק מחבילות המודולים דורשות שחבילת רישיון תוענק לפני שאפשר להתקין אותן. רק צוות קו מעניק אותן. ראו הענקת חבילת רישיון.
• תפקידים. שמירת פרטי גישה, פרסום כללים והגדרות העוזר נמצאים אצל מנהל העיר. ודאו שהאדם הזה קיים לפני שמתחילים.

רשימת בדיקה

• ידוע לי איזו מערכת אני מחבר ומי ישמור את הסיסמה שלה.
• מופע המחבר קיים, פעיל ובמצב Mock.
• מנהל העיר שמר את פרטי הגישה, וטביעת האצבע מופיעה.
• היכולת משויכת למחבר ולפעולה שלי, ונשמרה כטיוטה.
• לשונית Compiled tool אומרת Publishable.
• כל כלל נכתב, נבדק ופורסם על ידי מנהל העיר.
• מודל העוזר ותקרת ההוצאה הוגדרו.
• בדקתי ב-Mock, אחר כך העברתי את המחבר ל-Live ושאלתי שאלה אמיתית אחת.
• השיוך פורסם, ופאנל Health נראה תקין.
• ידוע לי איפה רואים את רשומת הביקורת.

להעמיק

• חיבור המערכת הראשונה שלכם, מקצה לקצה
• מחזור החיים של מחבר
• הפנייה לפרטי גישה שלעולם לא תראו שוב
• שלושת הפנים של יכולת
• בדיקת כלל לפני פרסום
• תפקידים והרשאות של צוות
• להתמצא בסטודיו של קו