UALA-Internal-Tools

Introduction

uala-internal-tools is the app dedicated to collect the parts of the SaaS used to optimise the company's teams day to day work. It works as a middleware between external tools (ex. CRMs) used within the company and the uala-main application operating on its DB or calling its functions.

The exposed EPs belongs to the following routes:

• internal-tools/salesforce/v1 to interact directly with Salesforce
• internal-tools/v1/ to interact in generale with internal tools applications (example: business-operations)
• internal-tools/pdvt/v1/ to interact with Partner Data Visualization Tool, an old application that is now now renamed and repurposed as business-operations

!!! Possible Improvement The route internal-tools/pdvt/v1/ could be merged into internal-tools/v1/ since there is no real logical difference. !!!

!!! Business Operation business-operations is the monolith application developed by the BOS Team

The authentication with business-operations follows the Server 2 Server authentication standard (the JWT token is generated by business-operations using it's own private key and uala-internal-tools already has it's public key). !!!

!!! Salesforce Salesforce is the CRM currently used by the customer support team. To be able perform some operations (example create and update a Venue) it needs to interact with TWPro using the EPs defined in uala-internal-tools.

Salesforce to be authenticated with the uala-internal-tools EPs uses a JWT Token generated by internal-tools/salesforce/v1/authorize since Salesforce doesn't support JWT Tokens. !!!

Main Endpoints

Salesforce Venue Creation

The EP internal-tools/salesforce/v1/venues creates Venue, Billing Company and the Venue owner with the following logic:

Venue and Billing Company are mandatory entities, so they are created inside a transaction if it fails he entire process stop, while the User is optional and it can be easily created after. And initially the Venue is created with the Marketplace disabled because it requires a Billing Company and setting that value is also considered optional (The customer support would do that manually when the Venue and the Billing Company are created)

The entire service is tracked in Trackable Jobs to easily detect Errors in the code or in the data.

Parameters acceptance

The Venue Creation EP as the Venue Update EP use use Dry::Schema.Params to ensure that Salesforce sends the JSON body with:

• The expected structure
• All the required fields
• all the fields (required and optional) are in the expected format

Salesforce send empty strings instead of Nil fields (because it's easier to implement on the Salesforce side). So empty strings should converted to nil parameters, for that reason the optional fields are defined using .maybe (Ex: optional(:vat_number).maybe(:string)) and then they will be both ignored while creating Venue, Billing Company and User so that the default values would be used.

Migration Endpoints

At the moment the Migration EPs are implemented only to retrieve a list of Venue's Entities (Example Customers) or Venue data to let business-operations migrate them from TWPro to other SaaSes. In the future it could be possible that other micro-services will access those EPs to consume or visualize those data.

All the migration EPs should have a similar structure and similar functionalities to respect the standard used by the business-operations migration engine:

• fields param to define the which subset of parameters could be sent throw the JSON, because based on the migration's destination SaaS the EP could need more or less fields and it can be inefficient to provide all the fields since the value can be slow to be computed or just to save bandwidth.

• <entity>_ids param to filter a specific set of entities, to retrieve only the records that failed to be migrated, so that customer support can check them.

• If the number of the Venue's Entity records could be hundreds or thousands the EP should be paginated using page and per_page fields and adding in the data JSON field:

  "page": {
    "pageNumber": 1,
    "pageSize": 2,
    "totalPages": 2,
    "totalElements": 3,
    "orderBy": "createdAt"
  }