Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Emergency Alerts Signup form and services.
API Guide / listing of all end points provided by boston.gov (Drupal 8).
Boston.gov integrates with many services across the City. Here is a run down of the methods for integrating with the website.
Depending on the level of complexity, a restful API can be used to integrate with Boston.gov. Currently, the CityScore module connects to an API to display data on the CityScore page.
Some things to keep in mind when building against an API:
Try to use existing modules when possible. We currently utilize a Salesforce module to bring data in for MetroList.
Use migrations if possible to store data locally when the data doesn’t change frequently and isn't likely to grow exponentially. This allows us to use Views within the sites.
Boston.gov provides some APIs of its data. Currently, the following APIs are available:
The next five upcoming events can be retrieved in JSON format from /api/v1/upcoming-events
.
All upcoming public notices can be retrieved from /api/v1/public-notices
. This is rendered in JSON format.
Blank layouts that can be used by external applications exist at /api/v1/layouts
. Currently, only /api/v1/layouts/search
is available, but more will be added.
The blank layouts should be used by external applications to provide wrapper HTML. This will also provide the necessary updates to navigation as things change at Boston.gov.
In the search example, we include the necessary <%= yield %>
tag that is used by our Rails based search application.
A method of creating PDF's or modifying template PDF's was required to serve customized PDF's for various applications on the website.
The solution needs to be a generic service exposing functions and an interaction workflow to enable different (and new) applications to use the solution (to generate or modify the PDF's as needed) without rewriting the PDF Manager module itself.
A Drupal module is provided which can manage the generation of PDF's on boston.gov. The module provides a series of methods and properties which can be used to create, manipulate and access PDF's.
A limitation of all the PHP libraries found (and in general all open-source libraries for all platforms in our tech stack -i.e. php, javascript) was that the form elements in fillable pdfs were removed during processing. This meant that the libraries returned a flat non-fillable PDF even if the original document was fillable. A CLI application was found, PDFToolkit (pdftk) which provides specific functionality to manage fillable PDF.
The PHP library FPDF was leveraged to create and edit PDFs along with 2 extensions to allow the importing of existing PDFs and the creation of barcodes.
During phase 1, a Drupal module PDFManager was created which is capable of:
adding text or any color, size and supported font to a new or existing document,
overlay images onto an existing document,
generate a unique barcode or barcodes and overlay those onto an existing document,
update the pdf's document properties (author etc)
The module can create a new PDF or alter an existing PDF (e.g. a template). However, if a fillable form type PDF is used as a template, the form fields are stripped and the output from the module will be a flat file. This limitation is mostly removed in phase 2.
The pdf document manipulation is defined by a json file, and this file can be parameterized. Using the json file Drupal CMS content and/or content from an external database can be injected onto the form.
This module can be used by any other module in Drupal.
The CLI package PDFToolkit (pdftk) was leveraged and a City of Boston managed API was deployed in AWS as a microservice to create and edit fillable PDF's (fillable forms).
The pdftk runs from a Linux command line. The main Drupal site (served by an Acquia webserver), while running on Linux is not managed by City of Boston and the pdftk libraries are not loaded on that server. Given the short time constraints, the pdftk was deployed within the same container as the DBConnector, leveraging the existing endpoint services (node/javascript/express) and some shellscripting.
The PDFManager module functionality was extended using this microservice to:
insert text into a fillable field in the form
return a fillable form to the caller (provided a fillable form was used as a template)
With Phase 2, the module can modify and return a fillable form PDF, but still cannot create a fillable form, nor can it add (or remove) fields to a PDF.
The Drupal PDFManager module is found here:
Adding the code in that folder to a Drupal site, then enabling the module in Drupal is all that is needed to install it.
The actual document manipulations (for both phases) are done by the class PDFManager.
While the PDFManager module is a Drupal module, the actual PDFManager class itself has no dependencies on other Drupal code, and hence can be used in any other PHP application.
The PDFManager class is included in any other class or PHP script by referencing the namespaced module:
Generally the workflow is to create a new instance of the object, then to pass in static data regarding filenames and data to be applied to the document, and finally to generate the document.
This example shows a simple use of the PDFManager to complete flat PDF.
This example shows a simple use of the PDFManager to complete a fillable form PDF.
There are more complex examples in bos_assessing
- pdf.php
and pdf2.php
, these also show how a json file can be used for managing the text and barcode insertions, and how it can be parameterized so that data can be injected from a database.
Additional functionality can be added to the PDFManager in the future, for example to extend it to be able to create fillable pdfs from scratch, and/or to add fillable fields to an existing document.
To extend, simply modify the code in either the Fpdf.php
or PdfToolkit.php
classes as needed, and maybe to the PdfManager.php`
If a new PHP library or remote endpoint is utilized, it is recommended that a new class be created, as in the example below. This class would then need to be added to PdfManager.php
and code added and/or new methods exposed to utilize it.
All public methods from this class should have error trapping so that errors do not bubble up to PdfManager. When an error occurs capture the error into the class error variable and then return FALSE. Code in the PdfManager should then check for an error and act accordingly.
Further information about the cityscore micro services.
There are 2 views which drive the get
requests for the endpoints.
The views have a dependency on the views_php
contributed module.
These views are defined at: /admin/structure/views/view/cityscore/edit
.
Display: Cityscore.
This display provides a full Drupal page containing the current cityscore table of metrics. The "page" URL for this is /rest/cityscore/html-table
. Because this is a fully themed Drupal page, it is more usual for the endpoint /rest/cityscore/html
to be used, as that endpoint provides just the <table>
HTML wrapped in a <div>
tag.
Display: JSON Output.
This display provides a JSON array with a single object being the current Cityscore total. The current Cityscore total is the mathematical average (mean) of all current non-null metrics.
This view is available at the endpoint /cityscore/totals/latest.json
. Because this is the output from a view, the JSON string is wrapped as an array. For backwards compatibility the endpoint /rest/cityscore/json
is used.
The endpoints provided at rest/cityscore/load
, /rest/cityscore/html
and /rest/cityscore/json
are all tracked on google analytics. Filter for pageviews named "/api".
There is a requirement to provide partially completed, fillable official City of Boston PDF forms to constituents on demand in Q3 of each financial year.
In 2023 for Q3 FY2023, this was migrated into Drupal because the existing PDF solution (a compiled .net solution using a third party iText component) was not available.
A solution was needed where a form would be filled out and returned to the user using "tax bill" data from the current assessing database on VSQL01.
The pdf should be available as a "GET" download with a "parameterized" url so it can be used as a dynamic link in webpages.
A get endpoint was designed which has a url format of:
The return is the correct form for the form-type (a pdf), completed with information from the property defined by the parcel_id. The file is downloaded as an application/pdf.
The first link provides a flat file which is not fillable, and the second (v2) is a fillable PDF.
Cityscore is a CoB city-performance metric devised by the Mayors office, calculated and managed by the analytics team.
Drupal (via https://www.boston.gov) is used to provide a public endpoint or micro service which can be used by other departments or external organizations to retrieve current cityscore data for use in their own applications.
POST
https://www.boston.gov/rest/cityscore/load
This secure endpoint is used by analytics to load and update the current cityscore data.
Payload Format.
GET
https://www.boston.gov/rest/cityscore/json
This public endpoint returns the latest cityscore indicator value.
GET
https://www.boston.gov/rest/cityscore/html
This public endpoint returns an HTML string which contains a cityscore metric table using the CoB style.
API Feed for Status Items from boston.gov.
GET
/api/v1/status_items
Status Items are information cards which are maintained by the website Content Editors to advise constituents on the status of various (usually physical) city services.
Conceptually, a status item relates to a city service (parking, street sweeping, city office opening hours etc) and contains a set of messages that can be displayed at different times.
The only place we presently display status items is on the homepage.
The API is consumed by the ConnectedBits mobile App, which calls the API periodically to get an update on the status items. The ConnectedBits App checks for added/deleted status items and the updated_at
field from the API and alters content on the App as necessary. The response format is customised to meet requirements provided by ConnectedBits in this document.
The main status item entity is a node called status_item
. The status_item node contains:
a title field which is the name of the status item,
a link to an icon,
a field to enable/disable the status item, and
a collection of messages to show for the status item.
Each message in the collection is a message_for_the_day paragraph entity which contains:
the text for the message and
information on when the message will be displayed.
The API is implemented using a view display (view:status_items
- display: bos_311_motd_api
[Bos311]). The view handles the selection and filtering of the information that will be provided by the API.
There is a small amount of pre-processing code in the node_status_item.module
and bos_messages.module
to validate and de-duplicate records to be usre the output matches that which is displayed on the site at the time the API is called..
There is a Drupal View Formatter (a style plugin) Bos311Serializer.php
which is used to re-organize the fields once the view has completed processing. This class does not filter or otherwise alter the view output other than ensuring the json result is organized in the format required by the ConnectedBits specification document (above).
The
An endpoint was written using PHP in the Drupal framework, utilizing the .
Name | Type | Description |
---|
payload | string | A JSON formatted array of cityscore metric objects. |
api-key | string | Authentication token |
See general notes on Upaknee.
Upaknee API documentation: Upaknee re-subscribe API
These subscribe/unsubscribe services are contained in the module bos_email
.
There are REST endpoints provided at:
/rest/email_newsletter
/subscriptions (legacy)
City of Boston use PostMark to relay emails.
Code for this service/endpoint is contained in the module bos_email
.
POST
/rest/email_token/create
Provides an email session token which must be supplied as a field when the form is submitted to therest/email_session
endpoints.
The session token is saved against the users session on the server.
POST
/rest/token/remove
Invalidates a previously created email session token.
POST
/rest/email_session/{server}
POST
/rest/email/{server}
Use email_session for additional security.
POST
/emails
Public Notices are contributed directly into Drupal by Content-Editors. This endpoint provides filtered and sorted lists of Public Notices.
GET
https://www.boston.gov/api/v2/public-notices
This endpoint provides a listing of the next 30 public notices which started in the last 3 hours or will start at some time in the future.
Response Notes:
All response fields are always strings.
Blank (empty) fields are still provided as key:value pairs, with the value being an empty string ("") - the API does not use the keyword "null".
Title, body and field_drawer may contain basic HTML mark-up.
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
authorization*
String
token {token}
email["token_session"]*
String
The session token.
email["to_address"]*
String
The recipient.
email["from_address"]*
String
The sender.
email["subject"]*
String
Subject for email.
email["message"]
String
Body for message (contactform)
email["useHtml"]
Int
Should mail be HTML format? 1 or 0
email["template_id"]
String
Use a POSTMARK template
email["cc"]
String
CC recipients for email.
email["bcc"]
String
BCC recipients for email.
email["{string}"]
String
Any other fields required by templates.