Deploying PeopleSoft Campus Solutions Digital Assistant

A proxy user is necessary to integrate the digital assistant with application services in the Chatbot Integration Framework.

1. As an administrator, navigate to PeopleTools > Security > User Profiles > User Profiles > User Profiles.

2. Click Add a New Value.

3. In User ID, enter PSFTPROXY, then click Add.

4. On the General page, in Symbolic ID, select SYSADM1.

5. In New Password, enter a password.

6. In Confirm Password, enter the same password you provided.

7. Deselect Password Expired.

8. Click ID.

9. Make sure ID Type is set to None.

10. Click Roles.

11. In User Roles, add the following roles:

    • PTCB_USER

    • EOCB Service User

    • EOCB Admin User

    • EOCB Client User

12. Click Save.

Once you have an ODA subscription and have created a proxy user, you can install the digital assistant.

1. Log in to your ODA instance, then click , then select Development > Store.

2. Search for the digital assistant. For example, to get PeopleSoft Campus Solutions assistants, search for "Campus Solutions."

3. In the tile of the skill or assistant you want to add, click , then select Pull.

Note that the process to install skills is similar to installing a digital assistant.

Extending a digital assistant enables you to customize it in several ways. When a new version appears in the Skill Store, you can transfer your customizations to the new version by rebasing.

Not that you won't be able to modify an installed assistant or skill directly, but you can create an extension of it and then modify that extension. For more information on extending skills or digital assistants, refer to the ODA documentation. There you'll find details about what extending a skill or digital assistant is for, and the difference between cloning and extending.

Here's what you need to do to extend a digital assistant:

1. Click , then select Development > Digital Assistants.

2. Search for the digital assistant.

3. In the tile for the digital assistant you want to extend, click , then select Extend.

4. Fill out Display Name and Name. You should provide a display name and name that's different from the name of the digital assistant you're extending.

5. Click Extend.

6. Click the tile of the new digital assistant, and note the skills included in it.

When you extend a digital assistant, the base skills that were in the original version are carried over to the extended version of the digital assistant.

After extending the digital assistant, you have to extend the base skills that it uses. Doing so lets you change the configuration of the base skill.

You will have to run through these steps for every skill in the extended digital assistant.

1. Click , then select Development > Skills.

2. Search for the skill.

3. In the tile for the skill you want to extend, click , then select Extend.

4. Fill out Display Name and Name. Similar to what you did for the digital assistant when you filled out the name fields, make sure you provide names that are different from the base skill you're extending.

5. Click Extend.

After extending the skill, add them to the digital assistant you extended.

1. Click , then select Development > Digital Assistant.

2. Look for the extended digital assistant, then select it.

3. Click , then click Configurations.

4. Look for the System Intents Mappings section.

5. Note down the values in "Digital Assistant Custom UnresolvedIntent Skill" and "Digital Assistant Custom UnresolvedIntent State." You will need them later.

6. In Digital Assistant Custom UnresolvedIntent Skill, select No Selection. Doing this also automatically sets Digital Assistant Custom UnresolvedIntent State to the same value.

7. Click . You should see all the base skills in the extended digital assistant.

8. To replace a base skill with its extended version, you need to perform the following actions for each skill contained in the digital assistant:

   1. Click the skill.

   2. Click Update Skill.

   3. From the Update Skill dialog, select the new version of the skill.

   4. Click Update Skill.

9. Click , then click Configurations.

10. Go to the System Intents Mappings section.

11. In Digital Assistant Custom UnresolvedIntent Skill, select the extended Grade skill.

12. In Digital Assistant Custom UnresolvedIntent State, select or enter ssr_unresolved.

Channels serve as messaging platforms, which lets users access the skill or digital assistant. A single digital assistant or skill can have several channels configured to allow access to it. This setup enables the digital assistant or skill to run on different services simultaneously.

In this section, we're creating a Web channel. While creating the Oracle Web Channel, note down the Channel Id value generated that's generated. This value is added to the corresponding PeopleSoft bot definition in Creating Bot Definitions. The Client Authentication Enabled option should be disabled.

1. Click , then click Development > Channels.

2. Click Add Channel.

3. In Name, enter a name for your channel.

4. In Channel Type, select Oracle Web.

5. In Allowed Domains, enter the actual domain name of the production environment.

6. Make sure the Client Authentication Enabled switch is off.

7. Keep the default value in Session Expiration (minutes).

8. Click Create.

9. With your channel selected, click the Channel Enabled switch to activate the channel.

10. In Route To, select the digital assistant you extended.

11. Note down the value in Channel Id.

Setting up the bot definitions creates digital assistant clients in PeopleSoft, which then lets you use the digital assistant and skills.

1. From Campus Solutions, navigate to Enterprise Components > Chatbot Configurations > Chatbot Definitions.

2. From the General Configurations page, in Default Branding Template, keep the default value.

3. In ODA Server URI, enter the value that's part of the link to your ODA instance. For example, the link to your ODA instance will look something like this:

   https://<ODA_Server_URI>/botsui/home

   Get the value in the ODA_Server_URI portion of the URL, then place that value in ODA Server URI.

4. In Bot Definitions, click the Edit button that corresponds to the the Bot ID STU_CHAT_ASST.

5. On the Maintain Bot Definition page, in Bot Channel ID, enter the channel ID value that you took note of when you created the channel.

6. Save your changes.

The digital assistant can be launched on CS fluid pages. Based on the settings you defined on the Bot Definition page, the assistant can be launched as a tile or widget.

1. From Campus Solutions, navigate to PeopleTools > Portal > Structure and Content.

2. Click Add Content Reference.

3. On the General page, in Name, enter EOCB_STUCHATASST_FL_GBL.

4. In Label, enter a descriptive label for the digital assistant. For example, you can use "Student Assistant."

5. In Node Name, select SA.

6. In URL Type, select PeopleSoft Generic URL.

7. In Portal URL, enter c/EOCB_MENU_FL.EOCB_CLIENT_FL.GBL?BOTID=NEW_SKILL

   Make sure you replace NEW_SKILL with the Bot ID value from the Chat Definitions page. The value you enter will look like:

   c/EOCB_MENU_FL.EOCB_CLIENT_FL.GBL?BOTID=STU_CHAT_ASST

8. Click Security.

9. Make sure you select Author Access.

10. From Security Authorizations, in Permission List, select EOCB_CLIENT_USER.

11. Click Fluid Attributes.

12. In Image Name, select your preferred image.

13. In Display In, select Modal.

14. In Modal Parameters, enter:

    $Style@frame-pt_chatclientpage;bAutoClose@0;width@600;height@1000;

15. In Folder, select a folder to create a link to the tile repository. For example, you can select CS_SCC_STUDENT_SELFSERV (Student Self Service).

16. Save your changes.

Students or university staff would have to configure their homepage in order to launch the digital assistant. This means adding the tile where the digital assistant is configured to their homepage.

1. From Campus Solutions, click the Homepage Actions button, then click Personalize Homepage.

2. Click Add Tile.

3. Search for the label you assigned in Configuring the Tile (step 4), then click Add.

   If you entered "Student Assistant," then search for that.

4. Save your changes.

You should see the digital assistant on the homepage. Clicking the tile launches the digital assistant.

You would have to update the component package of a skill to interface with ODA's custom component service. This service is an active connection from the skill to the host server.

Note that you will have to perform this procedure for any new skills that you add to the digital assistant in the future.

1. Make sure you have these software:

   • Oracle Digital Assistant Bots Node.js software development kit (SDK) (bots-node-sdk), which you can get from GitHub.

   • Node.js 8.11.4, which you can get from https://nodejs.org. Install this for global access. Node Package Manager (npm) is distributed with Node.js.

2. To test if Node.js and npm are installed, open a terminal window and type these commands:

   node –v 
   npm –v

3. To verify your Oracle Digital Assistant Bots Node.js SDK installation, type the following command:

   bots-node-sdk -v

   The command should print the Oracle Digital Assistant Bots Node.js SDK version.

4. Log in to your ODA instance.

5. Click , then select Development > Digital Assistants.

6. Select the digital assistant to open its page. You will see the first skill on the list selected.

7. From the selected skill, click Go to Skill.

8. Click .

9. Download the package (.tgz) file, then update the environments.json file.

   1. Look for the package (.tgz) file you downloaded.

   2. Extract the contents of the file to your local drive.

   3. Extract the .tar file in the same folder that the package file is in.

      A package folder will appear.

   4. From the package folder, navigate to psft-lib > config.

   5. Open environments.json.

   6. Update the server, port, and node values in baseURL using the information from your PIA server.

      "baseURL": "http://<server>:<port>/PSIGW/RESTListeningConnector/<node>/PTCB_APPL_SVC.v1"

      So, if your PIA URL looks like this:

      http://server.com:8000/psp/s17cbguix/?cmd=login&languageCd=ENG&

      Then your baseURL value will look like this:

      Field	Value
      <server>	server.com
      <port>	8000
      <node>	S17CBGUI (this alphanumeric text should be capitalized)

      If your PIA URL uses http, then the baseURL should also use http. If it uses https, then use https.

   7. From your computer, launch the command prompt.

   8. Go to the directory where the package folder is stored, then from the command prompt enter npm pack.

      This creates a package with the updates you made and a new TGZ file is saved in the same package folder.

      In the future, if you wish to update the component package file, make sure you delete the existing .tgz file before you run the npm pack command.

10. Upload the package (.tgz) file you updated.

    1. Go back to your browser where you have your ODA instance open.

    2. From the Components page of the digital assistant (the one you accessed from step 8), make sure you're on the page of the skill you downloaded the package file from.

    3. In Package File, click the Change package file icon, then locate the .tgz file you created to upload it to the skill.

       The upload is complete when the Status indicates Ready.

11. Repeat steps 7 to 10 for the other skills.

    Note: Skip the Small Talk skill.

Training your digital assistant or skill facilitates goal-oriented conversations between users and a machine. This means the machine must understand natural language. This understanding isn't semantic, but a prediction the machine makes based on a set of training phrases.

1. From your ODA instance, click , then select Development > Digital Assistants.

2. Click the extended digital assistant.

3. Select a skill from the assistant's list of skills, then click Go to Skill.

4. Click .

   The red indicator on the train icon means the skill needs to be trained.

5. From the dialog that appears, select Trainer Tm, then click Submit.

6. Repeat steps 3-5 for the other skills in the digital assistant.

7. After training all the skills in the digital assistant, navigate again to your extended digital assistant, then click the corresponding train icon.

8. From the dialog that appears, select Trainer Tm, then click Submit.

In your ODA instance, navigate to the extended digital assistant's page, then update the parameters of each skill using the information from your PIA server. Start with the Enrollment Skill.

If your PIA URL looks like this:

http://server.com:8000/psp/s17cbguix/?cmd=login&languageCd=ENG&

Then the parameters should look like this example:

If your PIA URL uses http, then the domain base URL and PSauthurl should also use http. If it uses https, then use https.

Do the following to test the chatbot functionality.

1. Log in as the student or university staff whose homepage was configured in Adding the Tile to the Homepage.

2. Click the chatbot Student Assistant.

   The chatbot launches. You should be able to engage the chatbot using the skills that were added to it. For example, you can find the enrollment dates of the logged-in user.

This section lists issues you might run into when using the digital assistant.

Assistant isn't loading

Check if the ODA server URI and Bot channel ID are correct. See Creating Bot Definitions.

Assistant isn't responding to a message

• Make sure the channel is routed to the appropriate skill or digital assistant.

• Turn off client authentication.

• In Allowed Domains, enter * to allow requests from all domains.

  You could also restrict the value to a PeopleSoft domain.

See Creating a Channel.

Error messages

Error	Solution
Oops! I'm encountering a spot of trouble. Please try again later.	ODA may be down. Wait until ODA is up and running.
Oops! Something went wrong while connecting to PeopleSoft. Check your network connection, or contact your system administrator.	Try the following solutions: In ODA, check the yaml code of the skill for syntax errors, and correct these errors if they exist. Navigate to PeopleTools > Utilities > Administration > Message Catalog. Check if any of the message catalog numbers specified in the yaml code of the skill exist in PeopleSoft. Navigate to PeopleTools > Security > User Profiles > User Profiles. Make sure that the user PSFTPROXY exists, isn't locked out, and has the appropriate roles. If it's locked out, unlock the account and reset the password. If you reset the password, you need to run through Updating the Custom Component Package of a Skill again to update PSFTPROXY's password. Ensure the environment's JSON file has the correct URL, user ID, and password for PSFTPROXY. See Updating the Custom Component Package of a Skill. In ODA, ensure that the parameters of the skill in the digital assistant are correct. See Connecting to a PeopleSoft Application Service.
Failed to sign in! Please check your credentials and try again.	This error appears either because the skill doesn't have the EOCB_CLIENT_USER or an incorrect role is assigned to it. To assign the role: From Campus Solutions, navigate to PeopleTools > Integration Broker > Application Services > Administration > Application Services Security. In Bulk Permissions, look for the appropriate App Service ID, Index, Method, and Root Resource of the skill, then click the corresponding Set Security. Make sure EOCB_CLIENT_USER is assigned, and that it has full access. If it isn't assigned, then add it. Save your changes.