Skip to main content

Simphony Install Handbook

  • Updated

Introduction

Please refer to this link to fill out the Agent configuration submission form:
Simphony Integration Form

The Omnivore Simphony integration utilizes the Simphony Transaction Services Generation 1(aka Gen1) Location API to inject orders and retrieve POS data for pricing and menu availability. The communication happens through a locally installed Omnivore Agent service called the POS Agent. The integration will pull the POS menu data to allow for various usage depending on the Application Partner that is utilizing it. 

Pre install Check

Simphony Version Requirements

Simphony versions 2.8, 2.9, 2.10; 18.2+; 19.2+. We do not support Simphony 19.1.

Simphony Environment Requirements

  • The designated Transaction Services Simphony client must have sufficient CPU, RAM, and storage space to process orders. Omnivore recommends a Quad-Core CPU with a 2 GHz speed or higher, 2GB of available RAM or higher, and at least 5GB of available storage space. 
  • Transaction Services and CAPS (check and posting service) can utilize the same physical Simphony client. 
  • The firewall must be set up to allow for outbound communication from the designed Transaction Services Simphony client. Please see below for network requirements.
  • The client must have Microsoft .Net Framework 4.5 or greater installed. 

Simphony Licensing Requirements

A Guest-Facing Transaction Services license is required in conjunction with an existing POS Client license. Please reach out to Oracle, or your POS support provider, for this license. 

Network Requirements

The integration requires the in-store network to allow for outbound internet traffic to Omnivore's servers. Please refer to the In-Store Firewall Allow List for the specifications. 

Connecting Simphony POS to Omnivore

The Omnivore Simphony integration is referred to as a Traditional or Push POS. This requires a local agent installed on a Simphony Workstation on the local network. Prior to the agent installation, the Simphony system needs to have an active Transaction Service license and the integration programmed into the Simphony database. The integration will also require information out of the database for Omnivore configurations. The below links provide you assistance on performing the Simphony programming, sending Omnivore the required variables, and how to install the Omnivore service.

 

Required Simphony EMC Configuration

Below is a set of information on how a Simphony system needs to be configured to be ready for the Omnivore integration. Since Simphony systems can have unique ways of being programmed, we recommend that you review these settings with your POS Support and/or Oracle Support to ensure that the settings are made in accordance with your specific Enterprise configuration.

Verify the Transaction Services licensing has been activated in your environment

  • Please consult with Oracle, or your POS support provider, for any assistance.

Configure a POSAPI Client Workstation

Create POSAPI Record

  1. Open the Workstations page in the Hardware/Interfaces section of EMC.
  2. Look for an existing workstation with Type set to POSAPI Client.
    • If one exists, open its Service Host tab and skip to the testing section at the end of this guide.
  3. If no POSAPI Client workstations are listed, click on the Insert Record icon in the menu bar.
  4. Select a recommended Object Number, or enter one manually.
  5. (Optional) Check the Use Template box.
    • Select the workstation you plan to use for the Host setting below as the Template Record.
  6. Enter POSAPI or desired Record Name.

General Tab

  1. Set the Type to 3 - POSAPI Client (this must be done first).
  2. In the Service Host Fields section, select the CAPS workstation(or Workstation hosting Transaction Services if different from CAPS) as the Service Host ID.

Transactions Tab

These values should be populated if a template workstation was selected.

  1. Minimum and Maximum Check Number values must match the Host workstation.
  2. Select the appropriate Default Order Type, if not already selected.
  3. Set or adjust any other values applicable to the location.

Order Devices Tab

These values should be populated if a template workstation was selected.

  • Only order devices enabled on the Host workstation are available to the POSAPI Client.
  • Select the appropriate Order Device Output entries (or just select all to be safe).

Revenue Centers Tab

Use the dropdown menus to add all desired Revenue Centers for integration. These values should be populated if a template workstation was selected. These values should match the Host Workstation identically.

 

Service Host Tab

Use the Host Name and Port in the Testing section below.

 

Restart the Transaction Services Host Workstation

Restart the Transaction Services Host Workstation that was identified in Step 2 from the General Tab section above. This should allow CAL to load the required files and configuration for Transaction Services.

 

Testing

Verify that the Transaction Services endpoint is operational by putting the SOAP URL into a browser and getting the xml code response.

Need more information? Click Here

 

Employees

Identify API Employee

An employee number to use with Simphony TS that has permissions for the Property/RVCs by way of Operator Records may have already been created with the POSAPI Client Workstation. To find an already created API Employee:

  1. Navigate to the Employee Maintenance section on the Enterprise level.
  2. Search without entering values.
  3. Find an appropriate employee record that has access to all RVCs by double-clicking the Employee and ensuring that the Operators tab has a record for all the desired RVCs.

Create Employee

  1. Navigate to the Employee Maintenance section on the Enterprise level.
  2. Click on the Insert Record icon.
  3. Select one of the recommended Object Numbers, or enter one of your choosing.
  4. (Optional but recommended to simplify configuration) Check the Use Template box.
    • Select an Enterprise- or Property-level manager as the Template Record.
  5. Enter a Record name. 

Ordering Employee

  • Repeat the steps in the previous section with a desired Ordering Employee name.

Need more information? Click Here

 

Optional Simphony EMC Configuration

Tenders

We recommend that you work with the Simphony system owner’s POS Support / Oracle Support to copy an existing Tender and modify its usage for the integration.

The Omnivore API has the ability to send different tenders that are configured in Simphony that are processed through Omnivore.

The Omnivore API only requires Option bit 48 - Item is Sharable from the Options tab, General Options section is selected.

 

Empty Menu Item

We recommend that you work with the Simphony system owner’s POS Support / Oracle Support to copy an existing Menu Item and modify its usage for the integration.

A $0.00 priced item, referred to as an Empty Item, is required for Application Partners that do not include Menu Items in their Open Ticket API calls (a.k.a. Discrete Ordering).

We recommend that the Empty Item is programmed in a way that adheres to the Enterprise’s currently Menu Item programming rules. The Menu Item should have a $0.00 Price Record and be set to not print. We recommend a name like “Empty Item” or the name of the Application Partner to denote its usage and ensure it won’t be changed inadvertently.

The Omnivore API requires the following for a Menu Item to be exposed to Transaction Services and for it to be cached by the API:

  • The Menu Item must have a Definition Sequence.
  • The Menu Item must have a Price Record.
  • The Menu Item must belong to a valid non-Condiment Menu Item Class.

Need more information? Click Here

 

Discounts/Coupons

We recommend that you work with the Simphony system owner’s POS Support / Oracle Support to copy any existing Discounts and modify its usage for the integration.

The Omnivore API supports Open and Preset Discounts of both Amounts and Percentages.

 

Service Charges

We recommend that you work with the Simphony system owner’s POS Support / Oracle Support to copy any existing Service Charges and modify its usage for the integration.

The Omnivore API supports Service Charges created in Simphony. Only non-taxable Service Charges display on API Ticket data as Service Charges; Taxable Service Charges are considered and displayed as Other Charges.

 

Minimum Omnivore Agent Configuration Information

Below is the minimum amount of configuration information required from EMC to program the Omnivore Agent for the integration.

  • Employee Record #.
    • Required: Yes.
    • Value: Numeric (i.e. 999).
    • Details: Employee Record # is used by our Agent to connect to the Simphony system, acting as the "Employee" for querying for data, expressed as the sole value in the directive ApiEmployee = <API Employee Record #>
  • Default Revenue Center Record # on POSAPI Client Workstation.
    • Required: Yes.
    • Value: Numeric (i.e. 999).
    • Details: Default RVC # is used by our Agent to pull the list of all the RVCs on the Property, expressed as the sole value in the directive ApiRevenueCenter = <Default RVC #>
  • Revenue Center Record #s.
    • Required: Yes.
    • Value: Numeric (i.e. 999).
    • Details: Record # is required for our config to note that the RVC should be enabled for our API to connect to, expressed as the value to the right of the equal sign in the directive ApiRevenueCenter<RVC ID> = <RVC #>.
  • Revenue Center IDs.
    • Required: Yes.
    • Value: Numeric (i.e. 999).
    • Details: RVC ID is required for our config to note that RVC should be enabled for our API to connect to, expressed as the value to the left of the equals sign in the directive ApiRevenueCenter<RVC ID> = <RVC #>.
  • Cash Tender Record #.
    • Required: Yes.
    • Value: Numeric (i.e. 999).
    • Details: Since there is no signal in the Simphony API for what is or is not a cash tender and our API reports and submits cash differently than other tenders, we use this value to disambiguate, expressed as the sole value in the directive CashTender = <Cash Tender Record #>
  • Save Check Tender Record #.
    • Required: Yes.
    • Value: Numeric (i.e. 999).
    • Details: The "Send", "Send and Stay", or Service Total Record # is required for our config to be used as the Tender sent with ordering API calls to be used to send the order to the back of house for preparation, expressed as the sole value in the directive SaveCheckTender = <Save Check Tender Record #>
  • SOAP URL.
    • Required: Yes.
    • Value: URL.
    • Details: The SOAP URL is required for our config as it's the primary method in which our API interacts with Transaction Services and the Simphony system, expressed as the sole value in the directive SoapUrl = <SOAP URL>

Testing Functionality Requirements

Please contact the Omnivore Support team for full testing of your location.

Upgrades

Upgrading the Agent is something that we do recommend you ask every quarter about as the Agent is always improving. Please use the document “Upgrade the Omnivore Agent on your Own” This will allow you to do this upgrade on your own. If you have further questions, please create a support request in the Omnivore Support Portal.

 

Required Simphony EMC Configuration, Detailed

Below is a more comprehensive set of information on how a Simphony system needs to be configured to be ready for the Omnivore integration. Since Simphony systems can have unique ways of being programmed, we recommend that you review these settings with your POS Support and/or Oracle Support to ensure that the settings are made in accordance with your specific Enterprise configuration.

Configure a POSAPI Client Workstation

Create POSAPI Record

  1. Open the Home Page in EMC.
  2. Select the appropriate Property in the navigation tree.
  3. Click the Setup tab.
  4. Click on Workstations, located in the Hardware/Interfaces section.
  5. Look for an existing workstation with Type set to POSAPI Client.
    • If one exists, open its Service Host tab and skip to the testing section at the end of this guide.
  6. If no POSAPI Client workstations are listed, click on the Insert Record icon in the menu bar.
  7. Select one of the recommended Object Numbers, or enter one manually.
  8. (Optional) Check the “Use Template” box.
    • Select the workstation you plan to use for the Host setting below as the Template Record.
  9. Enter POSAPI as the Record Name and click OK.

General Tab

  1. In the General Settings section, set the Type to 3 - POSAPI Client (this must be done first).
  2. In the Service Host Fields section, make sure the Service Host ID matches the Workstation hosting Transaction Services (our default is the CAPS).
  3. Click on the Save Record icon in the menu bar.

Transactions Tab

  • These values should be populated if a template workstation was selected.
  1. Minimum and Maximum Check Number values must match the Host workstation.
  2. Select the appropriate Default Order Type, if not already selected.
    • Default Order Type must be specified.
  3. Set or adjust any other values applicable to the location.
  4. If any changes were made, click on the Save Record icon in the menu bar.

Order Devices Tab

  • These values should be populated if a template workstation was selected.
  • Only order devices enabled on the Host workstation are available to the POSAPI Client.
  1. Select the appropriate Order Device Output entries (or just select all to be safe).
  2. If any changes were made, click on the Save Record icon in the menu bar.

Revenue Centers Tab

  • These values should be populated if a template workstation was selected.
  • These values, including their order, must match the Host workstation.
  1. Select the appropriate Revenue Centers for the deployment.
  2. If any changes are made, click on the Save icon in the menu bar.

Service Host Tab

Use the Host Name and Port in the Testing section below.

Restart the Transaction Services Host Workstation.

This should prompt CAL to load the required files and configuration for Transaction Services, as well as expose any changes to the Simphony Transaction Services API.

Testing

This will verify that the Transaction Services endpoint is operational.

  1. Open a web browser.
  2. Use the values from the Service Host tab and the following format to build a URL that will be entered into the browser’s address field:
  3. A page displaying xml code should be displayed.
  4. If the page is not reachable:
    • Verify the URL matches the format above and does not contain any spaces.
    • Consult the merchant’s technical contact regarding security settings or firewalls which may block access.
    • Request that the merchant contact Oracle support for further assistance.

 

Employees

Identify API Employee Number

An employee number to use with Simphony TS that has permissions for the Property/RVCs by way of Operator Records may have already been created with the POSAPI Client Workstation. To find an already created API Employee:

  1. Open the Home page in EMC.
  2. From the Enterprise level in the Navigation Tree.
  3. Click the Configuration tab.
  4. Click on Employee Maintenance, located in the Personnel section.
  5. Click the Search button, without entering any values.
  6. Look for an appropriate Employee Record. Sometimes this will be called “POSAPI” or just “API”.*
  7. Double-click on the Employee
  8. Select a Property
  9. Click the General Tab, ensure that the Employee has an Emp Class.
  10. Click the Operators Tab, ensure that the Employee has Operator Records for all desired RVCs.

* If this Employee does not exist, see the next section called “Create Employee #” for steps on creating a new Employee Record.

 

Create Employee #

  1. Open the Home page in EMC.
  2. From the Enterprise level in the Navigation Tree.
  3. Click the Configuration tab.
  4. Click on Employee Maintenance, located in the Personnel section.
  5. Click the Search button, without entering any values.
  6. Click on the Insert Record icon in the menu bar.
  7. Select one of the recommended Object Numbers, or enter one of your choosing
  8. Check the Use Template box
    • This is optional and used to simplify configuration
    • Select an Enterprise- or Property-level manager as the Template Record
  9. Enter a desired name for the record.
  10. Press OK.

Adding Operator Records

  1. From the Operators tab, click on the Insert Record button in the mennu bar.
  2. Check the boxes for all desired RVCs.
  3. Click OK.

Ordering Employee

  • Repeat the steps in the previous section with a desired Ordering Employee name.

 

Tenders

We recommend that you work with the Simphony system owner’s POS Support / Oracle Support to copy an existing Tender and modify its usage for the integration.

The Omnivore API has the ability to send different tenders that are configured in Simphony that are processed through Omnivore.

The Omnivore API only requires Option bit 48 - Item is Sharable from the Options tab, General Options section is selected.

Empty Menu Item

We recommend that you work with the Simphony system owner’s POS Support / Oracle Support to copy an existing Menu Item and modify its usage for the integration.

A $0.00 priced item, referred to as an Empty Item, is required for Application Partners that do not include Menu Items in their Open Ticket API calls (a.k.a. Discrete Ordering).

We recommend that the Empty Item is programmed in a way that adheres to the Enterprise’s currently Menu Item programming rules. The Menu Item should have a $0.00 Price Record and be set to not print. We recommend a name like “Empty Item” or the name of the Application Partner to denote its usage and ensure it won’t be changed inadvertently.

The Omnivore API requires the following for a Menu Item to be exposed to Transaction Services and for it to be cached by the API:

  • The Menu Item must have a Definition Sequence.
  • The Menu Item must have a Price Record.
  • The Menu Item must belong to a valid non-Condiment Menu Item Class.

 

 

 

Related articles