Giter Site home page Giter Site logo

hcl-tech-software / connections-doc Goto Github PK

View Code? Open in Web Editor NEW
6.0 8.0 12.0 779.24 MB

HCL Connections Product Documentation Help Center

Home Page: https://opensource.hcltechsw.com/connections-doc/v8-cr5/

License: Other

HTML 3.41% JavaScript 67.57% CSS 29.02%
connections documentation

connections-doc's Introduction

HCL Connections 8 for on-premises product documentation

HCL Connections Multi-Tenant product documentation

Contributing

Bug reports on product documentation and pull requests are welcome on GitHub at https://github.com/HCL-TECH-SOFTWARE/connections-doc. This is the Connections 8 on-premises and Connections MT product documentation site, not a product support platform. All bug reports and pull requests must pertain to the product documentation.

Updates should be performed only to the markdown files in the following folders

  • v8
  • v8-cr1
  • v8-cr2
  • v8-cr3
  • v8-cr4
  • v8-cr5

Updating the documentation and validating changes

  • Clone the Connections documentation repository and create a working branch.
  • Edit the markdown in connections-doc/source or scr_mt as needed.
  • Install Python 3
  • Install missing packages for MkDocs
pip3 install -r requirements.txt

To build the documentation run

mkdocs serve

Submitting documentation changes

  • Open a Pull Request.
  • Respond to review comments as needed.
  • You will be notified when your changes have been merged. They will appear on the public site the next time the documentation is built.

connections-doc's People

Contributors

davidsayer57 avatar erika-dg avatar lee-hung avatar leyrer-pnp avatar milanmatejic avatar ms2art avatar sabrina-yee avatar stoeps13 avatar stwissel avatar

Stargazers

avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar avatar avatar avatar

Forkers

davidsayer57 isabella232 stoeps13 billwimer leyrer-pnp sabrina-yee syeda-git aarondewes milanmatejic marde16 umeli fainbogdan

connections-doc's Issues

Menu not responsive

Hi,
when I open the site https://opensource.hcltechsw.com/connections-doc/ on mobile and click on the burger menu, then the page color gets a little darker, but no menu appears. Checked the digital-experience documentation, there the menu is responsive and working.
It can also be reproduced with the developer tools in Firefox and Chrome.
Regards
Christoph

Page format broken ICEC

The page shows wrong table format: https://opensource.hcltechsw.com/connections-doc/v8-cr5/connectors/icec/cec-inst-connections-config.html

The original page is https://help.hcltechsw.com/connections/v65/connectors/icec/cec-inst-connections-config.html

Additionally, I wonder why the widgetBundle should be defined because there is no strings file in <connections-share>/customization/strings with this name. Ah, I found the documentation https://opensource.hcltechsw.com/connections-doc/v8-cr5/connectors/icec/cec-inst-create-string-prop-files.html which is used to rename the Highlights application. So this is only needed if you want to adjust the application name.

I think that's an historic and outdated part of the documentation and was needed before IBM acquired XCC. This could be explained a bit more.
The main page for this topic https://opensource.hcltechsw.com/connections-doc/v8-cr5/connectors/icec/cec-inst-community-on-prem-config.html says:

To use the Engagement Center's Community iwidget for HCL Connections on-premises editions, perform the following steps.

Highlights is integrated to Connections since 6.5, so all these steps are not needed at all.

Spelling mistake in Values & Client ID exposed

Note: This form is for submitting issues about Connections MT documentation, not Connections MT itself.

Description

On this page, https://github.com/HCL-TECH-SOFTWARE/connections-doc/blob/main/v8-cr6/admin/secure/t_azure_oidc_websphere.md, you see that under Step 8 there is a table of properties and values. The endpoint properties, provider_1.tokenEndpointUrl, provider_2.tokenEndpointUrl, provider_3.tokenEndpointUrl, provider_4.tokenEndpointUrl the value is specified as https://login.microsoftlonline.com/{tenant}/oauth2/v2.0/token when it has an extra 'l' in it (microsoftlonline).

Same page, provider_2.scope, provider_2.scope, provider_4.scope all contain a client_id and not the replace value.

Desired

Value should be https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token, removing the extra 'l'.

Scopes should be updated to be the same as provider_1 with a value of 'openid profile email api://{client_id}/default'

Topics

https://opensource.hcltechsw.com/connections-doc/v8-cr6/admin/secure/t_azure_oidc_websphere.html
https://github.com/HCL-TECH-SOFTWARE/connections-doc/blob/main/v8-cr6/admin/secure/t_azure_oidc_websphere.md

To Reproduce

If this issue is about a product behavior, or a product UI element (like a dialog or some field help), that isn’t covered or is described incorrectly, include some steps to reproduce the behavior or get to the UI element.

Wrong helm_repo_path for Harbor OCI registry

Description

The value for the <<helm_repo_path>> given in the section "Log in to a Harbor OCI registry" of "Steps to install or upgrade to Component Pack 8" is wrong.
<<helm_repo_path>> is the Harbor repository to log into, that is https://hclcr.io

Observed

image

Desired

<<helm_repo_path>> is the Harbor repository to log into, that is https://hclcr.io/chartrepo/cnx

Topics

https://opensource.hcltechsw.com/connections-doc/v8-cr5/admin/install/cp_install_services_tasks.html#harbor_repo

CP Customizer installation instructions miss "Enabling the Connections app registry service"

Note: This form is for submitting issues about Connections MT documentation, not Connections MT itself.

Description

The "Set up Customizer" section of the "Steps to install or upgrade to Component Pack 8" page does mention the steps "Set up your reverse proxy to forward some traffic to the customizer and "Configuring the Customizer component" but it does not mention the step "Enabling the Connections app registry service for customization", which is mandatory if you want to use Customizer to modify the UI, which is it's main function.

Observed

image

Desired

Add a line similar to this in order to tie in the mandatory configuration step, so Customizer actually works as expected by customers:

Connections needs to be enabled to make requests to the app registry service to discover the extensions that Customizer provides. By default, Connections applications do not try to make requests to the app registry service to avoid unnecessary requests if the app registry service has not been deployed as part of a Component Pack installation. In order to enable the Customizer integration into Connections, follow the steps outlined in Enabling the Connections app registry service for customization.

Topics

https://opensource.hcltechsw.com/connections-doc/v8/admin/install/cp_install_services_tasks.html#section_n3c_xhj_dvb
https://opensource.hcltechsw.com/connections-doc/v8/admin/customize/enabling-app-registry.html?scLang=en

Inconsistent documentation on "Number of Apache Tika File Conversion Threads"

Description

The documentation on how to set the number of Apache Tika file conversion threads is inconsistent between the product documentation and the "Connections Performance and Tuning Guide" and the "Connections Performance and Tuning Guide" is is vague on how to properly set the values.

Product documentation at admin/admin/c_admin_search_file_index_issuesl:

tikaFileConversion.maxConversionThreads
Displays the maximum number of threads that will be allowed to run conversions simultaneously. This is also the maximum number of tika processes which run simultaneously.

Connections Performance and Tuning Guide:

Parameters to be modified. All 3 should be kept equal.
MAX_CONVERSIONS_THREADS == maxConcurrentDownloads == tikaFileConversion.maxConversionThreads
+ Note: 1st one to be modified through was console and next two in search-config.xml

  1. As you can see, the "Connections Performance and Tuning Guide" contradicts the product documentation as to where to change the number of Apache Tika file conversion threads.
  2. "Connections Performance and Tuning Guide" mentions
    a. "was console" without further information.
    b. "search-config.xml" without further information.

Observed

image
image

Desired

  1. Consolidate information between product documentation and "Connections Performance and Tuning Guide" to be consistent. Esp. regarding the configuration changes needed to modify the number of Apache Tika file conversion threads.
    2a) "MAX_CONVERSIONS_THREADS" looks like a Websphere environment variable to set via the IBM Websphere Integrated Solutions Console (ISC vulgo "was console"). If that is the case, provide a more detailed how-to or link to a fitting, already existing documentation page.
    2b) Provide more information on where "maxConcurrentDownloads" and "tikaFileConversion.maxConversionThreads" are located in the "search-config.xml", how to properly modify it (check in/check out, ...) and link to corresponding existing documentation.

Topics

HCL Connections Desktop Plug-ins: Missing "delay on sending network traffic" policy documentation

Version 22.11 (Nov, 2022) of the HCL Connections Desktop Plug-i introduced the new feature: "Policy-driven delay on sending network traffic on startup and on wake from sleep."

Description

Version 22.11 (Nov, 2022) of the HCL Connections Desktop Plug-ins introduced the new feature: "Policy-driven delay on sending network traffic on startup and on wake from sleep". See https://support.hcltechsw.com/csm?id=kb_article&sysparm_article=KB0073986
The documentation is missing a description of these policies..

Observed

See https://opensource.hcltechsw.com/connections-doc/v8-cr4/connectors/enduser/t_ms_office_group_policies.html

Desired

The parameters as described in CS0302418 should be added.

Topics

https://opensource.hcltechsw.com/connections-doc/v8-cr4/connectors/enduser/t_ms_office_group_policies.html

Congratulations and some ideas

Hi,
first, thanks and congratulations on moving forward with Connections documentation. Using mkdocs and publish the markdown files is a big improvement.

I checked the src_v8 folder and tried to build the documentation. The mkdocs.yml searches the markdown files in a folder source, so it only works to see the documentation when I move most of the folders to source:

.
├── source
│   ├── admin
│   ├── assets
│   ├── connectors
│   ├── guide_me
│   ├── logo
│   ├── stylesheets
│   └── user
├── theme_overrides
│   ├── assets
│   └── partials_ORG
└── theme_overrides-docs-as-code

Then I can test the documentation with mkdocs serve. If I'm wrong with this, can you please provide information in srv_v8/README.md how to build the documentation?

MkDocs needs the section-index plugin, so may I suggest adding a requirements.txt file with needed modules?

mkdocs>=1.1.2
mkdocs-section-index

Then everybody can install missing packages with pip3 install -r requirements.txt

As you're in the middle of releasing 8, I won't start creating this as PR, I assume this would be some hard merges.

In the global README DITA is mentioned to create the documentation, that's legacy or?

Thanks for any comments and fingers crossed for V8.

Regards
Christoph

Update for "Configuring Connections to support Keycloak OIDC Authentication"

Note: This form is for submitting issues about Connections MT documentation, not Connections MT itself.

Description

The screenshot for LCC config is very tiny.
After the configuration final steps are missing - restart of entire Cnx environment (Websphere and IHS).

Observed

image

Desired

  • Replace tiny screenshot with LCC config text - so we can copy & paste it.
  • add additional steps (restart of entire Cnx environment) after configuration part

Topics

URLs of topics affected.

Update for Keycloak configuration

In my test environment I use Keycloak V22.0.3 which has a different UI as used in the Connections Keycloak documentation.

If you create a mapper for the client scope roles the step differs from step 6 "Next create a Client Scope Mapper for realmName in the Keycloak admin portal. Go to {realm} > Client Scopes > roles > Mappers > Create.":

connections-doc/v8-cr2/admin/secure/t_keycloak_config_conn_oidc.md

Line 34 in 2d83167

6. Next create a Client Scope Mapper for realmName in the **Keycloak admin portal**. Go to **{realm}** > **Client Scopes** > **roles** > **Mappers** > **Create**.

... because you have to select the mapper by configuration.

So the documentation should be updated as follows:

  1. Next create a Client Scope Mapper for realmName in the Keycloak admin portal. Go to {realm} > Client Scopes > roles > Mappers > Add mapper > by configuration.

  2. Click entry Hardcoded claim in list

  3. Fill in the following fields with the values below and click Save.

    a. Name= realmName

    b. Token claim name= realmName

    c. Claim name= {realm}

The new UI of Keycloak replaces Access Type through Client authentication:

connections-doc/v8-cr2/admin/secure/t_keycloak_config_conn_oidc.md

Line 43 in 2d83167

11. **[Optional]** Create additional clients for the Connections mobile and desktop plugins applications. Similar to creating the main Connections client, in the **Keycloak admin portal** go to **Clients** > **Create**. Repeat for each client. <p> See the information and screenshots below for guidance. </p> <section>**Mobile Client** </section> The following creates the Keycloak client for mobile, there is additional Connections configuration required to complete enabling mobile access (see later section). <p> Set the values for the following fields as indicated:</p><p><ol><li>**Client ID** = connections_social_mobile</li><li>**Enabled** = On</li><li>**Client Protocol** = openid-connect</li><li>**Access Type** = public</li><li>**Standard Flow Enabled** = On</li><li>**Implicit Flow Enabled** = Off</li><li>**Direct Access Grants Enabled** = Off</li><li>**Valid Redirect URIs** = com.ibm.ibmscp://com.ibm.mobile.connections/token</li></ol></p><p>Under Advanced Settings, set:</p><ol><li>**Access Token Lifespan** = 60</li><li>**Proof Key for Code Exchange Code Challenge Method** = S256</li></ol>![keycloak_config_oidc_prov_p5.jpg](keycloak_config_oidc_prov_p5.jpg)<section>**Desktop Plugins**</section><p>Both Mac and Windows Desktop plugins use the same Keycloak client as the Mobile that is defined above (connections_social_mobile). Add the following redirect URI to the Valid Redirect URIs list of the Mobile client Valid Redirect URIs: <p><filepath>com.ibm.ibmscp://com.ibm.desktop.connections</filepath></p><p>**Note:** If you are supporting older desktop plugins (pre-21.07): <p><ul><li> Add another Keycloak client with ClientID: conn-dsk-plugin </li><li>Other than ClientID, use the same settings as the mobile Keycloak client </li><li>Add this redirect URI to the Valid Redirect URIs list of the conn-dsk-plugin client: <p>Valid Redirect URIs: <filepath>'com.ibm.ibmscp://com.ibm.desktop.connections' </li></ul></p> </p></p> </p></li>

So the documentation should be updated as follows:

In step 11 the mobile definition have to change:

Set the values for the following fields as indicated:

a. Client ID = connections_social_mobile
b. Enabled = On
c. Client Protocol = openid-connect
d. Client authentication= Off (Note: former Access Type = public )
e. Standard Flow Enabled = On
f. Implicit Flow Enabled = Off
g. Direct Access Grants Enabled = Off
h. Valid Redirect URIs = com.ibm.ibmscp://com.ibm.mobile.connections/toke

Please update these steps on this site Configuring KeyCloak as an OIDC provider for Connections

Documentation is published on /connections-doc and /connections-documentation

Description

When I search for connections on opensource.hcltechsw.com I find two documentation repos:
image

connections-documentation has the documentation until cr3 and connections-doc until cr5. Searching in Google find both repos and links in the top 10.

So please publish the same documentation in both repos, or remove the older one. It is quite annoying searching in the old one.

Check

and the linked repositories.

Opensearch Upgrade to 2.7.0

Description

The description about the Opensearch update and backup is somehow misleading.

https://github.com/HCL-TECH-SOFTWARE/connections-doc/blob/946c61621beffdc9cf9e12cba70d58baaddffb90/v8-cr4/admin/install/upgrade_opensearch.md

"These files can include opensearch.yml, plugin configuration files, and TLS certificates, for example. Once you identify which files you want to back up, copy them to remote storage for safety."

The opensearch.yml is mounted from the Kubernetes config-map and the certs from K8s secrets. So even when you backup these, you have to update secret and configmap. (So better backup K8s).
image

As certs are only updated with bootstrap and setting the special flag and the only thing which happens when the certs are renewed, is that you have to redeploy the cert stores within WebSphere, this is not important at all.

Maybe as a side note because snapshots are mentioned here. Opensearch 2.1+ supports automatic schedulers for Snapshot creation (like some customers used in ES 7), but the plugin is not installed.
https://opensearch.org/docs/latest/tuning-your-cluster/availability-and-recovery/snapshots/snapshot-management/

As backup / restore with file system backups is not guaranteed with OpenSearch / Elasticsearch, this plugin could help all customers to keep the data.

As we are talking about opensearch.yml, please remove the option

audit.type: internal_opensearch

from opensearch.yml because this creates daily indices for securityaudits:
image

Or add an option to remove these auditlogs on a weekly basis.

Thanks
Christoph

Huge docs folder

The /docs folder needs about 7 GB and updates nearly each time. As these pages are stored in GH pages, why is the generated HTML stored in the repository at all?

Please add /docs to ⁣.gitignore and remove the folder from the repository.

Formatting of "Configuring file downloads through IBM HTTP Server" defect

Note: This form is for submitting issues about Connections MT documentation, not Connections MT itself.

Description

  • item/2 - Line break missing
  • item/3 - Code formatting missing
  • item/5 - broken link and formatting
  • item/5 Notes - formatting of application_context_root (no backslash) and line break (have to be removed)
  • item/9 - broken link and formatting

Observed

image

image

image

image

image

image

Desired

Fixing formatting.

Topics

URLs of topics affected.

Customize Huddo Boards is missing Highlights configuration

Note: This form is for submitting issues about Connections MT documentation, not Connections MT itself.

Description

Adding Activities Plus to a community or home page documentation page is missing the part to configure the Highlights widget for Huddo Boards

Observed

Missing doc

Desired

(https://docs.huddo.com/boards/connections/widgets-on-prem/#cec-community-highlights)

Topics

URLs of topics affected.

To Reproduce

If this issue is about a product behavior, or a product UI element (like a dialog or some field help), that isn’t covered or is described incorrectly, include some steps to reproduce the behavior or get to the UI element.

Update for "Updating WebSphere to support Keycloak OIDC Authentication for Connections"

Note: This form is for submitting issues about Connections MT documentation, not Connections MT itself.

Description

The configuration step for Keycloak realm as a trusted realm is twice.
Step 14 contains Microsoft Certificate endpoint instead of Keycloak

Observed

Keycloak realm
image
image

Certificate endpoint
image

Desired

  • The configuration step for Keycloak realm as a trusted realm is twice. Step 10 and Step 13 describe the same configuration, but Step 13 with a screenshot. Please remove one of them.

Update
When I compare the Keycloak configuration with this PDF "HCL MT CH-MSP Product Documentation - Keycloak Authentication and SSO" then I think Step 13 could be the outbound configuration. Or is this only for MT deployments?

  • Replace in step 14 the Microsoft Certificate endpoint with Keycloak Certificate endpoint

Topics

URLs of topics affected.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.