Inbound Integration Guide - Users and Employees

Description

This How-to guide explains the integration of following configuration data entities.

• User Role
• User
• Employee
• Employee Balance

Notes

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

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

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.

Employee identify employees who can make purchases.

EmployeeAccountBalance is an account to track employee purchase amounts.

Role

A user role grant 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 many not affect visibility of options (depends on specific privileges).

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 privileges to grant for the role
id	privileges	Element	the specific privilege to grant	String

User

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

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
dateTime Activated	user	Element	The first date/time this user can access the system	Date Time
dateTime Deactivated	user	Element	The last date/time this user can access the system	Date Time
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
maintenance InactivityDelay	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	Locale String
locationId	user	Element	The location to which this user is assigned	String
password	user	Element	The encrypted password for this user	String
password ExpiryTime	user	Element	The number of days before user must change password. 0 means unlimited	Integer	3
passwordLast Changed	user	Element	Date/Time when password was late updated	Date Time
preventPassword SimilarToUserId	user	Element	if true, do not allow password similar to user id if omitted, false	Boolean
forceChange Password	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
forceAlphNumeric Password	user	Element	if true, user must have alpha and numeric characters in password if omitted, false	Boolean
forceMixedCase Password	user	Element	if true, user password must contain upper and lower case characters if omitted, false	Boolean
preventPassword ReUse	user	Element	if true, user cannot reuse a previous password if omitted, false	Boolean
minimumPassword Length	user	Element	if omitted, no minimum	Integer	2
maximumPassword Length	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
disallowMulti LocationSignOn	user	Element	if true, restrict user to assigned location and do not allow user to sign on at multiple locations if omitted, false	Boolean
cardSign OnOnly	user	Element	if true, user must use card to sign in if omitted, false	Boolean
skipPassword IfCard	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
preferred Authentication Method	user	Element	The preferred authentication method for the user; One of the following fixed values: INTERNAL, AD if omitted, INTERNAL	fixed
singleSignOn UserId	user	Element	user's single sign on id	String
singleSignOn CommonName	user	Element	user's single sign on name	String
disallowLocking MultiplePos	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 name	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	time Period
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	Date Time

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	Add'l phone number	String
postCode	address	Element	Postal code	String
street1	address	Element	Street address	String
street2	address	Element	Add'l street address	String
street3	address	Element	Add'l 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 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	employee Name
address	employee	Element	see address	address
employeeDiscount	employee	Element	Decimal percentage of base discount; e.g. 20% = 0.2	Float
employeeAllowance Discount	employee	Element	Decimal percentage of premium discount until Employee Discount Allowance expires; e.g. 20% = 0.2	Float
employeeDiscount Allowance	employee	Element	The value of discount allowance, either discount value or total spending, the employee may accumulate over the reset period	Integer
normalWorking LocationId	employee	Element	The location id to which the associate is normally assigned	String
automaticEmployee Sale	employee	Element	if true, any sale performed by 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	Date Time

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 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
employeeDiscount BalanceAccount		Root	Outer wrapper for the entity	String
accountId	employeeDiscount BalanceAccount	Element	The unique account id	String
accountType	employeeDiscount BalanceAccount	Element	Fixed: employeeDiscountBalanceAccount	fixed
currencyId	employeeDiscount BalanceAccount	Element	The currency type for this account	String
status	employeeDiscount BalanceAccount	Element	The account status. One of the following fixed values: NEW, ACTIVE, CLOSED, SUSPENDED	fixed
accountOpened Date	employeeDiscount BalanceAccount	Element	The date the account was opened	Date Time

employeeCreditAccount

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

Role Delete

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	entityDelete Request	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 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	entityDelete Request	Element	The user id to delete	String
type	entityKey	Attribute	Fixed:UserKey	fixed

Employee Delete

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	entityDelete Request	Element	The employee id to delete	String
type	entityKey	Attribute	Fixed:EmployeeKey	fixed

Employee Account Delete

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	entityDelete Request	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