Skip to main content

Secure Downloading of WebMIS Reports

Updated

Table of Contents

  1. Overview
  2. Steps to securely download a report
    1. Obtain the list of reports
    2. Acquire an Access ID
    3. Download the report
  3. Example Code

 

Overview

This article covers how to download a WebMIS report via SOAP using the secure method which will be enforced from the dates noted below. Please note that any integrations that utilize the existing method of downloading reports will need to update by these dates to ensure they are not impacted.

Platform Enforcement Date
Staging TBD
Production TBD



Steps to download a report

Downloading a report from WebMIS via SOAP using the secure method now requires the following actions:

  • Log in to WebMIS (not covered in this article)
  • Obtain the GUID of the desired report
  • Acquire an Access ID for that report
  • Initiate the download, including the acquired Access ID in the request

 

Obtain the list of reports

Call the following SOAP method:

Class Method Return Type
WebServiceOfflineQuery GetOfflineQueries OfflineQuery[]

 

This will return all reports for the logged in user. The OfflineQuery type has the following properties that are relevant to downloading reports (note this is not an exhaustive list) :

Property Type Description
Guid GUID The unique identifier for the given report. This is required to acquire an Access ID (see below) and to download the report.
Name String

The name of the report.

This is no longer required to download the report, but may be useful once the file has been acquired.
ZipFileSize Int64

The size of the file in bytes.

This is no longer required to download the report, but may be useful once the file has been acquired.

Note the ZipLocation property of OfflineQuery should no longer be used to download reports. Please follow the process outlined below.

 

Acquire an Access ID

Call the following SOAP method, passing up the GUID of the report you wish to download:

Class Method Return Type
WebServiceUserAccessId GenerateDownloadReportAccessId AccessId
Argument Type Description
ReportGuid GUID Required. The GUID of the report to be downloaded.

 

If the ReportGuid argument provided is valid, this method will return an AccessId object, which has the properties detailed below. Otherwise, it will return null .

Property Type Description
Purpose String Indicates what this ID can be used to do. The ID is only valid for the indicated purpose.
ExpiresUtc DateTime

The UTC date/time after which this ID will not be valid.

Access IDs used for downloading reports are valid for 30 seconds after their creation.
ItemGuid GUID or null

If present, the GUID of the item to which this ID applies. The ID is only valid for use against this item for the specified purpose.

In this case, ItemGuid will be the GUID of the report to be downloaded.
Value String The value of the ID, to be passed up to the server when the desired action is taken.

 

The Value property returned is what will be used when downloading the report. The other properties are for informational purposes only. Knowledge of the Access ID’s Value allows a report to be downloaded. Therefore it should not be shared and should be considered confidential to the user that generated it.

 

Download the report

To download the report, send a GET request to https://soap.cardeasexml.com/GetReport?guid={guid}&type={type} with WebMIS-Report-Access-ID: {accessIdValue} included in the header of the request, where {accessIdValue} is the Value property of the Access ID acquired in step 2 and the values of the parameters in the URL are as follows:

Parameter Value
{guid} The GUID of the report.
{type} The file type of the report (e.g. xlsx or zip).

 

Example Code

C#

var downloadValues = new string[][]
{
    new string[] { "ReportGuid", offlineReport.Guid.toString()},
};

AccessId accessId = Program.client.CallNameValue("WebServiceUserAccessId", "GenerateDownloadReportAccessId", downloadValues) as AccessId;
var url = $"https://testsoap.cardeasexml.com/GetReport?guid={offlineReport.Guid}&type=zip";
try
{
    var httpClientHandler = new HttpClientHandler {
        Credentials = new NetworkCredential("NETWORK_CREDETIAL_USERNAME", "NETWORK_CREDENTIAL_PASSWORD");
    };

    using (HttpClient httpClient = new HttpClient(httpClientHandler))
    {
        httpClient.DefaultRequestHeaders.Add("WebMIS-Report-Access-ID", accessId.Value);
        Task.Run(async () =>
        {
            var response = await httpClient.GetAsync(url);

            if (response.IsSuccessStatusCode)
            {
                byte[] content = await response.Content.ReadAsByteArrayAsync();
                // Write to file / handle content as required
            }
        }).Wait();
    }
}
catch (Exception e)
{
    // Exception
}