New tenant onboarding
Which role does what here
This screen has no capability in the role map. The application opens it only for the role: Platform operator (tenant onboarding).
What the screen is for
With this screen the platform operator creates a new olive mill tenant from an Excel file. The file is the onboarding template: you download it from the screen, fill it in and upload it. The server checks the file and shows you a preview of what will be created, together with every error and warning. Nothing is created until you confirm the preview.
On confirmation, everything is created together: the company, the sites, the production lines, the tanks, the quality and certification classes, the measurement and byproduct types, the varieties, the prices, the producers with their agreements, and the users. Each user gets an invitation email for their first sign-in. Nobody sets a password for someone else's account.
Note: The template only creates a new tenant. It does not update a tenant that already exists. Changes after onboarding are made on the tenant's ordinary screens.
Who sees it
Only the Platform operator (tenant onboarding) role. It is the only screen they see; they see no olive mill's data. Without the right, they see "You are not allowed to provision tenants… Nothing was done."
Tour
The title is Tenant onboarding. The screen has four numbered steps.
1. Template
The Download the current template (.xlsx) button downloads the file tropeion-onboarding-template.xlsx. Fill in the current template only. A file made from an older template is refused as a whole.
The template has one sheet per section. Row 1 of each sheet is hidden; row 2 holds the Greek column titles; data starts on row 3. The sheets are:
- Company: the company, exactly one row: Code, Name, Time zone (default), Current season.
- Sites: the sites (olive mills): Code, Name, Time zone.
- Users: the users: Email, Full name, Role, Scope (site/tenant), Site code.
- Lines: the production lines per site.
- Tanks: the tanks per site, with Capacity (kg).
- QualityClasses: the quality classes, with Quality rank.
- CertificationClasses: the certification classes, with Certification rank and Compatibility group.
- Varieties: the olive varieties.
- LabTypes: the lab measurement types, with Unit and Required.
- MeasurementTypes: the production measurement types per site, with Warn below and Warn above.
- ByproductTypes: the byproduct types per site.
- Prices: the oil prices: Site code, Quality code, Certification code, Effective date, Price per kg.
- Producers: the producers: Tax id (ΑΦΜ), Name, Mobile, Email.
- Agreements: the agreements: Producer tax id, Site code, Valid from, Valid to, Fee type, Fee rate, Monetary fee, Settlement grouping.
The column titles in the file are in Greek; the names above are their English meaning. Do not rename, delete or add sheets, and do not change the order or names of the columns.
Values you type in some columns:
- Scope (site/tenant):
sitefor a user of one site (then fill in the Site code) ortenantfor the whole company (then leave the Site code empty). - Role: one of the codes
intake_operator("Intake operator"),production_operator("Production operator"),quality_officer("Quality officer"),warehouse_tank_operator("Warehouse and tank operator"),cashier_settlement_officer("Cashier and settlement officer"),site_manager("Site manager"),central_manager("Central manager"),accountant_back_office("Accountant and back office"),auditor_read_only("Auditor (read-only)"),queue_display("Queue display (view only)"). To give one user two roles, write two rows with the same email. - Required:
1for yes and0for no.yes/no,true/falseand the Greekναι/οχιare also accepted. Typeοχιwithout the accent: with the accent the file gives the error "Enter yes or no." - Fee type:
percentage(a share of the oil) ormonetary_converted_to_oil(a money fee converted into oil). - Settlement grouping:
per_batch(one settlement per batch) orconsolidated(several batches together).
Every user row needs an email, because the invitation goes there. Producers and agreements follow the same rules as manual entry.
2. Upload and check
- Filled template (.xlsx): choose the file. Excel .xlsx only, up to 10 MB. Macros and formulas are refused.
- Upload and check the file: uploads the file. You see "Uploading: N%" and then "Checking the file on the server…".
Errors and warnings in the file
If the file has problems, the list Errors and warnings in the file appears, with the summary "N errors (they block the confirmation), N warnings (they do not block)." You can filter with Show (Errors and warnings, Errors only, Warnings only) and with Sheet. Each row shows the type, Sheet, row, column and message, with a short code next to the message. The row is the Excel row number, so you find the cell at once.
- Error: must be fixed in the file. While there is even one error, the file is not stored and cannot be confirmed.
- Warning: does not block. Check it before you confirm. Warnings come for example from a tax id with a wrong check digit ("This is a warning only; confirm the AFM with the producer.") or from two producers with the same name.
3. Preview
It appears when the file has no errors. The Rows per section table shows how many rows each section will create (Company, Sites, Users, Production lines, Tanks, Producers, Agreements and so on). Below it:
- "The file is valid with no errors or warnings." or "The file is valid with N warnings…"
- The Create tenant …: N sites, N users, N producers… button.
- The Discard this batch (nothing is created) button.
Both buttons work only for the operator who uploaded the file. A checked batch that is not confirmed is discarded automatically after 72 hours.
4. Result
After confirmation: "The tenant was created.", the Tenant id, the Batch status and the User invitations table with User, Status (Pending, Sent, or "Failed: … (N attempts)") and Last change.
The batch statuses are:
- "checked, waiting for confirmation";
- "tenant created, invitations being sent";
- "tenant created, some invitations failed";
- "completed";
- "discarded".
Buttons:
- Refresh the batch and invitation statuses: reads the statuses again. Sending happens in the background, so press it after a while.
- Close the batch: stop the N pending invitations: appears only when some invitations failed. Stops the invitations still waiting.
- Onboard another tenant: clears the screen for a new file.
Buttons and actions, step by step
Create the tenant
- In the preview, check the Rows per section table and every warning.
- Press Create tenant ….
- The Create this tenant? window opens. Read which tenant is created, with how many sites, users and producers, and that it cannot be undone from this screen.
- Press Create the tenant and send N invitations. To go back without creating anything, press Back to the preview (nothing created).
- You will be asked to sign in again. After signing in you return to the same batch and the request is sent once.
- Step 4. Result appears.
Discard the batch
- In the preview, press Discard this batch (nothing is created).
- The screen says the batch was discarded and nothing was created. You can upload the same or a corrected file again.
Messages and what to do
- "The file has N errors and N warnings. Nothing was stored…": Fix the errors in Excel, following the list, and upload it again.
- "This file was made from an older template…": Press Download the current template (.xlsx), copy the data into the new file and upload it.
- "This file has already been uploaded…": Exactly the same file already has a checked batch or already created a tenant. The same file never creates a second tenant.
- "The file is larger than 10 MB…": Remove unused sheets or rows and upload it again.
- "The company code in the file is already in use… Nothing was created.": Change the Code on the Company sheet and upload the file again.
- "This batch can no longer take this action: it expired (72 hours), was discarded or was already handled…": The screen shows the current state. If it expired, upload the file again.
- "No connection. Nothing was lost…" or "The service is unavailable. The outcome is unknown; retrying is safe.": Press the retry button, for example Retry: create the tenant (same request) or Retry the upload (same request). Retrying never creates a second tenant.
- "The confirmation needs a fresh sign-in…": Sign in again. If the sign-in page does not open, sign in and retry.
- "The batch was not found…": It may belong to another operator or no longer exist.
- An invitation "Failed": Press Refresh the batch and invitation statuses after a while. If you want no more attempts, press Close the batch: ….
Common mistakes
- An old template. Always download a new template before each onboarding.
- Formulas in Excel. A cell with a formula and no stored value is an error. Save the file in Excel or type the value.
- A user without an email. Every user needs an email, otherwise they cannot be invited.
- Scope and site code. With
tenantthe Site code stays empty; withsiteit is required. - Overlapping agreements. Two agreements of the same producer at the same site cannot be valid in the same period.