Update ctl tool documentation #6172
+227
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| ## Logging | ||
|
|
||
| IAM-CTL uses a unified logging system that provides structured, filterable log output with resource context and an end-of-run summary after every export or import operation. | ||
|
|
||
| ### Log configuration | ||
|
|
||
| Add a `LOGS` block to your `toolConfig.json` to configure logging behavior: | ||
|
|
||
| === "toolConfig.json" | ||
|
|
||
| ```json | ||
| { | ||
| "LOGS": { | ||
| "LOG_LEVEL": "INFO", | ||
| "LOG_REQUEST_PAYLOADS": false | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| | Property | Values | Default | Description | | ||
| | ---------------------- | -------------------------------- | ------- | ---------------------------------------------------------------------------------------------- | | ||
| | `LOG_LEVEL` | `DEBUG`, `INFO`, `WARN`, `ERROR` | `INFO` | Minimum log level to print. Messages below this level are suppressed. | | ||
| | `LOG_REQUEST_PAYLOADS` | `true`, `false` | `false` | When set to `true`, HTTP request bodies are logged at `DEBUG` level for POST and PUT requests. | | ||
|
RovinKYK marked this conversation as resolved.
|
||
|
|
||
| !!! warning "Sensitive data in request payloads" | ||
| Request bodies may contain sensitive credentials (client secrets, passwords, access tokens). Enabling `LOG_REQUEST_PAYLOADS` will write these values to your log output. Only enable this option in secure, non-production environments, and ensure log files are adequately protected. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,82 @@ | ||||||
| ## Resource-specific notes | ||||||
|
|
||||||
| The following notes describe resource-type-specific behavior to be aware of when using IAM-CTL. | ||||||
|
Contributor
There was a problem hiding this comment. 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win Convert passive construction to active voice. The phrase "to be aware of" is passive. As per coding guidelines, use active voice and present tense. Consider: "Note the following resource-type-specific behavior when you use IAM-CTL." 🧰 Tools🪛 LanguageTool[style] ~3-~3: To make your writing concise, consider an alternative. (AWARE_OF) 🤖 Prompt for AI Agents |
||||||
|
|
||||||
| !!! note | ||||||
| Users and groups are considered dynamic configurations and are not portable across environments. When a resource contains user or group data embedded within it, IAM-CTL strips that data during export. As a result, importing into a target environment will remove this data from the affected resource. For resources that contain dynamic data, use IAM-CTL for initial resource creation only. Add the dynamic configurations manually, then exclude the resource in future imports using **`EXCLUDE`** to preserve the data. | ||||||
|
|
||||||
| ### Roles | ||||||
|
|
||||||
| Users and groups assigned to roles are not exported or imported by IAM-CTL. | ||||||
|
|
||||||
| ### Claims | ||||||
|
|
||||||
| Claim dialect names may contain characters that are not valid in file names (e.g., `http://wso2.org/oidc/claim`). IAM-CTL uses an escaped version of the dialect name as the file name (e.g., `http_wso2_org_oidc_claim`). When referencing a claim dialect in tool configurations such as **`EXCLUDE`** or keyword mappings, use the exact claim dialect name, not the escaped file name. | ||||||
|
|
||||||
| ### User stores | ||||||
|
|
||||||
| When propagating user stores, do not exclude the local claim dialect (`http://wso2.org/claims`). Excluding it will prevent new claim attribute mappings of user stores from being propagated. | ||||||
|
|
||||||
| ### Applications | ||||||
|
|
||||||
| When propagating applications, do not exclude roles. Excluding roles will prevent new application roles from being propagated. | ||||||
|
|
||||||
| ### Governance connectors | ||||||
|
|
||||||
| Group-based password expiry rules of the password expiry connector are not exported by IAM-CTL. As a result, these rules will be removed from the connector on import, when **`ALLOW_DELETE`** is enabled. | ||||||
|
|
||||||
| {% if product_name == "Asgardeo" or server_version >= "7.3" %} | ||||||
|
|
||||||
| ### Identity providers | ||||||
|
|
||||||
| Outbound provisioning groups of outbound provisioning connectors are not exported by IAM-CTL. As a result, these groups will be removed from the identity provider on import. | ||||||
|
|
||||||
| {% endif %} | ||||||
|
|
||||||
| ### Organizations | ||||||
|
|
||||||
| {% if product_name != "Asgardeo" %} | ||||||
| When referencing organizations in tool configurations such as **`EXCLUDE`** or keyword mappings, use the organization handle as the resource name. | ||||||
| {% endif %} | ||||||
|
|
||||||
| When IAM-CTL creates organizations using M2M app credentials, no user is assigned as the creator. As a result, no user has access to the newly created organization after creation. You can [manually assign an organization admin]({{base_path}}/guides/organization-management/onboard-org-admins/self-service-approach/#maintain-admins-within-the-organization){:target="_blank"} after the organization is created. | ||||||
|
Contributor
There was a problem hiding this comment. 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win Define the M2M acronym and convert to active voice. Two issues:
✍️ Suggested rewrite-When IAM-CTL creates organizations using M2M app credentials, no user is assigned as the creator. As a result, no user has access to the newly created organization after creation. You can [manually assign an organization admin]({{base_path}}/guides/organization-management/onboard-org-admins/self-service-approach/#maintain-admins-within-the-organization){:target="_blank"} after the organization is created.
+When IAM-CTL creates organizations using machine-to-machine (M2M) application credentials, IAM-CTL does not assign a user as the creator. As a result, no user has access to the newly created organization after creation. You can [manually assign an organization admin]({{base_path}}/guides/organization-management/onboard-org-admins/self-service-approach/#maintain-admins-within-the-organization){:target="_blank"} after IAM-CTL creates the organization.📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||
|
|
||||||
| {% if product_name != "Asgardeo" and server_version >= "7.0" and server_version < "7.3" %} | ||||||
|
|
||||||
| Alternatively, to assign a creator at import time, configure **`CREATOR_ID`** and **`CREATOR_USERNAME`** under `ORGANIZATIONS` in `toolConfig.json`. | ||||||
|
Check warning on line 46 in en/includes/deploy/ctl-tool/resource-specific-notes.md
|
||||||
|
|
||||||
| === "toolConfig.json" | ||||||
| ```json | ||||||
| { | ||||||
| "ORGANIZATIONS": { | ||||||
| "CREATOR_ID": "<user-id>", | ||||||
| "CREATOR_USERNAME": "<username>" | ||||||
| } | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| When both values are set, IAM-CTL assigns the specified user as the organization creator on import. These attributes are stripped on export and are not stored in the exported files, as they are environment-specific and not portable. | ||||||
|
Contributor
There was a problem hiding this comment. 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win Convert passive voice to active voice. The sentence contains passive constructions: "are stripped on export and are not stored in the exported files." As per coding guidelines, use active voice. ✍️ Suggested rewrite-When both values are set, IAM-CTL assigns the specified user as the organization creator on import. These attributes are stripped on export and are not stored in the exported files, as they are environment-specific and not portable.
+When you set both values, IAM-CTL assigns the specified user as the organization creator on import. IAM-CTL strips these attributes on export and does not store them in the exported files, as they are environment-specific and not portable.📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||
|
|
||||||
| {% endif %} | ||||||
|
|
||||||
| ### Branding | ||||||
|
|
||||||
| Branding contains two sub-resource types: **Branding Preferences** and **Custom Texts**. When referencing branding in tool configurations such as **`EXCLUDE`** or keyword mappings, use the sub-resource type names as shown below. | ||||||
|
|
||||||
| === "toolConfig.json" | ||||||
| ```json | ||||||
| { | ||||||
| "EXCLUDE": ["BrandingPreferences"], | ||||||
| "CUSTOM_TEXTS": { | ||||||
| "EXCLUDE": ["screen1"] | ||||||
| } | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| {% if product_name == "Asgardeo" or server_version >= "7.2" %} | ||||||
|
|
||||||
| ### Workflows | ||||||
|
|
||||||
| Users included in approval steps are not exported by IAM-CTL. These users will be removed from the exported workflow, and any approval steps that contained only users will also be removed. As a result, these users and steps will be removed from the workflow on import. | ||||||
|
|
||||||
| {% endif %} | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.