EPMRPP-93644 || Add documentation for 24.2 (#761)

Co-authored-by: Yuliya_Prihodko <[email protected]>

docs/configuration/ProjectConfiguration.mdx

@@ -72,44 +72,120 @@ The "Integration" tab can allow the project to connect ReportPortal with externa
 
 For more information on this topic, please refer to [Integration with external systems](/configuration/IntegrationViaPlugin).
 
-### E-mail notifications
+### Notifications
 
-The "Notifications" tab provides the administrator with the ability to activate e-mail notifications on the project.
+The ‘Notifications’ tab provides the administrator with the ability to activate notifications on the project – through either Email or Slack.
 
-ReportPortal provides a way to add multiple rules with specific conditions. The Notification rule should be unique per project, have a unique parameter set, and specify recipients. For Example: In case, Launch names, attributes).
+ReportPortal provides a way to add multiple rules with specific conditions. The notification rule should be unique per Notification group – Email or Slack, have a unique parameter set. For example: In case, Launch names, Attributes.
 
-Permissions: 
-Users with `ADMINISTRATOR` a role can configure "Notifications" in the Administrate section.
-Users with `PROJECT_MANAGER` roles can edit the settings on the project space only.
-
-To do that, perform the following steps:
-
-1. Login to the ReportPortal.
-2. Navigate to the Project -\> Project "Settings" page.
-3. Open the "Notifications" tab and click on a button "Create new notification rule" 
-4. Enter your email into the "From" field. This email will be used as a notification sender.
-5. Select recipients. To do that, start typing any symbols into the "Recipients" field.
-You can select an item from the auto-complete tool-tip using the
-keyboard (use the "Up" and "Down" arrows and "Enter" button). You can also enter a custom email into the "Recipients" field. To add a custom
-email, just enter the email address and press "Enter".
-6. The "Launch owner" is selected by default. Uncheck "Launch owner" to exclude
-him/her from the notification.
-7. Select the "In Case" setting. To do that, select one of the following options from the "In Case" drop-down.
-8. Select launches (optional). To do that, start typing any symbols into the "Launch names" field.
-You can select an item from the auto-complete tool-tip using the "Up" and "Down" arrows and clicking "Enter" on the keyboard. This is an alternate way you can add a new launch name that does not exist on the project. Several launches names can be selected; the recipients will receive notifications when each of them finishes.
-9. Then Select attributes (optional). To do that, start typing any symbols into the "Attribute key" and "Attribute value" fields. The system will suggest the results in the drop-down, after at least 1 symbol is provided. It is also possible to add a new attribute (that does not exist on the project). Several attributes can be selected at once; the corresponding recipients will receive notifications about the launches that have all the specified attributes.
-10. Switch ON Notifications
-11. The system will activate the "Email notification" option. After the launch is finished, the recipients will receive a notification via email.
-12. Add more rules, if needed. Each Notification rule should be unique.
-13. You can edit/ copy/enable/disable notification rule by clicking on the appropriate controls on the notification rule.  
+:::note
+Users with ADMINISTRATOR role can configure ‘Notifications’ in the Administrate section.<br />
+Users with PROJECT_MANAGER role can edit the settings on the project space only.<br />
+Users with MEMBER/ OPERATOR/ CUSTOMER project role will not have the capability to edit the project settings, however, they do have the permission to view them.
+:::
 
+**Email notifications**
 
-:::note
-Users with a `MEMBER`/ `OPERATOR`/ `CUSTOMER` project role will not have the capability to edit the project settings, however, they do have the permissions to view them.
+:::tip
+For using this functionality be sure that the Email server is configured. For that, go to the Project Settings -> Integrations -> Email Server.
 :::
+
+To create Email notification rule, perform the following steps:
+
+1. Go to the Project settings -> Notifications.
+
+2. Choose Email Notification Group.
+
+3. Click ‘Create Rule’ button.
+
+4. Fill the form:
+
+**Rule name** – from 1 to 55 characters, mandatory field
+
+**Recipients** – optional field
+
+Start typing any symbols into the ‘Recipients’ field. You can select an item from the auto-complete tooltip using the keyboard (use the ‘Up’ and ‘Down’ arrows and ‘Enter’ button). You can also enter a custom email into the ‘Recipients’ field. To add a custom email, just enter the email address and press ‘Enter’.
+
+**Launch owner** – optional checkbox
+
+The ‘Launch owner’ checkbox is selected by default. Uncheck ‘Launch owner’ to exclude him/her from the notification.
+
+**In case** – optional field, dropdown with the options:
+
+* Always – notification will be sent upon the launch finish.
+* 10% of items have issues – notification will be sent, if more than 10% of items have issues.
+* 20% of items have issues – notification will be sent, if more than 20% of items have issues.
+* 50% of items have issues – notification will be sent, if more than 50% of items have issues.
+* Launch has issues – notification will be sent, if at least 1 item has issues
+* Launch has ‘To Investigate’ items – notification will be sent, if at least 1 item has ‘To Investigate’
+
+**Launch names** – optional field
+
+Start typing any symbols into the ‘Launch names’ field. You can select an item from the auto-complete tooltip using the ‘Up’ and ‘Down’ arrows and clicking ‘Enter’ on the keyboard. This is an alternate way you can add a new launch name that does not exist on the project. Several launches names can be selected; the recipients will receive notifications when each of them finishes.
+
+**Attributes** – optional checkbox
+
+When the ‘Attributes’ checkbox is checked, user can provide key/value for attributes and select the necessary radio button:
+
+* All attributes should match
+* Any attribute should match
+
+Start typing any symbols into the ‘Attribute key’ and ‘Attribute value’ fields. The system will suggest the results in the dropdown, after at least 1 symbol is provided. It is also possible to add a new attribute (that does not exist on the project). Several attributes can be selected at once; the corresponding recipients will receive notifications about the launches that have all the specified attributes.
+
+You can edit/ copy/enable/disable notification rule by clicking on the appropriate controls on the notification rule.
+
+5. Click on ‘Create’ button.
+
+<MediaViewer src={require('./img/EmailNotification.png')} alt="Create Email Notification rule" />
+
+**Slack notifications**
+
 :::tip
-For using this functionality be sure that the E-mail server is configured.
+To use this functionality, ensure that the Slack plugin is uploaded and enabled. For that, go to Administrate -> Plugins or contact your instance Administrator.
 :::
+
+To create Slack notification rule, perform the following steps:
+
+1. Go to the Project settings -> Notifications.
+
+2. Choose Slack Notification Group.
+
+3. Click ‘Create Rule’ button.
+
+4. Fill the form:
+
+**Rule name** – from 1 to 55 characters, mandatory field
+
+**Webhook URL** – mandatory field (it is configured on the Slack side)
+
+**In case** – optional field, dropdown with the options:
+
+* Always – notification will be sent upon the launch finish.
+* 10% of items have issues – notification will be sent, if more than 10% of items have issues.
+* 20% of items have issues – notification will be sent, if more than 20% of items have issues.
+* 50% of items have issues – notification will be sent, if more than 50% of items have issues.
+* Launch has issues – notification will be sent, if at least 1 item has issues
+* Launch has ‘To Investigate’ items – notification will be sent, if at least 1 item has ‘To Investigate’
+
+**Launch names** – optional field
+
+Start typing any symbols into the ‘Launch names’ field. You can select an item from the auto-complete tooltip using the ‘Up’ and ‘Down’ arrows and clicking ‘Enter’ on the keyboard. This is an alternate way you can add a new launch name that does not exist on the project. Several launches names can be selected; the recipients will receive notifications when each of them finishes.
+
+**Attributes** – optional checkbox
+
+When the ‘Attributes’ checkbox is checked, user can provide key/value for attributes and select the necessary radio button:
+
+* All attributes should match
+* Any attribute should match
+
+Start typing any symbols into the ‘Attribute key’ and ‘Attribute value’ fields. The system will suggest the results in the dropdown, after at least 1 symbol is provided. It is also possible to add a new attribute (that does not exist on the project). Several attributes can be selected at once; the corresponding recipients will receive notifications about the launches that have all the specified attributes.
+
+You can edit/ copy/enable/disable notification rule by clicking on the appropriate controls on the notification rule.
+
+5. Click on ‘Create’ button.
+
+<MediaViewer src={require('./img/SlackNotification.png')} alt="Create Email Notification rule" />
+
 ### Custom defect types
 
 The "Defect Types" tab allows users with permissions to create custom defect types as subtypes of default defects on the project.

docs/issues-troubleshooting/EmailNotificationIssues.md

@@ -0,0 +1,20 @@
+# Email Notification Issues
+
+In case of observing issues with email notifications when email service stopped processing messages, RP administrators should be aware of some kinds of known issue types:
+
+1. ThreadPoolTaskExecutor capacity is too small for handling large number of queued users to be notified.
+
+**Solution:**<br />
+Update environment variable rp_environment_variable_executor_pool_user-email_queue with bigger value (default: 1000).
+
+2. The number of ThreadPoolTaskExecutor active threads is bigger than the number of simultaneous connections allowed by SMTP server (e.g., 10 maximum connections for gmail). That makes email server consider such heavy load as DDoS attack and refuse to establish new connections.
+
+**Solution:**<br />
+Decrease number of active threads by updating environment variable rp_environment_variable_executor_pool_user-email_max (default: 10)
+
+In order to update environment variables, you should edit your docker-compose.yml file.<br />
+[Job environment variables example for docker](https://github.com/reportportal/reportportal/blob/2b22c61f87674aaf2efc7a973af38004c2517680/docker-compose.yml#L201)
+
+:::note
+In addition, there are daily limits on sending emails from one account. Different email servers have their own restrictions (e.g. 2000 max messages for gmail).
+:::

docs/log-data-in-reportportal/ImportDataToReportPortal.mdx

@@ -5,58 +5,79 @@ sidebar_label: Import data to ReportPortal
 
 # Import data to ReportPortal
 
+## Import via UI
+
 Import functionality gives the opportunity to upload log files via UI.
-To start the import process, you should hit the 'Import' button on the Launch page (All Launches tab). In a new pop-up window **'Import Launch'** you can drop files or add them by adding a link.
+
+To start the import process, you should have at least one import plugin enabled: either JUnit or RobotFramework.
+
+To import launch via UI:
+
+1. Log in to ReportPortal.
+
+2. Go to the Launches page.
+
+3. Click ‘Import’ button.
+
+4. Select appropriate option in the ‘Report Type’ dropdown on the ‘Import launch’ modal window.
+
+5. Click the drag-and-drop area to add .xml or .zip file under 32MB.
+
+6. Click ‘Import’ button and then ‘OK’ button on the ‘Import launch’ modal window.
 
 ReportPortal checks file size and format first. Imported files should meet the following requirements:
+
 * File format is zip archive or XML file.
 * File size is up to 32Mb.
 * Timestamp format is 2022-11-17T10:15:43
 
-If the file format is incorrect, it is marked in red and the reason is shown in the tooltip on hovering over the file in the pop-up window. This is to prevent any incorrect files from being run through the import process.
+If the file format is incorrect, it is marked in red, and the reason is shown in the tooltip on hovering over the file in the pop-up window. This is to prevent any incorrect files from being run through the import process.
+
+If all the files added are correct you may click the 'Import' or 'Cancel' buttons:
 
-If all the files added are correct you may hit the 'Import' or 'Cancel' buttons:
 * The Cancel button closes the pop-up window without any operation under log files.
-* The Import button starts copying files into the RP file storage and disables the 'Import' button.
+* The Import button starts copying files into the RP file storage.
 
 The System will start copying files into the RP file storage if the files meet the following requirements:
-* The File format is a zip archive.
+
+* The File format is a zip archive or XML file.
 * The File size is up to 32Mb.
-* The XML files must have the JUnit structure in the zip archive.
+* The XML files must have the JUnit or RobotFramework structure in the zip archive and in XML files depend on Report Type you have chosen.
 
-The system copies valid XML files into RP file storage and marked them in green in the Import pop-up window.
+The system copies valid XML files into RP file storage and marked them in green in the ‘Import launches’ pop-up window.
 
 If files from the zip archive have formats other than XML, the system will skip them.
 
-If the XML file is not in the JUnit structure, the system will interrupt the process of copying and mark the file in red. The reason is then shown on the tooltip when hovering the file in the pop-up window.
+If the XML file is not in the correct structure (depend on Report Type – JUnit or RobotFramework), the system will interrupt the process of copying and mark the file in red. The reason is then shown on the tooltip when hovering the file in the pop-up window.
 
 :::note
-Files that were copied earlier stay in the RP file storage
+Files that were copied earlier stay in the RP file storage.
 :::
-When all of the valid log files are downloaded and processed the 'OK' button is enabled. The 'OK' button closes the Import launches pop-up window. The Zip archive is then deleted after the Import is finished or canceled.
 
-<MediaViewer src="https://youtu.be/238DO03guaA" alt="Import data to our test automation reporting platform" type="video" />
+When all valid log files are downloaded and processed, the 'OK' button is enabled. The 'OK' button closes the ‘Import launches’ pop-up window.
+
+<MediaViewer src="https://youtu.be/AQ4wZgKMNt4" alt="Import via UI on our test automation reporting dashboard" type="video" />
 
-You can only interrupt the import in UI when files are being downloaded into the RP file storage. In this case, you should hit the 'Cancel' button (or X button in the pop-up window) and confirm the cancellation of import and then hit the 'Cancel' button again.
+You can only interrupt the import in UI when files are being downloaded into the RP file storage. In this case, you should click the 'Cancel' button (or X button in the pop-up window) and confirm the cancellation of import and then click the 'Cancel' button again.
 
-<MediaViewer src="https://youtu.be/Qf_vY0J7xGA" alt="Import Break" type="video" />
+<MediaViewer src="https://youtu.be/wv_zGn2SfuI" alt="Import via UI. Cancel button" type="video" />
 
 ## Import via API
 
-The details about import via API you can find on the ReportPortal menu at the bottom: API -> launch controller -> Import junit xml report
+The details about import via API you can find on the ReportPortal menu at the bottom: API -> Plugin Controller -> Send report to the specified plugin for importing
 
-<MediaViewer src={require('./img/ImportJunitXMLReport.png')} alt="Import junit xml report in our qa automation dashboard" />
+<MediaViewer src={require('./img/ImportViaAPI.png')} alt="Import via API in our qa automation dashboard" />
 
 You can configure parameters (name, description, attributes) for the imported launch by specifying these values in your API request.
 
-The endpoint **POST /v1/&#123;projectName}/launch/import** allows importing a launch into the specified project using an XML or ZIP file in JUnit format.
+The endpoint ```POST /v1/plugin/{projectName}/{pluginName}/import``` allows importing a launch into the specified project using an XML or ZIP file.
 
 **Permissions:** Admin, PM, Member, Customer, Operator.
 
 Here's an example of a request to the endpoint:
 
 ```yaml
-curl -L -X POST 'http://localhost:8080/api/v1/superadmin_personal/launch/import' \
+curl -L -X POST 'http://localhost:8080/api/v1/plugin/superadmin_personal/junit/import' \
 -H 'Content-Type: multipart/form-data' \
 -H 'Authorization: Bearer {token}' \
 -F 'file=@"file_path.zip";type=application/x-zip-compressed' \
@@ -77,14 +98,24 @@ curl -L -X POST 'http://localhost:8080/api/v1/superadmin_personal/launch/import'
 
 **Query parameters:**
 
+**pluginName** – mandatory field to specify import plugin
+
+**projectName** – mandatory field to specify project name
+
+**file** – mandatory area to upload file for import
+
 **launchImportRq** is application/json part of the request where you can specify needed custom information about launch.
 
 **attributes** – array of attributes
 
 **description** – custom launch description
 
+**name** – custom launch name
+
 **startTime** – if launch start time needed, or will be used first time in imported report
 
+<MediaViewer src={require('./img/parameters.png')} alt="Query parameters for API import" />
+
 If the array of attributes contains the next "skippedIsNotIssue" attribute marked as system, then all test items with SKIPPED status will be processed without applying a "To Investigate" defect type.
 
 ```yaml
@@ -99,11 +130,10 @@ If the array of attributes contains the next "skippedIsNotIssue" attribute marke
 
 When set to "false", test items with SKIPPED status will be processed and marked with the defect type "To Investigate". If the parameter is not set, the default behavior is equivalent to "false".
 
-
 **Scenario 1** (Test items with SKIPPED status have "To Investigate" status):
 
 ```yaml
-curl -L -X POST 'http://localhost:8080/api/v1/superadmin_personal/launch/import' \
+curl -L -X POST 'http://localhost:8080/api/v1/plugin/superadmin_personal/junit/import' \
 -H 'Content-Type: multipart/form-data' \
 -H 'Authorization: Bearer {token}' \
 -F '[email protected];type=application/x-zip-compressed' \
@@ -117,7 +147,7 @@ curl -L -X POST 'http://localhost:8080/api/v1/superadmin_personal/launch/import'
 **Scenario 2** (Test items with SKIPPED status don't have "To Investigate" status)
 
 ```yaml
-curl -L -X POST 'http://localhost:8080/api/v1/superadmin_personal/launch/import' \
+curl -L -X POST 'http://localhost:8080/api/v1/plugin/superadmin_personal/junit/import' \
 -H 'Content-Type: multipart/form-data' \
 -H 'Authorization: Bearer {token}' \
 -F '[email protected];type=application/x-zip-compressed' \
@@ -135,4 +165,4 @@ curl -L -X POST 'http://localhost:8080/api/v1/superadmin_personal/launch/import'
 }";type=application/json'
 ```
 
-<MediaViewer src="https://youtu.be/rjsftLtEcpc" alt="Import via API on our test automation results dashboard" type="video" />
+<MediaViewer src="https://youtu.be/nSnhm31-8iE" alt="Import via API on our test automation results dashboard" type="video" />