Configure agent connection

As an administrator, you can configure a connection type to securely connect to the agents.

About this task

The connection type is optional and can be configured to connect to third‑party Z endpoints; currently, this is required only for the Upgrade and zRAG foundational agents.

Procedure

Log in to the watsonx Assistant for Z Management Console.
From the Chat interface, click the three vertical dots in the upper-right corner, then select Connections.

Click Create New Connection + and provide the following details:

Connection Name: Enter a name for the connection.
Connection Type: Select one of the following connection types:
- Key-Value Credentials: Choose this option to define custom credential parameters specific to your agent’s requirement. It allows you to specify any required credentials as key-value pairs for the target agent.
  
  Note: For IBM Z Upgrade and zRAG agents, set the connection type to Key-Value Credentials.
- Basic Authentication: Choose this option to use traditional username and password authentication. The credentials are encoded and sent in the HTTP Authorization header using the Basic authentication scheme.
- Bearer Token: Choose this option to use API authentication with OAuth 2.0 or JWT tokens. A bearer token (typically obtained through a separate authentication process) is sent in the Authorization header.
- API Key Authentication: Choose this option to use API keys for authentication. A unique API key is sent as a header or query parameter to authenticate requests.

Credentials: Provide the following information:

Key: Defines the parameter name used internally by the agent. It identifies a specific configuration item or credential (for example, host, username, certificate, api_key).
Value: Specifies the actual data associated with the key. These are runtime values such as host details, tokens, credentials, or configuration inputs that the agent uses at runtime.

Use the following key-value pairs for IBM Z Upgrade agent.

Key Default value Sample JSON

Connections

None

Key	Default value	Sample JSON
Connections	None	{ "tivlp12": { "tes_url": "<TES base URL>", "tes_cert": { "key": "<Base64-encoded private key>", "cert": "<Base64-encoded certificate>" }, "jcl_config": { "SMPNTS": "<SMP/E NTS directory path>", "KEYRING": "<z/OS keyring name>", "PDS_NAME": "<REXX PDS dataset name>", "SMPCPATH": "<SMP/E classes directory path>", "SMPJHOME": "<Java home directory path>", "CERT_NAME": "<Certificate name>", "JCL_CLASS": "<JCL job class>", "JCL_ACCOUNT": "<JCL account number>", "JCL_MSGCLASS": "<JCL message class>", "SMPWDIR_PATH": "<SMP/E work directory path>", "DOWNLOADKEYRING": "<Download keyring name>", "DOWNLOAD_METHOD": "<Download method (http/https)>", "ORDER_SERVER_URL": "<Order server URL>" }, "tes_applid": "<TES application ID>", "zosmf_endpoint": "<z/OSMF endpoint URL>", "zosmf_ssl_verify": "<false)>", "default_email_id": "<Default email address>" } }

{
  "tivlp12": {
    "tes_url": "<TES base URL>",
    "tes_cert": {
      "key": "<Base64-encoded private key>",
      "cert": "<Base64-encoded certificate>"
    },
    "jcl_config": {
      "SMPNTS": "<SMP/E NTS directory path>",
      "KEYRING": "<z/OS keyring name>",
      "PDS_NAME": "<REXX PDS dataset name>",
      "SMPCPATH": "<SMP/E classes directory path>",
      "SMPJHOME": "<Java home directory path>",
      "CERT_NAME": "<Certificate name>",
      "JCL_CLASS": "<JCL job class>",
      "JCL_ACCOUNT": "<JCL account number>",
      "JCL_MSGCLASS": "<JCL message class>",
      "SMPWDIR_PATH": "<SMP/E work directory path>",
      "DOWNLOADKEYRING": "<Download keyring name>",
      "DOWNLOAD_METHOD": "<Download method (http/https)>",
      "ORDER_SERVER_URL": "<Order server URL>"
    },
    "tes_applid": "<TES application ID>",
    "zosmf_endpoint": "<z/OSMF endpoint URL>",
    "zosmf_ssl_verify": "<false)>",
    "default_email_id": "<Default email address>"
  }
}

The following table describes the configuration variables for the Upgrade agent. All variables are mandatory, and no default values are defined.

Variable	Description
`CONTEXT_NAME`	Specifies the target z/OS context, LPAR, or host where the automation or API request runs. This value uniquely identifies the environment configuration. For example, `tivlp12`.
`tes_url`	Specifies the URL of the Token Exchange Service (TES). This endpoint exchanges authentication credentials and obtains the RACF PassTicket that provides access to z/OS resources.
`tes_applid`	Specifies the RACF Application ID (APPLID) that is configured on the z/OS system. The Token Exchange Service uses this APPLID to generate a RACF PassTicket. The value must exactly match the APPLID that RACF defines.
`zosmf_endpoint`	Specifies the base URL of the z/OSMF REST API endpoint. All z/OSMF REST API requests are sent to this endpoint. For example, https://hostname:port/zosmf.
`zosmf_ssl_verify`	Specifies whether the connection to the z/OSMF endpoint verifies the SSL/TLS certificate. Set the value to `true` to verify the server certificate. Set the value to `false` to disable certificate verification. A value of `false` is recommended only for development or test environments.
`default_email_id`	Specifies the default email address that maps to a RACF user ID. The Token Exchange Service uses this email address to generate a RACF PassTicket when a user-specific email address is not provided.
`tes_cert`	Specifies the configuration object that contains the client certificate and private key for mutual TLS (mTLS) authentication with the Token Exchange Service. Both values must use Base64 encoding.
`tes_cert.key`	Specifies the Base64-encoded private key that is associated with the client certificate. Mutual TLS authentication uses this private key, which must correspond to the specified client certificate.
`tes_cert.cert`	Specifies the Base64-encoded client certificate that authenticates the client with the Token Exchange Service during mutual TLS communication. The certificate must be valid and must match the specified private key.
`jcl_config`	Specifies the configuration object that contains the JCL job card and SMP/E path settings that are required to build and submit JCL jobs to z/OSMF. These settings support PTF receive, HOLDDATA refresh, and hardware compatibility check operations.
`jcl_config.SMPNTS`	Specifies the z/OS UNIX path to the SMP/E NTS directory. This value maps to the //SMPNTS DD PATH= statement in the generated JCL.
`jcl_config.SMPWDIR_PATH`	Specifies the z/OS UNIX working directory that SMP/E uses during PTF receive processing. This value maps to the //SMPWKDIR DD PATH= statement in the generated JCL.
`jcl_config.SMPJHOME`	Specifies the Java home directory path that SMP/E uses. This value maps to the //SMPJHOME DD PATH= statement in the generated JCL and to the `javahome` element in the CLIENT XML block.
`jcl_config.SMPCPATH`	Specifies the SMP/E Java class library (JAVALIB) directory. This value maps to the //SMPCPATH DD PATH= statement in the generated JCL and to the classpath element in the CLIENT XML block.
`jcl_config.ORDER_SERVER_URL`	Specifies the HTTPS URL of the IBM ShopzSeries PTF order server. This value maps to the `url` attribute in the ORDERSERVER XML block.
`jcl_config.KEYRING`	Specifies the z/OS RACF `keyring` that contains the TLS certificate for outbound connections to the order server. This value maps to the `keyring` attribute in the ORDERSERVER XML block.
`jcl_config.CERT_NAME`	Specifies the RACF certificate label in the `keyring` that mutual TLS authentication uses when connecting to the order server. This value maps to the certificate attribute in the ORDERSERVER XML block.
`jcl_config.DOWNLOAD_METHOD`	Specifies the protocol that downloads PTF packages from the order server. Valid values are `https` and `http`. The value `https` is recommended. This value maps to the `downloadmethod` element in the CLIENT XML block.
`jcl_config.DOWNLOADKEYRING`	Specifies the z/OS RACF `keyring` that authenticates HTTPS download connections to the order server. This value maps to the `downloadkeyring` element in the CLIENT XML block.
`jcl_config.PDS_NAME`	Specifies the fully qualified MVS PDS data set name that stores REXX exec members for the hardware compatibility check job. For example, `USER.REXX.PDS`.
`jcl_config.JCL_ACCOUNT`	Specifies the accounting information for the JOB statement in all JCL jobs that the agent submits. This value maps to the account field in the JOB statement. For example, //JOBNAME JOB (<value>),....
`jcl_config.JCL_CLASS`	Specifies the job class for all JCL jobs that the agent submits. This value maps to the `CLASS= parameter` in the JOB statement.
`jcl_config.JCL_MSGCLASS`	Specifies the message class (SYSOUT class) for JCL job output, such as `SYSPRINT`, `SMPOUT`, and `SMPRPT`. This value maps to the MSGCLASS= parameter in the JOB statement.

Use the following key-value pairs for zRAG agent.

Key Default value Sample JSON

filter

None

Key	Default value	Sample JSON
filter	None	`{ "topics": { "enable": "", "disable": "" }, "doc_weight": { "product_docs": 1, "customer_docs": 0 }, "ibm_indices": "*_ibm_docs_slate" }`
metadata	None	`{ "rerank": true, "doc_weight": { "product_docs": 1, "customer_docs": 0 }, "search_type": "reranked_fusion", "customer_indices": "customer_*", "dynamic_filtering": true }`

{
  "topics": {
    "enable": "",
    "disable": ""
  },
  "doc_weight": {
    "product_docs": 1,
    "customer_docs": 0
  },
  "ibm_indices": "*_ibm_docs_slate"
}

metadata

None

{
  "rerank": true,
  "doc_weight": {
    "product_docs": 1,
    "customer_docs": 0
  },
  "search_type": "reranked_fusion",
  "customer_indices": "customer_*",
  "dynamic_filtering": true
}

Click Save.