Use Analytics scenarios in Manager

Start from: The Mapal Manager home screen.

What Sales scenarios are

Sales scenarios are saved views created in the Analytics app. Each scenario stores:

Parameters (for example, date range, comparison scenario, analysis type).
Filters (for example, business units, brands, regions).

When you load a scenario in Mapal Manager, the Sales screen is configured exactly as it was when the scenario was saved in Analytics.

For instructions on creating scenarios, see Save and load scenarios in Analytics.

View and load a scenario in Mapal Manager

On the Sales screen, open the More Options button (...).
Select Scenarios.

From the list, select the scenario you want to use.

Mapal Manager loads the selected scenario and applies its parameters and filters to the Sales view. The Sales screen (metric cards and breakdown list) updates to match the configuration stored in the scenario, so you can analyse performance without manually setting dates, filters, or comparison scenarios.

Set a default scenario

You can set a default scenario so that your preferred view loads automatically when you open Sales.

Open the Scenarios list from the More Options button (...).
Locate the scenario you want to set as default.
Select the flag icon for that scenario.

That scenario becomes your default and will load by default when you enter the Sales module.

Note: The default scenario is shared between Analytics and Mapal Manager. If you change your default in one, it updates in both.

What happens when you load a scenario

When you load a scenario in Mapal Manager:

The Sales view immediately switches to the parameters and filters stored in that scenario (dates, comparison scenario, analysis type, selected units, etc.).
The configuration stays active while you stay in Sales, even if you close and reopen the app later.
Any manual changes you make afterwards (for example, changing the business unit or period) override the scenario until you load another one.
If your permissions change (for example, you lose access to a business unit or brand), the scenario still loads, but you will only see data for the units and filters you are currently allowed to access.

Change the sales comparison scenario

Start from: The home screen in Mapal Manager.

On the Sales screen, tap the More Options (...) button.

Select Parameters from the menu.

The Parameters panel opens. Under the Analysis section, select the Comparison Scenario dropdown. Select the scenario you want to use, for example:
- Like for like
- Actual vs previous year
- Actual vs budget
- Actual vs previous day/week/month
- Custom comparison period (if available)

Note: Some scenarios update automatically (for example, Actual vs previous year selects the same date last year). For scenarios such as Custom, choose the specific comparison date or period if additional fields appear. Confirm any required values.

When you have chosen your scenario and completed any extra fields, tap Accept. The Parameters panel closes.
On the Sales screen, the percentage change shown under each metric card (Net Sales, Checks, Average Check) updates to use the new scenario.
Any arrows or colours indicating performance direction also update.
The breakdown list under the cards (for example, by site, brand or region) refreshes with the new comparative values.

The selected comparison scenario stays active while you remain in the Sales view. Switching business unit does not reset the scenario.

Notes: Loading a saved scenario can override the comparison scenario you set manually. If there is not enough historical data for the chosen scenario, the comparison value may show as 0% or no data.

Workforce Sales API

The Sales API is a RESTful service for secure server-to-server integration.
It allows you to:

Retrieve data: Get net and gross sales filtered by unit and date range.
Submit data: Import detailed, hourly, and total sales.
Secure integration: All communication is encrypted via SSL/TLS and authenticated with JWT tokens.

Quick Start

Here’s the typical workflow in five steps:

1. Generate a JWT token

curl -X POST https://login.mapal-os.com/connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password&username=<your_username>&password=<your_password>&client_id=wf_wap_tp&client_secret=<shared_client_secret> "

2. Start an import session

curl -X POST https://api.workforce.mapal-os.com/sales/api/v1/import \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{ "unitId": 9, "businessDay": "2025-02-06" }'

3. Import sales data (example: total sales)

curl -X POST https://api.workforce.mapal-os.com/sales/api/v1/import/1/total-sales \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{ "TotalSales": [ { "CurrencyId": "EUR", "NetSales": 250, "GrossSales": 270, "NumChecks": 2, "NumGuests": 3, "SalesTypeId": "TAKE", "SalesType": "Takeaway" } ] }'

4. Finish the import session

curl -X POST https://api.workforce.mapal-os.com/sales/api/v1/import/1/finish \
-H "Authorization: Bearer <token> "

5. Retrieve sales data

curl -X GET "https://api.workforce.mapal-os.com/sales/api/v1/business-unit/9/net-sales?start=2025-02-06&end=2025-02-06" \
-H "Authorization: Bearer <token> "

Authentication

The API uses JWT (JSON Web Token) for authentication.

Request a token with your client credentials.
- URL: https://login.mapal-os.com/connect/token
- grant_type: password
- client_id: wf_wap_tp
- client_secret: provided by Mapal OS
Use the token in every request:
Authorization: Bearer {access_token}
Token expiry: Tokens expire (default: 3600 seconds). Refresh or regenerate when needed.

Import Workflow

Authenticate: generate JWT token.
Start import session: creates a session for a specific business day.
- Previous sales data for that day will be replaced.
- Sessions must be filled sequentially (no gaps in business days).
Submit sales data: send data to one or more endpoints:
- Detailed sales
- Total sales
- Half-hourly sales
- Product mix
- Inventory
- VAT sales
- …and more (see endpoint list).
Finish import session: finalise the import.
View imported data: inside Analytics > Sales in Mapal OS.

Endpoint Reference

All endpoints are under: https://api.workforce.mapal-os.com/sales

Sales Retrieval

Net sales: GET /api/v1/business-unit/{unitId}/net-sales?start=yyyy-MM-dd&end=yyyy-MM-dd
Gross sales: GET /api/v1/business-unit/{unitId}/gross-sales?start=yyyy-MM-dd&end=yyyy-MM-dd

Import Workflow

Start import session: POST /api/v1/import
Finish import session: POST /api/v1/import/{importId}/finish

Import Endpoints

POST /api/v1/import/{importId}/detailed-sales
POST /api/v1/import/{importId}/total-sales
POST /api/v1/import/{importId}/half-hourly-sales
POST /api/v1/import/{importId}/total-half-hourly-sales
POST /api/v1/import/{importId}/product-mix
POST /api/v1/import/{importId}/special-tickets
POST /api/v1/import/{importId}/payment-method-sales
POST /api/v1/import/{importId}/average-ticket-duration
POST /api/v1/import/{importId}/inventory
POST /api/v1/import/{importId}/vat-sales

Error Handling

400 Bad Request: check parameters or JSON body.
401 Unauthorized: refresh or regenerate token.
404 Not Found: invalid unitId or tenant config.
500 Internal Server Error: retry or contact support.

Filter and navigate through sales data

Start from: The Analytics module.

Select Sales from the main menu.

Select the Parameters button.

In Analysis, set:
- If you want to visualize Sales as Net Sales or Gross Sales.
- If you want to see Traffic by Tickets or Guests.
- The Comparison Scenario of the analytics, can be Comparable vs Previous Year, Actual vs Previous Year, Actual vs Budget, Budget vs Previous Year.
- The Reference Year, which can be any in the last five (5) years.
- If you want to see Averaged Amounts, whether daily, weekly, monthly or annual.

In Time Period, set:
- The Time period you want to see. You can see the last day, week, month, year or a specific date range that you select.
- If you want to exclude or include specific days of the week.
- If you want to include Holidays, Holiday Eves, Events and Exclude non-representative dates.
- If you want to filter by Weather or Temperatures.

In Sales Type and Periods, set:
- If you want to see Individual sales types or Groups of sales types. Then, select the specific type or group of types from the dropdown.
- If you want to see one or all Sales Periods.

In Others, you can set parameters such as data source, currencies, percentage variations in local currency or ignore days without sales. At this point, you will establish if the data will come from the POS or from the Cash Sheet.
Once the parameterization is completed, select Accept to save it OR Cancel to discard it.

Back on the Sales Analytics screen, select Filter by Center.

In this window, you will be able to select the specific center or centers for which you want to visualize the data.

Once the centers are selected, the Sales Analytics screen will show you a list of the selected centers with their respective data. On this screen you will be able to get an overview of actual sales, previous year sales (based on the comparable year), and the variation both in percentages and amounts.

This parameterization can be saved later as a Scenario, which will allow you to present it permanently on a Dashboard or make a comparison with another scenario.

Navigate through sales

Once you deploy the data, you will be able to navigate through the sales screen using different tools available in the panel.

To learn more, see Navigate using views and levels in Analytics.

Manage budgets from the Analytics sales tool

Start from: The Analytics module.

Select Sales from the main menu.

Configure the Sales screen to display the data you need OR choose an existing Scenario where you use a Budget as a Comparison Scenario.

To learn more about Sales configuration, see Filter and navigate through Sales data.

Select from the dropdown the Budget you want to view and manage.

Select Accept to see the configuration result on the Sales screen.

Select the Budget button.

A Sales Budget modal will open where you can manage four blocks:

Budget Scope

In this section, you will set the general budget data.

Select the budget to manage from the Budget* dropdown.
Select the Data Source for that budget. It can be POS or Cash Sheet.

Select the Center* for which you will configure that budget.

Set the From* and To* dates that will govern that budget.

Select the Sale Types included in that budget. Use the Individual or Group switch to set whether it will be a single group of sale types or several.

Select the Sale Periods established for the budget.

Notes: Fields marked with * are mandatory.

Reference Data

In this block, you will set whether the budget will use reference data from another center, date, or source.

In Reference Center, select whether you want to use the same center in a previous year or another specific center.

Select whether you want to use Historical Data or another Budget as Reference Source.

In Reference Date, you can set the specific time range you will use as reference for your budget. It can be the same day of the week in a previous week, same date in a previous year, or a comparable day in a previous year.

Depending on the parameter you use in Reference Date, you can select the Previous Year or Previous Week you will use as reference.

Select whether you will Use budgeted data as reference for future dates. If you do, then set the Budget for Future Dates.

Projection Method and Assumptions

In this section, you can set how you want to project the budget and whether you want to establish variations to the references you have set.

Select the Projection Method to use. It can be Sales, Tickets and Average Ticket, Customers and Average Ticket per Customer, or Trend.

In Sales Assumptions, set a Percentage variation, Specific variation or Particular value. You can set a single value for All days or a different one By days of the week.

Set a reference parameter for Tickets and Customers. It can be Same growth as in Sales, Same number of Tickets/Customers as in Reference Date, Same growth as Tickets/Customers and Average ticket per customer.

Distribution by Sale Types and Periods

In this block you can set specific budget distributions by periods and sale types.

Choose whether you want to make the distribution Based on Reference Data or not.

Choose whether you want to Show all Sale Types or not.

You can Load a base distribution by choosing a specific date from the reference data.

Set the distributions in percentage. In the table, rows correspond to sale types and columns to periods.

Keep in mind that the sum of all distributions must equal 100%. You can view this in the Total row.

Once you complete each of the blocks, select Accept to save changes OR Cancel to discard them.

Submit real-time sales via API

Start from: Your server-to-server integration (API client).

Real-time Sales API

The Real-time Sales API is a RESTful service for submitting live sales data securely.

Key Benefits:

Immediate updates to sales figures.
Secure server-to-server connection (HTTPS + JWT).
Supports flexible filtering by business unit and business day.

Generate a JWT token

POST to: https://login.mapal-os.com/connect/token

Parameters:

grant_type=password
username=
password=
client_id=wf_wap_tp
client_secret= (contact Customer Support to obtain)

Successful response includes: access_token, expires_in, token_type, refresh_token, scope.

Include the token in requests

Add header: Authorization: Bearer {access_token}

Submit real-time sales

Base domain: https://api.workforce.mapal-os.com/sales
Endpoint path: /api/v1/business-unit/{unitId}/real-time-sales
Method: GET (if your OpenAPI specification shows a different method, follow the specification)

Parameters / payload fields

unitId (route, integer)
businessDay (string, yyyy-MM-dd)
realTimeSales (array of objects):
- currencyId (string)
- salesTypeId (string)
- timeSlotStart (string, date-time)
- netSales (decimal)
- grossSales (decimal)
- numChecks (integer)
- numGuests (integer)

Check submitted sales

Navigate to Analytics > Sales in Mapal OS.

Notes:

All requests must use HTTPS.
Tokens expire (expires_in) and must be regenerated.
Tokens can be revoked if compromised.

Error handling

400 Bad Request: Invalid unit ID; business day mismatch; currency or sales type mismatch; invalid time slots.
401 Unauthorized: Invalid or missing token.
404 Not Found: Tenant or tenant configuration not found.
500 Internal Server Error.

Configure outlier dates to improve accuracy

Start from: The Analytics Dashboard.

Navigate to Configuration > Outlier Dates.

Select the Year and the Site for which you want to configure non-representative dates. These dates are set on the current year's calendar but are used to adjust the sales budget for the following year.

Example: If you mark dates in 2024 as outliers, they will not influence the sales budget calculations when 2024 is used as the historical reference for 2025.

Review system-suggested outliers

Days outlined in red are Potentially Non-Representative Days. These are flagged automatically based on the sensitivity setting and variations detected in the data source (POS or cash sheet).

Adjust the sensitivity using the slider control to detect fewer or more outliers.

Manually mark non-representative days

Click on any date to mark it as Non-Representative.
The selected day will appear in yellow.
Add a comment to justify the selection (e.g., “Bank holiday” or “Local event”).

Select Accept to confirm or Cancel to discard.

Generate a report

To get a global overview of all configured outlier dates for a specific site:

Select Report at the top of the grid.
A PDF summary will be generated listing all the dates marked as Non-Representative for the selected site and year. This report helps provide visibility and traceability for forecasting decisions across your organisation.

Create and manage sales and financial budgets

Start from: The Analytics module.

Navigate to Configuration > Budgets.

Select the Budgets ? button.

Interfaz de usuario gráfica, Aplicación, Tabla Descripción generada automáticamente con confianza media

Enter the name of the budget.
Select the + button to create it.

Interfaz de usuario gráfica, Aplicación Descripción generada automáticamente

Once created, find the new budget in the table and flip the switch in the row of each role to enable the roles that will have access to it.
Permission levels include:
- View – Users can access budget details but cannot make changes.
- Close – Users can lock budgets once finalized.

Captura de pantalla de computadora Descripción generada automáticamente

Edit and rename budgets

Select the Budgets ? button.
Locate the existing budget and select Edit.
Rename the budget and press Accept.

Delete budgets

Select the Budgets ? button.
Locate the existing budget and select Delete.
Select Delete again in the confirmation window.

Configure sales forecast

Start from: The Workforce module.

Select Scheduling > Scheduler 2.0 from the main menu.

Once in the scheduler screen, select the < button to open the favourite shifts catalog and sequences in the side panel.

Escala de tiempo Descripción generada automáticamente con confianza baja

The catalog is divided into two tabs: one for favourite shifts and the other for sequences. Both tabs work in the same way.
Select the appropriate tab.

Interfaz de usuario gráfica, Texto, Aplicación Descripción generada automáticamente

Enter the name of the shift or sequence in the Search field.
Indicate how many times the assignment of the selected shift or sequence is to be repeated.

Notes: This functionality is very useful when you must make the same assignment for an employee repeatedly on consecutive days.

Select the shift or sequence from the list (the selection is marked with a blue ball).

Interfaz de usuario gráfica, Aplicación, Teams Descripción generada automáticamente

Select in the grid the day and employee to whom you will assign the shift or sequence.

Tabla<br><br>Descripción generada automáticamente con confianza media

Notes: As long as the catalog panel remains open, the shift or sequence will be assigned the indicated number of times starting from the day and for the employee you have selected in the grid. To create new favourite shifts and sequences, see Set up favourite shifts and sequences. To change or delete existing favourite shifts and sequences, see Manage favourite shifts and sequences.

FAQs

I am planning for a week, and I have selected a shift to be assigned for 10 days in a row. When I go to look at the following week the days over the last week are not with the favourite shift assigned, why?

The favourite shifts, when we apply a repetition, are only assigned until it reaches the indicated number of repetitions or the last day of the selected period in parameters, whichever conditions that is met first.

To assign a shift 10 times we must have the 10 days we want to assign loaded in the planning.

I've assigned a sequence with time off and it gives me an error, why?

This is because we don't know the timetable of the time off to apply until we assign it to an employee and it can happen that the employee's time off's center timetable, overlaps with other shifts of the same sequence or other shifts already assigned to the employee for the same day where the time off corresponds.

I have assigned a shift or a sequence, but it gives me an error indicating that it cannot be assigned because the day for that center is not in process, why?

This is because the center that has the associated favourite shift or sequence for the day where we want to assign this favourite shift is in a different status to "On Going" and therefore cannot be edited.

Manage sales budgets

Start from: The Analytics module.

Select Sales Budgets > Budgets from the main menu.

Project or modify a sales budget

Select the Center where the budget you wish to modify is located.
Select the Budget to be modified.
Select the Year of the budget.
Select the Update button to load the budget data.

Define and adjust budget parameters

Once the budget is loaded, users can adjust different variables:
- Traffic (Customers or Tickets): Modify the projected number of customers or transactions.
- Adjusted Budgets by Sales Type and Period: Customize projections for each sales type (e.g., dine-in, takeout) and selected time periods.
- Distribution (%): Define how sales are allocated across different periods and sales types using historical percentages or custom allocations.

Set the reference data for the budget

Select the Data Source, Method, Center and Reference Year to be used to modify the budget.
Select a Month or Year depending on whether you are modifying an Annual or Monthly budget.
Under Non-Representative Dates select what to do with the dates you have set as non-representative.
Selecting the Use Budget As Reference For Future Dates checkbox will use the reference year's sales budget for future days where there are no actual sales yet.

Una captura de pantalla de una computadora Descripción generada automáticamente

Choose the budget method

Once you have selected whether to modify the Budget by Year or Month, on the screen that appears, you’ll be prompted to select a calculation method:
- Sales Budget: Modify sales figures directly.
- Ticket Budget and Average Ticket: Adjust projections based on ticket count and average spending per ticket
- Customer Budget and Average Net Ticket per Customer: Modify budgets based on expected customer volume and average spending per customer.
- Trend Analysis: Project budgets using historical data trends.
Within this screen, you can apply percentage variations to modify the budget against reference data. If set to zero, the budget remains unchanged.

Notes: The Lock Table button causes the data typed in a cell to be repeated in the entire row, Unlock Table allows you to adjust cell by cell, and Clear allows you to delete all data in the table and return it to zero.

Once you have made the settings in this table, select Accept to save the changes OR Cancel to discard them.

Interfaz de usuario gráfica Descripción generada automáticamente con confianza baja Notes: To make a budget adjustment, you must make sure that the budget has not been Closed. If it is closed, it must be reopened for modifications.

Export a sales budget

In the Budget Sales screen, select the Center where the budget you wish to modify is configured.
Select the Budget to be modified.
Select the Year of the budget.
Select the Update button to load the budget data.

Select the Excel button.
In the next window, choose the Template with budgeted data.

The resulting file will be an .XLS file with the budget data.

Tabla Descripción generada automáticamente con confianza media