Additional configuration for upgrading AEM Guides as Cloud Service
ui_config.json). After every upgrade, review and modify your settings as needed to ensure compatibility with the latest changes.Depending on the version you are upgrading from, additional configuration steps may be required to integrate changes introduced in newer Cloud Service versions.
Some configurations apply only to specific versions only. Ensure you refer to the configuration sections below and apply the required configurations applicable for your set up.
Steps to apply search filters on DITAVAL files for all output presets
To ensure filters function correctly, update the ui_config.json. Change the properties listed under browseFilters > Non-DITA files > Ditaval Files as shown below:
{
"title": "Ditaval Files",
"property": "LOWER_NAME",
"operation": "like",
"value": ".ditaval"
}
Steps to perform B-Tree migration for Content Fragments
If references are not displayed for content fragments, you can choose to run the migration job:
POST:
http://localhost:4503/bin/guides/script/start?jobType=cf-reference-store-btree-migration
Response:
{
"msg": "Job is successfully submitted and lock node is created for future reference",
"lockNodePath": "/var/dxml/executor-locks/cf-reference-store-btree-migration/1683190032886",
"status": "SCHEDULED"
}
In the previous response, JSON, the key lockNodePath holds the path to the node created in the repository, which points to the job submitted. It will automatically be deleted once the job is completed. You can refer to this node for the status of the job.
Wait till this job is completed before proceeding to the next steps.
GET:
http://<aem_domain>/var/dxml/executor-locks/cf-reference-store-btree-migration/1683190032886.json
Steps to handle the 'fmdita rewriter' conflict
Experience Manager Guides has a custom sling rewriter module for handling the links generated in case of cross-maps (links between the topics of two different maps).
If you have another custom sling rewriter in your codebase, use an 'order' value greater than 50, as Experience Manager Guides sling rewriter uses 'order' 50. To override this, you need a value >50. For more details, view Output Rewriting Pipelines.
During this upgrade, since the 'order' value is changed from 1000 to 50, you need to merge the existing custom rewriter, if any, with fmdita-rewriter.
Configurations applicable for versions before June 2023
The following configurations are required only if you are using a version of Experience Manager Guides as a Cloud Service released before June 2023. Expand the relevant sections below to apply the necessary settings and ensure compatibility with necessary updates.
Perform the following steps for indexing the existing content and use the new find and replace text at map level and topic list under the reports tab:
-
Run a POST request to the server (with correct authentication) -
http://<server:port>/bin/guides/map-find/indexing. (Optional: You can pass specific paths of the maps to index them, by default all maps are indexed|| Example :https://<Server:port>/bin/guides/map-find/indexing?paths=<path of the MAP in repository>) -
You can also pass a root folder to index the DITA maps of a specific folder (and its subfolders). For example,
http://<server:port\>/bin/guides/map-find/indexing?root=/content/dam/test. Note that if both the paths parameter and root parameter are passed, only the paths parameter is considered. -
The API returns a jobId. To check the status of the job, you can send a GET request with job id to the same end point -
http://<server:port>/bin/guides/map-find/indexing?jobId={jobId}(For example:http://localhost:8080/bin/guides/reports/upgrade?jobId=2022/9/15/7/27/7dfa1271-981e-4617-b5a4-c18379f11c42_678) -
Once the job is completed, the previous GET request responds with success and mention if any maps failed. The successfully indexed maps can be confirmed from server logs.
Perform the following steps for post-processing the existing content and using the new broken link report:
-
(Optional) If there are more than 100,000 DITA files in the system, update the
queryLimitReadsandqueryLimitInMemoryunderorg.apache.jackrabbit.oak.query.QueryEngineSettingsServiceto a larger value (any value greater than the number of assets present, for example 200,000) and then redeploy.-
Use the instructions given in the Configuration overrides section in Install and configure Adobe Experience Manager Guides as a Cloud Service, to create the configuration file.
-
In the configuration file, provide the following (property) details to configure the
queryLimitReadsandqueryLimitInMemoryoption:table 0-row-3 1-row-3 2-row-3 PID Property Key Property Value org.apache.jackrabbit.oak.query.QueryEngineSettingsService queryLimitReads Value: 200000 Default Value: 100000 org.apache.jackrabbit.oak.query.QueryEngineSettingsService queryLimitInMemory Value: 200000 Default Value: 100000
-
-
Run a POST request to the server (with correct authentication) -
http://<server>//bin/guides/reports/upgrade. -
The API returns a jobId. To check the status of the job, you can send a GET request with job id to the same end point -
http://<server>/bin/guides/reports/upgrade?jobId= {jobId}
(For example:http://localhost:8080/bin/guides/reports/upgrade?jobId=2022/9/15/7/27/7dfa1271-981e-4617-b5a4-c18379f11c42_678) -
Once the job is completed, the previous GET request responds with success. If the job fails for some reason, then the failure can be seen from server logs.
-
Revert back to the default or previous existing value of
queryLimitReadsif you have changed it in step 1.
After you complete the installation, you can choose to start the translation job:
POST:
| code language-none |
|---|
|
Response:
| code language-none |
|---|
|
In the previous response JSON, the key lockNodePath holds the path to the node created in the repository pointing to the job submitted. It is automatically deleted once the job is completed, then you can refer to this node for the status of the job.
Wait till this job is completed before proceeding to the next steps.
| note note |
|---|
| NOTE |
| You should check if the node is still present, and the status of the job. |
| code language-none |
|---|
|