Method sendFaxJob

This method prepares fax jobs for transfer for processing. If a valid JobRequest has been received by the Webservice via the sendFaxJob method, the Webservice sends an ID back that is assigned to this fax job via JobReponse. The client must specify this Job ID when querying the job's status.

In addition to entering the job’s content and recipients, entries related to the receipt of the job status reports can also be made in JobRequest.

Input parameter: JobRequest

Output parameter: JobResponse

JobRequest

reportMail
if a fax job status report will be sent via email: recipient email addresses

httpStatusPush
if a report on the fax job’s status will be sent via HTTP

faxRecipient
information for a fax recipient (multiple, in cases of more than one recipient)

document
data and additional information on sent documents; if there is no document and no cover page, the Webservice will not accept the job.

options
options related to the fax being sent, such as header, priority, scheduling, etc.

JobResponse

jobId

the Job ID generated by the Webservice, which can be used to reference the job in the future

Java sample code

// Authentication:
jobRequest.setUsername(_USERNAME_);
jobRequest.setPassword(_PASSWORD_);

// Add recipient to request:
List<FaxRecipient> rcptList = jobRequest.getFaxRecipient();
FaxRecipient rcpt = this.objectFactory.createFaxRecipient();
rcpt.setNumber("00498912504001710");
rcptList.add(rcpt);

// Add document to request:
File documentFile = *new* File("./Tests/documents/document.pdf");
List<DocumentWithData> documentList = jobRequest.getDocument();
DocumentWithData document = this.objectFactory.createDocumentWithData();
document.setName(documentFile.getName());
document.setData(FileUtils._readFileToByteArray_(documentFile)); // Loads whole document into memory!
documentList.add(document);

// Add options to request:
Options options = this.objectFactory.createOptions();
options.setResolution(Resolution._HIGH_);
options.setCsid("Example Inc.");
options.setHeader("Fax from %C to %#%r%Y-%m-%d"); // -> "Fax from Example Inc. to 001987654321 2015-12-11"
options.setBillingCode("My BC");
options.setJobReference("My Reference ID");
jobRequest.setOptions(options);

// Add HTTP Push to request:
HttpStatusPush statusPush = this.objectFactory.createHttpStatusPush();
statusPush.setUrl("https://statuslistener.example.com:9564/Faxolution-v3.0");

// Optional; only if push receiver demands authentication:
statusPush.setAuthMethod(PushAuthMethod._HTTP_BASIC_); // Use HTTP Basic Auth
statusPush.setPrincipal(_HTTP_PUSH_USERNAME_);
statusPush.setCredentials(_HTTP_PUSH_PASSWORD_);
jobRequest.setHttpStatusPush(statusPush);

// Fire request:
JobResponse jobResponse = this.servicePort.sendFaxJob(jobRequest);
log.info("Sent job to web service: Job ID " + jobResponse.getJobId());

Request XML

<ns2:JobRequest xmlns:ns2="http://retarus.com/fax4ba/faxws/3/0">
	<username>username</username>
	<password>password</password>
	<httpStatusPush>
		<url>https://statuslistener.example.com:9564/Faxolution-v3.0</url>
		<principal>push_username</principal>
		<credentials>push_password</credentials>
		<authMethod>HTTP_BASIC</authMethod>
	</httpStatusPush>
	<faxRecipient>
		<number>00123456789</number>
	</faxRecipient>
	<document>
		<name>document.pdf</name>
		<data>base64 data</data>
	</document>
	<options>
		<resolution>HIGH</resolution>
		<csid>Example Inc.</csid>
		<header>Fax from %C to %#%r%Y-%m-%d</header>
		<billingCode>My BC</billingCode>
		<jobReference>My Reference ID</jobReference>
	</options>
</ns2:JobRequest>

Response XML

<ns2:JobResponse xmlns:ns2="http://retarus.com/fax4ba/faxws/3/0">
	<jobId>FJIJPIFQLJ06EDIJNFXVWC</jobId>
</ns2:JobResponse>

Exceptions

TemporaryFailure
appears if the request currently cannot be processed due to an internal error in the webservice.

WrongUserPassword
appears if the request contains invalid authentication data.

InvalidRequestData
appears if the request can be not be processed because it contains invalid data (e.g., neither a document nor a cover page).

In addition to querying via Webservice (getFaxReport), it is possible to request notification for each fax job as soon as processing is completed. The status information can be sent by either HTTP POST or email. Separate email addresses can each be specified for delivery and failed delivery confirmations. If an email address is deleted for either type of confirmation, no notification email will be sent for the confirmation type that was removed.

ReportMail

The Fax Image feature in the Report Mails is triggered by options in the SOAP job.

ReportMail

successAddress
email address, to which delivery confirmations notifications should be sent

failureAddress
email address, to which a notification should be sent when errors occur

attachedFaxImageMode
determines, when the fax image will be attached. Valid modes are NEVER, SUCCESS_ONLY, FAILURE_ONLY, ALWAYS.

• attachedFaxImageFormat: the following formats are supported: TIFF and PDF_WITH_OCR (creates a fully searchable PDF file)

The report emails’ format is specified through a template which is filled out with relevant data (Job ID, job status, details on the fax recipients). A default template is available for all customers; however, you can install a customized template. Templates must be encoded in UTF-8 format.

HttpStatusPush

In order to receive notification via HTTP, the JobRequest must contain the httpStatusPush element. The URL to which the HTTP POST request is sent has to be specified.

See HTTP status push for additional details.

HttpStatusPush

url
the target URL that is the destination for a POST request (sometimes called “Callback URL”)

principal
the username (if authentication is used)

credentials
the password (if authentication is used)

authMethods
HTTP_BASIC, HTTP_DIGEST, OAUTH2 or NONE.

FaxRecipient

If a fax can be successfully sent to the recipient fax number, the transmission is completed and considered successful. The destination number which received the fax will be indicated in the report data for each recipient under RecipientStatus - sentToNumber.

FaxRecipient

number
dialed number (international format, e.g., +49891234678)

property
personalized data for the cover page

RecipientProperty

Personalized data (key-value pairs) for the cover page (see also Cover page personalization).

key
name of the key

value
the value assigned to the key

DocumentWithData

Metadata + document data

DocumentWithData

name
document file name; the extension is important for determining the file type, e.g., Invoice-2016-01.pdf. Please note: the maximum length of a file name is 32 characters. Allowed characters are: [a-zA-Z0-9-_.] (brackets excluded). Whitespaces, slashes, or other special characters are not permitted. See Supported document formats.

charset
character encoding of plain text documents (*.txt). Potential values: US-ASCII, UTF-8, UTF-16, UTF-16BE, UTF-16LE, ISO-8859-1, and Windows-1252

• isText: currently is not enabled in this version

data
the document’s binary data, Base64-coded

It is also possible to send a PDF that is located at an URL. To do so, the name element within DocumentWithData must have an additional file extension ".url" after the regular ".pdf" file extension. The URL leading to the PDF must be encoded in Base64. This is how an example could look like:

XML

<document>
	<name>myfaxdocument.pdf.url</name>
	<data>aHR0cHM6Ly9hc3NldHMucmV0YXJ1cy5jb20vd3AtY29udGVudC91cGxvYWRzLzIwMTgvMDIvcmV0YXJ1c191c2UtY2FzZV9vcHRpbWl6ZWQtZGVsaXZlcnktcHJvY2Vzc2VzX2VuLnBkZg==</data>
</document>

Options

Various settings for the fax job; e.g., header, priority, scheduling, etc.

Options

resolution
the fax’s resolution (LOW, HIGH)

csid
the sender ID the received fax was sent from (max. 20 characters)

header
the content of the header, including control characters

isBlacklistEnabled
flag for the use of the Robinson List (only for numbers in Germany)

isExpress
flag for transmissions sent express

overlay
data for the overlay function (stationery function)

coverpageTemplateName
name of the cover page’s template

scheduleTS
scheduled transmission time in the future, if not being sent immediately

jobExpiryMinutes
termination time for attempts to send a fax job

billingCode
information on the cost center; format is arbitrary (max. 80 characters)

billingInfo
additional data for internal customer accounting (max. 80 characters)

jobReference

reference information on the fax job; format is arbitrary, e.g., for a customer-defined equivalent to the Job ID (this would be concurrently managed along with the actual Job ID, but will not overwrite it; max. 256 characters)

Overlay

Settings for the overlay (e.g. stationery). A template (e.g., with letter header and footer) can be applied to all or specific pages in the fax. A template consists of a one-page, black-and-white document. In order to install an overlay, the customer transfers a template to Retarus, and the template is then saved in Retarus’ infrastructure under a mutually agreed upon name.

• name: the template name, without the path information and file extension, e.g., overlay_template1

• mode: specifies the page in the document where the template (overlay) will be applied. Possible values:

• ALL_PAGES: the overlay is applied to all pages (used when mode is not specified)

• NO_OVERLAY: no overlay is used (returns the same result as if “no overlay” had been specified in the options)

• FIRST_PAGE: the overlay is applied only to the first page (if you are using a cover page, it is considered the first page)

• LAST PAGE: the overlay is applied only to the last page

• ALL_BUT_FIRST_PAGE: the overlay is applied to all pages except for the first (if you are using a cover page, the overlay will be applied to all other pages because the cover page is considered the first page)

• ALL _BUT_LAST_PAGE: the overlay is applied to all pages except the last one

• ALL_BUT_FIRST_AND_LAST_PAGE: the overlay is applied to all pages except for the first and the last (the cover page is considered the first page if this mode is used)

• FIRST_FILE: if the faxed document consists of multiple files, the overlay will only be used on the first file’s pages (the cover page is considered not to belong to any file and does not an overlay in this mode)

Header

Header contents, including control characters.

See Headers for details.

CoverpageTemplateName

A cover page can be personalized for each individual recipient and then attached to the front of each fax document.

A template containing keys that function as placeholders for the definitive personalized data is used to design the cover page. Customers can choose which keys in the template they want to use. An element from the RecipientProperty type has to be specified in the job request within the Fax Recipient element. RecipientProperty contains the name of the key and the value for the key that should be applied to the cover page, which allows you to specify a value for each fax recipient.

Example

Template (FreeMarker Template Language)

…
Fax from ${senderName} an ${rcptName}<br>
<b>Subject: ${subject}</b>
…

RecipientProperty

Result - Personalized cover page

Fax from Alice to Bob
<b>Subject: Important message</b>

The template used to process a fax job is entered in the job itself. The name of the template is specified under the CoverpageTemplate method.

Templates are stored on Retarus servers.

JobExpiryMinutes

The maximum processing time for a fax job can be individually customized for each job. No further attempt to send the fax will be made after the expiration of the time frame that has been configured. Instead of additional attempts to send the fax, it will be aborted and considered to have failed. If a fax job has multiple recipients, it is possible that a portion of the fax had already been successfully delivered before the job was aborted. The time frame (in number of minutes) is configured in the job request under the jobExpiryMinutes option, and begins as soon as a job is received by the Webservice.

Supported Document Formats

See Supported document formats.