Managing Timesheets from External Sources
This topic provides an overview of external timesheet management.:
|
Page Name |
Definition Name |
Usage |
|---|---|---|
|
Integration Broker Quick Configuration |
PTIB_ADMIN |
Activate the domain. To process asynchronous messages, one application server domain must be active. See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Understanding Setting Up PeopleSoft Integration Broker," Activating Pub/Sub Server Domains. |
|
Gateways |
IB_GATEWAY |
Activate the local gateway. See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Understanding Setting Up PeopleSoft Integration Broker," Defining Integration Gateways and Loading Connectors. See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Understanding Setting Up PeopleSoft Integration Broker," Configuring Integration Gateway Properties. |
|
Service Configuration |
IB_SVCSETUP |
Set up the service configuration and listening connector. See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Configuring PeopleSoft Integration Broker for Handling Services." See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Understanding Setting Up PeopleSoft Integration Broker," Defining Integration Gateways and Loading Connectors. See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Using the Delivered Listening Connectors and Target Connectors." |
|
Queue Status |
IB_MONITOR_QUEUES |
Activate the queue for your message. See documentation PeopleTools : PeopleSoft Integration Broker, "Managing Service Operation Queues." |
|
Services Page |
IB_SERVICEDEFN |
Activate your service, handler, and routing. Setting Up Integration Broker for the SOA for Inbound Timesheets Feature |
|
Transformation Test Page |
IB_TRANSFORM_PAGE |
Convert XML from a service provider. |
|
Handler Tester Page |
IB_EVENTTESTER |
Use the converted XML to create a timecard. |
Many PeopleSoft Services Procurement customers use external time tracking and project management tools. This often requires service providers to enter time in two systems: PeopleSoft Services Procurement for billing and the supplier system or other external system to track time for a project. The SOA (Service Oriented Architecture) for Inbound Timesheets feature enables third parties to capture time information on an external web-based system using an industry-standard generic HR-XML 2.5 timecard schema and then send the XML file to your system without having to enter the information directly into Services Procurement. Your system then uses the XML file to generate and submit a timesheet.
The feature includes:
The ability for service providers to submit time information electronically to your system through a web service.
A process for converting the time information into XML that can be used to generate a timesheet.
Processing for timesheets (including approvals and history) that is the same as time processing that is used when you manually enter information into PeopleSoft Services Procurement. The timesheet is processed and invoiced just like a time sheet entered directly in Services Procurement.
The use of XML schema elements and attributes that map to Services Procurement application fields.
The primary benefit is that service providers can enter time in one system instead of two with little difference in processing time for manually entered timesheets. Specifically, the feature:
Enables the quick and cost-effective receipt of time reporting data from any external web-based, time-capture system that uses industry-standard generic HR-XML 2.5 timecard schema.
Is broad enough to be used globally without having to establish, engineer, and implement many separate transformation mechanisms.
Validates the data and enables sending a response message to the external system for any invalid data.
Handles the time data the same as it would a timesheet that is entered manually in PeopleSoft Services Procurement after the system accepts the data.
Provides an email notification to notify the external system of any timesheets that were denied in Services Procurement.
Provides an email notification to notify the external system of any timesheet adjustments that were made in Services Procurement.
Receives resubmitted timesheets that were rejected previously or that were changed after being submitted to Services Procurement.
How the SOA for Inbound Timesheets Feature Works
The following diagram shows how data flows between the service provider and PeopleSoft Services Procurement:
The following diagram shows the main components of the SOA for Inbound Timesheets feature and shows how data flows between these components:
The following process is a high-level overview of the steps depicted in the preceding diagrams:
Time data is recorded in an external time-capturing system.
A message is created in the time-capturing system and sent to your system in the format of the HR-XML 2.5 timecard schema. This message is sent asynchronously two-way (request and response) from the external time-capturing system to the Services Procurement database.
The PeopleSoft Integration Broker receives the HR-XML time data and transforms it into the PeopleSoft Message SP_TIME_CARD.
The On Notify request handler is invoked to receive the transformed message. The On Notify application class processes the time card message and invokes the SP:SP_INTEGRATION: TimeCard application class.
The TimeCard application class validates and verifies the data, and it rejects the invalid data.
The TimeCard application class builds and sends a response message for the rejected data.
The response message is published to the Gateway.
The accepted data is written into the Timecard hold table.
Timecard data is loaded into the timecard rowset. The rowset supplies the Timecard Component Interface properties. Timecard Component Interface validates all the business logic and accepts or rejects the time information. It then saves the timesheet for the valid timecard.
For rejected timecards, the Timecard Component Interface builds and sends a response message. The response message is published to the Gateway.
The timecard is routed to the approver (based on the timesheet status and the timecard approval setting at the business unit level).
The service provider SPC is notified of any timesheet adjustments made in PeopleSoft Services Procurement or timesheets that are denied in Services Procurement.
Approved timesheets are processed and invoiced.
Any updates to the timesheet in the external system are resubmitted to Services Procurement and steps 2 through 13 are repeated.
|
Condition |
Error or Warning |
Action |
|---|---|---|
|
Invalid message format. |
Error : Invalid Time Message. |
Reject the TimeCard message. |
|
External ID is missing. |
Error: External TimeSheet required. |
Reject the TimeCard message. |
|
Business unit is missing. |
Error: Business Unit is required. |
Reject the TimeCard message. |
|
Work order is missing. |
Error: Work Order is required. |
Reject the TimeCard message. |
|
Period start and end dates are missing. |
Error: Period Start and End Dates are required. |
Reject the TimeCard message. |
|
Required fields are missing, |
Error: Required "field name" is missing. |
Reject the TimeCard message. |
|
Field format or date is invalid. |
Error: "Field" format is invalid. |
Reject the TimeCard message. |
|
A timesheet already exists for the time period for the provider for the given template. |
Warning: TimeSheet exists for the %Time Period. |
Send a warning when the action for the incoming time data is Add and the timesheet already exists in Services Procurement for the time period. |
|
The person ID of the service provider is invalid. |
Person is not valid in PeopleSoft Services Procurement system. |
Send an error message for the invalid service provider. |
|
Work order ID is invalid. |
Error : Work order not found. |
Reject the TimeCard message. |
|
Work order and purchase order for the time period were missing. |
Error : Work order not found for the Time period. |
If an overlap occurs in the time period or if the start date and end date are both outside of work order time period, then reject the TimeCard message. |
|
The time date entered for the reported time (time interval, time event) is outside of the work order period. |
Error : Reported time is outside of the work order period. |
Reject the TimeCard message. |
|
The work order consumption amount is exceeded. |
Error : Work order over amount. |
Reject the TimeCard message. |
|
The time template period is in error. |
Error: The reported time format is wrong for the time template. |
Reject the TimeCard message. |
|
An Expense time element was found. |
Warning: "Expenses" are currently not supported. |
Accept the time message, ignore the expense message, and generate a warning. |
|
For an action code of Change, the Services Procurement timesheet that was sent by the external system was not found in Services Procurement. |
Error : Invalid sPro Timesheet id. |
Reject the TimeCard message. |
|
For an action code of Change, the status is anything other than Rejected. |
Error: Timecard in Raw/Submitted/Processed/Approved status cannot be processed in Change mode. |
Reject the TimeCard message. |
|
For an action code of Add, the status is Processed or Final. |
Error: Timecard in Processed/Final status cannot be processed in Add mode. |
Reject the TimeCard message. |
|
Any information data sent from the external system is not used by Services Procurement. |
Warning message |
Accept the time data and generate the warning message for unused data. |
Technical Dependencies
To use the SOA for Inbound Timesheets feature, you need:
Tools Integration Broker web services, release 8.5 or later.
The new Approval Framework feature implemented for timesheets for release 9.1 of PeopleSoft Software.
Field Mappings
|
External System Element or Attribute |
Services Procurement Field |
|---|---|
|
Timecard ID |
SP_EXT_TIME_HDR.SP_EXTERNAL_ID SPA_TIME_HDR.SP_EXTERNAL_ID |
|
Reported Resource Person ID |
SP_EXT_TIME_HDR.PERSON_ID SPA_TIME_HDR.PERSON_ID |
|
Reported Time Status |
SP_EXT_TIME_HDR.SP_EXT_STATUS SPA_TIME_HDR.TIME_HDR_STATUS |
|
Period Start Date |
SP_EXT_TIME_HDR.PERIOD_START_DT SPA_TIME_HDR.PERIOD_START_DT |
|
Period End Date |
SP_EXT_TIME_HDR.PERIOD_END_DT SPA_TIME_HDR.PERIOD_END_DT |
|
Time Interval Type |
SP_EXT_TIME_DTL.SP_TRN_TYPE SPA_TIME_DTL.Activity_id |
|
Time Interval Billable |
SP_EXT_TIME_DTL.SPA_BILLING_ACTION SPA_TIME_DTL.SPA_BILLING_ACTION |
|
Time Interval Action Code |
SP_EXT_TIME_DTL.SP_ACTION_CODE |
|
Time Interval ID |
SP_EXT_TIME_DTL.SP_EXTERNAL_ID SPA_TIME_DTL.SP_EXTERNAL_ID |
|
Start Date Time |
SP_EXT_TIME_DTL.STARTDATETIME SPA_TIME_DTL.STARTDATETIME |
|
End Date Time |
SP_EXT_TIME_DTL.ENDDATETIME |
|
Duration |
SP_EXT_TIME_DTL.SP_TIME_DURATION |
|
Approval Information Person ID |
SP_EXT_TIME_DTL.Approval_OPRID |
|
Time Event Type |
SP_EXT_TIME_DTL.SP_TRN_TYPE |
|
Time Event Billable |
SP_EXT_TIME_DTL.SPA_BILLING_ACTION SPA_TIME_DTL.SPA_BILLING_ACTION |
|
Time Event Action Code |
SP_EXT_TIME_DTL.SP_ACTION_CODE |
|
Event DateTime |
SP_EXT_TIME_DTL.START_DATETIME (IF clock-in) or SP_EXT_TIME_DTL.ENDDATETIME ( IF clock-out) |
|
Expense Billable |
SP_EXT_TIME_DTL.SPA_BILLING_ACTION SPA_TIME_DTL.SPA_BILLING_ACTION |
|
Expense Action Code |
SP_EXT_TIME_DTL.SP_ACTION_CODE |
|
External Order Number |
SP_CUST_REP_SUB.WORK_ORDER_ID SPA_TIME_WO.WORK_ORDER_ID |
|
Customer Reporting Requirements Entity |
SP_EXT_TIME_DTL.BUSINESS_UNIT |
Before using the SOA for Inbound Timesheets feature, you need to set up PeopleSoft Integration Broker to accept time information from external service providers. This section discusses how to:
Activate the domain.
Activate the local gateway.
Set up the service configuration and listening connector.
Activate the queue for your message.
Activate your service, handler, and routing.
For general information about setting up the Integration Broker,
See documentation PeopleTools PeopleSoft Integration Broker Administration, "Understanding Setting Up PeopleSoft Integration Broker."
Activating the Domain
To process asynchronous messages, one application server domain must be active.
See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Understanding Setting Up PeopleSoft Integration Broker," Activating Pub/Sub Server Domains.
Activate the Local Gateway
To activate the local gateway:
See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Understanding Setting Up PeopleSoft Integration Broker," Defining Integration Gateways and Loading Connectors.
See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Understanding Setting Up PeopleSoft Integration Broker," Configuring Integration Gateway Properties.
Setting Up the Service Configuration and Listening Connector
To set up the service configuration and listening connector:
See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Configuring PeopleSoft Integration Broker for Handling Services."
See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Understanding Setting Up PeopleSoft Integration Broker," Defining Integration Gateways and Loading Connectors.
See documentation PeopleTools : PeopleSoft Integration Broker Administration, "Using the Delivered Listening Connectors and Target Connectors."
Activating the Queue for Your Message
To activate the queue for your message:
See documentation PeopleTools : PeopleSoft Integration Broker, "Managing Service Operation Queues."
Activating Your Service, Handler, and Routing
Use the Services page (IB_SERVICEDEFN) to activate your service, handler, and routing.
Navigation:
On the Services search page, enter SP_TIME_CARD in the Service field and click Search.
This example illustrates the fields and controls on the Services page. You can find definitions for the fields and controls later on this page.
On the Services page, select Services Procurement in the Object Owner ID field.
Click the SP_TIME_CARD.v1 link on the Operation tab at the bottom of the page.
This example illustrates the fields and controls on the Services page General tab. You can find definitions for the fields and controls later on this page.
On the General tab, select the Active check box in the Default Service Operation Version group box.
Select the Handlers tab.
This example illustrates the fields and controls on the Services page Handlers tab. You can find definitions for the fields and controls later on this page.
Select Active from the Status drop-down list box.
Note: The handler must be active for the Message subscription PeopleCode/Application package logic to run. If the handler is not active, the message will appear to be done, but nothing will be processed by the code.
Select the Routings tab.
This example illustrates the fields and controls on the Services page Routings tab. You can find definitions for the fields and controls later on this page.
In the Routing Definitions group box, select the check box next to the routing name that you want to use and click Activate Selected Routings.
Note: The routing and operation must be active or you will receive a message in the Send Master stating that the routing cannot be found.
See the product documentation for PeopleTools: Integration Broker Administration, Configuring PeopleSoft Integration Broker for Handling Services. , Configuring PeopleSoft Integration Broker for Handling Services," Understanding Configuring PeopleSoft Integration Broker for Handling Services, Setting Service Configuration.
PeopleTools: Integration Broker, Managing Services, Managing Service Operation Handlers, Managing Service Operation Routing Definitions," Creating Routing Definitions.
The service provider sends time information to your system in HR-XML 2.5 format. Your system then:
Imports the XML file into PeopleTools.
Converts the XML from the service provider into XML that can be used to create a timecard.
Uses the converted XML to create a timecard that can be used in PeopleSoft Services Procurement.
When the timecard is created, it is automatically submitted for approval and a copy is sent to the service provider. This section discusses how to:
Convert XML from a service provider into XML that can be used to create a timecard.
Use the converted XML to create a timecard.
Converting XML from a Service Provider
Use the Transformation Test page (IB_TRANSFORM_PAGE) to convert XML from a service provider.
Navigation:
On the Transform Test Utility search page, enter SP_TIME_CARD in the Search by field and click Search.
This example illustrates the fields and controls on the Transformation Test page. You can find definitions for the fields and controls later on this page.
In the File Name field, enter the path and file name where the XML from the service provider is stored.
Click Transform.
The converted XML appears in the Message Text text box.
This example illustrates the fields and controls on the Transformation Test page displaying converted XML. You can find definitions for the fields and controls later on this page.
Copy the XML in the Message Text text box into your buffer, for example, Notepad.
Click Save.
Using the Converted XML to Create a Timecard
Use the Handler Tester page (IB_EVENTTESTER) to use the converted XML to create a timecard.
Navigation:
The Select a service operation to test group box appears displaying the service operation to test.
This example illustrates the fields and controls on the Handler Tester Search page. You can find definitions for the fields and controls later on this page.
Note: This procedure is only one way to perform the conversion. You can also do it using Sendmaster.
See documentation PeopleTools : Integration Broker Testing Utilities and Tools, "Using the Handler Tester Utility," Uploading XML Data from Files.
Click the SP_TIME_CARD link under Service Operation.
This example illustrates the fields and controls on the Handler Tester page. You can find definitions for the fields and controls later on this page.
Select On Notify in the Handler Type drop-down list box.
Select TimeNotifyHandler in the Handler Name drop-down list box.
Click the Provide XML button in the Populate Input Message group box.
On the Enter XML page, copy the XML from your buffer into the XML text box.
This example illustrates the fields and controls on the Enter XML page. You can find definitions for the fields and controls later on this page.
Click OK.
The Handler Tester page appears with the XML in the Input Message text box.
This example illustrates the fields and controls on the Handler Tester page displaying XML in Input Message box. You can find definitions for the fields and controls later on this page.
Click Execute Event.
The process creates a timecard that can be used in Services Procurement. It automatically submits the timecard for approval and sends a copy of the time sheet to the service provider to view.
When your system generates a timecard for a service provider, the system sends a copy of the timecard to the service provider. The service provider can then view the timecard in PeopleSoft Services Procurement. The imported timecard has a status attached to it.
|
Status in External System |
Status in Services Procurement |
|---|---|
|
Raw |
Accept in both Add and Update status. |
|
Processed |
Accept and submit the timesheet unless status is Final. |
|
Submitted |
Accept in both Add and Update status. If status is Update, create an adjustment in Services Procurement. |
|
Approved |
If the timesheet is passed to Services Procurement already having a status of Approved in the external system, it will not go through the approval process again within Services Procurement. The timesheet will be automatically approved and will be available for invoicing. |
|
Rejected |
Reject the timesheet, but accept resubmitted timesheets. For resubmitted timesheets in Update status, create an adjustment row in Services Procurement. Rejected is also a valid status for resubmitted timesheets. |
If you are a provider who has had a timecard generated based on XML that you sent to an enterprise for whom you provide services and the timecard has been submitted, to view the timecard:
Sign in to the PeopleSoft system.
Select
The Manage Timesheets page appears.
This example illustrates the fields and controls on the Manage Timesheets page. You can find definitions for the fields and controls later on this page.
Click the Search button in the Timesheet History group box.
The system displays a list of timesheets.
This example illustrates the fields and controls on the Manage Timesheets page with timesheets listed. You can find definitions for the fields and controls later on this page.
To view details of a timesheet, click the link for the date range of the timesheet that you want to view.
This example illustrates the fields and controls on the Enter Time for Provider page. You can find definitions for the fields and controls later on this page.
