Wiki: WEB SERVICES

Web Services#

EMPLOYEE HIRE Inbound to Personality#

Purpose// This service receives information form an external system and loads the employee into Personality, as a new hire or rehire, populating all the pertinent data as noted.

Users can process one employee at a time through this service, since it is processed from a user interface action from the source system. The response back to the external system will be either an:

OK condition, providing the generated (or pre-existing) employee number PERSON_CODE, or
ERROR condition, with information provided to identify the type of error encountered

Input Data#

Name	Type	Mandatory *Only on new hire	Notes
PERSON_CODE	Character 16	No	If not provided, indicates a new hire, and a new employee is created with a new person code. If it is provided, indicates a re-hire and the employee is processed as a rehire, if they already exist. If they do not exist, an error is generated.
GOVERNMENT_CODE	Character 16	Yes	Formatted government code, with hyphens provided
FIRST_NAME	Character 50	Yes	Employee first name
LAST_NAME	Character 50	Yes	Employee last name
BIRTH_DATE	Date	Yes*	Date in YYYYMMDD format
GENDER	Character 2	Yes*	01 for Male; 02 for Female
ETHNIC	Character 4	Yes*	Value must be one of the values defined for Ethnic code
LANGUAGE_CODE	Character3	Yes*	Value must be one of the values defined for Language code
MIDDLE_NAME	Character 50	No	Employee middle name
ENTITY_CODE	Character 16	Yes	Name of entity employee is being hired into
EMPLOYMENT_TYPE	Character 2	Yes	Value must be one of the values defined for Employment type
HIRE_DATE	Date	Yes	Date in YYYYMMDD format
ORIGINAL_HIRE_DATE	Date	Yes*	Date in YYYYMMDD format
SENIORITY_DATE	Date	Yes*	Date in YYYYMMDD format
ASSIGNMENT_CODE	Character 16	Yes	Unique value for an employee. Recommend PRIMARY for new hires
ASSIGNMENT_TYPE	Character 2	Yes	Value must be one of the values defined for Assignment Type
ASSIGNMENT_STATUS	Character 2	Yes	Value must be one of the values defined for Assignment Status
ASSIGNMENT_START_DATE	Date	Yes	Date in YYYYMMDD format, and must not be earlier than the HIRE_DATE
POSITION_CODE	Character 16	Yes	The position that the employee is being (re)hired into. NOTE: The position code implies a number of fields will have values defaulted from the position definition.
EMPLOYMENT_STATUS	Character 16	Yes	Value must be one of the values that have been defined on the IDES form at the client’s site
FTE	Number	Yes	A value not exceeding 1.0 and greater than 0
WAGE_RATE	Number	No	Wage rate can be defined here, if overriding the value derived from the position definition
RATE_BASIS	Character 2	No	If the Wage Rate is defined, then Rate Basis is mandatory. Value must be one of the values defined for Rate Basis
EMAIL_ADDRESS_WORK	Character 50	No	Employee work email address
EMAIL_ADDRESS_HOME	Character 50	No	Employee home email address
ADDRESS_LINE_1	Character 50	No	Employee home address, line 1
ADDRESS_LINE_2	Character 50	No	Employee home address, line 2
LOCALITY	Character 50	No	Employee home city/town
ZIP_POSTAL	Character 16	No	Employee home zip code/postal code
STATE_PROV_CODE	Character 2	Yes*	Employee home address State/Province
PHONE_NUMBER	Character 20	No	Employee home phone number, formatted (AAA) EEE_NNNN
DEPOSIT1_BANK_LOCATION	Character 16	No	The bank transit code for the direct deposit
DEPOSIT1_BANK_ACCOUNT	Character 30	No	The bank account for direct deposit. When the DEPOSIT1_BANK_LOCATION is defined, then this field is mandatory.
DEPOSIT1_AMOUNT	Number	No	The dollar amount to be deposited into this account each pay. One of DEPOSIT1_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be provided if DEPOSIT1_BANK_LOCATION is defined.
DEPOSIT1_NET_PAY_PERCENT	Number	No	The percentage of net pay to be deposited into this account each pay. One of DEPOSIT1_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be provided if DEPOSIT1_BANK_LOCATION is defined.
DEPOSIT1_PAY_REMAINING	Character 1	No	If any amount is left to be paid into this account, indicate this with a “1” in this field. One of DEPOSIT1_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be provided if DEPOSIT1_BANK_LOCATION is defined.
DEPOSIT2_BANK_LOCATION	Character 16	No	The bank transit code for the direct deposit
DEPOSIT2_BANK_ACCOUNT	Character 30	No	The bank account for direct deposit. When the DEPOSIT1_BANK_LOCATION is defined, then this field is mandatory.
DEPOSIT2_AMOUNT	Number	No	The dollar amount to be deposited into this account each pay. One of DEPOSIT1_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be provided if DEPOSIT1_BANK_LOCATION is defined.
DEPOSIT2_NET_PAY_PERCENT	Number	No	The percentage of net pay to be deposited into this account each pay. One of DEPOSIT1_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be provided if DEPOSIT1_BANK_LOCATION is defined.
DEPOSIT2_PAY_REMAINING	Character 1	No	If any amount is left to be paid into this account, indicate this with a “1” in this field. One of DEPOSIT1_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be provided if DEPOSIT1_BANK_LOCATION is defined.
CONTACT1_FIRST_NAME	Character 50	No	The first name of the first emergency contact
CONTACT1_LAST_NAME	Character 50	No	The last name of the first emergency contact. If CONTACT1 information is defined, then both First and Last Name must be defined.
CONTACT1_ADDRESS_LINE_1	Character 50	No	The home address of the first emergency contact, line 1
CONTACT1_ADDRESS_LINE_2	Character 50	No	The home address of the first emergency contact, line 2
CONTACT1_LOCALITY	Character 50	No	The home city/town of the first emergency contact
CONTACT1_ZIP_POSTAL	Character 16	No	The home zip code/postal code of the first emergency contact
CONTACT1_PHONE_NUMBER	Character 20	Yes	The home phone number of the first emergency contact, formatted (AAA) EEE_NNNN
CONTACT1_EMAIL_ADDRESS	Character 100	No	The email address of the first emergency contact
CONTACT2_FIRST_NAME	Character 50	No	The first name of the second emergency contact
CONTACT2_LAST_NAME	Character 50	No	The last name of the second emergency contact. If CONTACT1 information is defined, then both First and Last Name must be defined.
CONTACT2_ADDRESS_LINE_1	Character 50	No	The home address of the second emergency contact, line 1
CONTACT2_ADDRESS_LINE_2	Character 50	No	The home address of the second emergency contact, line 2
CONTACT2_LOCALITY	Character 50	No	The home city/town of the second emergency contact
CONTACT2_ZIP_POSTAL	Character 16	No	The home zip code/postal code of the second emergency contact
CONTACT2_PHONE_NUMBER	Character 20	Yes	The home phone number of the second emergency contact, formatted (AAA) EEE_NNNN
CONTACT2_EMAIL_ADDRESS	Character 100	No	The email address of the second emergency contact
W4_FED_FILING_STATUS (UFED_FILING_STATUS)		Yes	Must be a valid value defined for Federal Filing Status
W4_FED_ALLOWANCES (UFED_ALLOWANCES)	Number	No
W4_FED_ADDITIONAL_AMOUNT (UFED_ADD_EXEMPTION)	Number	No
W4_FED_EXEMPT (UFED_ANN_EXEMPTION)	Character 1	No	If defined, must be a “1” if the employee is exempt.
W4_STATE_FILING_STATUS (UST_FILING_STATUS)	Character 100	No	Must be a valid value for the employee’s work state as defined by the position’s location. Valid values can vary by State and are defined on the IPUTP (US Tax Parameters) form.
W4_STATE_ALLOWANCES (UST_NUM_EXEMPTION_1)		No
W4_STATE_ADDITIONAL_AMOUNT (UST_ADDITIONAL_EXEMPTION)	Number	No
W4_STATE_EXEMPT (UST_NUM_EXEMPTION_1)	Character 1	No	If defined, must be a “1” if the employee is exempt

Processing#

Personality receives this data and hires/rehires the employee as follows:

If the person code is provided, this is assumed to be a re-hire. The system will verify that the employee number already exists.
Data is verified as valid for all fields, as necessary. If there are no issues with the quality of the data, Personality processes the data as an integral transaction.
No values are case sensitive. Fields that must be in upper case in Personality (code fields) will be upshifted and trimmed.
For a new hire, new IDENTITIES and PERSONALS information are created with the next available PERSON_CODE selected from the code sequence. Effective date of the PERSONALS is 01-Jan-0001.
For a re-hire, IDENTITIES and PERSONALS information are updated, if provided. If the data on the PERSONALS is being updated, the effective date is the HIRE_DATE.
An EMPLOYMENTS record is created, along with an ASSIGNMENT and ASSIGNMENT DETAILS record.
The ASSIGNMENTS start date is the HIRE_DATE.
The effective date of the ASSIGNMENT_DETAILS record is the HIRE_DATE.
If direct deposit information is provided, a PAYMENT RULES record is created effective on the HIRE_DATE, with up to two PAYMENT RULE DETAILS created for direct deposits.

Response Data#

Response	Information Returned
OK	The person code generated is also returned
-1	Person code provided but does not exist within Personality
-2	Government code not defined or not formatted correctly
-3	First name not defined
-4	Last name not defined
-5	Birth date not defined or not formatted correctly
-6	Gender not defined or not one of the valid values
-7	Ethnic not defined or not one of the valid values
-8	Language code not defined or not one of the valid values
-9	Entity Code is not defined or does not exist within Personality
-10	Employment Type is not defined or not one of the valid values
-11	Hire date not defined
-12	Original hire date not defined or not formatted correctly
-13	Seniority date not defined or not formatted correctly
-14	Assignment Code not defined
-15	Assignment Type not defined or not one of the valid values
-16	Assignment Status not defined or not one of the valid values
-17	Assignment Start Date not defined or not formatted correctly
-18	Assignment Start Date cannot be earlier than Hire Date
-19	Position Code not defined or does not exist within Personality
-20	Employment Status not defined or does not exist within Personality
-21	FTE not defined or greater than 1 / less than .01
-22	Wage Rate defined but rate basis not defined
-23	Employee State/Prov Code not defined or does not exist within Personality
-24	Bank Location defined but Bank Account not defined for Deposit 1
-25	One of Amount, Net Pay Percentage or Pay Remaining must be defined for Deposit 1
-26	Bank Location defined but Bank Account not defined for Deposit 2
-27	One of Amount, Net Pay Percentage or Pay Remaining must be defined for Deposit 2
-28	Both first and last name must be defined for Emergency Contact 1
-29	Phone number is not defined for Emergency Contact 1
-30	Both first and last name must be defined for Emergency Contact 2
-31	Phone number is not defined for Emergency Contact 1
-32	W4 Federal Filing Status is not defined or does not exist within Personality
-33	W4 State Filing Status is not defined or does not exist within Personality
-1001	Field XXXXXX is a date field but is not formatted as YYYYMMDD
-1002	Field XXXXXX is a numeric field but does not contain only numbers
-1003	Field XXXXXX is a toggle field where only valid values are “1” or null

Definitions#

Field	Definition
Name	employeehire
Version	V1
rootURI	This is the domain and port for the web server hosting the Personality REST services e.g. devas2.highlinehosting.com:7833
URI	/api/personality/v1/employeehire
Sample URL	https://devas2.highlinehosting.com:7833/api/personality/v1/employeehire

HTTP Headers#

Name	Type	Required	Description	Example
HL-CLIENT-ID	Character 50	Yes	Identifier for the client system	ABC
HL-CLIENT-TXN-ID	Character 50	No	Unique value for this service invocation. This can be used for trouble shooting and is stored by the Personality system.	A12345-1234
Accept	Character 50	Yes	Indicates what format the web service response is, must be set to 'application/json'	application/json
Content-Type	Character 50	Yes	Indicates what the format of the payload is, must be set to 'application/json'	application/json
Authorization	Character 50	Yes	OAuth Authorization Token (see OAuth Security)	Bearer nnnnnnnnnnnnnnn…

All inbound services require OAutho2 security. A token can be retrieved as described in the OAuth section later in this document. Tokens have a-one hour life span after which a new token must be retrieved.

EMPLOYEE HIRE Inbound to Personality#

Purpose// When an update is made in certain fields in Personality, a workflow is triggered that in turn invokes the Web Service outbound service from Personality to the 3rd party system. These actions are:

Changes in employee address (data source – p2k_hr_personals EPS)
Changes in emergency contact information (data source – p2k_hr_contacts ECT)
Changes to an employee’s ASSIGNMENT information (data source – p2k_hr_assignment_details EASD)
- Position code
- Group Changes
- Employment Status. NOTE: A long term leave cannot be future dated. If an employee is put into leave in the future, then a pro-active workflow will fire to transmit this data to the receiving system on the actual leave start date.
- Wage Rate (still to be decided)
Termination of an employee. NOTE: A termination cannot be future dated. If an employee is terminated in the future, then a pro-active workflow will fire to transmit this data to the receiving system on the actual termination date.

Users can process one employee at a time through this service, since it is triggered by an action from a workflow off the database.

The response back to Personality system will be either an OK condition or an ERROR condition, with information provided to identify the type of error encountered. In the event of an error, diagnostic information will be made available to the user.

Input Data#

Name	Type	Mandatory	Notes
PERSON_CODE	Character 16	Yes
TRANSACTION_TYPE	Character 16	Yes	An indicator of the type of transaction that is being transmitted. Data in each group is mandatory, based upon the transaction code here. Options are: * POSITION = Position code change * GROUP = Group code change * STATUS = New employment status, including TERMINATION * WAGE = New wage rate

Transaction Types

Transaction Type	Name	Type	Mandatory	Notes
Position	EFFECTIVE	Date	Yes	The date that the new position becomes effective, formatted in YYYYMMDD
Position	POSITION_CODE	Character 16	Yes	The new position code
Group	EFFECTIVE	Date	Yes	The date that the new position becomes effective, formatted in YYYYMMDD
Group	GROUP_CODE	Character 16	Yes	The new group code
Status	EFFECTIVE	Date	Yes	The date that the new employment status becomes effective, formatted in YYYYMMDD. In the case of terminated or leave employees, this is the termination or leave start date.
Status	EMPLOYMENT_STATUS	Character 16	Yes	The new employment status
Wage	EFFECTIVE	Date	Yes	The date that the new position becomes effective, formatted in YYYYMMDD
Wage	WAGE_RATE	Number	Yes	The new wage rate
Wage	RATE_BASIS	Character 2	Yes	The rate basis of the amount in WAGE_RATE. Must be one of the values defined for Rate Basis

Processing#

The Work Flow module is utilized to trigger the calls to this web service. When an update is made on the ASSIGNMENT DETAILS table of POSITION_CODE, GROUP_CODE, EMPLOYMENT_STATUS or WAGE_RATE, the workflow fires and invokes this web service, passing the information as needed.

Work Flows fire upon the commit of the updated/inserted/deleted data at the database level. If the EMPLOYMENT_STATUS change is one of a defined LEAVE or TERMINATION status, and the date of the transaction is a future date, then no action is taken.

A pro-active workflow is executed on a scheduled basis to examine any employees who were put on leave in one of the defined LEAVE statuses or TERMINATED, which takes effect on the date the workflow is executing. All changes are then sent to the receiving system.

Work Flow UserCalcs#

Custom functions have been created for the following tables, utilizing Personality Workflow with integrated web services:

Function	Defined As
Assignment Details (EASD)	P2K_PWSOEU.CF_TMC_EASD
Personals (EPS)	P2K_SOEU.CF_TMC_EPS
Contacts (ECT)	P2K_PQSOEU.CF_TMC_ECT

The workflow example below is executed after each CRUD (create, retrieve, update, delete) operation on Assignment Details, Personals and Contacts calling the appropriate inbound web service into the receiving/3rd party system. Connection details to the inbound web service must be defined on the IMCT form – custom tables admin screen, as shown below.

The URL of the inbound service must be defined On the IMCT form in the Custom Data field. The Custom Key and Custom Subkey columns must be defined as follows:

Column	Defined As
Custom Key	EASD UPDATE
Custom Subkey	URL

If the authorization is a user name and password to be included in the header of the request, another Subkey under the same Custom Key would be defined as follows:

Column	Defined As
Custom Key	EASD UPDATE
Custom Subkey	AUTHORIZATION
Custom Subkey	USERNAME

Each outbound service is defined in the same manner. The URL, User Name and Password are also stored in the same manner for each outbound service.

Pro-Active Work Flow#

For Employee status changes dated in the future, which are not handled by the standard work flow, a pro-active work flow must be defined and scheduled to run each day. The UMPWF update process must have the following fields defined.

Product
User Calc Code: the one that was created in the TMC Personality data base
Where Clause
Exception Level
Schedule Start Date
Run Start Time
Frequency

Output Data#

Response	Information Returned
OK	The data was received and processed successfully
User Defined Code	Employee is not a valid employee number
User Defined Code	Position Code is not a valid position code
User Defined Code	Group code is not a valid group code
User Defined Code	Employment status is not a valid employment status

TIME TRANSACTION Inbound to Personality#

Purpose// This is a bulk loading mechanism to transfer timesheet data from a Time & Attendance system into Personality, in the LOADED PAY LINES table structure.

No values are case sensitive. Fields that must be in upper case in Personality (code fields) are upshifted and trimmed.

This mechanism is triggered by a user interface action on the originating system, or on a scheduled basis.

The input is a set of transactions to be loaded. The response back will be an:

OK condition if all transactions are loaded without incident, or
If there is a problem with transactions, an error is generated with diagnostic information made available to the end user.

Time systems can send hours as well as an in/out time to Personality. The in/out time is not used, but must be stored for audit purposes. There is an assumption that the Service does not provide rate overrides or position changes during this interaction.

Input Data#

Name	Type	Mandatory	Notes
PERSON_CODE	Character 16	Yes
TRANSACTION_TYPE	Character 16	Yes	Date, formatted in YYYYMMDD
TIME_CODE	Character 16	Yes	The time code, as defined by the user in Personality
AMOUNT	Number	Yes	The number of hours or dollars that applies to this time code
TIME_IN(new DB column required)	Character 16	No
TIME_OUT(new DB column required)	Character 16	No
LOCATION_CODE	Character 16	No	If defined, this must be a valid value of locations as defined by the user in Personality.
CATEGORY_CODE	Character 16	Yes

Processing#

As records are received by this web service, they are inserted into the LOADED PAY LINES table with a destination of the IPTR screen, with a status of “To Be Loaded”. Other than the validation that data is in the correct format, no further validation of data is done through this process. Additional validation is done through the Personality UPTR process.

Output Data#

Response	Information Returned
OK	The data was received and processed successfully
-1001	Field XXXXXX is a date field, but is not formatted in YYYYMMDD
-1002	Field XXXXXX is a numeric field, but does not contain only numbers

Definitions#

Field	Definition
Name	timetransaction
Version	V1
rootURI	This is the domain and port for the web server hosting the Personality REST services e.g. devas2.highlinehosting.com:7833
URI	/api/personality/v1/timetransaction
Sample URL	https://devas2.highlinehosting.com:7833/api/personality/v1/timetransaction

HTTP Headers#

Name	Type	Required	Description	Example
HL-CLIENT-ID	Character 50	Yes	Identifier for the client system	ABC
HL-CLIENT-TXN-ID	Character 50	No	Unique value for this service invocation. This can be used for trouble shooting and is stored by the Personality system.	A12345-1234
Accept	Character 50	Yes	Indicates what format the web service response is, must be set to 'application/json'	application/json
Content-Type	Character 50	Yes	Indicates what the format of the payload is, must be set to 'application/json'	application/json
Authorization	Character 50	Yes	OAuth Authorization Token (see OAuth Security)	Bearer nnnnnnnnnnnnnnn…

LEAVE BALANCE Outbound from Personality#

Purpose// This is a bulk loading mechanism to transfer employee leave balance data from Personality back to a 3rd party (Time & Attendance) system.

This mechanism is triggered by a user interface action on the originating system, or on a scheduled basis.

The input is a set of records to be loaded. The response back will be an:

OK condition if all transactions are loaded without incident, or
If there is a problem with transactions, an error is generated with diagnostic information provided to the end user.

Input Data#

Name	Type	Mandatory	Notes
PERSON_CODE	Character 16	Yes
LEAVE_POLICY_TYPE	Character 16	Yes	This contains the leave policy type as defined in Personality
AS_OF_DATE	Date	Yes	The date, in YYYYMMDD format, that reflects the time this data was valid
AMOUNT	Number	Yes	The number of hours available to the employee in the defined leave type

Processing#

The 3rd party system receives the records and updates its own data with the values provided when the UWSALB function is run. This function has Personality’s standard employee selection parameters, along with an As Of Date defaulted to the current date and with the standard trace level parameter.

As mentioned above in the work flow UserCalc section, the IMCT screen holds the inbound URL, user name and password under the custom key LEAVE BALANCE. The fourth sub-key AUTHORIZATION is used to identify the type of security the outbound service uses. USERNAME indicates the user name and password sent in the header of the request.

Output Data#

Response	Information Returned
OK	The data was received and processed successfully
User-Defined Code	Employee is not a valid or active employee

OAuth Security#

Access Token Service Definition

Field	Definition
Name	Get OAUTH Authorization Token
rootUri	This is the domain and port for the web server hosting the Personality REST services e.g. devas2.highlinehosting.com:7833
protocols	https
OAuth Scheme	OAuth 2.0 Client Credentials (credentials)
Access Token URI	https://{rootUri}/oauth2/token
Sample URL	https://devas2.highlinehosting.com:7833/api/personality/oauth/token
Description	In order to call High Line web services, users must first be on-boarded as a Client Application. Once this process is complete, users are provided a Client Identifier and a Client Secret. Users utilize these values to obtain a token to gain access to the web services the user has access to. NOTE: The token is only available for 1 hour (3,600 seconds), after that users must make another call to this service to obtain another token.

Authorization

Username	Client ID (will be provided by High Line)
Password	Client Secret (will be provided by High Line)

This access token is included in the header of each inbound call to Personality’s web services as shown below under the Authorization key.

HTTP Headers#

Name	Type	Required	Description	Example
HL-CLIENT-ID	Character 50	Yes	Identifier for the client system	ABC
Accept	Character 50	Yes	Indicates what format the web service response is, must be set to 'application/json'	application/json
Content-Type	Character 50	Yes	Indicates what the format of the payload is, must be set to 'application/json'	application/json
Authorization	Character 50	Yes	OAuth Authorization Token (see OAuth Security)	Bearer nnnnnnnnnnnnnnn…

HTTPS Connection Details#

Inbound Services to 3rd Party System#

URL’s which have SSL security require the certificates to be stored as an external wallet file that the Personality outbound web services references. The wallet location is defined in the IMCT screen, custom tables.

Column	Defined As
Custom Key	WALLET
Custom Subkey	PATH
Custom Subkey	PASSWORD