|prev next Table of Contents JobSubmit
The JobSubmit function allows one or more documents to be submitted for delivery to one or more destinations. This is one of the most basic, and also one of the most complex, functions available through the Cloud Fax and Notifications API.
One source of the complexity arises from the need to support the wide variety of services and features that are available, and the different options and formats that each may require or forbid. Another source of the complexity is the desire to allow the XML representation of the data to be at least somewhat intelligible to humans and support some level of automatic validation. The Cloud Fax and Notifications API schema reflects all this in that there are many choices, optional elements, and alternative valid XML arrangements. The schema itself does not completely define proper use of the service - there are valid XML JobSubmitRequests that will be rejected by API processing, or result in errors as the job is processed by EasyLink switches. In some cases this was done in order to allow the function to be expanded without needing to amend the schema, and in others this was done since representing the dependencies in the schema was not practical. Many of the dependencies are mentioned here, but in general any developer of Cloud Fax and Notifications API applications should work with EasyLink to gain an understanding of the services and options and how they behave and interact.
The user profile as stored on EasyLink systems may interact with a JobSubmitRequest in setting the options used for a job. For example, if a user is not set up to ordinarily receive delivery reports, then a DeliveryReport is required to get one. On the other hand, if the profile indicates a default delivery report, then a report will be received unless the DeliveryReport specifies "none".
Currently, a JobSubmitRequest can contain multiple Message elements, each of which corresponds to a job to be processed by an EasyLink switch. The ability to include multiple Message elements allows multiple jobs to be submitted with a single Cloud Fax and Notifications API call, and may help users aggregate processing of a group of different job types. The intent is to facilitate processing of related messages (for example, if essentially the same notification is to be sent to both fax and email destinations in separate jobs), rather than to create large batches of distinct messages (for which multiple JobSubmit requests are recommended.)
An important feature of each Message is the delivery optionset - FaxOptions, MailMergeFaxOptions, EmailOptions, EnhancedEmailOptions, VoiceOptions, or SmsOptions - included in the JobOptions element. Each of these optionsets requires a distinct content structure, and may support or require different destination types and features. The Cloud Fax and Notifications API will select an EasyLink switch to process each Message based on the optionset(s) specified - currently an XDDS-type switch will be used for FaxOptions, MailMergeFaxOptions, EmailOptions, and VoiceOptions, and a messageREACH®-type switch will be used for EnhancedEmailOptions and SmsOptions. If more than one optionset is specified, an XDDS-type switch will be used. The user is responsible for making sure that the destinations specified for a given Message are appropriate for the optionset specified, e.g. email destinations for EnhancedEmailOptions.
There are some limitations on the using combinations of option sets. MailMergeFaxOptions and EmailOptions may not be used in conjunction with other option sets, or in MultiMode. MultiMode EnhancedEmail may require special user settings (for example, "EDMTA delivery") to work as expected.
An option set may be explicitly present in the message if one of the elements named above appears within the JobOptions. An option set may be implicitly present if an AddrTypeUse element in a Part names the associated destination type.
The "URL" option set has no explicit element or options, and no restrictions on content. But its presence along with another option set will trigger multi mode processing and validation.
The next section contains the description of the request element. Following that there is a discussion of the types of documents that can be used for different types of deliveries.
Jobs submitted by mail2fax users that identify the effective user using an "M2F" alias (see Request) will be internally marked as mail2fax jobs, and will be visible on the Fax2Mail website.
|prev next Table of Contents JobSubmit