Configuring the icalendar Export Feature in Oracle HRMS Applications An Oracle White Paper June 2009 1
Configuring the icalendar Export Feature in Oracle HRMS Applications... 1 icalendar Download Feature... 3 icalendar in Oracle HRMS Applications... 3 Oracle irecruitment... 3 Oracle Self-Service Human Resources (Oracle SSHR)... 3 Oracle Learning Management (OLM)... 3 Enabling the Export Feature Through Personalization... 4 Configuring the Download Option from an OAF Page... 4 Setting Parameters in the Destination URI:... 7 Viewing the Export Column in the My Interviews Table... 9 Configuring the icalendar File as an Attachment with Notifications... 11 Configuring the Workflow to send icalendar file as Attachment... 11 Samples of icalendar Files... 17 2
icalendar Download Feature The icalendar data download feature enables users to download calendar details such as meeting information in the form of icalendar files (.ics file) from Oracle Applications Framework (OAF) pages and to send icalendar files as attachments in notifications. Purpose This document explains how to: Configure the icalendar download feature in Oracle HRMS applications Configure the icalendar files as attachments with notifications icalendar Format icalendar uses the icalendar format (as specified in RFC 2445) for downloading the calendar data. icalendar information saved using this feature can be loaded to any Calendar application that supports this format, for example, Microsoft Outlook Calendar and Oracle Beehive. icalendar in Oracle HRMS Applications Some of the Oracle HRMS applications allow users to download calendar details and also to send the details as notification and email attachments. This download functionality can be enabled using Personalization. See: Enabling the Export Feature Through Personalization This section lists some of the products that could be configured to use the icalendar download feature. Oracle irecruitment From the Interviews table on their home page, managers, recruiters, and candidates can export interview data to the calendar application that they use. Oracle Self-Service Human Resources (Oracle SSHR) Managers and workers can export absence details such as absence dates to the calendar application that they use. Oracle Learning Management (OLM) Learners and instructors can export class schedule details such as class time, class start and end dates to the calendar application that they use. 3
Enabling the Export Feature Through Personalization Using the Personalization function available on the OAF pages, system administrators can enable the Export feature to help users download class schedules, interview information, or absences details from the application pages. Configuring the Download Option from an OAF Page System administrators can configure the download option from the OAF pages. This section uses the example of configuring the download option on the Oracle irecruitment home page for managers and recruiters. As a system administrator, complete the following steps to enable the Export column on the OAF page: 1. Identify the table for icalendar export support. This example uses the Oracle irecruitment home page for managers and recruiters. You learn how to enable the Export column in the Interviews table: 2. Get the required information about this page by clicking the About this Page link. You must get the following information: a. View Object Instance: In this example, it is MyInterviewsVO b. View Attribute Names for the My Interviews table that form the data required for building icalendar, for example, Start Date, Location. 4
3. Click the Return to Page: irecruitment Manager Home Page link to navigate to the Home page. 4. Click the Personalize Page link on the Home page. 5. On the Personalize Page: irecruitment Manager Home Page, click the Create Item icon in the Table: Interview row. 5
6. On the Create Item page, select Image as the Item Style and set the properties to create the Export column. 6
Provide the following values: a. ID: ICalButton. If you are creating multiple tables to support icalendar on the same page, then you must enter a unique id for each icalendar item that you want to create. b. Image URI: export_enabled.gif c. Prompt: Export d. View Instance: Enter the view object instance of the underlying data source. In this example, enter: MyInterviewsVO. e. Set the Destination URI property to retrieve the calendar information as follows: OA.jsp?page=/oracle/apps/per/ri/calendar/webui/ICalPG&retainAM=Y&DTSTA RTDATE={@StartDateViewAttributeName}&DTENDDATE={@EndDateView AttributeName}&DESCRIPTION={@DescriptionViewAttributeName}&LOCA TION={@LocationViewAttributeName}&SUBJECT={@SubjectViewAttribute Name} Destination URI for the example: OA.jsp?page=/oracle/apps/per/ri/calendar/webui/ICalPG&retainAM=Y&DTSTA RTDATE={@StartDate}&DTENDDATE={@StartDate}&DTSTARTTIME={@ StartTime}&DTENDTIME={@EndTime}&DESCRIPTION=Interview%20of%2 0{@ApplicantName}&LOCATION={@Location}&SUBJECT=Interview%20of %20{@ApplicantName}&DTTIMEFORMAT=HH:mm If you want literal strings as a part of calendar event attribute, ensure that these words follow the URL encoding standards. In the example: the Description will be: DESCRIPTION=Interview%20of%20 Here %20 is used for space. Writing only Interview of would cause error. You can use similar steps to configure the OA:AdvancedTable & Form-layout elements. For information on how to configure, see: Oracle Application Framework Personalization Guide After you enter the required values click Apply to create the Export column. Setting Parameters in the Destination URI: You define the parameters to specify the data that you want to export. These parameters will be used as source of information for building the icalendar file. E.g.: DTSTARTDATE= {@StartDate} 7
Here StartDate is the ViewAttribute that contains the start date of the event to be generated. Mandatory parameters: You must set the following parameters: 1. DTSTARTDATE Start date of the event 2. DTENDDATE End date of the event [If date fields are implemented as DataType=Date, then you need not set the DTDATEFORMAT parameter]. Other parameters: 1. DTSTARTTIME Start time of the event 2. DTENDTIME End time of the event If time fields and date fields refer to the same view attribute you must provide the same view attribute in time and date parameters: DTSTARTTIME, DTSTARTDATE or DTENDTIME, DTENDDATE. In this case you need not provide DTTIMEFORMAT. Note: Here it is important to note that if the VO attribute being passed to time parameter is of type DATE then a transient attribute of type TIMESTAMP needs to be created and passed to time parameter. This issue is tracked in bug: 7319415. If time information of event is not provided it will be treated as a day event. 3. SUBJECT Defines a short summary or subject for the calendar component. Maximum Length: 150 characters. 4. DESCRIPTION Provides a more complete description of the calendar component, than that provided by the "SUBJECT" property. Maximum Length: 450 characters. 5. LOCATION Defines the intended venue for the activity defined by a calendar component. Maximum Length: 150 characters. 6. DTDATEFORMAT Java format of the date data. [In case date field is not implemented as DataType=Date you need to set DTDATEFORMAT] 7. DTTIMEFORMAT Java format of the time data. [In case time field is not implemented as Type=TimeStamp you need to set DTTIMEFORMAT] 8
8. ACCESS Defines the access classification for a calendar component. Valid values are PUBLIC, PRIVATE, CONFIDENTIAL, default being PUBLIC. 9. UI_TIME_ZONE If you want to force certain time zone as time zone for current time settings use UI_TIME_ZONE parameter. If User Preferred Time zone is used and time seen on screen is as per these settings you need not set UI_TIME_ZONE parameter. For valid values use query SELECT * FROM FND_TIMEZONES_VL. Value to be used is column TIMEZONE_CODE. 10. IGNORE_TIME_ZONE Y/N. Default N. [If you want the icalendar generated to ignore time zone, then set IGNORE_TIME_ZONE=Y. Note that in this case the event generated will show same time irrespective of time zones.] 11. METHOD Default value for parameter METHOD is PUBLISH. If REQUEST is used, MAIL_TO parameter must be set.) 12. MAIL_TO Defines the email Id to whom response will be sent for given event. 13. PRIMARY_KEY Used to build UID for the event. Should be unique for each event Viewing the Export Column in the My Interviews Table Navigate to the Home page and view the Export column in the My Interviews table: Managers or recruiters can click the Export icon to download the calendar details of their interviews. 9
Screenshot of the Export Feature Screenshot of Calendar Details on the Mail Application 10
Configuring the icalendar File as an Attachment with Notifications Using the Workflow configuration, system administrators can enable the workflow notifications to send icalendar file as attachment along with the notification details. Configuring the Workflow to send icalendar file as Attachment System administrators must complete the following steps to configure icalendar files to be sent as an attachment: 1. Open the workflow for which the calendar file needs to be attached. 2. Create an Item Attribute with following parameters: Type=Document Frame Target=New Window Example: Calendar Attachment (Internal Name= ATTACHMENT) Item Attribute 11
3. Add this item attribute to message of the notification that needs to be attached with calendar file. (This can be done by creating new attribute in Message or by drag drop from the item type level. Ensure that Attach Content check box is checked.) Example: Calendar Attachment 12
4. Create Item Attributes in workflow, which will contain the data that is to be used for creating the calendar file. E.g.: CAL_DTSTARTDATE. 13
5. Ensure that item attributes created in step 5 are initialized before notification activity is invoked. wf_engine.setitemattrdate(itemtype => l_itemtype,itemkey => l_itemkey,aname => 'CAL_DTSTARTDATE' -- Internal Name,avalue =>SYSDATE); 6. Ensure that you initialize Calendar Attachment Item Attribute using following code: wf_engine.setitemattrdocument (itemtype=>l_itemtype, itemkey=>l_itemkey, aname=>'attachment' -- Internal Name, documentid =>'PLSQLBLOB:PackageName.ProcedureName/' l_itemtype '/' l_itemkey ); 7. Create a procedure PackageName.ProcedureName. a. The signature of this new procedure must be PROCEDURE ProcedureName (document_id,display_type IN VARCHAR2, document IN OUT BLOB IN VARCHAR2 14
,document_type IN OUT VARCHAR2) Example: This procedure must pick up data from item attributes. CAL_DTSTARTDATE:=wf_engine.GetItemAttrDate(itemtype=>l_itemtype, itemkey=>l_itemkey, aname=>'cal_dtstartdate'); Here this method will retrieve itemtype & itemkey using document id. (See step 6 document id parameter.) POSITION:=INSTR(STRINGIS, / ); l_itemtype :=SUBSTR(STRINGIS,0,POSITION-1); l_itemkey:= SUBSTR(STRINGIS,POSITION+1); b. Call appropriate procedure from PER_CALENDAR_UTIL (CALENDAR_GENERATE_ICAL overloaded function). Eg: PER_CALENDAR_UTIL.CALENDAR_GENERATE_ICAL (DTSTARTDATE =>CAL_DTSTARTDATE, DTENDDATE =>CAL_DTENDDATE, DTSTARTTIME =>CAL_DTSTARTTIME, DTENDTIME =>CAL_DTENDTIME, SUBJECT =>CAL_SUBJECT, LOCATION =>CAL_LOCATION, DESCRIPTION =>CAL_LOCATION, ICAL =>data ); c. Convert the data returned by the above procedure to blob and assign to the out parameter document. The following sample code can be used. document := to_blob(utl_raw.cast_to_raw(data)); d. Set document type as : document_type := 'text/calendar' ';name=event.ics'; event.ics refers to filename of the attachment. Parameter Settings You must set the following mandatory parameters: DTSTARTDATE Start date of the event DTENDDATE End date of the event Other parameters: DTSTARTTIME Start time of the event DTENDTIME End time of the event [Even if in the flow, date & time information is available in same variable, you need to pass it to both time & date parameters] 15
[If time information of event is not provided it will be treated as a day event.] DTTIMEFORMAT Database format of the time data. [In case time field is not implemented as DataType=Date, TimeStamp or Time you need to set DTTIMEFORMAT] SUBJECT Defines a short summary or subject for the calendar component. Maximum Length: 150 characters. DESCRIPTION Provides a more complete description of the calendar component, than that provided by the "SUBJECT" property. Maximum Length: 450 characters. LOCATION Defines the intended venue for the activity defined by a calendar component. Maximum Length: 100 characters. ACCESS Defines the access classification for a calendar component. Valid values are PUBLIC, PRIVATE, CONFIDENTIAL, default being PUBLIC. TIMEZONE If you want to force certain time zone as time zone for current data use TIMEZONE parameter. For valid values use query SELECT * FROM FND_TIMEZONES_VL. Value to be used is column TIMEZONE_CODE. IGNORE_TIME_ZONE true/false. Default false. [If you want the this icalendar generated to ignore time zone, then set IGNORE_TIME_ZONE=false. Note that in this case the event generated will show same time irrespective of time zones.] METHOD Default value for parameter METHOD is PUBLISH. (If REQUEST is used, MAIL_TO parameter must be set.) MAIL_TO Defines the email Id to whom response is intended to be sent for given event PRIMARY_KEY Used to build UID for the event. Should be unique for each event 16
Samples of icalendar Files Oracle irecruitment Interview Details BEGIN:VCALENDAR VERSION:2.0 PRODID:-//ORACLE//Ical Builder//EN METHOD:PUBLISH BEGIN:VEVENT DTSTART:20090507T150000Z DTEND:20090507T170000Z DESCRIPTION:Interview of Brown\, John SUMMARY:Interview of Brown\, John CLASS:PUBLIC LOCATION:New York City UID:DTS20090507150000ZDTE20090507170000Z DTSTAMP:20090505T013919Z END:VEVENT END:VCALENDAR Oracle SSHR Absence Details BEGIN:VCALENDAR VERSION:2.0 PRODID:-//ORACLE//Ical Builder//EN METHOD:PUBLISH BEGIN:VEVENT DTSTART;VALUE=DATE:20060106 DTEND;VALUE=DATE:20060107 DESCRIPTION:Leave of type Vacation:Approved SUMMARY:Vacation CLASS:PUBLIC LOCATION:Vacation UID:DTS20060106DTE20060107 DTSTAMP:20090504T230321Z END:VEVENT END:VCALENDAR 17
Configuring the icalendar Export Feature in Oracle HRMS Applications June 2009 Authors: Vinod Viswanathan, Somshekher Badiger, Gowri Arur Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: Phone: +1.650.506.7000 Fax: +1.650.506.7200 oracle.com Copyright 2007, Oracle. All rights reserved. This document is provided for information purposes only and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission. Oracle, JD Edwards, and PeopleSoft, are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. 18