A browser extension to handle reported issues (users and notes) on the OpenStreetMap website. Allows to quickly create OTRS tickets from issues and to add OSM messages to tickets. Mainly of interest to OSMF Data Working Group members. An alternative to osm-dwg-userscripts without requesting/storing OTRS account login/password.
Available as a Firefox addon on addons.mozilla.org since v0.1.2. Older versions can be downloaded as xpi files from github releases. osm_dwg_helper-version-fx.xpi files are signed Firefox releases. There are also osm_dwg_helper-version.zip files for non-browser-specific releases. They should be installable on any browser that supports running unsigned extensions. For example, on Chromium you can drag-and-drop it into the Settings > Extensions page (chrome://extensions/). No browsers other than Firefox and Chromium have been tested yet.
See CONTRIBUTING.md for instructions on installing from the source code.
After a successful installation the extension is going to be available as a sidebar on browsers that support sidebars (View > Sidebar > DWG Helper in Firefox) and as a toolbar button opening a popup. First thing that you'll need to do is to grant this extension permissions to access to OSM and OTRS websites. This action is separate from granting permissions during the installation in order to avoid hardcoding urls of these websites in the extension manifest. It's possible to change those urls in the extension options.
Automatic updates of the extensions are available if installed from addons.mozilla.org. Updating the extension is likely to be important because it relies on the specific markup of certain OSM web pages. Changes to those may break the functionality. Last known breakage happened on 2021-11-11 before the v0.1.0 release, also affecting v0.1.1. You need to update the extension if you're running an older version. See CONTRIBUTING.md for details.
Overall the goals were:
- speed up some common actions that a DWG member might want to do by replacing copy-pasting various things with clicking
- avoid additional logins present in other similar tools
- don't submit actions right away so they can be reviewed and altered if necessary
- try not to alter the webpage contents too much, keep most of the controls inside the extension panel (currently available as a sidebar) - this may change as further development required altering issue pages, but most of alterations should be marked with the extension icon
The standard procedure for converting an OSM issue into an OTRS ticket involves opening a Create New Phone Ticket form in OTRS and populating its fields with information from the OSM issue webpage. You can do this manually by copy-pasting which is tedious, that's why this extension was created to automate creating tickets from issues.
You start by opening the issue webpage (https://www.openstreetmap.org/issues/id). Then you click the Create ticket link in the extension panel. This should open a Create New Phone Ticket form, giving you the opportunity to change ticket details. Before clicking the link you may select the reports and comments to be included in the ticket. By default, all new reports and no comments are selected.
The new ticket form is going to have all of the required fields set. These fields are:
- Customer user containing usernames of users who reported the issue formatted as email addresses. If the issue was reported by several users and more than one report was selected, multiple customer user values will be set. Customers have an email address specified in the Customer template extension setting, which is set to
@dwgmail.infoby default. - To queue set to a first valid queue. In case of the current DWG setup this is going to be a generic Data Working Group queue. You may want to change the queue right away to something more specific. Changing the queue later, when the ticket is already created, may do other possibly unwanted things like unlocking.
- Subject containing the issue id and the reported item.
- Text with selected issue reports and comments.
When the reported item is a user, there's an additional option to create a ticket - + scan user id. If you choose this option, the extension is going to open the user profile before proceeding to the OTRS new ticket form. While on the user profile page, the id of the user is detected to be later added to the ticket. This might be helpful in case the user changes their name which can happen anytime.
Another thing you may encounter before the Create New Phone Ticket form is the OTRS login form. This happens if you haven't yet logged in OTRS with your browser, that is, if you haven't successfully opened any page on the OTRS website, or if your login timed out. Just enter your OTRS username and password as usual and, after a successful login, you'll see the ticket form. Usernames and passwords are not read and stored by this extension, all the credentials management is done by the OTRS code.
Last thing that happens is that the issue gets its comment form filled with a link to the newly created ticket. This doesn't yet submit the comment which could be done manually or with a help from the extension. There will be an update issue entry under Ongoing actions with a button that reads either resolve issue or comment issue. Clicking resolve issue will submit the comment and resolve the issue. Resolving is only available if all new reports were selected to be added to the newly created ticket. Otherwise there are more reports that were probably saved for another ticket, therefore resolving may have to wait. After dealing with these reports you can resolve the issue manually.
As noted above, when tickets are created using this extension, the reporting users are automatically added as customers with @dwgmail.info addresses. In the current DWG setup these addresses serve as means to send and receive user messages from/to OTRS. However the implementation of this OTRS-to-OSM messaging bridge is located outside of OTRS, OSM and this extension and may come with limitations. Its possible for a username to be processed incorrectly, especially if it contains special characters. There are also message text conversions that may mangle the text. Until recently the DWG setup had a html-to-plaintext-to-kramdown-to-html conversion of roundtrip messages. Currently the plaintext stage is avoided, but html-allowed-inside-OTRS and html-produced-by-kramdown still have differences that may lead to formatting losses.
If you want to be absolutely sure that the message is sent to a specific user and want to know exactly how its text is going too look, you may create it directly on the OSM website. After that, of course, you'll have to add it manually to the OTRS ticket, and do the same thing for the reply once you receive it. That is, you'll have to do the things that the mail forwarding system was supposed to automate. But if you still want to send messages through the OSM website, or already have the messages you want to add to a ticket, the extension can help you with copy-pasting them. When on the OTRS ticket page, use Add last outbox/inbox message to ticket in the extension panel to quickly add the last send/received message. You can choose to add it either as note without any additional actions or as pending which lets you specify a pending reminder/autoclose along with the message.
In order to add a message that is not necessarily the last one in your inbox/outbox take the following steps:
- Navigate to an OTRS ticket page.
- Open a new browser tab and navigate to the necessary message on the OSM website, or just switch to the message tab if it's already open.
- Switch back to the tab with an OTRS ticket.
- Add message from/to username to ticket links should appear in the Other Tab Actions menu of the extension panel. Click one of those links.
Sometimes, after creating a ticket, you discover another issue about the same thing or that new reports got added to the original issue. For example, this happens when two users report each other. At first you may come across only one of those reports and create a ticket for it. Later you may discover another report and decide that it belongs to the already existing ticket. Thus you can't use the Create ticket command but you probably still don't want to copy-paste stuff from issue pages.
In order to add reports to an existing ticket, use Add selected reports/comments from issue in the extension panel. Using it is similar to adding an already posted OSM message. The panel entry appears when you switch from an issue tab to a ticket tab when the issue contains selected reports or comments. By default unread ("new") reports are selected, but you can change the selection with checkboxes similarly to when creating a new ticket. The reports, like messages, can be added as either a ticket note or a pending item, with subject and body similar to the ones you get by creating a ticket. After the reports are added, the issue gets commented with a link to the ticket, again similar to what happens when creating a ticket. You'll have to resolve the issue to turn unread reports into read ones that won't be selected by default and picked up by this extension feature.
If you've issued a block, you can add it to a ticket in a manner similar to adding messages/reports. Open the block tab, then switch to the ticket tab, and Add block record should appear in This+other tab actions menu. Clicking one of the links below it opens a new ticket article with a link to the block. It also adds block issued to DWG Actions free field. Since this is a DWG-specific field not present in default OTRS configurations, the name of its input can be configured in the options.
Sometimes you don't want to create a ticket for an issue. You may want just to send a message to the reporting user and resolve te issue. To quickly do this from the issue page, click the username under Quick message reporting user in the extension panel. The list of users in the menu includes only those who have at least one report selected with a checkbox. After clicking the username a new OSM message form will be opened with a pregenerated subject.
- Go to the issue page corresponding to an OTRS ticket title from a ticket page.
- Search OTRS for reported items in issues.
- Translate issue reports.
- A pane is added for opening the reported item directly inside the issue webpage. This should make it faster to deal with reported notes that don't require creating a ticket.
- A pane is added for OSMCha page of the reported user. The default two-week time limit is disabled, allowing to see all of the user's changesets. Issue reports are scanned for changeset links. These links open their changeset inside the OSMCha pane. Middle-click opens them in a new tab. The OSMCha pane insertion requires working against cross-site frame permissions and may not work on some browsers.
The extension can be set up work with other Rails Port (OpenStreetMap web server) and OTRS instances.
- any version with 2021-11-11 changes
- any user account is enough for message/translation/search-related functionality
- moderator account for issue-related functionality
- use the OpenStreetMap root URL option to setup your Rails Port instance
- default value for DWG workflow is
https://www.openstreetmap.org/ - value for dev.openstreetmap.org-hosted sandbox is
https://master.apis.dev.openstreetmap.org/
- default value for DWG workflow is
- there's also the OpenStreetMap API root URL option
- currently only in use to provide links to user ids, because all user links on the web server use display names
- no data is read by the extension from this address
- default value for DWG workflow is
https://api.openstreetmap.org/ - sandbox value is
https://master.apis.dev.openstreetmap.org/
- ((OTRS)) Community Edition 6.x, which is discontinued, or one of its forks
- checked to work with Centuran Consulting fork
- agent account for all ticket-related functionality
- use the OTRS root URL option to setup your Rails Port instance
If you want to try Centuran fork online demo:
- to avoid accidentally submitting real issue data, set up the Rails Port sandbox or other dummy instance as described in the previous section
- go to demo.otrsce.com or new.demo.otrsce.com
- click Open Agent Interface
- change the extension option OTRS root URL to either
https://demo.otrsce.com/orhttps://new.demo.otrsce.com/
Part of the code that processes the mail sent from OTRS is available here. You likely want to put the receiving email address in the Customer template extension option.
The main functionality of this extension is creating tickets from issues. Aside from creating tickets manually, there's dwg_issue2ticket.user.js script from osm-dwg-userscripts to automate this task. Instead of opening the new ticket form and populating its fields, the script uses OTRS API calls to create a ticket. This requires the API call to be configured. The script also has to manage the OTRS logins/passwords independently from the usual OTRS browser login form. Automatically creating issue comments is only going to work if the CORS Everywhere addon is installed.