tellma-ltd/tellma

The next generation ERP system for Enterprises

Tellma

For the time being, this document will contain instructions for developers on Windows.

First Time Setup

Follow the steps below to set up the solution for the first time.

Environment

• Install Visual Studio 2019 (or later) Community Edition with the "ASP.NET and web development" workload
• Install Visual Studio Code from the official website with the Angular Language Service extension
• Install SQL Server 2017 (or later) Developer Edition and make sure it is accessible on "." with Windows authentication
• Install NodeJS (LTS edition) from the official website
• Install Angular CLI globally by running the following in cmd: npm install -g @angular/cli
• Install typescript globally by running the following in cmd: npm install -g typescript

IDEs

• Use Visual Studio to open Tellma.sln
• Use Visual Studio Code to open the Angular project in (SolutionDir)/Tellma.Api.Web/ClientApp/

Database Tier

• Right-Click -> Publish the project Tellma.Database.Admin to a database [Tellma] on SQL server "."

• Right-Click -> Publish the project Tellma.Database.Application to a separate database [Tellma.101] on the same server "." setting the SQLCMD variables as follows:

  SQLCMD Variable	Value
  DeployEmail	[email protected]
  OverwriteDb	1
  FunctionalCurrency	USD
  PrimaryLanguageId	en
  SecondaryLanguageId	NULL
  TernaryLanguageId	NULL
  ShortCompanyName	Contoso Ltd.
  ShortCompanyName2	NULL
  ShortCompanyName3	NULL

• In the Admin database, run the following script:

BEGIN TRANSACTION;

DECLARE @Email NVARCHAR(255) = N'[email protected]'

EXEC [dal].[AdminUsers__CreateAdmin] @Email = @Email, @FullName = N'Administrator'

-- Add [Tellma.101] DB to the sharding catalogue
DECLARE @ServerId INT = (SELECT [Id] FROM [dbo].[SqlServers] WHERE [ServerName] = N'<AdminServer>')
DECLARE @AdminId INT = (SELECT [Id] FROM [dbo].[AdminUsers] WHERE [Email] = @Email)
INSERT INTO [dbo].[SqlDatabases] ([Id], [DatabaseName], [ServerId], [CreatedById], [ModifiedById])
VALUES (101, N'Tellma.101', @ServerId, @AdminId, @AdminId)

-- Add membership for the admin user in [Tellma.101]
DECLARE @DirectoryAdminId INT = (SELECT [Id] FROM [dbo].[DirectoryUsers] WHERE [Email] = @Email)
INSERT INTO [dbo].[DirectoryUserMemberships] ([UserId], [DatabaseId])
VALUES (@DirectoryAdminId, 101)

COMMIT;

Application Tier

• Make sure the project Tellma.Api.Web is your startup project (Right-Click -> Set as Startup Project)

Client Tier

• Install all ClientApp npm dependencies as follows: Go inside "(SolutionDir)/Tellma.Api.Web/ClientApp/" in cmd and run: npm install

Running The App

Follow these steps to run the solution on your development machine:

• Make sure you pull the latest version of the solution from GitHub
• Make sure the latest version of the admin and app databases are published to [Tellma] and [Tellma.101]
• Make sure the latest ClientApp npm dependencies are installed: Go inside "(SolutionDir)/Tellma.Api.Web/ClientApp/" and run: npm install
• Start the backend server on https://localhost:5001/ as follows: Visual Studio -> Debug -> Start Without Debugging. This should launch a debug console similar to this:

• Start the client app server on http://localhost:4200/ as follows:
  • Open cmd
  • Navigate to "(SolutionDir)/Tellma.Api.Web/ClientApp/"
  • Run ng serve -o

• Sign in with username: [email protected] and default password: Admin@123

Optional Configuration

In your development environment you can use the user secrets of project Tellma.Api.Web to add additional functionality or override any of the default settings in appsettings.json and appsettings.Development.json.

To Enable Email

• Right-Click the project Tellma.Api.Web -> Manage User Secrets, this opens a file secrets.json containing a JSON object
• Add the following properties inside the JSON object:

  "EmailEnabled": true,
  "Email": {
    "SendGrid": {
      "ApiKey": "(YourSendGridApiKey)",
      "CallbacksEnabled": false
    }
  }

• Replace (YourSendGridApiKey) with a real SendGrid API key, you can grab one for free from SendGrid.

To Enable SMS

• Right-Click the project Tellma.Api.Web -> Manage User Secrets, this opens a file secrets.json containing a JSON object
• Add the following properties inside the JSON object:

  "SmsEnabled": true,
  "Twilio": {
    "AccountSid": "(YourTwilioAccountSid)",
    "AuthToken": "(YourTwilioAuthToken)",
    "Sms": {
      "ServiceSid": "(YourTwilioServiceSid)",
      "CallbacksEnabled": false
    }
  }

• Replace all placeholders (Your...) with real values, you can grab those values from Twilio

To Use Custom Port Numbers

If you want to run the client app server on a port number other than 4200, follow these steps:

• Right-Click the project Tellma.Api.Web -> Manage User Secrets, this opens a file secrets.json containing a JSON object
• Add the following property inside the JSON object:

  "ClientApplications": {
    "WebClientUri": "http://localhost:(YourClientPortNumber)"
  }

• Replace (YourClientPortNumber) with your custom port number

If you want to run the backend server on a port number other than 5001, follow these steps:

• Launch the client app in the browser
• Using the browser's developer tools open the console and run localStorage.appsettings = "{\"apiAddress\":\"https://localhost:(YourBackendPortNumber)\"}" replacing (YourBackendPortNumber) with your custom port number
• Refresh the client app in the browser
• The preconfigured credentials for Google and Microsoft redirect only to http://localhost:5001, so either remove them or add your own credentials for your custom port number:
  • Right-Click the project Tellma.Api.Web -> Manage User Secrets, this opens a file secrets.json containing a JSON object
  • To remove the preconfigured credentials, add the following property inside the JSON object:

     "EmbeddedIdentityServer": {
       "Google": {
         "ClientId": "",
         "ClientSecret": ""
       },
       "Microsoft": {
         "ClientId": "",
         "ClientSecret": ""
       }
     }

  • Or you can grab your custom credentials from Google Developer Console and Microsoft Azure

tellma's Issues

Signing in sometimes fails the nonce check

When attempting to sign in, the following error is logged in the console: "Validating access_token failed, wrong state/nonce. null LV9ewx59....."

Export for import may not maintain fidelity of definition Ids

These are some of the entities that refer to the definition Id without a foreign key constraint.

1. Permissions -> View
2. LineDefinitionGenerateParameters -> ControlOptions
3. ReportDefinitions -> DefinitionId
4. ReportDefinitionParameters -> ControlOptions
5. ReportDefinitionRows -> ControlOptions
6. ReportDefinitionColumns -> ControlOptions
7. ReportDefinitionMeasures -> ControlOptions

When exporting those entities and importing them in a different tenant it can cause a successful yet erroneous import, where the data in the destination is semantically different from the data in the source.

Add AVCO recalculation button in the UI

Make AVCO recalculation stored procedure available as a button in the financial settings screen. Handle the case when the processing takes longer than the timeout.

Add validation for permission views, actions and filters

Right now there is no validation when saving Permissions, users are able to add anything especially when importing from Excel. Validation must be added on these columns:

1. View
2. Action
3. Filter

Support unary operators in Template expressions

1 - Template expressions (unlike query expressions) currently do not support unary operators like -2.
2 - Also bad input like Func(1, 2, +) returns a meaningless error message. Store the function arguments outside the operator stack to fix this.

Optimize entity queries with temporary tables

Use temporary tables to store principal queries that need to be subsequently joined with related queries. This should improve the performance of some screens, especially the document details screen.

Add user management screen to admin portal

The screen allows a central admin to create identity users and set their passwords when the Tellma installation has Email disabled (e.g. in an offline deployment). The screen should be disabled when Email is enabled.

Implement Markup Template based reports

Markup Template reports:
Pros

1. Are very flexible in their style and layout (HTML and CSS)
2. Can be exported to PDF
3. Can be sent as email attachments

Cons

1. Expensive to develop
2. No native support for drilldown
3. No export to CSV

"Body was Empty" intermittent error when saving documents

Sometimes when saving a document, a mysterious 400 Bad Request returns with the message "Body was Empty".

Support null entries

Some line definitions have too many entries that are sparsely used. Right now every time a line belonging to such definition must have all entries saved with 0 values. Which is a waste of database space.
We would like the ability to specify in the save logic which entries we wish to save and the code in the entire pipeline should be able to handle a missing entry slot.

Using the expression (true) in a details report column displays nothing

The column header shows "Yes", but nothing in the rows.

In tree entities, Delete should always be with descendants

Delete while keeping descendants is meaningless and currently buggy. Remove it and keep only delete with descendants.
This applies to the following entities:

• AccountTypes
• AccountClassifications
• EntryTypes
• Centers

Reports do not remember the last selected parameters

Leaving the custom report screen and returning to it clears away all the parameters.

Prevent users from overwriting each other's changes or signing on the wrong document

Before saving, compare the item's ModifiedAt with the one in the database and prevent the update if they are different.
Also prevent users from signing lines if the lines' ModifiedAt is different than the one on the client.

Increase timeout for DB operations to 15 mins

Some operations like auto-generate of expense capitalization is timing out. Increase the timeout period to 15 mins in order to handle larger data.

Ability to edit your own comments on documents

Right now any document comment a user adds is fixed in stone forever, they don't have a chance to fix typos for example. We need a way to edit a comment that was already added, but make it clear in the UI that the comment was edited after it was created.

Need a way to download attachments.

Right now you can view an attachment in the browser, but there is no straightforward way to download it on your computer, this is especially true for image attachments.

MSDTC error when trying to delete a used warehouse

When trying to delete a used Resource or Relation, an MSDTC error is thrown instead of a friendly error message.

[dal].[Reconciliation__Load_Reconciled] does not return entries that cancel each other out

In the bank reconciliation screen you can reconcile 2 entries that have equal but opposite values without including any external entries (example below). However when you switch to the Reconciled view, you are unable to find these 2 entries.

Keep checkbox selection when navigating across screens and data pages

In any master screen, if you multi-select some check boxes and navigate to the next page, or change the search criteria, or navigates into the details screen and back, you find that your selection has been cleared away, this is not the behavior one usually expects.

Utilize Signal-R to update the client side cache in real-time

The client app caches definitions, permissions and company/user settings, all information that affect the UI. The client only detects that there is a new version of these when it makes an API call to the server and the server returns cache-bust signal in the response headers.
It would be better if we can make use of the Signal-R infrastructure to send a cache-bust signal to all the clients instantly resulting in a real time update of the UI when definitions and permissions are modified.

Keyboard shortcuts for common tasks

Implement keyboard shortcuts for common tasks, such as edit, save and post. As well as navigating through search results, opening a search result and clearing search.

Implement API versioning

To be able to introduce breaking changes in the future, implement API versioning from now. Like this: https://web.tellma.com/api/v1/documents/1/2

Bank reconciliation report spanning all bank accounts

Right now the bank reconciliation report is restricted to a single bank account and there is no way to see the bigger picture. We would like to see the same report for all bank accounts in a single view.

Right-click context menu appears behind ngb-modal

The z-index should be fixed.

Implement a UI framework for SP based reports

Some reports like Aging receivables cannot be constructed using the regular API for the reporting studio and must be implemented as stored procedure.

Checkbox parameters in reports can look unchecked even when they are

If a report has a checkbox parameter, and you set it to true, leave the report and come back, it would look unchecked even though in reality it is.

Store emails in the blob storage rather than table

To save on cost, store the bodies of emails that Tellma dispatches in the Azure blob storage (when available) instead of the table itself.

Non-square images result in oval user thumbnails

All user thumbnails should be squares.

Example:

Saving a new currency with an existing description returns an SQL error

Should return a friendly error message instead.

Reconciliation screen: Create new row appears while data is loading

Select an account such that the right column has more entries than the left column.
When you refresh, two problems appear:

1. The create new entry row remains visible while the data is loading.
2. The 3-dot menu button appears out of place.

Remove invisible character from all UI screens

The invisible zwnj (zero-width non-joiner) character used to maintain height of empty fields is causing issues when users copy values from the UI and paste them somewhere that doesn't know how to handle that character.
Need to find an alternative way of maintaining empty field height without the zwnj character.

Make switching to another culture encoded in the URL

When switching to another culture in the UI, the browser back button should switch you back as the user would expect.

Add ValidFrom and ValidTo to versioned entities

Versioned entities like LineDefinition do not currently expose the ValidFrom and ValidTo properties in master screens and in the reporting studio. These properties need to be added.

Prevent an admin user from revoking his/her own admin privileges

Right now this is possible which may lead to situations where there is no administrator left. If a user has permission on Users or Roles, they cannot remove that permission from themselves. Another administrator has to do it for them.

Add an option to make document attachments optional

Currently there are two options for a document definition:

1. Attachments are visible and required
2. Attachments are hidden

We would like a third option to make attachments visible and optional.

Reports: Improve the distinction between row totals and row leaf values

Right now the totals and their leaf children look too much alike giving the user a hard time when consume the report.

Lookups are better sorted by code

By default lookups should be sorted by their codes. They are currently sorted by Id which cannot be influenced by the user. Sorting by code will not cause performance degradation since lookups tend to be few per lookup definition

Printing errors don't appear to the user doing the printing

Angular is expecting a blob to print, so when the endpoint returns a JSON error, it throws a technical error instead.

Add cancel to the confirm sign-out screen

Right now there is only one option: Confirm sign-out, it makes sense to add a cancel button which simply navigates the user back.

Clean up all legacy provisioning code in Tellma.Database.Application

Anything client-specific should not be in the framework source code.

Error while trying to run tellma locally

after forking to project and deploy all the DB project according to the instructions
we face this error
can you please help

thank in advancece

Improve the UX of Show In Main Menu of Reports and Dashboards

Users consistently enable "show in Main Menu" without adding any roles, and feel confused when they don't find it in the main menu. Options are:

1. Either prevent ShowInMainMenu = true when there are no roles.
2. Or remove ShowInMainMenu all together and rely only on the list of roles.

Exporting account statement from second page will return an SQL error

For example go here and click Export.

The following error comes back:

Note that exporting from the first page does not return this error.

Ability to navigate to document and line definitions from document

1. Need to be able to navigate to document definition from the document screen (Just like Resource, Relation and Lookup)
2. Need to be able to navigate to line definition by right clicking on the tab in the document screen.

The ability to disable or enable core screens and features

Some core screens and features like bank reconciliation should be possible to enable and disable to allow for more customization.

Implement licensing framework

Design and implement a flexible licensing framework on the installation level and on the tenant level.

Using a filter of X descof V where V doesn't exist returns everything

Using a filter lile Account.AccountType.Concept descof 'ConceptThatDoesntExist' returns everything. The more expected behavior is that it should return nothing.

Freeze definitions mode

Add a boolean flag FreezeDefinitions per company settings that can only be set from the admin console.
When set to true, all definition screens become inaccessible.

Report Definition details: preview is refreshing the report many times

We notice in Chrome debug tool that the report is querying the server many times whenever the definition is changed.