Custom Report Instructions

CloudBlue Connect allows creating reports based on your custom templates. Such templates should be created by following the Connect Reports SDK guidelines. It is required to upload custom templates to a Git repository and assign a specific release tag. Thereafter, your repository can be linked with the system via the Reports section of the Account module.

The following showcases how to prepare your template files and provides step-by-step instructions on how to prepare your Git repository, how to add your Git repository to Connect, and how to successfully generate a report by using a custom template.

Preparing Template Files

Follow the Connect Reports SDK guidelines to successfully create your custom report template. Namely, prepare your report template by following the provided steps:

1. First, report template files should be generated by using the provided Cookiecutter framework.
2. Your report.json file should contain required report template parameters. Refer to the Report Parameters table for more details.
3. The entrypoint.py file should contain your report generate code. Use the RQL client or string concatenation to successfully prepare your entrypoint file.
4. When all required data is presented, you can generate your report template by executing the corresponding command via Connect CLI.

Therefore, in case your report template is generated successfully, you can upload your report template files to your Git repository. Note that in order to use your custom templates on the Connect platform, your repository should have a version tag. Prepare your Git repository as described below.

Preparing Repository

Before adding your Git repository to Connect and starting to use your custom template within the system, it is required to make sure that your repository includes at least one version tag. Otherwise, your repository will not be added to the system. The following steps demonstrate how to create a new release and prepare your repository on GitHub:

1. Click Create a new release from your repository with a custom template.
2. Use the following form to define your release:
   • Select Tag: It is recommended to use a version tag with the v prefix (e.g., v1.0.0 or v0.2.3)
   • Release title: Enter any title for your release.
   • Description: Provide description for your new release.
3. Publish your release by using the corresponding button on the interface.

Thus, a new version tag of your custom template will be created and your repository will be successfully configured for the following operations. In case more information on managing your releases is required, please refer to the GitHub documentation.

Adding Repository

Once your Git repository includes at least one release with your custom templates and a version tag, it is possible to add this repository to the Connect platform. Navigate through the Accounts module on Connect and access the Reports section that provides available templates and repositories. Switch to the Repositories tab and click Add Repository to launch a wizard.

Follow the wizard steps to add your Git repository to the system:

1. Provide your repository link to the Git Repository URL input field. In case your repository requires authorization, check the Requires Authorization checkbox to specify your username and password.
2. Select a version tag in the following form. If the system does not provide any tags, make sure that your repository includes a version tag as described above.
3. Click the Add button to finalize your repository configuration on Connect.

Therefore, the system starts adding your Git repository. Note that the system provides a status of your repository. Once the status of your repository object is switched to Ready, the system will successfully add your custom templates and will allow generating reports by using these templates. In case of an error, the system provides an error description within your repository details and conversation box.

Generating Custom Reports

When your custom reports are successfully uploaded to Connect, the system allows generating reports by using the reports creation wizard in the Reports module. Note that the number of wizard steps vary depending on your created template.

The following showcases how to create a new Connect report based on a custom template:

1. Launch the aforementioned wizard by clicking the Create Report button from the Reports module.
2. Select your custom template on the first wizard step. Use the the search input to locate your uploaded template faster.
3. Next, the wizard provides your created overview and your defined configuration options on the following steps. Keep providing configuration specifications as it is required for your report.
4. Once all of your custom report template options are specified, the wizard asks to select an output for your report. It is possible to generate a report in XLSX, JSON, or CSV format.
5. When the wizard asks to specify your report details, it is required to provide a name for your report object on Connect. It is also possible to specify your report description if necessary.
6. Finalize your report creation by clicking the Create button.

As a result, the system generates a new custom report object and assigns the Pending status to this object. Once the status of your report object will be switched to Ready, the system allows downloading the report file by clicking on your file from the Reports data grid and by using the Download button from the Report details screen.

Note that the system also allows using your custom templates to configure schedules for your reports creation. Refer to Reports Interface documentation for more details.