Corprio.AspNetCore.XtraReportSite 2.0.31.125

Corprio.AspNetCore.XtraReportSite

What is Corprio.AspNetCore.XtraReportSite for?

The Corprio.AspNetCore.XtraReportSite is the base library for develpers to build a web applicaiton working with Corprio using ASP.NET Core and need to execute reports in the web application. If your application does not need to execute reports, then you can use Corprio.AspNetCore.Site instead.

Technology

The application is developed using ASP.NET Core 8, DevExtreme and XtraReports.

To start

Follow the steps below to start building your web applicaiton with Corprio.

Prepare the development environment

Download and install the latest version of Visual Studio from Microsoft. You will need to select components for building ASP.NET Core applications.

Clone Corprio.Internal solution

Your web application needs to work the Corprio API. Instead of directly calling the online API, you can clone the Corprio.Internal repository onto your development machine so that you can have the Corprio API server running in your development machine.

Start new web application

1. Launch Visual Studio
2. Create a new project
3. Select the ASP.NET Core Web App (Model-View-Controller) template using C#
4. Right click on the project and select Manage NuGet Packages
5. Search for Corprio.AspNetCore.XtraReportSite and install the package
6. Create a class to get data for your reports running in this application. For example

/// <summary>
/// Service for getting data for reports
/// </summary>
public class ReportDataService : BaseReportDataService
{
        /// <summary>
        /// Constructor
        /// </summary>
        /// <param name="httpContextAccessor">HttpContextAccessor for getting organization ID from HttpContext</param>
        /// <param name="corprio">Corprio client for getting data from server</param>
        public ReportDataService(IHttpContextAccessor httpContextAccessor, APIClient corprio, IHttpClientFactory httpClientFactory) : base(httpContextAccessor, corprio, httpClientFactory)
        {
        }

        public override IEnumerable<Type> GetAvailableTypes(string context)
        {
            return new Type[] {
                //put the data types of your report data here, e.g. MySalesReportData
                };
        }

        public override System.Collections.IEnumerable GetReportData(Type dataType, Guid organizationID, Dictionary<string, object> parameters)
        {
            //add code to return data for each of your report data type 
            throw new NotSupportedException($"DataType {dataType} is not supported");
        }

        public override IEnumerable<Corprio.DataModel.Report.Parameter> GetParametersOfDataType(Type reportDataType, string[] supportedLanguages)
        {
            //add code to return an array of Parameter for prompting users before executing the report
            return Array.Empty<Corprio.DataModel.Report.Parameter>();
        }
}

7. Edit the Startup.cs and modify ConfigureServices as

public void ConfigureServices(IServiceCollection services)
{
	services.AddCommonAppServices(Configuration);
	services.AddXtraReports<ReportDataService>();
}

8. Edit appsettings.Development.json to include the following sections

  "CorprioApiSetting": {
    "AuthServerUrl": "https://localhost:44334", //replace with the port of your local AuthServer project
    "ApiUrl": "https://localhost:44394", //replace with the port of your local Corprio API project
    "ApiVersion": "1.0"
  },
  "CorprioClientCredential": {
    "ClientID": "your app ID", //replace with the ID of your application which will be used to register your application in Corprio Portal
    "ClientSecret": "xxxxxxxxxxxxxxxxxxx" //replace with the secret of your application
  },

Adding new report

Define report data type

1. Create a class of the data type of your report data. For example

public class MySalesReportData
{
	public string ProductName { get; set; }
	public int QuantitySold { get; set; }
	public decimal TotalSales { get; set; }
}

Save the class in the folder /Models/ReportData

Modify ReportDataService class to return the report data

1. In the GetAvailableTypes method, add the data type of your report data

public override IEnumerable<Type> GetAvailableTypes(string context)
{
	return new Type[] {
		typeof(MySalesReportData) //add your report data type here
	};
}

1. In the GetReportData method, add code to return the data for your report data type

public override System.Collections.IEnumerable GetReportData(Type dataType, Guid organizationID, Dictionary<string, object> parameters)
{
	if (dataType == typeof(MySalesReportData))
	{
		//add code to return the data for MySalesReportData
		return GetDataFromAPI((int pageIndex) =>
                corprio.InvoiceApi.QueryLines<MySalesReportData>(
                    organizationID: organizationID,
                    dynamicQuery: new DynamicQuery
                    {
                        Selector = "new (Product.Name as ProductName,Qty as QuantitySold,LineAmount*np(Invoice.ExchangeRate,1) as TotalSales)",
                        Where = "Invoice.InvoiceDate>=@0 && Invoice.InvoiceDate<@1 && Invoice.IsVoided==false",
                        WhereArguments = new object[] { dateRange.Start, dateRange.End },
                        GroupBy = "",
                        Skip = BatchRecordSize * pageIndex,
                        Take = BatchRecordSize
                    }
                    )).GetAwaiter().GetResult();
	}
	throw new NotSupportedException($"DataType {dataType} is not supported");
}

2. If the report data needs parameters, then implement the GetParametersOfDataType method to return an array of Corprio.DataModel.Report.Parameter for new reports when users are creating custom reports in web designer using this report data type.

public override IEnumerable<Corprio.DataModel.Report.Parameter> GetParametersOfDataType(Type reportDataType, string[] supportedLanguages)
{
	if (reportDataType == typeof(MySalesReportData))
	{
		return new Corprio.DataModel.Report.Parameter[]
		{
			new Corprio.DataModel.Report.Parameter
			{
                Hidden = false,
				Name = "dateRange",
				Type = Corprio.DataModel.Report.ParameterType.DateRange,
				Prompt= new Global.Globalization.GlobalizedText(
                   resourceType: typeof(DataModel.Resources.Resource),
                   key: "DateRange",
                   langCodes: supportedLanguages),
                Required = true
			}
		};
	}
	return Array.Empty<Corprio.DataModel.Report.Parameter>();
}

Create the report

1. Create a new XtraReport in the folder /Reports
2. In the Properties of the report, click the dropdown of Data > DataSource
3. Select Add DataSource and select Object in Select a data connection type. Then click Next.
4. Select the assembly containing MySalesReportData in the Select an assembly containing the class type definition of a data source and then click Next.
5. In Select a data source type, select MySalesReportData and then click Next. If you cannot find the data type, then restart Visual Studio.
6. Select Do not select a member, bind to the entire object. and then click Next.
7. In Select the data binding mode, select Retrieve the data source schema and then click Finish.
8. Drag and drop Report Controls to the report from the Toolbox to design your report.
9. Developers can add the following report parameters in the report and they are populated autotmatically:
   • organizationName: the name of the organization to run the report
   • organizationLogoUrl: the url of the logo of the organization
   • organizationPhone: the phone number of the organization
   • organizationAddress: the address of the organization

Register the report

Developers must register the report in their applications so that the report can be executed in the web application. follow the steps below to register the report.

1. Login the Corprio Portal site using the developer login
2. Click on the user icon and select Developer Portal
3. Select Applications and find the application which runs the report. In the action menu, select Reports.
4. Click Download report definition file template file and then edit the file using a text/json editor. Make sure the ReportName field is filled with the class name of the XtraReport, e.g. MyApplication.Reports.MySalesReport
5. Upload the report definition file to the Reports section of the application in the Corprio Portal to add the report definition.
6. Click the down arrow to expand the report definition.
7. Click Push to subscribers to push the report definition to all subscribers of the application.

Run a report

1. After pusing the report definition to subscribers, they can run the report in the web application in the action /Report/Index

Run a report from code

You can run a report from code. For example, to print an invoice from an invoice record.

1. Create a new controller and inherits from Corprio.AspNetCore.XtraReportSite.Controllers.BaseController
2. Create a new action method to run the report

[HttpGet]
 public async Task<IActionResult> Print([FromServices] ApplicationSettingService applicationSettingService,
    [FromServices] IReportStorageService reportStorageService,
    [FromRoute] Guid organizationID,
    [FromRoute] Guid invoiceID)
{
    //get definition of the report
    string reportID = "InvoicePrintout";
    ReportDefinition reportDefinition = await reportStorageService.GetReportDefinition(organizationID, reportID);
    if (reportDefinition == null) return BadRequest($"Report {reportID} does not exist");
    //call ExecuteReport action of the base controller to execute the report
    return ExecuteReport(new ReportRequest
            {
                ReportID = reportID,
                OrganizationID = organizationID,
                Parameters = new Dictionary<string, object>() { ["invoiceID"] = invoiceID }
            });
}

What happens under the hood

When the report is executed, the following steps are performed:

1. The ExecuteReport action of the BaseController is called with a ReportRequest parameter. The ReportRequest contains
   1. the report ID (which is the ID of the report to run),
   2. organization ID and
   3. parameters for running the report.
2. Redirect the request to the action ViewerRedirect of the Report controller with the ReportQuest as a query string parameter.

return RedirectToAction("ViewerRedirect", "Report", new { OrganizationID, request = reportRequest.ToUrl() });

1. The ViewerRedirect action displays the Viewer view of the Report controller with the report request as the vieew model.
2. The javascript in Viewer view executes the OpenReport function of WebDocumentViewer widget.
3. The WebDocumentViewer widget uses CustomWebDocumentViewerReportResolver (which implements the IWebDocumentViewerReportResolver interface) to resolve the report to run by parsing the ReportRequest url.
4. If the report request can be parsed, then calls the ReportHelper.PrepareXtraReport method to prepare the XtraReport to run.
5. The PrepareXtraReport method calls the GetXtraReport method of IReportStorageService to creaet an instance of the XtraReport.
6. Then assign parameter values from the report request to the parameters of the XtraReport.
7. Then assign values to the object datasource(s) of the XtraReport.
8. For each object datasource, the GetReportData method of the ReportDataService is called to get the data for the report.