MY MENU – SIMPHONY

TRANSACTION SERVICE
COMMUNICATION

March 15, 2024

My Menu
Version: 1.2
1.1 Simphony Architecture
The Transaction Services API (TS) is a web service hosted by ServiceHost.exe that is designed to run on
each POS workstation of the Simphony system. The Service Host application is a custom-built web server
by Oracle that hosts various services, such as transaction services, print controller, cash management,
check and posting, and the POS client user interface. These services are required on a workstation for end-
to-end POS operations. The user can remove the POS client user interface from Service Host (using the
Simphony EMC application) if only services must be hosted for third-party integration.

The POS client provides a user interface for all POS operations in the Simphony system. The order taker
can log on to the POS client using valid credentials and add a transaction to create a guest check. As part
of a transaction, he or she can add menu items, discounts, service charges, multiple tax rates, and tender
details to the guest check and save it to the POS database. The guest checks created on one workstation
of the property can be accessed from other workstations of the same property using the CAPS (Check and
Posting) service.

TS web service uses the same underlying business libraries used by the POS client for all POS operations.
Technically TS web service is a version of the POS client without the UI.

The guest check created through the Transaction Services API will post to the enterprise database
(MCRSPOS) for reporting purposes via CAPS. All transactions made through the TS web service or POS
client UI will first be stored in the local POS database named DataStore. The CAPS that owns
CheckAndPostingDB database will post all transactional data to the enterprise database (MCRSPOS) with
the help of EGateway service, which is hosted on the Simphony application server.

All configuration changes made by the EMC application at the enterprise server are downloaded to the
local POS database of each workstation using a DB Sync component. By default, the DB Sync operation
runs every 30 minutes. Thus, any configuration changes made at the enterprise server for a specific
property or workstation will be available for Transaction Services and the POS client within 30 minutes.
The DB Sync can also be manually initiated anytime using a function button in the POS client.

Direct Posting Services is a Windows service that runs on the application server to upload data from the
transaction database (MCRSPOS) to one of the reporting databases named LOCATION_ACTIVITY_DB. Any
workstation in a store can be configured to host TS API.

1.2 Hosting Method

The Transaction Services web service is pre-installed on each workstation or application server where the
Simphony installation media or CAL package was executed. Configuring a proper workstation client of type
POS API from the EMC application will allow for the successful hosting of Transaction Services web service
at the POS workstation.

The Service Host, configured via EMC to run on a workstation, hosts the Transaction Services API as a web
service by default at port 8080. The format of the web service URL is (optional to replace the localhost
address with the IP Address of the workstation):
http://127.0.0.1:8080/EGateway/SimphonyPosApiWeb.asmx

My Menu – Simphony Communication 1

Any client machine that has access to a given POS workstation can consume Transaction Services by
referring to the correct URL of the TS web service.

Apart from this method (that is, hosting TS web service on Service Host), TS web service can be hosted on
the application server as well, but it will never be applied because the application server is beyond the
boundary of third-party clients. By default, the Simphony application server has the TS web service
installed and hosted after the successful execution of Simphony installation media. This web service can
access the application server with the right URL. It is normally hosted on the following URL. Replace the
placeholder with the IP address of the application server below.

Note: Simphony Transaction Services is an API exposed at the location, typically on a workstation. Oracle
does not provide a function or mechanism to expose the API outside the location. Customers and their
Integrators will need to implement a service (i.e., Secure VPN, etc.) to establish communication with the
premise and local API.

2.1 My Menu Architecture

My Menu (MM) is a cloud-based SAAS application. My Menu has a Tablet Application (iOS & Android), QR
Menu Platform (web-based), and Panel (web-based).

My Menu servers are isolated from the public internet and lie inside the private subnet. All the requests
originating from the different MM servers are routed to the public via the NAT Gateway. The NAT gateway
has a static IP address. For integrations that require whitelisting of IP addresses, clients will whitelist the
NAT Gateways IP address. The incoming requests to the My Menu are routed through the Internet
Gateway(IG), and then IG forward the requests to the load balancer, and finally, it reaches the MM
Servers.

For WebSocket communication, MM uses AWS APIGateway. AWS fully manages this service, and there is
no static IP address. For any integration that uses WebSocket communication, the client will have to
whitelist the URLs instead of the IP address.

My Menu – Simphony Communication 2

3.1 Communication Model
My Menu communicates to the Simphony Transaction Service (TS) API using

1. The Public IP address or Reverse Proxy of the Hotel

3.1.1 Reverse Proxy / Hotels Public IP Address

My Menu communicates to the Simphony Transaction Service (TS) API through the static IP address of the
Hotel or the reverse proxy. All the communication originating from My Menu will be from a single IP
address. If the Simphony web service is running behind a firewall, the Hotel needs to whitelist the IP
address of My Menu Server. My Menu communicates to the hotel's IP address, and the request needs to
be forwarded to the internal IP address where the Transaction Service API is hosted.

My Menu static IP address is 15.184.81.153. This IP address needs to be whitelisted for incoming requests.
For the incoming request, My Menu expects a status from the TS. So, clients have to whitelist outgoing
requests for the response.

Diagram 1.1

The following IP’s need to be whitelisted.

IP’s: 15.184.81.153
Port number: 443

Messages:

My Menu – Simphony Communication 3

1. Connection Check
Establish the connection between My Menu Cloud and Transaction Service API.
The configuration details are checked by calling the transaction service API. If the API returns a
valid response, the details entered on the My Menu panel are correct, as shown in Fig: 1.2.

Endpoint: <ReverseProxy>/EGateway/SimphonyPosApiWeb.asmx
Packet flow:
Request: MM Cloud -> Hotel IP/Reverse Proxy -> TS Webservice

Payload:

<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetConfigurationInfo
xmlns="http://micros-hosting.com/EGateway/">
<vendorCode />
<employeeObjectNum>1</employeeObjectNum>
<revenueCenter>11</revenueCenter>
<configurationInfoType>
<int>16</int>
</configurationInfoType>
</GetConfigurationInfo>
</soap:Body>
</soap:Envelope>

Fig: 1.1

Response:

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

My Menu – Simphony Communication 4

 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<GetConfigurationInfoResponse
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://micros-hosting.com/EGateway/">
<configInfoResponse>
<OperationalResult>
<Success>true</Success>
<ErrorCode>Success</ErrorCode>
<ErrorMessage>Success</ErrorMessage>
</OperationalResult>
<ConfigInfoType>
<EConfigurationInfoType>VERSION</EConfigurationInfoType>
</ConfigInfoType>
<Version><?xml version="1.0" encoding="utf-8"?><?micros-type
System.String, mscorlib, Version=4.0.0.0, Culture=neutral,
PublicKeyToken=b77a5c561934e089?><string>19.2.1.0></Version>
</configInfoResponse>
</GetConfigurationInfoResponse>
</soap:Body>
</soap:Envelope>
Fig: 1.2

2. Menu Sync
The method used to pull Menu details from TS API
Endpoint: <ReverseProxy>/EGateway/SimphonyPosApiWeb.asmx
Packet flow:
Request: MM Cloud -> Hotel IP/Reverse Proxy -> TS Webservice

Payload:
<soap:Envelope

My Menu – Simphony Communication 5

 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetConfigurationInfo
xmlns="http://micros-hosting.com/EGateway/">
<vendorCode />
<employeeObjectNum>1</employeeObjectNum>
<revenueCenter>11</revenueCenter>
<configurationInfoType>
<int>13</int>
<int>8</int>
</configurationInfoType>
</GetConfigurationInfo>
</soap:Body>
</soap:Envelope>
Fig: 1.3
Response:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<GetConfigurationInfoResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://micros-hosting.com/EGateway/">
<configInfoResponse>
<OperationalResult>
<Success>true</Success>
<ErrorCode>Success</ErrorCode>

My Menu – Simphony Communication 6

 <ErrorMessage>Success</ErrorMessage>
</OperationalResult>
<ConfigInfoType>

<EConfigurationInfoType>MENUITEMMASTERS</EConfigurationInfoType>
<EConfigurationInfoType>FAMILYGROUP</EConfigurationInfoType>
</ConfigInfoType>
<FamilyGroups>
<?xml version="1.0" encoding="utf-8"?>
<?micros-type
Micros.PosCore.Extensibility.DataStore.DbRecords.DbFamilyGroup[], PosCore,
Version=2.5.0.0, Culture=neutral, PublicKeyToken=null?>
<ArrayOfDbFamilyGroup xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<DbFamilyGroup>
<FamGrpID>474</FamGrpID>
<HierStrucID>722</HierStrucID>
<ObjectNumber>100</ObjectNumber>
<Name>
<StringNumberId>132769</StringNumberId>
<StringText>"***FOOD***"</StringText>
</Name>
</DbFamilyGroup>
</ArrayOfDbFamilyGroup>
</FamilyGroups>
</configInfoResponse>
</GetConfigurationInfoResponse>

</soap:Body>

My Menu – Simphony Communication 7

 </soap:Envelope>

Fig: 1.4

3. Order Post
The method used to push the order details to the TS API
Endpoint: <ReverseProxy>/EGateway/SimphonyPosApiWeb.asmx
Packet flow:
Request: MM Cloud -> Hotel IP/Reverse Proxy -> TS Webservice

Payload:
<soap:Envelope
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<PostTransactionEx2
xmlns="http://micros-hosting.com/EGateway/">
<pGuestCheck>
<CheckDateToFire>2023-02-10T07:01:02</CheckDateToFire>
<CheckEmployeeObjectNum>1009</CheckEmployeeObjectNum>
<CheckGuestCount>0</CheckGuestCount>
<CheckID />
<CheckNum>0</CheckNum>
<CheckOrderType>1</CheckOrderType>
<CheckRevenueCenterID>40</CheckRevenueCenterID>
<CheckSeq>0</CheckSeq>
<CheckStatusBits>0</CheckStatusBits>
<CheckTableObjectNum>1604</CheckTableObjectNum>
<EventObjectNum>0</EventObjectNum>
<PCheckInfoLines>
<string>*** Paid - 53.78

My Menu – Simphony Communication 8

 Online - (Stripe) ***</string>
<string>*** Ticket: 2047 ***</string>
<string>*** ***</string>
<string>*** ***</string>
</PCheckInfoLines>
</pGuestCheck>
<ppMenuItemsEx>
<SimphonyPosApi_MenuItemEx>
<Condiments>
<SimphonyPosApi_MenuItemDefinitionEx>
<MiObjectNum>31930136</MiObjectNum>
</SimphonyPosApi_MenuItemDefinitionEx>
<SimphonyPosApi_MenuItemDefinitionEx>
<MiObjectNum>31930149</MiObjectNum>
</SimphonyPosApi_MenuItemDefinitionEx>
<SimphonyPosApi_MenuItemDefinitionEx>
<MiObjectNum>31930190</MiObjectNum>
</SimphonyPosApi_MenuItemDefinitionEx>
</Condiments>
<MenuItem>
<MiObjectNum>31025016</MiObjectNum>
<MiQuantity>1</MiQuantity>
<MiReference></MiReference>
</MenuItem>
</SimphonyPosApi_MenuItemEx>
<SimphonyPosApi_MenuItemEx>
<Condiments/>
<MenuItem>
<MiObjectNum>31025002</MiObjectNum>
<MiQuantity>1</MiQuantity>

My Menu – Simphony Communication 9

 <MiReference></MiReference>
</MenuItem>
</SimphonyPosApi_MenuItemEx>
<SimphonyPosApi_MenuItemEx>
<Condiments/>
<MenuItem>
<MiObjectNum>31037001</MiObjectNum>
<MiQuantity>1</MiQuantity>
<MiReference></MiReference>
</MenuItem>
</SimphonyPosApi_MenuItemEx>
</ppMenuItemsEx>
<ppComboMealsEx />
<pSvcChargeEx>
<SvcChgObjectNum>1</SvcChgObjectNum>
<SvcChgAmountOrPercent>8.21</SvcChgAmountOrPercent>
<SvcChgReference />
</pSvcChargeEx>
<pTmedDetailEx2>
<SimphonyPosApi_TmedDetailItemEx2>
<TmedEPayment>
<AccountDataSource>SOURCE_UNDEFINED</AccountDataSource>
<AccountType>ACCOUNT_TYPE_UNDEFINED</AccountType>
<ExpirationDate>0001-01-01T00:00:00</ExpirationDate>
<IssueNumber>0</IssueNumber>
<PaymentCommand>NO_E_PAYMENT</PaymentCommand>
<StartDate>0001-01-01T00:00:00</StartDate>
</TmedEPayment>
<TmedObjectNum>202</TmedObjectNum>
<TmedPartialPayment>0.00</TmedPartialPayment>

My Menu – Simphony Communication 10

 <TmedReference></TmedReference>
</SimphonyPosApi_TmedDetailItemEx2>
</pTmedDetailEx2>
<pTotalsResponseEx />
</PostTransactionEx2>
</soap:Body>
</soap:Envelope>
Fig: 1.5

My Menu – Simphony Communication 11