API usage

The API is provided through an HTTP REST web service with custom HTTP authentication (which means that simply a pair of username and password needs to be provided in the HTTP header in order to perform authentication). The URL to which the web service listens is http://<servername>:<port>/MailAndDeploy/Api.

The web service supports both POST and GET requests. POST requests need to supply their parameters in the HTTP message, GET requests may supply their parameters through URL parameters. For every request, the API will return an XML document that contains the requested data or, if unsuccessful, an error message.


GET Requests 

As previously stated, GET requests need to supply their parameters by using query string parameters. An example for a GET request might be:

http://<servername>:<port>/MailAndDeploy/Api/?RequestType=CreateReportDocument&RepositoryN ame=CrmReporting&ReportName=CustomerReport&FileType=AdobePdfDocument&Parameter_Custo merId=1

This would instruct Mail & Deploy to process a CreateReportDocument request (see Create Report Document Request) by creating a report document from the Report CustomerReport in repository CrmReporting. The file type in which to create the report document is AdobePdfDocument and the ID of the customer for which to create that report is 1.


POST Requests 

As previously stated, POST requests need to supply their parameters as part of the message header. POST requests need to be submitted to the URL http://<servername>:<port>/MailAndDeploy/Api.


Responses 

Every request will be answered by Mail & Deploy API with an XML document.


Success Responses

If the request can be handled successfully by Mail & Deploy, an XML document that contains the return value for that request will be returned; the actual content of that XML document depends on the type of request; therefore, you will find detailed information about how success responses look like in the documentation of each individual request below.


Exception Responses 

The XML document that will be returned in case the request fails is formatted as follows:

<?xml version="1.0" encoding="utf-8"?>
<MailAndDeployApiResponse Success="False"
ExceptionMessage="{exception_message}" 
ExceptionStackTrace="{exception_stacktrace}" />

The following properties are contained in the response:

SuccessThe value False indicates that the request has failed.
ExceptionMessageAn exception message that contains information about why the request has failed.
ExceptionStackTrace Contains information about the stack trace of the exception.

 
Reference 

This reference provides information on all request types that can be made through Mail & Deploy API.

Create Report Document Request 

This request instructs Mail & Deploy to create a report document from a report with a given file type and optionally parameters. The parameters for this request are:

RequestType This parameter specifies the type of request and needs to be set to CreateReportDocument.
RepositoryNameThe name of the repository (see Repository) to which the report from which you want to create a report document belongs.
ReportName The name of the report (see Reports) from which you want to create a report document.
File Type

The file type in which you want to create the report document. The range of available file types depends on the report type ( see Report Types). 

The following values can be provided:

  • AdobePdfDocument. This file type represents an Adobe PDF Document.
  • AdobePdfADocument. This file type represents an Adobe PDF/A compliant document.
  • HtmlDocument. This file type represents an HTML document.
  • MicrosoftExcelWorkbook. This file type represents a Microsoft Excel Workbook.
  • MicrosoftPowerPointPresentation. This file type represents a Microsoft PowerPoint Presentation.
  • MicrosoftWordDocument. This file type represents a Microsoft Word Document
Parameter_*You can supply values for report parameters (see Report Parameters) if the report from which you want to create a report document supports them. Each report parameter needs to be called Parameter_<name_of_report_parameter>.

Example
The following URL can be used as a GET request to request a report document from a report named CustomerReport that is contained in a repository named CRMReports. The file type in which the report document shall be created is an Adobe PDF Document. The report contains three report parameters (see Report Parameters): CustomerId which represents the ID of the customer for which to create the report document, Year which defines the year for which the report document shall contain data and Month that defines the month for which the report document shall contain data:

http://<servername>:<port>/MailAndDeploy/Api/?RequestType=CreateReportDocument&RepositoryN ame=CRMReports&ReportName=CustomerReport&FileType=AdobePdfDocument&Parameter_Custome rId=1&Parameter_Year=2017&Parameter_Month=1

Success Response 
The XML document that will be returned in case the request completes successfully is formatted as follows:

<?xml version="1.0" encoding="utf-8"?> 
<MailAndDeployApiResponse Success="True" 
FileType="{file_type}" 
ReportDocumentContent="{base64_content}" />

The following properties are contained in the response:

Success
The value True indicates that the request has completed successfully.
File Type
This indicates the file type of the returned report document. It can be one of the following values:
  • AdobePdfDocument. This file type represents an Adobe PDF Document.
  • AdobePdfADocument. This file type represents an Adobe PDF/A compliant document.
  • HtmlDocument. This file type represents an HTML document.
  • MicrosoftExcelWorkbook. This file type represents a Microsoft Excel Workbook.
  • MicrosoftPowerPointPresentation. This file type represents a Microsoft PowerPoint Workbook.
  • MicrosoftWordDocument. This file type represents a Microsoft Word Document.
ReportDocumentContentThis is the content of the report document. It is a byte array encoded as Base64; if this Base64-String is decoded and the resulting byte array is written to a file with the correct file type (see above) the file can be opened with the associated application (e.g. Adobe PDF Reader for Adobe PDF Documents).


Execute Task Request

his request instructs Mail & Deploy to execute a task (see Tasks) of the given repository. The parameters for this request are:

RequestType This parameter specifies the type of request and needs to be set to ExecuteTask.
RepositoryNameThe name of the repository (see Repository) to which the task to execute belongs.
TaskName The name of the task (see Tasks) you want to execute.
Parameter_*You can supply values for task parameters (see Task Parameters) if the task you want to execute supports them. Each task parameter needs to be called Parameter_<name_of_task_parameter>.

Example 
The following URL can be used as a GET request to request the execution of the task named CreateStoreReports that is contained in a repository named CRMReports. The task contains three task parameters (see Task Parameters): StoreId which represents the IDs of the stores for which to execute the task, Year which defines the year for which to execute the task and Month that defines the month for which to execute the task:

http://<servername>:<port>/MailAndDeploy/Api/?RequestType=ExecuteTask&RepositoryName=CRMR eports&TaskName=CreateStoreReports &Parameter_StoreId=1|2|3&Parameter_Year=2017&Parameter_Month=1 


Success Response 
The XML document that will be returned in case the request completes successfully is formatted as follows:

<?xml version="1.0" encoding="utf-8"?>
 <MailAndDeployApiResponse Success="True" />

The following properties are contained in the response:

SuccessThe value True indicates that the request has completed successfully.


Get Available Reports Request 

This request instructs Mail & Deploy to return all available reports (see Reports) of the given repository. The parameters for this request are:

RequestType This parameter specifies the type of request and needs to be set to GetAvailableReports.
RepositoryNameThe name of the repository (see Repository) for which to return all available reports.

Example
The following URL can be used as a GET request to request all available reports of a repository named CRMReports:

http://<servername>:<port>/MailAndDeploy/Api/?RequestType=GetAvailableReports&RepositoryNam e=CRMReports 


Success Response 
The XML document that will be returned in case the request completes successfully is formatted as follows:

<?xml version="1.0" encoding="utf-8"?> 
<MailAndDeployApiResponse Success="True"> 
<Report Name="{report_name}" 
Description="{report_description}">
 <SupportedFileType Value="{supported_file_type}" /> 
... 
<ReportParameter Name="{reportparameter_name}" 
Caption="{reportparameter_caption}" />
 ... 
</Report> 
... 
</MailAndDeployApiResponse>

The following properties are contained in the response:

Success
The value True indicates that the request has completed successfully.
ReportNameThe name of the report.
Report DescriptionThe description of the report.
Supported File Types A list of file types supported by that report (i.e. report documents can be created in any of these supported file types). The following values are possible:
  • AdobePdfDocument. This file type represents an Adobe PDF Document.
  • AdobePdfADocument. This file type represents an Adobe PDF/A compliant document.
  • HtmlDocument. This file type represents an HTML document.
  • MicrosoftExcelWorkbook. This file type represents a Microsoft Excel Workbook.
  • MicrosoftPowerPointPresentation. This file type represents a Microsoft PowerPoint Workbook.
  • MicrosoftWordDocument. This file type represents a Microsoft Word Document.
Report ParametersA list of zero or more report parameters (see Report Parameters) of that report.


Get Available Tasks Request 

This request instructs Mail & Deploy to return all available tasks (see Tasks) of the given repository. The parameters for this request are:

RequestType This parameter specifies the type of request and needs to be set to GetAvailableTasks.
RepositoryNameThe name of the repository (see Repository) for which to return all available tasks. 

Example 
The following URL can be used as a GET request to request all available reports of a repository named CRMReports:

http://<servername>:<port>/MailAndDeploy/Api/?RequestType=GetAvailableTasks&RepositoryName= CRMReports 

Success Response 
The XML document that will be returned in case the request completes successfully is formatted as follows:

<?xml version="1.0" encoding="utf-8"?>
 <MailAndDeployApiResponse Success="True"> 
<Task Name="{report_name}" 
Description="{report_description}"> 
<TaskParameter Name="{taskparameter_name}" 
Caption="{taskparameter_caption}" />
 ... 
</Task> 
... 
</MailAndDeployApiResponse>

The following properties are contained in the response:

Success
The value True indicates that the request has completed successfully.
Task Name 
The name of the task.
Task DescriptionThe description of the task.
Task ParametersA list of zero or more task parameters (see Task Parameters) of that task.



T
Team is the author of this solution article.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.