Method getFaxReports
The getFaxReports method makes it possible to request one or more jobs' data as well as its current status during processing. The report generated in response displays entries related to a job. Entries on job characteristics defined in the JobRequest as well as information on the current status of each recipient are located below under ReportResponse.
A job’s status can be queried until its report data is deleted. You can initiate deletion of the data with the use of the Webservice deleteFaxReport method, but if this does not occur, the data will automatically be deleted after 30 days.
If you sent the fax job requests via a high availability URL, you have to poll the status from both included data centers. E.g., US1 and US2 in case of the US high availability URL. Please do not poll statuses directly from an HA URL but use the specific ones for the data centers.
You can concurrently query the Webservice getFaxReports
method and request a notification on the fax job to be sent via http or email.
The maximum number of jobs per request is set to 1000.
Input parameter: ReportRequest
Output parameter: ReportResponse
ReportRequest
Field Name | Data type | Required | Multiple possible |
---|---|---|---|
jobId | String | Yes | Yes |
jobId
the Job ID whose status is being queried
ReportResponse
Field name | Data type | Required | Multiple possible |
---|---|---|---|
faxJobReport | faxJobReport | No | Yes |
faxJobReport
the report of the job ID queried
Field Name | Data type | Required | Multiple possible |
---|---|---|---|
jobId | String | Yes | No |
reportMail | ReportMail | No | No |
httpStatusPush | httpStatusPush | No | No |
faxRecipient | FaxRecipientWithStatus | Yes | Yes |
document | Document | No | Yes |
options | Options | No | No |
pages | Integer | No | No |
jobId
the ID of the job for which a report is delivered
reportMail
if a report email is required; email addresses to which the report is sent (see ReportMail).
httpStatusPush
See the table below.
faxRecipient
information on the fax recipient and the status of the fax transmission to this recipient (multiple in cases of more than one recipient)
document
information on the sent document, but not on the document’s data itself (multiple in cases of more than one recipient)
options
the send option set for each job
pages
number of pages in the fax document, as long as it was successfully delivered.
httpStatusPush
Field name | Data type | Required | Multiple possible |
---|---|---|---|
url | url | No | No |
authMethod | Enumeration | No | no |
url
if an HTTP Status Push was required, this is the URL to which the status of the fax transmission is sent
authMethod
authentication used for HTTP Status Push
See HTTP status push for additional details.
Java sample code
ReportRequest reportRequest =
this.objectFactory.createReportRequest();
// Authentication:
reportRequest.setUsername(_USERNAME_);
reportRequest.setPassword(_PASSWORD_);
// Specify jobs:
List<String> jobIdList = reportRequest.getJobId();
for (String jobId : requestedJobIds) {
jobIdList.add(jobId);
}
// Fire request:
ReportResponse reportResponse = this.servicePort.getFaxReports(reportRequest);
// Analyse response:
List<FaxJobReport> reportList = reportResponse.getFaxJobReport();
for (FaxJobReport report : reportList) {
int pageCount = report.getPages();
for (FaxRecipientWithStatus rcptWithStatus : report.getFaxRecipient())
{
String rcptNumber = rcptWithStatus.getNumber();
String rcptStatus = rcptWithStatus.getStatus();
int durationSecs = rcptWithStatus.getDurationInSecs();
if ("PENDING".equals(rcptStatus)) {
log.info("Job not yet completed");
} else if ("OK".equals(rcptStatus)) {
// Success
log.info("Successfully sent fax to " + rcptNumber + " in " +
durationSecs + " seconds (pages: " + pageCount + ")");
} else {
// Failure
log.info("Failed to send fax to " + rcptNumber + "; Reason: " +
rcptWithStatus.getReason());
}
}
}
Request XML
<ns2:ReportRequest xmlns:ns2="http://retarus.com/fax4ba/faxws/3/0">
<username>username</username>
<password>password</password>
<jobId>FJIJPNJABCJNFGI5S</jobId>
</ns2:ReportRequest>
Response XML
<ns2:ReportResponse xmlns:ns2="http://retarus.com/fax4ba/faxws/3/0">
<faxJobReport>
<jobId>FJIJPNJYN906EDIJNFGI5S</jobId>
<reportMail>
<successAddress></successAddress>
<failureAddress></failureAddress>
<attachedFaxImageMode>NEVER</attachedFaxImageMode>
<attachedFaxImageFormat>TIFF</attachedFaxImageFormat>
</reportMail>
<httpStatusPush>
<url>https://statuslistener.example.com:9564/Faxolution-v3.0</url>
<authMethod>HTTP_BASIC</authMethod>
</httpStatusPush>
<faxRecipient>
<number>+498912504001710</number>
<numId>FNIJPNJYNA06EDIJNFUO1Q</numId>
<status>PENDING</status>
<reason>async_rendering</reason>
<durationInSecs>0</durationInSecs>
<sentToNumber>00498912504001710</sentToNumber>
<remoteCsid>+49/89/1250400-1710</remoteCsid>
</faxRecipient>
<document>
<name>document.pdf</name>
<isText>false</isText>
</document>
<options>
<resolution>HIGH</resolution>
<csid>Example Inc.</csid>
<header>Fax from %C to %#%r%Y-%m-%d</header>
<isBlacklistEnabled>false</isBlacklistEnabled>
<isExpress>true</isExpress>
<overlay>
<name></name>
<mode>ALL_PAGES</mode>
</overlay>
<coverpageTemplateName></coverpageTemplateName>
<jobExpiryMinutes>50</jobExpiryMinutes>
<billingCode>My BC</billingCode>
<billingInfo></billingInfo>
<jobReference>My Reference ID</jobReference>
</options>
<pages>1</pages>
</faxJobReport>
</ns2:ReportResponse>
Exceptions
TemporaryFailure
Appears when the request currently cannot be processed due to an internal Webservice error.
WrongUserPassword
Appears when the request contains invalid authentication data. InvalidRequestData: Appears when the request cannot be processed because it contains invalid data.
NotAvailable
Appears when there is no report in the system for the Job ID you entered.
FaxRecipientWithStatus
This method contains information on the fax recipient as well as the transmission status of the fax sent to this recipient.
FaxRecipientWithStatus
Field name | Data type | Required | Multiple possible |
---|---|---|---|
number | String | Yes | No |
numId | String | No | No |
property | RecipientProperty | No | Yes |
status | String | Yes | No |
reason | String | No | No |
sentTS | Date | No | No |
durationInSecs | Integer | No | No |
sentToNumber | String | No | No |
remoteCsid | String | No | No |
number
dialed number (international format, e.g., +49891234678)
numId
recipient’s ID, which is set by the Webservice; possibly overwritten by a value set by the client
property
personalized data for the cover page (see RecipientProperty).
status
fax transmission status
reason
fault description, if the transmission failed
sentTS
time when fax transmission ended, provided it is already completed
durationInSecs
duration of the fax transmission, in seconds, provided the transmission is complete
sentToNumber
the fax number the fax was actually sent to, provided the transmission is complete
remoteCsid
the identifier of the recipient fax device, provided the fax was successfully delivered
Document
The metadata for this document; not the actual document data (see DocumentWithData).
Document
Field name | Data type | Required | Multiple possible |
---|---|---|---|
name | String | Yes | No |
charset | String | No | No |
isText | Boolean | No | No |
name
document file name; the file extension is important for determining the file type, e.g., Invoice-2016-01.pdf
charset
character encoding of plain text documents (*.txt). For a list of possible values, see Supported character sets.
isText
currently is not enabled in this version