TmxEmployee Interface

The interface is used to manage the 'Employee' tables in the database. It includes the following methods:

Employee table
Name	COM Type	DB Type	Description
EmployeeNumber	BSTR	A15	Uniquely identifies an employee
FirstName	BSTR	A30	Employee's first name
LastName	BSTR	A30	Employee's last name
StoreNumber	SHORT	Smallint	Number of current store
Address	BSTR	A50	Street, street number and suite/ apartment number
City	BSTR	A20	City name
StateProvinceCode	BSTR	A2	State or province code
PhoneNumber	BSTR	A10	Phone number without mask
Social Insurance Number	Int	Integer	Social Insurance Number
ZipCode	BSTR	A10	Zip or postal code
EmployeeDiscount	Int	Integer	Discount rate
SalesPersonId	Int	Integer	Identify each salesperson
CommissionRate	VARIANT	Numeric (4,2)	Commission rate
PriceLevel	SHORT	Smallint	Identify price level for discount
EmployeeType	SHORT	Smallint	Employee type
EmployeeStatus	SHORT	Smallint	Further classify employee
CashierNumber	Int	Integer	Identify cashier
Password	BSTR	A20	Password for the employee
AuthorizationLevel	SHORT	Smallint	Authority level for security
ForcePreset	BOOL	A1	Indicate whether or not a preset price can be modified at POS at the time of sale
RegionNumber	SHORT	Smallint	Sales region ID
ClockedIn	BOOL	A1	Whether an employee is clocked in or clocked out
ClockInReason	Int	Int	Define the reason given for the last clock in/ out
ClockInDateTime	DT	TimeStamp	Actual time employee last clocked in/ out
LoggedOn	BOOL	A1	Define whether the employee is logged on as a cashier
NewPasswordRequired	BOOL	A1	Define whether or not the employee must change their password
LoggedOnRegisterNumber	SHORT	Smallint	Indicate the POS terminal the cashier is logged onto.
LoggedOnDrawNumber	SHORT	Smallint	Indicate the drawer number to use for the employee at the POS terminal the cashier is logged onto.
ModificationTime	DT	Timestamp	Date and time the row last modified.
EmployeeShortName	BSTR	A12	Employee short name
SchedulingMode	SHORT	Smallint
Salary	VARIANT	Numeric (20,6)	Employee salary
HourlyPayRate	VARIANT	Numeric (20,6)	Hourly paid rate
EmployeeProfileID	SHORT	Smallint	Identify profile ID

Method

HRESULT Inquiry (BSTR bstrXmlEmpInq, BSTR *bstrXmlEmpInqResult)

This method is used to retrieve records from 'Employee' table. In order to perform proper operations, these mandatory parameters have to be defined. The record found can be none, one or more than one based on the searching criteria. These mandatory parameters have to be defined when calling the function, others can be empty string. If the user prefers to find employee whose last name starting with letter D, the LastName is defined as D* so the search is based on the query like rather than equal to operator. EmployeeNumber is defined in the same way. This provides flexibility to the user to perform database operations that are required.

Since not all employees have the authority to perform inquiry, so 'cashier number', 'password' and 'store number' are required in order to check employee security ID. Certain employees may be allowed to perform an inquiry while others are allowed to perform full operations such as inquiry and update.

After the method is called, the return value has to be checked. If it is S_OK, the return string contains the data for the found record. If more than one record is found in the query, all of them can be parsed into the response string and it is up to the client how to use these data properly.

If there is no record found in the database, the result is defined as S_FALSE and the return string includes a message such as TmxEmployee Error: No Record Found in the Database!. If the cashier does not have the authority to perform Inquiry, E_INVALIDAUTHORITY is returned and the error message is defined as TmxEmployee Error: Invalid Security for Inquiry!.

If there is a communication error, E_COMMUNICATIONERROR is returned and the error message is defined as TmxEmployee Error: Communication Error!.

Parameters
BSTR bstrXmlEmpInq	String containing XML document, including storeNumber, employeeNumber, firstName, lastName, cashierNumber, password and cashierStoreNumber based on the defined data dictionary.
BSTR bstrXmlEmpInqResult	In contains the detail data for the found records or a particular error if the inquiry failed.

Return
S_OK	If the record is successfully returned from the database.
S_FALSE	If no record is found during inquiry.
E_COMMUNICATIONERROR	If there is a communication error.
E_INVALIDAUTHORITY	If the employee does not have authority to inquiry 'Employee' table.
E_FAIL	If other error occurs during Inquiry.

Method

HRESULT Update(BSTR bstrXmlEmpUpdate, BSTR *bstrXmlEmpUpdateResult)

BSTR bstrXmlEmpUpdate	String containing all columns defined in 'Employee' table plus one more element to indicate the operation to Update. It includes: EmployeeDelete – Delete an employee record EmployeeDeleteAll – Delete all employee records EmployeeAdd – Add an employee record EmployeeModify – Modify an employee record
BSTR bstrXmlEmpUpdateResult	It contains two optional elements. If the result is S_OK, it includes how many records are updated. Otherwise, it returns some error messages.

Return
S_OK	If the record is successfully returned from the database.
S_FALSE	If employee is not found in the database.
E_COMMUNICATIONERROR	If there is a communication error.
E_INVALIDAUTHORITY	If the employee does not have authority to inquiry 'Employee' table.
E_FAIL	If other error occurs during Update.

This method is used to update an 'Employee' record based on the UpdateType element. Use the Inquiry method to retrieve the record first and change certain fields. Then call this method. The fields passed to the stored procedure have to be checked to make sure that the value passed to the stored procedure is in the right data type format. If an error happens, the record is not updated. This can be done by both XML schema validation.

If the employee who performs the update operation does not have the authority to update 'Employee' table, E_INVALIDAUTHORITY is returned.

EmployeeAdd and EmployeeModify require that the following elements are defined:

1	storeNumber	Mandatory (M)
2	employeeNumber	M
3	type	M
4	status	M
5	firstName	M
6	lastName	M
7	address1	NULL if not setup
8	city	NULL if not setup
9	stateProvinceCode	NULL if not setup
10	zipCode	NULL if not setup
11	phoneNumber1	NULL if not setup
12	socialInsuranceNumber	M
13	cashierNumber	0 if not set
14	authorizationLevel	1 if not set
15	password	M
16	salesPersonID	M
17	commissionRate	NULL if not set
18	priceLevel	1 if not set
19	forcePreset	NULL if not set
20	employeeDiscount	NULL if not set
21	shortName	NULL if not set
22	schedulingMode	NULL if not set
23	salary	NULL if not set
24	hourlyPayRate	NULL if not set
25	employeeProfileID	NULL if not set

EmployeeDelete requires that the following elements be defined:

1	storeNumber	Mandatory (M)
2	employeeNumber	(M)
3	firstName	(M)
4	lastName	(M)

Note Note

EmployeeDeleteAll deletes all employee records in the 'Employee' table.

End of the note.

Method

HRESULT InquirySecurity (BSTR bstrXmlEmpInqSecurity, BSTR *)

This method is used to retrieve the security level for the entered employee . After the method is called, the AuthorizationLevel is included in the output string if the result is S_OK. The authorization level controls what functions the employee can perform and what functions they cannot.

If no record is found, S_FALSE is returned.

Parameters
BSTR bstrXmlEmpInqSecurity	String containing XML document, including storeNumber, cashierNumber, password and cashierStoreNumber, based on the defined data dictionary (a separate document).
BSTR bstrXmlEmpInqSecurityResult	It contains two optional elements. If the result is S_OK, it includes the authority level. Otherwise, it returns some error messages.

Return
S_OK	If the record is successfully returned from the database.
S_FALSE	If there is no record found.
E_COMMUNICATIONERROR	If there is a communication error.
E_FAIL	If other error occurs during inquiry.

XML Format

Currently several schema have been defined for each of these methods. They are:

schema_Triversity_employee_inquiry_request_1
schema_Triversity_employee_inquiry_response_1
schema_Triversity_employee_update_request_1
schema_Triversity_employee_inquiry_response_1
schema_Triversity_employee_security_inquiry_request_1
schema_Triversity_employee_security_inquiry_response_1

One schema example for Employee Inquiry can be defined as:

<?xml version= "1.0" ?>

<Schema name = "schema_Triversity_employee_inquiry_request_1" xmlns="urn:schemas-microsoft-com:xml-data" xmlns:dt="urn:schema-microsoft-com:datatypes" xmlns:trvdic="urn:trv_dictionary_0.xml">

<ElementType name="EMPLOYEE_INQUIRY_REQUEST" order="seq" content="eltOnly">

<element type="trvdic:storeNumber" minOccurs="1" maxOccurs="1" />

<element type="trvdic:cashierNumber" minOccurs="1" maxOccurs="1" />

<element type="trvdic:password" minOccurs="1" maxOccurs="1" />

<element type="trvdic:cashierStoreNumber" minOccurs="1" maxOccurs="1" />

<element type="trvdic:employeeNumber" minOccurs="0" maxOccurs="1" />

<element type="trvdic:firstName" minOccurs="0" maxOccurs="1" />

<element type="trvdic:lastName" minOccurs="0" maxOccurs="1" />

</ElementType>

</Schema>