Create or obtain your IBM Container Software production entitlement key.
A production entitlement key is required to pull the container images that get deployed by the operator.
To create or retrieve your existing entitlement key, follow the instructions here.
-If extra assistance is needed, refer to this site.
+If you don't have an entitlement key at the above link, click the Add new key to create a new one or visit this link to create a new one.
+If extra assistance is needed, refer to this site. Note, the process here is not
Locate your existing key or create a new one and continue to the next step.
If extra assistance is needed, refer to this site.
+If you don't have an entitlement key at the above link, click the Add new key to create a new one or visit this link to create a new one.
+If extra assistance is needed, refer to this site. Note, the process here is not
Locate your existing key or create a new one and continue to the next step.
Welcome to the IBM watsonx Assistant for Z for Technical Sales Level 4 Lab Guide (lab guide). The lab guide is part of the IBM watsonx Assistant for Z for Technical Sales Level 4 learning plan for IBM and Business Partner Technical Sales and related badge. The learning plan is intended to teach technical sellers and Business Partners how to conduct a proof of experience (PoX) for a client.
In a fast-paced world, things change...
The products and services may appear differently than what is shown in the lab guide. This can occur if the product or service is updated with a new version.
Responses generated by IBM watsonx Assistant for Z are likely to change over time. The responses you see when you run the queries in this section may differ from the screen images captured in the lab guide.
Read and follow all the directions.
It is important to read and follow all the documented steps. Skipping steps or sections can cause issues with completing the lab.
Also, invest a few minutes in reading the tips in the Using the demonstration guide section. THe tips will save you time and frustration in completing the lab.
This lab guide covers the setup, configuration, and usage of watsonx Assistant for Z. This lab guide uses the IBM watsonx Assistant for Z Velocity collection and the three Velocity Pilot lab environments in IBM Technology Zone (ITZ).
The lab guide also enables dedicated lab environments for customized client PoXs and demonstrations. If you are preparing for an actual pilot engagement, refer to the Pilot Scoping Guide for watsonx Assistant for Z for additional information.
Using the lab guide, you will learn how to:
In addition, you will import pre-packaged z/OS skills and create custom-built skills to deliver an assistant that handles 3 use cases:
Not all capabilities of the offering are covered in the lab guide.
This lab guide covers many features and capabilities of IBM Watson Assistant for Z, but not all. Some uncovered capabilities may be available in ITZ environments, while others may not, such as using skills for OMEGAMON.
"},{"location":"#support","title":"Support","text":"Think something is down? Check the applicable status pages for any known issues such as a site or service not being available:
For issues with provisioning the ITZ environment for this lab (for example, a failed reservation request due to insufficient quota capacity), open a ticket with ITZ support:
Web: IBM Technology Zone ticket system
Email: techzone.help@ibm.com
For issues related to specific steps found in the demonstration guide after the ITZ environment is provisioned, contact the authors:
Slack:
#watsonx-assistant-z-technical - IBM only
#wxo-practitioners - IBM only - for questions that are related to the software as a service (SaaS) instance of watsonx Orchestrate
Email: andrewj@us.ibm.com and maxwell.g.weiss@ibm.com
Business Partners, use the IBM Training live Chat Support service or other support methods that are found on the IBM Training portal here.
"},{"location":"#using-the-demonstration-guide","title":"Using the demonstration guide","text":"Use these helpful tips to take full advantage of the IBM watsonx Assistant for Z for Technical Sales Level 4 Lab Guide.
Printing the demonstration guidePrinted or saved copies can be out of date
The IBM watsonx Assistant for Z for Technical Sales Level 4 Lab Guide changes regularly to match the IBM watsonx Assistant for Z offering and associated ITZ environment. Printed or saved copies of the demonstration guide can become out-of-date quickly and result in failed steps.
A ready-to-print PDF version of the IBM watsonx Assistant for Z for Technical Sales Level 4 Lab Guide is here.
Create a reference card for storing user IDs, passwords, and links for your ITZ environments.You will be creating and using multiple user IDs, passwords, links, and other content throughout the lab. To save time, it is strongly suggested you create a simple text file to store this data so it is readily available and you can easily cut and paste the data when needed. Here is a template to get you started.
watsonx Assistant for Z - Level 4 shortcuts:\n\nwatsonx Orchestrate\n\n IBM Cloud account: \n IBM Cloud resources: https://cloud.ibm.com/resources\n watsonx Orchestrate URL: \n\n Assistant name: \n Assistant description: \n Assistant icon: https://ibm.github.io/SalesEnablement-L4-watsonx-AssistantForZ/Setup/_attachments/Zeeves75x75.png\n\nOpenShift\n\n Cluster Admin Username: kubeadmin\n Cluster Admin Password: \n OCP Console: \n\n IBM Cloud container entitlement key: \n\n OS-secret password: \n Client ingestion AuthKey: \n Wrapper password: \n Cluster domain for routes: \n Ingestion route (append /v1/query): \n\nAnsible\n\n Ansible Automation Platform URL: \n AAP User Name: admin\n AAP password:\n\n Wazi User: IBMUSER\n Wazi Password:\n Wazi URL: \n\nLive Embed\n\n inetegrationID:\n region:\n serviceInstanceID:\nImages in the demonstration guide can be enlarged by clicking on the image. Press the Esc key or click the X to dismiss the enlarged image.
Image highlightingIn some images, the following styles of highlighting are used:
Solid highlight box: This style of box highlights where to click, enter, or select an item.
Dash highlight box: This style of box highlights one of two things: the path to follow to get to a specific location in the user interface, or areas to explore on your own.
Copying and pasting commands and prompts from this demonstration guide is easy and can eliminate typographical errors.
Click the highlighted copy icon and then use your operating system's paste function. For example, Ctrl+V, or right-click and select Paste.
IBM employees and the tech industry in general, tend to use acronyms. In the demonstration guide, most acronyms will appear with a dashed underline. Hover over the acronym to learn its meaning. A question mark () icon will first appear and after a second the tool tip with the acronym's meaning is displayed. Try it here: LPAR.
The Lab Guide table of contentsThis Demonstration Guide uses a responsive browser-based interface to ensure pages are usable on various devices with different screen sizes. The Demonstration Guide table of contents may be displayed as highlighted in the green dashed box in this image:
However, if the browser window is sized smaller, the table of contents can be accessed by clicking the main menu icon ():
Click the main menu icon () to expand the table of contents.
Continue to the Reserve the IBM Technology Zone environments section to begin the journey to obtain the IBM watsonx Assistant for Z Technical Sales Advanced badge.
"},{"location":"NextSteps/","title":"Next steps","text":""},{"location":"NextSteps/#next-steps","title":"Next steps","text":"This lab guide covered many of the IBM watsonx Assistant for Z capabilities and provides a good base for conducting basic client pilots. However, there is still more to learn about IBM watsonx Assistant for Z. Updates and new releases of the offering and the underlying offerings like watsonx Orchestrate rollout regularly. Be sure to stay informed by bookmarking and regularly reviewing the offering landing page and the product documentation.
"},{"location":"NextSteps/#other-resources","title":"Other resources","text":"The following resources are also available; however, not all are available to Business Partners:
Slack channel: #watsonx-assistant-z-technical
Wiki: Development team's wiki
Box: wxa4z Q&A - questions with high-quality responses.
"},{"location":"NextSteps/#earn-the-badge","title":"Earn the badge","text":"Finally, remember to earn the IBM watsonx Assistant for Z Technical Sales Advanced you must complete the IBM watsonx Assistant for Z for Technical Sales Level 4 learning plan.
IBM technical sellers: Your Learning learning plan
Business Partners IBM Training learning plan
"},{"location":"TechZoneEnvironment/","title":"Reserve the IBM Technology Zone environment","text":""},{"location":"TechZoneEnvironment/#ibm-technology-zone-environment","title":"IBM Technology Zone environment","text":"To enable sellers to learn how to deliver client pilots of IBM watsonx Assistant for Z, three environments are available in IBM Technology Zone (ITZ). The environments are part of the watsonx Assistant for Z Velocity lab collection and can be found in the IBM watsonx Assistant for Z collection.
Watsonx Assistant for Z lab \u2013 watsonx Orchestrate: provides a dedicated environment on IBM Cloud where you can create and configure the assistant, set up conversational search, import skills, and configure actions.
Ansible Automation Platform (AAP) & z/OS: provides a pre-configured instance of AAP and Wazi z/OS. This environment includes Ansible playbooks, which you can import as skills within watsonx Orchestrate and connect to your assistant. Preinstalled templates for various use cases are also available (covered in later sections). Learn more about AAP here. Learn more about Wazi, here.
Single Node OpenShift with NFS storage: provisions a single-node Red Hat OpenShift cluster (SNO) on IBM Cloud. This cluster installs a dedicated instance of OpenSearch for Watson Assistant for Z, enabling ingestion of client-supplied documents.-
All activities in this lab guide are required.
To earn the IBM watsonx Assistant for Z Technical Sales Advanced badge and complete the Level 4 learning plan, you must provision all three ITZ environments and finish every section in the lab guide. Disregard any statements in the ITZ collection that suggest optional environments or tasks.
Follow the instructions to create new reservation requests, extend the reservations, and access the ITZ demonstration environments. Provisioning the SNO environment in ITZ can take several hours, while the other two environments typically provisioning in under 30 minutes.
"},{"location":"TechZoneEnvironment/#create-a-reservation-request","title":"Create a reservation request","text":"Click each of the links that follow to open a browser to the reservation pages of the IBM watsonx Assistant for Z ITZ environments.
You may be asked to authenticate to IBM Technology Zone.
The steps to authenticate to ITZ are not detailed here as they may vary between users.
Watsonx Assistant for Z lab \u2013 watsonx Orchestrate - reservation page
Ansible Automation Platform (AAP) & z/OS - reservation page
Single Node OpenShift with NFS storage - reservation page
The next two steps are for one of the three environments. Repeat for all three environments.
Follow the steps to create a reservation in ITZ for all three environments.
Select Reserve now.
The Reserve now option creates a reservation for immediate use. Optionally, schedule the reservation for a later date, for example, when you are at your client's office to start a pilot.
Complete the reservation request form and then click Submit.
The first two reservations are similar to the first image and have fields a-e that need to be completed.
a. Name: specify a name for the reservation (optional).
b. Purpose: select the Education purpose tile.
For client pilots...
For client pilots, set the Purpose field in the reservation to Pilot and provide an opportunity number to receive a longer reservation.
c. Purpose description: enter a description, for example: Level 4 education.
d. Preferred geography: select the region nearest to your physical location for improved performance and reduced network latency.
e. End date and time: the initial maximum will be set to a specific number of days (typically two, but in somce cases longer) after the current date and time. Instructions follow to extend the reservation end date.
f. Accept the IBM Technology Zone's terms and conditions and security policies.
g. Click Submit.
In addition to the preceding fields, the reservation for the Single Node OpenShift with NFS storage has these additional fields:
h. OCP/Kubernetes cluster network: leave the default setting of 10.128.0.0/14.
i. Enable FIPS security: leave the default setting of No. Learn more about the Federal Information Processing Standards (FIPS) here.
j. Master single node flavor: select 16 vCPU x 64 GB - 300 GB ephemeral storage.
k. OpenShift version: select 4.14.
l. OCP/Kubernetes service network: leave the default setting of 172.30.0.0/16.
m. Accept the IBM Technology Zone's terms and conditions and security policies.
n. Click Submit.
During the provisioning process, multiple emails are sent to you from ITZ as the provisioning process runs. One email states the reservation is provisioning and the other email states that the environment is Ready.
In rare cases, the provisioning process can fail. If you receive an email stating the reservation failed, try again by repeating Steps 1-3 for the environment that failed to provision. In addition, review the Troubleshooting section that follows. If issues continue, open an ITZ support ticket by using the methods that are mentioned in the Support section.
"},{"location":"TechZoneEnvironment/#extend-the-reservation","title":"Extend the reservation","text":"When the reservations are in the Ready state, you can extend each reservation beyond its original end date. The duration of the extension will vary by reservation.
In the IBM Technology Zone portal, expand My TechZone and select My Reservations.
Click the overflow icon () on the reservation tile and select Extend.
Click the Select a date option, (a) specify the date to extend to, and then (b) click Extend.
If you anticipate needing more time, repeat Steps 5-6 to extend the reservation to the maximum allowed. Repeat these steps for the other two reservations.
"},{"location":"TechZoneEnvironment/#join-the-itz-ibm-cloud-account","title":"Join the ITZ IBM Cloud account","text":"Both the watsonx Assistant for Z lab \u2013 watsonx Orchestrate and the Ansible Automation Platform (AAP) & z/OS environments add you to an IBM Cloud account while your reservation is active. During the provisioning process of these ITZ environments, you receive two emails from IBM Cloud.
You only need to accept the invitation to the watsonx Assistant for Z lab \u2013 watsonx Orchestrate environment.
Open the email from IBM Cloud and click the Join now links.
In the Join IBM Cloud browser window that opens, select the I accept the product Terms and Conditions of the registration form, and then click Join Account.
After joining the account, verify that the account appears in your available account list in the IBM Cloud portal.
Click the following link to open a browser to the IBM Cloud portal.
IBM Cloud portal
Follow the directions to complete the authentication to IBM Cloud using the same email address you used to login to ITZ. The login steps vary depending on any two-factor authentication methods enabled.
Click the account menu and verify access to the IBM Cloud account listed in your ITZ reservation.
The account may be different.
The account name should align with the account named in the invitation email you received.
Does your IBM Cloud portal view look different?If your IBM Cloud portal looks different from the images above, it could be because the IBM Cloud portal has gone through a design change, or your browser window is set to smaller size. Instead of the current selected account appearing in the top menu, you may see this change account icon: . Click this icon to view the list of accounts you can access.
Each reservation provides access to its respective environment. Details for accessing each environment are provided in the Pilot setup sections that follow in the lab guide.
After all three reservations are in the Ready state and you accept the invitations to the IBM Cloud accounts, proceed to the next section to complete the pilot setup.
"},{"location":"TechZoneEnvironment/#troubleshooting","title":"Troubleshooting","text":"If your reservation for the Single Node OpenShift environment fails...If your reservation for the Single Node OpenShift environment fails, try selecting one of the eu-gb region options as the Preferred Geography.
"},{"location":"nav/","title":"Nav","text":"IBM watsonx Assistant for Z can integrate with other delivery channels beyond a web page. Other channels include Slack, Microsoft teams, WhatsApp, and many others. Integrating with these and other channels are not covered in the lab guide. However, follow the steps to find the current channels that are supported and where to get more information.
Hover over the Home () and click Integrations.
Explore the Essential channels and Channels sections.
Click Add on the Slack tile.
Click Add.
Review the step-by-step instructions and additional information available for adding a Slack integration.
Note: Most regular users do not have permissions to integrate with your enterprise slack deployment as doing so requires administrative rights.
Take time to further explore the next steps for adding a Slack integration channel and the other supported integration channels.
Learn more about adding integrations here.
"},{"location":"publishDeploy/","title":"Publish and deploy your assistant","text":""},{"location":"publishDeploy/#publishing-and-deploying-your-assistant","title":"Publishing and deploying your assistant","text":"To this point, acting as an Assistant Builder, you built the assistant, configured conversational search, and added skills and automations. You tested your assistant by using the preview capability of AI Assistant Builder. The preview capability is a closed environment for experimenting with prompts.
After your assistant is finalized, you can publish it to make it available to users. Each assistant that you create comes with two environments: draft and live. You configured your assistant in the draft environment. Each environment has its own set of IDs, URLs, and service credentials referenced by external services.
The Environments page in the AI assistant builder has tabs for managing both the Draft environment and the Live environment:
The Draft environment contains all your in-progress work in the Actions, Preview, and Publish pages. Use the Draft environment tab to build out your assistant and use for internal testing before deployment. Any integrations (channels) that you use for the Draft environment are unique to that environment, and changes to draft integrations don\u2019t affect the Live environment.
"},{"location":"publishDeploy/#publish-the-assistant","title":"Publish the assistant","text":"Each time that you publish, you\u2019re creating a new version of the assistant, for example V1. When you publish your content, you\u2019re creating a snapshot of the draft content, resulting in a version.
Versions do not contain integration configurations or environment settings
Published versions contain all of the content from actions, including settings and variables. However, versions do not contain integration configurations or environment settings. Integration configurations and environment settings must be configured manually in each environment.
For managing quality-control and versioning, the Live environment is the version of the assistant to give to users.
Follow these steps to publish the first version of your assistant by using Assistant Builder:
Hover over the Home icon () and click Publish.
Click Publish.
Enter a description of the changes (a), set the environment to Live (b), and then click Publish (c).
Important: When the live environment is created, the settings from the draft environment are not carried over (for example, the configuration of the OpenSearch instance used for conversational search).
Hover over the Home icon () and click Environments.
Click Live.
Click Web chat.
Customize the live assistant as you see fit.
On the Style tab, you\u2019re able to set the Assistant name that is displayed on the chat window when users are interacting with the assistant. For pilots or demos, consider personalizing this name for the client. Also in the Style tab, you can set the themes and display settings of the chat windows, including the ability to enable the IBM Watermark and enable streaming.
On the Home tab, you enable and customize the greeting message from the assistant when the user accesses the assistant chat. You are also able to set Conversation starters that are displayed in the chat window. When selected by the user, the text of the conversation starter is sent as a prompt, so it is important that your assistant is trained and tested to answer correctly. It is highly recommended to remove the default conversation starters and create your own. The ability to add a Background style for the assistant chat window is on the home screen tab.
Explore all the other tabs.
Customize your live environment.
For this lab, toggle Streaming on and turn Suggestions off on the Suggestions tab. You may also want to change the theme to Dark to differentiate your draft and live environments.
Click Save and exit.
Click Add in the Search tile.
Click Custom service.
Enter the URL for your bring-your-own-search (BYOS) engine (a), select Basic authentication for the authentication type (b), enter admin for the Username (c), enter the password that you specified in the wrapper-creds.yaml file for the Password (d), and then click Next (e).
Use the correct URL and authentication type!
Use the URL and credentials for your BYOS OpenSearch engine created earlier here.
Verify conversational search is enabled and click Save.
Update the Custom service settings (a-f), click Save (g), and then click Close (h).
Customize the settings.
This is your assistant. Feel free to customize the settings. The settings shown below reflect the changes made earlier in the lab guide to the draft version of the assistant. This includes the Metadata field to weigh ingested client documents higher using:
{\"doc_weight\":\n{\"product_docs\":0.2,\n\"customer_docs\":0.8},\n\"ibm_indices\":\"*_ibm_docs_slate,*_ibm_redbooks_slate\",\n\"standardize\":true,\n\"customer_indices\":\"customer_*\"\n}\nClick Skill sets in the main menu.
Select your assistant's live instance in the Skill sets list.
Click Connections.
Search for the application name you specified earlier.
Click the ellipses () for your app and then click Connect app.
Click Connect app.
Enter the username (a) and password (b) using the username (admin) and password for your IBM Technology Zone (ITZ) watsonx Assistant for Z Pilot - AAP & z/OS reservation, and then click Connect app (c).
Learn more about publishing your assistant and creating live environments here.
After configuring your assistant\u2019s settings and publishing, the final step is to deploy your assistant, which can be done across various channels depending on the use case.
Several options exist for deploying your assistant through channels and integrations to satisfy the use cases that you might encounter. Learn more about all the deployment options here.
For this lab, deploy the assistant by using the web chat integration. The web chat integration provides an assistant interface that can integrate with a website. Learn more about the web chat integration here.
Open the Environments page in the AI assistant builder.
Click Web chat for the Live environment.
Click the Embed tab.
Copy and record the integrationID, region, and serviceInstanceID values.
In a text editor, create a file that is named Watson Assistant Chat.html and paste the following text in the file.
File name:
Watson Assistant Chat.html\nFile contents:
<html lang=\"en\">\n<head>\n<title>Watson Assistant Chat</title>\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n\n<style>\n .WebChatContainer {\n position: absolute;\n left: 0;\n right: 0;\n top: 0;\n bottom: 0;\n }\n</style>\n</head>\n<body>\n\n<div class=\"WebChatContainer\"/>\n\n<script>\nconst element = document.querySelector('.WebChatContainer');\n\nwindow.watsonAssistantChatOptions = {\n integrationID: \"<YOUR INTEGRATION ID>\", // The ID of this integration.\n region: \"<YOUR REGION>\", // The region your integration is hosted in.\n serviceInstanceID: \"<YOUR SERVICE INSTANCE ID>\", // The ID of your service instance.\n element,\n\n openChatByDefault: true,\n hideCloseButton: true,\n\n layout: {\n showFrame: false,\n hasContentMaxWidth: true,\n },\n\n onLoad: async (instance) => {\n window.WACInstance = instance;\n await instance.render();\n }\n};\n\nsetTimeout(function() {\n const t = document.createElement('script');\n t.src = 'https://web-chat.global.assistant.test.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';\n document.head.appendChild(t);\n});\n</script>\n\n</body>\n</html>\nBefore modification:
After modification:
Open the Watson Assistant Chat.html file in a web browser.
Your assistant is now live. Explore some of the earlier prompts to verify that the assistant is accessing the ingested documents and your skills and skill flows are active.
Wait 5-10 seconds before clicking apply on skill actions.
Prompts to try:
What is z/OS continuous delivery?\nGet z/OS facts\nShow me z/OS facts\nGather and display z/OS facts\nWatsonx Orchestrate allows you to create and configure an assistant with conversational search capabilities. Configure your assistant to use conversational search by using a hosted OpenSearch instance. The pre-configured instance of watsonx Orchestrate in IBM Technology Zone (ITZ) boasts over 220 knowledge sources and supports Retrieval Augmented Generation (RAG). The large language model (LLM) providing conversational AI augments this knowledge based on IBM Z documentation, generating IBM Z context-aware responses to queries with content-grounded knowledge.
A high-level, logical architecture of the environment is illustrated in the following diagram.
"},{"location":"Setup/creatingAssistant-configuringConvoSearch/#access-the-itz-ibm-cloud-account-for-the-watsonx-assistant-for-z-pilot-environment","title":"Access the ITZ IBM Cloud account for the watsonx Assistant for Z Pilot environment","text":"In the IBM Technology Zone portal, expand My TechZone and select My Reservations, or click the following link.
ITZ My reservations
Click the watsonx Assistant for Z Pilot - watsonx Orchestrate tile.
Record the ITZ IBM Cloud account name associated with the reservation.
Did you read the tip on the welcome page about creating a reference card? Check it out here.
Click the IBM Cloud Login link.
Steps to authenticate to IBM Cloud are not illustrated here.
You may need to authenticate to IBM Cloud after clicking the link. These steps are not shown here as they may vary by individual.
Verify that the current IBM Cloud account is the same as the account name recorded in step 3. If the account is not the same, switch to the proper account.
Note: The formatting of the name can appear differently than what is shown in the ITZ reservation.
If the proper account is not listed, click the account drop down and select the proper account.
Note: If your browser window is narrow, the account drop down can be depicted with the Switch Account icon ().
Click the Resources icon ().
Expand the AI / Machine Learning section and click the watsonx Orchestrate instance listed (the instance name is different than shown in the following image).
Click Launch watsonx Orchestrate.
Click the AI assistant builder tile to start creating a new assistant.
Enter a name and optional description for your assistant and click Next.
Complete the Personalize your assistant form and click Next.
Explore the personalization options. In creating an assistant for a client pilot, consider specifying attributes that align with the client's business.
a. Select Web.
b. Select the industry of your choice.
c. Select the role of your choice.
d. Select the need of your choice.
Complete the Customize your chat UI form and click Next.
Explore the customization options. When creating an assistant for a client pilot, consider specifying attributes that align with the client (for example, colors and logos).
Preview your assistant and then click Create.
The assistant is now created.
In the next steps you will be to configure conversational search for your assistant that uses a hosted instance of OpenSearch.
Click Generative AI menu item () in the left navigation.
Select granite-3-8b-instruct for the base large language model (LLM) settings.
Click Set up your Search Integration.
By default, conversational search is not enabled when an assistant is created. Conversational search takes priority over general-purpose answering if both are enabled. Learn more about conversational search in watsonx here.
Click Custom service.
Complete the Custom service (a-e) form and then click Next (f).
a. Select By providing credentials.
b. Enter the following value in the URL field (use the copy icon to avoid typographical errors). This is the URL for the shared OpenSearch instance. In later sections, you create and customize a dedicated instance.
https://wxa4z-opensearch-wrapper-wxa4z-demo-v2-1-0.wxo4z-opc-opensearch-clus-47e063e6a3ad1f71bf2e58f91c3b4c2e-0000.us-south.containers.appdomain.cloud/v1/query\nc. Select Basic authentication in the Choose an authentication type drop-down list.
d. Enter admin in the Username field.
e. Enter secureP@ssw0rd! in the Password field.
secureP@ssw0rd!\nEnable conversational search and then click Save.
Update the conversational search custom service settings based on your requirements.
Note: The Settings page is divided into two sections in the following images to enhance the visibility of the screen captures.
Learn more about these custom service settings here.
The following settings are proven to work well. You can experiment with these settings to see how they affect queries for your client's pilot.
a. Enable Conversational search.
b. Select Single turn. Multi-turn conversation (by selecting Entire conversation) is supported by the offering, but has not been fully included in the lab guide. See the callout in the Testing conversational search section below.
c. Specify the text that appears to instruct the user to expand the list of citations in the assistant (except web chat client).
d. Select Lowest for the retrieval confidence threshold setting. This setting checks the confidence of the retrieved citations before a response is generated.
e. Select Verbose for the generated response length. This setting affects the average response length. Depending on user input, variations from the selected length can occur.
f. Select Lowest for the response confidence threshold. This setting checks the confidence of the generated citations after the response is generated.
g. Keep the default setting of All for the listing of citations.
h. Keep the Default filter field empty.
i. The Metadata field provides a way to adjust your assistant\u2019s behavior during conversational search for your OpenSearch instance. This option is explored in detail in the Installing and using zassist to ingest client documents. Leave the field empty for now.
j. The Search display text options specify the default text displayed when no results are found or when connectivity issues to the backend search service occur. You can keep the defaults or customize the service.
Click Save (a) and then click Close (b).
After you save and close the Conversational search configuration page, a few more configurations are needed to get the best experience from your conversational chat. Details on these settings are available here.
Hover over the Generative AI icon () in the left navigation and click Actions.
Click Set by assistant under the All items menu.
Click No matches.
Click Step 1 under Conversation steps.
Select without conditions (a) in the Is taken drop-down menu and then click Clear conditions (b).
Note: the Is taken value does not change from with conditions after selecting without conditions.
Delete the default text in the Assistant says entry field.
Expand the And then drop-down menu and select Search for the answer.
Click Edit settings.
Click After generation.
Select End the action after this step and then click Apply.
Click Save ().
Select Step 2 (No matches count) under Conversation steps and click delete ().
Click Delete in the confirmation dialog to delete Conversation step 2.
Click Close (the x icon) the Editor window.
Click Fallback in the Actions table.
Delete all of the Conversation steps.
Note: The following image is edited. Only five steps are shown, but all six need to be deleted. You need to select each step individually. Click delete () and confirm the deletion.
Verify that all Conversation steps are deleted and then click the x to close the Editor window.
Click the Global settings ().
Click No matches under the Conversation routing tab.
Move the slider to More often (or select More often in the drop-down).
The setting helps ensure that actions are triggered less often unless the user\u2019s query specifically matches the action\u2019s input.
Click Autocorrection.
Click the autocorrection toggle to turn the feature Off.
Click Save (a) and then Close (b).
Hover over the Home () and click Environments.
Click Web chat.
On the Style tab, click the Streaming toggle to enable streaming.
The streaming setting allows responses to be streamed to the assistant and displayed as they are generated versus waiting until the full response is received and then displayed.
Click the Home screen tab.
Customize the Home screen by setting a custom Greeting message and deleting the default Conversation starters. Optionally, adjust the Background style.
Click Suggestions.
Click the Suggestions toggle to turn this feature Off.
Click (a) Save and exit and then click (b) Close.
There are enhancements that you can make to configure how the large language model (LLM) responds to your queries, including adding prompt instructions and configuring the LLM\u2019s answer behavior. The options are summarized here.
Hover over the Home () and click Generative AI.
Click Add instructions.
Enter a prompt instruction.
Your assistant's LLM gives refined responses by following the prompt's instructions, which clarify how to achieve the end-goal of an action.
Enter prompt instructions in the field. The maximum number of characters you can enter in the prompt instruction field is 1,000.
The following is an example prompt instruction that works well. Experiment with different prompt instructions.
You are a subject matter expert on mainframe systems. Please respond to all prompts with truth and accuracy. Keep all answers short and concise, unless requested to provide details.\nNote: When the instructions are typed in, they are automatically saved and the LLM is immediately trained on them.
Toggle General-purpose answering to Off and then click Save ().
The ability exists to configure the answering behavior of your assistant to provide responses that are based on the preinstalled content or general content.
On the Generative AI page (under Prompt Instructions), you see the Answer behavior section. After you configure Conversational search, you see that it is enabled (toggled on) with the search integration added.
If you enable both general-purpose answering and conversational search, conversational search answering takes precedence over General-purpose answering.
Recommendation: For purposes of retrieving Z-specific answers and responses, it is recommended that you turn off general-purpose answering and leave only conversational search turned on.
Now, you can begin issuing queries to test the assistant's responses. For more detailed responses, try appending \"Please provide a detailed response.\" to the end of your question.
Important: Modify settings iteratively based on your assessment of response quality. Review and change them at any time. For example, add extra prompt instructions, change response verbosity, and modify OpenSearch indexes.
Hover over the Home () and click Preview.
Experiment with different prompts and validate that the answers are reasonable and related to IBM Z.
Other prompts and responses follow.
Note: The responses that you receive can vary from the ones shown.
Prompt:
What is z/OS continuous delivery?\nExample output:
Prompt:
What is the APF list in z/OS?\nExample output:
Prompt:
Why is Db2 different than other database systems?\nExample output:
Prompt:
What happens during an IPL on IBM Z?\nExample output:
Experiment with multi-turn (entire conversation) contextual awareness.
In the December 2024 release of IBM watsonx Assistant for Z support for multi-turn contextual awareness was added. This capability enables the assistant to use an entire session history for retrieving search results and generating answers. This handles context-dependent questions well but may over-rely on past topics, even if the user has moved on.
Experiment with this setting by changing your custom service contextual awareness setting from Single turn to Entire conversation.
Once enabled, try sequential prompts like:
What are some features of z/OS?\nGive me an itemized list?\nTell me more about item 3.\nYou have a working assistant that uses IBM Watson Assistant for Z. Explore different prompt instructions and settings. If you encounter issues, refer to the Troubleshooting section that follows for resolution.
Continue to the Creating a stand-alone OpenSearch instance for document ingestion to learn how to configure a dedicated OpenSearch instance for ingesting client-specific documentation into the RAG model.
"},{"location":"Setup/creatingAssistant-configuringConvoSearch/#troubleshooting","title":"Troubleshooting","text":"The following are issues that you may encounter. If the provided resolutions do not work, contact support by using the methods that are mentioned in the Support section.
Assistant responds to all prompts with, \"I might have information related to your query to share, but am unable to connect to my knowledge base at the moment\"This Assistant is unable to connect to the custom service URL specified. This could be a network issue, the service may be down, the service may be restarting, or the service is no longer running at that URL.
Before reaching out to Support, try the following:
Wait a few minutes and try again. It may be the service was in the process of restarting.
If you printed this demonstration guide or saved a copy, verify you are using the most current version of the lab guide and the correct service URL (https://wxa4z-opensearch-wrapper-wxa4z-demo-v2-1-0.wxo4z-opc-opensearch-clus-47e063e6a3ad1f71bf2e58f91c3b4c2e-0000.us-south.containers.appdomain.cloud/v1/query). The URL may have changed since you saved or printed the lab guide.
Now that you created and deployed your own assistant with conversational search capabilities, your client can understand how watsonx Assistant for Z provides its content-grounded responses to any Z-related questions. In the previous section, you configured your assistant to use a pre-configured Z RAG that has over 220 knowledge sources, and uses this knowledge to provide AI-generated responses.
Next, learn to enable clients to personalize the assistant with an internal knowledge base that contains documentation they add to the Retrieval Augmented Generation (RAG). This helps provide a level of context-awareness for their own environment when environment-specific questions are asked to the assistant.
Now, install and configure a \u201cZ RAG\u201d on Red Hat OpenShift enabling the bring-your-own-search (BYOS) and bring-your-own-documentation (BYOD) capability to ingest other documentation. In doing so, you deploy a dedicated OpenSearch instance (BYOS). Then, connect your assistant to the new RAG database to provide responses based on the ingested documentation (BYOD).
Below is a high-level, logical architecture of the environment deployed in this section.
Earlier, you provisioned three IBM Technology Zone (ITZ) environments. One of which was a single-node Red Hat OpenShift (SNO) cluster. If you have not reserved this environment, or it is not in the Ready state, return to the IBM Technology Zone environment section to complete the reservation.
"},{"location":"byosd/documentIngestion/#install-the-red-hat-openshift-command-line-interface-utility","title":"Install the Red Hat OpenShift command line interface utility","text":"The Red Hat OpenShift command line interface (CLI) utility, which is known as oc, must be installed on your local workstation. If you already installed the oc utility, you can proceed to log in to the SNO cluster.
Click the following link to open a browser window to your ITZ reservations.
ITZ My reservations
Click the Single Node OpenShift tile.
Scroll down and record the Cluster Admin Username and Cluster Admin Password.
Click the OCP Console link.
Note: OCP stands for OpenShift Container Platform.
Enter the Cluster Admin Username and Cluster Admin Password values from step 3 and click Log in.
Click Help () and then click Command Line Tools.
Click the link under oc - OpenShift Command Line Interface (CLI) for the operating system of your local machine.
Clicking the preceding link automatically downloads either a .zip or .tar file specific to your operating system. Extract the file's content. Place the oc binary for your operating system (OS) in a directory that is in your default PATH, or set the PATH environment variable to include the location of the oc binary.
Verify the installation by running the oc command on your local workstation.
oc --help\nThe oc binary may cause a security exception. Adjust the security settings by opening the System Settings utility and clicking Privacy & Security. Under Security locate the message about the oc binary and click Allow Anyway. Return to the terminal window and try the oc --help command again and click Allow Anyway when prompted.
Before ingesting documents, complete the following setup steps.
"},{"location":"byosd/documentIngestion/#log-in-to-the-openshift-cluster-from-your-local-terminal","title":"Log in to the OpenShift cluster from your local terminal","text":"Note: If you just installed the oc utility, skip the next 5 steps.
Click the following link to open a browser window to your ITZ reservations.
ITZ My reservations
Click the Single Node OpenShift tile.
Scroll to the bottom of the reservation page and record the Cluster Admin Username and Cluster Admin Password.
Click the OCP Console link.
Enter the Cluster Admin Username and Cluster Admin Password values from step 3 and click Log in.
Click the kube:admin profile drop-down and click Copy login command.
Click Display Token.
Select and copy the Log in with this token string.
For most operating systems, double-click the value, then right-click and select Copy.
Open a command prompt or terminal window on your local workstation.
Paste the login command and press enter.
Create a directory to store the configuration files that you will create in the next steps.
Instructions vary by your local workstation's operating system.
The directions that follow may vary depending on your operating system. The examples provided are based upon MacOS.
mkdir watsonxAssistant\nChange to the new directory.
cd watsonxAssistant\nIn a text editor, create a file that is named catalogCertManager.yaml and paste the following text in the file.
Formatting of the yaml file is critical!
The content of the YAML file must be formatted exactly as shown. Use the Copy icon to prevent typographical errors.
File name:
catalogCertManager.yaml\nFile contents:
apiVersion: operators.coreos.com/v1alpha1 \nkind: CatalogSource \nmetadata: \n name: ibm-cert-manager-catalog \n namespace: openshift-marketplace \nspec: \n displayName: ibm-cert-manager-4.2.7 \n grpcPodConfig: \n securityContextConfig: restricted \n image: icr.io/cpopen/ibm-cert-manager-operator-catalog@sha256:4dcf4ace4b5f166f83b31063f7e6404dbf78d8e98a9d4fcf52fedf576a55ca6c \n publisher: IBM \n sourceType: grpc \n updateStrategy: \n registryPoll: \n interval: 30m0s\nInstall the IBM Certificate Manager operator in the Red Hat OpenShift cluster.
oc apply -f catalogCertManager.yaml\nThe preceding command returns a message that states the ibm-cert-manager-catalog was created.
In the OpenShift web console, click Operators and then select OperatorHub.
Click the Project to pull-down menu and click the Show default projects toggle.
Scroll down and select openshift-marketplace.
Enter IBM Cert Manager in the search field and then click the IBM Cert Manager tile.
Be patient.
It may take a minute or two for the IBM Cert Manager tile to appear.
Note: The current version of the operator may differ than shown in the image below. Select the most current version.
Click Install.
Keep the default settings and click Install.
Do not continue until...
The installation process takes a few minutes. Do not continue until you see the following message: Installed operator: ready for use.
In your command prompt or terminal window, create a new namespace called wxa4z-byos in the Red Hat OpenShift cluster.
oc create namespace wxa4z-byos \nCreate or obtain your IBM Container Software production entitlement key.
A production entitlement key is required to pull the container images that get deployed by the operator.
To create or retrieve your existing entitlement key, follow the instructions here.
If extra assistance is needed, refer to this site.
Locate your existing key or create a new one and continue to the next step.
Click copy and record your entitlement key for future use in a secure location.
In your command prompt or terminal window, set an environment variable with your production entitlement key.
Substitute your production entitlement key copied in the last step for <entitlement key>.
Mac OS:
export IBM_CS_ENT_KEY=<entitlement key>\nMicrosoft Windows:
set IBM_CS_ENT_KEY=<entitlement key>\nEnter the following command to create a pull secret for the Container Registry.
Mac OS:
oc -n wxa4z-byos create secret docker-registry icr-pull-secret --docker-server=cp.icr.io --docker-username=cp --docker-password=$IBM_CS_ENT_KEY\nMicrosoft Windows:
oc -n wxa4z-byos create secret docker-registry icr-pull-secret --docker-server=cp.icr.io --docker-username=cp --docker-password=%IBM_CS_ENT_KEY%\nIn a text editor, create a file that is named catalogSource.yaml and paste the following text in the file.
Formatting of the yaml file is critical!
The content of YAML files must be formatted exactly as shown. Use the copy icon to prevent typographical errors.
File name:
catalogSource.yaml\nFile contents:
apiVersion: operators.coreos.com/v1alpha1 \nkind: CatalogSource \nmetadata: \n name: ibm-wxa4z-operator-catalog \n namespace: wxa4z-byos \nspec: \n displayName: \"IBM watsonx Assistant for Z Operator Catalog\" \n image: icr.io/cpopen/ibm-wxa4z-catalog:v2.1.0@sha256:a085d360b6aa0e40cf86a632eb5cd190a0407d1c54ec1b2d1d2fb5507f39a524\n publisher: 'IBM' \n sourceType: grpc \n secrets: \n - icr-pull-secret\nCreate your document catalog in the Red Hat OpenShift operator.
oc apply -f catalogSource.yaml\nIn the Red Hat OpenShift web console, click OperatorHub and select the wxa4z-byos project.
Enter ibm watsonx in the search field and the click the IBM watsonx Assistant for Z Operator Catalog tile.
Be patient.
It may take a minute or two for the IBM watsonx Assistant for Z Operator Catalog tile to appear. Reload the browser page if the operator is not listed.
Note: The current version of the operator may differ than that shown in the image below.
Click Install.
Note: The current version of the operator may differ than the one shown in the image after this. Select the most current version.
Select A specific namespace on the cluster (a) under Installation mode and wxa4z-byos (b) for the Installed Namespace, then click Install (c).
Do not continue until...
The installation process takes a few minutes. Do not continue until you see the following message: Installed operator: ready for use.
In your command prompt or terminal window, run the following commands to add the Container Registry credential to the operator's service account.
Mac OS and Microsoft Windows:
oc project wxa4z-byos\nMac OS:
oc patch serviceaccount ibm-wxa4z-operator-controller-manager --type merge -p '{\"imagePullSecrets\": [{\"name\": \"icr-pull-secret\"}]}'\nMicrosoft Windows:
oc patch serviceaccount ibm-wxa4z-operator-controller-manager --type merge -p \"{\\\"imagePullSecrets\\\":[{\\\"name\\\":\\\"icr-pull-secret\\\"}]}\"\nIn the Red Hat OpenShift web console, under Workloads, click Pods.
Verify the two pods that start with ibm-wxa4z-operator have a status of Running and that all pods are Ready.
Run the following command to set the administrative policy for the workspace.
oc -n wxa4z-byos adm policy add-scc-to-user privileged -z byos\nIn a text editor, create a file that is named os-secret.yaml, paste the following text in the file, and then modify the default password.
File name:
os-secret.yaml\nSubstitute a secure password of your choosing for the string <OPENSEARCH_PASSWORD>. Record this value for later use.
File contents:
apiVersion: v1 \nstringData: \n password: <OPENSEARCH_PASSWORD> \nkind: Secret \nmetadata: \n name: opensearch-creds \n namespace: wxa4z-byos \ntype: Opaque\nCreate the secret by running the following command.
oc apply -f os-secret.yaml\nIn a text editor, create a file that is named client-ingestion-secret.yaml, paste the following text in the file, and then modify the default password.
File name:
client-ingestion-secret.yaml\nSubstitute a secure authentication key of your choosing for the string <CLIENT_INGESTION_AUTHKEY>. The authentication key can be a random password. Record this value for later use.
File contents:
apiVersion: v1 \nstringData: \n authkey: <CLIENT_INGESTION_AUTHKEY> \nkind: Secret \nmetadata: \n name: client-ingestion-authkey \n namespace: wxa4z-byos \ntype: Opaque\nCreate the secret by running the following command.
oc apply -f client-ingestion-secret.yaml\nIn a text editor, create a file that is named wrapper-creds.yaml, paste the following text in the file, and then modify the default password.
File name:
wrapper-creds.yaml\nSubstitute a secure password credential of your choosing for the string <WRAPPER_PASSWORD>. The password can be a random password. Record this value for later use. Use this password in the following steps when you configure your BYOS connection in your assistant to connect to the network route.
File contents:
apiVersion: v1\nstringData:\n username: admin\n password: <WRAPPER_PASSWORD>\nkind: Secret\nmetadata:\n name: wrapper-creds\n namespace: wxa4z-byos\ntype: Opaque\nCreate the secret by running the following command.
oc apply -f wrapper-creds.yaml\nObtain and record your cluster domain that is used for routes by running the following command.
oc -n openshift-ingress-operator get ingresscontroller default -o jsonpath=\"{.status.domain}\"\nThe output from the command does not include a newline.
The value returned for the cluster domain does not include a newline. When copying the value do not include the character or characters used for your command line prompt. Do not include the your prompt in the next step!
Note: The output of the command will be a string similar to: apps.672b79320c7a71b728e523b4.ocp.techzone.ibm.com
In a text editor, create a file that is named byos.yaml and paste the following text in the file.
File name:
byos.yaml\nSubstitute the domain name recorded in the previous step for the string <YOUR_CLUSTER_DOMAIN>.
File contents:
apiVersion: wxa4z.watsonx.ibm.com/v1\nkind: BYOSearch\nmetadata:\n name: byosearch\n namespace: wxa4z-byos\nspec:\n imagePullSecrets:\n - name : icr-pull-secret\n namespace: wxa4z-byos\n clusterName: wxa4z-byos-cluster\n clusterDomain: <YOUR_CLUSTER_DOMAIN>\n\n opensearch:\n secretName: opensearch-creds\n\n persistence:\n enabled: true\n storageClass: \"managed-nfs-storage\"\n accessModes:\n - ReadWriteOnce\n size: 24Gi\n\n wrapper:\n createRoute: true\n resources:\n requests:\n cpu: 2\n memory: \"500Mi\"\n limits:\n cpu: 2\n memory: \"1Gi\"\n\n clientIngestion:\n secretName: client-ingestion-authkey\n\n resources:\n limits:\n cpu: \"500m\"\n memory: 2Gi\n nvidia.com/gpu: \"0\"\n requests:\n cpu: \"500m\"\n memory: 1Gi\n nvidia.com/gpu: \"0\"\n pvc:\n storageClass: \"managed-nfs-storage\"\n enabled: true\n size: 24Gi\nRun the following command to deploy BYOS on your cluster.
oc apply -f byos.yaml\nIn the OCP console, verify that all pods have the status of Running or Completed.
Do not continue until...
The BYOS deployment can take 20 minutes or more to complete. Do not continue until all the pods have a status of \u201cRunning\u201d or \"Completed\". The next step is to retrieve your BYOS endpoint URL.
Under Networking, click Routes.
Copy and record the location for the wxa4z-opensearch-wrapper route.
You are now ready to configure your assistant with the route to your BYOS instance.
Using the network route for your BYOS instance, append the string /v1/query to complete the URL endpoint.
The URL should look similar to:
https://wxa4z-opensearch-wrapper-wxa4z-byos.apps.672b79320c7a71b728e523b4.ocp.techzone.ibm.com/v1/query
Important: The above URL will not work for you. Use the value of your specific OpenSearch instance that is recorded in the previous step.
Update your assistant's custom search integration URL.
Next, you need to return to your assistant in the watsonx Orchestrate AI assistant builder and update the custom search integration URL. Use the URL form the network route (with /v1/query) appended. Use admin for the Username and the Password will be the password that you specified in the wrapper-creds.yaml file.
Don't recall how to set the customer search URL?
Refer back to Creating an assistant and configuring conversational search if you don't remember how to specify the customer search URL.
Test your assistant and verify that it is still answering questions that are related to IBM Z.
Experiment with different prompts and validate that the answers provided are reasonable, and that you can view the documentation that was sourced. If responses are not received as expected, verify that the URL is formatted correctly and you specified the wrapper-creds.yaml password as the admin password.
The following are issues that you may encounter. If the provided resolutions do not work, contact support by using the methods that are mentioned in the Support section.
Pods have a status of ErrImagePull or ImagePullBackoffIf the pods starting with ibm-wxa4z-operator have a status of \u201cErrImagePull\u201d or \u201cImagePullBackoff\u201d, you can delete the pod and it will automatically restart and pull the image successfully. Wait until the pod is re-created successfully.
The wxa4z-client-ingestion pod does not startDid you include the % character in the clusterDomain name when creating the byos.yaml? To resolve, edit the byos.yaml file and run the following command again. The current pod will be terminated and a new one started. This will take about 20 minutes to start.
oc apply -f byos.yaml\nWith bring-your-own-search (BYOS) installed and configured in your assistant, you can now prepare for document ingestion (bring-your-own-documents (BYOD)). BYOD demonstrates how clients can augment their assistant\u2019s conversational search by creating an internal knowledge base with their documentation. Using the client's documentation allows the assistant to provide valuable responses to a range of questions not possible with the default documentation available.
As an example, a client mentioned that their developers often need reference material on company-specific legacy code or company-specific syntax. The users must search through volumes of documentation to find it or look at old code. Also, a need for their operational support group to quickly determine how to resolve technical issues using runbooks exists.
You can show your client how watsonx Assistant for Z can assist developers and operational support personnel in finding answers about internal processes for code development and deployment.
Currently, only PDF, HTML, and DOCX file formats are supported for ingestion.
A high-level, logical architecture of the environment is illustrated in the following diagram.
To prepare for document ingestion, you can also reference the setup instructions that are located here.
"},{"location":"byosd/zassist/#install-the-zassist-utility","title":"Install the zassist utility","text":"The zassist utility is an executable program that automates the ingestion of client documentation into the RAG for watsonx Assistant for Z. A version of zassist is available for download for IBMers and Business Partners for conducting pilots. Follow the steps to download and install zassist.
How do clients get the zassist utility?
The utility is available to clients through IBM Passport Advantage.
Click the following link and download the zassist.zip file.
https://ibm.box.com/s/j3nt5iw4fqd5w2jgcqwxnjlsu8bpvl77
Extract the zassist.zip file.
Locate the appropriate file for your local workstation's operating system.
Either copy the appropriate zassist file to a directory in your PATH, or add the appropriate directory to your PATH environment variable.
Additional information for running the preceding tasks can be found here.
Windows users may need to rename the file zassist file!
If the zassist file does not execute properly, rename the file to zassist.exe.
Run the zassist command to verify that it is working.
zassist\nThe zassist binary may cause a security exception. Adjust the security settings by opening the System Settings utility and clicking Privacy & Security. Under Security locate the message about the zassist binary and click Allow Anyway. Return to the terminal window and try running teh command again.
With the zassist command installed, you are now able to begin ingesting data.
Step-by-step guidance for ingesting documents using zassist is provided in the IBM watsonx Assistant for Z documentation.
Download the BYOD.zip file.
BYOD.zip
What is in the sample client documentation?
Three sample documents are included:
Mainframe_COBOL_Error_Codes.pdf
This is a document containing company-specific mainframe COBOL error codes for their application. Developers within the organization typically review this document to quickly diagnose issues based on the application error codes returned.
Mainframe_Operational_Incidents_Log.pdf
This document is leveraged by the organization\u2019s operational support team and contains historical records of production-level incidents that occurred. For each incident, there\u2019s a record of what the incident was, the date, how it was resolved and who was involved in resolving the incident.
COBOL-CICS-to-Java-Internal-Framework.pdf
This document is leveraged by the development team and contains details about the organization\u2019s internal framework for developing applications consisting of legacy COBOL CICS interoperating with new Java code. Within the document contains company-specific coding practices and code syntax that the developers frequently reference.
Extract the BYOD.zip file.
BYOD directory.Set the TLS_VERIFY environment variable to false.
Mac OS:
export TLS_VERIFY=false\nWindows OS:
set TLS_VERIFY=false\nInitialize the zassist environment.
zassist init\nRetrieve the server URL for the client ingestion server.
Mac OS:
echo https://$(oc -n wxa4z-byos get route wxa4z-client-ingestion -o jsonpath=\"{.spec.host}\")\nThe output of this command is your unique URL for your client ingestion server.
Windows OS (this method can also be used by Mac OS users):
You can retrieve the URL in your OCP Web console by navigating to Networking Routes and then copy the URL for the wxa4z-client-ingestion route.
Retrieve the client-ingestion-authkey.
oc -n wxa4z-byos get secret client-ingestion-authkey -o jsonpath=\"{.data.authkey}\" | base64 -d\nThe output of this command is your unique auth-key that you had previously set. You will need the output of both previous commands in the next step.
If the command doesn\u2019t work for you...You can find your authkey value by viewing the client-ingestion-secret.yaml file you created and copying the value set for the authkey parameter.
Login to your server. Replace <server url> with the value from step 6.
zassist login <server url>\nWhen prompted, enter the password from step 7. Verify that a Success message is received.
Verify zassist is ready to ingest documents by checking the status.
zassist status\nIngest the documentation using the commands.
For the next steps, you must be in the root directory called BYOD.
zassist ingest dev\nzassist ingest ops\nUpload the ingested documents.
zassist load dev\nzassist load ops\nVerify that all documents were successfully ingested and loaded.
zassist status\nUse the watsonx Orchestrate AI assistant builder to verify your document ingestion.
Enter the following prompt in your assistant and record the response (cut and paste into a text file on your local machine).
The customer application is failing with ERR-CBL-001, what does this internal error mean?\nClick the Down arrow to view the citations for the response.
Click View source for the Mainframe_COBOL_Error_Codes-... citation.
Take note of the order of the response citations!
Accept the security risk to view the source document for any ingested document cited.
The steps to accept the security risk for the document are not shown as it varies by the browser you are using. The risk occurs because the certificate for the connection to the SNO instance is not secure. Notice that the URL contains the path to your SNO instance route.
Repeat the preceding steps for the following prompts in your assistant and record the responses (cut and paste into a text file on your local machine).
Are there any production incidents that were resolved in relation to Data corruption in the production database. If yes who can I collaborate with to resolve a similar issue today and what are their names?\nWhat specific syntax changes do I need to make in COBOL to call Java using the internal framework? Please provide a detailed explanation. \nWhat is the internal git lab link to execute the Java on z/OS pipeline?\nDo you recall the Metadata field when you configured your assistant?
The Metadata field provides a way to adjust your assistant\u2019s behavior during conversational search for your OpenSearch instance. Now that you have your own docs that are ingested for conversational search, you can set the metadata field for your assistant to use those documents in its content-grounded search. If you leave the metadata field empty, then it defaults to settings found to perform well but may not use the ingested documents as part of the search results.
If you leave the Metadata field empty, OpenSearch relies on the default settings, which means OpenSearch searches all the default IBM-provided documentation and all of the ingested customer documentation using the following value:
{\"ibm_indices\":\"*_ibm_docs_slate,*_ibm_redbooks_slate\",\n\u201ccustomer_indices\u201d:\u201ccustomer_*\u201d}\nReplacing the wildcard string with an explicit list of indices allows for personalization. The metadata setting is where you can input specific indices (pointing to the underlying documentation) that you want your assistant to use for the content-grounded search. There are over 220 products and topics that the OpenSearch instance has IBM Documentation for. You can find those indices and products here.
You can input a subset of indices into the \u201cMetadata\u201d field in cases where you want your assistant to only gather context for specific IBM products or topics. The specific indices can be listed out in this format:
{\u201cibm_indices\u201d:\u201c<comma separated index values>\u201d,\u201ccustomer_indices\u201d:\u201ccustomer_*\u201d}\nFor example, if you want your assistant to reference only documentation for \u201cDb2 Analytics Accelerator for z/OS\u201d and no ingested client documentation, you can enter the following into the metadata field:
{\u201cibm_indices\u201d:\u201css4lq8_ibm_docs_slate\u201d}\nIf you have a mix of IBM Documentation and client documentation ingested, then there\u2019s an optional search string that you can use to set the \u201cweights\u201d used for each.
For example:
{\"doc_weight\":\n{\"product_docs\":0.5,\n\"customer_docs\":0.5},\n\"ibm_indices\":\"*_ibm_docs_slate,*_ibm_redbooks_slate\",\n\"standardize\":true,\n\"customer_indices\":\"customer_*\"\n}\nSet the (a) Metadata field for your BYOS custom search instance to the following value, click (b) Save, and then click (c) Close. Notice the weight for customer_docs is heavier than the weight for product_docs.
{\"doc_weight\":\n{\"product_docs\":0.2,\n\"customer_docs\":0.8},\n\"ibm_indices\":\"*_ibm_docs_slate,*_ibm_redbooks_slate\",\n\"standardize\":true,\n\"customer_indices\":\"customer_*\"\n}\nHover over the Home () icon and click Preview.
Click the Restart conversation () icon.
Repeat the queries four queries run earlier and record the results and the order of the response citations.
Compare the two sets of results. Notice how the answers changed based on the weighting of the ingested documents versus the IBM product documentation. Were the ingested documents always the first document cited? If not, why do you think that is?
Before proceeding, experiment with different metadata and other configuration settings for your custom service instance.
For client pilots
If you or your client have other documents to ingest, you can do so by repeating the steps using zassist. The Velocity Pilot ITZ environment is limited in compute and storage capacity. The following limits should be adhered to:
Loading documents can take a long time, especially with > 100 MB of text.
It is recommended to run large loads late at night.
When loading, ensure your workstations does not sleep during the process.
If you receive a batch time error, set the batch size to a lower number for that command. For example:
zassist ingest . -s 50\nOnce you have a subset of skills that are published, the application you created can be connected to your assistant.
Expand the main menu and select Skill sets.
Click the Team Skills drop-down and select the Draft of your assistant.
Click the Connections tab.
Click the Search () icon.
Search for the application name you specified in the previous section.
Click the ellipses () and click Connect app.
On the Connect to Ansible Controller Skills form, keep the defaults and click Connect app.
Enter the username (a) and password (b) using the username (admin) and password for your IBM Technology Zone (ITZ) watsonx Assistant for Z Pilot - AAP & z/OS reservation, and then click Connect app (c).
The application is now connected to the draft version of your assistant.
Continue to the next section to create actions for your assistant.
"},{"location":"skills/creatingActions/","title":"Create actions for the assistant","text":""},{"location":"skills/creatingActions/#creating-actions-for-your-assistant","title":"Creating actions for your assistant","text":"Now that the skills in your application are connected to your assistant, you are ready to create actions that are tied to those skills. Learn more about building actions here
"},{"location":"skills/creatingActions/#configure-the-number-of-input-fields","title":"Configure the number of input fields","text":"Before configuring actions, it is important to modify a setting within watsonx Orchestrate that allows triggered skills to display as forms (versus conversational skills).
Click your (a) profile icon and then click (b) Settings
Learn more about configuring input fields here.
Click the Skill configurations tab.
Enter 0 for the Number of form fields.
Click the main menu and select AI assistant builder.
Hover over the Home icon () and click Actions.
Click Create action.
Click the Skill-based action tile.
Select the z/OS Gather Facts tile and click Next.
Note, it may take a minute for the page to display the action tiles. The date that is shown in the z/OS Gather Facts tile reflects when you added the skill to your application.
On the New action dialog, (a) enter a prompt a user of the assistant might use to initiate the action and then (b) click Save.
Sample prompts:
Get z/OS facts\nGather z/OS facts\nAdd any extra prompts (a) and then click the save () (b).
Click Preview.
Enter one of the prompts you specified in step 9 or 10.
Prompt:
Get z/OS facts\nReview the returned results and record the job number.
If an error is generated or the action is not performed and only search results are returned, review the following Troubleshooting section.
Return to the Ansible Automation Platform (AAP) console and review the job information.
Click Jobs and then click the job number that you recorded in the previous step for the z/OS Gather Facts skill.
Review both the Details and Output for the z/OS Gather Facts job.
Recall, that in the assistant, the contents shown in the Output of the Ansible job were not displayed.
IBM watsonx Assistant for Z provides utility skills to retrieve the job output. It is also possible to create a skill flow that executes the z/OS Gather Facts skill followed by the Retrieve job output utility skill in sequence; passing the job ID from the first skill to the second to view the output within the assistant. Creating a skill flow is covered in the next section.
"},{"location":"skills/creatingActions/#troubleshooting","title":"Troubleshooting","text":"Skill returns \"Sorry, we're having issues generating a response\" or the action is not performed and only search results are returned.This error appears to be an intermittent issue when a skill is first added. To resolve, add the skill to your personal skills catalog using the steps that follow. If you encounter the issue, try the steps that follow:
Expand the main menu and select Chat.
Click Add skills from the catalog.
Search for the skill app you created earlier and click the tile for your app.
Click Add skill for all the skills you want to add.
Click Connect app.
Enter the (a) username and (b) password using the username (admin) and password for your IBM Technology Zone (ITZ) watsonx Assistant for Z Pilot - AAP & z/OS reservation (AAP User Password (Use SSH key to login, only use password for UI)), and then click Connect app.
Expand the main menu and select Chat.
Try one of the prompts you created for your skill.
Prompt:
Gather z/OS facts\n
You should now be able to run the skill through the assistant preview.
"},{"location":"skills/creatingCustomActions/","title":"Create custom-built actions","text":""},{"location":"skills/creatingCustomActions/#creating-custom-built-actions","title":"Creating custom-built actions","text":"To this point, you learned how to:
import skills into watsonx Orchestrate
add applications with those skills to your assistant
create skill-based actions for your assistant
combine skills in a skill flow
You can also create custom-built actions. Custom-built actions have actions with different steps to take in conversations and form sequences of prompts that define the conversation experience. The steps can be defined with or without conditions, which help control the custom responses. Steps within the custom action can end with routing to conversational search, triggering another existing subaction, and other actions. Custom-built actions are a powerful way of customizing the user's experience.
Learn more about creating custom-built actions here.
"},{"location":"skills/creatingFlows/","title":"Create skill flows for the assistant","text":""},{"location":"skills/creatingFlows/#creating-skill-flows","title":"Creating skill flows","text":"In the previous section, you ran the Gather z/OS facts skill, but the output was not displayed in the assistant. To both run the action and display the results, a skill flow is needed. Skills are often more valuable when combined with other skills. You can create a skill flow to use two or more skills together to finish a task (like returning the output of a previous skill). When you create a skill flow, you map the output of one skill as the input for subsequent skills. Learn more about creating skill flows here.
As mentioned in a previous section, default utility skills that are provided with the watsonx Assistant for Z skills collection. The Retrieve job output utility skill is used to return the output of a skill.
"},{"location":"skills/creatingFlows/#add-the-utility-skill","title":"Add the utility skill","text":"Open IBM watsonx Orchestrate Skill studio.
Expand Create and click Import API.
Click the z/OS Skills accelerator (Trial) tile.
Enter the following values in the z/OS Skills accelerator form and then click Connect.
Use the URL, User Name, and Password values recorded in the Explore Ansible Automation Platform section earlier.
a: Connection Type: ansible
b: Application Name: <use the same application name from the previous section>
c: Connection URL: <enter the URL for your AAP UI>
d: User Name: <enter the AAP User Name (for UI access)>
e: Password: <enter the AAP User Password>
f: Search Pattern: *
Expand Ansible Utility Skills and click Ansible Utility Skills.
Select Retrieve job output and click Save as draft.
Click the ellipses () for the Retrieve job output skill and select Enhance this skill.
Review the skill settings and then click Publish.
Select Skill sets from the main menu.
Select (a) your draft assistant in the Team Skills drop-down list and (b) click the Connections tab.
Click the Search () icon.
Search for the application name you specified earlier.
Click the (a) ellipses () for your application and (b) click Edit connection.
Verify that the application is Connected (a) and then click Close (b).
Connect the application if it is not connected.
Use the AAP user name (admin) and the AAP password for your ITZ reservation.
Click Skill catalog in the main menu.
Search for the application name you specified earlier.
Click the tile for your application.
Note, the tile name is proceeded by Ansible Controller Skills.
Click Add skill for each of the skills you want to add to the flow.
Click Skill studio in the main menu.
Expand the Create drop-down menu and click Skill flow.
Click the + icon.
Next, you need to add the z/OS Gather Facts skill and the Retrieve job output skill to the skill flow. Use the Search apps function to locate the skills.
Search for the application name you specified earlier and click the tile.
Click Add Skill in the z/OS Gather Facts tile.
Verify the z/OS Gather Facts skill is added to the skill flow.
Click the + icon after the z/OS Gather Facts tile.
Repeat steps 5 and 6 for the Retrieve job output skill.
After adding the Retrieve job output skill, your skill flow should look like:
Next you must map the output values of the first skill to the input of the second skill. In this case, pass the job ID output from z/OS Gather Facts as an input for Retrieve job output.
Click the Retrieve job output tile.
Select the Input tab and click the id field.
Click the z/OS Gather Facts skill in the Mapping data for \"id\" section.
Click the job icon.
Verify that the job appears in the id field.
Optionally, toggle the Hide this from the user setting.
For this lab guide, this option is left disabled. Learn more about this option here.
Click the x to close mapping window.
Click the pencil ().
Enter a (a) Name and (b) Description for your skill flow and then (c) click Save.
Expand the Actions pull-down and click Save as draft.
Expand the Actions pull-down and click Enhance.
On the Enhancing the skill pages, you can:
modify the skill name, description, and version
add phrases (prompts) that will be recognized by the assistant to call the skill flow
Click the Phrases tab.
Replace the existing phrases (prompts) and then click Publish.
Notice that the default prompts are either not intuitive (the skill flow name) or a bit verbose. Replace the existing phrases with phrases that you anticipate users will use.
Example prompts:
Show me z/OS facts\nGather and display z/OS facts\nClick AI assistant builder in the main menu.
Hover over the Home () and click Actions.
Click New action.
Click the Skill-based action tile.
Click the skill flow that you created earlier and then click Next.
Note: it may take a minute for the tiles to appear on the screen.
Enter an example prompt for the skill and click Save.
You can use one of the prompts you used earlier for the skill flow.
Show me z/OS facts\nEnter any additional phrases (prompts) and then click the save ().
Click close (x).
Select the original skill that you created (a) (not the skill flow you just created), click the ellipses (b), and then click Delete (c).
Wait for system training to complete.
Note: The message changes to \"System is trained\" and then disappears.
Click Preview.
Enter one of the prompts you specified into the assistant preview.
Show me z/OS facts\nWait 10 seconds and then click Apply.
Note: It is important to wait for the first job to complete before submitting the second job in the flow.
Review the results from the skill flow.
Use both scroll bars in the assistant preview to review all the returned information. The output is similar to what was seen in the AAP web console. The character strings like [0;32m are special characters that are not properly displayed in the assistant preview interface.
Content
Identity\u00a0added:\u00a0/runner/artifacts/16/ssh_key_data\u00a0(/runner/artifacts/16/ssh_key_data) [1;35m[WARNING]:\u00a0Collection\u00a0ibm.ibm_zos_core\u00a0does\u00a0not\u00a0support\u00a0Ansible\u00a0version\u00a02.14.2[0m
PLAY\u00a0[Gather\u00a0z/OS-specific\u00a0facts.]\u00a0*********
TASK\u00a0[Gather\u00a0all\u00a0facts\u00a0about\u00a0z/OS\u00a0host.]\u00a0********* [0;32mok:\u00a0[zos_host][0m
TASK\u00a0[Print\u00a0gathered\u00a0facts\u00a0about\u00a0the\u00a0master\u00a0catalog.]\u00a0**** [0;32mok:\u00a0[zos_host]\u00a0=>\u00a0{[0m [0;32m\u00a0\u00a0\u00a0\u00a0\"msg\":\u00a0[[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"master\u00a0catalog\u00a0dsn:\u00a0CATALOG.VS01.MASTER\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"master\u00a0catalog\u00a0volser:\u00a0OPEVS1\"[0m [0;32m\u00a0\u00a0\u00a0\u00a0][0m [0;32m}[0m
TASK\u00a0[Print\u00a0only\u00a0CPC\u00a0and\u00a0IODF\u00a0info\u00a0from\u00a0gathered\u00a0z/OS\u00a0facts.]\u00a0****** [0;32mok:\u00a0[zos_host]\u00a0=>\u00a0{[0m [0;32m\u00a0\u00a0\u00a0\u00a0\"msg\":\u00a0[[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"manufacturer:\u00a0IBM\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"model:\u00a0A00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"plant:\u00a0C1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodf\u00a0name:\u00a0PROV.IODF00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodf\u00a0config:\u00a0DEFAULT\"[0m [0;32m\u00a0\u00a0\u00a0\u00a0][0m [0;32m}[0m
TASK\u00a0[Print\u00a0out\u00a0all\u00a0gathered\u00a0facts\u00a0about\u00a0the\u00a0z/OS\u00a0host.]\u00a0***** [0;32mok:\u00a0[zos_host]\u00a0=>\u00a0{[0m [0;32m\u00a0\u00a0\u00a0\u00a0\"ansible_facts\":\u00a0{[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"arch_level\":\u00a0\"2\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"cpc_nd_manufacturer\":\u00a0\"IBM\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"cpc_nd_model\":\u00a0\"A00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"cpc_nd_plant\":\u00a0\"C1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"cpc_nd_seqno\":\u00a0\"20D90792EB76\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"cpc_nd_type\":\u00a0\"008562\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"edt\":\u00a0\"00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"hw_name\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"ieasym_card\":\u00a0\"(00,K2)\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"io_config_id\":\u00a0\"00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodate\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodesc\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodf_config\":\u00a0\"DEFAULT\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodf_name\":\u00a0\"PROV.IODF00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodf_unit_addr\":\u00a0\"DE28\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"ioproc\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iotime\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"ipaloadxx\":\u00a0\"K2\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"ipl_volume\":\u00a0\"D25VS1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"load_param_device_num\":\u00a0\"DE28\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"load_param_dsn\":\u00a0\"SYS0.IPLPARM\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"lpar_name\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"master_catalog_dsn\":\u00a0\"CATALOG.VS01.MASTER\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"master_catalog_volser\":\u00a0\"OPEVS1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"nucleus_id\":\u00a0\"1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"operator_prompt_flag\":\u00a0\"M\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"parmlib_dsn\":\u00a0\"K2.PARMLIB\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"parmlib_volser\":\u00a0\"USRVS1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"primary_jes\":\u00a0\"JES2\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"product_mod_level\":\u00a0\"00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"product_name\":\u00a0\"z/OS\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"product_owner\":\u00a0\"IBM\u00a0CORP\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"product_release\":\u00a0\"05\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"product_version\":\u00a0\"02\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"smf_name\":\u00a0\"VS01\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"sys_name\":\u00a0\"VS01\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"sysplex_name\":\u00a0\"LOCAL\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"tsoe_rel\":\u00a0\"05\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"tsoe_ver\":\u00a0\"4\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"vm_name\":\u00a0\"\"[0m [0;32m\u00a0\u00a0\u00a0\u00a0}[0m [0;32m}[0m
PLAY\u00a0RECAP\u00a0*********** [0;32mzos_host[0m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0:\u00a0[0; 32mok=4\u00a0\u00a0\u00a0 [0m\u00a0changed=0\u00a0\u00a0\u00a0\u00a0unreachable=0\u00a0\u00a0\u00a0\u00a0failed=0\u00a0\u00a0\u00a0\u00a0skipped=0\u00a0\u00a0\u00a0\u00a0rescued=0\u00a0\u00a0\u00a0\u00a0ig nored=0\u00a0\u00a0\u00a0
The previous scenario might or might not be relevant for your client's use case. The scenario illustrates how to sequence skills together in a skill flow to create an action that your assistant triggers based on prompts that use the pre-configured Ansible automation templates. You are encouraged to create your own skill flows and prompts that use other skills available within the AAP instance. As an example, create a skill flow for the z/OS Ping skill. Be sure to add the Retrieve job output skill to view the results.
Next, learn about custom-built actions.
"},{"location":"skills/exploreAAP/","title":"Explore Ansible Automation Platform","text":""},{"location":"skills/exploreAAP/#explore-ansible-automation-platform","title":"Explore Ansible Automation Platform","text":"After you reserved the Ansible Automation Platform (AAP) and Wazi z/OS environment in IBM Technology Zone (ITZ) and the reservation is in the Ready state, follow these steps to explore AAP.
"},{"location":"skills/exploreAAP/#access-the-aap-and-wazi-as-a-service-environment","title":"Access the AAP and Wazi as a Service environment","text":"Be sure to record the information as instructed
Several of the steps below instruct you to record values from your ITZ reservation. Be sure to do this as they will not only be used in this section, but also in later sections of the lab guide.
In the IBM Technology Zone portal, expand My TechZone and select My Reservations, or click the following link.
ITZ My reservations
Click the watsonx Assistant for Z Pilot - AAP & z/OS tile.
Locate and record the AAP User Name (For UI access) and AAP User Password fields.
Record and then click the Ansible Automation Platform UI link.
Enter the Username and Password that is recorded in step 3 and click Log In.
Click Templates under the Resources section.
The AAP instance is preconfigured to the Wazi aaS instance
Note that because the AAP instance and the back-end z/OS system are preconfigured, no changes are needed to execute the templates and they will target your provisioned z/OS system by default.
Locate the z/OS Ping template and click the rocket () icon to start the template.
Observe the z/OS Ping job run.
Take time to explore the other templates that are ready to use. Learn more about the automation capabilities here.
"},{"location":"skills/gettingStartedSkills/","title":"Get started with skills and actions","text":""},{"location":"skills/gettingStartedSkills/#getting-started-with-skills-and-actions","title":"Getting started with skills and actions","text":"Watsonx Assistant for Z automates a range of IBM Z related tasks through assistant interactions by importing skills. Each skill is a pre-defined automation that accomplishes some unit or units of work by running tasks. For example, skills can view z/OS IPL information or work with z/OS datasets.
Watsonx Assistant for Z extends watsonx Orchestrate, allowing users to build new skills from Ansible Automation platform or z/OS Management Facility (z/OSMF) through the Z Skills Accelerator extension. The Z Skills Accelerator extension connects Ansible and z/OS application programming interfaces (APIs) and imports automation as Ansible Playbooks, JCL, or REXX as skills. Learn more importing and building skills here.
Aa high-level, logical architecture of the environment is illustrated in the figure that follows.
"},{"location":"skills/gettingStartedSkills/#environments","title":"Environments","text":""},{"location":"skills/gettingStartedSkills/#watsonx-orchestrate","title":"Watsonx Orchestrate","text":"The Z Skills Accelerator extension is already configured in your watsonx Orchestrate IBM Technology Zone (ITZ) environment. You can use this component to import new skills.
"},{"location":"skills/gettingStartedSkills/#ansible-automation-platform-and-wazi-as-a-service","title":"Ansible Automation Platform and Wazi as a Service","text":"To import skills for automations, you use Ansible Automation Platform (AAP) and Wazi as a Service (Wazi aaS) to serve as the z/OS back-end. Learn more about AAP here. Learn more about Wazi, here.
The two resources are provisioned together in the ITZ environment that you reserved earlier. This environment enables the ability to manage and automate z/OS tasks and subsystems with various preinstalled Ansible playbooks. It includes a z/OS back-end (Wazi as a Service) with all needed prerequisites.
The playbooks provided cover various use cases for automating z/OS management. Ansible\u2019s capabilities for automating various Z-specific tasks are not limited to the use cases that are preinstalled in the AAP instance. The preinstalled playbooks are tasks from the \u2018IBM z/OS core collection\u2019. Using this environment accelerates the ability to showcase the value of watsonx assistant for Z, and to get started with simple automations that can be expanded.
The ITZ environment gives you access to AAP, which is preconfigured to target the accompanying z/OS Wazi system, along with web-based access to AAP to experiment with different playbook templates. These templates are imported into watsonx Orchestrate as skills and connected to your assistant.
For more information on the AAP and Wazi z/OS environments, refer to this document.
The playbook templates that are preinstalled in AAP cover various use cases, which you can explore, including:
Each of the sections that follow build upon each other. Complete each to successfully enhance your assistant by starting with Explore Ansible Automation Platform.
"},{"location":"skills/importSkills/","title":"Import skills from Ansible Automation Platform","text":""},{"location":"skills/importSkills/#importing-skills-from-ansible-automation-platform","title":"Importing skills from Ansible Automation Platform","text":"Now that you understand Ansible Automation Platform (AAP) and the preinstalled automations available, you can import them as skills into your watsonx Orchestrate instance, which is used for assistant guided actions.
"},{"location":"skills/importSkills/#import-skills-into-your-assistant","title":"Import skills into your assistant","text":"The next steps assume that you have an active browser window to the watsonx Orchestrate ITZ cloud account. If you do not, refer to the initial steps in Creating an assistant and configuring conversational search.
Return to your watsonx Orchestrate instance and expand the main menu and click Skill studio.
Expand Create and click Import API.
Click the z/OS Skills accelerator (Trial) tile.
Enter the following values in the z/OS Skills accelerator form and then click Connect.
Use the URL, User Name, and Password values recorded in the Explore Ansible Automation Platform section earlier.
a: Connection Type: ansible
b: Application Name: <enter a meaningful name for the skills that you will import> - record this name, you will need in the next section
c: Connection URL: <enter the URL for your AAP UI>
d: User Name: <enter the AAP User Name (for UI access)>
e: Password: <enter the AAP User Password>
f: Search Pattern: *
Expand the Ansible Job Template Proj... folder.
Explore the other available skills
Take time to explore the available skills. There are many utility skills provided out of the box with the \u201cZ Skills Accelerator\u201d which are needed for actions such as retrieving the output of an Ansible skill. Consider importing these utility skills to enable more complete automation execution flows.
Click aap4zos.
Select the skills that you want to import into your application and then click Save as draft.
For this lab, select the Z/os ping and Z/os gather facts skills.
Click the ellipses () for the first skill and select Enhance this skill.
Review the skill enhancement options and then click Publish.
On the Enhance this skill page, you can specify enhancements to the default skill. Refer to this documentation for more information on enhancing skills.
Repeat steps 8 and 9 for each skill you imported.
The selected skills are now ready for use and available to your assistant. In the next section, learn how to connect them to your assistant.
"},{"location":"skills/importingzOSskills/","title":"Import pre-packaged z/OS skills","text":""},{"location":"skills/importingzOSskills/#importing-pre-packaged-zos-skills","title":"Importing pre-packaged z/OS skills","text":"Provided with Version 2 of watsonx Assistant for Z is a set of pre-packaged skills. These skills are used to automate various tasks on z/OS, such as running different console commands and retrieving logs from batch jobs.
The list of pre-packaged skills available include:
Authorized program list
z/OS IPL Information
Display zOS parmlib datasets
UNIX System Services options
Display zOS subsystems
List spool files
Retrieve dataset content
Retrieve spool file content
Retrieve z/OS Management Facility (OSMF) job status
IBM watsonx Orchestrate requires that any OSMF environment you connect to for skill execution has certificate authority (CA) signed certificates.
As an example, the following are console commands that are used in some of the pre-packaged skills:
operator command -> d prog,lnklistoperator command -> d iplinfooperator command -> d parmlibYou can import the pre-packaged skills to your sandbox environment by downloading the compressed file here and following these instructions.
Extract the embedded JSON file and modify the file for your environment by following these instructions.
"},{"location":"usecases/cert/cert/","title":"SSL certificate renewal","text":""},{"location":"usecases/cert/cert/#use-case-ssl-certificate-renewal-on-zos","title":"Use case: SSL Certificate renewal on z/OS","text":"Now, shift roles to that of a mainframe Security Administrator (SA). The client want to understand how watsonx Assistant for Z can help them to verify that their critical security certificates are up to date and reduce the risk of expired certificates disrupting their organization\u2019s services.
Secure Sockets Layer (SSL) certificates, often referred to as digital certificates, are used to establish an encrypted connection between communicating parties over a network. Certificate management is crucial for maintaining the security of a company\u2019s z/OS environment. The SA has not performed the tasks to manage and renew a certificate in some time. The SA recalls that there are many steps that are required on z/OS and various RACF commands that need to be run to renew a certificate. Rather than going to their senior SA for assistance, demonstrate how using watsonx Assistant for Z can help the SA automate the certificate renewal process.
In this scenario, use the Ansible automation templates that are provided with AAP and the WAZI z/OS environment to create assistant actions. The actions guide the client through the process of identifying their SSL certificate\u2019s expiration dates, and automating the certificate renewal process for them. The assistant saves them time and improve their productivity.
"},{"location":"usecases/cert/cert/#create-an-initial-certificate-authority-ca-certificate-to-sign-future-site-certificates","title":"Create an initial certificate authority (CA) certificate to sign future SITE certificates","text":"For this use case, a certificate authority (CA) certificate is needed to sign new SITE certificates.
Open and log in to the Ansible Automation Platform (AAP) web console.
Don't remember how?
Refer to the first 5 steps in Explore Ansible Automation Platform.
Click Templates under the Resources section.
Click the launch icon () for the z/OS Certs - Create Cert template.
On the Survey screen, modify the Certificate Label and Type fields with the values that follow and then click Next.
a: Certificate Label
TESTCA\nb: Type
CERTAUTH\nLeave the default values for all other fields.
Click Launch.
Review the output of the job.
In the output of the playbook, notice that a new keyring is created, a certificate is created, and the certificate is connected to the key ring.
Locate the line TASK [GENERATE new certificate], click the changed: [zos host].
Click JSON.
Review the RACDCERT command that was run to generate the certificate and then click x to close the window.
Now, create an expiring certificate that uses the CA certificate that you just created.
Return to the Templates tab and click the launch icon () for the z/OS Certs - Create Cert template.
On the Survey screen, modify the fields that follow with the values specified and then click Next.
a: Type
SITE\nb: Sign with
CERTAUTH\nc: Sign Label
TESTCA\nd: Common Name
company.com\ne: Expiration Date
Enter a date that occurs within the next 30 days. The date must be in the format YYYY-MM-DD.
Leave the default values for all other fields.
Unlike the first certificate you created which was self-signed, this certificate will be signed by the local certificate authority that uses the CA you created.
The following image does not highlight all the fields that need to be modified!
Click Launch.
Verify that the job was successful and inspect the output of the job.
Now that you have a certificate and it is expiring within 30 days, it is time to renew the certificate.
Return to the Templates tab and click the launch icon () for the z/OS Certs - Search and Renew template.
On the Survey screen, modify the fields that follow with the values specified and then click Next.
a: Certificate Label
TESTSITE\nb: Type
SITE\nc: Sign with
CERTAUTH\nd: Sign Label
TESTCA\ne: Expiration Date
Specify a new expiration date in the format YYYY-MM-DD.
The following image does not highlight all the fields that need to be modified!
Click Launch.
Verify that the job was Successful and review the output.
Note: Click the Reload Output button to view the full output after the job completes.
Review the tasks that were run within the automation to renew the certificate. Some of the steps completed include:
Run the RACF_CERTIFICATE_EXPIRATION z/OS Health Check
Submit JCL to pull a report on the z/OS Health Check
Search the output of the report for the given certificate label
Print the expiring certificate, if it is found. You see: \u2018TESTSITE expiring \u2013 True\u2019
If the certificate is expiring, start a series of RACDCERT commands to do the following:
Backup the expiring certificate
Rekey the certificate and give it a new temporary label
Generate a CSR for the new certificate
Sign the new certificate with the local CA
Delete the old certificate
Relabel the new certificate to use the same label as before
Refresh the digital certificate list
Create one more expiring certificate to use with the assistant and the new skills you will create.
Return to the Templates tab and click the launch icon () for the z/OS Certs - Create Cert template.
On the Survey screen, modify the fields that follow with the values specified and then click Next.
a: Certificate Label
DEMOCERT\nb: Type
SITE\nc: Sign with
CERTAUTH\nd: Sign Label
TESTCA\ne: Common Name
company.com\nf: Expiration Date
Enter a date that falls within the next 30 days in the format YYYY-MM-DD.
The following image does not highlight all the fields that need to be modified!
Click Launch.
Verify that the DEMOCERT was successfully created.
For this use case, configure the assistant to guide the user through the process of identifying their SSL certificate\u2019s expiration date and automate the certificate renewal process. To do so, import the needed AAP templates into watsonx Orchestrate as skills.
For this use case, the ansible templates you import are:
Open Skill studio in watsonx Orchestrate.
Click Create and then click Import API.
Click the z/OS Skills accelerator (Trial) tile.
Enter the following values in the z/OS Skills accelerator form and then click Connect.
Use the URL, User Name, and Password values recorded in the Explore Ansible Automation Platform section earlier.
a: Connection Type:
ansible\nb: Application Name:
certs\nc: Connection URL:
<Enter the URL for your AAP UI>
d: User Name:
<Enter the AAP User Name (for UI access)>
e: Password:
<Enter the AAP User Password>
f: Search Pattern:
*\nExpand the Ansible Job Template Proj... folder and then click aap4zos.
Select Z/os certs - list cert and Z/os certs - search and renew and then click Save as draft.
Scroll through the table of skills to find the required skills.
Click the ellipses () for the z/OS Certs - List Cert skill and select Enhance this skill.
Review the skill enhancement options and then click Publish.
Repeat steps 7 and 8 for the z/OS Certs - Search and Renew skill.
Challenge: You also need to add the Retrieve job output utility to your certs app just like you did when creating the Gather Facts skill flow. Repeat steps 2 - 8 to add the Retrieve job output utility skill to your certs app.
Open Skill catalog in watsonx Orchestrate.
Enter certs in the search bar.
Click the certs tile.
Click Add skill + for each of the 3 skills in the certs app.
Click Connect app.
Enter your AAP Username and AAP Password and then click Connect app.
Verify that the app is connected.
Open Skill catalog in watsonx Orchestrate.
Select the Draft version of your assistant and click Connections.
Enter certs in the search bar.
Click the ellipses () for the certs app and select Connect app*.
Click Connect app.
Enter your AAP Username and AAP Password and then click Connect app.
The goal of this scenario is to configure the assistant to automate the certificate renewal process for the client. The first step in that process is to help the SA identify the expiration date of their z/OS certificate. You have imported the z/OS Certs \u2013 List Cert skill from Ansible Automation Platform. Next, create a new skill flow that uses the z/OS Certs \u2013 List Cert skill that can later be used in a natural conversation through assistant actions.
First, create a skill flow to retrieve and display the expiration date of a z/OS certificate based on the certificate label the user provides.
Open Skill studio in watsonx Orchestrate.
Click Create and then click Skill flow.
Click the + icon.
Click the certs app.
Search on certs if you do not see the tile for your app.
Click Add Skill + in the z/OS Certs - List Cert tile.
Click the + icon below the z/OS Certs - List Cert skill and repeat steps 4 and 5 to add the Retrieve job output skill.
Click the Retrieve job output skill.
Click the id field.
Click z/OS certs - List Cert.
Click job.
Click the z/OS Certs - List Cert tile.
On both the Input and Output tabs for the z/OS Certs - List Cert skill, enable the Hide this form from the user options.
To enhance the user experience, hide the input and output forms from the user. This disables the List Cert skill form from being displayed. Rather than the user entering in their certificate details as input to the skill form, those details can be gathered into the skill through user prompts when creating an assistant action. This enables a more natural conversation flow when interacting with the assistant.
Repeat step 12 for the Output of the Retrieve job output skill.
The output of the List Cert skill includes a large amount of data. In the assistant, only the certificate expiration date is needed. In the next steps, transform the output to return only the certificate expiration date.
Click the + icon below the Retrieve job output skill.
Click the Custom forms.
Click Add skill + in the Input form.
Click the Input form skill.
Click Add input field +.
Click Paragraph text and then click Next.
Enter certificate expiration date in the Display label field and click Apply.
Display label:
certificate expiration date\nClick the certificate expiration date entry field.
In the Mapping data for \"certificate expiration data\" section, click Retrieve job output.
Click content.
Click Add transformation +.
A transformation is used to extract the certificate expiration date from all the job output data.
Click the Select drop-down and select Get substring by regular expression.
Cut and paste the regular express that follows to extract the certificate end date and then click Add.
Regular Expression:
(?<=End Date: ).[^\"]*\nNote
There are several ways to transform data to match the type of output you need. In the above example, regular expression is used to get the needed output (the certificate expiration date). This regular expression was tested against the output of the z/OS Certs \u2013 List Cert Ansible job to extract the value assigned to the \u2018End Date\u2019 field in the job\u2019s output. After completing this use case, you can experiment with other regular expressions to extract additional information from the job\u2019s output.
For more information on transforming data within watsonx Orchestrate, review the documentation found here.
Enter certificate expiration date in the form title and toggle the Hide this form from the user option.
Form title:
certificate expiration date\nNext, create an output for to return the transformed data from the input skill.
Click the + icon below the Input form.
Click Custom forms.
Click Add Skill + in the Output form tile.
Click the Output form skill.
Click in the Custom forms field and enter # (the pound key, also know as the number sign or hash key).
Typing the # opens a new dialog window.
Expand (a) Input form, select (b) certificate expiration date, and then click (c) OK.
Enable the Hide this form from the user option.
Why hide some of the forms?
You may be wondering why hide the input and output forms for the skills in the skill flow. This is done to execute the automation based on user prompts for the inputs of the skills. This is done through natural conversation with the assistant when the skill flow is configured as an assistant \u2018action\u2019 (you will do this soon). Although the final output is hidden, it is accessible as a variable in a custom-built action. The value can be displayed exactly at the point it is expected in the conversation.
Click the pencil icon ().
Enter Retrieve certificate expiration in the Name field and click Save.
Name:
Retrieve certificate expiration\nClick Actions and then click Save as draft.
Click Actions and then click Enhance.
Review the skill flow settings and click Publish.
You created a new skill flow that accomplishes part of the use case \u2013 retrieving and displaying the expiration date of a z/OS certificate based on the certificate label the user provides.
In the next section, you will create a simpler skill flow for the z/OS Certs \u2013 Search and Renew skill that you previously imported. After this additional skill flow is created, add both skill flows as skill-based actions to be called in a custom-built action that maps inputs to the skill flows through natural conversation.
"},{"location":"usecases/cert/cert/#create-a-skill-flow-for-certificate-renewal","title":"Create a skill flow for certificate renewal","text":"The final step before configuring the assistant with actions is to create a skill flow for renewing certificates. Recall the z/OS Certs \u2013 Search and Renew automation imported the from Ansible Automation Platform earlier. The skill flow that you create next is composed of that single skill. There is no need to return the output. After the automation is triggered, the user can verify the new expiration date by running the retrieve certificate expiration date flow.
In Skill studio, click Create and then click Skill flow.
Click the + icon.
Click the certs app.
Search on certs if you do not see the tile for your app.
Click Add Skill + in the z/OS Certs - Search and Renew tile.
As mentioned, there is no need to return the Ansible job output of this skill when it is run. The z/OS Certs - Search and Renew is used to set default values for some of the inputs. In this use case, assume that the SA will be renewing their SITE certificates that are signed with a previously generated certificate authority.
Click the z/OS Certs - Search and Renew skill.
Click Input.
Hover over the extra_vars.cert_type_survey input field and click the pencil icon ().
Click in the extra_vars.cert_type_survey input field and enter SITE.
extra_vars.cert_type_survey:
SITE\nDo not enter spaces before or after the word SITE.
Repeat 7 and 8 for the extra_vars.sign_with_survey field and enter the word CERTAUTH.
extra_vars.sign_with_survey:
CERTAUTH\nDo not enter spaces before or after the word CERTAUTH.
Enable the Hide this form from the user option for both the Input and Output forms.
The image that follows only shows the Output form, but enable the option for both forms.
Click (a) the pencil icon () for the skill flow, enter (b) Cert Renewal skill flow in the Name field, and click (c) Save.
Name:
Cert Renewal skill flow\nClick Actions and then click Save as draft.
Click Actions and then click Enhance.
Review the skill flow settings and click Publish.
Next, create 2 skill-based actions that use the skill flows. The skill-based actions enable the ability to call the skill flow as a subaction within a new custom-built action. For this use case, create two skill-based actions that use the previously created skill flows:
Retrieve certificate expiration \u2013 maps the user prompted certificate label as input and extracts the certificate expiration date from the Ansible job\u2019s output.
Cert Renewal skill flow \u2013 maps the user prompted certificate label and new expiration date as input and runs the Search and Renew Ansible job to extend the expiration date of the certificate.
After the 2 skill flows are added as skill-based actions, integrate the actions into a custom-built action that defines the entire conversation flow. The flow assists the SA with the certificate renewal process.
Open AI assistant builder in watsonx Orchestrate.
Click Actions.
Click New action+.
Click Skill-based action.
Click the Retrieve certificate expiration tile and then click Next.
Click Cancel on the New action dialog.
For this use case, the action is triggered from a custom-built action. To prevent the skill flow from being run as the skill-based action, do not enter any example phrases.
Click x to close the Retrieve certificate expiration skill.
Repeat steps 3 - 7 to create a skill-based action for the Cert Renewal skill flow.
This action is also triggered from a custom-built action. Do not enter any example phrases.
Verify that both skill-based actions are available.
Next, create a custom-built action that runs the new skill-based actions as subactions. Configure the custom-built action to enable a natural conversation with the assistant, gather relevant details from the user, and map those details to the action inputs.
Click New action +.
Click Custom-built-action.
Enter z/OS certificate expires soon and then click Save.
What does your customer say to start this interaction:
z/OS certificate expires soon\nThe conversational search capability that is provided by watsonx Assistant for Z can provide step-by-step guidance for determining certificate expiration and renewing certificates, and is grounded on Z domain-specific knowledge. In the first step to be taken when the user prompts the assistant with z/OS certificate expires soon, configure the assistant to use conversational search to provide a response on the process and the ability to automate the process.
Click the And then drop down and select Search for the answer.
The result is that anytime the user input matches the example phrase z/OS certificate expires soon, the first step that is taken is for the assistant to use conversational search and provide a response to their original question.
Like in the IPL Information scenario, add a custom search query so when conversational search is run in the first conversation step, the query used is hardcoded and not what the user input.
Click Edit settings.
Enter the following prompt to be used in the Custom search query field and then click Apply.
Custom search query:
My z/OS certificate is going to expire soon. How do I retrieve the expiration date for my certificate?\nClick Next step+.
Enter the following response in the Assistant says field.
Assistant says:
Would you like to run the skill to retrieve your certificate\u2019s expiration date?\nClick the Define customer response option list and select Confirmation.
The Confirmation option prompts the user to select Yes or No.
Click Next step +.
Click the Is taken option list and select with conditions.
This step handles the flow when the user selects Yes in the previous step, indicating that they want to run the skill to retrieve the certificate\u2019s expiration date. To run the Retrieve certificate expiration action created earlier, the assistant needs the certificate label. This label is mapped as input to the skill.
Enter the following text in the Assistant says field.
Assistant says:
What is your certificate label?\nClick the Define customer response drop-down list and select Free text.
Click Next step+.
Click the Is taken option list and select with conditions.
After the user enters the certificate label as free text, the next step is to run the Retrieve certificate expiration skill-based action created earlier. To do so, map the user input to the skill flow and retrieve the expiration date for that certificate.
Click the And then option list and click Go to a subaction.
Notice that the default condition validates the free text is defined from the previous step.
Click the (a) Go to option list, select the (b) Retrieve certificate expiration skill-based action, and then click (c) Apply.
Click Edit passed values.
To run the Retrieve certificate expiration subaction that uses the users certificate label, the passed value needs to be modified.
Click Set new value + and then select extra_vars.cert_label_survey.
In the To field, select Action step variables, and then select What is your certificate label?.
Click Apply.
Click Next step +.
Click the Is taken option list and select with conditions.
In the previous step, you configured the assistant to run the Retrieve certificate expiration subaction you created, passing the certificate label the user inputted to the skills inputs. Recall when the Retrieve certificate expiration skill flow was created, the output form at the end of the skill flow was hidden. That form contained the expiration date. As a result, nothing is returned when running the subaction in the previous step. Now, configure the custom-action to provide that output as a response.
Enter the following text in the Assistant says field.
Assistant says:
Below is your certificate\u2019s expiration date:\nWhile still in the Assistant says field, press return and then type $.
The $ is a special key that lists available functions. The following image is edited to show that you must type the $, but it is not displayed on your screen.
Click Retrieve certificate expiration (step 4) and then click Retrieve certificate expiration result variable.
Review the Assistant says field and then click Save ().
Before completing the use case, test the z/OS certificate expires soon custom-built skill that uses the DEMOCERT certificate created earlier.
Click Preview.
Enter the following prompt in the preview.
Prompt:
My z/OS certificate is going to expire soon. How do I retrieve the expiration date for my certificate?\nReview the response and click Yes.
The assistant responds by calling Conversational search and returns a response by using the Z RAG, displaying the RACDCERT command that can be used. The assistant then prompts Would you like to run the skill to retrieve?.
Review the response and enter DEMOCRT.
Prompt:
DEMOCRT\nClick Apply.
Review the response.
If you see the following response (the date may differ), the custom-built skill ran successfully. The output of the skill flow was not the entire output of the z/OS Certs \u2013 List Cert Ansible job, but rather the certificate expiration date that was extracted from the full job output by using the Regular Expression transformation.
Now that the custom-built action is working, add steps to include the certificate renewal process. After retrieving and displaying the user\u2019s certificate expiration date, ask the user if they want to renew the certificate, and if so, prompt for the new date and renew the certificate.
Click Next step +.
Click the Is taken option list and select with conditions.
Enter the following text in the Assistant says field.
Assistant says:
Would you like to renew your certificate?\nClick the Define customer response option list and select Confirmation.
Click Next step +.
Click the Is taken option list and select with conditions.
This step handles the flow in which the user selects Yes in the previous step indicating they want to renew their expiring certificate. Before initiating the Cert Renewal skill flow action to automate this, the assistant first needs the new expiration date for the certificate.
Enter the following text in the Assistant says field.
Assistant says:
What date would you like to set the renewed certificate\u2019s expiration date to? Please enter in the form of YYYY-MM-DD.\nClick the Define customer response option list and select Free text.
Click New step +.
Click the Is taken option list and select with conditions.
With the new expiration date entered by the user, the next step is to run the Cert Renewal skill flow action as a subaction. Next, trigger the renewal skill flow and pass the user provided details as input to the action to renew the certificate and extend the certificates expiration date.
Enter the following text in the Assistant says field.
This assistant first responds with the message that follows before triggering the certificate renewal skill-flow. When performing a demo of this use case, mention the z/OS Certs \u2013 Search and Renew Ansible playbook typically takes a minute or so to complete.
Assistant says:
Renewing your certificate\u2026this could take up to a minute. Please wait one minute before selecting an option below.\nClick the And then option list and select Go to a subaction.
Click the Go to option list and select the Cert Renewal skill flow.
Click Apply.
Click Edit passed values.
Edit the passed values to use them in the Cert Renewal skill flow subaction.
Click Set new value + and then select extra_vars.cert_label_survey.
In the To field, select Action step variables.
Click What is your certificate label?
Repeat steps 16 - 18 adding the extra_vars.new_expiry-date_survey input variable and What date would you like to set the... in the To field.
Click Set new value + and then select extra_vars.sign_label_survey.
In the To option list, select Enter text.
Enter TESTCA in the Enter text field and click Apply for the To option list.
Enter text:
TESTCA\nFor this passed value, hardcode TESTCA in the skill flow\u2019s input for the sign_label variable. This is the CA certificate created earlier for demo purposes in the AAP web console.
Review the Edit passed values and then click Apply.
Review all 3 variables are set correctly.
Click Next step +
Click the Is taken option list and select with conditions.
To complete the flow, ask the user if they want to verify the new expiration date.
Enter the text that follows in the Assistant says field.
Assistant says:
Would you like to verify the new expiration date for your certificate?\nClick the Define customer response option list and select Confirmation.
Click Next step +.
Click the Is taken option list and select with conditions.
On the condition that the user selected Yes in the previous step, configure a step to run the Retrieve certificate expiration skill-flow again to retrieve and display the new expiration date of the renewed certificate.
Click the And then option list and select Go to a subaction.
Click the (a) Go to option list, select (b) Retrieve certificate expiration, and then click (c) Apply.
Click Edit passed values.
Click Set new value + and then select extra_vars.cert_label_survey.
In the To option list, click Action step variables.
Click What is your certificate label?.
Review the Edit variable values and click Apply.
Click Next step +.
Click the Is taken option list and select with conditions.
The final step is to display new expiration date of the certificate. Nothing is returned in the previous step when running the Retrieve certificate expiration skill flow - this was because the output form was hidden when the skill was created. In this step, provide the output as an assistant response to the user, with only the expiration date extracted from the full job output.
Enter the following text in the Assistant says field.
Assistant says:
Below is the new expiration date of your renewed certificate:\nWhile still in the Assistant says field, press return and then type $.
The $ is a special key that lists available functions. The following image is edited to show that you must type the $, but it is not displayed on your screen.
Click Retrieve certificate expiration (step 10).
Be sure to select the output from step 10 and not step 4.
Click Retrieve certificate expiration result variable.
Click the And then option list and select End the action.
Review the (a) final step, click (b) Save (), and then click (c) x.
The custom-built action is now complete and can be demonstrated to the SA for this use case. In demonstrating the ability to infuse Ansible automations into a natural conversation, the SA is able to see the value that watsonx Assistant for Z can provide in helping them improve productivity and remove the need to go to their senior colleagues for assistance.
Open Preview in the Ai assistant builder.
Enter the following text in the assistant.
Prompt:
How do I check the expiration date for my certificate that\u2019s expiring soon?\nUse the Change layout option to open a full page view of the assistant.
Review the response and click Yes.
The assistant responds with conversational search, providing a content-grounded answer based on IBM Z documentation. The response includes a RACF command that the SA might use to determine their certificate\u2019s expiration date.
Following the response, the assistant prompts the user if they want to run the skill to retrieve a certificate\u2019s expiration date.
Enter DEMOCERT after the assistant responds with What is your certificate label?
Prompt:
DEMOCERT\nWait 10 seconds and then click Apply.
Review the response and then click Yes.
By providing the automation within the assistant conversation, it makes it very quick for the SA to identify the certificate\u2019s expiration date. In addition to providing this valuable information, the assistant is configured with another automation to renew the certificate if they choose to do so.
The expiration date you see may differ from the image that follows.
Enter a date in the future in the format YYYY-MM-DD.
Review the response, wait 30 seconds to a minute, and then click Yes.
It is crucial that you wait 30 seconds to a minute before selecting Yes.
This is because in the background, your z/OS Certs \u2013 Search and Renew automation is running within AAP (which you can verify within the AAP Web console). This is mapping the user-inputted expiration date as well as the original certificate label provided by the end-user to the inputs of this AAP automation.\"
Wait 10 seconds and then click Apply.
Review the response.
The response should match the date that is entered in step 7.
In the demo, the SA receives immediate guidance on identifying the certificate expiration date via RACF commands. The SA runs automation that is proposed by the assistant to retrieve the certificate information. Also, because the assistant is configured with step-by-step conversation flows, it is possible to add other prompts within the conversation. For example, proposing the automation of renewing the certificate on their behalf. By doing so, the SA is able to reduce the time it takes to complete this routine task.
Recall how many steps were involved in the Ansible template for z/OS Certs \u2013 Search and Renew. By automating these tasks with Ansible, the System Administrator streamlines the entire process and ensures that their critical certificates are up to date and reduce the risk of expired certificates disrupting their business services.
"},{"location":"usecases/cert/certPH/","title":"COMING SOON!","text":""},{"location":"usecases/cert/certPH/#coming-soon","title":"COMING SOON!","text":""},{"location":"usecases/ipl/ipl/","title":"Retrieve IPL information","text":""},{"location":"usecases/ipl/ipl/#use-case-retrieve-ipl-information","title":"Use case: Retrieve IPL information","text":"Next, explore a use case to improve productivity for early-tenure system programmers (SysProg) who are preparing for an upcoming initial program load (IPL) for a logical partition (LPAR).
To prepare for the IPL, the SysProgs need to familiarize themselves with the process. Rather than spending time reading through the wide array of documentation available online, they would like to use watsonx Assistant for Z. The content-grounded capabilities that are provided by watsonx Assistant for Z return accurate responses to their questions quickly and uses automations to perform actions.
As part of the pilot, they already explored prompting the assistant with questions. In one example prompt, they asked the assistant is \u201cWhat information is needed to perform an IPL on a z/OS LPAR?\u201d In reading the response, the SysProg learns they need information about their system in preparation for the IPL. For example, the IPL Volume and the IPL LOAD PARM.
For this use case, show how a simple automation for retrieving this type of information can be infused in a natural conversation with watsonx Assistant for Z. You use pre-packaged skills to automate various tasks on z/OS. The pre-packaged skills are provided as an OpenAPI JSON file. Learn more about OpenAPI here. The file includes skill definitions that can be uploaded to the Skill Studio within watsonx Orchestrate to import the pre-packaged skills. First, the file must first be customized for your z/OS server.
The list of pre-packaged skills available include:
A great value of watsonx Orchestrate is the ability to build skills that anyone can use. You can build your own custom skills by importing an OpenAPI file into watsonx Orchestrate as a JSON or YAML file. For more information on building skills by importing OpenAPI files, refer to the documentation here.
Watsonx Orchestrate also makes it possible to build, edit, and generate OpenAPI specifications by using the OpenAPI builder. With the OpenAPI Builder, you can use the AI function to simplify the process of generating these specifications. For more information on using the OpenAPI Builder, refer to the documentation here.
For this use case, you are importing the skill for retrieving a z/OS server\u2019s IPL information. The next steps walk you through the process of downloading that OpenAPI JSON file and customizing it for your environment.
"},{"location":"usecases/ipl/ipl/#download-and-customize-the-watsonx-assistant-for-z-openap-json-file","title":"Download and customize the watsonx Assistant for Z OpenAP JSON file","text":"Download the watsonx Assistant for Z OpenAP JSON file.
wxa4z-skillpak-prepackaged-skills.json.zip
Extract the file.
In a text editor, open the wxa4z-skillpak-prepackaged-skills.json, modify the server's url field as described, and save the file.
File name:
wxa4z-skillpak-prepackaged-skills.json\nSubstitute your Wazi as a Service (WaaS) instance URL for the string <your z/OSMV URL>. Your WaaS URL is based on your ITZ AAP URL that can be obtained from your watsonx Assistant for Z Pilot - AAP & z/OS ITZ reservation.
The AAP URL is similar to:
https://itzvsi-aap-ppxbcno.techzone.ibm.com
Change the aap string to zos and append :10443 to the URL value. Record this value for later use! Your new URL is similar to:
https://itzvsi-zis-ppxbcno.techzone.ibm.com:10443
Before:
After:
In watsonx Orchestrate, each app is associated with a single URL.
If you have not imported previous skills into an app called z/OS operations, the default values in the info section are fine. If you already have a app named \"z/OS operations\", modify the info section to meet your needs.
For more information on modifying the OpenAPI JSON file, see the instructions here.
For your skills to run successfully on your WaaS instance, you need to ensure that you can authenticate to it from watsonx Orchestrate. To achieve successful authentication, setup a new RACF Passphrase for the IBMUSER ID that is a pre-defined user ID on the WaaS server. The following steps take you through the steps of setting a new passphrase for your user and verifying access.
Open and log in to the Ansible Automation Platform (AAP) web console.
Don't remember how?
Refer to the first 5 steps in Explore Ansible Automation Platform.
Click Templates under the Resources section.
Click the launch icon () for the z/OS TSO Command(s) template.
Replace the default command with the text that follows and substituting a password of your choosing for the string YOUR PASSWORD PHRASE and then click Next.
ALTUSER IBMUSER PHRASE('YOUR PASSWORD PHRASE') NOEXPIRE RESUME\nAvoid typographical errors later... keep the password simple.
If you type the command yourself, be sure to include the single quotes before and after the password. Record the password as it will be needed later. We will refer to this as your WaaS password.\"
Click Launch.
Verify that the job is Successful by locating the message \"failed\": false in the job output.
Verify that you can log in to z/OSMF in a new browser tab.
Use the WaaZ URL created earlier and append /zosmf to the string. The URL is similar to: https://itzvsi-zos-pwgabob.techzone.ibm.com:10443/zosmf.
Accept any connection not private messages to open the page.
Enter (a) IBMUSER for the z/OS USER ID, (b) the password you specified in step 4 for the z/OS PASSWORD, and then (c) click LOG IN.
Close the new browser tab after verifying a screen similar to the image that follows is displayed.
Open Skills studio in watsonx Orchestrate.
Click Create and then click Import API.
Click From a file.
Click Drag and drop files here or click to upload in the Import a skill file window.
Locate and select the JSON file that you modified earlier and then click Upload.
Verify that you receive the message The Open file or skill package is good to go! and then click Next.
Not good to go?
If the file does not load properly you will need to verify not formatting or errors were made in your json file. Return to the previous section to verify the file contents and then reload the JSON file.
Select the z/OS IPL Information skill and then click Add.
Note: Only the z/OS IPL Information skill is required for this use case, but you can add as many skills as you like for testing purposes.
Click the ellipses icon (~) for the z/OS IPL Information skill and then click Enhance this skill.
Review the skill enhancements options and then click Publish.
If you added other skills in step 7, repeat the previous 2 steps for each skill added.
In Skill studio, click the Apps tab.
In the search field, enter the name of the application in the search field. Unless you modified the info section of the JSON file, the default name is z/OS operations.
Click the ellipses icon (~) for the z/OS Operations and then click Edit.
Click the Configuration tab.
Click Test connection.
Note: the Server URL field must match the URL you created for your WaaS server. It is similar to: https://itzvsi-zos-pwgabob.techzone.ibm.com:10443.
Enter (a) IBMUSER in the username field, (b) your WaaS password created earlier in the password field, and then (c) click Connect app.
Verify that the connection is successful and then click Save.
Repeat step 2 above to verify that the Configuration status is Configured.
Open Chat in watsonx Orchestrate.
Click Add skills from the catalog.
In the search apps field, enter the name of the application. Unless you modified the info section of the JSON file, the default name is z/OS operations.
Locate and click the tile for your app (z/OS operations).
Click Add skill + for the z/OS IPL Information skill.
Repeat step 5 for any additional skills you added to the app.
Click Connect app.
Enter (a) IBMUSER in the username field, (b) your WaaS password created earlier in the password field, and then (c) click Connect app.
Verify that the skill is connected.
Open Chat in watsonx Orchestrate.
Click the z/OS IPL Information tile.
The name of the tile may be different.
If you added multiple skills to your app, the tile name may be z/OS operations and the number of skills included will be shown.
Using the defaults in the form, click Apply.
Review the returned information.
The provided output shows information the early-tenure SysProg needs to prepare for an IPL on their z/OS LPAR. For example, the date and time the system was last IPL\u2019ed, the z/OS release level, the IPL volume, the IPL LOAD PARM used during the IPL, and other details.
If you loaded other pre-packaged skills, test them now.
Before configuring the z/OS IPL Information skill as an assistant action, the app containing the skill must first be connected to the assistant.
Open Skill sets in watsonx orchestrate.
Click the Skill sets drop-down list and select the Draft of your assistant.
Click Connections.
Enter your skill app name (z/OS operations) in the search bar.
Click the ellipses icon (~) for the z/OS operations app and then click Connect app.
In the dialog, click Connect app.
Enter (a) IBMUSER in the username field, (b) your WaaS password in the password field, and then (c) click Connect app.
Next, create a skill-based action that uses the z/OS IPL Information. Recall, with the z/OS Gather Facts skill flow that was created earlier, adding the skill as a skill-based action allows the skill to run based on user prompts to the assistant.
Skill-based actions also serve another purpose. After creating the skill-based action, you can then call that action from a custom-built action. This is accomplished through subactions. For this use case, create an action that triggers the z/OS IPL Information skill on z/OS to display the LPARs IPL information. That action is integrated into another custom-built action (as a subaction) to provide a customized user experience.
Open AI assistant builder in watsonx Orchestrate.
Select Actions.
Click New action +.
Click Skill-based action.
Click z/OS IPL Information and then click Next.
Enter a prompt like Display IPL information that starts the skill and then click Save.
Prompt:
Display IPL information\nClick the Save icon ().
Click Preview.
Wait for the Your changes are being added. message to disappear before proceeding.
Enter the prompt (Display IPL information) to test the skill.
Using the defaults in the form, click Apply.
Verify the results.
Click the delete icon () to remove the example phrase (Display IPL information) from the skill.
Next, you will add this skill-based action as a subaction to a custom-build action. To have the custom-built action started rather than the skill-based action, the existing example phrases need to be removed.
Verify (a) all example phrases are deleted, (b) click the Save icon (), and then (c) click x to close the action.
Custom-built actions allow you to define each step of a conversation with your assistant. You can define steps with or without conditions to control the user responses. You can include your skill-based actions as sub-actions. You can pass generated values between the subactions.
Recall the use case of an early-tenure SysProg who is preparing for an upcoming IPL on one of their LPARs. After going through documentation, the SysProg found that there is information that is needed about their LPAR before they can begin the IPL process. To gather that information, the SysProg might ask the assistant \u201cHow do you retrieve the information needed to IPL a z/OS LPAR? Provide a detailed response\u201d. A response the assistant might return is shown in the following image.
A custom-built action can help the SysProg to take the next steps that are required by adding next-step action suggestions and start skills to gather the needed information.
Click New action +.
Click Custom-built action.
Enter an example phrase (Retrieve IPL information) to prompt the assistant to start the custom-built action and click Save.
Prompt:
Retrieve IPL information\nReview the form to create a custom-built action.
A custom-built action can consist of multiple steps with each step that is taken with or without conditions. Each step specifies the assistant's response and the next step to start.
For client demonstrations and pilots...
For client demonstrations and pilots, it is possible to add a custom search query such that when conversational search is executed in the 1st step, the query being used is hard-coded and isn\u2019t necessarily what the end-user inputted. This can be done by clicking on the Edit settings option under Search for the answer and specifying a custom search query that specifies the exact query to be used.
Click the And then drop-down list and select Search for the answer.
Click Edit settings.
Enter a Custom search query and click Apply.
Custom search query:
How do you retrieve the information needed to IPL a z/OS LPAR? Provide a detailed response\nClick Next step +.
The new custom-built action only responds with a description of how to retrieve the IPL information. Now, infuse automation into the conversation and ask the user if they want to perform the action.
In the Assistant says field, enter a response asking if the user wants to display the IPL information.
Assistant says:
Would you like to display your LPARs IPL information?\nClick the Define customer response drop-down and select Confirmation.
Now, after providing a conversational search-based response to the original question, the assistant asks the user if they want to display the IPL information and prompts the user to select Yes or No.
Click Next step +.
Click the Is taken drop-down and select with conditions.
Review the Conditions.
Notice that the default condition is based on Step 2 and the user clicking Yes when prompted.
Enter Retrieving your system's IPL information... in the Assistant says field.
Assistant says:
Retrieving your system's IPL information...\nClick the And then drop-down and select Go to a subaction.
Click (a) the Go to drop-down, (b) select your skill-based action (z/OS IPL Information), and then (c) click Apply.
Click Save () and then click x.
You can now practice demonstrating the flow of this use case. Recall the steps that were taken and the scenario of the early-tenure SysProg being tasked with preparing for an upcoming IPL.
Click Preview.
Enter How do you retrieve the information needed to IPL a z/OS LPAR? in the assistant prompt.
Prompt:
How do you retrieve the information needed to IPL a z/OS LPAR?\nUse the Change layout option to open a full page view of the assistant.
Review the response.
By using the conversational search capability of watsonx Assistant for Z, grounded on Z-domain knowledge in the Z RAG, the user is able to quickly find an answer to their question. The assistant returns a response that shows the exact operator command they might use, and the types of details it provides which is relevant for preparing for an upcoming IPL. For example, the system\u2019s release level, the LOAD LIB information used for the IPL, the IODF device, the IPL device, and other system information.
You are also able to improve their productivity by infusing automations into the natural conversation that will provide them exactly the information they need to accomplish their task.
Click Yes.
Using the defaults in the form, click Apply.
Review the response to the custom-built action.
The output provides relevant pieces of information the early-tenure SysProg needs to prepare for an IPL on their z/OS LPAR. For example, when the system was last IPLed, the z/OS release they have running (2.5), the IPL volume (D25VS1), the IPL LOAD PARM (LOADK2) used during the last IPL, and other relevant details.
The ability to infuse skills and automations into the conversation allows the user to issue the operator command on their system directly within the assistant itself. The assistant provides a single interface for retrieving details that are required for the IPL process to go smoothly and increases the user's efficiency.
"},{"location":"usecases/ipl/iplPH/","title":"COMING SOON!","text":""},{"location":"usecases/ipl/iplPH/#coming-soon","title":"COMING SOON!","text":""},{"location":"usecases/racf/racf/","title":"Challenge: RACF administration support","text":""},{"location":"usecases/racf/racf/#use-case-racf-administration-support","title":"Use case: RACF administration support","text":"This is a challenge use case.
In this use case, step-by-step directions are not provided. Use the knowledge gained from previous sections of the lab guide to complete updates to the assistant to meet the use case requirements. Several help tips are provided and a sample demonstrate flow is included.
This use case explores the ability of watsonx Assistant for Z to provide self-service support for activities related to Resource Access Control Facility RACF (RACF) Administration support. The client mentioned that their RACF Administrators are often inundated with requests to help reset user's Time Sharing Option (TSO) passwords. Also, requests to grant users certain authorizations to RACF profiles required for the users to complete their jobs are numerous.
Creating a custom-built action for the assistant that provides self-service options to users requesting RACF assistance. Depending on the assistance being requested, the assistant will trigger automations that complete tasks on their behalf without intervention from the RACF Administrator.
The actions and configuration that follow are meant purely for demonstration purposes.
The actions and configuration that follow are meant purely for demonstration purposes to show the art of the possible with watsonx Assistant for Z. There are security considerations to keep in mind when configuring assistants for this purpose, including user authentication and the ability to authorize users to execute certain automations. However, by following the steps in this section, you will show the level of customization that is possible with watsonx Assistant for Z and different an assistant can improve productivity.
Create an app with the required TSO skills.
Use Skills studio to create the app.
App name:
TSO Command\nSkills to include: z/OS TSO COmmand(s) Retrieve job output (utility skill)
Create a connection for the app.
Use Skills catalog to create the app.
Create a skill flow to get the output of the TSO Command.
Use Skills studio to create the skill flow.
The skill flow should run the TSO Command skill and then the Retrieve job output utility skill. The output from the TSO Command should be mapped to the input of the Retrieve job output utility skill. Hide both the input and output forms for the TSO Command skill.
Skill flow name:
TSO COMMAND\nAdd the skills to the draft version of the assistant.
Use Skill sets to add the skills to the assistant.
Create a skill-based action that uses the skill flow.
Create an action that triggers the skill flow to execute TSO commands on z/OS and then display the output of those commands.
Use AI Assistant builder to create the action.
Do not add example phrases to the skill-based action.
Create a custom-built action for RACF administration support.
Use AI Assistant builder to create the action.
Phrase to start the interaction:
RACF assistance\nThe steps for the custom-built action follow:
Step 1. Without conditions, prompt the user for their RACF User ID as free text.
Assistant says:
What is your RACF User ID?\nThe step should look like the following image:
Use the following guidance when entering prompts and expressions in the following custom-built action steps.
Do NOT use the copy and paste icon if the string contains a $. Type each string manually.
When $ appears in the string to enter, type the $ character and then select the variable specified in the <>. For example: User passphrase changed to $<7. Please enter your new RACF passphrase>
Use the single quote character ' for all single quotes shown.
Step 2. Without conditions, use provided user ID and display a message that the assistant is checking the current privileges.
Assistant says:
Checking user privileges for $<1. What is your RACF User ID>
Include in the Assistant says the provided user ID by including the function 1. What is your RACF User ID.
Add an And then option to run the TSO Command as a subaction.
Edit the passed values for the subaction and add a new passed value for 1. extra_vars.zos_tso_command. The To of the variable will be an Expression and include the string:
'LIST USER ' + $<1. What is your RACF User ID>
After the +, enter a $ and select Action step variables and then select 1. What is your RACF User ID.
The step should look like the following image:
Step 3. Without conditions, prompt the user if they want RACF assistance and get a Yes or No confirmation.
Assistant says:
Do you need RACF assistance?\nThe step should look like the following image:
Step 4. With conditions, prompt the user what type of assistance they need.
Assistant says:
What type of assistance?\nCreate a Options type Customer response with two options:
Changing my RACF password\nPrivileges issue\nChange the Customer response settings to Always ask for this information, regardless of previous messages.
The step should look like the following image:
Step 5. With conditions, change the condition Step 4. What type of assistance? and the value of Privilege issue.
Assistant says:
Notifying the RACF Administrator.\nOther options exist.
There are alternative actions that can be taken if the user selects \u2018Privileges issue\u2019. For example, the assistant can trigger an automated email to the RACF administrator. At the time of writing this documentation, Orchestrate does not allow Outlook integrations to IBM\u2019s Outlook organization, so this action cannot be demonstrated. But for the purpose of the flow, simply have the assistant respond with \u2018Notifying the RACF Administrator\u2019 for demonstration purposes.
The step should look like the following image:
Step 6. With conditions, change the condition Step 4. What type of assistance? and the value of Changing my RACF password, and add a Yes or No confirmation.
Assistant says:
Would you like to change your user ID\u2019s RACF passphrase?\nThe step should look like the following image:
Step 7. With conditions, prompt the user to enter their new password as free text.
Assistant says:
Please enter your new RACF passphrase.\nThe step should look like the following image:
Step 8. With conditions, change the condition to Step 6. Would you like to change your user IDS passphrase equals Yes, inform the user the password is bing changed, and create a TSO Command subaction to change the passphrase.
Assistant says:
Issuing RACF command ...\nThe formatting of the values that follow is important.
When creating the To expression for the passed values, be very careful with typing the expression. Do NOT cut & paste this value. Type each charter. All quotes are single-quotes. The $<> denotes typing $ and then selecting the appropriate action step variable.
Edit the passed values for the TSO Command subaction to include the 1. extra_vars.zos_tso_command variable with a To expression with the value of:
'ALTUSER ' + $<1. What is your RACF User ID?> + ' PHRASE(''$<7. Please enter your new RACF passphrase>'') NOEXPIRE RESUME'
The expression should look like the following image:
The step should look like the following image:
Step 9.: With conditions, change the condition to Step 6. Would you like to change your user IDS passphrase equals Yes, and inform the user the passphrase has been changed. Change the And then option to End the action.
Assistant says:
User passphrase changed to $<7. Please enter your new RACF passphrase.>
When entering the above string, after typing $ select the 7. Please enter your new RACF passphrase.
The step should look like the following image:
Be sure to save your custom-built action.
Demonstrate the custom-built action.
Using the AI Assistant builder preview, run the custom-built action. Use the APP web console to verify the passphrase ws changed.
The following video shows how the demonstration should work. The video does not have audio.
This use case demonstrates the value watsonx Assistant for Z can provide to offload common, manual tasks from subject matter experts like RACF Administrators. The use case shows the level of customization offered with infusing automations into natural conversations. Watsonx Assistant for Z improves employee productivity and reduces effort needed by individuals to completing manual tasks.
"},{"location":"usecases/racf/racfPH/","title":"COMING SOON!","text":""},{"location":"usecases/racf/racfPH/#coming-soon","title":"COMING SOON!","text":""}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome","text":""},{"location":"#welcome","title":"Welcome","text":"Welcome to the IBM watsonx Assistant for Z for Technical Sales Level 4 Lab Guide (lab guide). The lab guide is part of the IBM watsonx Assistant for Z for Technical Sales Level 4 learning plan for IBM and Business Partner Technical Sales and related badge. The learning plan is intended to teach technical sellers and Business Partners how to conduct a proof of experience (PoX) for a client.
In a fast-paced world, things change...
The products and services may appear differently than what is shown in the lab guide. This can occur if the product or service is updated with a new version.
Responses generated by IBM watsonx Assistant for Z are likely to change over time. The responses you see when you run the queries in this section may differ from the screen images captured in the lab guide.
Read and follow all the directions.
It is important to read and follow all the documented steps. Skipping steps or sections can cause issues with completing the lab.
Also, invest a few minutes in reading the tips in the Using the demonstration guide section. THe tips will save you time and frustration in completing the lab.
This lab guide covers the setup, configuration, and usage of watsonx Assistant for Z. This lab guide uses the IBM watsonx Assistant for Z Velocity collection and the three Velocity Pilot lab environments in IBM Technology Zone (ITZ).
The lab guide also enables dedicated lab environments for customized client PoXs and demonstrations. If you are preparing for an actual pilot engagement, refer to the Pilot Scoping Guide for watsonx Assistant for Z for additional information.
Using the lab guide, you will learn how to:
In addition, you will import pre-packaged z/OS skills and create custom-built skills to deliver an assistant that handles 3 use cases:
Not all capabilities of the offering are covered in the lab guide.
This lab guide covers many features and capabilities of IBM Watson Assistant for Z, but not all. Some uncovered capabilities may be available in ITZ environments, while others may not, such as using skills for OMEGAMON.
"},{"location":"#support","title":"Support","text":"Think something is down? Check the applicable status pages for any known issues such as a site or service not being available:
For issues with provisioning the ITZ environment for this lab (for example, a failed reservation request due to insufficient quota capacity), open a ticket with ITZ support:
Web: IBM Technology Zone ticket system
Email: techzone.help@ibm.com
For issues related to specific steps found in the demonstration guide after the ITZ environment is provisioned, contact the authors:
Slack:
#watsonx-assistant-z-technical - IBM only
#wxo-practitioners - IBM only - for questions that are related to the software as a service (SaaS) instance of watsonx Orchestrate
Email: andrewj@us.ibm.com and maxwell.g.weiss@ibm.com
Business Partners, use the IBM Training live Chat Support service or other support methods that are found on the IBM Training portal here.
"},{"location":"#using-the-demonstration-guide","title":"Using the demonstration guide","text":"Use these helpful tips to take full advantage of the IBM watsonx Assistant for Z for Technical Sales Level 4 Lab Guide.
Printing the demonstration guidePrinted or saved copies can be out of date
The IBM watsonx Assistant for Z for Technical Sales Level 4 Lab Guide changes regularly to match the IBM watsonx Assistant for Z offering and associated ITZ environment. Printed or saved copies of the demonstration guide can become out-of-date quickly and result in failed steps.
A ready-to-print PDF version of the IBM watsonx Assistant for Z for Technical Sales Level 4 Lab Guide is here.
Create a reference card for storing user IDs, passwords, and links for your ITZ environments.You will be creating and using multiple user IDs, passwords, links, and other content throughout the lab. To save time, it is strongly suggested you create a simple text file to store this data so it is readily available and you can easily cut and paste the data when needed. Here is a template to get you started.
watsonx Assistant for Z - Level 4 shortcuts:\n\nwatsonx Orchestrate\n\n IBM Cloud account: \n IBM Cloud resources: https://cloud.ibm.com/resources\n watsonx Orchestrate URL: \n\n Assistant name: \n Assistant description: \n Assistant icon: https://ibm.github.io/SalesEnablement-L4-watsonx-AssistantForZ/Setup/_attachments/Zeeves75x75.png\n\nOpenShift\n\n Cluster Admin Username: kubeadmin\n Cluster Admin Password: \n OCP Console: \n\n IBM Cloud container entitlement key: \n\n OS-secret password: \n Client ingestion AuthKey: \n Wrapper password: \n Cluster domain for routes: \n Ingestion route (append /v1/query): \n\nAnsible\n\n Ansible Automation Platform URL: \n AAP User Name: admin\n AAP password:\n\n Wazi User: IBMUSER\n Wazi Password:\n Wazi URL: \n\nLive Embed\n\n inetegrationID:\n region:\n serviceInstanceID:\nImages in the demonstration guide can be enlarged by clicking on the image. Press the Esc key or click the X to dismiss the enlarged image.
Image highlightingIn some images, the following styles of highlighting are used:
Solid highlight box: This style of box highlights where to click, enter, or select an item.
Dash highlight box: This style of box highlights one of two things: the path to follow to get to a specific location in the user interface, or areas to explore on your own.
Copying and pasting commands and prompts from this demonstration guide is easy and can eliminate typographical errors.
Click the highlighted copy icon and then use your operating system's paste function. For example, Ctrl+V, or right-click and select Paste.
IBM employees and the tech industry in general, tend to use acronyms. In the demonstration guide, most acronyms will appear with a dashed underline. Hover over the acronym to learn its meaning. A question mark () icon will first appear and after a second the tool tip with the acronym's meaning is displayed. Try it here: LPAR.
The Lab Guide table of contentsThis Demonstration Guide uses a responsive browser-based interface to ensure pages are usable on various devices with different screen sizes. The Demonstration Guide table of contents may be displayed as highlighted in the green dashed box in this image:
However, if the browser window is sized smaller, the table of contents can be accessed by clicking the main menu icon ():
Click the main menu icon () to expand the table of contents.
Continue to the Reserve the IBM Technology Zone environments section to begin the journey to obtain the IBM watsonx Assistant for Z Technical Sales Advanced badge.
"},{"location":"NextSteps/","title":"Next steps","text":""},{"location":"NextSteps/#next-steps","title":"Next steps","text":"This lab guide covered many of the IBM watsonx Assistant for Z capabilities and provides a good base for conducting basic client pilots. However, there is still more to learn about IBM watsonx Assistant for Z. Updates and new releases of the offering and the underlying offerings like watsonx Orchestrate rollout regularly. Be sure to stay informed by bookmarking and regularly reviewing the offering landing page and the product documentation.
"},{"location":"NextSteps/#other-resources","title":"Other resources","text":"The following resources are also available; however, not all are available to Business Partners:
Slack channel: #watsonx-assistant-z-technical
Wiki: Development team's wiki
Box: wxa4z Q&A - questions with high-quality responses.
"},{"location":"NextSteps/#earn-the-badge","title":"Earn the badge","text":"Finally, remember to earn the IBM watsonx Assistant for Z Technical Sales Advanced you must complete the IBM watsonx Assistant for Z for Technical Sales Level 4 learning plan.
IBM technical sellers: Your Learning learning plan
Business Partners IBM Training learning plan
"},{"location":"TechZoneEnvironment/","title":"Reserve the IBM Technology Zone environment","text":""},{"location":"TechZoneEnvironment/#ibm-technology-zone-environment","title":"IBM Technology Zone environment","text":"To enable sellers to learn how to deliver client pilots of IBM watsonx Assistant for Z, three environments are available in IBM Technology Zone (ITZ). The environments are part of the watsonx Assistant for Z Velocity lab collection and can be found in the IBM watsonx Assistant for Z collection.
Watsonx Assistant for Z lab \u2013 watsonx Orchestrate: provides a dedicated environment on IBM Cloud where you can create and configure the assistant, set up conversational search, import skills, and configure actions.
Ansible Automation Platform (AAP) & z/OS: provides a pre-configured instance of AAP and Wazi z/OS. This environment includes Ansible playbooks, which you can import as skills within watsonx Orchestrate and connect to your assistant. Preinstalled templates for various use cases are also available (covered in later sections). Learn more about AAP here. Learn more about Wazi, here.
Single Node OpenShift with NFS storage: provisions a single-node Red Hat OpenShift cluster (SNO) on IBM Cloud. This cluster installs a dedicated instance of OpenSearch for Watson Assistant for Z, enabling ingestion of client-supplied documents.-
All activities in this lab guide are required.
To earn the IBM watsonx Assistant for Z Technical Sales Advanced badge and complete the Level 4 learning plan, you must provision all three ITZ environments and finish every section in the lab guide. Disregard any statements in the ITZ collection that suggest optional environments or tasks.
Follow the instructions to create new reservation requests, extend the reservations, and access the ITZ demonstration environments. Provisioning the SNO environment in ITZ can take several hours, while the other two environments typically provisioning in under 30 minutes.
"},{"location":"TechZoneEnvironment/#create-a-reservation-request","title":"Create a reservation request","text":"Click each of the links that follow to open a browser to the reservation pages of the IBM watsonx Assistant for Z ITZ environments.
You may be asked to authenticate to IBM Technology Zone.
The steps to authenticate to ITZ are not detailed here as they may vary between users.
Watsonx Assistant for Z lab \u2013 watsonx Orchestrate - reservation page
Ansible Automation Platform (AAP) & z/OS - reservation page
Single Node OpenShift with NFS storage - reservation page
The next two steps are for one of the three environments. Repeat for all three environments.
Follow the steps to create a reservation in ITZ for all three environments.
Select Reserve now.
The Reserve now option creates a reservation for immediate use. Optionally, schedule the reservation for a later date, for example, when you are at your client's office to start a pilot.
Complete the reservation request form and then click Submit.
The first two reservations are similar to the first image and have fields a-e that need to be completed.
a. Name: specify a name for the reservation (optional).
b. Purpose: select the Education purpose tile.
For client pilots...
For client pilots, set the Purpose field in the reservation to Pilot and provide an opportunity number to receive a longer reservation.
c. Purpose description: enter a description, for example: Level 4 education.
d. Preferred geography: select the region nearest to your physical location for improved performance and reduced network latency.
e. End date and time: the initial maximum will be set to a specific number of days (typically two, but in somce cases longer) after the current date and time. Instructions follow to extend the reservation end date.
f. Accept the IBM Technology Zone's terms and conditions and security policies.
g. Click Submit.
In addition to the preceding fields, the reservation for the Single Node OpenShift with NFS storage has these additional fields:
h. OCP/Kubernetes cluster network: leave the default setting of 10.128.0.0/14.
i. Enable FIPS security: leave the default setting of No. Learn more about the Federal Information Processing Standards (FIPS) here.
j. Master single node flavor: select 16 vCPU x 64 GB - 300 GB ephemeral storage.
k. OpenShift version: select 4.14.
l. OCP/Kubernetes service network: leave the default setting of 172.30.0.0/16.
m. Accept the IBM Technology Zone's terms and conditions and security policies.
n. Click Submit.
During the provisioning process, multiple emails are sent to you from ITZ as the provisioning process runs. One email states the reservation is provisioning and the other email states that the environment is Ready.
In rare cases, the provisioning process can fail. If you receive an email stating the reservation failed, try again by repeating Steps 1-3 for the environment that failed to provision. In addition, review the Troubleshooting section that follows. If issues continue, open an ITZ support ticket by using the methods that are mentioned in the Support section.
"},{"location":"TechZoneEnvironment/#extend-the-reservation","title":"Extend the reservation","text":"When the reservations are in the Ready state, you can extend each reservation beyond its original end date. The duration of the extension will vary by reservation.
In the IBM Technology Zone portal, expand My TechZone and select My Reservations.
Click the overflow icon () on the reservation tile and select Extend.
Click the Select a date option, (a) specify the date to extend to, and then (b) click Extend.
If you anticipate needing more time, repeat Steps 5-6 to extend the reservation to the maximum allowed. Repeat these steps for the other two reservations.
"},{"location":"TechZoneEnvironment/#join-the-itz-ibm-cloud-account","title":"Join the ITZ IBM Cloud account","text":"Both the watsonx Assistant for Z lab \u2013 watsonx Orchestrate and the Ansible Automation Platform (AAP) & z/OS environments add you to an IBM Cloud account while your reservation is active. During the provisioning process of these ITZ environments, you receive two emails from IBM Cloud.
You only need to accept the invitation to the watsonx Assistant for Z lab \u2013 watsonx Orchestrate environment.
Open the email from IBM Cloud and click the Join now links.
In the Join IBM Cloud browser window that opens, select the I accept the product Terms and Conditions of the registration form, and then click Join Account.
After joining the account, verify that the account appears in your available account list in the IBM Cloud portal.
Click the following link to open a browser to the IBM Cloud portal.
IBM Cloud portal
Follow the directions to complete the authentication to IBM Cloud using the same email address you used to login to ITZ. The login steps vary depending on any two-factor authentication methods enabled.
Click the account menu and verify access to the IBM Cloud account listed in your ITZ reservation.
The account may be different.
The account name should align with the account named in the invitation email you received.
Does your IBM Cloud portal view look different?If your IBM Cloud portal looks different from the images above, it could be because the IBM Cloud portal has gone through a design change, or your browser window is set to smaller size. Instead of the current selected account appearing in the top menu, you may see this change account icon: . Click this icon to view the list of accounts you can access.
Each reservation provides access to its respective environment. Details for accessing each environment are provided in the Pilot setup sections that follow in the lab guide.
After all three reservations are in the Ready state and you accept the invitations to the IBM Cloud accounts, proceed to the next section to complete the pilot setup.
"},{"location":"TechZoneEnvironment/#troubleshooting","title":"Troubleshooting","text":"If your reservation for the Single Node OpenShift environment fails...If your reservation for the Single Node OpenShift environment fails, try selecting one of the eu-gb region options as the Preferred Geography.
"},{"location":"nav/","title":"Nav","text":"IBM watsonx Assistant for Z can integrate with other delivery channels beyond a web page. Other channels include Slack, Microsoft teams, WhatsApp, and many others. Integrating with these and other channels are not covered in the lab guide. However, follow the steps to find the current channels that are supported and where to get more information.
Hover over the Home () and click Integrations.
Explore the Essential channels and Channels sections.
Click Add on the Slack tile.
Click Add.
Review the step-by-step instructions and additional information available for adding a Slack integration.
Note: Most regular users do not have permissions to integrate with your enterprise slack deployment as doing so requires administrative rights.
Take time to further explore the next steps for adding a Slack integration channel and the other supported integration channels.
Learn more about adding integrations here.
"},{"location":"publishDeploy/","title":"Publish and deploy your assistant","text":""},{"location":"publishDeploy/#publishing-and-deploying-your-assistant","title":"Publishing and deploying your assistant","text":"To this point, acting as an Assistant Builder, you built the assistant, configured conversational search, and added skills and automations. You tested your assistant by using the preview capability of AI Assistant Builder. The preview capability is a closed environment for experimenting with prompts.
After your assistant is finalized, you can publish it to make it available to users. Each assistant that you create comes with two environments: draft and live. You configured your assistant in the draft environment. Each environment has its own set of IDs, URLs, and service credentials referenced by external services.
The Environments page in the AI assistant builder has tabs for managing both the Draft environment and the Live environment:
The Draft environment contains all your in-progress work in the Actions, Preview, and Publish pages. Use the Draft environment tab to build out your assistant and use for internal testing before deployment. Any integrations (channels) that you use for the Draft environment are unique to that environment, and changes to draft integrations don\u2019t affect the Live environment.
"},{"location":"publishDeploy/#publish-the-assistant","title":"Publish the assistant","text":"Each time that you publish, you\u2019re creating a new version of the assistant, for example V1. When you publish your content, you\u2019re creating a snapshot of the draft content, resulting in a version.
Versions do not contain integration configurations or environment settings
Published versions contain all of the content from actions, including settings and variables. However, versions do not contain integration configurations or environment settings. Integration configurations and environment settings must be configured manually in each environment.
For managing quality-control and versioning, the Live environment is the version of the assistant to give to users.
Follow these steps to publish the first version of your assistant by using Assistant Builder:
Hover over the Home icon () and click Publish.
Click Publish.
Enter a description of the changes (a), set the environment to Live (b), and then click Publish (c).
Important: When the live environment is created, the settings from the draft environment are not carried over (for example, the configuration of the OpenSearch instance used for conversational search).
Hover over the Home icon () and click Environments.
Click Live.
Click Web chat.
Customize the live assistant as you see fit.
On the Style tab, you\u2019re able to set the Assistant name that is displayed on the chat window when users are interacting with the assistant. For pilots or demos, consider personalizing this name for the client. Also in the Style tab, you can set the themes and display settings of the chat windows, including the ability to enable the IBM Watermark and enable streaming.
On the Home tab, you enable and customize the greeting message from the assistant when the user accesses the assistant chat. You are also able to set Conversation starters that are displayed in the chat window. When selected by the user, the text of the conversation starter is sent as a prompt, so it is important that your assistant is trained and tested to answer correctly. It is highly recommended to remove the default conversation starters and create your own. The ability to add a Background style for the assistant chat window is on the home screen tab.
Explore all the other tabs.
Customize your live environment.
For this lab, toggle Streaming on and turn Suggestions off on the Suggestions tab. You may also want to change the theme to Dark to differentiate your draft and live environments.
Click Save and exit.
Click Add in the Search tile.
Click Custom service.
Enter the URL for your bring-your-own-search (BYOS) engine (a), select Basic authentication for the authentication type (b), enter admin for the Username (c), enter the password that you specified in the wrapper-creds.yaml file for the Password (d), and then click Next (e).
Use the correct URL and authentication type!
Use the URL and credentials for your BYOS OpenSearch engine created earlier here.
Verify conversational search is enabled and click Save.
Update the Custom service settings (a-f), click Save (g), and then click Close (h).
Customize the settings.
This is your assistant. Feel free to customize the settings. The settings shown below reflect the changes made earlier in the lab guide to the draft version of the assistant. This includes the Metadata field to weigh ingested client documents higher using:
{\"doc_weight\":\n{\"product_docs\":0.2,\n\"customer_docs\":0.8},\n\"ibm_indices\":\"*_ibm_docs_slate,*_ibm_redbooks_slate\",\n\"standardize\":true,\n\"customer_indices\":\"customer_*\"\n}\nClick Skill sets in the main menu.
Select your assistant's live instance in the Skill sets list.
Click Connections.
Search for the application name you specified earlier.
Click the ellipses () for your app and then click Connect app.
Click Connect app.
Enter the username (a) and password (b) using the username (admin) and password for your IBM Technology Zone (ITZ) watsonx Assistant for Z Pilot - AAP & z/OS reservation, and then click Connect app (c).
Learn more about publishing your assistant and creating live environments here.
After configuring your assistant\u2019s settings and publishing, the final step is to deploy your assistant, which can be done across various channels depending on the use case.
Several options exist for deploying your assistant through channels and integrations to satisfy the use cases that you might encounter. Learn more about all the deployment options here.
For this lab, deploy the assistant by using the web chat integration. The web chat integration provides an assistant interface that can integrate with a website. Learn more about the web chat integration here.
Open the Environments page in the AI assistant builder.
Click Web chat for the Live environment.
Click the Embed tab.
Copy and record the integrationID, region, and serviceInstanceID values.
In a text editor, create a file that is named Watson Assistant Chat.html and paste the following text in the file.
File name:
Watson Assistant Chat.html\nFile contents:
<html lang=\"en\">\n<head>\n<title>Watson Assistant Chat</title>\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n\n<style>\n .WebChatContainer {\n position: absolute;\n left: 0;\n right: 0;\n top: 0;\n bottom: 0;\n }\n</style>\n</head>\n<body>\n\n<div class=\"WebChatContainer\"/>\n\n<script>\nconst element = document.querySelector('.WebChatContainer');\n\nwindow.watsonAssistantChatOptions = {\n integrationID: \"<YOUR INTEGRATION ID>\", // The ID of this integration.\n region: \"<YOUR REGION>\", // The region your integration is hosted in.\n serviceInstanceID: \"<YOUR SERVICE INSTANCE ID>\", // The ID of your service instance.\n element,\n\n openChatByDefault: true,\n hideCloseButton: true,\n\n layout: {\n showFrame: false,\n hasContentMaxWidth: true,\n },\n\n onLoad: async (instance) => {\n window.WACInstance = instance;\n await instance.render();\n }\n};\n\nsetTimeout(function() {\n const t = document.createElement('script');\n t.src = 'https://web-chat.global.assistant.test.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';\n document.head.appendChild(t);\n});\n</script>\n\n</body>\n</html>\nBefore modification:
After modification:
Open the Watson Assistant Chat.html file in a web browser.
Your assistant is now live. Explore some of the earlier prompts to verify that the assistant is accessing the ingested documents and your skills and skill flows are active.
Wait 5-10 seconds before clicking apply on skill actions.
Prompts to try:
What is z/OS continuous delivery?\nGet z/OS facts\nShow me z/OS facts\nGather and display z/OS facts\nWatsonx Orchestrate allows you to create and configure an assistant with conversational search capabilities. Configure your assistant to use conversational search by using a hosted OpenSearch instance. The pre-configured instance of watsonx Orchestrate in IBM Technology Zone (ITZ) boasts over 220 knowledge sources and supports Retrieval Augmented Generation (RAG). The large language model (LLM) providing conversational AI augments this knowledge based on IBM Z documentation, generating IBM Z context-aware responses to queries with content-grounded knowledge.
A high-level, logical architecture of the environment is illustrated in the following diagram.
"},{"location":"Setup/creatingAssistant-configuringConvoSearch/#access-the-itz-ibm-cloud-account-for-the-watsonx-assistant-for-z-pilot-environment","title":"Access the ITZ IBM Cloud account for the watsonx Assistant for Z Pilot environment","text":"In the IBM Technology Zone portal, expand My TechZone and select My Reservations, or click the following link.
ITZ My reservations
Click the watsonx Assistant for Z Pilot - watsonx Orchestrate tile.
Record the ITZ IBM Cloud account name associated with the reservation.
Did you read the tip on the welcome page about creating a reference card? Check it out here.
Click the IBM Cloud Login link.
Steps to authenticate to IBM Cloud are not illustrated here.
You may need to authenticate to IBM Cloud after clicking the link. These steps are not shown here as they may vary by individual.
Verify that the current IBM Cloud account is the same as the account name recorded in step 3. If the account is not the same, switch to the proper account.
Note: The formatting of the name can appear differently than what is shown in the ITZ reservation.
If the proper account is not listed, click the account drop down and select the proper account.
Note: If your browser window is narrow, the account drop down can be depicted with the Switch Account icon ().
Click the Resources icon ().
Expand the AI / Machine Learning section and click the watsonx Orchestrate instance listed (the instance name is different than shown in the following image).
Click Launch watsonx Orchestrate.
Click the AI assistant builder tile to start creating a new assistant.
Enter a name and optional description for your assistant and click Next.
Complete the Personalize your assistant form and click Next.
Explore the personalization options. In creating an assistant for a client pilot, consider specifying attributes that align with the client's business.
a. Select Web.
b. Select the industry of your choice.
c. Select the role of your choice.
d. Select the need of your choice.
Complete the Customize your chat UI form and click Next.
Explore the customization options. When creating an assistant for a client pilot, consider specifying attributes that align with the client (for example, colors and logos).
Preview your assistant and then click Create.
The assistant is now created.
In the next steps you will be to configure conversational search for your assistant that uses a hosted instance of OpenSearch.
Click Generative AI menu item () in the left navigation.
Select granite-3-8b-instruct for the base large language model (LLM) settings.
Click Set up your Search Integration.
By default, conversational search is not enabled when an assistant is created. Conversational search takes priority over general-purpose answering if both are enabled. Learn more about conversational search in watsonx here.
Click Custom service.
Complete the Custom service (a-e) form and then click Next (f).
a. Select By providing credentials.
b. Enter the following value in the URL field (use the copy icon to avoid typographical errors). This is the URL for the shared OpenSearch instance. In later sections, you create and customize a dedicated instance.
https://wxa4z-opensearch-wrapper-wxa4z-demo-v2-1-0.wxo4z-opc-opensearch-clus-47e063e6a3ad1f71bf2e58f91c3b4c2e-0000.us-south.containers.appdomain.cloud/v1/query\nc. Select Basic authentication in the Choose an authentication type drop-down list.
d. Enter admin in the Username field.
e. Enter secureP@ssw0rd! in the Password field.
secureP@ssw0rd!\nEnable conversational search and then click Save.
Update the conversational search custom service settings based on your requirements.
Note: The Settings page is divided into two sections in the following images to enhance the visibility of the screen captures.
Learn more about these custom service settings here.
The following settings are proven to work well. You can experiment with these settings to see how they affect queries for your client's pilot.
a. Enable Conversational search.
b. Select Single turn. Multi-turn conversation (by selecting Entire conversation) is supported by the offering, but has not been fully included in the lab guide. See the callout in the Testing conversational search section below.
c. Specify the text that appears to instruct the user to expand the list of citations in the assistant (except web chat client).
d. Select Lowest for the retrieval confidence threshold setting. This setting checks the confidence of the retrieved citations before a response is generated.
e. Select Verbose for the generated response length. This setting affects the average response length. Depending on user input, variations from the selected length can occur.
f. Select Lowest for the response confidence threshold. This setting checks the confidence of the generated citations after the response is generated.
g. Keep the default setting of All for the listing of citations.
h. Keep the Default filter field empty.
i. The Metadata field provides a way to adjust your assistant\u2019s behavior during conversational search for your OpenSearch instance. This option is explored in detail in the Installing and using zassist to ingest client documents. Leave the field empty for now.
j. The Search display text options specify the default text displayed when no results are found or when connectivity issues to the backend search service occur. You can keep the defaults or customize the service.
Click Save (a) and then click Close (b).
After you save and close the Conversational search configuration page, a few more configurations are needed to get the best experience from your conversational chat. Details on these settings are available here.
Hover over the Generative AI icon () in the left navigation and click Actions.
Click Set by assistant under the All items menu.
Click No matches.
Click Step 1 under Conversation steps.
Select without conditions (a) in the Is taken drop-down menu and then click Clear conditions (b).
Note: the Is taken value does not change from with conditions after selecting without conditions.
Delete the default text in the Assistant says entry field.
Expand the And then drop-down menu and select Search for the answer.
Click Edit settings.
Click After generation.
Select End the action after this step and then click Apply.
Click Save ().
Select Step 2 (No matches count) under Conversation steps and click delete ().
Click Delete in the confirmation dialog to delete Conversation step 2.
Click Close (the x icon) the Editor window.
Click Fallback in the Actions table.
Delete all of the Conversation steps.
Note: The following image is edited. Only five steps are shown, but all six need to be deleted. You need to select each step individually. Click delete () and confirm the deletion.
Verify that all Conversation steps are deleted and then click the x to close the Editor window.
Click the Global settings ().
Click No matches under the Conversation routing tab.
Move the slider to More often (or select More often in the drop-down).
The setting helps ensure that actions are triggered less often unless the user\u2019s query specifically matches the action\u2019s input.
Click Autocorrection.
Click the autocorrection toggle to turn the feature Off.
Click Save (a) and then Close (b).
Hover over the Home () and click Environments.
Click Web chat.
On the Style tab, click the Streaming toggle to enable streaming.
The streaming setting allows responses to be streamed to the assistant and displayed as they are generated versus waiting until the full response is received and then displayed.
Click the Home screen tab.
Customize the Home screen by setting a custom Greeting message and deleting the default Conversation starters. Optionally, adjust the Background style.
Click Suggestions.
Click the Suggestions toggle to turn this feature Off.
Click (a) Save and exit and then click (b) Close.
There are enhancements that you can make to configure how the large language model (LLM) responds to your queries, including adding prompt instructions and configuring the LLM\u2019s answer behavior. The options are summarized here.
Hover over the Home () and click Generative AI.
Click Add instructions.
Enter a prompt instruction.
Your assistant's LLM gives refined responses by following the prompt's instructions, which clarify how to achieve the end-goal of an action.
Enter prompt instructions in the field. The maximum number of characters you can enter in the prompt instruction field is 1,000.
The following is an example prompt instruction that works well. Experiment with different prompt instructions.
You are a subject matter expert on mainframe systems. Please respond to all prompts with truth and accuracy. Keep all answers short and concise, unless requested to provide details.\nNote: When the instructions are typed in, they are automatically saved and the LLM is immediately trained on them.
Toggle General-purpose answering to Off and then click Save ().
The ability exists to configure the answering behavior of your assistant to provide responses that are based on the preinstalled content or general content.
On the Generative AI page (under Prompt Instructions), you see the Answer behavior section. After you configure Conversational search, you see that it is enabled (toggled on) with the search integration added.
If you enable both general-purpose answering and conversational search, conversational search answering takes precedence over General-purpose answering.
Recommendation: For purposes of retrieving Z-specific answers and responses, it is recommended that you turn off general-purpose answering and leave only conversational search turned on.
Now, you can begin issuing queries to test the assistant's responses. For more detailed responses, try appending \"Please provide a detailed response.\" to the end of your question.
Important: Modify settings iteratively based on your assessment of response quality. Review and change them at any time. For example, add extra prompt instructions, change response verbosity, and modify OpenSearch indexes.
Hover over the Home () and click Preview.
Experiment with different prompts and validate that the answers are reasonable and related to IBM Z.
Other prompts and responses follow.
Note: The responses that you receive can vary from the ones shown.
Prompt:
What is z/OS continuous delivery?\nExample output:
Prompt:
What is the APF list in z/OS?\nExample output:
Prompt:
Why is Db2 different than other database systems?\nExample output:
Prompt:
What happens during an IPL on IBM Z?\nExample output:
Experiment with multi-turn (entire conversation) contextual awareness.
In the December 2024 release of IBM watsonx Assistant for Z support for multi-turn contextual awareness was added. This capability enables the assistant to use an entire session history for retrieving search results and generating answers. This handles context-dependent questions well but may over-rely on past topics, even if the user has moved on.
Experiment with this setting by changing your custom service contextual awareness setting from Single turn to Entire conversation.
Once enabled, try sequential prompts like:
What are some features of z/OS?\nGive me an itemized list?\nTell me more about item 3.\nYou have a working assistant that uses IBM Watson Assistant for Z. Explore different prompt instructions and settings. If you encounter issues, refer to the Troubleshooting section that follows for resolution.
Continue to the Creating a stand-alone OpenSearch instance for document ingestion to learn how to configure a dedicated OpenSearch instance for ingesting client-specific documentation into the RAG model.
"},{"location":"Setup/creatingAssistant-configuringConvoSearch/#troubleshooting","title":"Troubleshooting","text":"The following are issues that you may encounter. If the provided resolutions do not work, contact support by using the methods that are mentioned in the Support section.
Assistant responds to all prompts with, \"I might have information related to your query to share, but am unable to connect to my knowledge base at the moment\"This Assistant is unable to connect to the custom service URL specified. This could be a network issue, the service may be down, the service may be restarting, or the service is no longer running at that URL.
Before reaching out to Support, try the following:
Wait a few minutes and try again. It may be the service was in the process of restarting.
If you printed this demonstration guide or saved a copy, verify you are using the most current version of the lab guide and the correct service URL (https://wxa4z-opensearch-wrapper-wxa4z-demo-v2-1-0.wxo4z-opc-opensearch-clus-47e063e6a3ad1f71bf2e58f91c3b4c2e-0000.us-south.containers.appdomain.cloud/v1/query). The URL may have changed since you saved or printed the lab guide.
Now that you created and deployed your own assistant with conversational search capabilities, your client can understand how watsonx Assistant for Z provides its content-grounded responses to any Z-related questions. In the previous section, you configured your assistant to use a pre-configured Z RAG that has over 220 knowledge sources, and uses this knowledge to provide AI-generated responses.
Next, learn to enable clients to personalize the assistant with an internal knowledge base that contains documentation they add to the Retrieval Augmented Generation (RAG). This helps provide a level of context-awareness for their own environment when environment-specific questions are asked to the assistant.
Now, install and configure a \u201cZ RAG\u201d on Red Hat OpenShift enabling the bring-your-own-search (BYOS) and bring-your-own-documentation (BYOD) capability to ingest other documentation. In doing so, you deploy a dedicated OpenSearch instance (BYOS). Then, connect your assistant to the new RAG database to provide responses based on the ingested documentation (BYOD).
Below is a high-level, logical architecture of the environment deployed in this section.
Earlier, you provisioned three IBM Technology Zone (ITZ) environments. One of which was a single-node Red Hat OpenShift (SNO) cluster. If you have not reserved this environment, or it is not in the Ready state, return to the IBM Technology Zone environment section to complete the reservation.
"},{"location":"byosd/documentIngestion/#install-the-red-hat-openshift-command-line-interface-utility","title":"Install the Red Hat OpenShift command line interface utility","text":"The Red Hat OpenShift command line interface (CLI) utility, which is known as oc, must be installed on your local workstation. If you already installed the oc utility, you can proceed to log in to the SNO cluster.
Click the following link to open a browser window to your ITZ reservations.
ITZ My reservations
Click the Single Node OpenShift tile.
Scroll down and record the Cluster Admin Username and Cluster Admin Password.
Click the OCP Console link.
Note: OCP stands for OpenShift Container Platform.
Enter the Cluster Admin Username and Cluster Admin Password values from step 3 and click Log in.
Click Help () and then click Command Line Tools.
Click the link under oc - OpenShift Command Line Interface (CLI) for the operating system of your local machine.
Clicking the preceding link automatically downloads either a .zip or .tar file specific to your operating system. Extract the file's content. Place the oc binary for your operating system (OS) in a directory that is in your default PATH, or set the PATH environment variable to include the location of the oc binary.
Verify the installation by running the oc command on your local workstation.
oc --help\nThe oc binary may cause a security exception. Adjust the security settings by opening the System Settings utility and clicking Privacy & Security. Under Security locate the message about the oc binary and click Allow Anyway. Return to the terminal window and try the oc --help command again and click Allow Anyway when prompted.
Before ingesting documents, complete the following setup steps.
"},{"location":"byosd/documentIngestion/#log-in-to-the-openshift-cluster-from-your-local-terminal","title":"Log in to the OpenShift cluster from your local terminal","text":"Note: If you just installed the oc utility, skip the next 5 steps.
Click the following link to open a browser window to your ITZ reservations.
ITZ My reservations
Click the Single Node OpenShift tile.
Scroll to the bottom of the reservation page and record the Cluster Admin Username and Cluster Admin Password.
Click the OCP Console link.
Enter the Cluster Admin Username and Cluster Admin Password values from step 3 and click Log in.
Click the kube:admin profile drop-down and click Copy login command.
Click Display Token.
Select and copy the Log in with this token string.
For most operating systems, double-click the value, then right-click and select Copy.
Open a command prompt or terminal window on your local workstation.
Paste the login command and press enter.
Create a directory to store the configuration files that you will create in the next steps.
Instructions vary by your local workstation's operating system.
The directions that follow may vary depending on your operating system. The examples provided are based upon MacOS.
mkdir watsonxAssistant\nChange to the new directory.
cd watsonxAssistant\nIn a text editor, create a file that is named catalogCertManager.yaml and paste the following text in the file.
Formatting of the yaml file is critical!
The content of the YAML file must be formatted exactly as shown. Use the Copy icon to prevent typographical errors.
File name:
catalogCertManager.yaml\nFile contents:
apiVersion: operators.coreos.com/v1alpha1 \nkind: CatalogSource \nmetadata: \n name: ibm-cert-manager-catalog \n namespace: openshift-marketplace \nspec: \n displayName: ibm-cert-manager-4.2.7 \n grpcPodConfig: \n securityContextConfig: restricted \n image: icr.io/cpopen/ibm-cert-manager-operator-catalog@sha256:4dcf4ace4b5f166f83b31063f7e6404dbf78d8e98a9d4fcf52fedf576a55ca6c \n publisher: IBM \n sourceType: grpc \n updateStrategy: \n registryPoll: \n interval: 30m0s\nInstall the IBM Certificate Manager operator in the Red Hat OpenShift cluster.
oc apply -f catalogCertManager.yaml\nThe preceding command returns a message that states the ibm-cert-manager-catalog was created.
In the OpenShift web console, click Operators and then select OperatorHub.
Click the Project to pull-down menu and click the Show default projects toggle.
Scroll down and select openshift-marketplace.
Enter IBM Cert Manager in the search field and then click the IBM Cert Manager tile.
Be patient.
It may take a minute or two for the IBM Cert Manager tile to appear.
Note: The current version of the operator may differ than shown in the image below. Select the most current version.
Click Install.
Keep the default settings and click Install.
Do not continue until...
The installation process takes a few minutes. Do not continue until you see the following message: Installed operator: ready for use.
In your command prompt or terminal window, create a new namespace called wxa4z-byos in the Red Hat OpenShift cluster.
oc create namespace wxa4z-byos \nCreate or obtain your IBM Container Software production entitlement key.
A production entitlement key is required to pull the container images that get deployed by the operator.
To create or retrieve your existing entitlement key, follow the instructions here.
If you don't have an entitlement key at the above link, click the Add new key to create a new one or visit this link to create a new one.
If extra assistance is needed, refer to this site. Note, the process here is not
Locate your existing key or create a new one and continue to the next step.
Click copy and record your entitlement key for future use in a secure location.
In your command prompt or terminal window, set an environment variable with your production entitlement key.
Substitute your production entitlement key copied in the last step for <entitlement key>.
Mac OS:
export IBM_CS_ENT_KEY=<entitlement key>\nMicrosoft Windows:
set IBM_CS_ENT_KEY=<entitlement key>\nEnter the following command to create a pull secret for the Container Registry.
Mac OS:
oc -n wxa4z-byos create secret docker-registry icr-pull-secret --docker-server=cp.icr.io --docker-username=cp --docker-password=$IBM_CS_ENT_KEY\nMicrosoft Windows:
oc -n wxa4z-byos create secret docker-registry icr-pull-secret --docker-server=cp.icr.io --docker-username=cp --docker-password=%IBM_CS_ENT_KEY%\nIn a text editor, create a file that is named catalogSource.yaml and paste the following text in the file.
Formatting of the yaml file is critical!
The content of YAML files must be formatted exactly as shown. Use the copy icon to prevent typographical errors.
File name:
catalogSource.yaml\nFile contents:
apiVersion: operators.coreos.com/v1alpha1 \nkind: CatalogSource \nmetadata: \n name: ibm-wxa4z-operator-catalog \n namespace: wxa4z-byos \nspec: \n displayName: \"IBM watsonx Assistant for Z Operator Catalog\" \n image: icr.io/cpopen/ibm-wxa4z-catalog:v2.1.0@sha256:a085d360b6aa0e40cf86a632eb5cd190a0407d1c54ec1b2d1d2fb5507f39a524\n publisher: 'IBM' \n sourceType: grpc \n secrets: \n - icr-pull-secret\nCreate your document catalog in the Red Hat OpenShift operator.
oc apply -f catalogSource.yaml\nIn the Red Hat OpenShift web console, click OperatorHub and select the wxa4z-byos project.
Enter ibm watsonx in the search field and the click the IBM watsonx Assistant for Z Operator Catalog tile.
Be patient.
It may take a minute or two for the IBM watsonx Assistant for Z Operator Catalog tile to appear. Reload the browser page if the operator is not listed.
Note: The current version of the operator may differ than that shown in the image below.
Click Install.
Note: The current version of the operator may differ than the one shown in the image after this. Select the most current version.
Select A specific namespace on the cluster (a) under Installation mode and wxa4z-byos (b) for the Installed Namespace, then click Install (c).
Do not continue until...
The installation process takes a few minutes. Do not continue until you see the following message: Installed operator: ready for use.
In your command prompt or terminal window, run the following commands to add the Container Registry credential to the operator's service account.
Mac OS and Microsoft Windows:
oc project wxa4z-byos\nMac OS:
oc patch serviceaccount ibm-wxa4z-operator-controller-manager --type merge -p '{\"imagePullSecrets\": [{\"name\": \"icr-pull-secret\"}]}'\nMicrosoft Windows:
oc patch serviceaccount ibm-wxa4z-operator-controller-manager --type merge -p \"{\\\"imagePullSecrets\\\":[{\\\"name\\\":\\\"icr-pull-secret\\\"}]}\"\nIn the Red Hat OpenShift web console, under Workloads, click Pods.
Verify the two pods that start with ibm-wxa4z-operator have a status of Running and that all pods are Ready.
Run the following command to set the administrative policy for the workspace.
oc -n wxa4z-byos adm policy add-scc-to-user privileged -z byos\nIn a text editor, create a file that is named os-secret.yaml, paste the following text in the file, and then modify the default password.
File name:
os-secret.yaml\nSubstitute a secure password of your choosing for the string <OPENSEARCH_PASSWORD>. Record this value for later use.
File contents:
apiVersion: v1 \nstringData: \n password: <OPENSEARCH_PASSWORD> \nkind: Secret \nmetadata: \n name: opensearch-creds \n namespace: wxa4z-byos \ntype: Opaque\nCreate the secret by running the following command.
oc apply -f os-secret.yaml\nIn a text editor, create a file that is named client-ingestion-secret.yaml, paste the following text in the file, and then modify the default password.
File name:
client-ingestion-secret.yaml\nSubstitute a secure authentication key of your choosing for the string <CLIENT_INGESTION_AUTHKEY>. The authentication key can be a random password. Record this value for later use.
File contents:
apiVersion: v1 \nstringData: \n authkey: <CLIENT_INGESTION_AUTHKEY> \nkind: Secret \nmetadata: \n name: client-ingestion-authkey \n namespace: wxa4z-byos \ntype: Opaque\nCreate the secret by running the following command.
oc apply -f client-ingestion-secret.yaml\nIn a text editor, create a file that is named wrapper-creds.yaml, paste the following text in the file, and then modify the default password.
File name:
wrapper-creds.yaml\nSubstitute a secure password credential of your choosing for the string <WRAPPER_PASSWORD>. The password can be a random password. Record this value for later use. Use this password in the following steps when you configure your BYOS connection in your assistant to connect to the network route.
File contents:
apiVersion: v1\nstringData:\n username: admin\n password: <WRAPPER_PASSWORD>\nkind: Secret\nmetadata:\n name: wrapper-creds\n namespace: wxa4z-byos\ntype: Opaque\nCreate the secret by running the following command.
oc apply -f wrapper-creds.yaml\nObtain and record your cluster domain that is used for routes by running the following command.
oc -n openshift-ingress-operator get ingresscontroller default -o jsonpath=\"{.status.domain}\"\nThe output from the command does not include a newline.
The value returned for the cluster domain does not include a newline. When copying the value do not include the character or characters used for your command line prompt. Do not include the your prompt in the next step!
Note: The output of the command will be a string similar to: apps.672b79320c7a71b728e523b4.ocp.techzone.ibm.com
In a text editor, create a file that is named byos.yaml and paste the following text in the file.
File name:
byos.yaml\nSubstitute the domain name recorded in the previous step for the string <YOUR_CLUSTER_DOMAIN>.
File contents:
apiVersion: wxa4z.watsonx.ibm.com/v1\nkind: BYOSearch\nmetadata:\n name: byosearch\n namespace: wxa4z-byos\nspec:\n imagePullSecrets:\n - name : icr-pull-secret\n namespace: wxa4z-byos\n clusterName: wxa4z-byos-cluster\n clusterDomain: <YOUR_CLUSTER_DOMAIN>\n\n opensearch:\n secretName: opensearch-creds\n\n persistence:\n enabled: true\n storageClass: \"managed-nfs-storage\"\n accessModes:\n - ReadWriteOnce\n size: 24Gi\n\n wrapper:\n createRoute: true\n resources:\n requests:\n cpu: 2\n memory: \"500Mi\"\n limits:\n cpu: 2\n memory: \"1Gi\"\n\n clientIngestion:\n secretName: client-ingestion-authkey\n\n resources:\n limits:\n cpu: \"500m\"\n memory: 2Gi\n nvidia.com/gpu: \"0\"\n requests:\n cpu: \"500m\"\n memory: 1Gi\n nvidia.com/gpu: \"0\"\n pvc:\n storageClass: \"managed-nfs-storage\"\n enabled: true\n size: 24Gi\nRun the following command to deploy BYOS on your cluster.
oc apply -f byos.yaml\nIn the OCP console, verify that all pods have the status of Running or Completed.
Do not continue until...
The BYOS deployment can take 20 minutes or more to complete. Do not continue until all the pods have a status of \u201cRunning\u201d or \"Completed\". The next step is to retrieve your BYOS endpoint URL.
Under Networking, click Routes.
Copy and record the location for the wxa4z-opensearch-wrapper route.
You are now ready to configure your assistant with the route to your BYOS instance.
Using the network route for your BYOS instance, append the string /v1/query to complete the URL endpoint.
The URL should look similar to:
https://wxa4z-opensearch-wrapper-wxa4z-byos.apps.672b79320c7a71b728e523b4.ocp.techzone.ibm.com/v1/query
Important: The above URL will not work for you. Use the value of your specific OpenSearch instance that is recorded in the previous step.
Update your assistant's custom search integration URL.
Next, you need to return to your assistant in the watsonx Orchestrate AI assistant builder and update the custom search integration URL. Use the URL form the network route (with /v1/query) appended. Use admin for the Username and the Password will be the password that you specified in the wrapper-creds.yaml file.
Don't recall how to set the customer search URL?
Refer back to Creating an assistant and configuring conversational search if you don't remember how to specify the customer search URL.
Test your assistant and verify that it is still answering questions that are related to IBM Z.
Experiment with different prompts and validate that the answers provided are reasonable, and that you can view the documentation that was sourced. If responses are not received as expected, verify that the URL is formatted correctly and you specified the wrapper-creds.yaml password as the admin password.
The following are issues that you may encounter. If the provided resolutions do not work, contact support by using the methods that are mentioned in the Support section.
Pods have a status of ErrImagePull or ImagePullBackoffIf the pods starting with ibm-wxa4z-operator have a status of \u201cErrImagePull\u201d or \u201cImagePullBackoff\u201d, you can delete the pod and it will automatically restart and pull the image successfully. Wait until the pod is re-created successfully.
The wxa4z-client-ingestion pod does not startDid you include the % character in the clusterDomain name when creating the byos.yaml? To resolve, edit the byos.yaml file and run the following command again. The current pod will be terminated and a new one started. This will take about 20 minutes to start.
oc apply -f byos.yaml\nWith bring-your-own-search (BYOS) installed and configured in your assistant, you can now prepare for document ingestion (bring-your-own-documents (BYOD)). BYOD demonstrates how clients can augment their assistant\u2019s conversational search by creating an internal knowledge base with their documentation. Using the client's documentation allows the assistant to provide valuable responses to a range of questions not possible with the default documentation available.
As an example, a client mentioned that their developers often need reference material on company-specific legacy code or company-specific syntax. The users must search through volumes of documentation to find it or look at old code. Also, a need for their operational support group to quickly determine how to resolve technical issues using runbooks exists.
You can show your client how watsonx Assistant for Z can assist developers and operational support personnel in finding answers about internal processes for code development and deployment.
Currently, only PDF, HTML, and DOCX file formats are supported for ingestion.
A high-level, logical architecture of the environment is illustrated in the following diagram.
To prepare for document ingestion, you can also reference the setup instructions that are located here.
"},{"location":"byosd/zassist/#install-the-zassist-utility","title":"Install the zassist utility","text":"The zassist utility is an executable program that automates the ingestion of client documentation into the RAG for watsonx Assistant for Z. A version of zassist is available for download for IBMers and Business Partners for conducting pilots. Follow the steps to download and install zassist.
How do clients get the zassist utility?
The utility is available to clients through IBM Passport Advantage.
Click the following link and download the zassist.zip file.
https://ibm.box.com/s/j3nt5iw4fqd5w2jgcqwxnjlsu8bpvl77
Extract the zassist.zip file.
Locate the appropriate file for your local workstation's operating system.
Either copy the appropriate zassist file to a directory in your PATH, or add the appropriate directory to your PATH environment variable.
Additional information for running the preceding tasks can be found here.
Windows users may need to rename the file zassist file!
If the zassist file does not execute properly, rename the file to zassist.exe.
Run the zassist command to verify that it is working.
zassist\nThe zassist binary may cause a security exception. Adjust the security settings by opening the System Settings utility and clicking Privacy & Security. Under Security locate the message about the zassist binary and click Allow Anyway. Return to the terminal window and try running teh command again.
With the zassist command installed, you are now able to begin ingesting data.
Step-by-step guidance for ingesting documents using zassist is provided in the IBM watsonx Assistant for Z documentation.
Download the BYOD.zip file.
BYOD.zip
What is in the sample client documentation?
Three sample documents are included:
Mainframe_COBOL_Error_Codes.pdf
This is a document containing company-specific mainframe COBOL error codes for their application. Developers within the organization typically review this document to quickly diagnose issues based on the application error codes returned.
Mainframe_Operational_Incidents_Log.pdf
This document is leveraged by the organization\u2019s operational support team and contains historical records of production-level incidents that occurred. For each incident, there\u2019s a record of what the incident was, the date, how it was resolved and who was involved in resolving the incident.
COBOL-CICS-to-Java-Internal-Framework.pdf
This document is leveraged by the development team and contains details about the organization\u2019s internal framework for developing applications consisting of legacy COBOL CICS interoperating with new Java code. Within the document contains company-specific coding practices and code syntax that the developers frequently reference.
Extract the BYOD.zip file.
BYOD directory.Set the TLS_VERIFY environment variable to false.
Mac OS:
export TLS_VERIFY=false\nWindows OS:
set TLS_VERIFY=false\nInitialize the zassist environment.
zassist init\nRetrieve the server URL for the client ingestion server.
Mac OS:
echo https://$(oc -n wxa4z-byos get route wxa4z-client-ingestion -o jsonpath=\"{.spec.host}\")\nThe output of this command is your unique URL for your client ingestion server.
Windows OS (this method can also be used by Mac OS users):
You can retrieve the URL in your OCP Web console by navigating to Networking Routes and then copy the URL for the wxa4z-client-ingestion route.
Retrieve the client-ingestion-authkey.
oc -n wxa4z-byos get secret client-ingestion-authkey -o jsonpath=\"{.data.authkey}\" | base64 -d\nThe output of this command is your unique auth-key that you had previously set. You will need the output of both previous commands in the next step.
If the command doesn\u2019t work for you...You can find your authkey value by viewing the client-ingestion-secret.yaml file you created and copying the value set for the authkey parameter.
Login to your server. Replace <server url> with the value from step 6.
zassist login <server url>\nWhen prompted, enter the password from step 7. Verify that a Success message is received.
Verify zassist is ready to ingest documents by checking the status.
zassist status\nIngest the documentation using the commands.
For the next steps, you must be in the root directory called BYOD.
zassist ingest dev\nzassist ingest ops\nUpload the ingested documents.
zassist load dev\nzassist load ops\nVerify that all documents were successfully ingested and loaded.
zassist status\nUse the watsonx Orchestrate AI assistant builder to verify your document ingestion.
Enter the following prompt in your assistant and record the response (cut and paste into a text file on your local machine).
The customer application is failing with ERR-CBL-001, what does this internal error mean?\nClick the Down arrow to view the citations for the response.
Click View source for the Mainframe_COBOL_Error_Codes-... citation.
Take note of the order of the response citations!
Accept the security risk to view the source document for any ingested document cited.
The steps to accept the security risk for the document are not shown as it varies by the browser you are using. The risk occurs because the certificate for the connection to the SNO instance is not secure. Notice that the URL contains the path to your SNO instance route.
Repeat the preceding steps for the following prompts in your assistant and record the responses (cut and paste into a text file on your local machine).
Are there any production incidents that were resolved in relation to Data corruption in the production database. If yes who can I collaborate with to resolve a similar issue today and what are their names?\nWhat specific syntax changes do I need to make in COBOL to call Java using the internal framework? Please provide a detailed explanation. \nWhat is the internal git lab link to execute the Java on z/OS pipeline?\nDo you recall the Metadata field when you configured your assistant?
The Metadata field provides a way to adjust your assistant\u2019s behavior during conversational search for your OpenSearch instance. Now that you have your own docs that are ingested for conversational search, you can set the metadata field for your assistant to use those documents in its content-grounded search. If you leave the metadata field empty, then it defaults to settings found to perform well but may not use the ingested documents as part of the search results.
If you leave the Metadata field empty, OpenSearch relies on the default settings, which means OpenSearch searches all the default IBM-provided documentation and all of the ingested customer documentation using the following value:
{\"ibm_indices\":\"*_ibm_docs_slate,*_ibm_redbooks_slate\",\n\u201ccustomer_indices\u201d:\u201ccustomer_*\u201d}\nReplacing the wildcard string with an explicit list of indices allows for personalization. The metadata setting is where you can input specific indices (pointing to the underlying documentation) that you want your assistant to use for the content-grounded search. There are over 220 products and topics that the OpenSearch instance has IBM Documentation for. You can find those indices and products here.
You can input a subset of indices into the \u201cMetadata\u201d field in cases where you want your assistant to only gather context for specific IBM products or topics. The specific indices can be listed out in this format:
{\u201cibm_indices\u201d:\u201c<comma separated index values>\u201d,\u201ccustomer_indices\u201d:\u201ccustomer_*\u201d}\nFor example, if you want your assistant to reference only documentation for \u201cDb2 Analytics Accelerator for z/OS\u201d and no ingested client documentation, you can enter the following into the metadata field:
{\u201cibm_indices\u201d:\u201css4lq8_ibm_docs_slate\u201d}\nIf you have a mix of IBM Documentation and client documentation ingested, then there\u2019s an optional search string that you can use to set the \u201cweights\u201d used for each.
For example:
{\"doc_weight\":\n{\"product_docs\":0.5,\n\"customer_docs\":0.5},\n\"ibm_indices\":\"*_ibm_docs_slate,*_ibm_redbooks_slate\",\n\"standardize\":true,\n\"customer_indices\":\"customer_*\"\n}\nSet the (a) Metadata field for your BYOS custom search instance to the following value, click (b) Save, and then click (c) Close. Notice the weight for customer_docs is heavier than the weight for product_docs.
{\"doc_weight\":\n{\"product_docs\":0.2,\n\"customer_docs\":0.8},\n\"ibm_indices\":\"*_ibm_docs_slate,*_ibm_redbooks_slate\",\n\"standardize\":true,\n\"customer_indices\":\"customer_*\"\n}\nHover over the Home () icon and click Preview.
Click the Restart conversation () icon.
Repeat the queries four queries run earlier and record the results and the order of the response citations.
Compare the two sets of results. Notice how the answers changed based on the weighting of the ingested documents versus the IBM product documentation. Were the ingested documents always the first document cited? If not, why do you think that is?
Before proceeding, experiment with different metadata and other configuration settings for your custom service instance.
For client pilots
If you or your client have other documents to ingest, you can do so by repeating the steps using zassist. The Velocity Pilot ITZ environment is limited in compute and storage capacity. The following limits should be adhered to:
Loading documents can take a long time, especially with > 100 MB of text.
It is recommended to run large loads late at night.
When loading, ensure your workstations does not sleep during the process.
If you receive a batch time error, set the batch size to a lower number for that command. For example:
zassist ingest . -s 50\nOnce you have a subset of skills that are published, the application you created can be connected to your assistant.
Expand the main menu and select Skill sets.
Click the Team Skills drop-down and select the Draft of your assistant.
Click the Connections tab.
Click the Search () icon.
Search for the application name you specified in the previous section.
Click the ellipses () and click Connect app.
On the Connect to Ansible Controller Skills form, keep the defaults and click Connect app.
Enter the username (a) and password (b) using the username (admin) and password for your IBM Technology Zone (ITZ) watsonx Assistant for Z Pilot - AAP & z/OS reservation, and then click Connect app (c).
The application is now connected to the draft version of your assistant.
Continue to the next section to create actions for your assistant.
"},{"location":"skills/creatingActions/","title":"Create actions for the assistant","text":""},{"location":"skills/creatingActions/#creating-actions-for-your-assistant","title":"Creating actions for your assistant","text":"Now that the skills in your application are connected to your assistant, you are ready to create actions that are tied to those skills. Learn more about building actions here
"},{"location":"skills/creatingActions/#configure-the-number-of-input-fields","title":"Configure the number of input fields","text":"Before configuring actions, it is important to modify a setting within watsonx Orchestrate that allows triggered skills to display as forms (versus conversational skills).
Click your (a) profile icon and then click (b) Settings
Learn more about configuring input fields here.
Click the Skill configurations tab.
Enter 0 for the Number of form fields.
Click the main menu and select AI assistant builder.
Hover over the Home icon () and click Actions.
Click Create action.
Click the Skill-based action tile.
Select the z/OS Gather Facts tile and click Next.
Note, it may take a minute for the page to display the action tiles. The date that is shown in the z/OS Gather Facts tile reflects when you added the skill to your application.
On the New action dialog, (a) enter a prompt a user of the assistant might use to initiate the action and then (b) click Save.
Sample prompts:
Get z/OS facts\nGather z/OS facts\nAdd any extra prompts (a) and then click the save () (b).
Click Preview.
Enter one of the prompts you specified in step 9 or 10.
Prompt:
Get z/OS facts\nReview the returned results and record the job number.
If an error is generated or the action is not performed and only search results are returned, review the following Troubleshooting section.
Return to the Ansible Automation Platform (AAP) console and review the job information.
Click Jobs and then click the job number that you recorded in the previous step for the z/OS Gather Facts skill.
Review both the Details and Output for the z/OS Gather Facts job.
Recall, that in the assistant, the contents shown in the Output of the Ansible job were not displayed.
IBM watsonx Assistant for Z provides utility skills to retrieve the job output. It is also possible to create a skill flow that executes the z/OS Gather Facts skill followed by the Retrieve job output utility skill in sequence; passing the job ID from the first skill to the second to view the output within the assistant. Creating a skill flow is covered in the next section.
"},{"location":"skills/creatingActions/#troubleshooting","title":"Troubleshooting","text":"Skill returns \"Sorry, we're having issues generating a response\" or the action is not performed and only search results are returned.This error appears to be an intermittent issue when a skill is first added. To resolve, add the skill to your personal skills catalog using the steps that follow. If you encounter the issue, try the steps that follow:
Expand the main menu and select Chat.
Click Add skills from the catalog.
Search for the skill app you created earlier and click the tile for your app.
Click Add skill for all the skills you want to add.
Click Connect app.
Enter the (a) username and (b) password using the username (admin) and password for your IBM Technology Zone (ITZ) watsonx Assistant for Z Pilot - AAP & z/OS reservation (AAP User Password (Use SSH key to login, only use password for UI)), and then click Connect app.
Expand the main menu and select Chat.
Try one of the prompts you created for your skill.
Prompt:
Gather z/OS facts\n
You should now be able to run the skill through the assistant preview.
"},{"location":"skills/creatingCustomActions/","title":"Create custom-built actions","text":""},{"location":"skills/creatingCustomActions/#creating-custom-built-actions","title":"Creating custom-built actions","text":"To this point, you learned how to:
import skills into watsonx Orchestrate
add applications with those skills to your assistant
create skill-based actions for your assistant
combine skills in a skill flow
You can also create custom-built actions. Custom-built actions have actions with different steps to take in conversations and form sequences of prompts that define the conversation experience. The steps can be defined with or without conditions, which help control the custom responses. Steps within the custom action can end with routing to conversational search, triggering another existing subaction, and other actions. Custom-built actions are a powerful way of customizing the user's experience.
Learn more about creating custom-built actions here.
"},{"location":"skills/creatingFlows/","title":"Create skill flows for the assistant","text":""},{"location":"skills/creatingFlows/#creating-skill-flows","title":"Creating skill flows","text":"In the previous section, you ran the Gather z/OS facts skill, but the output was not displayed in the assistant. To both run the action and display the results, a skill flow is needed. Skills are often more valuable when combined with other skills. You can create a skill flow to use two or more skills together to finish a task (like returning the output of a previous skill). When you create a skill flow, you map the output of one skill as the input for subsequent skills. Learn more about creating skill flows here.
As mentioned in a previous section, default utility skills that are provided with the watsonx Assistant for Z skills collection. The Retrieve job output utility skill is used to return the output of a skill.
"},{"location":"skills/creatingFlows/#add-the-utility-skill","title":"Add the utility skill","text":"Open IBM watsonx Orchestrate Skill studio.
Expand Create and click Import API.
Click the z/OS Skills accelerator (Trial) tile.
Enter the following values in the z/OS Skills accelerator form and then click Connect.
Use the URL, User Name, and Password values recorded in the Explore Ansible Automation Platform section earlier.
a: Connection Type: ansible
b: Application Name: <use the same application name from the previous section>
c: Connection URL: <enter the URL for your AAP UI>
d: User Name: <enter the AAP User Name (for UI access)>
e: Password: <enter the AAP User Password>
f: Search Pattern: *
Expand Ansible Utility Skills and click Ansible Utility Skills.
Select Retrieve job output and click Save as draft.
Click the ellipses () for the Retrieve job output skill and select Enhance this skill.
Review the skill settings and then click Publish.
Select Skill sets from the main menu.
Select (a) your draft assistant in the Team Skills drop-down list and (b) click the Connections tab.
Click the Search () icon.
Search for the application name you specified earlier.
Click the (a) ellipses () for your application and (b) click Edit connection.
Verify that the application is Connected (a) and then click Close (b).
Connect the application if it is not connected.
Use the AAP user name (admin) and the AAP password for your ITZ reservation.
Click Skill catalog in the main menu.
Search for the application name you specified earlier.
Click the tile for your application.
Note, the tile name is proceeded by Ansible Controller Skills.
Click Add skill for each of the skills you want to add to the flow.
Click Skill studio in the main menu.
Expand the Create drop-down menu and click Skill flow.
Click the + icon.
Next, you need to add the z/OS Gather Facts skill and the Retrieve job output skill to the skill flow. Use the Search apps function to locate the skills.
Search for the application name you specified earlier and click the tile.
Click Add Skill in the z/OS Gather Facts tile.
Verify the z/OS Gather Facts skill is added to the skill flow.
Click the + icon after the z/OS Gather Facts tile.
Repeat steps 5 and 6 for the Retrieve job output skill.
After adding the Retrieve job output skill, your skill flow should look like:
Next you must map the output values of the first skill to the input of the second skill. In this case, pass the job ID output from z/OS Gather Facts as an input for Retrieve job output.
Click the Retrieve job output tile.
Select the Input tab and click the id field.
Click the z/OS Gather Facts skill in the Mapping data for \"id\" section.
Click the job icon.
Verify that the job appears in the id field.
Optionally, toggle the Hide this from the user setting.
For this lab guide, this option is left disabled. Learn more about this option here.
Click the x to close mapping window.
Click the pencil ().
Enter a (a) Name and (b) Description for your skill flow and then (c) click Save.
Expand the Actions pull-down and click Save as draft.
Expand the Actions pull-down and click Enhance.
On the Enhancing the skill pages, you can:
modify the skill name, description, and version
add phrases (prompts) that will be recognized by the assistant to call the skill flow
Click the Phrases tab.
Replace the existing phrases (prompts) and then click Publish.
Notice that the default prompts are either not intuitive (the skill flow name) or a bit verbose. Replace the existing phrases with phrases that you anticipate users will use.
Example prompts:
Show me z/OS facts\nGather and display z/OS facts\nClick AI assistant builder in the main menu.
Hover over the Home () and click Actions.
Click New action.
Click the Skill-based action tile.
Click the skill flow that you created earlier and then click Next.
Note: it may take a minute for the tiles to appear on the screen.
Enter an example prompt for the skill and click Save.
You can use one of the prompts you used earlier for the skill flow.
Show me z/OS facts\nEnter any additional phrases (prompts) and then click the save ().
Click close (x).
Select the original skill that you created (a) (not the skill flow you just created), click the ellipses (b), and then click Delete (c).
Wait for system training to complete.
Note: The message changes to \"System is trained\" and then disappears.
Click Preview.
Enter one of the prompts you specified into the assistant preview.
Show me z/OS facts\nWait 10 seconds and then click Apply.
Note: It is important to wait for the first job to complete before submitting the second job in the flow.
Review the results from the skill flow.
Use both scroll bars in the assistant preview to review all the returned information. The output is similar to what was seen in the AAP web console. The character strings like [0;32m are special characters that are not properly displayed in the assistant preview interface.
Content
Identity\u00a0added:\u00a0/runner/artifacts/16/ssh_key_data\u00a0(/runner/artifacts/16/ssh_key_data) [1;35m[WARNING]:\u00a0Collection\u00a0ibm.ibm_zos_core\u00a0does\u00a0not\u00a0support\u00a0Ansible\u00a0version\u00a02.14.2[0m
PLAY\u00a0[Gather\u00a0z/OS-specific\u00a0facts.]\u00a0*********
TASK\u00a0[Gather\u00a0all\u00a0facts\u00a0about\u00a0z/OS\u00a0host.]\u00a0********* [0;32mok:\u00a0[zos_host][0m
TASK\u00a0[Print\u00a0gathered\u00a0facts\u00a0about\u00a0the\u00a0master\u00a0catalog.]\u00a0**** [0;32mok:\u00a0[zos_host]\u00a0=>\u00a0{[0m [0;32m\u00a0\u00a0\u00a0\u00a0\"msg\":\u00a0[[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"master\u00a0catalog\u00a0dsn:\u00a0CATALOG.VS01.MASTER\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"master\u00a0catalog\u00a0volser:\u00a0OPEVS1\"[0m [0;32m\u00a0\u00a0\u00a0\u00a0][0m [0;32m}[0m
TASK\u00a0[Print\u00a0only\u00a0CPC\u00a0and\u00a0IODF\u00a0info\u00a0from\u00a0gathered\u00a0z/OS\u00a0facts.]\u00a0****** [0;32mok:\u00a0[zos_host]\u00a0=>\u00a0{[0m [0;32m\u00a0\u00a0\u00a0\u00a0\"msg\":\u00a0[[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"manufacturer:\u00a0IBM\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"model:\u00a0A00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"plant:\u00a0C1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodf\u00a0name:\u00a0PROV.IODF00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodf\u00a0config:\u00a0DEFAULT\"[0m [0;32m\u00a0\u00a0\u00a0\u00a0][0m [0;32m}[0m
TASK\u00a0[Print\u00a0out\u00a0all\u00a0gathered\u00a0facts\u00a0about\u00a0the\u00a0z/OS\u00a0host.]\u00a0***** [0;32mok:\u00a0[zos_host]\u00a0=>\u00a0{[0m [0;32m\u00a0\u00a0\u00a0\u00a0\"ansible_facts\":\u00a0{[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"arch_level\":\u00a0\"2\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"cpc_nd_manufacturer\":\u00a0\"IBM\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"cpc_nd_model\":\u00a0\"A00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"cpc_nd_plant\":\u00a0\"C1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"cpc_nd_seqno\":\u00a0\"20D90792EB76\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"cpc_nd_type\":\u00a0\"008562\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"edt\":\u00a0\"00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"hw_name\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"ieasym_card\":\u00a0\"(00,K2)\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"io_config_id\":\u00a0\"00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodate\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodesc\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodf_config\":\u00a0\"DEFAULT\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodf_name\":\u00a0\"PROV.IODF00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iodf_unit_addr\":\u00a0\"DE28\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"ioproc\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"iotime\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"ipaloadxx\":\u00a0\"K2\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"ipl_volume\":\u00a0\"D25VS1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"load_param_device_num\":\u00a0\"DE28\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"load_param_dsn\":\u00a0\"SYS0.IPLPARM\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"lpar_name\":\u00a0\"\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"master_catalog_dsn\":\u00a0\"CATALOG.VS01.MASTER\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"master_catalog_volser\":\u00a0\"OPEVS1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"nucleus_id\":\u00a0\"1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"operator_prompt_flag\":\u00a0\"M\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"parmlib_dsn\":\u00a0\"K2.PARMLIB\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"parmlib_volser\":\u00a0\"USRVS1\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"primary_jes\":\u00a0\"JES2\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"product_mod_level\":\u00a0\"00\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"product_name\":\u00a0\"z/OS\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"product_owner\":\u00a0\"IBM\u00a0CORP\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"product_release\":\u00a0\"05\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"product_version\":\u00a0\"02\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"smf_name\":\u00a0\"VS01\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"sys_name\":\u00a0\"VS01\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"sysplex_name\":\u00a0\"LOCAL\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"tsoe_rel\":\u00a0\"05\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"tsoe_ver\":\u00a0\"4\",[0m [0;32m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"vm_name\":\u00a0\"\"[0m [0;32m\u00a0\u00a0\u00a0\u00a0}[0m [0;32m}[0m
PLAY\u00a0RECAP\u00a0*********** [0;32mzos_host[0m\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0:\u00a0[0; 32mok=4\u00a0\u00a0\u00a0 [0m\u00a0changed=0\u00a0\u00a0\u00a0\u00a0unreachable=0\u00a0\u00a0\u00a0\u00a0failed=0\u00a0\u00a0\u00a0\u00a0skipped=0\u00a0\u00a0\u00a0\u00a0rescued=0\u00a0\u00a0\u00a0\u00a0ig nored=0\u00a0\u00a0\u00a0
The previous scenario might or might not be relevant for your client's use case. The scenario illustrates how to sequence skills together in a skill flow to create an action that your assistant triggers based on prompts that use the pre-configured Ansible automation templates. You are encouraged to create your own skill flows and prompts that use other skills available within the AAP instance. As an example, create a skill flow for the z/OS Ping skill. Be sure to add the Retrieve job output skill to view the results.
Next, learn about custom-built actions.
"},{"location":"skills/exploreAAP/","title":"Explore Ansible Automation Platform","text":""},{"location":"skills/exploreAAP/#explore-ansible-automation-platform","title":"Explore Ansible Automation Platform","text":"After you reserved the Ansible Automation Platform (AAP) and Wazi z/OS environment in IBM Technology Zone (ITZ) and the reservation is in the Ready state, follow these steps to explore AAP.
"},{"location":"skills/exploreAAP/#access-the-aap-and-wazi-as-a-service-environment","title":"Access the AAP and Wazi as a Service environment","text":"Be sure to record the information as instructed
Several of the steps below instruct you to record values from your ITZ reservation. Be sure to do this as they will not only be used in this section, but also in later sections of the lab guide.
In the IBM Technology Zone portal, expand My TechZone and select My Reservations, or click the following link.
ITZ My reservations
Click the watsonx Assistant for Z Pilot - AAP & z/OS tile.
Locate and record the AAP User Name (For UI access) and AAP User Password fields.
Record and then click the Ansible Automation Platform UI link.
Enter the Username and Password that is recorded in step 3 and click Log In.
Click Templates under the Resources section.
The AAP instance is preconfigured to the Wazi aaS instance
Note that because the AAP instance and the back-end z/OS system are preconfigured, no changes are needed to execute the templates and they will target your provisioned z/OS system by default.
Locate the z/OS Ping template and click the rocket () icon to start the template.
Observe the z/OS Ping job run.
Take time to explore the other templates that are ready to use. Learn more about the automation capabilities here.
"},{"location":"skills/gettingStartedSkills/","title":"Get started with skills and actions","text":""},{"location":"skills/gettingStartedSkills/#getting-started-with-skills-and-actions","title":"Getting started with skills and actions","text":"Watsonx Assistant for Z automates a range of IBM Z related tasks through assistant interactions by importing skills. Each skill is a pre-defined automation that accomplishes some unit or units of work by running tasks. For example, skills can view z/OS IPL information or work with z/OS datasets.
Watsonx Assistant for Z extends watsonx Orchestrate, allowing users to build new skills from Ansible Automation platform or z/OS Management Facility (z/OSMF) through the Z Skills Accelerator extension. The Z Skills Accelerator extension connects Ansible and z/OS application programming interfaces (APIs) and imports automation as Ansible Playbooks, JCL, or REXX as skills. Learn more importing and building skills here.
Aa high-level, logical architecture of the environment is illustrated in the figure that follows.
"},{"location":"skills/gettingStartedSkills/#environments","title":"Environments","text":""},{"location":"skills/gettingStartedSkills/#watsonx-orchestrate","title":"Watsonx Orchestrate","text":"The Z Skills Accelerator extension is already configured in your watsonx Orchestrate IBM Technology Zone (ITZ) environment. You can use this component to import new skills.
"},{"location":"skills/gettingStartedSkills/#ansible-automation-platform-and-wazi-as-a-service","title":"Ansible Automation Platform and Wazi as a Service","text":"To import skills for automations, you use Ansible Automation Platform (AAP) and Wazi as a Service (Wazi aaS) to serve as the z/OS back-end. Learn more about AAP here. Learn more about Wazi, here.
The two resources are provisioned together in the ITZ environment that you reserved earlier. This environment enables the ability to manage and automate z/OS tasks and subsystems with various preinstalled Ansible playbooks. It includes a z/OS back-end (Wazi as a Service) with all needed prerequisites.
The playbooks provided cover various use cases for automating z/OS management. Ansible\u2019s capabilities for automating various Z-specific tasks are not limited to the use cases that are preinstalled in the AAP instance. The preinstalled playbooks are tasks from the \u2018IBM z/OS core collection\u2019. Using this environment accelerates the ability to showcase the value of watsonx assistant for Z, and to get started with simple automations that can be expanded.
The ITZ environment gives you access to AAP, which is preconfigured to target the accompanying z/OS Wazi system, along with web-based access to AAP to experiment with different playbook templates. These templates are imported into watsonx Orchestrate as skills and connected to your assistant.
For more information on the AAP and Wazi z/OS environments, refer to this document.
The playbook templates that are preinstalled in AAP cover various use cases, which you can explore, including:
Each of the sections that follow build upon each other. Complete each to successfully enhance your assistant by starting with Explore Ansible Automation Platform.
"},{"location":"skills/importSkills/","title":"Import skills from Ansible Automation Platform","text":""},{"location":"skills/importSkills/#importing-skills-from-ansible-automation-platform","title":"Importing skills from Ansible Automation Platform","text":"Now that you understand Ansible Automation Platform (AAP) and the preinstalled automations available, you can import them as skills into your watsonx Orchestrate instance, which is used for assistant guided actions.
"},{"location":"skills/importSkills/#import-skills-into-your-assistant","title":"Import skills into your assistant","text":"The next steps assume that you have an active browser window to the watsonx Orchestrate ITZ cloud account. If you do not, refer to the initial steps in Creating an assistant and configuring conversational search.
Return to your watsonx Orchestrate instance and expand the main menu and click Skill studio.
Expand Create and click Import API.
Click the z/OS Skills accelerator (Trial) tile.
Enter the following values in the z/OS Skills accelerator form and then click Connect.
Use the URL, User Name, and Password values recorded in the Explore Ansible Automation Platform section earlier.
a: Connection Type: ansible
b: Application Name: <enter a meaningful name for the skills that you will import> - record this name, you will need in the next section
c: Connection URL: <enter the URL for your AAP UI>
d: User Name: <enter the AAP User Name (for UI access)>
e: Password: <enter the AAP User Password>
f: Search Pattern: *
Expand the Ansible Job Template Proj... folder.
Explore the other available skills
Take time to explore the available skills. There are many utility skills provided out of the box with the \u201cZ Skills Accelerator\u201d which are needed for actions such as retrieving the output of an Ansible skill. Consider importing these utility skills to enable more complete automation execution flows.
Click aap4zos.
Select the skills that you want to import into your application and then click Save as draft.
For this lab, select the Z/os ping and Z/os gather facts skills.
Click the ellipses () for the first skill and select Enhance this skill.
Review the skill enhancement options and then click Publish.
On the Enhance this skill page, you can specify enhancements to the default skill. Refer to this documentation for more information on enhancing skills.
Repeat steps 8 and 9 for each skill you imported.
The selected skills are now ready for use and available to your assistant. In the next section, learn how to connect them to your assistant.
"},{"location":"skills/importingzOSskills/","title":"Import pre-packaged z/OS skills","text":""},{"location":"skills/importingzOSskills/#importing-pre-packaged-zos-skills","title":"Importing pre-packaged z/OS skills","text":"Provided with Version 2 of watsonx Assistant for Z is a set of pre-packaged skills. These skills are used to automate various tasks on z/OS, such as running different console commands and retrieving logs from batch jobs.
The list of pre-packaged skills available include:
Authorized program list
z/OS IPL Information
Display zOS parmlib datasets
UNIX System Services options
Display zOS subsystems
List spool files
Retrieve dataset content
Retrieve spool file content
Retrieve z/OS Management Facility (OSMF) job status
IBM watsonx Orchestrate requires that any OSMF environment you connect to for skill execution has certificate authority (CA) signed certificates.
As an example, the following are console commands that are used in some of the pre-packaged skills:
operator command -> d prog,lnklistoperator command -> d iplinfooperator command -> d parmlibYou can import the pre-packaged skills to your sandbox environment by downloading the compressed file here and following these instructions.
Extract the embedded JSON file and modify the file for your environment by following these instructions.
"},{"location":"usecases/cert/cert/","title":"SSL certificate renewal","text":""},{"location":"usecases/cert/cert/#use-case-ssl-certificate-renewal-on-zos","title":"Use case: SSL Certificate renewal on z/OS","text":"Now, shift roles to that of a mainframe Security Administrator (SA). The client want to understand how watsonx Assistant for Z can help them to verify that their critical security certificates are up to date and reduce the risk of expired certificates disrupting their organization\u2019s services.
Secure Sockets Layer (SSL) certificates, often referred to as digital certificates, are used to establish an encrypted connection between communicating parties over a network. Certificate management is crucial for maintaining the security of a company\u2019s z/OS environment. The SA has not performed the tasks to manage and renew a certificate in some time. The SA recalls that there are many steps that are required on z/OS and various RACF commands that need to be run to renew a certificate. Rather than going to their senior SA for assistance, demonstrate how using watsonx Assistant for Z can help the SA automate the certificate renewal process.
In this scenario, use the Ansible automation templates that are provided with AAP and the WAZI z/OS environment to create assistant actions. The actions guide the client through the process of identifying their SSL certificate\u2019s expiration dates, and automating the certificate renewal process for them. The assistant saves them time and improve their productivity.
"},{"location":"usecases/cert/cert/#create-an-initial-certificate-authority-ca-certificate-to-sign-future-site-certificates","title":"Create an initial certificate authority (CA) certificate to sign future SITE certificates","text":"For this use case, a certificate authority (CA) certificate is needed to sign new SITE certificates.
Open and log in to the Ansible Automation Platform (AAP) web console.
Don't remember how?
Refer to the first 5 steps in Explore Ansible Automation Platform.
Click Templates under the Resources section.
Click the launch icon () for the z/OS Certs - Create Cert template.
On the Survey screen, modify the Certificate Label and Type fields with the values that follow and then click Next.
a: Certificate Label
TESTCA\nb: Type
CERTAUTH\nLeave the default values for all other fields.
Click Launch.
Review the output of the job.
In the output of the playbook, notice that a new keyring is created, a certificate is created, and the certificate is connected to the key ring.
Locate the line TASK [GENERATE new certificate], click the changed: [zos host].
Click JSON.
Review the RACDCERT command that was run to generate the certificate and then click x to close the window.
Now, create an expiring certificate that uses the CA certificate that you just created.
Return to the Templates tab and click the launch icon () for the z/OS Certs - Create Cert template.
On the Survey screen, modify the fields that follow with the values specified and then click Next.
a: Type
SITE\nb: Sign with
CERTAUTH\nc: Sign Label
TESTCA\nd: Common Name
company.com\ne: Expiration Date
Enter a date that occurs within the next 30 days. The date must be in the format YYYY-MM-DD.
Leave the default values for all other fields.
Unlike the first certificate you created which was self-signed, this certificate will be signed by the local certificate authority that uses the CA you created.
The following image does not highlight all the fields that need to be modified!
Click Launch.
Verify that the job was successful and inspect the output of the job.
Now that you have a certificate and it is expiring within 30 days, it is time to renew the certificate.
Return to the Templates tab and click the launch icon () for the z/OS Certs - Search and Renew template.
On the Survey screen, modify the fields that follow with the values specified and then click Next.
a: Certificate Label
TESTSITE\nb: Type
SITE\nc: Sign with
CERTAUTH\nd: Sign Label
TESTCA\ne: Expiration Date
Specify a new expiration date in the format YYYY-MM-DD.
The following image does not highlight all the fields that need to be modified!
Click Launch.
Verify that the job was Successful and review the output.
Note: Click the Reload Output button to view the full output after the job completes.
Review the tasks that were run within the automation to renew the certificate. Some of the steps completed include:
Run the RACF_CERTIFICATE_EXPIRATION z/OS Health Check
Submit JCL to pull a report on the z/OS Health Check
Search the output of the report for the given certificate label
Print the expiring certificate, if it is found. You see: \u2018TESTSITE expiring \u2013 True\u2019
If the certificate is expiring, start a series of RACDCERT commands to do the following:
Backup the expiring certificate
Rekey the certificate and give it a new temporary label
Generate a CSR for the new certificate
Sign the new certificate with the local CA
Delete the old certificate
Relabel the new certificate to use the same label as before
Refresh the digital certificate list
Create one more expiring certificate to use with the assistant and the new skills you will create.
Return to the Templates tab and click the launch icon () for the z/OS Certs - Create Cert template.
On the Survey screen, modify the fields that follow with the values specified and then click Next.
a: Certificate Label
DEMOCERT\nb: Type
SITE\nc: Sign with
CERTAUTH\nd: Sign Label
TESTCA\ne: Common Name
company.com\nf: Expiration Date
Enter a date that falls within the next 30 days in the format YYYY-MM-DD.
The following image does not highlight all the fields that need to be modified!
Click Launch.
Verify that the DEMOCERT was successfully created.
For this use case, configure the assistant to guide the user through the process of identifying their SSL certificate\u2019s expiration date and automate the certificate renewal process. To do so, import the needed AAP templates into watsonx Orchestrate as skills.
For this use case, the ansible templates you import are:
Open Skill studio in watsonx Orchestrate.
Click Create and then click Import API.
Click the z/OS Skills accelerator (Trial) tile.
Enter the following values in the z/OS Skills accelerator form and then click Connect.
Use the URL, User Name, and Password values recorded in the Explore Ansible Automation Platform section earlier.
a: Connection Type:
ansible\nb: Application Name:
certs\nc: Connection URL:
<Enter the URL for your AAP UI>
d: User Name:
<Enter the AAP User Name (for UI access)>
e: Password:
<Enter the AAP User Password>
f: Search Pattern:
*\nExpand the Ansible Job Template Proj... folder and then click aap4zos.
Select Z/os certs - list cert and Z/os certs - search and renew and then click Save as draft.
Scroll through the table of skills to find the required skills.
Click the ellipses () for the z/OS Certs - List Cert skill and select Enhance this skill.
Review the skill enhancement options and then click Publish.
Repeat steps 7 and 8 for the z/OS Certs - Search and Renew skill.
Challenge: You also need to add the Retrieve job output utility to your certs app just like you did when creating the Gather Facts skill flow. Repeat steps 2 - 8 to add the Retrieve job output utility skill to your certs app.
Open Skill catalog in watsonx Orchestrate.
Enter certs in the search bar.
Click the certs tile.
Click Add skill + for each of the 3 skills in the certs app.
Click Connect app.
Enter your AAP Username and AAP Password and then click Connect app.
Verify that the app is connected.
Open Skill catalog in watsonx Orchestrate.
Select the Draft version of your assistant and click Connections.
Enter certs in the search bar.
Click the ellipses () for the certs app and select Connect app*.
Click Connect app.
Enter your AAP Username and AAP Password and then click Connect app.
The goal of this scenario is to configure the assistant to automate the certificate renewal process for the client. The first step in that process is to help the SA identify the expiration date of their z/OS certificate. You have imported the z/OS Certs \u2013 List Cert skill from Ansible Automation Platform. Next, create a new skill flow that uses the z/OS Certs \u2013 List Cert skill that can later be used in a natural conversation through assistant actions.
First, create a skill flow to retrieve and display the expiration date of a z/OS certificate based on the certificate label the user provides.
Open Skill studio in watsonx Orchestrate.
Click Create and then click Skill flow.
Click the + icon.
Click the certs app.
Search on certs if you do not see the tile for your app.
Click Add Skill + in the z/OS Certs - List Cert tile.
Click the + icon below the z/OS Certs - List Cert skill and repeat steps 4 and 5 to add the Retrieve job output skill.
Click the Retrieve job output skill.
Click the id field.
Click z/OS certs - List Cert.
Click job.
Click the z/OS Certs - List Cert tile.
On both the Input and Output tabs for the z/OS Certs - List Cert skill, enable the Hide this form from the user options.
To enhance the user experience, hide the input and output forms from the user. This disables the List Cert skill form from being displayed. Rather than the user entering in their certificate details as input to the skill form, those details can be gathered into the skill through user prompts when creating an assistant action. This enables a more natural conversation flow when interacting with the assistant.
Repeat step 12 for the Output of the Retrieve job output skill.
The output of the List Cert skill includes a large amount of data. In the assistant, only the certificate expiration date is needed. In the next steps, transform the output to return only the certificate expiration date.
Click the + icon below the Retrieve job output skill.
Click the Custom forms.
Click Add skill + in the Input form.
Click the Input form skill.
Click Add input field +.
Click Paragraph text and then click Next.
Enter certificate expiration date in the Display label field and click Apply.
Display label:
certificate expiration date\nClick the certificate expiration date entry field.
In the Mapping data for \"certificate expiration data\" section, click Retrieve job output.
Click content.
Click Add transformation +.
A transformation is used to extract the certificate expiration date from all the job output data.
Click the Select drop-down and select Get substring by regular expression.
Cut and paste the regular express that follows to extract the certificate end date and then click Add.
Regular Expression:
(?<=End Date: ).[^\"]*\nNote
There are several ways to transform data to match the type of output you need. In the above example, regular expression is used to get the needed output (the certificate expiration date). This regular expression was tested against the output of the z/OS Certs \u2013 List Cert Ansible job to extract the value assigned to the \u2018End Date\u2019 field in the job\u2019s output. After completing this use case, you can experiment with other regular expressions to extract additional information from the job\u2019s output.
For more information on transforming data within watsonx Orchestrate, review the documentation found here.
Enter certificate expiration date in the form title and toggle the Hide this form from the user option.
Form title:
certificate expiration date\nNext, create an output for to return the transformed data from the input skill.
Click the + icon below the Input form.
Click Custom forms.
Click Add Skill + in the Output form tile.
Click the Output form skill.
Click in the Custom forms field and enter # (the pound key, also know as the number sign or hash key).
Typing the # opens a new dialog window.
Expand (a) Input form, select (b) certificate expiration date, and then click (c) OK.
Enable the Hide this form from the user option.
Why hide some of the forms?
You may be wondering why hide the input and output forms for the skills in the skill flow. This is done to execute the automation based on user prompts for the inputs of the skills. This is done through natural conversation with the assistant when the skill flow is configured as an assistant \u2018action\u2019 (you will do this soon). Although the final output is hidden, it is accessible as a variable in a custom-built action. The value can be displayed exactly at the point it is expected in the conversation.
Click the pencil icon ().
Enter Retrieve certificate expiration in the Name field and click Save.
Name:
Retrieve certificate expiration\nClick Actions and then click Save as draft.
Click Actions and then click Enhance.
Review the skill flow settings and click Publish.
You created a new skill flow that accomplishes part of the use case \u2013 retrieving and displaying the expiration date of a z/OS certificate based on the certificate label the user provides.
In the next section, you will create a simpler skill flow for the z/OS Certs \u2013 Search and Renew skill that you previously imported. After this additional skill flow is created, add both skill flows as skill-based actions to be called in a custom-built action that maps inputs to the skill flows through natural conversation.
"},{"location":"usecases/cert/cert/#create-a-skill-flow-for-certificate-renewal","title":"Create a skill flow for certificate renewal","text":"The final step before configuring the assistant with actions is to create a skill flow for renewing certificates. Recall the z/OS Certs \u2013 Search and Renew automation imported the from Ansible Automation Platform earlier. The skill flow that you create next is composed of that single skill. There is no need to return the output. After the automation is triggered, the user can verify the new expiration date by running the retrieve certificate expiration date flow.
In Skill studio, click Create and then click Skill flow.
Click the + icon.
Click the certs app.
Search on certs if you do not see the tile for your app.
Click Add Skill + in the z/OS Certs - Search and Renew tile.
As mentioned, there is no need to return the Ansible job output of this skill when it is run. The z/OS Certs - Search and Renew is used to set default values for some of the inputs. In this use case, assume that the SA will be renewing their SITE certificates that are signed with a previously generated certificate authority.
Click the z/OS Certs - Search and Renew skill.
Click Input.
Hover over the extra_vars.cert_type_survey input field and click the pencil icon ().
Click in the extra_vars.cert_type_survey input field and enter SITE.
extra_vars.cert_type_survey:
SITE\nDo not enter spaces before or after the word SITE.
Repeat 7 and 8 for the extra_vars.sign_with_survey field and enter the word CERTAUTH.
extra_vars.sign_with_survey:
CERTAUTH\nDo not enter spaces before or after the word CERTAUTH.
Enable the Hide this form from the user option for both the Input and Output forms.
The image that follows only shows the Output form, but enable the option for both forms.
Click (a) the pencil icon () for the skill flow, enter (b) Cert Renewal skill flow in the Name field, and click (c) Save.
Name:
Cert Renewal skill flow\nClick Actions and then click Save as draft.
Click Actions and then click Enhance.
Review the skill flow settings and click Publish.
Next, create 2 skill-based actions that use the skill flows. The skill-based actions enable the ability to call the skill flow as a subaction within a new custom-built action. For this use case, create two skill-based actions that use the previously created skill flows:
Retrieve certificate expiration \u2013 maps the user prompted certificate label as input and extracts the certificate expiration date from the Ansible job\u2019s output.
Cert Renewal skill flow \u2013 maps the user prompted certificate label and new expiration date as input and runs the Search and Renew Ansible job to extend the expiration date of the certificate.
After the 2 skill flows are added as skill-based actions, integrate the actions into a custom-built action that defines the entire conversation flow. The flow assists the SA with the certificate renewal process.
Open AI assistant builder in watsonx Orchestrate.
Click Actions.
Click New action+.
Click Skill-based action.
Click the Retrieve certificate expiration tile and then click Next.
Click Cancel on the New action dialog.
For this use case, the action is triggered from a custom-built action. To prevent the skill flow from being run as the skill-based action, do not enter any example phrases.
Click x to close the Retrieve certificate expiration skill.
Repeat steps 3 - 7 to create a skill-based action for the Cert Renewal skill flow.
This action is also triggered from a custom-built action. Do not enter any example phrases.
Verify that both skill-based actions are available.
Next, create a custom-built action that runs the new skill-based actions as subactions. Configure the custom-built action to enable a natural conversation with the assistant, gather relevant details from the user, and map those details to the action inputs.
Click New action +.
Click Custom-built-action.
Enter z/OS certificate expires soon and then click Save.
What does your customer say to start this interaction:
z/OS certificate expires soon\nThe conversational search capability that is provided by watsonx Assistant for Z can provide step-by-step guidance for determining certificate expiration and renewing certificates, and is grounded on Z domain-specific knowledge. In the first step to be taken when the user prompts the assistant with z/OS certificate expires soon, configure the assistant to use conversational search to provide a response on the process and the ability to automate the process.
Click the And then drop down and select Search for the answer.
The result is that anytime the user input matches the example phrase z/OS certificate expires soon, the first step that is taken is for the assistant to use conversational search and provide a response to their original question.
Like in the IPL Information scenario, add a custom search query so when conversational search is run in the first conversation step, the query used is hardcoded and not what the user input.
Click Edit settings.
Enter the following prompt to be used in the Custom search query field and then click Apply.
Custom search query:
My z/OS certificate is going to expire soon. How do I retrieve the expiration date for my certificate?\nClick Next step+.
Enter the following response in the Assistant says field.
Assistant says:
Would you like to run the skill to retrieve your certificate\u2019s expiration date?\nClick the Define customer response option list and select Confirmation.
The Confirmation option prompts the user to select Yes or No.
Click Next step +.
Click the Is taken option list and select with conditions.
This step handles the flow when the user selects Yes in the previous step, indicating that they want to run the skill to retrieve the certificate\u2019s expiration date. To run the Retrieve certificate expiration action created earlier, the assistant needs the certificate label. This label is mapped as input to the skill.
Enter the following text in the Assistant says field.
Assistant says:
What is your certificate label?\nClick the Define customer response drop-down list and select Free text.
Click Next step+.
Click the Is taken option list and select with conditions.
After the user enters the certificate label as free text, the next step is to run the Retrieve certificate expiration skill-based action created earlier. To do so, map the user input to the skill flow and retrieve the expiration date for that certificate.
Click the And then option list and click Go to a subaction.
Notice that the default condition validates the free text is defined from the previous step.
Click the (a) Go to option list, select the (b) Retrieve certificate expiration skill-based action, and then click (c) Apply.
Click Edit passed values.
To run the Retrieve certificate expiration subaction that uses the users certificate label, the passed value needs to be modified.
Click Set new value + and then select extra_vars.cert_label_survey.
In the To field, select Action step variables, and then select What is your certificate label?.
Click Apply.
Click Next step +.
Click the Is taken option list and select with conditions.
In the previous step, you configured the assistant to run the Retrieve certificate expiration subaction you created, passing the certificate label the user inputted to the skills inputs. Recall when the Retrieve certificate expiration skill flow was created, the output form at the end of the skill flow was hidden. That form contained the expiration date. As a result, nothing is returned when running the subaction in the previous step. Now, configure the custom-action to provide that output as a response.
Enter the following text in the Assistant says field.
Assistant says:
Below is your certificate\u2019s expiration date:\nWhile still in the Assistant says field, press return and then type $.
The $ is a special key that lists available functions. The following image is edited to show that you must type the $, but it is not displayed on your screen.
Click Retrieve certificate expiration (step 4) and then click Retrieve certificate expiration result variable.
Review the Assistant says field and then click Save ().
Before completing the use case, test the z/OS certificate expires soon custom-built skill that uses the DEMOCERT certificate created earlier.
Click Preview.
Enter the following prompt in the preview.
Prompt:
My z/OS certificate is going to expire soon. How do I retrieve the expiration date for my certificate?\nReview the response and click Yes.
The assistant responds by calling Conversational search and returns a response by using the Z RAG, displaying the RACDCERT command that can be used. The assistant then prompts Would you like to run the skill to retrieve?.
Review the response and enter DEMOCRT.
Prompt:
DEMOCRT\nClick Apply.
Review the response.
If you see the following response (the date may differ), the custom-built skill ran successfully. The output of the skill flow was not the entire output of the z/OS Certs \u2013 List Cert Ansible job, but rather the certificate expiration date that was extracted from the full job output by using the Regular Expression transformation.
Now that the custom-built action is working, add steps to include the certificate renewal process. After retrieving and displaying the user\u2019s certificate expiration date, ask the user if they want to renew the certificate, and if so, prompt for the new date and renew the certificate.
Click Next step +.
Click the Is taken option list and select with conditions.
Enter the following text in the Assistant says field.
Assistant says:
Would you like to renew your certificate?\nClick the Define customer response option list and select Confirmation.
Click Next step +.
Click the Is taken option list and select with conditions.
This step handles the flow in which the user selects Yes in the previous step indicating they want to renew their expiring certificate. Before initiating the Cert Renewal skill flow action to automate this, the assistant first needs the new expiration date for the certificate.
Enter the following text in the Assistant says field.
Assistant says:
What date would you like to set the renewed certificate\u2019s expiration date to? Please enter in the form of YYYY-MM-DD.\nClick the Define customer response option list and select Free text.
Click New step +.
Click the Is taken option list and select with conditions.
With the new expiration date entered by the user, the next step is to run the Cert Renewal skill flow action as a subaction. Next, trigger the renewal skill flow and pass the user provided details as input to the action to renew the certificate and extend the certificates expiration date.
Enter the following text in the Assistant says field.
This assistant first responds with the message that follows before triggering the certificate renewal skill-flow. When performing a demo of this use case, mention the z/OS Certs \u2013 Search and Renew Ansible playbook typically takes a minute or so to complete.
Assistant says:
Renewing your certificate\u2026this could take up to a minute. Please wait one minute before selecting an option below.\nClick the And then option list and select Go to a subaction.
Click the Go to option list and select the Cert Renewal skill flow.
Click Apply.
Click Edit passed values.
Edit the passed values to use them in the Cert Renewal skill flow subaction.
Click Set new value + and then select extra_vars.cert_label_survey.
In the To field, select Action step variables.
Click What is your certificate label?
Repeat steps 16 - 18 adding the extra_vars.new_expiry-date_survey input variable and What date would you like to set the... in the To field.
Click Set new value + and then select extra_vars.sign_label_survey.
In the To option list, select Enter text.
Enter TESTCA in the Enter text field and click Apply for the To option list.
Enter text:
TESTCA\nFor this passed value, hardcode TESTCA in the skill flow\u2019s input for the sign_label variable. This is the CA certificate created earlier for demo purposes in the AAP web console.
Review the Edit passed values and then click Apply.
Review all 3 variables are set correctly.
Click Next step +
Click the Is taken option list and select with conditions.
To complete the flow, ask the user if they want to verify the new expiration date.
Enter the text that follows in the Assistant says field.
Assistant says:
Would you like to verify the new expiration date for your certificate?\nClick the Define customer response option list and select Confirmation.
Click Next step +.
Click the Is taken option list and select with conditions.
On the condition that the user selected Yes in the previous step, configure a step to run the Retrieve certificate expiration skill-flow again to retrieve and display the new expiration date of the renewed certificate.
Click the And then option list and select Go to a subaction.
Click the (a) Go to option list, select (b) Retrieve certificate expiration, and then click (c) Apply.
Click Edit passed values.
Click Set new value + and then select extra_vars.cert_label_survey.
In the To option list, click Action step variables.
Click What is your certificate label?.
Review the Edit variable values and click Apply.
Click Next step +.
Click the Is taken option list and select with conditions.
The final step is to display new expiration date of the certificate. Nothing is returned in the previous step when running the Retrieve certificate expiration skill flow - this was because the output form was hidden when the skill was created. In this step, provide the output as an assistant response to the user, with only the expiration date extracted from the full job output.
Enter the following text in the Assistant says field.
Assistant says:
Below is the new expiration date of your renewed certificate:\nWhile still in the Assistant says field, press return and then type $.
The $ is a special key that lists available functions. The following image is edited to show that you must type the $, but it is not displayed on your screen.
Click Retrieve certificate expiration (step 10).
Be sure to select the output from step 10 and not step 4.
Click Retrieve certificate expiration result variable.
Click the And then option list and select End the action.
Review the (a) final step, click (b) Save (), and then click (c) x.
The custom-built action is now complete and can be demonstrated to the SA for this use case. In demonstrating the ability to infuse Ansible automations into a natural conversation, the SA is able to see the value that watsonx Assistant for Z can provide in helping them improve productivity and remove the need to go to their senior colleagues for assistance.
Open Preview in the Ai assistant builder.
Enter the following text in the assistant.
Prompt:
How do I check the expiration date for my certificate that\u2019s expiring soon?\nUse the Change layout option to open a full page view of the assistant.
Review the response and click Yes.
The assistant responds with conversational search, providing a content-grounded answer based on IBM Z documentation. The response includes a RACF command that the SA might use to determine their certificate\u2019s expiration date.
Following the response, the assistant prompts the user if they want to run the skill to retrieve a certificate\u2019s expiration date.
Enter DEMOCERT after the assistant responds with What is your certificate label?
Prompt:
DEMOCERT\nWait 10 seconds and then click Apply.
Review the response and then click Yes.
By providing the automation within the assistant conversation, it makes it very quick for the SA to identify the certificate\u2019s expiration date. In addition to providing this valuable information, the assistant is configured with another automation to renew the certificate if they choose to do so.
The expiration date you see may differ from the image that follows.
Enter a date in the future in the format YYYY-MM-DD.
Review the response, wait 30 seconds to a minute, and then click Yes.
It is crucial that you wait 30 seconds to a minute before selecting Yes.
This is because in the background, your z/OS Certs \u2013 Search and Renew automation is running within AAP (which you can verify within the AAP Web console). This is mapping the user-inputted expiration date as well as the original certificate label provided by the end-user to the inputs of this AAP automation.\"
Wait 10 seconds and then click Apply.
Review the response.
The response should match the date that is entered in step 7.
In the demo, the SA receives immediate guidance on identifying the certificate expiration date via RACF commands. The SA runs automation that is proposed by the assistant to retrieve the certificate information. Also, because the assistant is configured with step-by-step conversation flows, it is possible to add other prompts within the conversation. For example, proposing the automation of renewing the certificate on their behalf. By doing so, the SA is able to reduce the time it takes to complete this routine task.
Recall how many steps were involved in the Ansible template for z/OS Certs \u2013 Search and Renew. By automating these tasks with Ansible, the System Administrator streamlines the entire process and ensures that their critical certificates are up to date and reduce the risk of expired certificates disrupting their business services.
"},{"location":"usecases/cert/certPH/","title":"COMING SOON!","text":""},{"location":"usecases/cert/certPH/#coming-soon","title":"COMING SOON!","text":""},{"location":"usecases/ipl/ipl/","title":"Retrieve IPL information","text":""},{"location":"usecases/ipl/ipl/#use-case-retrieve-ipl-information","title":"Use case: Retrieve IPL information","text":"Next, explore a use case to improve productivity for early-tenure system programmers (SysProg) who are preparing for an upcoming initial program load (IPL) for a logical partition (LPAR).
To prepare for the IPL, the SysProgs need to familiarize themselves with the process. Rather than spending time reading through the wide array of documentation available online, they would like to use watsonx Assistant for Z. The content-grounded capabilities that are provided by watsonx Assistant for Z return accurate responses to their questions quickly and uses automations to perform actions.
As part of the pilot, they already explored prompting the assistant with questions. In one example prompt, they asked the assistant is \u201cWhat information is needed to perform an IPL on a z/OS LPAR?\u201d In reading the response, the SysProg learns they need information about their system in preparation for the IPL. For example, the IPL Volume and the IPL LOAD PARM.
For this use case, show how a simple automation for retrieving this type of information can be infused in a natural conversation with watsonx Assistant for Z. You use pre-packaged skills to automate various tasks on z/OS. The pre-packaged skills are provided as an OpenAPI JSON file. Learn more about OpenAPI here. The file includes skill definitions that can be uploaded to the Skill Studio within watsonx Orchestrate to import the pre-packaged skills. First, the file must first be customized for your z/OS server.
The list of pre-packaged skills available include:
A great value of watsonx Orchestrate is the ability to build skills that anyone can use. You can build your own custom skills by importing an OpenAPI file into watsonx Orchestrate as a JSON or YAML file. For more information on building skills by importing OpenAPI files, refer to the documentation here.
Watsonx Orchestrate also makes it possible to build, edit, and generate OpenAPI specifications by using the OpenAPI builder. With the OpenAPI Builder, you can use the AI function to simplify the process of generating these specifications. For more information on using the OpenAPI Builder, refer to the documentation here.
For this use case, you are importing the skill for retrieving a z/OS server\u2019s IPL information. The next steps walk you through the process of downloading that OpenAPI JSON file and customizing it for your environment.
"},{"location":"usecases/ipl/ipl/#download-and-customize-the-watsonx-assistant-for-z-openap-json-file","title":"Download and customize the watsonx Assistant for Z OpenAP JSON file","text":"Download the watsonx Assistant for Z OpenAP JSON file.
wxa4z-skillpak-prepackaged-skills.json.zip
Extract the file.
In a text editor, open the wxa4z-skillpak-prepackaged-skills.json, modify the server's url field as described, and save the file.
File name:
wxa4z-skillpak-prepackaged-skills.json\nSubstitute your Wazi as a Service (WaaS) instance URL for the string <your z/OSMV URL>. Your WaaS URL is based on your ITZ AAP URL that can be obtained from your watsonx Assistant for Z Pilot - AAP & z/OS ITZ reservation.
The AAP URL is similar to:
https://itzvsi-aap-ppxbcno.techzone.ibm.com
Change the aap string to zos and append :10443 to the URL value. Record this value for later use! Your new URL is similar to:
https://itzvsi-zis-ppxbcno.techzone.ibm.com:10443
Before:
After:
In watsonx Orchestrate, each app is associated with a single URL.
If you have not imported previous skills into an app called z/OS operations, the default values in the info section are fine. If you already have a app named \"z/OS operations\", modify the info section to meet your needs.
For more information on modifying the OpenAPI JSON file, see the instructions here.
For your skills to run successfully on your WaaS instance, you need to ensure that you can authenticate to it from watsonx Orchestrate. To achieve successful authentication, setup a new RACF Passphrase for the IBMUSER ID that is a pre-defined user ID on the WaaS server. The following steps take you through the steps of setting a new passphrase for your user and verifying access.
Open and log in to the Ansible Automation Platform (AAP) web console.
Don't remember how?
Refer to the first 5 steps in Explore Ansible Automation Platform.
Click Templates under the Resources section.
Click the launch icon () for the z/OS TSO Command(s) template.
Replace the default command with the text that follows and substituting a password of your choosing for the string YOUR PASSWORD PHRASE and then click Next.
ALTUSER IBMUSER PHRASE('YOUR PASSWORD PHRASE') NOEXPIRE RESUME\nAvoid typographical errors later... keep the password simple.
If you type the command yourself, be sure to include the single quotes before and after the password. Record the password as it will be needed later. We will refer to this as your WaaS password.\"
Click Launch.
Verify that the job is Successful by locating the message \"failed\": false in the job output.
Verify that you can log in to z/OSMF in a new browser tab.
Use the WaaZ URL created earlier and append /zosmf to the string. The URL is similar to: https://itzvsi-zos-pwgabob.techzone.ibm.com:10443/zosmf.
Accept any connection not private messages to open the page.
Enter (a) IBMUSER for the z/OS USER ID, (b) the password you specified in step 4 for the z/OS PASSWORD, and then (c) click LOG IN.
Close the new browser tab after verifying a screen similar to the image that follows is displayed.
Open Skills studio in watsonx Orchestrate.
Click Create and then click Import API.
Click From a file.
Click Drag and drop files here or click to upload in the Import a skill file window.
Locate and select the JSON file that you modified earlier and then click Upload.
Verify that you receive the message The Open file or skill package is good to go! and then click Next.
Not good to go?
If the file does not load properly you will need to verify not formatting or errors were made in your json file. Return to the previous section to verify the file contents and then reload the JSON file.
Select the z/OS IPL Information skill and then click Add.
Note: Only the z/OS IPL Information skill is required for this use case, but you can add as many skills as you like for testing purposes.
Click the ellipses icon (~) for the z/OS IPL Information skill and then click Enhance this skill.
Review the skill enhancements options and then click Publish.
If you added other skills in step 7, repeat the previous 2 steps for each skill added.
In Skill studio, click the Apps tab.
In the search field, enter the name of the application in the search field. Unless you modified the info section of the JSON file, the default name is z/OS operations.
Click the ellipses icon (~) for the z/OS Operations and then click Edit.
Click the Configuration tab.
Click Test connection.
Note: the Server URL field must match the URL you created for your WaaS server. It is similar to: https://itzvsi-zos-pwgabob.techzone.ibm.com:10443.
Enter (a) IBMUSER in the username field, (b) your WaaS password created earlier in the password field, and then (c) click Connect app.
Verify that the connection is successful and then click Save.
Repeat step 2 above to verify that the Configuration status is Configured.
Open Chat in watsonx Orchestrate.
Click Add skills from the catalog.
In the search apps field, enter the name of the application. Unless you modified the info section of the JSON file, the default name is z/OS operations.
Locate and click the tile for your app (z/OS operations).
Click Add skill + for the z/OS IPL Information skill.
Repeat step 5 for any additional skills you added to the app.
Click Connect app.
Enter (a) IBMUSER in the username field, (b) your WaaS password created earlier in the password field, and then (c) click Connect app.
Verify that the skill is connected.
Open Chat in watsonx Orchestrate.
Click the z/OS IPL Information tile.
The name of the tile may be different.
If you added multiple skills to your app, the tile name may be z/OS operations and the number of skills included will be shown.
Using the defaults in the form, click Apply.
Review the returned information.
The provided output shows information the early-tenure SysProg needs to prepare for an IPL on their z/OS LPAR. For example, the date and time the system was last IPL\u2019ed, the z/OS release level, the IPL volume, the IPL LOAD PARM used during the IPL, and other details.
If you loaded other pre-packaged skills, test them now.
Before configuring the z/OS IPL Information skill as an assistant action, the app containing the skill must first be connected to the assistant.
Open Skill sets in watsonx orchestrate.
Click the Skill sets drop-down list and select the Draft of your assistant.
Click Connections.
Enter your skill app name (z/OS operations) in the search bar.
Click the ellipses icon (~) for the z/OS operations app and then click Connect app.
In the dialog, click Connect app.
Enter (a) IBMUSER in the username field, (b) your WaaS password in the password field, and then (c) click Connect app.
Next, create a skill-based action that uses the z/OS IPL Information. Recall, with the z/OS Gather Facts skill flow that was created earlier, adding the skill as a skill-based action allows the skill to run based on user prompts to the assistant.
Skill-based actions also serve another purpose. After creating the skill-based action, you can then call that action from a custom-built action. This is accomplished through subactions. For this use case, create an action that triggers the z/OS IPL Information skill on z/OS to display the LPARs IPL information. That action is integrated into another custom-built action (as a subaction) to provide a customized user experience.
Open AI assistant builder in watsonx Orchestrate.
Select Actions.
Click New action +.
Click Skill-based action.
Click z/OS IPL Information and then click Next.
Enter a prompt like Display IPL information that starts the skill and then click Save.
Prompt:
Display IPL information\nClick the Save icon ().
Click Preview.
Wait for the Your changes are being added. message to disappear before proceeding.
Enter the prompt (Display IPL information) to test the skill.
Using the defaults in the form, click Apply.
Verify the results.
Click the delete icon () to remove the example phrase (Display IPL information) from the skill.
Next, you will add this skill-based action as a subaction to a custom-build action. To have the custom-built action started rather than the skill-based action, the existing example phrases need to be removed.
Verify (a) all example phrases are deleted, (b) click the Save icon (), and then (c) click x to close the action.
Custom-built actions allow you to define each step of a conversation with your assistant. You can define steps with or without conditions to control the user responses. You can include your skill-based actions as sub-actions. You can pass generated values between the subactions.
Recall the use case of an early-tenure SysProg who is preparing for an upcoming IPL on one of their LPARs. After going through documentation, the SysProg found that there is information that is needed about their LPAR before they can begin the IPL process. To gather that information, the SysProg might ask the assistant \u201cHow do you retrieve the information needed to IPL a z/OS LPAR? Provide a detailed response\u201d. A response the assistant might return is shown in the following image.
A custom-built action can help the SysProg to take the next steps that are required by adding next-step action suggestions and start skills to gather the needed information.
Click New action +.
Click Custom-built action.
Enter an example phrase (Retrieve IPL information) to prompt the assistant to start the custom-built action and click Save.
Prompt:
Retrieve IPL information\nReview the form to create a custom-built action.
A custom-built action can consist of multiple steps with each step that is taken with or without conditions. Each step specifies the assistant's response and the next step to start.
For client demonstrations and pilots...
For client demonstrations and pilots, it is possible to add a custom search query such that when conversational search is executed in the 1st step, the query being used is hard-coded and isn\u2019t necessarily what the end-user inputted. This can be done by clicking on the Edit settings option under Search for the answer and specifying a custom search query that specifies the exact query to be used.
Click the And then drop-down list and select Search for the answer.
Click Edit settings.
Enter a Custom search query and click Apply.
Custom search query:
How do you retrieve the information needed to IPL a z/OS LPAR? Provide a detailed response\nClick Next step +.
The new custom-built action only responds with a description of how to retrieve the IPL information. Now, infuse automation into the conversation and ask the user if they want to perform the action.
In the Assistant says field, enter a response asking if the user wants to display the IPL information.
Assistant says:
Would you like to display your LPARs IPL information?\nClick the Define customer response drop-down and select Confirmation.
Now, after providing a conversational search-based response to the original question, the assistant asks the user if they want to display the IPL information and prompts the user to select Yes or No.
Click Next step +.
Click the Is taken drop-down and select with conditions.
Review the Conditions.
Notice that the default condition is based on Step 2 and the user clicking Yes when prompted.
Enter Retrieving your system's IPL information... in the Assistant says field.
Assistant says:
Retrieving your system's IPL information...\nClick the And then drop-down and select Go to a subaction.
Click (a) the Go to drop-down, (b) select your skill-based action (z/OS IPL Information), and then (c) click Apply.
Click Save () and then click x.
You can now practice demonstrating the flow of this use case. Recall the steps that were taken and the scenario of the early-tenure SysProg being tasked with preparing for an upcoming IPL.
Click Preview.
Enter How do you retrieve the information needed to IPL a z/OS LPAR? in the assistant prompt.
Prompt:
How do you retrieve the information needed to IPL a z/OS LPAR?\nUse the Change layout option to open a full page view of the assistant.
Review the response.
By using the conversational search capability of watsonx Assistant for Z, grounded on Z-domain knowledge in the Z RAG, the user is able to quickly find an answer to their question. The assistant returns a response that shows the exact operator command they might use, and the types of details it provides which is relevant for preparing for an upcoming IPL. For example, the system\u2019s release level, the LOAD LIB information used for the IPL, the IODF device, the IPL device, and other system information.
You are also able to improve their productivity by infusing automations into the natural conversation that will provide them exactly the information they need to accomplish their task.
Click Yes.
Using the defaults in the form, click Apply.
Review the response to the custom-built action.
The output provides relevant pieces of information the early-tenure SysProg needs to prepare for an IPL on their z/OS LPAR. For example, when the system was last IPLed, the z/OS release they have running (2.5), the IPL volume (D25VS1), the IPL LOAD PARM (LOADK2) used during the last IPL, and other relevant details.
The ability to infuse skills and automations into the conversation allows the user to issue the operator command on their system directly within the assistant itself. The assistant provides a single interface for retrieving details that are required for the IPL process to go smoothly and increases the user's efficiency.
"},{"location":"usecases/ipl/iplPH/","title":"COMING SOON!","text":""},{"location":"usecases/ipl/iplPH/#coming-soon","title":"COMING SOON!","text":""},{"location":"usecases/racf/racf/","title":"Challenge: RACF administration support","text":""},{"location":"usecases/racf/racf/#use-case-racf-administration-support","title":"Use case: RACF administration support","text":"This is a challenge use case.
In this use case, step-by-step directions are not provided. Use the knowledge gained from previous sections of the lab guide to complete updates to the assistant to meet the use case requirements. Several help tips are provided and a sample demonstrate flow is included.
This use case explores the ability of watsonx Assistant for Z to provide self-service support for activities related to Resource Access Control Facility RACF (RACF) Administration support. The client mentioned that their RACF Administrators are often inundated with requests to help reset user's Time Sharing Option (TSO) passwords. Also, requests to grant users certain authorizations to RACF profiles required for the users to complete their jobs are numerous.
Creating a custom-built action for the assistant that provides self-service options to users requesting RACF assistance. Depending on the assistance being requested, the assistant will trigger automations that complete tasks on their behalf without intervention from the RACF Administrator.
The actions and configuration that follow are meant purely for demonstration purposes.
The actions and configuration that follow are meant purely for demonstration purposes to show the art of the possible with watsonx Assistant for Z. There are security considerations to keep in mind when configuring assistants for this purpose, including user authentication and the ability to authorize users to execute certain automations. However, by following the steps in this section, you will show the level of customization that is possible with watsonx Assistant for Z and different an assistant can improve productivity.
Create an app with the required TSO skills.
Use Skills studio to create the app.
App name:
TSO Command\nSkills to include: z/OS TSO COmmand(s) Retrieve job output (utility skill)
Create a connection for the app.
Use Skills catalog to create the app.
Create a skill flow to get the output of the TSO Command.
Use Skills studio to create the skill flow.
The skill flow should run the TSO Command skill and then the Retrieve job output utility skill. The output from the TSO Command should be mapped to the input of the Retrieve job output utility skill. Hide both the input and output forms for the TSO Command skill.
Skill flow name:
TSO COMMAND\nAdd the skills to the draft version of the assistant.
Use Skill sets to add the skills to the assistant.
Create a skill-based action that uses the skill flow.
Create an action that triggers the skill flow to execute TSO commands on z/OS and then display the output of those commands.
Use AI Assistant builder to create the action.
Do not add example phrases to the skill-based action.
Create a custom-built action for RACF administration support.
Use AI Assistant builder to create the action.
Phrase to start the interaction:
RACF assistance\nThe steps for the custom-built action follow:
Step 1. Without conditions, prompt the user for their RACF User ID as free text.
Assistant says:
What is your RACF User ID?\nThe step should look like the following image:
Use the following guidance when entering prompts and expressions in the following custom-built action steps.
Do NOT use the copy and paste icon if the string contains a $. Type each string manually.
When $ appears in the string to enter, type the $ character and then select the variable specified in the <>. For example: User passphrase changed to $<7. Please enter your new RACF passphrase>
Use the single quote character ' for all single quotes shown.
Step 2. Without conditions, use provided user ID and display a message that the assistant is checking the current privileges.
Assistant says:
Checking user privileges for $<1. What is your RACF User ID>
Include in the Assistant says the provided user ID by including the function 1. What is your RACF User ID.
Add an And then option to run the TSO Command as a subaction.
Edit the passed values for the subaction and add a new passed value for 1. extra_vars.zos_tso_command. The To of the variable will be an Expression and include the string:
'LIST USER ' + $<1. What is your RACF User ID>
After the +, enter a $ and select Action step variables and then select 1. What is your RACF User ID.
The step should look like the following image:
Step 3. Without conditions, prompt the user if they want RACF assistance and get a Yes or No confirmation.
Assistant says:
Do you need RACF assistance?\nThe step should look like the following image:
Step 4. With conditions, prompt the user what type of assistance they need.
Assistant says:
What type of assistance?\nCreate a Options type Customer response with two options:
Changing my RACF password\nPrivileges issue\nChange the Customer response settings to Always ask for this information, regardless of previous messages.
The step should look like the following image:
Step 5. With conditions, change the condition Step 4. What type of assistance? and the value of Privilege issue.
Assistant says:
Notifying the RACF Administrator.\nOther options exist.
There are alternative actions that can be taken if the user selects \u2018Privileges issue\u2019. For example, the assistant can trigger an automated email to the RACF administrator. At the time of writing this documentation, Orchestrate does not allow Outlook integrations to IBM\u2019s Outlook organization, so this action cannot be demonstrated. But for the purpose of the flow, simply have the assistant respond with \u2018Notifying the RACF Administrator\u2019 for demonstration purposes.
The step should look like the following image:
Step 6. With conditions, change the condition Step 4. What type of assistance? and the value of Changing my RACF password, and add a Yes or No confirmation.
Assistant says:
Would you like to change your user ID\u2019s RACF passphrase?\nThe step should look like the following image:
Step 7. With conditions, prompt the user to enter their new password as free text.
Assistant says:
Please enter your new RACF passphrase.\nThe step should look like the following image:
Step 8. With conditions, change the condition to Step 6. Would you like to change your user IDS passphrase equals Yes, inform the user the password is bing changed, and create a TSO Command subaction to change the passphrase.
Assistant says:
Issuing RACF command ...\nThe formatting of the values that follow is important.
When creating the To expression for the passed values, be very careful with typing the expression. Do NOT cut & paste this value. Type each charter. All quotes are single-quotes. The $<> denotes typing $ and then selecting the appropriate action step variable.
Edit the passed values for the TSO Command subaction to include the 1. extra_vars.zos_tso_command variable with a To expression with the value of:
'ALTUSER ' + $<1. What is your RACF User ID?> + ' PHRASE(''$<7. Please enter your new RACF passphrase>'') NOEXPIRE RESUME'
The expression should look like the following image:
The step should look like the following image:
Step 9.: With conditions, change the condition to Step 6. Would you like to change your user IDS passphrase equals Yes, and inform the user the passphrase has been changed. Change the And then option to End the action.
Assistant says:
User passphrase changed to $<7. Please enter your new RACF passphrase.>
When entering the above string, after typing $ select the 7. Please enter your new RACF passphrase.
The step should look like the following image:
Be sure to save your custom-built action.
Demonstrate the custom-built action.
Using the AI Assistant builder preview, run the custom-built action. Use the APP web console to verify the passphrase ws changed.
The following video shows how the demonstration should work. The video does not have audio.
This use case demonstrates the value watsonx Assistant for Z can provide to offload common, manual tasks from subject matter experts like RACF Administrators. The use case shows the level of customization offered with infusing automations into natural conversations. Watsonx Assistant for Z improves employee productivity and reduces effort needed by individuals to completing manual tasks.
"},{"location":"usecases/racf/racfPH/","title":"COMING SOON!","text":""},{"location":"usecases/racf/racfPH/#coming-soon","title":"COMING SOON!","text":""}]} \ No newline at end of file