- 1.Preface
- 2.Guide Map
- 3.Administrator's Guide
- 4.Project Manager's Guide
- 4.1.Account Authorization
- 4.2.Settings
- 4.3.Sync With Redmine
- 4.4.View Gantt Chart
- 4.5.Edit Gantt Chart
- 4.6.Limitations
- 5.Project Member's Guide
- 5.1.Account Link
- 5.2.Sync On Card
- 5.3.Sort List By Priority
- 5.4.Report Time
- 5.5.View Gantt Chart
- 6.System Requirement
1.Preface
Menu Access
You may access the RedSync menus from a Board menu as follows:
Depending on the configuration, you will find all or part of those menus.
Banner
The following banner means you are currently on the Free plan. If you click the Upgrade link, RedSync opens the Optro marketplace.
Icons
The following icons are displayed on the screens if applicable.
- 🔒Available for Pro Plan (Locking means you are currently on the Free plan)
- ⛔Disabled since you select JSONP for the interface with Redmine
2.Guide Map
The following shows the types of users and their tasks.
User’s guides are provided for each user type as follows:
- Administrator’s Gude
- Project Manager’s Guide
- Project Member’s Guide
3.Administrator's Guide
Redmine Configuration
RedSync requires certain settings of Redmine to integrate with Trello. Settings vary depending on your plan.
Free Plan | Personal & Pro Plans | |
HTTPS | ✔ | ✔ |
REST | ✔ | ✔ |
JSONP | ✔ *1 | |
CORS | ✔ *1 | ✔ *2 |
RedSync Proxy | ✔ *2 |
*1 Free Plan requires JSONP or CORS. You need CORS support if you enable the update of Subject or Description from Trello to Redmine in the Settings. Otherwise, JSONP is enough (You can always use CORS instead of JSONP if available).
*2 Personal and Pro Plans require CORS or RedSync Proxy.
HTTPS
RedSync always requires HTTPS.
REST / JSONP
REST and JSONP are APIs supported by Redmine. RedSync always requires REST.
CORS Support
CORS (Cross-Origin Resource Sharing) is a protocol to access a server (Redmine) from a script (RedSync) in a Web browser loaded from another server. Redmine does not support CORS in the case of a typical installation; hence you need to apply additional configuration to Redmine (Refer to this article).
An alternative solution is RedSync Proxy, or JSONP, described below.
About RedSync Proxy
RedSync Proxy enables the integration between Trello and Redmine without CORS support at the Redmine server.
RedSync Proxy is a server running on AWS. Hence your Redmine should be accessible from the Internet. If your Redmine is available only in your Intranet, RedSync Proxy cannot access it.
RedSync Proxy logs the access to Redmine. It includes the server name, path, and parameters included in the URL. However, it does not include any data exchanged between Trello and Redmine.
Use of RedSync Proxy may cause performance decrease due to the network latency etc.
We recommend using CORS if possible.
Installation
You can install RedSync Power-Up from the menu as follows:
Menu -> Power-Ups -> Add Power-Ups
RedSync adds the Account Link board menu as follows:
Redmine REST Web Service
You need to enable the Redmine REST Web service as follows:
Administration -> Settings -> API
Enable API based on the integration type:
- REST: Enable REST web service
- JSONP: Enable REST web service + JSONP
You must enable REST web service to protect the interface with the API Key. - RedSync Proxy: Enable REST web service
Upgrade to Pro Plan
RedSync has three plans: Free Plan, Personal Plan, and Pro Plan.
You can upgrade to the Pro Plan on Optro.
4.Project Manager's Guide
Operations described in this section require that you have:
- Admin permission to the Board on which RedSync has been installed.
4.1.Account Authorization
You need to authorize RedSync as follows:
Menu -> Power-Ups -> RedSync Settings -> Authorize account -> Authorize -> Allow
4.2.Settings
You can start the Settings of RedSync as follows:
Menu -> Power-Ups -> RedSync Settings -> Edit Power-Up settings
RedSync opens the Settings window. You can select the target of settings by clicking a tab on the top of the window.
Redmine Server Settings
Make the settings to access the Redmine server.
Server
Specify the URL of the Redmine server (HTTPS required).
Access with JSONP
RedSync accesses Redmine with JSONP API. Redmine does not need to support CORS. However, the update from Trello to Redmine is not supported. RedSync disables the setting items related to it and displays a ⛔ icon.
Access via Proxy (Pro Plan)
RedSync accesses Redmine via RedSync Proxy. Redmine does not need to support CORS. The REST API of Redmine is used.
API Key
Specify the Redmine API Key.
RedSync uses the API Key to synchronize Cards and Issues in the Sync with Redmine operation described later. The user of the API Key should have the authority to update Issues (e.g., assigned to the project as a developer or a manager).
By clicking the Validation button, RedSync displays the user name of the API Key for confirmation.
You can get the API Key from Redmine.
Refer to How To Get Redmine API Key
Project
Select a project to be connected with Trello.
Edit*
Click to unlock the above fields.
* Displayed conditionally. Once the server and project are determined, RedSync locks their fields. You have to unlock them by clicking the Edit button to change them.
When you change the project, RedSync archives the currently connected Cards or moves them to the specified List, if any, then creates new Cards from Issues in the newly specified project.
When you change the server (and the project), you have to archive all the currently connected Cards beforehand because there may be a project or Issues which coincidently have the same ID in the new server.
Timezone
Select a timezone for the Redmine server.
Start Time
Select the time of the Issue’s start date.
Due Time
Select the time of the Issue’s due date.
Redmine does not have a timezone for start and due dates. RedSync uses the above timezone to convert Redmine’s start and due dates to Trello’s start and due dates with time.
Sync with Redmine Settings
Make the settings for the Sync with Redmine operation.
List for New Card
Select a List on which RedSync creates a new Card. After the creation, you can move it to any List.
Disconnected Card
If a Card has no connected Issue or the connected Issue is private, RedSync considers the Card disconnected. In such a case, you can ask RedSync for one of the following options:
Archive: If checked, RedSync archives the Card.
Move to List: If checked, RedSync moves the Card to the specified List. You can archive all Cards on the List from the List menu.
RedSync provides a tool to delete archived Cards.
Refer to Archive Manager.
Create New Card for Closed Issue
If checked, RedSync creates a Card for a closed Issue. Otherwise, RedSync ignores the closed Issue.
Archive (or move to List) Card for Closed Issue
If checked, RedSync archives (or moves) a Card for a closed Issue (to List).
Include Issue ID in Card’s Title
If checked, RedSync includes an issue ID in a Card’s title as a prefix. This is an exclusive setting with synchronizing Subject from Card To Issue described below.
Synchronize an assigned user from Issue to Card
If checked, the issue assignee will be synchronized with the card members.
Please note that this synchronization will always be additive only. This is because an issue can have only one assignee, while a card can have multiple members specified. RedSync cannot determine if the assignee has been removed from the card members.
Synchronize from Card to Issue
- Subject
- Description
If checked, RedSync synchronizes the item from Cards to Issues. If not checked, RedSync synchronizes it in the opposite direction. In both cases, RedSync overwrites any change on the other side.
Synchronize Sub-projects
Specify if issues from sub-projects should be included.
- Include Issues from sub-projects
- Exclude Issues from sub-projects
- Follow Redmine Settings
If you configure Redmine to “Display sub-projects issues on the main project by default” in Settings, RedSync synchronizes issues from sub-projects.
Sync On Card Settings
Make the settings for the Sync On Card operation.
Shared API Key (Optional)
Specify API Key from Redmine.
RedSync uses the Shared API Key to access Redmine when the Account Link has no API Key. Use of the Shared API Key is optional.
See the following for details.
How To Get Redmine API Key
Indivisudal API Key vs. Shared API Key
Editable on Card (Pro Plan)
If checked, the item is editable on a Card. Otherwise, it is read-only.
- Status
- Progress
- Tracker
- Priority
- Category
Redmine’s workflow, roles, and permissions also protect those items. Even if an item is editable in this setting, Redmine may reject the update.
Link Settings
Specify whether to display links to related issues on a card. These links will be stored as card data, hence there is a limit (here) to the number of links allowed. If the limit is exceeded, you can avoid the limit by not including links on the card.
If checked, links to the related issues will not be displayed on the card.
- Do not include links to related issues
Custom Field Settings
Make the settings for the synchronization of the custom fields between issues and cards.
Standard Fields
Make the settings for synchronizing from the Standard Fields defined in the Redmine Issue to the Custom Fields defined in Trello Card.
Redmine’s Standard Fields | Types of Trello’s Custom Fields |
project status tracker progress priority category id (issue number) assignee | Text |
RedSync shows you the Standard Fields in the Redmine Data section of the Card. However, Trello does not recognize the Redmine Data section; hence you can not use the Standard Field for filtering Cards or triggering a workflow (Butler) or cannot show the Standard Field on the List. By mapping the Standard Field to the Custom Field, you can use it for those operations.
Custom Fields – Redmine to Trello
Make the synchronization settings from Redmine’s to Trello’s custom fields.
Types of Redmine’s Custom Fields | Types of Trello’s Custom Fields |
Link | Text |
User | Text |
List | Text |
Key Value | Text |
Long Text | Text |
Text | Text |
Bool | Text | Checkbox |
Date | Text | Date |
File | Text |
Float | Text | Number |
Integer | Text | Number |
Version | N/A |
RedSync shows all custom fields associated with Issues in the dropdown list to select. The dropdown list may contain custom fields unrelated to the current project; hence please avoid selecting those custom fields.
Custom Fields – Trello to Redmine (Pro Plan)
Make the synchronization settings from Trello’s to Redmine’s custom fields.
Types of Trello’s Custom Fields | Types of Redmine’s Custom Fields |
Text | Text |
Dropdown | Text |
Number | Text |
Checkbox | Text | Bool |
Date | Text | Date |
RedSync shows all custom fields associated with Issues in the dropdown list to select. The dropdown list may contain custom fields unrelated to the current project; hence, please avoid selecting those custom fields.
Admin Settings
Allow other Board admins to execute Sync with Redmine
If checked, anyone with the Admin privilege can perform the Sync with Redmine operation. If not, only the person who did these settings can perform the Sync with Redmine operation.
Allow other Board admins to edit Gantt chart
If checked, anyone with the Admin privilege can edit the Gantt chart. If not, only the person who did these settings can edit the Gantt chart.
Enable Personal Plan
You can enable the Personal Plan by checking “Enabling Personal Plan.” With the Personal Plan, you can use all functions the same with the Pro Plan. However, the number of board members is limited to one.
4.3.Sync With Redmine
You can initiate the Sync with Redmine operation as follows:
Menu -> Sync with Redmine
RedSync performs the synchronization and shows the in-progress status.
During the synchronization, RedSync performs the following operations:
- Create a new Card if Redmine has a new Issue.
- Archive a Card if the connected Redmine Issue is missing (probably deleted).
- Move the Card to the specified List if Move to List is checked in the Settings.
- Start Date
- Sync Issue to Card always.
- Due Date
- Sync Issue to Card always
- Subject / Description
- Sync Issue to Card when:
- Synchronize from Card to Issue on Sync with Redmine is checked in the Settings.
- Sync Card to Issue when:
- Synchronize from Card to Issue on Sync with Redmine is not checked in the Settings.
- Sync Issue to Card when:
- Members
- Synchronize Assigned User is checked in the Sync with Redmine, the issue assignees will be added to the card as a member.
You can perform this operation when:
- You are an administrator of the Board, and
- You made the Settings or Allow other administrators to execute Sync with Redmine is checked in the Settings.
- If you are another administrator who did not make Settings, you have registered your API Key via Account Link.
Suppose you are not the same person who made the Settings; RedSyncnc shows a warning that the synchronization may result in inconsistencies between Cards and Issues if you and another person execute synchronizations simultaneously. If you are sure there is no simultaneous synchronization, you can continue the operation.
See also Sync with Redmine vs. Sync on Card
4.5.Edit Gantt Chart
A board administrator can edit the Gantt chart. If you have multiple administrators, you have to set a guideline to avoid multiple administrators editing the Gantt chart simultaneously. If they edit the Gantt chart at the same time, it may cause inconsistency between the editing result and its appearance.
To start editing, click the Lock / Unlock Schedule icon to unlock after opening the Gantt chart from the board menu.
Add Issue
Right-click on the project bar to add the first issue.
Click the Create child issue popup menu. RedSync shows the New Child Issue dialog.
Enter items to the New Child Issue dialog. Click the Save button when finished.
Right-click an issue bar to add the second and subsequent issue.
Click the Create child issue or the Create sibling issue. If you click the Create child issue, an issue is created as a child of the current issue. If you click the Create sibling issue, an issue is created at the same level as the current issue.
Delete Issue
Right-click on an issue bar to delete the issue.
Click the Delete issue, and RedSync displays the confirmation dialog box.
Click the Delete button.
Change Issue’s Schedule
Drag the right or left edge of an issue bar to change the issue’s start date or due date respectively.
Drag an issue bar to change the issue’s schedule keeping the same duration.
Restrictions on Changing Schedule
If an issue has a preceding issue, there are restrictions on changing its schedule based on Redmine’s behaviors.
- You cannot set the start date of the issue before the earliest starting date.
- You can set the start date of the issue after the earliest starting date. However, if you moved the preceding issue, the start date is forcedly set to the earliest starting date.
Earliest Starting Date – If there is a delay in relation to the preceding issue, it will be the first business day after the due date of the preceding issue, adding the number of days of delay. If there is no delay, it will be the first business day after the due date of the preceding issue.
Regardless of the preceding issue’s existence,
- If you drag an entire issue, the start and due dates are adjusted to avoid overlapping with weekends.
- If you drag the start date of an issue on the weekend, the weekend will not be included in the working days of the issue.
- If you drag the due date of an issue on the weekend, one day will be added to the working days of the issue.
Change of Delay Setting
To change the delay setting for a preceding issue, press the ALT key (Option key for Mac) while dragging either the entire issue or the left edge (start date).
The delay will be removed if the modified start date falls immediately after the preceding issue. Otherwise, the delay will be updated.
If there are multiple preceding issues, all issues’ delays will be reassessed. If you want to change the delay for a specific issue only, you can remove the connection from the popup menu and create it again.
Change Issue’s Parent
Drag an issue on the issue tree and drop it on another issue which is a new parent. Hold a mouse button on the issue node to grab the issue.
When the Gantt chart is loaded, issues are ordered by their start dates. After changing the parent, the order of issues may be disordered. You can reorder them by clicking the Reorder icon (🔄) or right-clicking the right-hand canvas’s white space (no bars).
Add Connection between Issues
To add a connection, move the mouse pointer to the outside of the origin issue bar. RedSync shows a triangle as a starting point of connection. Click it.
Move the mouse pointer to an issue to be connected. Click on it. RedSync shows a dialog to input parameters for the connection.
If you select the Preceding as a relation type, RedSync asks you a delay days. If you left it blank, the following issue starts on the working day immediately after the preceding issue.
Delete Connection
Right-click the destination issue bar (connected line end with an arrow) of the connection to be deleted.
Click the Delete relation.
RedSync shows you the list of connections. Click the garbage can icon.
4.6.Limitations
Number of Cards
The number of Cards per Board is limited to 5,000 (as of this writing in April 2022). If you have more than 5,000 Issues in the Redmine project, the Sync with Redmine operation may fail. In such a case, please consider the following:
- Make the settings not to create a Card for the closed Issue and archive the Card when the connected Issue is closed
- Divide the project into subprojects, and sync each subproject to a different Board
Number of Links
An Issue can have links to related Issues. The number of links per Issue is limited to about 30.
If you have more than 30 links in your project settings, you can disable showing the links in a Card. Otherwise, Sync with Redmine operation may fail.
5.Project Member's Guide
5.1.Account Link
You have to register your API Key for the Redmine account. If you do not have an account on Redmine, you can skip this (but please confirm it with your project manager).
Menu -> Account Link
RedSync displays a dialog to input the API Key. You can get the API Key from your Redmine account.
Refer to How To Get Redmine API Key.
Validate your API Key by clicking the Validate button. RedSync shows the user name associated with the API Key.
5.2.Sync On Card
When you open a Card, Redmine shows the Redmine Data section that data RedSync retrieves from the Redmine Issue.
It contains the following data items:
- Project
- Tracker
- Status
- Progress
- Priority
- Category
Depending on the Settings, some of those items are editable, and you can update them. However, Redmine’s workflow, roles, and permissions associated with the API Key also protect those items. Hence when you update those items, you may be noticed their value does not change.
The section also includes the following links:
- Parent Issue – Open the parent Card if any
- Child Issues – Open the child Card if any
- Related Issues – Open the related Card if any
- Issue – Open the connected Issue in Redmine
You can also update the following fields on the Card, but RedSync may overwrite them in the Sync with Redmine operation, depending on the Settings.
- Subject – Synchronized from Card to Issue or vice versa
- Description – Synchronized from Card to Issue or vice versa
- Start Date – Always overwritten with the start date in the Issue
- Due Date – Always overwritten with the due date in the Issue
5.3.Sort List By Priority
You can sort the Cards on a List by Priority.
5.4.Report Time
You can log working time to Redmine Issue via a Card.
- Pro Plan – You can create, update, and delete the working time. However, some of those operations may be prohibited depending on your roles and permissions as a Redmine user.
- Free Plan – You can display working time.
Click Log Time on the Card menu to report working time.
RedSync displays the following dialog.
Click Edit, then RedSync displays the following dialog to edit the log time.
5.5.View Gantt Chart
A project manager and members can view the Gantt chart from the board menu.
Menu > Gantt
Move the mouse pointer to ℹ️, and the description of icons and connections is displayed.
The Lock/ Unlock Schedule icon is locked for the free plan. It is also locked for the pro plan but can be unlocked by clicking the icon.
The Zoom-out and Zoom-in icons change the calendar duration.
Move the mouse pointer on an issue bar, and the issue details are displayed.
6.System Requirement
Redmine
Versions: 4.1, 4.2, 5.0
Protocol:
- HTTPS
- CORS (Cross-Origin Resource Sharing) (Optional) (Check Here)
The Redmine server should be accessible from the user’s browser (not necessary to use Redmine UI, but RedSync should be able to access the Redmine server from the browser).
Please also refer to the following articles for HTTPS and CORS configuration.
Browser
Tested with Chrome, Firefox, Safari, Edge
7.Support
We provide RedSync power-up on an “as-is” basis with Q&A support only.
Please submit any questions or defects to the Github:
We welcome your feedback and feature suggestions. Please submit them to the Github as well.
8.Appendix
8.1.How To Get Redmine API Key
You can get the API Key as follows:
My Account -> Access Key -> Show
8.3.Archive Manager
You do not need to delete the archived Cards in general. Trello provides enough capacity for holding the archived Cards. However, you may want to delete them if you want to make sure they are not restored.
Archive Manager allows you to delete the archived Cards altogether.
You can enable Archive Manager as follows:
Menu -> Power-Ups -> RedSync Settings -> Edit Power-Up settings
At the bottom of the Setting window, there are two option switches.
Turn on the Maintenance switch, then RedSync shows the Archive Manager board menu.
8.4.Sync with Redmine vs. Sync on Card
RedSync synchronizes Trello Card with Redmine Issue by either Sync with Redmine or Sync on Card operation as follows:
Item | Sync with Redmine | Sync on Card |
Card | ||
Card Creation | X | |
Card Archiving | X | |
Card Fields | ||
Schedule | X | |
Completion Flag | X | |
Name | X | |
Description | X | |
Redmine Data (on Card) | ||
Tracker | X | |
Status | X | |
Progress | X | |
Priority | X | |
Category | X | |
Parent | X | |
Children | X | |
Relations | X |
Sync with Remine is a batch operation and triggered by the user, while Sync on Card is a real-time operation and activated by just opening a Card.