Trello Integration - Technical Details
Through this form you can save in SocrateCloud, at User level, the authentication data for Trello through API, specifically: API key, Token and Trello User.
the key and token are automatically transmitted on each API request
the Trello user Id is used for:
assigning Trello users to a card. Only members for which the setup has been made are synchronized;
identifying the SocrateCloud user which made an action in Trello that generated a callback. See Synchronize Trello - SocrateCloud below.
Java Classes Used:
com.bitsoftware.so web.client.form.strl.DFTrelloUserSetup
com.bitsoftware.so web.server.service.form.strl.STRL_TrelloUserSetupImpl
Warning: When you do the setup the user must be logged into Trello within the browser. Also the Trello user must have access to the boards defined within SocrateCloud.
Here you define which dashboards will be synchronized between SocrateCloud and Trello. There are two types of SocrateCloud dashboards which can be synchronized:
Request K-boards: synchronize requests (not tasks) linked to the specified project;
There cannot be defined more than one board on the same project. Verification is made in the model class: org.bitsoftware.strl.model.MTRL Trello Board;
Creating a K-Board in Trello is done by calling the process Create Board in Trello on the selected record.
Sales Pipeline: synchronize leads. Only one board of this type is allowed. Verification is done in the model class: org.bitsoftware.strl.model.MTRL Trello Board.
When deactivating/activating a dashboard in SocrateCloud the respective Trello board is archived/un-archived, only if the board from Trello has been created using the Create Board in Trello process. Synchronization is made using the class: org.bitsoftware.strl.model.STRL ModelValidator.
When renaming a dashboard in SocrateCloud the Trello board is renamed, only if the board from Trello was created using the process Create Board in Trello. Synchronization is made using the class: org.bitsoftware.strl.model.STRL ModelValidator.
The processes that can be run from a board are: Create Board in Trello, Register Trello Callback and Synchronize Board.
The button is visible only if the process was not already run, specifically, if the board was not already created in Trello.
The process returns an error if the User running it does not have a Trello user setup.
After the process is successfully completed the User ID is saved on the record and a callback from Trello is created which is registered to SocrateCloud. The callback ID together with the token and user are saved on the record.
If an error appears when registering the callback this step is skipped and the board is created. An error may appear if the service which listens to Trello is not on a server that can be accessed by Trello. Even if an error occurs the Key and Token for the user are saved so that later the callback can be registered on the same credentials.
When the board is created the respective Trello lists are created also. The lists represent the K-Board columns defined in SocrateCloud. A Trello board comes with three lists which are renamed and additional lists are added.
Java Class Used: org.bitsoftware.strl.process.STRL_CreateTrelloBoard
The button is only visible if the board was created in Trello and a callback was not registered. In other words, we have a board ID on the record but we have no callback ID.
The callback is registered with Trello authentication data, for the user that had run the Create board in Trello process.
Java Class Used: org.bitsoftware.strl.process.STRL_RegisterTrelloBoardCallback
The button is visible only if the board was created in Trello (we have board ID on the record).
The process synchronizes requests and leads depending on the board type. Only the requests which are on the project and for which the request state correspond with a K-board column are synchronized.
It offers the option to insert and update cards in Trello with requests/leads which have not been synchronized.
Offers the option to synchronize notes on requests (significantly increases the number of API requests and the time it takes to complete the process).
The members on the request are synchronized with card members (only members from SocrateCloud for which the Trello user setup has been completed get saved in Trello).
Data sent to Trello is identical to that sent when updating a request or lead (details below).
Java class used: org.bitsoftware.strl.process.STRL_SynchronizeBoard
Only requests get synchronized and not tasks.
Only requests from the projects which can be found on an active dashboard in SocrateCloud get synchronized (it takes into consideration if the request goes from a project linked to a board to an un-linked project and the other way around).
From the master data:
request subject, estimated time and accumulated time -> card title in the format “[0/12] Subject”;
request due date -> card due date;
request summary -> card description;
request state -> Trello list;
processed state -> archived state;
project -> board;
request members -> Trello members.
The request only takes place if one of the fields above changes it's value. The values are sent all the time except for the due date which is sent only if it's value gets changed to prevent a ping pong effect.
After synchronization the Trello card ID is saved on the request. The synchronization request depends on whether the card ID is present: if the request contains an ID then an update request is made otherwise a card insert request is made.
From the request notes:
accumulated time together with the text on the note -> card comment of format “[5] note text”; the note text which goes as a card comment can be the respective text or the activity name, if the text is missing, the accumulated time of format “[5] Quantity Used: 5”.
Synchronization takes place only if the request has been synchronized with Trello (saved card ID) and contains time text or an activity.
After synchronization the comment id is saved on the note. The synchronization request depends on whether the comment ID is present on the note: if it exists update, if not insert.
From the member list:
only members with setup completed;
if you delete or deactivate a member in SocrateCloud it is delete from the Trello card;
if you add a member to a SocrateCloud request and the user has setup completed it is added to the card;
when running the Synchronize board process, the member list from the card is synchronized by overwriting the Trello member list with the request member list;
If the request/lead is moved from a project which is not linked to a Trello board and it has a card ID saved, a request to close the card is made, otherwise it is not synchronized. If the request/lead is moved to another project linked to a Trello board if it has a card ID, a new card is created. If the request/lead is moved to a state which has no equivalent K-board column and a respective Trello list then, if it has a card ID the card is updated and the list remains unchanged. Otherwise nothing gets synchronized.
Leads may be synchronized only if there is an active Sales Pipeline dashboard in SocrateCloud. Below is a list of what is synchronized:
name of the business partner on the lead or document number together with lead type (if there is a lead type this is added after the number using a “-”) -> card title;
due date -> due date;
lead description -> card description;
lead state -> Trello list;
processed state -> archive card.
Synchronization takes place only if one of the fields above changes value.
The information above is sent all the time except for due date which is sent only if it changes value to prevent a ping pong effect.
If the lead is moved to a state which has no equivalent list in Trello then: if the lead has a card ID the card is updated with the info above and the list remains unchanged, otherwise nothing gets changed.
Synchronization is based on calls made from Trello (callbacks) to SocrateCloud.
In SocrateCloud a callback is registered at the creation of a board in Trello in order to get notifications related to board modifications. If at the Trello Board creation for different reasons the callback cannot be created the Register Trello Callback Button will appear on the record window.
For processing Trello callbacks the Java class is used: org.bitsoftware.strl.rest.Trello Callback . Different API methods are used for requests(.../strl/rest/trello Callback/RK/board) and leads(.../strl/rest/trello Callback/SP/board) in order to read messages differently. The methods are specified when registering the callbacks.
Examples of JSON messages received from Trello can be found in the Git, in the folder: “callback_models”.
When saving the PO (lead/request) a Boolean (non-persistent) variable is saved in the PO which is to be verified in the validator model to prevent another call to be made back to Trello (ping-pong effect). In some cases such calls are permitted in order to correct errors. For each callback a log with the JSON message is created at INFO level (can be followed if the SocrateCloud for Trello web module is activated).
Only update card notifications types are accepted. Only updates to the following fields are accepted: card title, card description, due date, list.
are identified by card ID;
if due date is updated (modified);
if the card title is changed it will be separated in text, estimated value, accumulated value. The request subject, estimated value and accumulated value for the request are modified in SocrateCloud;
if the card description is modified the request summary is updated;
if the Trello list is modified the following actions may take place:
if the Trello list is present on the SocrateCloud dashboard it checks if there is a change in the K-Board value and f so, the request state will be changed accordingly;
if the list is not present on the SocrateCloud board a backlog state with a corresponding type is searched an is set on the request. A new Trello API call is allowed from validator model for the case which in Trello there is a backlog list with the purpose of correcting (to not allow the card to stay on a list which has no SocrateCloud equivalent).
The request is saved and if changes are made the code from the validator model for Trello synchronization will be applied. In the model validator the Boolean variable mentioned above is changed to prevent synchronization, if the request was modified by a Trello callback.
the lead is identified by card ID;
due date is updated;
if the card title is modified a lead update is simulated and a new Trello API call is allowed;
if the card description is modified the lead description gets updated;
if the Trello list is modified the same logic is followed as for requests.
model JSON (data sfarsit modificata)
{
"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": "update Card",
}
SocrateCloud Trello integration must be installed;
SocrateCloud Users which work on requests/leads must have a Trello account and must go through the Trello User Setup.
A configured SocrateCloud Dashboard must exist (request states linked to K-Board columns);
On system level, the Web UI module must be defined (it is necessary to create the link for the API call from Trello to SocrateCloud).
The SocrateCloud admin (which must go through the Trello User setup) defines the boards in SocrateCloud for requests and/or leads and runs the Create Trello Board process. The process runs a single time and on the Trello board the lists corresponding to existing K-board columns will be created. If an error occurs while registering the callback the step can be made later (an error can occur if the STRL web module is not available on the application web server or is not accessible on the web).
On a request/lead update a synchronization call is made to Trello. Users can modify some info in Trello and this can automatically be changed in SocrateCloud (details above).
If a user has not gone through the Trello User setup and updates a request in Trello, no synchronization will be made.
If a user makes a Trello account and does not have access to the board in SocrateCloud when updating requests the Trello synchronization will not be made, and an error message will appear saying the user has no rights to modify the respective Trello card.