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

jobId
the Job ID whose status is being queried

ReportResponse

faxJobReport

the report of the job ID queried

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

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

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

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