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.
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.
`wrapper-creds.yaml password as the admin password.
+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.
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.
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 how to:
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 two days 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 the base large language model (LLM) settings.
If available, set the LLM model to granite-13b-chat-v2.
Notice their are several LLM models available. The current recommendation is for pilots, to use the granite-13b-chat-v2 model as it provides the best results in recent testing. However, this model has been deprecated as of 2024-11-04 and will may not be available after 2025-01-19. Note: screen captures that follow show the granite-3-8b-instruct LLM as being selected.
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? Provide a detailed explanation?\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.
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 and paste the following text in the file.
File name:
os-secret.yaml\nSubstitute a secure password of your choosing for the string <OPENSEARCH_PASSWORD>.
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 and paste the following text in the file.
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.
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 and paste the following text in the file.
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. 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.
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.
echo https://$(oc -n wxa4z-byos get route wxa4z-client-ingestion -o jsonpath=\"{.spec.host}\")\nYou 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.
Be careful with the sample phrases that you specify.
During the development of the lab guide, it was discovered that some sample phrases with a / character can cause issues with the actions. Avoid using z/OS in the your sample phrases. This issue has been reported to the offering team.
Sample prompts:
Get zOS facts\nGather zOS 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 zOS 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 zOS 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).
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.
Be careful with the sample phrases that you specify.
During the development of the lab guide, it was discovered that some sample phrases with a / character can cause issues with the actions. Avoid using z/OS in the your sample phrases. This issue has been reported to the offering team.
Example prompts:
Show me zOS facts\nGather and display zOS 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 zOS 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 zOS 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.
"}]} \ 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.
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 how to:
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 two days 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 the base large language model (LLM) settings.
If available, set the LLM model to granite-13b-chat-v2.
Notice their are several LLM models available. The current recommendation is for pilots, to use the granite-13b-chat-v2 model as it provides the best results in recent testing. However, this model has been deprecated as of 2024-11-04 and will may not be available after 2025-01-19. Note: screen captures that follow show the granite-3-8b-instruct LLM as being selected.
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? Provide a detailed explanation?\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.
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 and paste the following text in the file.
File name:
os-secret.yaml\nSubstitute a secure password of your choosing for the string <OPENSEARCH_PASSWORD>.
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 and paste the following text in the file.
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.
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 and paste the following text in the file.
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. 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.
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.
echo https://$(oc -n wxa4z-byos get route wxa4z-client-ingestion -o jsonpath=\"{.spec.host}\")\nYou 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.
Be careful with the sample phrases that you specify.
During the development of the lab guide, it was discovered that some sample phrases with a / character can cause issues with the actions. Avoid using z/OS in the your sample phrases. This issue has been reported to the offering team.
Sample prompts:
Get zOS facts\nGather zOS 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 zOS 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 zOS 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).
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.
Be careful with the sample phrases that you specify.
During the development of the lab guide, it was discovered that some sample phrases with a / character can cause issues with the actions. Avoid using z/OS in the your sample phrases. This issue has been reported to the offering team.
Example prompts:
Show me zOS facts\nGather and display zOS 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 zOS 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 zOS 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.
"}]} \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index 2d1c33f..2ef01e8 100644 Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ