diff --git a/docs/service_interactions.md b/docs/service_interactions.md new file mode 100644 index 0000000000000000000000000000000000000000..85147e60b4779866f766b0c1f6f65f28dc9d9897 --- /dev/null +++ b/docs/service_interactions.md @@ -0,0 +1,79 @@ +# Service Interactions +Documentation of how BP buildings interacts with other services + +- [Building Service](#building-service) + * [building endpoint](#building-endpoint) + * [turkhit endpoint](#turkhit-endpoint) +- [Document Service](#document-service) + * [document endpoint](#document-endpoint) +- [Utility Service](#utility-service) + * [bills endpoint](#bills-endpoint) + * [account endpoint](#account-endpoint) + +## Building Service +Building service has two endpoints that are used in BP buildings. + +### building endpoint + +The building endpoint is used in the SearchBar and Building containers. + +The building index _GET_ endpoint is used on the home page of BP buildings to search through the buildings database. The home page search is currently limited to searching by bbl or address. Functionality is planned to allow search by the other two filter parameters in the building endpoint: lot\_id and building\_id. + +The building _GET_ endpoint is also used on the building detail page to fetch a single building's data. + +### turkhit endpoint + +All turkhit endpoints are called by the Dimensions container. All turkhit endpoints are used on the building dimensions section of the building detail page: /buildings/:building\_id/dimensions. + +The turkhit _GET_ endpoint is used by the buildings page to get the current hit status of the mechanical turk job and a list of all of the documents in box related to building dimensions. Currently if the hit status is in a reviewable, accepted or rejected state (a state in which we would expect a document to be associated with the hit) the buildings front end will display the newest document in the list of building dimensions, thereby assuming that the newest document is the one referenced by the hit status. In the future the buildings front end will be refactored to include a documents container that retrieves all of the documents on its own. When that refactor is complete the building dimensions documents returned by +the _GET_ endpoint will no longer be used. + +The turkhit _POST_ endpoint is used to create a new hit. The body of the endpoint is created using a default form located in /src/components/TurkHit/defaultForm.js. The _POST_ endpoint returns the new hit status which is displayed on the front end. + +The turkhit _PUT_ endpoint is used to approve or reject a completed hit. The endpoint is passed "accept: 1" or "accept: 0" in the body to approve or reject respectively. In the future the endpoint will also be passed an explanation field that will be required when a hit is rejected. + +--- +## Document Service +The document service has a single endpoint, document. + +### document endpoint + +The `Documents` container has two main actions `loadDocuments` and `uploadDocument`. +The `Building` container imports these actions and passes them down to the child +components. Currently `BuildingOverview` component is the only child component that +uses these actions. `BuildingOverview` passes the actions down to the `DocumentCardViewer` +which will render the upload button and the `DocumentCards`. + +When the `DocumentCardViewer` is mounted it will call `getDocuments` which is a +prop mapped to `loadDocuments` action. After the action `loadDocuments` is dispatched, +a request will be made to the document service _INDEX_ route and the data returned +will be stored in the redux state. + +The action `uploadDocument` will be dispatched when the user selects the upload button. +This action will make a request to the document service _POST_ route. + +--- +## Utility Service + +Utility service has two endpoints that are used in BP buildings. + +### bills endpoint + +All bills endpoints are used in the Utilities component. All bills endpoints are used on the utilities section of the building detail page: /buildings/:building\_id/utilities. + + +The bills _GET_ endpoint is used to retrieve a list of box utility documents associated with the inputted building\_id. It is combined with the account _GET_ endpoint to associate a file stored in box with account data stored in the database. This is done by comparing the tag on the box file with the utility account number stored in the database. If the tag and the account number match, the box file is associated with the account. This assumes that there is exactly one file per account number. The naming scheme for box files is currently $(utility\_company)--$(account\_number) so this should work fine. In the future the $(utility\_company) data stored in the box filename could be compared with the utility in the account information, thereby ensuring there is no problem with overlapping account\_numbers between differing utility companies. + +The bills _POST_ endpoint is used to scrape new utility bill information. It saves the scraped file into box using document service. If the file already exists the _POST_ endpoint overwrites the file using document service's _PUT_ endpoint. The bills _POST_ endpoint then returns the download URL of the box file. + + +### account endpoint + +All account endpoints are used in the Utilities component. All account endpoints are used on the utilities section of the building detail page: /buildings/:building\_id/utilities. + +The account _GET_ endpoint is used to retrieve a list of utility accounts stored in the database. See the description above in the bills _GET_ endpoint to understand the interaction between account and bills _GET_ on the buildings front end. + +The account _POST_ endpoint is used to store new utility account data in the database. The _POST_ body is determined by the form filled out by the user. The username, password and access\_code fields will only be displayed if national\_grid\_gas is selected. If national\_grid\_gas is selected, username and pasword are empty and access\_code is non-empty the account _POST_ endpoint will send an email to someone (defined in the utility service endpoint) instructing them to connect the +access\_code with the BlocPower natonal\_grid\_gas account. + +The account _DELETE_ endpoint is used to delete a utility account from the database. This endpoint will delete all utility accounts with the inputted account number. Thus if there are any duplicates on this detail page they will be deleted.