9.1 Integrare Trello - detalii tehnice

Tipuri de tablouri de bord:

• K-Board Sesizări:

  • se sincronizează sesizări (nu și sarcini!) legate de proiectul specificat pe înregistrare în câmpul Proiect;

  • nu se pot defini două borduri Trello active pe același proiect (verificarea se face în clasa model org.bitsoftware.strl.model.MSTRLTrelloBoard);

  • crearea bordului în Trello se face apelând procesul Crează bord în Trello de pe înregistrarea selectată.

• Sales Pipeline:

  • se sincronizează lead-uri;

  • este permis un singur bord activ de acest tip (verificarea se face în clasa model org.bitsoftware.strl.model.MSTRLTrelloBoard);

  • la dezactivarea/activarea unui tablou de bord în SocrateCloud, acesta se dezarhivează/arhivează în Trello, doar dacă bordul din Trello a fost creat rulându-se procesul Crează bord în Trello (sincronizarea se face în clasa org.bitsoftware.strl.model.STRLModelValidator).

La redenumirea unui tablou de bord în SocrateCloud acesta se redenumește și bordul Trello, doar dacă bordul din Trello a fost creat rulându-se procesul Crează bord în Trello (sincronizarea se face în clasa org.bitsoftware.strl.model.STRLModelValidator).

Procese ce se pot rula din fereastra Setări Kanban Bord - Trello:

Crează bord în Trello:

• butonul este vizibil doar dacă procesul nu a fost rulat deja (tabloul nu a fost încă creat în Trello);

• procesul întoarce un mesaj de eroare dacă utilizatorul care face acțiunea nu are setup-ul de Trello făcut;

• după ce procesul rulează cu succes și tabloul este creat în Trello, ID-ul acestuia este salvat pe înregistrare;

• la crearea tabloului se înregistrează un callback dinspre Trello către SocrateCloud. ID-ul callback-ului împreună cu cheia și token-ul utilizatorului care a rulat procesul de creare sunt salvate pe înregistrare;

• dacă apare eroare la înregistrarea callback-ului, se trece peste acest pas și se continuă cu crearea tabloului. Eroarea poate să apară dacă serviciul care ascultă la Trello nu este pe un server ce poate fi accesat din Trello. Chiar dacă dă eroare tot se salvează cheia și token-ul utilizatorului care a rulat procesul pe înregistrare, pentru ca ulterior să se poată înregistra callback-ul cu aceleași credenţiale;

• odată cu tabloul sunt create și listele din Trello care corespund coloanelor din tabelul de bord definit în SocrateCloud. Un tablou de bord în Trello vine cu trei liste implicite, acestea sunt redenumite și tabloul se completează cu restul listelor corespunzătoare coloanelor din tabelul de bord;

• clasă java utilizată: org.bitsoftware.strl.process.STRL_CreateTrelloBoard.

Înregistrează callback bord Trello:

• butonul este vizibil doar dacă bordul a fost creat în Trello și callback-ul nu a fost înregistrat. Cu alte cuvinte, pe înregistrare, avem ID de bord dar nu avem ID de callback;

• callback-ul este înregistrat cu datele de autentificare în Trello a celui care a apelat procesul Crează bord în Trello;

• clasă java utilizată: org.bitsoftware.strl.process.STRL_RegisterTrelloBoardCallback&.

Sincronizează Bord:

• butonul este vizibil doar dacă bordul a fost creat în Trello (avem ID de bord pe înregistrare);

• sincronizează sesizări sau lead-uri în funcție de tipul bordului;

• sunt sincronizate doar acele sesizări/lead-uri ce sunt pe proiectul de pe bord și pentru care starea sesizării corespunde unei coloane de K-Board;

• oferă opțiunea de a insera carduri în Trello cu sesizări/lead-uri ce nu au fost sincronizate și opțiunea de a actualiza carduri cu sesizări/lead-uri ce au fost deja sincronizate în Trello;

• oferă opțiunea de a sincroniza notele de pe sesizări (creste semnificativ numărul de request-uri de API Trello și perioada de timp în care rulează procesul);

• se sincronizează membrii de pe sesizare cu membrii de pe card (se salvează în Trello doar membrii din SocrateCloud care au Setup utilizator Trello făcut);

• datele trimise în Trello sunt identice cu cele trimise la actualizarea unei sesizări sau a unui lead (detalii mai jos);

• clasa java utilizata: org.bitsoftware.strl.process.STRL_SynchronizeBoard.

Sincronizare SocrateCloud -> Trello

Sincronizare sesizări

Se sincronizează doar sesizări de pe proiectele care se regăsesc pe un tabel de bord activ în SocrateCloud (se tine cont dacă sesizarea trece de pe un proiect legat de un tabel de bord pe un proiect nelegat de un tabel de bord și invers). Se sincronizează doar sesizări, nu și sarcini.

De pe master sesizare se sincronizează:

• subiectul sesizării, timpul cumulat și timpul estimat -> titlu card în format "[0/12] Subiect sesizare";

• data sfârșit -> Due Date pe card;

• sumarul sesizării -> descriere card;

• starea sesizării -> lista Trello;

• starea procesat -> arhivare card;

• proiectul -> bordul cardului;

• membri sesizare -> membri Trello.

Sincronizarea are loc dacă unul din câmpurile de mai sus își modifică valoarea. Cu fiecare apel de sincronizare se trimit toate informațiile de sus mai putin "data sfârșit" care se trimite doar dacă își modifică valoarea (pentru a preveni efectul de ping-pong);

după sincronizare, id-ul cardului din Trello se salvează pe sesizare.

Apelul de sincronizare diferă în funcție de prezenta ID-ului de card: dacă ID-ul exista pe sesizare atunci se face request de update card, altfel request de insert card.

De pe note sesizări se sincronizează:

• timpul consumat împreuna cu textul de pe notă -> comentariu la card în format "[5] text nota"; textul de pe notă care merge drept comentariu de card poate sa fie textul propriu zis, numele activității sau, dacă textul lipsește, timpul consumat în format "[5] timp consumat: 5";

Sincronizarea notei are loc doar dacă sesizarea a fost sincronizata cu Trello (are ID de card salvat) și conține timp introdus, text sau activitate. După sincronizare ID-ul comentariului este salvat pe nota. Apelul de sincronizare diferă în funcție de prezenta ID-ului de comentariu pe notă: dacă ID-ul exista atunci se face request de update comentariu card, altfel request de insert comentariu card.

Din lista de membri de pe sesizare se sincronizează:

• doar membrii care au setup-ul de utilizator Trello făcut în SocrateCloud;

• dacă se șterge sau dezactivează un membru din SocrateCloud, el este șters și de pe card în Trello;

• dacă se adaugă un membru la o sesizare în SocrateCloud, și utilizatorul respectiv are setup-ul de utilizator Trello făcut, acesta se adaugă și pe card;

• la rularea procesului Sincronizare Bord (vezi mai sus) lista cu membrii de pe sesizare suprascrie lista de membri de pe card în Trello.

Dacă sesizarea se mută pe un proiect ce nu este legat de un tablou de bord definit în SocrateCloud, atunci, dacă sesizarea are ID de card salvat, se face un request de închidere a cardului (cu actualizarea informațiilor de mai sus) altfel nu se sincronizează nimic. Dacă sesizarea se mută pe un proiect legat de un tablou de bord în SocrateCloud, atunci, dacă sesizarea are ID de card, se deschide cardul în Trello, altfel se creează un card nou. Dacă sesizarea se muta pe o stare ce nu are echivalent o coloană de K-Board, respectiv o lista în Trello, atunci, dacă sesizarea are ID de card, se actualizează cardul cu informațiile de mai sus iar lista rămâne neschimbată, altfel nu se sincronizează nimic.

Sincronizare lead-uri

Se sincronizează doar dacă există în SocrateCloud un tablou de bord activ de tipul Sales Pipeline.

Se sincronizează următoarele:

• numele terțului de pe lead sau număr document împreună cu tip lead (dacă există tip lead acesta este concatenat după numărul de document prin "-") -> titlu card în Trello;

• data sfârșit -> Due Date pe card;

• descriere lead -> descriere card;

• starea lead-ului -> lista Trello;

• starea procesat -> arhivare card.

Sincronizarea are loc dacă unul din câmpurile de mai sus își modifică valoarea.

Tot timpul se trimit toate informațiile de sus mai putin "dată sfârșit" care se trimite doar dacă își modifică valoarea (pentru a preveni efectul de ping-pong).

Dacă lead-ul se mută pe o stare ce nu are echivalent o coloană de K-board, respectiv o listă în Trello, atunci, dacă lead-ul are ID de card, se actualizează cardul cu informațiile de mai sus iar lista rămâne neschimbată, altfel nu se sincronizează nimic.

Sincronizare Trello -> SocrateCloud

Sincronizarea are la bază apeluri din Trello (callback-uri) către SocrateCloud.

În SocrateCloud un callback se înregistrează la crearea unui bord în Trello, pentru a primi notificări legate de modificările de pe bord-ul respectiv. Dacă la crearea bord-ului în Trello nu se poate crea callback-ul din diferite motive, în fereastra de Setări K-Boards - Trello apare butonul de înregistrare callback (vezi detalii mai sus, la descrierea procesului).

Procesarea apelurilor din Trello se face în clasa org.bitsoftware.strl.rest.TrelloCallback. Se folosesc metode de API separate pentru sesizări (.../strl/rest/trelloCallback/RK/board) și pentru lead-uri (.../strl/rest/trelloCallback/SP/board) pentru a trata diferit mesajele. Metodele sunt specificate la înregistrarea callback-ului. Exemple de mesaje JSON primite din Trello se pot găsi în proiectul din Git, în folderul callback_models.

La fiecare apel se scrie în log conținutul mesajului JSON, pe nivel INFO (se poate urmări din monitorizare dacă se înregistrează modulul web "SocrateCloud for Trello" ).

La salvarea PO-ului (sesizare/lead) se salvează o variabilă de tip boolean în PO (nepersistentă) ce urmează a fi verificată în model validator pentru a nu se mai face un apel înapoi către Trello (efectul ping-pong). În unele cazuri se permite totuși apelul înapoi către Trello pentru a se corecta anumite informații.

Sunt acceptate doar notificările tipul "updateCard" care semnifică modificarea unuia din câmpurile: titlu card, descriere card, dată sfârșit, listă.

Callback bord sesizări:

Se identifică sesizarea după ID-ul de card.

Se actualizează dată sfârșit (dacă s-a modificat).

Dacă s-a modifică titlul cardului, se descompune în text, cantitate estimată, cantitate consumată și dacă este cazul, se actualizează subiectul și cantitatea estimată de pe sesizare. Dacă se modifică cantitatea planificată, se permite un nou apel de API Trello din model validator (prin setarea variabilei prezentate mai sus).

Dacă s-a modificat descrierea cardului se modifică sumarul sesizării.

Dacă s-a modificat lista în Trello, sunt câteva acțiuni ce pot avea loc. Se verifică dacă lista e prezentă pe bord-ul din SocrateCloud: 

• Dacă e prezentă, se verifică dacă s-a schimbat coloana de K-board și dacă s-a schimbat, se setează pe sesizare.

• Dacă lista nu e prezentă pe bord-ul din SocrateCloud se cauta o stare de backlog corespunzătoare tipului de sesizare (o stare legată de o coloană de K-board cu numele "%BACKLOG%") și se setează pe sesizare. De altfel, se permite un nou apel API Trello din model validator (prin setarea variabilei prezentate mai sus) pentru cazul în care și în Trello exista listă de backlog în vederea corecției. (a nu permite cardului care e și sesizare în SocrateCloud să stea pe o listă care nu are stare echivalentă în SocrateCloud) 

Se salvează sesizarea și dacă sunt modificări se va apela codul din model validator de sincronizare cu Trello. În model validator se verifică variabila menționată mai sus pentru a se împiedica sincronizarea dacă sesizarea a fost modificată de un callback din Trello (cu unele excepții care au fost semnalate).

Callback lead-uri:

Se identifică lead-ul după ID-ul de card.

Se actualizează data sfârșit (dacă s-a modificat).

Dacă s-a modificat titlul cardului (este necesară corecția în Trello), se simulează o modificare pe lead și se permite un nou apel de API Trello (prin setarea variabilei nepersistente).

Dacă s-a modificat descrierea cardului se modifică descrierea lead-ului .

Dacă s-a modificat lista în Trello se urmează logica de la sesizări.

Model JSON (dată sfârșit modificată)

{

"action": {

"idMemberCreator": "53c6d0c73f3f696a487ce170",

"data": {

"board": {

"name": "SocrateCloud 14.02 (7)",

"id": "5419fdc59bde1fd80d9fcd47"

},

"old": {

"due": "2014-10-17T09:00:00.000Z",

},

"card": {

"name": "[1/12] Request subject",

"id": "5419fee31ca8e98be7af9bb7",

"due": "2014-10-31T10:00:00.000Z"

}

},

"type": "updateCard",

}

}

Desfășurarea procesului (process flow)

1. Trebuie instalată componenta SocrateCloud Trello Integration.

2. Utilizatorii ce vor lucra pe sesizări și/sau lead-uri trebuie să își facă cont în Trello și setup-ul în SocrateCloud (vezi mai sus).

3. Trebuie să existe K-bord-ul configurat (stări de sesizări legate de coloane de K-bord).

4. Pe System trebuie să existe definit modulul web "Web UI" (este necesar la crearea url-ului pentru apel-ul de API din Trello în SocrateCloud).

5. Adminul de SocrateCloud (trebuie sa aibă setup-ul de utilizator Trello făcut) definește bord-urile în SocrateCloud pentru sesizare și/sau lead-uri și rulează Procesul de creare bord (vezi mai sus). Procesul rulează o singură dată iar pe bord în Trello se vor crea doar coloanele de K-board existente în acel moment (coloanele ulterioare nu vor putea fi sincronizate). Dacă apare o eroare la înregistrarea callback-ului, acest pas se poate face și ulterior (poate aparea o eroare dacă modulul web STRL nu este pus pe serverul de aplicație sau nu este accesibil de pe internet).

La actualizarea sesizărilor și/sau lead-urilor se face apel de sincronizare în Trello. Utilizatorii pot sa modifice anumite informații în Trello și acestea să se modifice automat și în SocrateCloud (vezi detalii mai sus).

Conflicte

Dacă un utilizator nu are setup-ul făcut și actualizează o sesizare, nu se va face nicio sincronizare cu Trello.

Dacă un utilizator își face setup-ul cu un cont de Trello care nu are acces la tabelul de bord creat din SocrateCloud, la actualizarea sesizărilor nu se va putea face sincronizarea cu Trello și sistemul va afişa o eroare cum că utilizatorul respectiv nu are drepturi să modifice cardul din Trello.