The MODIFY command

Use the MODIFY command to refresh the IBM® z/OS® Connect server artifacts such as API archive (.ara), Service archive (.sar) and API requester archive (.ara) files, policies and rule sets, data transformation files and the server.xml configuration file. It can also be used to clear caches.

To use the MODIFY command, add the following feature to the server.xml configuration file:
<feature>zosconnect:zosConnectCommands-1.0</feature>

Syntax

modify <jobname>.<identifier>,help|zcon,refresh|cleartokencache|clearsafcache

If the help parameter is not used, the zcon parameter is required, followed by one of the options.

Parameters

jobname
Specifies the job name of the target server.
identifier
Specifies an identifier to distinguish between multiple jobs that use the same job name.
help
Displays information about the supported parameters and options.
zcon
Must be included and written as shown if any options are used.

Options

refresh
Specifies that the IBM z/OS Connect server artifacts be refreshed. These artifacts include API archive (.ara), Service archive (.sar) and API requester archive (.ara) files, policies and rule sets, data transformation files and the server.xml configuration file.
Note:
  1. To update the configuration file, the configuration must contain the statement <config updateTrigger="mbean"/>.
  2. If an API or service is invoked while a refresh is in progress, interceptor calls might not occur as expected. For example, you change the server.xml file to add an interceptor, and issue the refresh command. While the refresh occurs, a service is invoked. The preInvoke interceptor method is not called because the refresh is not finished. After the refresh is complete, the postInvoke interceptor method for the service is called because it now exists.
  3. When you use the MODIFY command to refresh the IBM z/OS Connect server artifacts, the value of the updateTrigger attribute on the zosconnect_apiRequesters, zosconnect_policy, zosconnect_services, zosconnect_zosConnectAPIs, and zosconnect_zosConnectDataXform elements are ignored. Leave these values to default (updateTrigger="disabled") to prevent changes from other update mechanisms.
  4. To refresh keystores, including SAF key rings, Liberty provides the MODIFY REFRESH,KEYSTORE command. For more information, see Modify commands on z/OS in the WebSphere® Application Server for z/OS Liberty documentation.
cleartokencache
Causes all access tokens retrieved from an authentication or authorization server and locally generated JWTs to be cleared from the cache.
clearsafcache
Causes the SAF cache to be cleared. The SAF cache contains SAF user IDs and any associated RACF groups in which the user ID resides. The SAF cache is only applicable to API requester, and only when ID assertion is enabled.

These artifacts include API archive (.ara), Service archive (.sar) and API requester archive (.ara) files, policies and rule sets, data transformation files and the server.xml configuration file.

Examples

The following command refreshes the artifacts that have new updates.

modify zosconn01.1023,zcon,refresh
The following command clears the OAuth 2.0 access token and JWT cache:
modify zosconn01.1023,zcon,cleartokencache
The following command clears the SAF cache:
modify zosconn01.1023,zcon,clearsafcache