Troubleshooting: How to exclude a customizing as a cause of a problem in censhare Web
Table of Contents:
There are 4 reasons, which can lead to a problem in censhare web:
Wrong customization/configuration
Bug in censhare default product
Bug in censhare product, which can be detected only with a specific configuration
Wrong censhare installation
This article will help you to exclude wrong customization/configuration as a cause .
The most common misconfigurations, which are reflecting the functionality of censhare Web, are observed in:
I. Workspace assets
II. Customized web modules
III. User Preferences templates
IV. Customization in other default module assets such as system, branding, dialogs, content editor, transformations, server actions, tables, searches, wizards, marcos, etc.
V. Master data
I. How to exclude Workspace assets as a cause
Example scenario:
A user "TestUser" with default role "TestRole" reports a problem in censhare Web.
There is no information if other users are affected.
Server action "Synchronize module assets" returns no errors.
Server action "Update web application configuration" completes without compilation errors.
Step 1. Determine if this is a user or a user-role specific problem.
Create a duplicate of "TestUser" => "TestUserDuplicate"
If the problem is reproducible with TestUserDuplicate, this is not a user specific, but a user-role specific problem. See Step 2 of Section I
If the problem is not reproducible with TestUserDuplicate, this is most probably a user specific problem.
Possible source of the problem:
All personal changes/customizations, done by the TestUser within its own User-Workspace such as rearranging of widgets/containers and others, are saved as resource events in the User-Workspace-Asset. Some resource events, which have been created in older censhare versions may no longer be supported in the current version. Normally such outdated events are simply ignored, but there might be cases where they are in collision with the current resource events.
Solution:
Reset (or even manually delete) the User-Workspace asset of user TestUser (How to find the user's Person and Workspace assets) and re-login. In case of reset, the resource events will be deleted from the existing User-Workspace asset. In case of deletion a new User-Workspace asset without resource events will be created on the next login of TestUser. All previous personal changes/customizations within the User-Workspace will be lost in both cases.
If the problem is not related to resource events, but to the user’s preferences, alternatively the User-Preferences-Asset should be reset (or even deleted manually).
If the initial problem is, that a user cannot even login and if the reseting of User-Workspace/User-Preferences doesn't solve the problem, temporary a new person asset should be assigned to the user. E.g. by deletion of party_asset_id in master data => new person, new user workspace, new user preferences, new pinboard, new favorites and new watched assets will be automatically created on the next user login.
If the problem is solved, the root cause should be analysed additionally, as a new person asset is only a workaround. Customizing cannot be excluded as a cause in this case.
Even if a new person asset does not fix the problem, most probably it is not related to censhare Web customization, but e.g. to a database problem, bug or something else.ˀ
Step 2. If this a user-role specific problem, find out what type of workspace template is applied for this user role and if it is a default or a customized.
Basics:
Two types of templates can be configured in censhare Web:
A. Workspace template based on assets (asset structure). It is only one but can be customized via resource replace variants (RRVs) of the assets, which are building it.
B. Workspace template based on XML file. There may be multiple templates of this kind on the system.
The default workspace template is A - based on assets.
There is no default XML-based template. But there is a possibility to create an XML representation of the default assets-based template (see Step 4 of section I), using a default manual server action.
Usually only one type of workspace template should be active for a specific role. There might be a deviation to this rule, due to a wrong configuration. Therefore, it is good to know how censhare reacts in such cases.
Case: Both types of templates are active for a specific role.
The XML template has higher priority and will overwrite the assets-based template.
Case: Two or more XML-based templates are active for a specific role.
Only one of the templates will be applied randomly on a user login.
Case: There are two or more RRVs of an asset, in which the same role is set.
Only one of the RRVs will be applied randomly on user login.
Case: Workspace asset has two RRVs. In the first one no resource replace role is set. In the second one TestRole is set.
For TestUser the second RRV will be applied.
Find what type of workspace template uses TestRole:
2.1. Check if XML-based template is applied for TestRole
The following expert search in censhare Web or in java client shows, if there are active XML-based templates for role TestRole. Currently the expert search is more accurate way to find the active XML templates, than the Workspace Template widget of the system asset, because the Workspace Template widget lists also templates without resource keys as active templates.
Search XML-based workspace template for TestRole
Important
If an XML-based template does not have a specified resource role, it won’t be applied to any user-role and can be ignored.
Important
Please have in mind that the Workspace Views are not part of the XML-based template. If in doubt, that the problem is related to Workspace Views, check if the Workspace Views are customized.
If the search above returns a result, this means that XML-based template is applied for TestRole, i. e. the problem occurs in a customized environment. At this stage a customized workspace cannot be excluded as a cause of the problem. Try to reproduce the problem on another system with the same customized XML workspace template. If the problem is reproducible – this is a customizing problem with the given XML workspace template.
Alternatively try to reproduce the problem on the custom environment, but with the default asset based template (see Step 3 how to do that).
If the problem is still not reproducible, see Section "II. How to exclude customized web modules as a cause".
If the search does not return a result, this means that an asset-based template will be applied for TestRole and not XML-based. In this case check if the default asset-based template is customized for TestRole.
2.2. Check if the default assets-based workspace template is customized for TestRole
The root element/asset of the assets-based template is defined in the system asset and has by default resource key "censhare:workspace.template.standard". Customized assets-based template means that at least one of the default-assets in the whole assets-based structure has RRV, which is not a default one.
Important
If an RRV does not have a specified resource replace role in its resource replace variant relation, the RRV will be applied to all existing user roles.
Use the system asset to get the resource key of the root asset of the assets-based template and check if this asset has a RRVs. Currently this is more accurate way to find if the root element of the asset-based template is customized, than the Workspace Template widget of the system asset, because the Workspace Template widget does not list all RRVs, but just the one, which is applied to all roles.
The root asset of the assets-based template has two RRVs
The Workspace Replace Variants widget of the system asset gives an overview, if pages, containers and widgets of the default asset-based template are customized:
Workspace Replace Variants widget shows that the default page "Asset image logo" is customized.
The assets-based workspace template has a customization, which reflects users with default role TestRole if:
The root asset of the assets-based template has a RRV, in which no role or TestRole is set to the resource replace variant relation.
OR
There is at least one RRV for TestRole or for all roles in Workspace Replace Variants widget.
If there are neither RRVs for TestRole nor for "all roles", this means that the default asset-based template is applied for TestRole. A customized workspace template can be excluded as a cause of the problem. See also Step 5 of Section I and Section "II"
If there is at least one RRV (as on the screenshots above) this means that the problem occurs in a customized asset-based workspace template. There are two possibilities to continue with the analysis:
Choice: Try to reproduce the problem with the default assets-based workspace template on the customer system. See Step 3 of section I how to do that.
If the problem is not reproducible with the default assets-based workspace on the customer system, this is a customizing problem with the customized assets-based workspace template.
If the problem is reproducible with the default assets-based workspace on the customer system, a customized asset-based workspace template can be excluded as a cause of the problem. See Step 5 of Section I and Section "II".
Choice. Create XML representation of this customized assets-based template and try to reproduce the problem on another system with this XML template. See Step 4 of Section I how to do that.
If the problem is reproducible – this is a customizing problem with the customized assets-based workspace template.
If the problem is not reproducible, see See Step 5 of Section I and Section "II".
Step 3. How to test a problem with the default assets-based workspace template on an already customized environment.
3.1. Create a NewRole with permission set "System Administrator" (id admin).
3.2. Create a NewUser user only with main role and main domain without additional roles. The main/default role should be NewRole, the main/default domain – root.
3.3. Login with a user, which is "System Administrator" in root. domain (e.g. NewUser fulfil this requirement).
3.4. Execute the following expert search to get a list of all (for all roles) not default RRVs of workspce assets.
Search for not default RRV of all workspace assets
3.5. Find the parent asset of every RRV in the list above. It should be an asset form the default assets-based template (i.e. asset of type module.workspace.*).
3.6. For every parent asset create a new RRV and assign the new NewRole to the resource replace variant relation.
3.7. Re-login with NewUser and try to reproduce the reported problem.
3.8. Revert the changes: delete the RRVs created in 3.6, delete the NewRole and NewUser.
Step 4. How to create XML workspace template from a customized assets-based template.
4.1. Login with TestUser and open its User-Workspace-Asset. (How to find the user's Person and Workspace assets).
4.2. Execute server action "Create Workspace XML Template". A new asset of type Module/Workspace without resource key will be created. This asset is the XML representation of the assets-based template, which is applied for TestUser.
4.3. Use server actions "Export/Import Assets" to export it and import it into independent test system.
4.4. On this independent test system, create a NewRole (System Administrator in root. domain) and a NewUser with default role NewRole.
4.5. Enable the XML template asset imported in 4.3. by setting a resource key and resource role => NewRole.
4.5. Login with user NewUser and try to reproduce the problem.
Step 5. Check if the Workspace view or Left workspace navigation assets are customized.
If in doubt, that the problem is related to a Workspace views , the following expert searches check for customized Workspace views:
Search for RRVs of the default workspace views
Search for customer-specific workspace views
Similarly can be check if the Left workspace navigation is customized.
If the first search above returns at least one result, this means that the workspace views (resp. left navigation) are customized via RRVs. Please refer to Step 3 of Section I how to exclude them as a cause of the problem.
If the second search above returns results, the customer-specific workspace views (resp. left navigation) should be temporarily deactivated or removed from the system asset. If the problem exists also without them, they can be excluded as a cause.
II. How to exclude customized web modules as a cause
Sometimes the source of a censhare Web problem is not or not only in a customized workspace asset, but also in a customized web module.
The customized censhare Web modules should be in directory /opt/corpus/cscs/app/web
If there are customized modules in this folder, try to reproduce the problem by coping these modules into independent system together with all customized module assets (workspace, preferences, dialogs, etc.) that might be related to the problem.
If the problem is still not reproducible, the next step of the troubleshooting would be to deactivate the customized modules directly on the customer system and try to reproduce the problem without them.
Collect the paths of all module assets, defined in file ~cscs/app/modules/admin/module_assets/sync-runtime-assets.xml, respectively in ~css/app/modules/admin/module_assets/sync-runtime-assets.xml (if the file is not customized).
Collect the paths of the module assets, defined in sync-runtime-assets.xml
b. Search for module assets, that has been created from these module-paths (via censhare web or java client) using feature "Module asset source" (id = censhare:module-asset-source):
Example search for module assets, that have been imported via module-path "~cscs/app/modules/dias_test"
3. If the found module assets are active, deactivate them by setting flag "Resource enabled" (feature id = censhare:resource-enabled) to false.
Important! For easy traceability and restore of the changes, assign the just modified module assets to a new group asset.
4. Stop censhare server.
5. Important! Backup the following directories outside censhare/ directory (e.g. under /opt/corpus/backup):
/opt/corpus/cscs/app/web/
/opt/corpus/cscs/app/modules/
/opt/corpus/work/runtime-web/
/opt/corpus/work/runtime.<server_name>/
/opt/corpus/work/scriptlets/
/opt/corpus/work/scriptlets-gen/
/opt/corpus/work/scriptlets-web/
6. Remove directories:
/opt/corpus/cscs/app/web/
/opt/corpus/cscs/app/modules/
/opt/corpus/work/runtime-web/
/opt/corpus/work/runtime.<server_name>/
/opt/corpus/work/scriptlets/
/opt/corpus/work/scriptlets-gen/
/opt/corpus/work/scriptlets-web/
7. Start censhare server.
If the problem is still reproducible, customized modules can be excluded as a cause of the problem.
If the problem is not reproducible, restore directories /opt/corpus/cscs/app/web/ and /opt/corpus/cscs/app/modules/ and the deactivated module assets one by one to isolate the source.
III. How to exclude user preferences template as a cause
By default, there is no Preferences template asset. However, a preferences template asset can be created manually and will overwrite the default definitions.
If in doubt, that the problem is related to a user preferences, the following expert search checks if a customized preferences template is applied for TestRole:
Search for manually created user preferences template
Important
If the template does not have a specified resource role, it won’t be applied to any user-role and can be ignored.
IV. How to find out if a single customized default module asset is the cause
Example scenario for dialog asset:
TestUser reports missing content of widget
User "TestUser" with default role "TestRole" reports missing content of widget on tab "Details" of asset type Image. When switching to tab "Details" an error "No master storage item found" appears.
The widget is defined as not configurable and its name is hidden for TestRole
The problem is reproducible for users with different Roles and with TestUserDuplicate, which is duplicate of TestUser
Server action "Synchronize module assets" returns no errors.
Server action "Update web application configuration" completes without compilation errors.
Initial analysis shows that for TestRole the assets-based template is applied and it is customized via RRVs.
Step 1. Try to reproduce the problem with XML representation of the customized asset-based template on another system with default configuration.
Result: not reproducible. So, the problem is not in the customized template, but this still does not exclude a customizing problem.
Step 2. Alternatively try to reproduce the problem with default asset-based template on the customer system.
Result: reproducible. So, the problem is not in the customized workspace template, but this still does not exclude a customizing problem.
Step 3. Find out the widget’s kind - csAssetMetadataWidget, csRelatedAssetWidget, etc.
Knowing the widget’s kind helps to find out in which direction to search a problem. E.g. csAssetMetadataWidget => dialog assets; csReportWidget => transformationassets; csRelatedAssetWidget => relation/feature definitions in master data; csTableWidget => search/table/transformation assets, etc.
At this stage it is unknown what kind of widget is that, because:
- its name is hidden
- it is defined as not configurable for TestRole, i.e. action "Configure widget …" is not active.
Inspecting the widget via the bowser’s developer tool, shows that this is a Metadata widget, which means that a dialog asset is responsible for the widget’s content. Which also explains why this is not a workspace template specific problem.
Inspect element of the browser developer tool gives a hint for widget’s kind
Step 4. Find the corresponding module.dialog. asset
The first step is to find the relevant workspace page asset, on which TestUser reports the problem, because this page asset contains reference to the corresponding workspace tab/container "Details" asset. This container asset has a reference to the widget configuration asset. In this widget configuration asset, there is a feature "internal widget configuration", which contains the resource key of the target dialog asset.
There are two possibilities to find the workspace page, container and widget configuration:
4.1. Create XML template from the asset-based template (only for censhare versions higher than 2017.2).
4.1.1. Login with user TestUser, open the User-Workspace asset and execute serveraction "Create Workspace XML Template".
4.1.2. Open the just created XML file and search for the URL pattern of the page, from which the customer reports the problem. In this case => "/assetImage/"
Searching for resource key of a dialog asset
The workspace page URL pattern should be unique, therefore the search returns only one result page. If this is not the case, the author of the asset-based workspace template should correct it before further analysis on the current problem.
Within the found page is container "Details" and the corresponding widget configuration. Both are default workspace assets (see the screenshot above).
4.1.3. The resource key of the target dialog asset is given with attribute templateKey in the widget configuration.
4.2. Direct search in the asset-based structure
4.2.1. The start point of the search is the URL pattern of the asset page, from which the customer reports the problem. In this case => "/assetImage/"
The following search (java client or censhare Web) will return all pages with this pattern:
Find workspace page asset via its URL page pattern
4.2.2. If there are more than one results, it should be checked which page asset is referenced (via resource key) form the root asset of the asset-based template, applied for TestRole. The workspacepage URL pattern should be unique, therefore only one of the result pages should be referenced. If this is not the case, the author of the asset-based workspace template should correct it before further analysis on the current problem.
If the page has RRVs, determine which one is applied for TestRole.
4.2.3. The page asset references container "Details"
Asset image page references container "Details"
4.2.4. Container "Details" references the widget configuration in question. The sequence of the widget configuration on the screenshot below is the same as their order on the asset image page.
Container "Details" references the searched widget configuration
4.2.5. In the widget configuration there is a feature "internal widget configuration", which contains the resource key of the target dialog asset.
Resource key of the target dialog asset
Step 5. Try to reproduce the problem with the default configuration of the module.dialog. asset:
The dialog asset, found in step 4, is default asset, but it has RRVs. Therefore, the problem should be tested with its default configuration.
5.1. Create a NewRole with permission set "System Administrator" (id admin).
5.2. Create a NewUser user only with main role and main domain without additional roles. The main/default role should be NewRole, the main/default domain – root.
5.3. Login with a user, which is "System Administrator" in root. domain (e.g. NewUser fulfil this requirement).
5.4. Create a new RRV of the default configuration of the customized dialog asset and assign the new NewRole to the resource replace variant relation (How to assign role to any relation or variant relation)
5.5. Re-login with NewUser and try to reproduce the problem. If reproducible – this is not a customizing problem in this asset.
In this example scenario the problem is not reproducible, which means that there is an error in the RRV, which is applied for TestRole => namely it does not have a master storage item.
5.6. Revert the changes: delete the RRV created in 5.4, delete the NewRole, NewUser and TestUserDuplicate.