Oracle PaaS enables building extensions to HCM cloud to provide custom functionality addressing specific business needs. These extensions can be built as bespoke Java web applications which are deployed in PaaS like JCS - SaaS Extension (JCS-SX) and can be embedded into HCM UI as a hyperlink or web page. Please refer to this link for some examples on SaaS extensions using JCS-SX.
When accessing the bespoke application from HCM application page, you might have to pass some information specific to the page to the bespoke application which could be used for further processing. This blog explains how to embed an external java web application into HCM UI as a hyperlink and pass context-specific parameters along with security token (JWT in this case) in the dynamic URL generated in Oracle HCM Cloud to the external application. For the sake of simplicity, the web application is just a simple JSP page which displays the values obtained from the HCM.
- The bespoke web application is deployed in JCS-SX that is associated with the HCM instance. Also if the external web page content is embedded into the region on HCM as a "Web Page", the web application should be manually configured to disable Framebusting by adding the following entry to the web.xml :
<description> Security precaution to prevent clickjacking - bust frames if the ancestor window domain (protocol, host, and port) and the frame domain are different. Options for this parameter are always and never.</description>
- A user account with a user ID identical to the logged-in Oracle HCM Cloud user's user ID is required to be created in JCS-SX. New user can be added by navigating to the "Users" tab on the "My Services" page and clicking on the "Add" button.
- HCM Cloud user should have administrative role like HCM Application Administrator to be able to edit application pages. Additionally users having access to “Source” view of the page can work with page layout components, this access can be enabled as shown below:
Note: All HCM development/customization activities should be performed in an activated sandbox.
Registering the external application with HCM
Before you can access the external application from within HCM, it has to be registered with HCM, this can be done using the “Manage Third Party Applications” option present under “Setup and Maintenance Page” as shown below:
Specify the full URL of the bespoke java application (up to the context root) and the application name in the “Create Third Party Application” page:
Define hyperlink to bespoke application from HCM Application Page
A link (named “Employee Details”) will be added to the “Employment Information” (Home -> My Team -> MyTeam -> <Select an Employee> -> Employment Information) page which points to the bespoke application deployed in JCS-SX. The following steps would enable to create and define this link:
1. Navigate to Employment Information page and click on “Customize Workarea Pages…” link under Administration category as shown below:
2. In the “Customize Page” window that comes up, select “Site” as the customization layer. Switch to the “Source” view of the page as shown below:
3. We will add the “Employee Details” link to the panel highlighted below. This panel can be selected by moving the cursor adjacent to “Years Since Last Promotion” heading.
4. Once the panel is selected, click on the “Add Content” button on the top left corner and click on the “+Add” button against the “Hyperlink” option from the “Components” category as shown below:
Note: If you want to embed the output of external page into a region in the HCM page, you can choose “Web Page” instead of hyperlink.
5. The hyperlink by default gets added as the first element in the panel with title “Click edit icon to define hyperlink”, you can move the hyperlink to the position of your choice within the panel.
6. Select “Click edit icon to define hyperlink” and click “Edit” on the top (adjacent to “Add Content”) to define the hyperlink properties as shown below:
7. Click on the “Secured Token” tab and then click on the “Create Secure Destination” (Key symbol) as shown below:
8. Select the name of the web application (specified when registering the application), specify the page that is being pointed to through this hyperlink (in this case it is empDetails.jsp) and give a name to the secured token that you want the JWT token to be tagged to.
Note: HCM Cloud generates a JWT token and assigns it to the key specified in the “Secured Token” field. In this case it is “jwt_tkn”. In the bespoke web application, the token can be fetched as a request parameter.
9. Click on the “Display Options” tab, You can edit the “Text” attribute and change the title of the hyper link, change it to “Employee Details” in this case.
10. On the “Display Options” tab click on the drop down arrow button adjacent to the “Destination” text box and select “Expression Builder”, an Edit box appears as shown below:
The URL configuration specified in the “Secured Token” tab is displayed in the text box:
Note that, ‘hcmapp’ is the name of the app we registered with HCM, ‘empDetails.jsp’ is the page this hyperlink would be pointing to and ‘jtw_tkn’ is the name given to the JWT token being passed.
11. The exposed attributes of the current page can be accessed from the “Binding Params” drop down. For example, when you select “Business Unit” attribute from the drop down, the expression for accessing the attribute value is populated in the text box as below:
12. You can identify expressions for the page attributes that needs to be sent along with the URL to the external web application and append them to the URL derived in step # 10 as shown below:
As depicted above, page attributes like person number, business unit name, and employer name are passed to the external web application in the URL.
13. Click on the “Close” button on top right corner to exit from the page customization view.
After the “Employee Details” hyperlink has been added to the page, the “Employment Information” page looks like below:
When you click on the “Employee Details” hyperlink, the web application deployed on JCS-SX opens up displaying the attribute values passed in the URL as follows:
This blog demonstrated the steps to access an external java web application from HCM UI as a hyperlink and pass context-specific parameters in the dynamic URL generated in Oracle HCM cloud to the external application deployed in JCS-SX. Please refer to this documentation for more details on page customization in fusion applications.
The views expressed in this post are my own and do not necessarily reflect the views of Oracle.