Try out commercetools InStore

Overview

This tutorial explains how to establish connectivity between the integration server and a store location that you create. The activities you will perform resemble setting up an actual production InStore environment. You'll become familiar with the InStore Center and the InStore colleague app. This tutorial does not require that you have an actual location or physical devices to connect.

Prerequisites

You'll need to obtain the following information from your commercetools representative:

• Credentials and a link for the InStore Center
• Credentials and a link for the InStore colleague app
• A key for the environment that will be your workspace during the tutorial
• A temporary integration server URL

Setup

Set up a store role

For this exercise, we have already created a "Store Manager" role and assigned you to it. In your actual implementation, role setup is a task you need to complete.

1. Log in to the InStore Center using the provided credentials, preferably on a Chromium-based browser.

2. On the left-hand navigation, click Store Roles.

3. Click ADD STORE ROLE.

4. On the Role Information pane, complete these settings:

   • Role Name: provide a unique name for this role that will apply to all locations in this environment, for example, Shift Lead or Sales Associate.
   • Role Description: provide guidance that store managers use when they assign this role to the users, such as Has full permissions in the store or Can perform sales and refunds only.

5. On the Permissions pane, select the permissions that you want to try out in the InStore colleague app. To sign in to the application, a user must select at least one permission. To set up a new location, a user must have at least the DeviceManagement permission.

   

6. Click SAVE CHANGES. The role you set up will be available to all future locations in this environment.

Set up the environment

1. Log in to InStore Center.

2. If you have received more than one environment from us, click the Settings icon, then click Switch Environment to verify you're in the correct environment. If necessary, select the correct environment and click SWITCH.

3. On the left-hand navigation, click Environment. The labels next to the page title indicate the environment type, for example, Test and the status, for example, New.

   

4. On the General tab, complete the following settings:

   • Label: rename this to a short name that retailer administrators will use when selecting to access this environment from the Dashboard, such as Acme-NSW.

   • Name: assign a unique name for the environment. For now, this can match the label.

   • Description: provide a description that identifies the intended purpose and users of the environment, such as Pre-Integration test drive environment to walk through setup.

   • TaxId: provide a sample tax identifier for this environment, such as US1234-5678. This field is optional and in your actual implementation, it can be used to include the retailer's government-issued tax identifier on receipts where required by the country's tax authority. This value applies to all locations within the environment unless overridden at the Location level.

   • Locale: select a locale (geography-specific language) to apply by default to locations in this environment. InStore uses ISO notation to identify locale—for example, en-US indicates English as spoken in the USA. This field lists all locales supported by InStore.

   • Currency: select a currency to apply to this environment.

     After you save this environment as active, you can no longer change this selection.

   • Parameter Set: verify this is set to a base parameter set. To experiment with changing this parameter set to suit the retailer's policies, see Parameter sets.

   • Template Set: verify this is set to a base template set. To explore changing receipts to suit the retailer's usage, see Template sets.

5. Click SAVE CHANGES.

6. On the Payment Processors tab, click ADD PAYMENT PROCESSOR and complete the following settings:

   • Processor: select Simulator, which is the InStore demo simulator.
   • Supported Payment Types: select all available options.

7. Click ADD, then click SAVE CHANGES & ACTIVATE ENVIRONMENT.

   If this button is not available, verify that you have at least one processor listed and at least one Store Role set up.

8. Click CONFIRM.

9. For the purposes of this demo, skip the Project Settings and Custom Fields tabs as these have been pre-populated for you based on our tutorial Project in Composable Commerce. For real-world configuration, you populate these in your Composable Commerce Project using a script, then return to the InStore Center to map them.

10. On the Integration Settings tab, complete the settings as shown below, substituting * with the integration server URL provided to you by your commercetools representative. In your actual environment, you’ll use the suffixes below with an integration-server URL that is unique to your organization.

    Setting name	Value you type after the URL
    Webhook URL	*/webhook
    Webhook Verification Key	NebulaTerra
    Cart Retrieval URL	*/commercetools/checkout/
    Return Cart Retrieval URL	*/commercetools/refund/

11. Complete the following settings, substituting * with the InStore colleague app link provided by your commercetools representative. In your actual environment, you’ll substitute your own in-store app's URL and then add the suffixes shown.

    Setting name	Value you type after the URL
    Token Retrieval URL	*/usertoken/
    Callback API Key	NebulaTerraKey
    Key Sync URL	*/tenant
    Sync API Key	NebulaTerraKey

12. Click SAVE CHANGES.

Add a location

1. On the left-hand navigation, click Locations.

2. Click ADD LOCATION.

   

3. On the Location Information page, complete the following settings:

   • Location Name: assign a name for the location, such as Downtown Store. This is displayed in the InStore Center and dashboard.

   • Location ID: specify an identifier for this location that is 001, 002, 003 or 004.

     You'll need to remember this identifier because it's required when logging in to the InStore colleague app.

   • Tax ID: leave this blank. A value here would override the environment's Tax ID just for this location. This field is for if you need the receipt to reflect a location Tax ID that varies from the parent retailer company's Tax ID, such as for a franchise, concession, or other local store arrangement.

   • Location Type: select the option that describes this location. If you do not find a suitable option, note that Location Types are configurable via Reference Lists.

   • Card Payment Processor: set to Simulator.

   • Gift Card Processor: set to Simulator.

   • Wallet Processor: set to Simulator.

   • Pay On Account Processor: set to Simulator.

   • Parameter Set: leave this blank. A value here would override the environment's parameter set just for this location. To experiment with changing this parameter set to suit the retailer's policies, see Parameter sets.

   • Template Set: leave this blank. A value here would override the environment's receipt templates just for this location. To explore changing receipts to suit the retailer's usage, see Template sets.

   • Language: verify that this is set correctly.

   • Address fields: provide sample information here to see how it will be displayed on receipts.

   • Telephone Number: provide the locally formatted phone number as you want it to be displayed on receipts.

4. Click SAVE CHANGES.

Access the InStore colleague app

1. Open the Storefront Accelerator link provided to you by your commercetools representative.

2. Complete or verify this information on the Update Settings pane of the Login page:

   • Key: provide the key that you received with your login credentials.
   • Location ID: provide the identifier for the location you created during Add a location. This will be 001, 002, 003, or 004.
   • Workstation ID: specify 01.

3. Click Update.

4. On the Enter Credentials page, complete the User ID and Password fields with the information you received from your commercetools representative.

5. Click Log In.

Set up devices for the location

For this demo, you need to set up a printer, cash drawer, workstation, and safe but you do not need any physical devices. For the purposes of this demo, we are not adding a scanner or a pin entry device (PED).

To set up the remaining devices, on the left-hand navigation of the InStore colleague app, select Manage Devices, then complete the following steps to set up each type of device:

Printer

1. Expand Printers and click ADD PRINTER.

2. Complete the following settings:

   • Device Name: assign a name that is meaningful to store associates, such as Main Checkout.
   • Supported Device: select from among supported models.
   • Shared: verify this is selected.
   • Activated: verify this is selected.
   • Printer Server Address: provide any URL in valid URL format.
   • Printer Address: assign any ip-formatted address, such as 192.0.2.1.

3. To save the device, click REGISTER.

Cash drawer

1. Expand Cash Drawers and click ADD CASH DRAWER.

2. Complete the following settings:

   • Cash Drawer ID: assign an ID that is unique to the location, such as 01. Any future cash drawers or safes that you create for this location cannot use this ID.
   • Device Name: assign a name that is meaningful to store associates, such as Main Checkout.
   • Supported Device: select from among the supported models.
   • Shared: verify this is selected.
   • Eligible as Safe: toggle this control to select it, which indicates this cash drawer could be assigned to act as the store's safe if required. Activating a location requires a safe or a safe-eligible cash drawer. For more information about safes, see Registering a safe.
   • Activated: verify this is selected. Activating a location requires an active cash drawer.
   • Connected Printer: select the printer that you previously added.

3. To save the cash drawer, click REGISTER.

Workstation

1. Expand Workstations and click ADD WORKSTATION.

2. Complete the following settings:

   • Workstation ID: assign an ID that is unique to the location, such as 01.
   • Device Name: assign a name that is meaningful to store associates, such as Main Checkout-iPad.
   • Supported Device: select from among the supported models.
   • Mobility: select Stationary.
   • Parameter Set: leave this blank. A value here would override the environment's parameter set just for this location. To experiment with changing this parameter set to suit the retailer's policies, see Parameter sets.
   • Activated: verify this is selected. Activating a location requires an active workstation.
   • On-Screen Keypad: verify this is selected.
   • Default Printer: select printer you previously added.
   • Default Cash Drawer: select the cash drawer you previously added.

3. To save the workstation, click Register.

Safe

1. Expand Safes and click ADD SAFE.

2. Complete the following settings:

   • Safe ID: assign an identifier to the safe that is unique from other safes and cash drawers in the location, such as 02.
   • Device Name: assign a name to this device that is unique to the location, such as Back Office Safe. Remember this name, because you must specify it in the InStore Center.
   • Supported Device: select Store Safe.
   • Shared: verify this is selected.
   • Activated: verify this is selected.

3. To save the safe, click Register.

4. Click Activate Location.

   If this button is not available, verify that you have followed the settings listed above.

5. Click DONE. You are taken to the Settings page.

6. Use the Workstation field to select the workstation you created. Select responses to claim the workstation.

7. Click UPDATE.

8. Log in again and notice that many more menu options are displayed, depending on the user's role.

Add your safe to the InStore Center

1. Go to the InStore Center.
2. On the left-hand navigation menu, click Locations.
3. Click the Edit icon for the location you just created.
4. In the Store Safe field, select the name of the safe you added in the InStore colleague app. Click SAVE CHANGES.

Prepare to receive cash

1. Go to the InStore colleague app.
2. On the left-hanf navigation menu, click Manage Cash, then click Cash Count.
3. Select to count the default cash drawer by selecting the Opening Count Reason, then click NEXT.
4. Type numbers of bills and coins that total more than 50.00, which is the default reserve amount for this environment. (This amount is also the starting point for each future cash drawer you create.)
5. Click NEXT.
6. Click ACCEPT.

The workstation is ready to process take-with sales paid with cash.

Explore InStore

Now that you have launched your virtual location, you have options.

Simulate setting up more in-store devices

The InStore colleague app allows users with the appropriate role (such as store managers) to activate, deactivate, and configure devices within a location. You don't need to have physical devices to practice connecting them.

For more information about each device type, see the following:

• Printers
• Cash Drawers
• Scanners
• PEDs
• Workstations
• Safes

Check out InStore features

We have a short list of activities that you can try, or you can make your own path based on your requirements.

To run transactions:

• Ring up sales with all tender types and combinations that the retailer accepts
• Run cash-management activities you will require, including your end-of-day
• Generate receipts

View InStore Center lists and metrics

After you have performed transactions using the InStore colleague app, use the InStore Center to track your activities by viewing these features:

• Dashboard statistics
• Cash Count monitoring
• Transaction search
• Device search

Provide access to others on your team

To add more administrators, see Users.

Get to know the InStore API

Now that you have seen how locations access the integration server, you can continue planning your integration.

Backend developers can check out the implementation overview to learn how to define the connections to the InStore integration server.