1E Platform integration

Prerequisites

This page assumes that you have a working 1E Platform installation. For details on implementing 1E, refer to the following articles:

• 1E Platform provisioning and upgrading guide

• 1E Platform in Infrastructure and licenses

Enabling the 1E Platform integration during Shopping installation or upgrade

Ensure you have configured all the prerequisites listed above, and then follow the steps outlined in Installing Shopping Central or Upgrading Shopping until you reach the screen where you can enable the 1E Platform integration.

1E Platform portal

1. Check the Enable 1E Platform Integration checkbox if you require any of the following Shopping features:

   • Shopping for 1E Instructions

   • Client-side Order Tracking to notify Shoppers via a notification icon and toast pop-ups.

2. Fill in the following fields for your 1E Platform implementation.
   
   

   Field	Description
   1E Platform base URL	Set this to the base URL of your 1E Platform. For example, https://tachyon.acme.local:443/.
   Setup User	Set this to the user name of the account you want to use for running the 1E Instruction that implements the Client-side Order Tracking feature and any 1E Instructions you are making available as Shopping applications. The user name must be provided in the form of Domain\User. You could even set this to the account details you used for the Shopping Service account to avoid having to provision another account. This user has to perform the following tasks: Create the Shopping Administrators role in 1E. 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 the 1E Platform. Assign the user account to the Shopping Administrators role. Save the name as 1E username in the Shopping Console settings (also saves its password encrypted). Allow read access on the private key.
   Integration User	This user is to be added as a Shopping administrator in the 1E Platform. The user name must be in UPN format.
   Client Assertion App ID	The Client Assertion App ID is used to retrieve tokens for authentication in the 1E Platform.
   Signing certificate for Platform tokens	This is the thumbprint of the certificate that is added to the Client Assertion App and also imported to the certificate store of the server.
   Add private key permissions	This checkbox grants 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 to fetch the authentication platform token.

3. Click Next to continue.

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.
     

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.
   

Managing 1E instruction sets

If you have enabled the 1E Platform integration, you're now ready for your 1E administrator to manage instructions sets, and upload product packs containing instructions to offer to your Shoppers.

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

Each instruction can belong to only one Instruction set. Each Instruction set can contain multiple instructions, and can be assigned to one or more 1E 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 1E Shopping Administrators role to the instruction set

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

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

3. Click on Members to confirm the listed 1E 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 the 1E Platform installation, or downloaded from the 1E Exchange. You can use the Exchange to search for suitable product packs, or submit requests for new instructions. You or your 1E administrator can also author your own instructions, as described in Writing 1E Instructions.

You can use the 1E 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 1E instructions to your users. See 1E Instruction applications for more details.

Enabling the 1E Platform integration after Shopping installation or upgrade

If you installed or upgraded to Shopping without enabling the 1E Platform integration, you must perform the following:

• Create a 1E consumer.

• Create a 1E Shopping Administrators role.

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

• Set values in the Shopping console.

These steps are done automatically if you enable the 1E Platform integration while installing or upgrading to Shopping.

The same 1E user permissions are required for the user doing the configuration.

Create a 1E Shopping consumer

In the Settings application in the 1E Platform:

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.
   

Editing the 1E Shopping consumer workflow

The 1E 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 the 1E 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 1E

In the Settings application in the 1E Platform:

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 1E 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 Set values in the Shopping Console.
    

    

Upload a 1E 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 1E Product Pack deployment tool (in the 1E Platform download zip available from the 1E Support Portal)

3. In the 1E Platform, 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 1E 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 1E 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 1E. The account requires no privileges other than being defined as a 1E account and having the 1E Shopping Administrators role.

4. Set the Tachyon Base URL to the URL for your 1E 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.