Inbound Integration Guide - Users and Employees

Description

This guide explains the integration of the following configuration data entities:

• User Role
• User
• Employee
• Employee Balance

---

Notes

note

This guide does not cover all possible integration topics. Please see the Enactor Books for detailed information.

note

See the Inbound Integration Guide - Introduction for the basics of importing and exporting data.

note

This guide will use manual import and export of data using the Enactor Estate Manager.

---

Overview

User Roles define user permissions through privileges.

Users are people with specific user roles who will access the system.

Employees identify employees who can make purchases.

EmployeeAccountBalance is an account to track employee purchase amounts.

---

Role

A user role grants specific privileges to accomplish actions. Enabling a user for a specific role grants the user all of the permissions/privileges associated with that role. Multiple user roles may be enabled for a user.

A mandatory element of the user role is the Authorisation Level for each configured role. The Authorisation Level is an arbitrary numeric value from 0 to 100 which is used to rank the different user roles.

• In configuration/administration using the Estate Manager user interface, a user can only modify and allocate roles of an authorisation level less than or equal to the highest authorisation level of all roles assigned to them.

• In menu selection, if multiple roles are assigned, the role with the highest authorisation level will be applied and will determine what options the user sees. This does not affect the user's available permissions, which may or may not affect visibility of options (depends on specific privileges).

XML Example

XML Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Batch xmlns:core="http://www.enactor.com/core"
    xmlns:retail="http://www.enactor.com/retail">
    <retail:role>
        <retail:roleId>SALESASSIST_UK</retail:roleId>
        <retail:description>Sales Assistant  - UK</retail:description>
        <retail:authorisationLevel>20</retail:authorisationLevel>
        <retail:regionId groupHierarchyId="All" groupTypeId="region">UK</retail:regionId>
        <retail:privileges>
            <retail:id>enactor.pos.AuthorisesEmployeeAccountTender</retail:id>
        </retail:privileges>
        <retail:privileges>
            <retail:id>enactor.pos.DeliveryChargeOverrideAllowed</retail:id>
        </retail:privileges>
    </retail:role>
</Batch>

XML Structure

XML Tag	Parent Element	Type	Description	Data Type	Length
role		Root	Outer wrapper for the entity	String
roleId	role	Element	The unique id for the role	String
description	role	Element	The description for the role	String
authorisationLevel	role	Element	A numeric value used to rank roles	Integer
regionId	role	Element	The region for the role (see groupId)	groupId
privileges	role	Element	A specific privilege to grant for the role
id	privileges	Element	The specific privilege to grant	String

---

User

Users define the user accounts that control which staff can use the system. Users are granted permissions through User Roles. Users also capture information about the staff members that is required for system access.

XML Example

XML Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Batch xmlns:core="http://www.enactor.com/core"
    xmlns:retail="http://www.enactor.com/retail">

    <retail:user>
        <retail:dateTimeActivated>2016-07-13T16:09:43+01:00</retail:dateTimeActivated>
        <retail:displayName>Angela Beige</retail:displayName>
        <retail:employeeId></retail:employeeId>
        <retail:inactivityDelay>0</retail:inactivityDelay>
        <retail:maintenanceInactivityDelay>0</retail:maintenanceInactivityDelay>
        <retail:localeId variant="" country="GB">en</retail:localeId>
        <retail:locationId>0100</retail:locationId>
        <retail:password>qQ7x8zKsY25qx8fM0Q7FL04SdWraV8poxs6oFYuH8UY=YVJxp4j7rUI=</retail:password>
        <retail:passwordExpiryTime>0</retail:passwordExpiryTime>
        <retail:passwordLastChanged>2016-07-13T16:10:29.638+01:00</retail:passwordLastChanged>
        <retail:forceChangePassword>false</retail:forceChangePassword>
        <retail:strongPassword>false</retail:strongPassword>
        <retail:forceAlphaNumericPassword>false</retail:forceAlphaNumericPassword>
        <retail:forceMixedCasePassword>false</retail:forceMixedCasePassword>
        <retail:preventPasswordReUse>false</retail:preventPasswordReUse>
        <retail:minimumPasswordLength>1</retail:minimumPasswordLength>
        <retail:maximumPasswordLength>20</retail:maximumPasswordLength>
        <retail:userId>3100</retail:userId>
        <retail:isTemplate>false</retail:isTemplate>
        <retail:emailAccountName></retail:emailAccountName>
        <retail:emailAddress></retail:emailAddress>
        <retail:emailPassword></retail:emailPassword>

        <retail:userName>
            <retail:surname>Angela</retail:surname>
            <retail:forename>Beige</retail:forename>
            <retail:title>Mrs</retail:title>
        </retail:userName>

        <retail:roleId>
            <retail:roleId>GIFTCARD_UK</retail:roleId>
            <retail:regionId groupHierarchyId="All" groupTypeId="region">UK</retail:regionId>
        </retail:roleId>
        <retail:roleId>
            <retail:roleId>ASSISTMANAGER_UK</retail:roleId>
            <retail:regionId groupHierarchyId="All" groupTypeId="region">UK</retail:regionId>
        </retail:roleId>

        <retail:address>
            <retail:countryCodeId></retail:countryCodeId>
            <retail:typeId></retail:typeId>
            <retail:isTemplate>false</retail:isTemplate>
        </retail:address>
        <retail:timePeriod>
            <core:dayOfWeek>1</core:dayOfWeek>
        </retail:timePeriod>
        <retail:timePeriod>
            <core:dayOfWeek>2</core:dayOfWeek>
        </retail:timePeriod>
        <retail:timePeriod>
            <core:dayOfWeek>3</core:dayOfWeek>
        </retail:timePeriod>
        <retail:timePeriod>
            <core:dayOfWeek>4</core:dayOfWeek>
        </retail:timePeriod>
        <retail:timePeriod>
            <core:dayOfWeek>5</core:dayOfWeek>
        </retail:timePeriod>
        <retail:timePeriod>
            <core:dayOfWeek>6</core:dayOfWeek>
        </retail:timePeriod>
        <retail:timePeriod>
            <core:dayOfWeek>7</core:dayOfWeek>
        </retail:timePeriod>

    </retail:user>
</Batch>

XML Structure

user

XML Tag	Parent Element	Type	Description	Data Type	Length
user		Root	Outer wrapper for the entity	String
userId	user	Element	The unique id for this user	String
dateTimeActivated	user	Element	The first date/time this user can access the system	DateTime
dateTimeDeactivated	user	Element	The last date/time this user can access the system	DateTime
displayName	user	Element	The name to display for this user	String
employeeId	user	Element	The employee id for this user for employee transactions	String
inactivityDelay	user	Element	The number of seconds until the user is logged off the POS when inactive. 0 means unlimited	Integer	5
maintenanceInactivityDelay	user	Element	The number of seconds until the user is logged off the Estate Manager when inactive. 0 means unlimited	Integer	5
localeId	user	Element	Locale to use for this user	LocaleString
locationId	user	Element	The location to which this user is assigned	String
password	user	Element	The encrypted password for this user	String
passwordExpiryTime	user	Element	The number of days before user must change password. 0 means unlimited	Integer	3
passwordLastChanged	user	Element	Date/Time when password was last updated	DateTime
preventPasswordSimilarToUserId	user	Element	If true, do not allow password similar to user id. If omitted, false	Boolean
forceChangePassword	user	Element	If true, user must change password on next successful login. If omitted, false	Boolean
strongPassword	user	Element	If true, password must pass strong password rules. If omitted, false	Boolean
forceAlphaNumericPassword	user	Element	If true, user must have alpha and numeric characters in password. If omitted, false	Boolean
forceMixedCasePassword	user	Element	If true, user password must contain upper and lower case characters. If omitted, false	Boolean
preventPasswordReUse	user	Element	If true, user cannot reuse a previous password. If omitted, false	Boolean
minimumPasswordLength	user	Element	If omitted, no minimum	Integer	2
maximumPasswordLength	user	Element	If omitted, no maximum	Integer	2
disabled	user	Element	If true, user is not enabled and cannot access the system. If omitted, false	Boolean
disallowMultiLocationSignOn	user	Element	If true, restrict user to assigned location and do not allow user to sign on at multiple locations. If omitted, false	Boolean
cardSignOnOnly	user	Element	If true, user must use card to sign in. If omitted, false	Boolean
skipPasswordIfCard	user	Element	If true, if card is used, do not require a password. If omitted, false	Boolean
trainingMode	user	Element	If true, user is restricted to training mode only. If omitted, false	Boolean
leftHanded	user	Element	If true, identify user as left handed for some themes which use this information. If omitted, false	Boolean
shortId	user	Element	The short id number for the user	String
preferredAuthenticationMethod	user	Element	The preferred authentication method for the user. One of the following fixed values: INTERNAL, AD. If omitted, INTERNAL	fixed
singleSignOnUserId	user	Element	User's single sign on id	String
singleSignOnCommonName	user	Element	User's single sign on name	String
disallowLockingMultiplePos	user	Element	If true, do not allow user to lock multiple POS terminals. If omitted, false	Boolean
userName	user	Element	The user name details. See userName	name
roleId	user	Element	One or more roles assigned to the user. See roleId	roleId
address	user	Element	Address information for the user. See address	address
timePeriod	user	Element	Days the user is allowed to log in. See timePeriod	timePeriod
isTemplate	user	Element	If true, user is a template. If omitted, false	Boolean

userName

XML Tag	Parent Element	Type	Description	Data Type	Length
userName		Root	Outer wrapper for the entity	String
surname	userName	Element	User surname	String
forename	userName	Element	User forename	String
title	userName	Element	User title	String
initials	userName	Element	User initials	String
sex	userName	Element	User sex	String
dateOfBirth	userName	Element	User date of birth	DateTime

roleId

XML Tag	Parent Element	Type	Description	Data Type	Length
roleId		Root	Outer wrapper for the entity	String
roleId	roleId	Element	The role to assign the user	String
regionId	roleId	Element	The region for this role. (See groupId)	groupId

address

XML Tag	Parent Element	Type	Description	Data Type	Length
address		Root	Outer wrapper for the entity	String
countryCodeId	address	Element	Country code	String
organisation	address	Element	Organisation name	String
county	address	Element	County	String
email	address	Element	Email address	String
mobilePhone	address	Element	Mobile phone number	String
phone1	address	Element	Phone number	String
phone2	address	Element	Additional phone number	String
postCode	address	Element	Postal code	String
street1	address	Element	Street address	String
street2	address	Element	Additional street address	String
street3	address	Element	Additional street address	String
town	address	Element	Town/City	String
isTemplate	address	Element	If true, address is a template. If omitted, false	Boolean

timePeriod

XML Tag	Parent Element	Type	Description	Data Type	Length
timePeriod		Root	Outer wrapper for the entity	String
dayOfWeek	timePeriod	Element	The day of the week the user is allowed to access the system	Integer
startTime	timePeriod	Element	The time of day before which the user cannot access the system
hour	startTime	Attribute	The start hour	Integer
minute	startTime	Attribute	The start minute	Integer
second	startTime	Attribute	The start second	Integer
endTime	timePeriod	Element	The time of day after which the user cannot access the system
hour	endTime	Attribute	The end hour	Integer
minute	endTime	Attribute	The end minute	Integer
second	endTime	Attribute	The end second	Integer

---

Employee

XML Example

XML Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Batch xmlns:core="http://www.enactor.com/core"
    xmlns:retail="http://www.enactor.com/retail">

    <retail:employee>
        <retail:employeeId>1</retail:employeeId>
        <retail:employeeName>
            <retail:surname>Granger</retail:surname>
            <retail:forename>Sam</retail:forename>
            <retail:initials>S</retail:initials>
            <retail:title>Mr</retail:title>
            <retail:sex>MALE</retail:sex>
            <retail:dateOfBirth>1964-08-17T00:00:00+01:00</retail:dateOfBirth>
        </retail:employeeName>
        <retail:address>
            <retail:countryCodeId></retail:countryCodeId>
            <retail:typeId></retail:typeId>
            <retail:isTemplate>false</retail:isTemplate>
        </retail:address>
        <retail:employeeDiscount>0.2</retail:employeeDiscount>
        <retail:employeeAllowanceDiscount>0.2</retail:employeeAllowanceDiscount>
        <retail:employeeDiscountAllowance>0</retail:employeeDiscountAllowance>
        <retail:normalWorkingLocationId>0001</retail:normalWorkingLocationId>
        <retail:automaticEmployeeSale>false</retail:automaticEmployeeSale>

    </retail:employee>

</Batch>

XML Structure

employee

XML Tag	Parent Element	Type	Description	Data Type	Length
employee		Root	Outer wrapper for the entity	String
employeeId	employee	Element	The unique employee id	String
employeeName	employee	Element	See employeeName	employeeName
address	employee	Element	See address	address
employeeDiscount	employee	Element	Decimal percentage of base discount; e.g. 20% = 0.2	Float
employeeAllowanceDiscount	employee	Element	Decimal percentage of premium discount until Employee Discount Allowance expires; e.g. 20% = 0.2	Float
employeeDiscountAllowance	employee	Element	The value of discount allowance, either discount value or total spending, the employee may accumulate over the reset period	Integer
normalWorkingLocationId	employee	Element	The location id to which the associate is normally assigned	String
automaticEmployeeSale	employee	Element	If true, any sale performed at the POS by this employee will automatically be an employee sale	Boolean
imageUrl	employee	Element	A URL to an image for the employee	String
externalReference	employee	Element	An external reference	String

employeeName

XML Tag	Parent Element	Type	Description	Data Type	Length
employeeName		Root	Outer wrapper for the entity	String
surname	employeeName	Element	Surname	String
forename	employeeName	Element	Forename	String
title	employeeName	Element	Title	String
initials	employeeName	Element	Initials	String
sex	employeeName	Element	Sex	String
dateOfBirth	employeeName	Element	Date of birth	DateTime

---

Employee Account

There are 5 different types of employee accounts: Discount Balance, Discount Spend, Credit, Grade Discount Balance, and Grade Discount Spend.

This guide will cover Discount Balance and Credit which are the most common types. See the Enactor Books for more information.

XML Example

XML Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Batch xmlns:core="http://www.enactor.com/core"
    xmlns:retail="http://www.enactor.com/retail">

    <retail:employeeDiscountBalanceAccount>
        <retail:accountId>1</retail:accountId>
        <retail:accountType>employeeDiscountBalanceAccount</retail:accountType>
        <retail:currencyId>GBP</retail:currencyId>
        <retail:status>NEW</retail:status>
        <retail:accountOpenedDate>2014-08-22T00:00:00+01:00</retail:accountOpenedDate>
    </retail:employeeDiscountBalanceAccount>

    <retail:employeeCreditAccount>
        <retail:accountId>8</retail:accountId>
        <retail:accountType>employeeCreditAccount</retail:accountType>
        <retail:currencyId>GBP</retail:currencyId>
        <retail:status>ACTIVE</retail:status>
        <retail:accountOpenedDate>2016-06-22T00:00:00+01:00</retail:accountOpenedDate>
        <retail:accountCreditLimit>0</retail:accountCreditLimit>
    </retail:employeeCreditAccount>

</Batch>

XML Structure

employeeDiscountBalanceAccount

XML Tag	Parent Element	Type	Description	Data Type	Length
employeeDiscountBalanceAccount		Root	Outer wrapper for the entity	String
accountId	employeeDiscountBalanceAccount	Element	The unique account id	String
accountType	employeeDiscountBalanceAccount	Element	Fixed: employeeDiscountBalanceAccount	fixed
currencyId	employeeDiscountBalanceAccount	Element	The currency type for this account	String
status	employeeDiscountBalanceAccount	Element	The account status. One of the following fixed values: NEW, ACTIVE, CLOSED, SUSPENDED	fixed
accountOpenedDate	employeeDiscountBalanceAccount	Element	The date the account was opened	DateTime

employeeCreditAccount

XML Tag	Parent Element	Type	Description	Data Type	Length
employeeCreditAccount		Root	Outer wrapper for the entity	String
accountId	employeeCreditAccount	Element	The unique account id	String
accountType	employeeCreditAccount	Element	Fixed: employeeCreditAccount	fixed
currencyId	employeeCreditAccount	Element	The currency type for this account	String
status	employeeCreditAccount	Element	The account status. One of the following fixed values: NEW, ACTIVE, CLOSED, SUSPENDED	fixed
accountOpenedDate	employeeCreditAccount	Element	The date the account was opened	DateTime
accountCreditLimit	employeeCreditAccount	Element	The credit limit for the account. 0 means unlimited	Integer

---

Role Delete

XML Example

XML Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Batch xmlns:core="http://www.enactor.com/core"
    xmlns:retail="http://www.enactor.com/retail"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!--   RoleKey -->
    <core:entityDeleteRequest>
        <core:entityKey xsi:type="retail:RoleKey">
            <retail:roleId>roleId</retail:roleId>
            <retail:regionId variantGroupHierarchyId="variantGroupHierarchyId" variantGroupId="variantGroupId" variantGroupTypeId="variantGroupTypeId" groupHierarchyId="groupHierarchyId" groupTypeId="groupTypeId">groupId</retail:regionId>
        </core:entityKey>
    </core:entityDeleteRequest>
</Batch>

XML Structure

entityDeleteRequest

XML Tag	Parent Element	Type	Description	Data Type	Length
entityKey	entityDeleteRequest	Element		String
type	entityKey	Attribute	Fixed: RoleKey	fixed
roleId	entityKey	Element	The role id key to delete	String
regionId	entityKey	Element	The region id for this role	groupId

---

User Delete

XML Example

XML Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Batch xmlns:core="http://www.enactor.com/core"
    xmlns:retail="http://www.enactor.com/retail"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!--   UserKey -->
    <core:entityDeleteRequest>
        <core:entityKey xsi:type="retail:UserKey">USERID</core:entityKey>
    </core:entityDeleteRequest>
</Batch>

XML Structure

entityDeleteRequest

XML Tag	Parent Element	Type	Description	Data Type	Length
entityKey	entityDeleteRequest	Element	The user id to delete	String
type	entityKey	Attribute	Fixed: UserKey	fixed

---

Employee Delete

XML Example

XML Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Batch xmlns:core="http://www.enactor.com/core"
    xmlns:retail="http://www.enactor.com/retail"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!--   EmployeeKey -->
    <core:entityDeleteRequest>
        <core:entityKey xsi:type="retail:EmployeeKey">employeeId</core:entityKey>
    </core:entityDeleteRequest>
</Batch>

XML Structure

entityDeleteRequest

XML Tag	Parent Element	Type	Description	Data Type	Length
entityKey	entityDeleteRequest	Element	The employee id to delete	String
type	entityKey	Attribute	Fixed: EmployeeKey	fixed

---

Employee Account Delete

XML Example

XML Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Batch xmlns:core="http://www.enactor.com/core"
    xmlns:retail="http://www.enactor.com/retail"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!--   EmployeeAccountKey -->
    <core:entityDeleteRequest>
        <core:entityKey xsi:type="retail:EmployeeAccountKey" accountType="employeeAccountType">employeeAccountId</core:entityKey>
    </core:entityDeleteRequest>
</Batch>

XML Structure

entityDeleteRequest

XML Tag	Parent Element	Type	Description	Data Type	Length
entityKey	entityDeleteRequest	Element	The employee account id to delete	String
type	entityKey	Attribute	Fixed: EmployeeAccountKey	fixed
accountType	entityKey	Attribute	One of the following fixed values: employeeDiscountBalanceAccount, employeeCreditAccount	fixed

---