Adaco Events Guide

Introduction

The Events solution in Fourth Adaco is used by our customers for catering planning activities, such as generating recipe sheets and production plans, and submitting purchase and outlet requisitions. This resource enables you to create, update and delete events in Adaco.

Partners using this resource may also need to integrate with the Adaco Sales Item API to retrieve retail and menu items.

Quick Facts

Updates

You can find any updates on the Release Notes page for the Adaco Web API.

Get Access

Before integrating, you’ll need to set up a new user account in Fourth with access rights to the API and resource. 

Requests to the Events resource are not restricted by property. This enables you to create and update events for properties in which the user account is not present.

Step 1: create a user group

Create a user group for accessing the API within one of the Fourth properties — we recommend the central purchasing property where there is one.

For security, we also recommend that you limit the user group to access to just the "Events API" and "Sales Item API" as necessary. The setting for this is within the user group's Property > API Access sub-section. The group needs the Create, Update and Delete access right selected for the Events API.

Step 2: create a user account

In the same property, create a user account. Assign it to the API user group.

Getting locations and menu items

To use this resource, you'll need to know the:

• IDs of the locations (Adaco properties) that you are managing events for. These are the IDs normally agreed between the POS system and Adaco, which are entered as Property Identifier 2 in Adaco.
• Menu and retail items in Adaco, so that you can include them in the EventItems array.

You can get this data programmatically via the Adaco Sales Item API. This API can also return the RevenueCentre values in Adaco. See the API Guide and Reference for integration details.

Request headers

For all requests, you must provide your authentication details using Basic authentication in the header. Example header:

GET /{customerName}Service/WebApi/Events  HTTP/1.1
Host: instance.example.com
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json

Resources path

The path for Events requests is:

<ROOT>/{customerName}Service/WebApi/Events

This is made of:

• The domain name of the Fourth cloud, referenced as <ROOT> above.
• A customer-specific customerName — this is the same name in the URL that is used when the customer logs into Fourth Inventory for Hotels. You must also add "Service" to the name; e.g. "acmeService".

Identifiers

The key identifier for an event in all requests is the combination of:

• location — the Adaco property ID.
• EventReference — your unique reference for the event.

Example POST or PUT request

Both the POST and PUT Events methods use the same request body. You can send an array of one or more events in a request.

When making a PUT Events request, you must include the full payload for the event. Any optional data that is not included is set to null or zero. This includes all EventItems.

For full details about making POST and PUT Events requests, see the Adaco Web API Reference.

{
             "Location": "45",
             "EventReference": "123",
             "EventName": "Acme Conference",
             "EventType": "Buffet",
             "EventDateTime": "2021-10-20T19:00:00.000Z",
             "TotalForecastCovers": 40,
             "TotalActualCovers": 0,
             "ChargePerCover": 80.00,
             "RevenueCentre": "101",
             "GroupName": "Acme Sales team",
             "Comments": "VIP Customer. Beware of allergen requirements.",
             "EventItems": [
                    {
                          "PLU": "503622",
                          "ForecastCovers": 10,
                          "ActualCovers": 0,
                          "Station": "Hot Mains"
                    },
                    {
                          "PLU": "501671",
                          "ForecastCovers": 15,
                          "ActualCovers": 0,
                          "Station": "Cold Buffet"
                    },
                    {
                          "PLU": "502987",
                          "ForecastCovers": 15,
                          "ActualCovers": 0,
                          "Station": "Desserts"
                    }

             ]
       }
]

Example delete request

To delete an event you only need to send the location and eventReference for the event. You can delete multiple events by sending the events as an array in the request body.

For full details about the DELETE request, see the Adaco Web API Reference.

[
   {
        "Location": "45",
        "EventReference": "123"
   },
   { 
        "Location": "45", 
        "EventReference": "135"
   }
]

Response to requests

The HTTP Status responses provided by Fourth Adaco will be one of:

• 200 — The request was fully or partially successful. The response body contains more details including a status field and error messages that will confirm the status for the request.
• 400 — The request was unsuccessful. The response body contains more details including a status field and error messages that will confirm the status for the request.
• 401 — Unauthorised, with a generic response body.
• 403 — Forbidden, with a generic response body.

Arrays

If you sent an array of events, then the response will be 200 OK regardless of whether part of the request failed. You will need to use the status and error messages for your requests to check that the request was successful, rather than rely solely on the HTTP status code.

Unmatched items

When an event is created or updated, Adaco checks that each event item's PLU matches an existing retail or menu item in Adaco. If for some reason a matching item is not found, then the PLU is sent back in the UnmatchedItems array.

Adaco creates or updates the event regardless of any unmatched PLUs.

Example response

[
       {
             "Location": "99",
             "EventReference": "1",
             "EventName": "Event 1",
             "Status": "Created",
             "Errors": [
                    {
                    }
             ],
             "UnMatchedItems": [
                    {
                          "123456",
                          "654321"
                    }
             ]
       },
       {
             "Location": "99",
             "EventReference": "2",
             "EventName": "Event 2",
             "Status": "Created",
             "Errors": [
                    {
                    }
             ],
             "UnMatchedItems": [
                    {
                    }
             ]
       },
       {
             "Location": "77",
             "EventReference": "3",
             "EventName": "",
             "Status": "Not created",
             "Errors": [
                    {
                          "The submitted location value could not be matched to an Adaco property",
                          "Event name must be provided"
                    }
             ],
             "UnMatchedItems": [
                    {
                    }
             ]
       }
]

Status options

Error messages

The Errors array holds one or more error messages. If you receive an error message, this means that the event has not been created, updated or deleted.