Configure a PeopleSoft instance to point to an ODA Channel/Skill

This post will cover the PeopleSoft configuration required to enable a delivered Chatbot and point to the ODA Channel/Skill.

PeopleBook References:
Creating Bot Definitions
Adding Chatbot to Application pages

PeopleBooks is self explanatory. Here are a few additional items that I found useful.

Configuring the Application Service

As delivered, both the service operations (PTCB_APPL_SVC_GET.v1 and PTCB_APPL_SVC_POST.v1) associated with the delivered REST - Chatbot Application Service - PTCB_APPL_SVC use 'Basic Authentication and SSL' as the 'Req Verification' option.

For example:

In my case, because I am using a HCM 9.2 - PI 31 instance running on OCI (created by PeopleSoft Cloud Manager) as a demo/proof of concept, I did not setup SSL. To workaround the SSL issues, I set the 'Req Verification' property to 'Basic Authentication' for both service operations.

Security to access the Bot Definition

While testing, I found that when I opened my 'Absence Assistant' chatbot, it would open the modal window but it would keep spinning endlessly without loading anything. I did not find any errors on the Browser Console either.

Note: The Chatbot window spinning could happen due to several reasons.

In this case, the issue was that the current PeopleSoft user did not have access to the Bot definition. We can provide this by adding the following Role that we used to setup the Bot definition.

Testing the Chatbot

I learnt that using the delivered JPATTERSON userid in HCM 9.2 - PI 31 was very handy because the user already had the necessary absence information setup!

Configuring the delivered Skill in the ODA instance

This post will cover some tips and lessons that I learnt while setting up the delivered Skill HGA_CHAT_ASST(1.0) in my ODA instance. It also covers a few items that are not very obvious when we refer PeopleBooks documentation. Before we proceed it is assumed that we already have an ODA instance created.

PeopleBooks Reference: Importing and Setting up a Delivered Skill

Delivered Skill location

The delivered absence Skill will be located in the following location.

<PS_APP_HOME>/setup/chatbot/

In my case, since I am using a HCM 9.2 - PI 31 running on OCI (created by PeopleSoft Cloud Manager), the Skill - HGA_CHAT_ASST(1.).zip was located here.

/u01/app/oracle/product/pt/ps_app_home/chatbot/

We simply need to download this to a local machine (PC/laptop) and use it in the next step.

Importing the delivered Skill to ODA

This step is self explanatory. Here are some screenshots that will further assist you with this activity.

Select Skills from the Digital Assistant Designer UI menu.

Next, upload the delivered Skill HGA_CHAT_ASST(1.0).zip using the Import Skill button. Once the import process completes, we will see the 'Absence Assistant' Skill in the list (as shown above).

Note: During the import process, we may see the following error/warning. I was told that this can be ignored. And it was true! It did not cause any issues.

Clone Delivered Skill

As always, it is best practice to maintain a copy of the delivered Skill so that we can refer back to it if necessary. So, as advised in PeopleBooks, we need to clone the 'Absence Assistant' Skill and create a copy of our own. In my case, I named my copy 'Absence Assistant Skill'.

Configuring the Delivered Skill to point to our PeopleSoft Environment

Once we clone the delivered Skill, the next step is to configure it to point to our PeopleSoft environment. Our PeopleSoft environment can be running either on the Cloud (OCI) or on premises. In my case, my HCM 9.2 - PI 31 is running on OCI.

ODA > Digital Assistant Designer UI > Menu > Development > Skills (select your copy of the Skill) >  Settings > Configuration (Tab) > Custom Parameters

If we scroll down further on this page, we will find all the delivered custom (oxymoron?) parameters.

We can leave the HGAmarket, HGAnode and HGAportal as delivered in the 'Absence Assistant' Skill.

We need to use the <Proxy User> and password (which we created before getting started) to configure the PSHCMuserid and PSHCMpassword parameters.

Refer PeopleBooks for more details on how to create this userid:
Understanding Security for Chatbot Integration Framework

Next, we need to ensure that we configure PSHCMbaseurl parameter to point to our Integration Broker REST end point of the delivered PTCB_APPL_SVC.v1 service.

End Point Format:
https://<server>:<port>/PSIGW/RESTListeningConnector/<node>/PTCB_APPL_SVC.v1

server: Integration Broker hostname
port: Integration Broker port
node: Default Local Node

In my case, since I am running my HCM 9.2 - PI 31 instance on OCI and I did not setup SSL, I used http instead of https. Also, since I did not  have a virtual address that pointed to my server, I simply used the public ip address of my HCM instance. So, my end point was in the following format.

http://1.2.3.4:8000/PSIGW/RESTListeningConnector/PSFT_HR/PTCB_APPL_SVC.v1

Creating and Configuring an ODA Channel

PeopleBooks: Creating the Web Channel

Once our Skill is created and configured appropriately, we need to create a Channel and configure it to route to our Skill. This step is briefly mentioned in PeopleBooks but I missed the routing step because it was not very obvious and found out the hard way. Here are the steps to create and configure a Channel.

ODA > Digital Assistant Designer UI > Menu > Development > Channels > Create Channel

Next, we need to ensure that the Channel is enabled and that it is routing to the Skill we configured in the previous step. Finally, we need to note down the App Id. We will use this while configuring our PeopleSoft application to point to this ODA Channel.

Setting up the Oracle Digital Assistant Instance

This post covers some tips on setting up an Oracle Digital Assistant (ODA) instance especially for those who are using an Oracle Cloud trial account.

The assumption here is that we already have an Oracle Cloud trial account created. Here is a resource that provides additional information on how to procure a free trial account.

https://docs.oracle.com/en/cloud/get-started/subscriptions-cloud/csgsg/request-trial-subscription.html

Setting Up the ODA Instance

From our OCI Homepage, we can use the menu to navigate to Oracle Digital Assistant. But I found that there are two Digital Assistant options available as shown in the screenshot below. For the purposes of the PeopleSoft - ODA integration, we need to use the Digital Assistant under the Platform Services menu.

Potential issue with Free Trial Service Limits

When I was trying to create an ODA instance, I kept running into the following error.

PSM-LCM-01002 One or more validations failed. See the included validation. See the included validation errors for details.

[No matching systems found to create the service]

After some trial and error, I found that I could workaround this validation error by selecting a different region other that Ashburn. I was able to successfully create an ODA instance in the Pheonix region as shown below. I believe I ran into this error because I already had my PeopleSoft Cloud Manager instance and my HCM 9.2 - PUM Image 31 instance running in the Ashburn Region. I may have run into this error because of Service Limits imposed on OCI free trial accounts.

You should also receive an email to confirm that the ODA instance was created successfully.

Once the ODA instance is ready, we can access the Digital Assitant Designer UI using the menu as shown below.

Setting Up the PeopleSoft Web Server for ODA

This post will describe the steps to setup the PeopleSoft web server for Oracle Digital Assistant (ODA) - Chatbots. This post will also go through some tips and tricks that are not covered in PeopleBooks (at the time of writing).

PeopleBook Reference: Setting Up the Web Server for the Chatbot

Creating a new 'external' site on the web server domain

This step should be pretty straight forward for a PS Admin. But for someone like me who does not have a lot of PS Admin background, it was a struggle to find the right information and create a new 'external' site on the PeopleSoft web server domain. Based on my experience creating this new site, I wrote a separate blog post to cover this topic and demystify some of the admin configuration and jargon.

Refer: Create new (external) site in a PUM Image

Note: This information is not in PeopleBooks but I was told that the new site can use the same web profile as the other existing site for regular PIA access. Since, my current environment is a HCM 9.2 - PI 31 created on OCI by PeopleSoft Cloud Manager, the delivered default site for the PIA is peoplesoft01 and it uses the delivered PROD web profile. So, I created my 'external' site using the PROD web profile using the procedure described in the blog post referenced above.

Copying the Web SDK (delivered ochatjs folder) to the new 'external' site

This step is also self explanatory. The one challenge I had was that my PUM image (HCM 9.2 - Image 31) was running on Oracle Cloud Infrastructure (OCI). I generally use WinSCP to perform file transfers, etc. to the servers. The default user 'opc' (Oracle Public Cloud) which we use to connect to OCI via WinSCP does not have the appropriate privileges to copy the Web SDK to the 'external' site.

Graham Smith, Oracle ACE Director, from Cedar Consulting UK showed me a neat trick to use WinSCP, login as the default user 'opc' and then switch to 'root'. I am forever thankful to him for this because it helps avoid the use of command line for such tasks.

How to use WinSCP to connect to PS Servers on OCI as root?

Use SCP Protocol, 'opc' user, set the private key in the authentication settings and use "sudo su -" in the SCP/Shell settings.

Copying the ochatjs folder (web SDK) to the external site

Source: ochatjs.zip file located in <%PS_APP_HOME%>/setup/chatbot

In my case, since I am using a HCM 9.2 - PI 31 running on OCI (created by PeopleSoft Cloud Manager), the ochatjs.zip was located here.

/u01/app/oracle/product/pt/ps_app_home/setup/

Destination: <PIA_HOME>\webserv\<DOMAIN_NAME>\application\peoplesoft\PORTAL.war\external\

In my case, since I am using a HCM 9.2 - PI 31 running on OCI (created by PeopleSoft Cloud Manager), the extracted ochatjs folder was placed here.

/u01/app/oracle/product/pt/ps_cfg_home/webserv/WEBSERVER01/applications/peoplesoft/PORTAL.war/external/

Verification

We can verify the success of the web SDK installation by accessing the following URL on a web browser.

https:\\<your server name>:port\external\ochatjs\loader.json

DIY PeopleSoft Chatbots

Chatbots are here in PeopleSoft! The PeopleSoft Chatbot Integration Framework was delivered via Enterprise Components in various Applications (HCM, FSCM, CS, etc.). Utilizing this framework, HCM delivered the 'Absence Assistant' Chatbot in PUM Image 31.

Using an Oracle Cloud trial account, I went through the exercise of spinning up a HCM 9.2 - PI 31 instance on Oracle Cloud Infrastructure (OCI) using PeopleSoft Cloud Manager, creating an Oracle Digital Assistant (ODA) instance on OCI, uploading the delivered 'Absence Assistant' Skill to ODA, configuring the ODA Skill/Channel to point to the HCM instance and likewise configuring the HCM instance to point to the ODA Skill/Channel!

Here is a demo of the 'Absence Assistant' Chatbot in action!

Hat Tip

I am very thankful to all Oracle PeopleSoft and ODA Product Managers, PeopleSoft Development team and PeopleSoft Support team for answering all my questions and pointing me in the right direction. Too many to list them all but they know who they are! Their insights are much appreciated.

Before you get started

Use HCM 9.2 PUM Image 32

If you are just getting started, I would highly recommend you to start with HCM 9.2 PUM Image 32. I started my proof of concept on PUM Image 31 and ran into several issues that were fixed in PI 32. Among other things, I had to pull out certain bugs (30151468, 30151584, 30150506) and the web SDK (ochatjs.zip) from PI 32 and apply them to my PI 31 instance. You will save yourself a lot of time simply by starting with PI 32!

Setup the <Proxy User> userid in PeopleSoft

Before we go any further, it would be a good idea to go ahead and setup the <Proxy User> userid in the HCM instance. This will be needed in the ODA Skill configuration.

PeopleBooks: Understanding Security for Chatbot Integration Framework

Configuration Steps - Blog Series

The following steps detail all the configurations that are necessary to setup the PeopleSoft - ODA Chatbot integration. This series of blogs address several practical tips, tricks and lessons learnt that might not be covered in PeopleBooks and other documentation.

Step 1: Setup PeopleSoft Web Server for ODA
Step 2: Setup the ODA instance on OCI
Step 3: Configure the delivered Skill in ODA
Step 4: Configure PeopleSoft to point to the Skill/Channel in ODA

Create new (external) site in a PUM image

This post will describe how we can create a new site in a PIA domain without modifying any existing configuration settings. As an example, we will focus on a delivered PUM image (HCM 9.2 PUM Image 29) installed as a VirtualBox instance.

If you are a PeopleSoft Administrator, then this might be second nature to you. But for others who only venture into the dark side occasionally, it might seem like a complex task.

Why?

Many of us download a PUM image (PI) and install it as a VirtualBox instance on our laptops/PCs to evaluate the latest features in the application releases or in some cases the PeopleTools releases.

Let us say we want to evaluate the latest features in the HCM 9.2 - External Candidate Gateway, FSCM 9.2 External Supplier Portal or even the latest HCM 9.2 - Absence Assistant Chatbot functionality. Unfortunately, the delivered PUM images do not contain these external sites by default, so in order to perform a true test, we might need to create a new (external) site in a PUM image and set it up appropriately.

How?

I am going to describe how I successfully created a new site in a PUM image (of course involving a lot of trial and error). I am sure there are more efficient ways to perform this task and I look forward to learning from your comments/feedback. I already know based on discussions with Dan from psadmin.io that we could also create a new site using DPK.

Anyway, after reviewing documentation in PeopleBooks, I found the following resources as a starting point.

Install Guides
PeopleSoft 9.2 Application Installation on Oracle (PeopleSoft PeopleTools 8.57)

"Task 15-1: Installing the PeopleSoft Pure Internet Architecture in Silent Mode" in the Installation Guide provides documentation on how to install various components of the PIA.

Based on this documentation, we can see that we simply need to update a response file with appropriate configuration settings and then kick off the command line to execute the site creation process "silently".

Updating resp_file.txt

"Task 15-1-1: Editing the Response File" mentions that this response file will be located here:
PS_HOME/setup/PsMpPIAInstall/scripts

But on a PUM image (HCM 9.2 - PI 29), I found it one level up.

I made a copy of this resp_file.txt and edited it to suit my needs.

External Site: ps_ext
Web Profile: KIOSK

Here is a copy of the resp_file.txt file that I used containing with only the parameters that are necessary.

Here are some items to keep in mind.

Where is the Weblogic Home directory?

I had no idea and could not find any documentation that pointed to this information. After some trial and error, I found that the Weblogic Home directory (at least on a PUM image) should be as follows.

BEA_HOME=/opt/oracle/psft/pt/bea

Note: If we use PeopleSoft Cloud Manager to create the PUM image instead of using the VirtualBox approach, then our Weblogic Home directory would be as follows.

BEA_HOME=/u01/app/oracle/product/pt/bea

Install action and Domain type

Use ADD_SITE and EXISTING DOMAIN as follows.

INSTALL_ACTION=ADD_SITE
DOMAIN_TYPE=EXISTING_DOMAIN

What is the App Server Name and JSL Port (particularly on a PUM image)?

I ended up accessing PS Admin (via Putty) and reviewing the configuration on the existing delivered site to pick up this information. The assumption here is that, the new site will also connect to the same App Server.

PeopleSoft PIA Administration > Web (PIA) Domain Administration > Administer a domain > peoplesoft (default domain for PUM image) >Administer a site > ps (existing delivered site) > Configure this site

We can use the Application Server Connect String as the PSSERVER parameter value as shown below.

PSSERVER=pi029.hcm92.edu:9033

Site Name and Web Profile

Provide the name for the new site as well the web profile that we want to use.

WEBSITE_NAME=ps_ext
WEB_PROF_NAME=KIOSK

Other items

The rest of the parameters in the resp_file.txt are either self explanatory or passwords.

Executing command line to create new site

Simply change the directory to the PsMpPIAInstall folder and execute the setup.sh script in silent mode passing in the resp_file.txt location as a parameter.

Demo

Delivered Site (ps) on PUM Image

New Custom/External Site (ps_ext)

Additional Resources

HCM9.2-CG: How To Configure The External Candidate Gateway URL On PUM16+ When The External Link Is Invalid (Doc ID 2145957.1)

Branding - Overriding the browser default :focus Selector

This post is based on a question that was recently asked here.

Question

"When user uses Keyboard instead of mouse, when they are using the TAB key on the homepage, the Home button and other button on the banner will be highlighted by the white dotted lines, and when it comes to the tiles, they are also highlighted by that white dotted line, but the visibility of that dotted lines is very minimal around the tiles, is there a way we can change the color of that dotted lines using the macro set or style sheet."

Demo

 
This 'dotted lines' is added by the browser for accessibility reasons and it could vary depending on the type of the browser. I found couple of excellent blog posts on this topic which are listed below.

https://www.kirupa.com/html5/changing_the_default_focus_styles.htm
http://outlinenone.com/

Overriding the browser default :focus Selector

Fluid - Global override

We simply need to add the following CSS to the 'Global Override Style Sheet' used in our current theme.

In this example, the 'Global Override Style Sheet' used in the current theme is shown below.

Demo

Fluid - Tile override

Let us say that we only want to change the :focus on the Tiles, then we can simply target the Tile elements by adding the following CSS instead to the 'Global Override Style Sheet' used in our current theme.

Demo

Classic - Global override

Similarly, if we want the same global override in Classic, we can simply add the following CSS as an 'Additional Style Sheet Object' in the 'Branding System Options' page.

Demo

Event Mapping PeopleCode in the context of a Component Interface

Is your Event Mapping PeopleCode not firing when executed via a Component Interface?

Check out this My Oracle Support Community (MOSC) forum thread for the solution:

https://community.oracle.com/message/15470895

Also, review the following My Oracle Support (MOS) Doc ID 2354155.1:
E-CI: Event Mapping Framework Not Working For Component Interface (Doc ID 2354155.1)

Page and Field Configurator - Migration Tips

Page and Field Configurator is another great framework delivered by Oracle to enable customers to isolate/eliminate customizations. Alternatively, it provides a method to make such changes as non-invasive configurations.

Let us take an example of a simple requirement where we need to update the label of a field (URL) on a page/component (URL_TABLE).

Instead of making this change on the Page object via App Designer as a customisation, we can simply configure this using the 'Page and Field Configurator'.

Navigation: Enterprise Components > Page and Field Configuration > Page and Field Configurator

Even after we make the changes as shown in the image above, we will notice that the URL label will continue to refer to the delivered value. This is because we are missing a step in the 'Page and Field Configurator' process! That is, we need to 'Map Configuration to the Portal Registry'. This basically means that we need to apply these configurations to the Component peoplecode events via the Event Mapping Framework. In case you did not know already, 'Page and Field Configurator' actually leverages Event Mapping framework behind the scenes!

Result

Once we push the 'Apply Configuration' button, we will now notice a new column 'Review/Edit Mapping' as shown in the image below. If we click on the 'Review/Edit Mapping' hyperlink, we will be taken to the corresponding Event Mapping configuration associated with the content reference of this component.

After the 'Map to Portal Registry' step is completed, we can now see the configuration take effect on the page.

Migration

Next, let us move on from the implementation phase to the release management phase. It is great that we can eliminate customization of managed objects and use configurations instead. But we need to find a way to automate the configuration process when we get ready to move the change to other environments (TEST, UAT, PROD, etc.). Simply making these changes online as a manual step will likely make it inconsistent and prone to errors.

To facilitate this configuration migration, a delivered ADS (Application Data Set) definition called EOCC_CONFIGURATION is available. This data set enables us to export the configuration data associated with the 'Page and Field Configurator' and import it to the desired target environment using Data Migration Workbench.

Here is how we create the Data Migration Workbench project using the EOCC_CONFIGURTATION data set.

PeopleTools > Lifecycle Tools > Migrate Data > Data Migration Workbench

Tip

The Data Migration Workbench project is now ready to be 'Saved' and 'Copied to File'/exported. But if we just use this data set, we will only be moving the 'Page and Field Configurator' data and will need to manually use the 'Apply Configuration' functionality on the 'Map to Portal Registry' page to generate the Event Mapping configuration on the target environment. This additional manual step basically defeats the original purpose of automating the configuration!

To eliminate this additional manual step ('Map to Portal Registry'), we can simply include the 'Event Mapping' configuration using the RCF_SERVICES data set in the same Data Migration Workbench project as follows.

Now, we are ready to 'Save' the project and 'Copy to File' to export the configuration data ('Page and Field Configurator' and 'Event Mapping') from the source environment.

Importing Data Migration Workbench Project

Here are the instructions to import the Data Migration Workbench project in the desired target environment.

Note: The following assumes that appropriate 'File Locations' are setup in both the source and target environments to be able to create and access the project (copied to file).

Navigation: PeopleTools > Lifecycle Tools > Migrate Data > Data Migration Workbench

By default the MigrateData Approval ProcessID will change the project status to 'Evaluating Approval'. We can use the 'Work Approvals' link which is shown in the image above to review and approve this migration.

Once we approve the migration, the project will change status to 'Scheduled for copy from file' and eventually to 'Copy from file succeeded' if there are no errors/issues with the migration.