From d0e0d92d92de0d7ac336a01a3ca2ccee996765dc Mon Sep 17 00:00:00 2001 From: Conrad S Date: Mon, 13 Feb 2017 09:40:12 -0500 Subject: [PATCH 1/3] First steps on service integration --- docs/service_interactions.md | 91 ++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/service_interactions.md diff --git a/docs/service_interactions.md b/docs/service_interactions.md new file mode 100644 index 00000000..3802a35e --- /dev/null +++ b/docs/service_interactions.md @@ -0,0 +1,91 @@ +# 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) +- [Utility Service](#utility-service) + +## Building Service +Building service has two endpoints that are used in BP buildings. + +### building endpoint + +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 + +The bils _POST_ endpoint calls the document service _POST_ endpoint in order save the newly scraped utility bill information into box. If the file already exists the bills endpoint uses the document service _PUT_ endpoint to overwrite the file. + +The bills _GET_ endpoint calls the document service _GET_ endpoint in order to get a list of box utility documents associated with the inputted building\_id. This endpoint is basically a wrapper around the document service _GET_ endpoint and should not be used if the service calling this endpoint already has access to the document service. + +--- +## Document Service +Document service is used in the bills _POST_ and _GET_ endpoints. + +The bils _POST_ endpoint calls the document service _POST_ endpoint in order save the newly scraped utility bill information into box. If the file already exists the bills endpoint uses the document service _PUT_ endpoint to overwrite the file. + +The bills _GET_ endpoint calls the document service _GET_ endpoint in order to get a list of box utility documents associated with the inputted building\_id. This endpoint is basically a wrapper around the document service _GET_ endpoint and should not be used if the service calling this endpoint already has access to the document service. + + +--- +## Utility Service +Document service is used in the bills _POST_ and _GET_ endpoints. + +The bils _POST_ endpoint calls the document service _POST_ endpoint in order save the newly scraped utility bill information into box. If the file already exists the bills endpoint uses the document service _PUT_ endpoint to overwrite the file. + +The bills _GET_ endpoint calls the document service _GET_ endpoint in order to get a list of box utility documents associated with the inputted building\_id. This endpoint is basically a wrapper around the document service _GET_ endpoint and should not be used if the service calling this endpoint already has access to the document service. + + +--- +## Stored Procedures +The account endpoint uses stored procedures to access and modify the database. + +The credentials used to connect to the database are located in the config folder. + +The account endpoint uses 3 stored\_procs from the public schema of the utility\_bill database. The stored procs and their parameters are as follows: + +**create**\_ **account** - Stores the account data in the database. Used in the account _POST_ endpoint. + +``` +in_building_id: integer +in_account_number: integer +in_type: string +in_login: string +in_pass: string +in_access_code: integer +``` +
+ +**get**\_ **accounts** - Gets the account data from the database. Used in the account _GET_ endpoint. + +``` +in_building_id: integer +``` +
+ +**delete**\_ **account** - Delete account data from the database. Used in the account _DELETE_ endpoint. + +``` +in_building_id: integer +in_account_number: integer +``` +
+ + + + + +--- +## Utility Bill Scraper + +The bills endpoint uses the Utility Bill Scraper app as a git submodule. + +When first cloning this app into your folder use the --recursive flag. If you forget to use the recursive flag you should run the following commands: +``` +git submodule init +git submodule update +``` -- GitLab From a51011045643767cba36808af794d1ef1b38ddd2 Mon Sep 17 00:00:00 2001 From: Conrad S Date: Mon, 13 Feb 2017 10:57:22 -0500 Subject: [PATCH 2/3] Documentation for all services --- docs/service_interactions.md | 76 ++++++++++++------------------------ 1 file changed, 26 insertions(+), 50 deletions(-) diff --git a/docs/service_interactions.md b/docs/service_interactions.md index 3802a35e..c6fbe4fa 100644 --- a/docs/service_interactions.md +++ b/docs/service_interactions.md @@ -5,87 +5,63 @@ Documentation of how BP buildings interacts with other services * [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 -The bils _POST_ endpoint calls the document service _POST_ endpoint in order save the newly scraped utility bill information into box. If the file already exists the bills endpoint uses the document service _PUT_ endpoint to overwrite the file. - -The bills _GET_ endpoint calls the document service _GET_ endpoint in order to get a list of box utility documents associated with the inputted building\_id. This endpoint is basically a wrapper around the document service _GET_ endpoint and should not be used if the service calling this endpoint already has access to the document service. +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. ---- -## Document Service -Document service is used in the bills _POST_ and _GET_ endpoints. +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 bils _POST_ endpoint calls the document service _POST_ endpoint in order save the newly scraped utility bill information into box. If the file already exists the bills endpoint uses the document service _PUT_ endpoint to overwrite the file. - -The bills _GET_ endpoint calls the document service _GET_ endpoint in order to get a list of box utility documents associated with the inputted building\_id. This endpoint is basically a wrapper around the document service _GET_ endpoint and should not be used if the service calling this endpoint already has access to the document service. +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. --- -## Utility Service -Document service is used in the bills _POST_ and _GET_ endpoints. - -The bils _POST_ endpoint calls the document service _POST_ endpoint in order save the newly scraped utility bill information into box. If the file already exists the bills endpoint uses the document service _PUT_ endpoint to overwrite the file. +## Document Service +The document service has a single endpoint, document. -The bills _GET_ endpoint calls the document service _GET_ endpoint in order to get a list of box utility documents associated with the inputted building\_id. This endpoint is basically a wrapper around the document service _GET_ endpoint and should not be used if the service calling this endpoint already has access to the document service. +### document endpoint +The document endpoint will be used in a future update implementing a documents container. --- -## Stored Procedures -The account endpoint uses stored procedures to access and modify the database. - -The credentials used to connect to the database are located in the config folder. - -The account endpoint uses 3 stored\_procs from the public schema of the utility\_bill database. The stored procs and their parameters are as follows: - -**create**\_ **account** - Stores the account data in the database. Used in the account _POST_ endpoint. +## Utility Service -``` -in_building_id: integer -in_account_number: integer -in_type: string -in_login: string -in_pass: string -in_access_code: integer -``` -
+Utility service has two endpoints that are used in BP buildings. -**get**\_ **accounts** - Gets the account data from the database. Used in the account _GET_ endpoint. +### bills endpoint -``` -in_building_id: integer -``` -
+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. -**delete**\_ **account** - Delete account data from the database. Used in the account _DELETE_ endpoint. -``` -in_building_id: integer -in_account_number: integer -``` -
+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. ---- -## Utility Bill Scraper +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 bills endpoint uses the Utility Bill Scraper app as a git submodule. +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. -When first cloning this app into your folder use the --recursive flag. If you forget to use the recursive flag you should run the following commands: -``` -git submodule init -git submodule update -``` +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. -- GitLab From d97a59ad102f6ca553942be78b23da49a8860fc2 Mon Sep 17 00:00:00 2001 From: Alessandro DiMarco Date: Mon, 13 Feb 2017 14:37:44 -0500 Subject: [PATCH 3/3] Add document service documentation --- docs/service_interactions.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/service_interactions.md b/docs/service_interactions.md index c6fbe4fa..85147e60 100644 --- a/docs/service_interactions.md +++ b/docs/service_interactions.md @@ -38,7 +38,19 @@ The document service has a single endpoint, document. ### document endpoint -The document endpoint will be used in a future update implementing a documents container. +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 -- GitLab