WEB SERVICES

Web Services#


EMPLOYEE HIRE Inbound to Personality#

Purpose#

This service receives information from 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:

Input Data#

NameTypeMandatory *Only on new hireNotes
PERSON_CODECharacter 16NoIf 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_CODECharacter 16YesFormatted government code, with hyphens provided
FIRST_NAMECharacter 50YesEmployee first name
LAST_NAMECharacter 50YesEmployee last name
BIRTH_DATEDateYes*Date in YYYYMMDD format
GENDERCharacter 2Yes*01 for Male; 02 for Female
ETHNICCharacter 4Yes*Value must be one of the values defined for Ethnic code
LANGUAGE_CODECharacter 3Yes*Value must be one of the values defined for Language code
MIDDLE_NAMECharacter 50NoEmployee middle name
ENTITY_CODECharacter 16YesName of entity employee is being hired into
EMPLOYMENT_TYPECharacter 2YesValue must be one of the values defined for Employment type
HIRE_DATEDateYesDate in YYYYMMDD format
ORIGINAL_HIRE_DATEDateYes*Date in YYYYMMDD format
SENIORITY_DATEDateYes*Date in YYYYMMDD format
ASSIGNMENT_CODECharacter 16YesUnique value for an employee. Recommend PRIMARY for new hires
ASSIGNMENT_TYPECharacter 2YesValue must be one of the values defined for Assignment Type
ASSIGNMENT_STATUSCharacter 2YesValue must be one of the values defined for Assignment Status
ASSIGNMENT_START_DATEDateYesDate in YYYYMMDD format, and must not be earlier than the HIRE_DATE
POSITION_CODECharacter 16YesThe 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_STATUSCharacter 16YesValue must be one of the values that have been defined on the IDES form
FTENumberYesA value not exceeding 1.0 and greater than 0
WAGE_RATENumberNoWage rate can be defined here, if overriding the value derived from the position definition
RATE_BASISCharacter 2NoIf the Wage Rate is defined, then Rate Basis is mandatory. Value must be one of the values defined for Rate Basis
EMAIL_ADDRESS_WORKCharacter 50NoEmployee work email address
EMAIL_ADDRESS_HOMECharacter 50NoEmployee home email address
ADDRESS_LINE_1Character 50NoEmployee home address, line 1
ADDRESS_LINE_2Character 50NoEmployee home address, line 2
LOCALITYCharacter 50NoEmployee home city/town
ZIP_POSTALCharacter 16NoEmployee home zip code/postal code
STATE_PROV_CODECharacter 2Yes*Employee home address State/Province
PHONE_NUMBERCharacter 20NoEmployee home phone number, formatted (AAA) EEE_NNNN
DEPOSIT1_BANK_LOCATIONCharacter 16NoThe bank transit code for the direct deposit
DEPOSIT1_BANK_ACCOUNTCharacter 30NoThe bank account number for direct deposit. When the DEPOSIT1_BANK_LOCATION is defined, then this field is mandatory.
DEPOSIT1_AMOUNTNumberNoThe dollar amount to be deposited into this account each pay. One of DEPOSIT1_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be defined if DEPOSIT1_BANK_LOCATION is defined.
DEPOSIT1_NET_PAY_PERCENTNumberNoThe percentage of net pay to be deposited into this account each pay. One of DEPOSIT1_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be defined if DEPOSIT1_BANK_LOCATION is defined.
DEPOSIT1_PAY_REMAININGCharacter 1NoIf any amount is left to be paid into this account, enter “1” in this field. One of DEPOSIT1_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be defined if DEPOSIT1_BANK_LOCATION is defined.
DEPOSIT2_BANK_LOCATIONCharacter 16NoThe bank transit code for the direct deposit
DEPOSIT2_BANK_ACCOUNTCharacter 30NoThe bank account number for direct deposit. When the DEPOSIT2_BANK_LOCATION is defined, then this field is mandatory.
DEPOSIT2_AMOUNTNumberNoThe dollar amount to be deposited into this account each pay. One of DEPOSIT2_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be defined if DEPOSIT2_BANK_LOCATION is defined.
DEPOSIT2_NET_PAY_PERCENTNumberNoThe percentage of net pay to be deposited into this account each pay. One of DEPOSIT2_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be defined if DEPOSIT2_BANK_LOCATION is defined.
DEPOSIT2_PAY_REMAININGCharacter 1NoIf any amount is left to be paid into this account, enter “1” in this field. One of DEPOSIT2_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be defined if DEPOSIT2_BANK_LOCATION is defined.
CONTACT1_FIRST_NAMECharacter 50NoThe first name of the first emergency contact
CONTACT1_LAST_NAMECharacter 50NoThe last name of the first emergency contact. If CONTACT1 information is defined, then both First and Last Name must be defined.
CONTACT1_ADDRESS_LINE_1Character 50NoThe home address of the first emergency contact, line 1
CONTACT1_ADDRESS_LINE_2Character 50NoThe home address of the first emergency contact, line 2
CONTACT1_LOCALITYCharacter 50NoThe home city/town of the first emergency contact
CONTACT1_ZIP_POSTALCharacter 16NoThe home zip code/postal code of the first emergency contact
CONTACT1_PHONE_NUMBERCharacter 20YesThe home phone number of the first emergency contact, formatted (AAA) EEE_NNNN
CONTACT1_EMAIL_ADDRESSCharacter 100NoThe email address of the first emergency contact
CONTACT2_FIRST_NAMECharacter 50NoThe first name of the second emergency contact
CONTACT2_LAST_NAMECharacter 50NoThe last name of the second emergency contact. If CONTACT2 information is defined, then both First and Last Name must be defined.
CONTACT2_ADDRESS_LINE_1Character 50NoThe home address of the second emergency contact, line 1
CONTACT2_ADDRESS_LINE_2Character 50NoThe home address of the second emergency contact, line 2
CONTACT2_LOCALITYCharacter 50NoThe home city/town of the second emergency contact
CONTACT2_ZIP_POSTALCharacter 16NoThe home zip code/postal code of the second emergency contact
CONTACT2_PHONE_NUMBERCharacter 20YesThe home phone number of the second emergency contact, formatted (AAA) EEE_NNNN
CONTACT2_EMAIL_ADDRESSCharacter 100NoThe email address of the second emergency contact
W4_FED_FILING_STATUS (UFED_FILING_STATUS) YesMust be a valid value defined for Federal Filing Status
W4_FED_ALLOWANCES (UFED_ALLOWANCES)NumberNo
W4_FED_ADDITIONAL_AMOUNT (UFED_ADD_EXEMPTION)NumberNo
W4_FED_EXEMPT (UFED_ANN_EXEMPTION)Character 1NoIf defined, must be a “1” if the employee is exempt.
W4_STATE_FILING_STATUS (UST_FILING_STATUS)Character 100NoMust 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)NumberNo
W4_STATE_EXEMPT (UST_NUM_EXEMPTION_1)Character 1NoIf defined, must be a “1” if the employee is exempt

Processing#

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

Response Data#

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

Definitions#

FieldDefinition
Nameemployeehire
VersionV1
rootURIThis is the domain and port for the web server hosting the Personality REST services. Example: devas2.highlinehosting.com:7833
URI/api/personality/v1/employeehire
Sample URLhttps://devas2.highlinehosting.com:7833/api/personality/v1/employeehire

HTTP Headers#

NameTypeRequiredDescriptionExample
HL-CLIENT-IDCharacter 50YesIdentifier for the client systemABC
HL-CLIENT-TXN-IDCharacter 50NoUnique value for this service invocation. This can be used for trouble shooting and is stored by the Personality system.A12345-1234
AcceptCharacter 50YesDefines what format the web service response is. Must be set to 'application/json'application/json
Content-TypeCharacter 50YesDefines what the format of the payload is. Must be set to 'application/json'application/json
AuthorizationCharacter 50YesOAuth 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 Outbound from 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:

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#

NameTypeMandatoryNotes
PERSON_CODECharacter 16Yes
TRANSACTION_TYPECharacter 16YesAn indicator of the type of transaction that is being transmitted. Data in each group is mandatory, based upon the transaction code defined here. Options are:
* POSITION = Position code change
* GROUP = Group code change
* STATUS = New employment status, including TERMINATION
* WAGE = New wage rate

Transaction Types

Transaction TypeNameTypeMandatoryNotes
PositionEFFECTIVEDateYesThe date that the new position becomes effective, formatted in YYYYMMDD
PositionPOSITION_CODECharacter 16YesThe new position code
GroupEFFECTIVEDateYesThe date that the new position becomes effective, formatted in YYYYMMDD
GroupGROUP_CODECharacter 16YesThe new group code
StatusEFFECTIVEDateYesThe 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.
StatusEMPLOYMENT_STATUSCharacter 16YesThe new employment status
WageEFFECTIVEDateYesThe date that the new position becomes effective, formatted in YYYYMMDD
WageWAGE_RATENumberYesThe new wage rate
WageRATE_BASISCharacter 2YesThe rate basis of the amount in WAGE_RATE. Must be one of the values defined for Rate Basis

Processing#

The Workflow 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.

Workflows 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.

Workflow UserCalcs#

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

FunctionDefined 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 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 Define Custom Tables (IMCT) admin form.

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

ColumnDefined As
Custom KeyEASD UPDATE
Custom SubkeyURL


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:

ColumnDefined As
Custom KeyEASD UPDATE
Custom SubkeyAUTHORIZATION
Custom SubkeyUSERNAME



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 Workflow#

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

Output Data#

ResponseInformation Returned
OKThe data was received and processed successfully
User Defined CodeEmployee number is not a valid employee number
User Defined CodePosition Code is not a valid position code
User Defined CodeGroup code is not a valid group code
User Defined CodeEmployment 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:

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

Input Data#

NameTypeMandatoryNotes
PERSON_CODECharacter 16Yes
TRANSACTION_TYPECharacter 16YesDate, formatted in YYYYMMDD
TIME_CODECharacter 16YesThe time code, as defined in Personality
AMOUNTNumberYesThe number of hours or dollars that applies to this time code
TIME_IN(new DB column required)Character 16No
TIME_OUT(new DB column required)Character 16No
LOCATION_CODECharacter 16NoIf defined, this must be a valid location value as defined in Personality.
CATEGORY_CODECharacter 16Yes

Processing#

As records are received by this web service, they are inserted into the LOADED PAY LINES table with a destination of the IPTR form, 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#

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

Definitions#

FieldDefinition
Nametimetransaction
VersionV1
rootURIThis is the domain and port for the web server hosting the Personality REST services. Example: devas2.highlinehosting.com:7833
URI/api/personality/v1/timetransaction
Sample URLhttps://devas2.highlinehosting.com:7833/api/personality/v1/timetransaction

HTTP Headers#

NameTypeRequiredDescriptionExample
HL-CLIENT-IDCharacter 50YesIdentifier for the client systemABC
HL-CLIENT-TXN-IDCharacter 50NoUnique value for this service invocation. This can be used for trouble shooting and is stored by the Personality system.A12345-1234
AcceptCharacter 50YesDefines what format the web service response is. Must be set to 'application/json'application/json
Content-TypeCharacter 50YesDefines what the format of the payload is. Must be set to 'application/json'application/json
AuthorizationCharacter 50YesOAuth 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:

Input Data#

NameTypeMandatoryNotes
PERSON_CODECharacter 16Yes
LEAVE_POLICY_TYPECharacter 16YesThe leave policy type. Value must be one of the values that have been defined in Personality.
AS_OF_DATEDateYesThe date the data is valid from, formatted in YYYYMMDD.
AMOUNTNumberYesThe 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 Workflow UserCalc section, the IMCT form 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 defines the user name and password sent in the header of the request.

Output Data#

ResponseInformation Returned
OKThe data was received and processed successfully
User-Defined CodeEmployee is not a valid or active employee

OAuth Security#

Access Token Service Definition
FieldDefinition
NameGet OAUTH Authorization Token
rootUriThis is the domain and port for the web server hosting the Personality REST services. Example: devas2.highlinehosting.com:7833
protocolshttps
OAuth SchemeOAuth 2.0 Client Credentials (credentials)
Access Token URIhttps://{rootUri}/oauth2/token
Sample URLhttps://devas2.highlinehosting.com:7833/api/personality/oauth/token
DescriptionIn 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: Tokens have a life span of 1 hour, after which a new token must be retrieved.

Authorization

UsernameClient ID (Provided by High Line)
PasswordClient Secret (Provided by High Line)
This access token is included in the header of each inbound call to Personality’s web services, under the Authorization key.

HTTP Headers#

NameTypeRequiredDescriptionExample
HL-CLIENT-IDCharacter 50YesIdentifier for the client systemABC
AcceptCharacter 50YesIndicates what format the web service response is. Must be set to 'application/json'application/json
Content-TypeCharacter 50YesIndicates what the format of the payload is. Must be set to 'application/json'application/json
AuthorizationCharacter 50YesOAuth 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 on the Define Custom Tables (IMCT) form.

ColumnDefined As
Custom KeyWALLET
Custom SubkeyPATH
Custom SubkeyPASSWORD

Auditing of Activity#

Inbound logging to Personality is captured in the Web Services Logging Table (P2K_WS_LOGS)

Outbound logging from Personality is captured through Workflow logging and is stored on the Executions table.

Time Transaction Flow#

The client's interface initiates the transfer of time to Personality, Loaded Pay Lines (IPTL).

A Personality user processes the Loaded Pay Lines to the Pay Transaction table (IPTR)


Pay transactions are viewed and managed on IPTR


Notes #

Click to create a new notes page