--- title: Upgrade Java RCS description: Before you upgrade the Java RCS and any connectors running on it, you must update the connector configuration (specifically the bundleVersion) to include the versions you're upgrading to. The bundleVersion defines a range of versions or a specific version. component: openicf page_id: openicf:connector-reference:upgrade-java-server canonical_url: https://docs.pingidentity.com/openicf/connector-reference/upgrade-java-server.html section_ids: update-connector-configuration: Update connector configuration update-connector-configuration-rest: Update connector configuration over REST update-connector-configuration-provisioner: Update connector configuration in provisioner file (IDM only) upgrade-rcs-connectors: Upgrade the RCS and connectors upgrade-rcs-and-connectors: Upgrade the RCS and any connectors running on the RCS upgrade-connector-only: Upgrade a connector running on the RCS --- # Upgrade Java RCS Before you upgrade the Java RCS and any connectors running on it, you must update the connector configuration (specifically the `bundleVersion`) to include the versions you're upgrading to. The `bundleVersion` defines a range of versions or a specific version. If the `bundleVersion` doesn't include the RCS version or connector version you're upgrading to, the new RCS or connector won't be usable after the upgrade. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Use a range for the `bundleVersion` to make future RCS and connector upgrades easier. The following example includes all versions starting from `1.5.0.0` up to, but not including, `1.6.0.0`:```json "bundleVersion": "[1.5.0.0,1.6.0.0)" ``` | ## Update connector configuration For IDM, you can update the connector over REST or in the provisioner file. For Advanced Identity Cloud, you can only update the configuration over REST. ### Update connector configuration over REST 1. Get the connector configuration: * IDM * Advanced Identity Cloud ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Content-Type: application/json" \ --request GET \ "http://localhost:8080/openidm/config/provisioner.openicf/connectorName" ``` ``` curl \ --header "authorization: Bearer " \ --header "Content-Type: application/json" \ --request GET \ "https:///openidm/config/provisioner.openicf/connectorName" ``` | | | | - | ---------------------------------------------------------------------------------------------------- | | | Keep a copy of this configuration before making changes in case you need to re-create the connector. | 2. Check the `bundleVersion` in the response includes the new RCS and connector versions. If the `bundleVersion` in the response includes the new RCS and connector versions, move ahead to [Upgrade the RCS and connectors](#upgrade-rcs-connectors); otherwise, continue to the next step of this procedure. 3. Update the `bundleVersion` to include the new RCS and connector versions. This example uses non-matching brackets to specify a range: ```json "bundleVersion": "[1.5.0.0,1.6.0.0)" ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------ | | | For more information about version range options, refer to [Connector reference properties](configure-connector.html#connector-reference-props). | 4. Use a PUT request to update the connector configuration previously returned with the updated `bundleVersion`: * IDM * Advanced Identity Cloud ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data-raw '{complete-configuration}' \ "http://localhost:8080/openidm/config/provisioner.openicf/connectorName" ``` ``` curl \ --header "authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data-raw '{complete-configuration}' \ "https:///openidm/config/provisioner.openicf/connectorName" ``` 5. If you are using Advanced Identity Cloud, [promote your connector configuration changes](https://docs.pingidentity.com/pingoneaic/latest/tenants/self-service-promotions.html) to staging and production. ### Update connector configuration in provisioner file (IDM only) 1. Open the `project-dir/conf/provisioner.openicf-connectorName` file. If the `bundleVersion` in the file includes the new RCS and connector versions, move ahead to [Upgrade the RCS and connectors](#upgrade-rcs-connectors); otherwise, continue to the next step of this procedure. 2. Update the `bundleVersion` to include the new RCS and connector versions. This example uses non-matching brackets to specify a range: ```json "bundleVersion": "[1.5.0.0,1.6.0.0)" ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------ | | | For more information about version range options, refer to [Connector reference properties](configure-connector.html#connector-reference-props). | ## Upgrade the RCS and connectors ### Upgrade the RCS and any connectors running on the RCS | | | | - | -------------------------------------------------------------------------------------------------------------- | | | You can [upgrade a connector](#upgrade-connector-only) running on the RCS without upgrading the RCS if needed. | 1. Download the new Java RCS and any required connectors from [Backstage download site](https://backstage.forgerock.com/downloads). 2. Stop the RCS: * If the RCS is running in a terminal, press `CTRL`+`C` or `q`. * If the RCS is running as a service, stop the service: * Linux * Windows ```console sudo systemctl stop rcs.service ``` ```console net stop OpenICFConnectorServerJava ``` 3. Rename the existing RCS directory to create a backup: * Linux * Windows ```console mv /path/to/openicf /path/to/openicf_old ``` ```console ren C:\path\to\openicf openicf_old ``` 4. Extract the downloaded Java RCS to the original directory (`/path/to/openicf`). 5. Copy the downloaded connector .jar file(s) to the `/path/to/openicf/connectors` directory. 6. Copy any custom connectors, such as scripted connectors from your backup to the `/path/to/openicf/connectors` directory to retain your customizations. 7. Copy the following files from your backup to the new RCS directory to retain your previous settings: * `conf/logback.xml` (if the RCS is set up for debug logging) * Any truststores and keystores. These are typically located in the `/path/to/openicf/security` directory. 8. Copy the applicable lines from your backup `conf/ConnectorServer.properties` file to the new RCS version of the file. Copying specific lines from the file ensures you get the latest updates to new and important configuration properties. In a typical deployment, you should copy: ConnectorServer.properties excerpt ```properties connectorserver.url=wss://my-tenant.forgeblocks.com:8443/openicf (1) connectorserver.connectorServerName=myConnectorServer (1) connectorserver.hostId=MY_UNIQUE_RCS_HOST_ID (1) connectorserver.tokenEndpoint=https://my-tenant.forgeblocks.com/am/oauth2/realms/root/realms/alpha/access_token (1) connectorserver.clientId=my-client-id (1) connectorserver.clientSecret=my-client-secret (1) connectorserver.trustStoreFile=security/truststore.pkcs12 (2) connectorserver.trustStoreType=PKCS12 (2) connectorserver.trustStorePass=changeit (2) connectorserver.keyStoreFile=security/keyStore.pkcs12 (3) connectorserver.keyStoreType=PKCS12 (3) connectorserver.keyStorePass=changeit (3) connectorserver.keyPass=changeit (3) connectorserver.proxyHost=my-proxy-host (4) connectorserver.proxyPort=my-proxy-port (4) connectorserver.proxyPrincipal=my-proxy-principal (4) connectorserver.proxyPassword=my-proxy-password (4) ``` | | | | ----- | ----------------------------------------------------- | | **1** | Connection details. | | **2** | Copy these lines if you have configured a truststore. | | **3** | Copy these lines if you have configured a keystore. | | **4** | Copy these lines if you have confiured a proxy. | 9. Start the RCS: * Linux terminal * Windows terminal * Linux service * Windows service ```console /path/to/openicf/bin/ConnectorServer.sh /run ``` ```console c:\path\to\openicf> bin\ConnectorServer.bat /run ``` ```console sudo systemctl start rcs.service ``` ```console net start OpenICFConnectorServerJava ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | In Advanced Identity Cloud, you must:1. Make these changes to the RCS in all three Advanced Identity Cloud environments (development, staging, and production). 2. Restart your staging and production environments using the Restart API endpoint: ``` curl \ --header "authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" --request POST \ "https:///environment/startup?_action=restart" ``` | ### Upgrade a connector running on the RCS You can upgrade a connector running on the RCS without upgrading the RCS itself. 1. Download the new connector version from [Backstage download site](https://backstage.forgerock.com/downloads). 2. Stop the RCS: * If the RCS is running in a terminal, press `CTRL`+`C` or `q`. * If the RCS is running as a service, stop the service: * Linux * Windows ```console sudo systemctl stop rcs.service ``` ```console net stop OpenICFConnectorServerJava ``` 3. Copy the downloaded connector .jar file to the `/path/to/openicf/connectors` directory and remove the old .jar file version. 4. Start the RCS: * Linux terminal * Windows terminal * Linux service * Windows service ```console /path/to/openicf/bin/ConnectorServer.sh /run ``` ```console c:\path\to\openicf> bin\ConnectorServer.bat /run ``` ```console sudo systemctl start rcs.service ``` ```console net start OpenICFConnectorServerJava ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | In Advanced Identity Cloud, you must:1. Make these changes to the RCS in all three Advanced Identity Cloud environments (development, staging, and production). 2. Restart your staging and production environments using the Restart API endpoint: ``` curl \ --header "authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" --request POST \ "https:///environment/startup?_action=restart" ``` |