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

insert screen shots x 3

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