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:
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 | Character 3 | 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 |
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 number 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 defined 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 defined if DEPOSIT1_BANK_LOCATION is defined. |
DEPOSIT1_PAY_REMAINING | Character 1 | No | If 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_LOCATION | Character 16 | No | The bank transit code for the direct deposit |
DEPOSIT2_BANK_ACCOUNT | Character 30 | No | The bank account number for direct deposit. When the DEPOSIT2_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 DEPOSIT2_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be defined if DEPOSIT2_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 DEPOSIT2_AMOUNT, NET_PAY_PERCENT or PAY_REMAINING must be defined if DEPOSIT2_BANK_LOCATION is defined. |
DEPOSIT2_PAY_REMAINING | Character 1 | No | If 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_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 CONTACT2 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 |
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 2 |
-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 the valid values are “1” or null |
Field | Definition |
---|---|
Name | employeehire |
Version | V1 |
rootURI | This 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 URL | https://devas2.highlinehosting.com:7833/api/personality/v1/employeehire |
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 | Defines what format the web service response is. Must be set to 'application/json' | application/json |
Content-Type | Character 50 | Yes | Defines 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.
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.
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 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 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 |
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.
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 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:
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.
Response | Information Returned |
---|---|
OK | The data was received and processed successfully |
User Defined Code | Employee number 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 |
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.
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 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 location value as defined in Personality. |
CATEGORY_CODE | Character 16 | Yes |
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 only contain numbers |
Field | Definition |
---|---|
Name | timetransaction |
Version | V1 |
rootURI | This 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 URL | https://devas2.highlinehosting.com:7833/api/personality/v1/timetransaction |
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 | Defines what format the web service response is. Must be set to 'application/json' | application/json |
Content-Type | Character 50 | Yes | Defines 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… |
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:
Name | Type | Mandatory | Notes |
---|---|---|---|
PERSON_CODE | Character 16 | Yes | |
LEAVE_POLICY_TYPE | Character 16 | Yes | The leave policy type. Value must be one of the values that have been defined in Personality. |
AS_OF_DATE | Date | Yes | The date the data is valid from, formatted in YYYYMMDD. |
AMOUNT | Number | Yes | The number of hours available to the employee in the defined leave type |
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.
Response | Information Returned |
---|---|
OK | The data was received and processed successfully |
User-Defined Code | Employee is not a valid or active employee |
Field | Definition |
---|---|
Name | Get OAUTH Authorization Token |
rootUri | This is the domain and port for the web server hosting the Personality REST services. Example: 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: Tokens have a life span of 1 hour, after which a new token must be retrieved. |
Authorization
Username | Client ID (Provided by High Line) |
Password | Client Secret (Provided by High Line) |
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… |
Column | Defined As |
---|---|
Custom Key | WALLET |
Custom Subkey | PATH |
Custom Subkey | PASSWORD |
Outbound logging from Personality is captured through Workflow logging and is stored on the Executions table.
A Personality user processes the Loaded Pay Lines to the Pay Transaction table (IPTR)
Pay transactions are viewed and managed on IPTR
Screen captures are meant to be indicative of the concept being presented and may not reflect the current screen design.
If you have any comments or questions please email the Wiki Editor
All content © High Line Corporation