Managing Write-Back Server
Summary
Most management operations are done on Write-Back Manager such as license management or configurations, and they are described on Setup & Manage with Write-Back Manager, however, there are some technical aspects that are important and this page describes them.
Audit
All the actions performed by users in Write-Back (add data, delete or edit) are stored in the historical_audit table. This can help you identify which user did a specific insert and at what time in which dataset, for example.
Historical Audit
The historical_audit table is automatically populated by Write-Back to keep track of all the actions taken by users. Each entry has the following fields:
| Field | Example | Description |
|---|---|---|
| ID | 1234a678-9b01-23c4-5d6e-7f89a0123b45 | ID - primary key. (UUID) |
| ACTIONDATE_LOCAL | 2019-01-21 14:24:47 | Date and time of the user's action. The date is stored in the server time zone. |
| ACTIONDATE_UTC | 2019-01-21 12:24:47 | Date and time of the user's action. The date is stored in UTC. |
| ACTIONNAME | ALTER_DATASET | The type of user's action. Please find below a list with the actions available. |
| ACTIONPARAMS | renameColumn;dropColumn;modifyColumn;addColumn | Details of a user's action. |
DATASET | forecasts_modifications | Name of the data set. |
| DATASETKEY | 1234a678-9b01-23c4-5d6e-7f89a0123b45 | Record's key in the dataset. (UUID) |
| SYSTEM | Server | The system where the user performs actions. Possible values include 'Server' or 'Desktop'. |
| USERNAME | username | The user that performed the action. |
| IDWIDGETCONFIGURATION | 1234a678-9b01-23c4-5d6e-7f89a0123b45 | The ID of the Widget Configuration. |
| WRITEBACK_SITE | default | The site used during the configuration or append of data. |
The historical is kept both in the metadata database and the persistence database - in the persistence database you only get the audit for data changes and not the changes to the dataset on a metadata level.
The action names considered are the following:
| Name | Action Detail |
|---|---|
| DELETE_DATA | The user either on Desktop or Server deletes a data entry |
| INSERT_DATA | The user either on Desktop or Server submits a data entry |
| EDIT_DATA | The user either on Desktop or Server edits an existing data entry |
For the EDIT_DATA actions, there are a few additional combinations to notice:
| ActionParams | Action Detail |
|---|---|
| editDataDelete | The user deleted a cell (when using pivots) or a complete line (when not using pivots) - only shows up when using tabular mode. |
| editDataInsert | The user inserted a new cell/line - only shows up when using tabular mode. |
| 1234a678-9b01-23c4-5d6e-7f89a0123b45 | The user edited an entry, the actionParam refers to the line that was disabled and the new line will be in the datasetKey column. |
Dataset Tables
When a dataset is created a table is also created in the database to store its values. Take the "Sales Forecast" dataset for example, when creating it will create a new table named "sales_forecast" with the defined fields on the configuration.
The creation of a dataset will also add a new line to the historical audit saying that a dataset was created, it will also add a line do the widget configuration and finally, all the defined fields will be added to the widget fields configuration.
Dataset tables will have columns mimicking the configuration defined on Write-Back plus some additional columns that are added by default:
| Field | Example | Description |
|---|---|---|
| SURROGATE_KEY | 1234a678-9b01-23c4-5d6e-7f89a0123b45 | ID - primary key. (UUID) |
| ISACTIVE | True / False | Indicates if the record is active on the latest snapshot. Write-Back never deletes or updates records instead it deactivates the existing version with this flag and inserts a new record. Typically you want to filter this column by True when using on a Tableau data source. |
| TIMESTAMP LOCAL | 2019-01-21 12:24:47 | Date and time of the user's action. The date is stored in the server time zone. |
| TIMESTAMP UTC | 2019-01-21 12:24:47 | Date and time of the user's action. The date is stored in UTC. |
Log Files
Write-Back
The log files for Write-Back can be found in:
- <installation_path>/apache-tomcat/logs
If you ever need to open a ticket regarding any type of error, please zip the log folder and attach it to the ticket.
Write-Back Manager
If you get errors while configuring Write-Back inside the Write-Back Manager, these errors are also written to the logs. The logs can be found in:
- <installation_path>/manager/apache-tomcat/logs
In the eventuality of opening a support ticket regarding any error within the Write-Back Manager, please zip the logs folder and attach it to the ticket.
Error Handling
Existing errors considered
To handle errors in the back-end some error codes have been created for some standard operations with the endpoints. They can be found in the following table. They are sent in the HTTP Response body. Please always recur to logs to find more detail about what happened.
The logs are found in the log folder of tomcat, and also in the logger file in the tomcat directory. The spring related logs (also important) are found in the temp folder, in the tomcat directory. When an error code is returned and there is no representation for it the error message will clarify it is an undefined error.
| HTTP Error Code | HTTP Error Code Description | Back-end Error | Message | Description |
|---|---|---|---|---|
500 | ERR_GENERAL_EXCEPTION | Generic error. Contact support. | When a general error happens. This is used if the category of error does not fit any of the other categories. Check logs for more info and contact support if needed. | |
| ERR_CONNECT_OUT | Database appears to be down. Contact administrator. | This error happens if the backend could not establish a connection to a database. Check if the database is available. | ||
| ERR_CREATE_DATASET | Not possible to create a configuration with the provided input. | When creating the database table fails, for some reason that is not expected. Check logs for help. CREATE TABLE | ||
| ERR_DELETE_DATASET | There was an unexpected error while deleting the dataset. | When deleting the database table fails. DROP TABLE | ||
| ERR_ALTER_DATASET | Not possible to alter configuration with the provided input. | When altering the database table fails, for some reason that is not expected. Check logs for more detail. SQL actions => ALTER TABLE | MODIFY COLUMN | RENAME TO ... CHANGE COLUMN | ||
ERR_DATASET_ALREADY_EXISTS_EXCEPTION | The configuration you attempted to create already exists. | When attempting to create a database table that it already exists or alter the name of an existing table to one that already exists. This usually should not happen as there is a condition on front end that blocks it. | ||
ERR_DUPLICATE_ENTRY_EXCEPTION | The configuration has duplicated pill names. | When inserting more multiple foreign keys with the same name. (PersistenceEntryExcenption) | ||
| ERR_DUPLICATE_COLUMN_EXCEPTION | The configuration has fields with the same name. | When attempting to submit a configuration or edit one and adding two field names identical. This usually should not happen as there is a condition on front end that blocks it. | ||
ERR_UNKOWN_DATASET_EXCEPTION | Couldn't delete the configuration because it was not found. | When trying to delete a database that does not exist. | ||
ERR_BUILDING_QUERY | We couldn't find the query on the queries file. Contact support. | Errors related to the statement creation for the dataset. This usually happens when the query couldn't be found in the query file twbe.properties. If this error is found while creating widget or altering widget it might mean that a manual rollback might be necessary, so check logs for the fatal warning. | ||
ERR_INSERT_AUDIT | The action was not audited. Manual rollback might be required. Contact administrator. | Errors when inserting on the audit. (should trigger manual rollback on dataset when DDL rollback is not supported) | ||
ERR_CREATE_WIDGET | Configuration was not created due to an unexpected error. Contact administrator. | Errors when creating widget. This error can be quite damaging since it means only the configuration was not created. Which might mean that the dataset was. Check the logs for a fatal error. You might need a manual rollback. (should trigger manual rollback on dataset when DDL rollback is not supported). Make sure to check logs. | ||
ERR_DELETE_WIDGET | An unexpected error occurred and the widget configuration was not deleted. | Errors when deleting widget. | ||
ERR_ALTER_WIDGET | The configuration was not altered due to an unexpected error. Contact administrator. | Errors when altering widget. (should trigger manual rollback on dataset when DDL rollback is not supported). Make sure to check logs. | ||
ERR_INSERT_DATA | There was an unexpected error while inserting data. Contact support. | Errors when inserting data in the dataset. Usually, because the query is not built properly with the input fields. It's not expected to happen. | ||
ERR_EDIT_DATA | There was an unexpected error while editing data. Contact support. | Errors related to the edit data operation. Usually, because the query is not built properly, an SQL error. It's not expected to happen. | ||
| ERR_DELETE_DATA | There was an unexpected error while deleting data. Contact support. | Errors related to the delete data operation. Usually, because the query is not built properly, an SQL error. It's not expected to happen. | ||
| 404 | NOT FOUND | ERR_WIDGET_NOT_FOUND | Configuration not found in the records. Maybe it was deleted manually. | This error happens when the backend returns a 404 for the getWidgetConfiguration, because it was not found in the database. |
| 200 | OK | SUCCESS | When everything goes as expected. |
Manual Rollbacks
If the server fails to write the configuration or audit, the widget configuration needs to be manually deleted as well as the audit record to maintain consistency or rollback the creation of the table.
These actions are only to be performed in the event of something unexpected fails.
| Operation | Scenario | Rollback instructions |
|---|---|---|
| CreateWidget | The configuration creates a table but isn't able to insert data or edit the dataset | Look in the log file or in the audit table to find the name of the table. Beware that it is necessary to remove the table from the widget_config and historical_audit as well as the fields from widget_field_config and widget_field_values. To delete from these last two simply use the WIDGETCONFIGURATION_ID and WIDGETFIELDCONFIGURATION_ID (if there are predefined values), you can find this ID in the widget_config table. Run query "Drop table X" where X is the name of the dataset that was associated with the exception. |
| DeleteWidget | The action to delete the dataset fails | Manually drop the table, similar to the previous instructions. |
| AlterWidget | Performing an edit on the dataset throws an error | If a rename of the fields needs to be performed simply go to the desired table and manually rename the columns and then in the widget_field_config also rename the fields. If a change of type is needed the column must be dropped and added with the new type and then in the widget_field_config the type should also be changed to the new one (TEXT if varchar, NUMERIC if double and PREDEFINED if varchar). Although, in the case of PREDEFINED it is also necessary to add the predefined values to the widget_field_values and have the WIDGETFIELDCONFIGURATION_ID be the foreign key to the predefined field in the widget_field_config. |
Back-end Procedures
If you need to create any external procedure to manippulate or automate data submisssion please check the Back-end Procedures on Write-Back Server page.
Upgrading Write-Back
For more information on upgrading Write-Back check Upgrading Write-Back Server.