Web Service Interface to Macromatix

To access the Web Service, the following url is used:

http:\\www.preceda.com.au/cgi-bin/precedawebservice

The following parameters are standard and required for all web service access:

USER	System user name.
PASSWORD	The user's System password
DATABASE	The name of the database to be accessed for data retrieval
SERVICE	The name of the web service to be activated.

 

USER, PASSWORD and DATABASE

The USER PASSWORD and DATABASE are used to validate access to download data. Only users that are given access to perform requests within the database will be allowed access. An error will be returned if the user does not have access to perform the request

SERVICE

This parameter should be set to "QSR_MACROMATIX" when performing an extract.

EXTRACT

The EXTRACT parameter is used to determine the type of extract being performed. This value ban be one of the following:

• EMP_CHANGES - used to retrieve changed employee records
• EMPLOYEE - used to retrieve a single employee record

LASTMODIFIED

If the LASTMODIFIED parameter is passed, the data will only be returned if changes have been made after the date/time specified. If there have been no changes, no data will be returned and the status code set to indicate this. If the LASTMODIFIED parameter is omitted or is not a valid date/time, all records will be returned.

For the EMP_CHANGES extract, only employees changed since the LASTMODIFIED date/time parameter will be returned. If the LASTMODIFIED parameter is not sent, all of the employees listed in the log file will be returned.

NOTE: The LASTMODIFED date is in GMT (Greenwich Mean Time) so that a standard date/time will be used (meaning that different Time Zones will not cause confusion).

MAXSIZE

The MAXSIZE parameter, if passed, is used to limit the amount of data returned by the web service. The value is given as a maximum number of bytes to return. If there is more data available in the file than the MAXBYTES parameter, data up to the maximum bytes will be returned and the status code will be set to 206 (Partial Content).

The number of bytes returned will not be exactly the number indicated by the MAXSIZE parameter. If multiple employee changes are made in the same second, all changes for that second are returned. Also, if the MAXSIZE value is reached, the entire record currently being retrieved will be returned (i.e. not just "part" of the record). This is to ensure that records are not lost. This may result in more data being returned than is requested.

EMPLOYEENUM and EMPLOYEEVER

These parameters will only be used when the extract type is EMPLOYEE. In this case only a single employee record will be returned matching employee number and version requested.

If the requested employee record cannot be found, a status of 404 - Not found will be returned.

When requesting a single employee, the Last-Modified date/time will not be returned.

Example of a Request:

POST /CGI-BIN/PRECEDAWEBSERVICE HTTP/1.1

Accept: */*

Accept-Language: en-au

Referer: http://dev3:91/accelerator/d30/logonWindow.zhtml

Content-Type: application/x-www-form-urlencoded

Accept-Encoding: gzip, deflate

User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)

Host: dev3:91

Content-Length: 101

Connection: Keep-Alive

Cache-Control: no-cache

 

USER=CRAIGB&PASSWORD=SECRET&DATABASE=PAY1XXXF80&&SERVICE=QSR_MACROMATIX=EMP_CHANGES&LASTMODIFIED=Thu, 26 Mar 2009 21:56:48

Format of Response

The response will be formatted using the standard http protocol. The response consists of one or more lines of header information followed by the .csv file in the response body.

The status will be one of the standard http status codes (e.g., 200 for success, 304 Not modified etc).

In the case of an error, the status code will be in the range 400 - 599 and an error message will be returned in the response body.

If the request is successful (ie status code = 200), the response header will contain a Last-Modified field. This field will contain the date/time of the most recent change in Preceda. This value should be used as the LASTMODIFIED parameter on the next request for the same extract type.

When data is returned the header field, Record-Count, will be set to the number of records returned. This header field will be set for both a return of all data (status code 200) and for a partial return of data (status code 206).

Example of a successful response:

HTTP/1.1 200

Date: Thu, 26 Mar 2009 23:50:14 GMT

Server: Apache

Content-Length: 210

Last-Modified: Thu, 26 Mar 2009 21:56:48

Record-Count: 2

Keep-Alive: timeout=300, max=482

Connection: Keep-Alive

Content-Type: text/html; charset=ISO-8859-1

"Column 1", "Column 2"

"Value 1", "Value 2"

"Value 3", "Value 4"

 

Example of a response when no data has changed:

HTTP/1.1 304 Not Modified

Date: Thu, 26 Mar 2009 23:50:14 GMT

Server: Apache

Connection: Keep-Alive

Keep-Alive: timeout=300, max=498

 

Example of an error:

HTTP/1.1 403 Forbidden

Date: Thu, 26 Mar 2009 23:50:14 GMT

Server: Apache

Content-Length: 223

Keep-Alive: timeout=300, max=500

Connection: Keep-Alive

Content-Type: text/html; charset=ISO-8859-1

 

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">

<HTML><HEAD>

<TITLE>403 Forbidden</TITLE>

</HEAD><BODY>

<H1>No Access</H1>

<P>The User, "CRAIGB", does not have access to the database "PAY1XXXF80".</P>

</BODY></HTML>

 

A CHGEMP.csv file is created in Preceda to track changes to employee data. The file contains the following fields:

Field	Type	Description
CHANGE_DATE	Date	Date of the change
CHANGE_TIME	Time	Time of the change
EMP_NUM	7 Alpha characters	Employee that has changed
VERSION	1 Alpha character	Employee version

 

Whenever a change is made to any of the employee data in PAYMST or PEMPMISC, a record will be written to the CHGEMP.csv file. This also occurs when a new employee is hired.

When the web service extracts employee changes, it will use the employee number and version in the above file to determine which employees have changed. If a last modified date is passed as a parameter, only records with a greater change date/time will be exported.

The data for the .csv file will be exported from the PAYMST and PEMPMISC files for the appropriate employees.

Where the same employee is listed twice in the file, only a single record will be returned in the .csv file.

The Last-Modified field in the response will be set to the change date/time of the last record processed from the file.

In Preceda, multiple versions (records) may be kept for the same employee. This will happen in the case were an employee is rehired. The current employee record will always have a value of blank in the version field.

 

In order to limit the number of records in the CHGEM.csv file, the Session Close program will delete old records from the file. The Session Close program runs whenever a user logs off of Preceda PEOPLE. The length of time data which is kept in the file will be determined by PREVAR variable *PP_CHGEM. This variable will store the number of days to keep data for. A value of zero will indicate that data is not deleted.

Maint	Position	Position Description	Options/Value
	2-5	Set the default number of days to keep records in the CHGEMP field	0015 being the default number of days to keep records A value of 000 days will stop any records from being deleted.

 

If the web service is unavailable for a period, a status code of 503 (Service Unavailable) will be returned. An example of when this may happen is during a complete backup run prior to a payrun.

The same method will be used to determine the availability of the web service as is used for the Preceda application.

This is not the same as the web service not being unavailable due to technical problems.

 

File	Description	Preceda Field
Employee Number	Employee Number from Macromatix	AEMPNO - Employee Number
Store Number	As per the Store Number in Macromatix	ALVL4 - Level 4 Code
Title	Mr, Ms. Dr, Mrs In the case of Miss this will be converted to MS, all other titles default to Mr	ATITLE - Title
First Name	Employees First Name	AFNAME - First Name
Middle Name	Employee Middle Name	AMNAME - Middle Name
Last Name	Employee Last Name	ASNAME - Surname
Date of Birth	Date format yyyy/mm/dd	ABRDAT - Date of Birth
Date Hired	Date format yyyy/mm/dd	AHRDATE - Hire Date
Address 1	Street Address Line1	AADDR - Address Line 1
Address 2	Street Address Line2	ACITY - Address Line 2
City	City	AADDR3 - Address Line 3
Post Code	Postcode	APOST - Post Code
Country	Defaults to Australia, unless otherwise specified	AUSTRALIA
Primary Job	Must match an existing Job Name in Macromatix e.g. 101 - Manager. 301 / 312 - Kitchenhand, 501 / 512 - Cashier	ALVL5 - Level 5 Code Description
Primary Pay Rate	Per Hour Rate. If the rate does not exist in Preceda, the Salary amount will be converted into an hourly rate.	APR1 - Base Rate
Employee Type	C - Casual, T - Part Time, P - Permanent	AEMPT - Employment Type
Status	A - Active, T - Terminated, R - Reinstate	ASTC - Status
POS ID	Id Number as per the Point of Sale, this is usually the Employee Number	AEMPNO - Employee Number
Brand	First two characters in ALVL4 e.g. ALVL4 = rr5046, then output rr or ALVL4 = bb60891, then output bb	ALVL4
Employee Contracted Hours	The value is derived from the NCTLBH Reference Table	Employee's Base Hours