Accessing Reports Programmatically

Many of the reports within SOLO Server can be accessed programmatically through standard HTTP GET or POST requests in order to allow integration with custom reporting tools.

The following list outlines which reports are accessible through this mechanism and the required User permissions:

Report Type	Supported Reports	Required User Permission
Licenses	All Reports except Licenses by Distributor	Report Access
Auditing Exports	All Reports	Authors: Master User ID Licenses: (see Auditing Exports) Products, Product Options: View Products Users: Manager Users
Trial Tracking	All Reports	Report Access
Uncompleted Store Orders	No Reports currently supported
Accounting	No Reports currently supported
Account Statements	All Reports	Accounting Reports
Customers	All Reports	Report Access
Store Sales	All Reports except Sales with Invoice Details and Unit Compare By Distributor Type	Sales Reports Access or Financial Access

Report Integration

To integrate your internal reporting application with SOLO Server, you simply need to call the appropriate SOLO Server reporting URL using either an HTTP GET or POST request containing authentication parameters along with report input parameters such as the report type and start and end date. SOLO Server will reply with a response which the calling application can then process accordingly.

Common Input Parameters

Parameter	Data Type	Required/Optional	Description
WebServiceLogin	boolean	Required	Must be set to "True". This parameter flags the request as a "web service" request, and instructs the request to be authenticated through the following three parameters rather than through session cookies.
AuthorID	int	Required	SOLO Server Author ID.
UserID	string	Required	The API User ID of the user from the given author using the service (previously the regular User ID). The API User ID and Password need to be used, as support for the regular User ID and Password will be removed in the future.
UserPassword	string	Required	The API User Password for API User ID (previously the regular User Password for the User ID). The API User ID and Password need to be used, as support for the regular User ID and Password will be removed in the future.
ReportType	string	Required	The format to generate the report in. This can be one of the following values: Pdf - Adobe Acrobat Xls - Microsoft Excel Csv - Comma Separated Value XmlElements - XML document with separate elements for each field in each record XmlParameters - XML document with a single element containing an attribute for each field for each record Note that some reports do not support all report types. You can reference the topic on each specific report to see the supported report types for each.
StartDate	date	Required	Start date of the report date range. This should be in MM/dd/yyyy format.
EndDate	date	Required	End date of the report date range. This should be in MM/dd/yyyy format.

Report Specific Parameters

In addition to the common input parameters, each report has it's own set of additional reporting parameters specific to the given report. You can determine the additional parameters for each report by examining the HTML source of the report form as follows:

• Log in to SOLO Server and navigate to the report in question.
• An HTML form is displayed containing all of the available parameters, with the common Report Type, Start Date, and End Date parameters noted above at the top.
• The remaining form fields are specific to the given report, and the form field names match the parameter names which must be passed when calling the report programmatically.
• Examine the HTML source of the page to extract the name property of each of the form fields. Alternately, if using Firefox or Chrome, install the Web Developer Toolbar. With this installed, from the Web Developer menu, simply choose Forms, View Form Information, which will open a new tab listing out the form details, including form field names.
• Note the following when accessing the reports programmatically:
  • The Save To Disk field does not apply.
  • Checkbox fields use values of "True" or "False".
  • For any drop down fields, the passed in value must match one of the values in the list. You must view the source and extract the "value" property of for the given list item rather than the text displayed in the list on the web page.
  • Fields not marked as required can be omitted.
  • In most cases, the field names will match the labels on the report page with spaces removed, but this is not always the case. In the case of certain drop down options, such as for choosing a product, the name will often include "ID" appended to the end.

Example - Licenses By Product Report

As a example, consider retrieving the output of the Licenses By Product Report in Excel format for the month of January 2012 for licenses with OK status, using a Status Check Days Back setting of 30 days and sorting by entered date. The URL and querystring or form data is put together as follows:

• Report URL - https://secure.yourdomain.com/[PathToSOLO]/authors/RptLicensesByProduct.aspx
  • secure.yourdomain.com is replaced with the SOLO Server domain
  • [PathToSOLO] replaced with the path to the SOLO Server root.
  • In the case of SOLO Server Shared URL, this would be: https://secure.softwarekey.com/solo/authors/RptLicensesByProduct.aspx
• ReportType - Xls
• StartDate - 1/1/2012
• EndDate - 1/31/2012
• ProductID - This can be omitted since we are not filtering on a specific product. Note that the form field name is "ProductID" rather than "Product" as noted in the prior section.
• FilterIssueLicense - This can be omitted as since we are not filtering on this field.
• FilterUnregistered - This can be omitted as well since we are not filtering on this field.
• FilterOKStatus - True
• StatusCheckDaysBack - 30
• SortBy - 1. Note that this value matches the corresponding "value" attribute from the HTML form and not the displayed text as noted in the prior section.

So, given this information, and assuming we are using AuthorID 123456 along a UserID of "Reporting" with a password of "testing", the querystring or form data to post would come together to the following (prior to HTML encoding):

Querystring/Post Data

WebServiceLogin=True&AuthorID=123456&UserID=Reporting&UserPassword=testing&ReportType=Xls &StartDate=1/1/2012&EndDate=1/31/2012&FilterOKStatus=True&StatusCheckDaysBack=30&SortBy=1

Report Output

If all input parameters to the report are valid, SOLO Server will return the report file as an attachment to the caller in the selected file format. If, however, there are any invalid or missing input parameters, SOLO Server will instead return an xml response to the caller with details on why the request failed. The xml response document is in the following format.

XML

<RequestError>

<ErrorType></ErrorType>
<InvalidParameters>

<InvalidParameter>

<Name></Name>
<Value></Value>
<Reason></Reason>

</InvalidParameter>

</InvalidParameters>

</RequestError>

The value of these elements is as follows:

Parameter	Data Type	Description
ErrorType	string	The type of error which occurred. Can be one of the following values: AuthenticationFailure - Authentication of the AuthorID/UserID/UserPassword combination failed. AccessDenied - The UserID does not have the appropriate permission to access the report. InvalidParameters - One of more of the input parameters is missing or invalid. For this error type, the InvalidParameters element described below is also included in the document, and will contain an InvalidParameter element for each missing/invalid parameter describing why the parameter is invalid.
InvalidParameters	XML child element	This is a container element holding one or more InvalidParameter child elements, each containing details on why the given parameter is invalid.
Name	string	The name of the invalid/missing parameter.
Value	string	The value passed for the invalid parameter.
Reason	string	A string description of why the parameter is invalid.

Sample Code

For sample code demonstrating this functionality, contact us.