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
Field name | Data type | Required | Multiple possible |
---|---|---|---|
reportMail | ReportMail | No | No |
httpStatusPush | HttpStatusPush | No | No |
faxRecipient | FaxRecipient | Yes | Yes |
document | DocumentWithData | No | Yes |
options | Options | No | No |
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
Field name | Data type | Required | Multiple possible |
---|---|---|---|
jobId | String | Yes | No |
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
Field name | Data type | Required | Multiple possible |
---|---|---|---|
successAddress | String | No | No |
failureAddress | String | No | No |
attachedFaxImageMode | Enumeration | No | No |
attachedFaxImageFormat | String | No | No |
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
Field name | Data type | Required | Multiple possible |
---|---|---|---|
url | url | yes | No |
principal | string | No | No |
credentials | string | No | No |
authMethods | Enumeration | No | No |
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
Field name | Data type | Required | Multiple possible |
---|---|---|---|
number | String | Yes | No |
property | RecipientProperty | No | Yes |
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).
Field name | Data type | Required | Multiple possible |
---|---|---|---|
key | String | Yes | No |
value | String | Yes | No |
key
name of the key
value
the value assigned to the key
DocumentWithData
Metadata + document data
DocumentWithData
Field name | Data type | Required | Multiple possible |
---|---|---|---|
name | String | Yes | No |
charset | String | No | No |
isText | Boolean | No | No |
data | Base64-coded binary data | Yes | No |
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:
<document>
<name>myfaxdocument.pdf.url</name>
<data>aHR0cHM6Ly9hc3NldHMucmV0YXJ1cy5jb20vd3AtY29udGVudC91cGxvYWRzLzIwMTgvMDIvcmV0YXJ1c191c2UtY2FzZV9vcHRpbWl6ZWQtZGVsaXZlcnktcHJvY2Vzc2VzX2VuLnBkZg==</data>
</document>
Options
Various settings for the fax job; e.g., header, priority, scheduling, etc.
Options
Field name | Data type | Required | Multiple possible |
---|---|---|---|
resolution | Resolution | No | No |
csid | String | No | No |
Field Name | Data Type | Required | Multiple Possible |
header | String | No | No |
isBlacklistEnabled | Boolean | No | No |
isExpress | Boolean | No | No |
overlay | Overlay | No | No |
coverpageTemplateName | String | No | No |
scheduleTS | Date | No | No |
jobExpiryMinutes | Integer | No | No |
billingCode | String | No | No |
billingInfo | String | No | No |
jobReference | String | No | No |
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.
Field name | Data type | Required | Multiple possible |
---|---|---|---|
name | String | Yes | No |
mode | String | Yes | No |
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
Key | Value |
---|---|
senderName | Alice |
rcptName | Bob |
subject | Important Message |
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.