קונימבו - חנויות מקצועיות באינטרנט

הסבר:

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

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

המדריך כולל:

1) הסבר כללי על ההיבריד ששולט על האינטגרציה.

2) תרשים זרימה של המערכת.

היבריד האינטגרציה

בהיבריד קיימות 3 לשוניות שרלוונטיות לנו:

- משתנים

- פנימי

- כללי

משתנים:

כל המשתנים שנצטרך שילוו אותנו במהלך האינטגרציה ויכנסו לתוך האובייקט  {{var_to_json}} בתוך ההיבריד.

דוגמא למשתנים: מיפוי שדות, כתובת פנייה , טוקן (token) של הלקוח אצל קונימבו וכו'.

פנימי:

כאן נמצא הURL של האינטגרציה (settings.json). הURL מחזיר קובץ JSON שמחזיק את כל המשתנים של ההייבריד ואת מהלך האינטגרציה שרשום בלשונית כללי בשדה "javascript_before".

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

בנוסף בלשונית זו מוגדרים משתנים פנימיים כמו שם משתמש, סיסמה וכו'.

כללי:

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

מהלך האינטגרציה כתוב בשדה javascript_before בשפת JavaScript.

מהלך האינטגרציה

בלשונית כללי בשדה javascript_before נמצא מהלך האינטגרציה בעל מבניות קבועה. דוגמא למבנה הקוד:

פרמטרים בקוד:

-"vars"-

אובייקט שמחזיק את כל הנתונים שנמצאים בשדות ההיבריד( {{var_to_json}} ).

-"log"  , "ErrLog"-

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

• בS3 Bucket של AWS - שומר את הלוגים בקבצים. ניתן לגשת אליהם אחר כך ולבצע קריאת S3get.

            (AWS -> Services -> S3 -> Bucket name)

• בCloudWatch - שומר console.log.

           (AWS -> Services -> S3 -> CloudWatch -> Logs)

ההבדל הוא ש-log נמצא בשימוש בסיום כל שלב בפעולה ו-ErrLog נמצא בשימוש כל פעם שיש שגיאה בשלב מסויים או פעולה מסויימת.

השדות בתוך האובייקט הם זהים:

 "types" 

רשימה (Array) של סוגי הלוגים (תיעודים) שנרצה לעשות. לדוגמא: s3, console.

 "save" 

האם לבצע את התיעוד. מקבל true או false.

 "key" 

שם הקובץ שנרצה לשמור בו את התיעוד במידה ובחרנו לתעד בs3.

-"response"-

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

-"actions"-

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

סדר הפעולות נקבע לפי סדר הכתיבה שלהן בקובץ.

-"type"-

לכל פעולה יש סוג שקובע באיזה סדר להריץ את השלבים (steps) בתוך הפעולה. לדוגמא:

normal - סדר ריצה רגיל כלומר מתחילת הפעולה עד סופה.

loop - במקרה כזה רצף השלבים בפעולה ירוצו  על כל יישות בסדר סינכרוני. לדומגא אם יש לנו רשימה (Array) של מוצרים מהפעולה הקודמת ואנחנו רוצים שבפעולה הנוכחית השלבים ירוצו על כל אחד מהמוצרים נשתמש בסוג loop.

-"freeMemory"-

קובע אם לשמור מידע של אותו אקשן / פעולה. אם הערך הוא true המידע לא יישמר (כלומר יתפנה מקום), אם יהיה false המידע יישמר. בדיפולט עדיף לא לשמור מידע, בעיקר של פעולות מסוג loop, אלא אם נצטרך את המידע להמשך האינטגרציה.

-"steps"-

השלבים בתוך הפעולה. לכל שלב מספר שדות וכולם חייבים להיות נוכחים, לא בהכרח עם נתונים. לכל שלב יש אובייקיטים של "log"  ,"ErrLog".

-"dataType"-

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

במידה והמידע לא כתוב בפורמט json תתבצע המרה לjson.

-"template"-

פה כתוב קוד JavaScript של כל שלב. הקוד נעטף מאוחר יותר ב- function Statement לכן אין צורך להגדיר פונקציה רק לכתוב את התוכן שלה. בנוסף בגלל הסביבה בה חי הקוד בסוף הטמפלט צריך להיות return Statement שהוא בעצם יהיה המידע של ה step הנוכחי.

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

-"options"-

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

בשביל שהלמדה (Lambda) תתעורר עם המידע הנכון, ההיבריד עם הנתונים שהכנו, יש כמה פרמטרים שצריך לכלול בקריאה אליה:

hybirdId: חובה. מספר ID של ההיבריד עליו עבדנו.

filename: חובה. כל היבריד נשמר בS3 כקובץ אותו אנחנו קוראים עם הלמדה. לכל קובץ כזה יש סיומת, אותה אנחנו יכולים לקבוע בהגדרת משתנה. לדוגמא -  settings.json.

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

subdomain: חובה. הסאב-דומיין של החנות בה קיים ההיבריד.

token: חובה. לכל היבריד כזה של הגדרות אינטגרציה יש token מסויים אשר נמצע גם ב {{var_to_json}}. בשביל צורכי אבטחה צריך לשלוח את אותו token גם בקריאה.

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

AccessControlAllowOrigin: אופציונלי. בשביל שנוכל לשלוט ב- Access-Control-Allow-Origin של ה - headers של התגובה של הלמדה.

• דוגמא לקריאה ללמדה (LambdaURL): 

https://spc4o29rz0.execute-api.eu-west-1.amazonaws.com/production/wakeup?dataIndex=X&subdomain=XX&hybridId=XXX&filename=settings.json&token=XXXXXX

יכולות המערכת:

שמירה בS3 Bucket של אמאזון:

    קיימת יכולת של שמירת מידע / שגיאות בS3. בכדי להשתמש ביכולת צריך להזין בקובץ, תחת log / ErrLog, בשדה של types את המילה      s3, מופרדת בפסיק אם קיימת עוד אופציה כמו console. דוגמא:

שליחת מיילים:

    קיימת אפשרות של שליחת מיילים ב2 מצבים: סיום אינטגרציה + שגיאה באינטגרציה.

    סיום אינטגרציה:

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

    שגיאה אינטגרציה:

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

נושא המייל:

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

שגיאה אינטגרציה:

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