אינטגרציה

כללי

מקומה של טפז במחשוב תהליכים עסקיים

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

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

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

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

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

הפניית המשתמש לכתובת URL לאחר השליחה

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

כך ניתן להעביר את המשתמש לשלב הבא בתהליך שמילוי הטופס הוא שלב בו וגם להעביר למערכת המטפלת בשלב הבא מידע על הטופס שנשלח בשורת הכתובת, למשל כ-Query string parameter.

הפניית המשתמש לכתובת דינאמית

טכניטקה נפוצה היא הוספה של שדה טקסט מוסתר בשם redirectUrl לטופס:

טופס עם שדה redirectUrl מוסתר

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

הגדרת הפנייה לכתובת דינאמית לאחר שליחת הטופס

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

טופס עם ערכים מלאים מראש

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

יישנן שתי דרכים לעשות זאת:

העברת הנתונים בשורת הכתובת

בשיטה זו המידע בטופס מועבר כ-Query string parameter בשם data שמכיל את המידע שיש להזין מראש בפורמט JSON. מסלולי הנתונים ב-JSON יהיו בהתאם למבנה הנתונים בטופס.

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

עבור טופס זה, הקישור לטופס, ללא נתונים מוזנים מראש הוא:

https://app.tepez.co.il/#/f/57d9228843fe563518f87d64/

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

אם: דנה כהן, ת.ז. 123456782
אב: משה כהן, ת.ז. 23456783
שלושה ילדים: אסף, שלי, גל

מבנה הנתונים יראה כך:

{
    "mother": {
        "firstName": "דנה",
        "lastName": "כהן",
        "idNum": 123456782
    },
    "father": {
        "firstName": "משה",
        "lastName": "כהן",
        "idNum": 23456783
    },
    "children": [
        {
            "name": "אסף"
        },
        {
            "name": "שלי"
        },
        {
            "name": "גל"
        }
    ]
}

הקישור לטופס עם הנתונים האלה ממולאים מראש יהיה:

https://app.tepez.co.il/#/f/57d9228843fe563518f87d64/?data=%7B%22mother%22%3A%7B%22firstName%22%3A%22%D7%93%D7%A0%D7%94%22%2C%22lastName%22%3A%22%D7%9B%D7%94%D7%9F%22%2C%22idNum%22%3A123456782%7D%2C%22father%22%3A%7B%22firstName%22%3A%22%D7%9E%D7%A9%D7%94%22%2C%22lastName%22%3A%22%D7%9B%D7%94%D7%9F%22%2C%22idNum%22%3A23456783%7D%2C%22children%22%3A%5B%7B%22name%22%3A%22%D7%90%D7%A1%D7%A3%22%7D%2C%7B%22name%22%3A%22%D7%A9%D7%9C%D7%99%22%7D%2C%7B%22name%22%3A%22%D7%92%D7%9C%22%7D%5D%7D

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

https://app.tepez.co.il/#/f/57d9228843fe563518f87d64/run/?data={"mother":{"firstName":"דנה","lastName":"כהן","idNum":123456782},"father":{"firstName":"משה","lastName":"כהן","idNum":23456783},"children":[{"name":"אסף"},{"name":"שלי"},{"name":"גל"}]}

יתרונות

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

חסרונות

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

יצירת רשומה

שיטה זו מצריכה שימוש בנקודת POST /entry/save ב-API של טפז.

שולחים לשרת את הבקשה הבאה:

POST https://api.tepez.co.il/v1.0/entry/save
{
    "form": "57d9228843fe563518f87d64", // זהו המזהה הייחודי של הטופס בדוגמא
    "data": {
        "mother": {
            "firstName": "דנה",
            "lastName": "כהן",
            "idNum": 123456782
        },
        "father": {
            "firstName": "משה",
            "lastName": "כהן",
            "idNum": 23456783
        },
        "children": [
            {
                "name": "אסף"
            },
            {
                "name": "שלי"
            },
            {
                "name": "גל"
            }
        ]
    }
}

התגובה תהיה:

{
  "formId": "57d9228843fe563518f87d64",
  "entryId": "< המזהה הייחודי של הרשומה שנוצרה >",
  "message": "The form was saved as a draft.",
  "bewit": "< טוקן שמאפשר גישה לרשומה, ללא צורך בהתחברות למערכת >"
}

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

https://app.tepez.co.il/#/e/entryId/run/?b=bewit

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

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

יתרונות

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

API

אימות

כמעט כל בקשות ה-API דורשות אימות. האימות נעשה בשני שלבים.

השלב הראשון נעשה אל מול נקודת ה-POST /auth/login. לנקודה זו שולחים את כתובת האימייל והסיסמה של המשתמש עבורו רוצים לבצע בקשות API. מקבלים בתגובה טוקן שמשמש לאמת את בקשות ה-API. הטוקן בתוקף ל-3 ימים (36 שעות) מרגע הוצאתו. ניתן לשמור אותו, בצורה בטוחה, ולעשות בו שימוש בתקופה זו. ניתן גם להוציא טוקן חדש כל פעם שרוצים לבצע בקשות API.

הבקשה נראית כך:

POST https://api.tepez.co.il/v1.0/entry/save
{
  "email": "<אימייל של המשתמש>",
  "password": "<סיסמה של המשתמש>"
}

התשובה נראית כך:

{
  "token": "<טוקן לאימות בקשות>",
  "user": {
    // פרטים על המשתמש
    ...
  }
}

בשלב השני מצרפים את הטוקן לכל בקשת API שרוצים לבצע. האימות נעשה ע"י צירוף הטוקן ב-authorization HTTP header כ-Bearer <טוקן>.

לדוגמה, נניח שרוצים למשוך את כל הרשומות של טופס עם המזהה 593d6c38b8eb0a40bf2eab69. נעשה זאת עם נקודת GET /entry. הבקשה תהיה:

GET https://api.tepez.co.il/v1.0/entry?query={"form": "57d9228843fe563518f87d64"}
authorization: Bearer TOKEN

אם נשלח את הבקשה ללא הטוקן נקבל שגיאה 401 עם התגובה:

{
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "Missing authentication"
}

תיעוד ה-API

כל נקודות הגישה ל-API של טפז מתעודות באתר docs.tepez.co.il. באתר ניתן לנסות את הפקודות השונות ולשלוח בקשות ישירות מהדפדפן. תחילה יש להכניס כתובת אימייל וסיסמה בטופס ההתחברות שבראש העמוד וללחוץ על כפתור get token:

אימות משתמש באתר תיעוד ה-API

לאחר מכן, ניתן לשלוח בקשות API כמשתמש הזה. בוחרים בקשה כלשהי, ממלאים את הפרמטרים הרלוונטיים לבקשה ולוחצים על כפתור Try it out!:

שליחת בקשות מאתר תיעוד ה-API

ניתן להשתמש ב-developer tools של הדפדפן (בדרך כלל נפתח ע"י לחיצה על F12) כדי לבחון את הבקשות ואת התשובות של השרת:

בחינת בקשות ותשובות עם developer tools

תיעוד בפורמט OpenAPI זמין בקובץ swagger.json.

אפשרויות

סינון השדות המוחזרים מהשרת

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

הסינון נעשה ע"י ה-Query string parameter בשם fields. אם מעוניינם בשדה אחד, לדוגמה id (המזהה הייחודי של האובייקט) אז מוסיפים לשורת הכתובת ?fields=id, לדוגמא:

GET https://api.tepez.co.il/v1.0/form?fields=id

אם מעוניינים במספר שדות, לדוגמה id, name ו-counts (הכולל מדדים על מספר הפעולות שבוצעו בטופס), התחביר הינו:

GET https://api.tepez.co.il/v1.0/form?fields=id&fields=name&fields=counts&

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

סינון האובייקטים המוחזרים מהשרת

בנקודות המשמשות למשיכה של רשימת אובייקטים, לדוגמה משיכת רשימת רשומות, ניתן לסנן הרשומות המוחזרות מהשרת. הסינון מוגדר ב-Query string parameter בשם query.

כברירת מחדל, אם לא צוין פרמטר query יוחרו כל האובייקטים אליהם יש למשתמש גישה.

query מקבל אובייקט JSON (שעבר קידוד ל-URL) עם הגדרה לסינון בפורמט MongoDB.

לדוגמה, כדי למשוך את כל הרשומות של טופס עם המזהה 593d29a7b8eb0a40bf2eaa90 הפקודה תהיה:

GET https://api.tepez.co.il/v1.0/entry?query=%7B%22form%22%3A%20%22593d29a7b8eb0a40bf2eaa90%22%7D

ללא קידוד URL זה:

GET https://api.tepez.co.il/v1.0/entry?query={"form": "593d29a7b8eb0a40bf2eaa90"}"

אם נרצה למשוך רק את הרשומות שהם בסטטוס נשלח עבור טופס, הפקודה תהיה:

GET https://api.tepez.co.il/v1.0/entry?query=%7B%22form%22%3A%20%22593d29a7b8eb0a40bf2eaa90%22%2C%20%22status%22%3A%202%7D

ללא קידוד URL זה:

GET https://api.tepez.co.il/v1.0/entry?query={"form": "593d29a7b8eb0a40bf2eaa90", "status": 2}

אנומליה בסינון לפי סטטוס

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

להלן הערכים האפשריים לסטטוס של רשומה:

שם סטטוס	ערך שיוחזר מהשרת (במשיכת רשומות)	קוד (משמש לסינון)
נוצרה	created	0
נשמרה	saved	1
נשלחה	submitted	2
תבנית	template	4

סידור האובייקטים המוחזרים

בנקודות המשמשות למשיכה של רשימת אובייקטים, לדוגמה משיכת רשימת רשומות,

ניתן למיין את הרשומות לפי כל אחד מהאפיינים באובייקט. המיון מוגדר ב-Query string parameter בשם sort.

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

sort מקבל אובייקט JSON (שעבר קידוד ל-URL) עם הגדרה למיון בפורמט MongoDB.

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

GET https://api.tepez.co.il/v1.0/entry?sort=%7B%22_id%22%3A%20-1%7D

ללא קידוד URL זה:

GET https://api.tepez.co.il/v1.0/entry?sort={"_id": -1}"

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

GET https://api.tepez.co.il/v1.0/entry?sort=%7B%22form%22%3A%201%2C%20%22_id%22%3A%201%7D

ללא קידוד URL זה:

GET https://api.tepez.co.il/v1.0/entry?sort={"form": 1, "_id": 1}

אנומליה בסידור/סינון לפי מזהה ייחודי

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

בחירת שפת ההודעות המוחזרות מהשרת

לעתים השרת מחזיר הודעות המיועדות להצגה למשתמש אנושי. הודעות כאלה, אם יוחזרו, יופיעו במאפיין message בגוף התשובה. ניתן לשלוט בשפת ההודעות המוחזרת ע"י Query string parameter בשם locale.

כברירת מחדל, אם לא צוין locale השפה תהיה אנגלית (ארצות-הברית). ערכים אפשריים נוספים הם he עבור עברית (ישראל) ו-en_GB עבור אנגלית (בריטניה). ההבדל בין אנגלית (ארצות-הברית) לבין אנגלית (בריטניה) הוא באופן הצגת תאריכים (12/31/2017 בארה"ב לעומת 31/12/2017 בבריטניה).

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