Skip to main content

Shopping

Enabling Tachyon integration

Prerequisites

This page assumes that you have a working Tachyon installation, for more details on implementing Tachyon please refer to the Tachyon documentation.

Tachyon Platform

If you want to use the Tachyon-related features - client-side Order Tracking and Tachyon Instruction Applications - you will need:

  • Tachyon license with Shopping-specific instructions enabled

  • Tachyon Platform 9.0 & 9.1(on-premises), 23.11(single-tenanted SaaS) or Elastic SaaS

  • 1E Client (the latest hotfix applied) or later, with the Shopping client and Tachyon Agent enabled.

You will need a Tachyon license that covers the Shopping-specific instructions if you want to use the client-side features of Shopping's Order Tracking feature. Contact 1E for a Shopping addition to your Tachyon license if you do not already have it.

Note

To automatically enable and configure this feature in Tachyon during installation or upgrade of Shopping Central, the Shopping Installer Account must be a Tachyon user assigned to the following roles. This can be temporary, and removed after installation.

  • Tachyon 8.x - Full Administrator assigned to All Devices.

In Tachyon, you will also need:

  • A Tachyon user - a domain account that will be used as a proxy by Shopping

  • A Tachyon role called Shopping Administrator - assigned to the Tachyon user

  • A Tachyon consumer called Shopping

  • An Instruction set called 1E Shopping with Actioner permission assigned to the Shopping Administrator role

  • An instruction (file name 1E-Shopping-ShowNotification.xml) added to the Instruction set that interfaces with the 1E Client Shopping module.

Note

All of these are added to Tachyon automatically by the Shopping Central installer, if you enable Tachyon integration when installing or upgrading Shopping, and you have configured the Installer Account permissions listed above.

Enabling Tachyon integration during Shopping installation or upgrade

Ensure you have configured all the prerequisites listed above. Then follow the steps in Installing Shopping Central or Upgrading to Shopping until you reach the screen where you Enable Tachyon Integration.

Tachyon Platform Portal

Ensure you have configured all the prerequisites listed above. Then follow the steps in Installing Shopping Central or Upgrading to Shopping until you reach the screen where you Enable Tachyon Integration.

You need to check the Enable Tachyon Integration checkbox and provide details for your Tachyon Platform implementation, if you require either of the following Shopping features:

  • Shopping for Tachyon Instructions

  • Client-side Order Tracking - notifying Shoppers using a notification icon and toast popups

1E_Integration_Modern_Auth.png

You need to fill out the values against each of the fields on this wizard. The following table describes the fields:

Fields

Description

Tachyon Platform base URL

Set this to the base URL for your Tachyon Platform implementation. For example https://tachyon.acme.local:443/.

Set-up user

Set this to the user name for the account you want to use for running the Tachyon Instructions that implements the client-side Order Tracking feature and any Tachyon Instructions you are making available as Shopping applications. The user name must be provided in the form Domain\User. You could even set this to the account details you used for the Shopping Service account to save having to provision another account. This user has to do the following tasks:

  • Create the Shopping Administrators role in Tachyon

  • Create an instruction set called 1E Shopping and add the client-side Order Tracking instruction to it

  • Give the Shopping Administrators role permission to run the instruction

  • Add the specified user account to Tachyon

  • Assign the user account to the Shopping Administrators role

  • Save the name as Tachyon username in the Shopping Console settings (also saves its password encrypted)

  • Read access on the private key

Integration User

This user is to be added as a Shopping administrator in the Tachyon Platform. The user name must be in the UPN format.

Client Assertion App ID

The application ID of the client assertion app ID is used to retrieve tokens for authentication on Tachyon Platform.

Signing Certificate for Platform tokens

This is the thumbprint of the certificate which is added to Client assertion app and also imported to certificate store of the server.

Add private key permissions

This checkbox grants the read permission to the Shopping Admin group and Central service account on the private key of the above certificate in the certificate store. This permission is required for creating the jwt required in fetching the authentication platform token.

Click Next to continue.

Ensure that you have the prerequisites before proceeding with the below steps as mentioned under Tachyon Platform.

Configure Microsoft Entra ID for the integration
Create certificate/principal mapping in 1E Platform

  1. Install the certificate with private key locally to the local machine personal certificate store. Ensure that you have added the required permissions to access the private key to the Shopping installer account.

  2. Login to your 1E instance using Set-1E Server.

  3. Get the certificate kid using:

    Get-1ECertificateThumbprint -StoreName localmachine\my | fl *

    The kid value of a certificate is a base 64 encoding of the certificate thumbprint.

  4. Now create a mapping using:

    Add-1EJwtPrincipalMapping -Identifier <Certificate-Kid> -Principal <1EUser@domain.com>

    Note that the above proxy user should be a principal with appropriate permissions in 1E.

    API_permissions.png
Upload the public key PEM file in Microsoft Entra ID

  1. Export the certificate that you have imported in the above steps in .CER format.

  2. Login with the administrator principal role.

  3. Navigate to Azure Active Directory → App Registrations → 1E Client Assertion → Certificates and upload the certificate.

    Cert_Upload.PNG
Managing Tachyon instruction sets

If you have enabled Tachyon integration, you're now ready for your Tachyon administrator to permission instructions sets, and upload product packs containing instructions to offer to your Shoppers.

You can only use Shopping to offer Tachyon action instructions, you cannot offer questions.

Note

By default, Shopping administrators will be able to offer all action instructions from Tachyon. However, many Tachyon action instructions are meant to fix technical issues that you and other IT staff understand well, but end-users may not. This means that you rely on Shopping administrators using common sense when choosing the instructions to publish as Tachyon instruction applications.

It's a good idea instead to restrict the range of Tachyon instructions made available to Shopping administrators to specific Instructions sets. Then, when Shopping administrators are creating Tachyon instruction applications to make them available to users, they will only be able to select from the Tachyon instructions available in those sets - not all the Tachyon instructions. Regardless of whether the Instructions sets contain both action and question instructions, the Shopping administrators will only see action instructions.

Each instruction can belong to only one Instruction set. Each Instruction set can contain multiple instructions, and can be assigned to one or more Tachyon roles. Shopping uses only one role called Shopping Administrators to which you will assign your chosen Instruction sets.

All of that is optional. You can use the following processes if you want to take the restrictive approach. By default, Shopping administrators will be able to offer all action instructions.

Restrict the Tachyon Shopping Administrators role to the instruction set

  1. In the Tachyon Settings app, go to the Permissions, Roles node.

  2. Click on the Shopping Administrators role - if this does not exist then check with your Tachyon administrators they have not used a different name, which may happen if Enabling Tachyon integration after Shopping 6.1 installation or upgrade.

  3. Click on Members to confirm the listed Tachyon username is the one specified in your Shopping Console settings.

  4. Click onManagement Groups to confirmAll Devicesis listed - this is the default - if required, you can change this to select specificManagement Groupsto limit the scope of devices you can send instructions to.

  5. Click on Permissions then for each Instruction set.

    1. Click Add then in the Add permission dialog.

    2. Click on the Type drop-down and select Instruction set type.

    3. Click on the Name drop-down and select your chosen Instruction set - if this does not exist then you will need to Cancel the Add step, and Create an Instruction set.

    4. Check Actioner.

    5. Click Add.

  6. If you want to delete an Instruction set, check the checkbox to its left and click Delete button on the right.

Create an Instruction set

Instructions are available from 1E in Product Packs, which are zips provided as part of Tachyon Platform installation, or downloaded from Tachyon Exchange. You can use the Exchange to search for suitable product packs, or submit requests for new instructions. You or your Tachyon administrator can also author your own instructions, as described in Writing Tachyon Instructions.

You can use the Tachyon Product Pack deployment tool to upload Product Packs, and the tool will automatically create one Instruction set for each pack. This is the preferred way of uploading instructions and creating Instruction sets.

Alternatively, you can use the Instruction sets page to manually upload Product Packs and then assign their instructions to Instructions sets you also create manually.

Upload or move instructions

Upload or move instructions to your instruction set. This process is fairly intuitive once you have created an Instruction set. Please refer to Instruction sets page if you need more detail.

You are now ready to offer Tachyon instructions to your users.

Enabling Tachyon integration after Shopping installation or upgrade

If you installed or upgraded to Shopping without enabling the Tachyon integration, you must then:

  • Create a Tachyon consumer

  • Create a Tachyon Shopping Administrators role

  • Load a Tachyon instruction to communicate with the 1E Client Shopping module

  • Set values in the Shopping console

These steps are done automatically if you enable Tachyon integration while installing or upgrading to Shopping, so that option is much preferred.

The same Tachyon user permissions are required for the user doing the configuration.

Create a Tachyon Shopping consumer

In the Tachyon Settings application:

  1. Open the Configuration node and select Consumers.

  2. Click Add.

  3. Set the Name to Shopping.

  4. Set the Maximum simultaneous instructions to 1000.

  5. Click Save.

230740620.png
Editing the Tachyon Shopping consumer workflow

The Tachyon consumer page does not allow you to specify the workflow for the Shopping consumer. This must be done using SQL Server Management Studio. To do so:

  1. Open SQL Server Management Studio and connect to the SQL instance that hosts the TachyonMaster database.

  2. Open a New Query and paste the below SQL query - no edits are required.

  3. Execute the SQL query and confirm the Shopping workflow setting is changed from NULL to:

    [{"ReferenceType":0,"InstructionWorkflow":[{"InstructionType":1,"Workflow":{"StateMachine":"State"}}]}]

  4. Close SQL Server Management Studio.

SQL script to configure Tachyon Shopping consumer workflow

SQL script to configure Tachyon Shopping consumer workflow 

/* Script to change TachyonMaster Consumer setting */
USE [TachyonMaster]
GO
DECLARE @setting nvarchar(max), @oldvalue nvarchar(max), @newvalue nvarchar(max)
SET @setting = 'Shopping'
SET @newvalue = '[{"ReferenceType":0,"InstructionWorkflow":[{"InstructionType":1,"Workflow":{"StateMachine":"State"}}]}]'

SET @oldvalue = (SELECT [Workflow] FROM [dbo].[Consumer] WHERE [Name]= @setting)
 
UPDATE [dbo].[Consumer] SET [Workflow]=@newvalue WHERE [Name]=@setting
 
SELECT @setting AS 'Setting', @oldvalue AS 'Before', [Workflow] AS 'After' FROM [dbo].[Consumer]
WHERE [Name]=@setting
GO
Create and assign a Shopping Administrators role in Tachyon

In the Tachyon Settings application:

  1. Open the Permissions node and select Roles

  2. Click Add

  3. For the Name, use Shopping Administrators - any name will do, but this is what the installer would have created automatically

  4. For the Description, use something like Users with this role can use the Shopping related instructions

  5. Click Save

  6. Click on the newly added role

  7. Go to the Permissions tab and click Add

  8. For the Type, select Instruction set

  9. For the Name, select Shopping - If Shopping is not available it is because you don't have a suitable Tachyon license

  10. Click the Actioner checkbox

  11. Click Add

  12. Click on the newly added role again

  13. Select the Members tab and click Add

  14. Add a user account - this is the same account specified in the Shopping Admin Console

230740619.png
230740618.png
Upload a Tachyon instruction to communicate with the 1E Client Shopping module

  1. Locate the 1E-Shopping.zip Product Pack (in the ProductPacks folder of the Shopping download zip available from the 1E Support Portal)

  2. Upload the 1E-Shopping Product Pack using the Tachyon Product Pack deployment tool (in the Tachyon Platform download zip available from the 1E Support Portal)

  3. In the Tachyon Portal, use the Settings app to navigate to Instructions→ Instruction sets and confirm

    1. existence of an Instruction set called 1E Shopping

    2. containing an instruction with name starting with: Show a notification with title %title% and description %description% to user %userName%...

  4. Search for Shopping

  5. Download the Shopping product pack and load it as per the Tachyon documentation for loading product packs

Set values in the Shopping Console

In the Shopping Admin Console:

  1. Open the Settings node and scroll down to the Tachyon Integration section

  2. Set Tachyon Integration to Enabled

  3. Set Tachyon Username and Tachyon Password to a Tachyon account - this account can be the same as the Shopping Central service account, but to keep to the principal of minimal privileges should be a unique account only used for connecting Shopping to Tachyon. The account requires no privileges other than being defined as a Tachyon account and having the Tachyon Shopping Administrators role

  4. Set the Tachyon Base URL to the URL for your Tachyon server

  5. The other values can be left at their default settings - see table below for guidance on changing values

  6. Click Save to save the settings

  7. Restart the Shopping Central service.

Setting name

Default value

Description

Order Tracking Enabled

False

Enables the Order Tracking feature on all clients when set to true.

The Order Tracking feature provides users with order tracking information via:

  • Shopping notification area icon and toast popups on clients

  • Notification emails.

To disable the icon and popups on a subset of clients, add Shopping client settings: Module.Shopping.OrderTrackingEnabled to the client configuration file and set to false. This setting does not affect emails.

You can control which notifications and emails that users receive using the web administration settings described in Managing Order Tracking.

Tachyon Base URL

Depends on installation

Set this to the base URL for your Tachyon Platform implementation.

For example: https://tachyon.acme.local:443/

Tachyon Instruction Processor Interval

5

Interval which Shopping checks to see if there are any new Tachyon Instruction Application orders to be run. This starts the gather period.

If you set this value smaller than the default, the Tachyon instruction applications will complete faster, but will add a bit more server load to the Shopping and Tachyon servers. Instruction applications will on average take half of whatever this value is. For example, when set to 5, instructions could take from 0 to 5 minutes to be effective, averaging 2.5 minutes.

Note that some instructions have their own stagger period to wait after being sent to the client and actually running.

Tachyon Instruction Status Processor Interval

5

Interval which Shopping polls Tachyon for status. Default value is 5 minutes.

Tachyon Instruction TTL Minutes

60

This defines the length of the gather period which Tachyon uses to wait for offline devices to come online and run the instruction.

When a Shopper shops for an Instruction application, they will be online. However, they may be offline if the instruction requires approval in shopping. A device may also be offline if administrators are shopping on behalf of the user.

Tachyon Integration Enabled

Depends on installation

This setting must be true if you want to use Tachyon Instruction applications or Order Tracking features.

If you change this from true to false, and restart the Central service, then pending Instruction applications will not be processed. Instruction applications will not be visible in the Shopping website for new users. Existing users will see them until their Shopping cache is refreshed, and any request will not be processed. Changing this setting back to true will continue to process the requests.

Tachyon Password

Depends on installation

Password for Tachyon Username - this is saved encrypted.

Tachyon Username

Depends on installation

Set this to the user name for the account you want to use for running the Tachyon Instructions.

230740616.png
In this section: