3 Oracle User Messaging Service Drivers

This chapter describes the purpose, features and limitations of Oracle User Messaging Service (UMS) drivers. It discusses the following UMS drivers:

Section 3.1, "Email Driver"
Section 3.2, "SMS (SMPP) Driver"
Section 3.3, "XMPP Driver"
Section 3.4, "Extension Driver"
Section 3.5, "Twitter Driver"
Section 3.6, "APNS Driver"

UMS drivers contain protocol specific implementation to connect UMS to various messaging gateways, for instance, email servers, or short message service centers (SMSC), and so on. Drivers can be deployed or undeployed, independently of one another, depending on the availability of messaging channels in a given installation.

3.1 Email Driver

The Email Driver sends and receives messages. It supports all relevant email protocols, SMTP for sending emails, and IMAP and POP3 for receiving emails, to be able to communicate with every standard mail server. Support is implemented for enabling the security protocols, TLS or SSL, to protect email contents on the wire. The Email Driver uses JavaMail v1.4, which is the standard Java component that implements the required protocols and clients, to create, access, send, and receive emails.

The Email Driver uses a multi-threaded design to be able to poll multiple mail boxes (over IMAP or POP3 protocol). One limitation is that if there is only one mail box to poll, this leads to only one thread working on that box.

Note:

POP3 is deprecated protocol and should be avoided.

3.1.1 Scalability notes

The Email Driver can be scaled out to multiple nodes.

3.1.2 High Availability notes

When the connection to the Email Server fails, the Email Driver will wait and retry. The wait period and maximum retries are configurable.

3.1.3 Compatibility notes

The Email Driver is compatible with these protocols: POP3, IMAP4, and SMTP. Table 3-1 lists the Email Driver gateway vendors and their versions.

Table 3-1 Email Driver Gateway Vendors and Versions

Vendor	Version
Oracle Beehive	Release 1 (1.4.3)
Oracle Collaboration Suite	10g Release 1 (10.1.2)
Microsoft Exchange	2003
Dovecot (IMAP4/POP3)	0.99.11
sendmail (SMTP)	8.13.1

The UMS Message API Priority Levels are translated into the Email message header "X-Priority" as follows:

MessagePriorityType.LOWEST => header value "5"
MessagePriorityType.LOW => header value "4"
MessagePriorityType.NORMAL => header value "3"
MessagePriorityType.HIGH => header value "2"
MessagePriorityType.HIGHEST => header value "1"

3.1.4 UMS API Programmer notes

The Email Driver handles transformation of a UMS message to an email message (and vice versa), including headers, content type and charset encoding, MIME multipart and body parts. For an incoming message, the UMS Message recipient is the email address of the email box that received the mail. You can tell if the recipient was in the email To, CC or BCC field, by looking at the Address metadata.

When an outbound email is not deliverable, a Delivery Status Notification (DSN) can be created by the recipient's mail server and sent back to the sender's email address. The Email Driver tries to match a received DSN to the outbound email which the DSN is referring to and create a ”failed to deliver” status of that outbound message. In such a case, a successful delivery status may, after some time, be changed to a failed delivery status.

3.2 SMS (SMPP) Driver

The Short Message Peer-to-Peer (SMPP) protocol is a TCP/IP based industry protocol for exchanging SMS messages between SMS peer entities such as short message service centers (SMS-C) and/or External Short Messaging Entities (ESME). The UMS SMPP Driver is implemented as an ESME. It is based on SMPP protocol v3.4.

If the sending feature is enabled, the SMPP driver opens one TCP connection to the SMS-C as a transmitter for sending. If the driver's receiving feature is enabled, it opens another connection to the SMS-C as a receiver for receiving. Only two TCP connections (both initiated by the driver) are needed for all communication between the driver and the SMS-C.

3.2.1 Scalability notes

The SMPP Driver can be scaled out to multiple nodes. There would be a limitation only if the SMS-C does not allow multiple login by the same account.

3.2.2 High Availability notes

If the connection to the SMS-C is lost, the SMPP driver will periodically attempt to reconnect.

3.2.3 Compatibility notes

The SMPP driver is based on SMPP Protocol v3.4. Table 3-2 lists the SMPP Driver gateway vendors.

Table 3-2 SMPP Driver Gateway Vendors

Vendor
Syniverse
Clickatell
Logica CMG
OpenSMPP (simulator)

3.2.4 UMS API Programmer notes

The outgoing text message is a concatenation of the UMS Message Subject and Content. The incoming SMS Content is put in the UMS Message Content. The UMS Message Subject will be empty.

The UMS Message API Priority Levels are translated into SMPP Priority as follows:

MessagePriorityType.LOWEST, MessagePriorityType.LOW, MessagePriorityType.NORMAL => Smpp Priority: 0

MessagePriorityType.HIGH => Smpp Priority: 1

MessagePriorityType.HIGHEST => Smpp Priority: 2

However, the Smpp Priority may be limited by the SMPP Driver configuration parameter ”PriorityAllowed”.

The SMPP Driver honors the UMS API MessageInfo ”expiration” data and passes that information with the message to the SMS-C.

3.3 XMPP Driver

The XMPP Driver provides unidirectional or bidirectional access from Oracle Fusion Middleware to end users for real-time IM through the Extensible Messaging and Presence Protocol (XMPP). This driver enables end users to receive alert notifications or interactively chat with applications through the IM client of their choice.

XMPP is an open XML-based protocol for IM and consists of a client/server architecture, which resembles the ubiquitous email network. Recipients are addressed by an XMPP ID (or Jabber ID or JID) with the following form: [username]@domain[/resource]. To use the XMPP Driver in UMS, you must have access to a Jabber/XMPP server and an XMPP account for the UMS XMPP Driver instance with which to log in.

An end user of XMPP connects to an XMPP server using an XMPP client to send instant messages to other XMPP users. XMPP, however, is not the only protocol network available for IM. XMPP has an extensible and modular architecture. It integrates with proprietary IM networks, enabling XMPP users to communicate with those on other networks.

3.3.1 Scalability notes

An XMPP Driver cannot be scaled out to multiple servers since the XMPP server does not allow multiple drivers (i.e. clients) to access the same account. When the second driver logs in, the XMPP server disconnects the first driver. The first driver, then, reconnects after a while and then the second driver is disconnected and so on. In this setup, outgoing messages work only if the driver that handles the message is connected at that particular moment.

3.3.2 High Availability notes

When there are connection problems towards the XMPP server, the XMPP driver keeps attempting to reconnect to the remote server, but, increases the delay to avoid tight loops.

3.3.3 Compatibility notes

lists the XMPP Driver gateway vendors and versions.

Table 3-3 XMPP Driver Gateway Vendors and Versions

Vendor	Version
ejabberd	2.1.3
jabberd2	2.2.14
jabberd14	1.6.1.1-p1
Oracle Beehive	2.0.1.2.1

3.3.4 UMS API Programmer notes

XMPP has a concept of Subject and Body which corresponds to the UMS Message Subject and Content.

3.4 Extension Driver

The Extension Driver sends messages to the configured Endpoint URL that implements the Notification WebServices interface defined by UMS. A messaging gateway, or an adapter to a gateway, can implement this Web Service, thereby, extending UMS with no changes in UMS.

The Extension driver also supports sending messages to any ADF Business Components web application, for instance, the ATK Popup Service which is one of Oracle's workflow and collaboration products. At runtime, the Extension Driver detects if the configured Endpoint URL is the Notification WebService or the ATK Popup Service and acts accordingly.

The Extension Driver is used for outgoing messages only.

3.4.1 Scalability notes

The Extension Driver can be scaled out to multiple nodes.

3.4.2 High Availability notes

The driver communicates with the external system via WebServices calls and the host part in the Endpoint URL is a virtual IP, that is, the external system is behind a load balancer.

3.4.3 Compatibility notes

Not applicable

3.4.4 UMS API Programmer notes

The UMS Message content must be textual, not binary. To enable a new protocol in UMS using the Extension Driver, perform the following tasks:

Implement and deploy a web service listener endpoint based on the MessagingNotifyService WSDL (umsnotify.wsdl):

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="http://xmlns.oracle.com/ucs/messaging/extension"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  name="MessagingNotifyService"
                  targetNamespace="http://xmlns.oracle.com/ucs/messaging/extension">
 
    <wsdl:types>
 
    <xsd:schema targetNamespace="http://xmlns.oracle.com/ucs/messaging/extension">
      <xsd:element name="notification">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="messageId" type="xsd:string" minOccurs="0"
 maxOccurs="1">
              <xsd:annotation>
                <xsd:documentation>Unique message identifier from User
 Messaging Service.</xsd:documentation>
              </xsd:annotation>
            </xsd:element>
            <xsd:element name="sender" type="xsd:string">
              <xsd:annotation>
                <xsd:documentation>The sender address.</xsd:documentation>
              </xsd:annotation>
            </xsd:element>
            <xsd:element name="recipient" type="xsd:string">
              <xsd:annotation>
                <xsd:documentation>The recipient address (typically
 username).</xsd:documentation>
              </xsd:annotation>
            </xsd:element>
            <xsd:element name="subject" type="xsd:string" minOccurs="0"
 maxOccurs="1">
              <xsd:annotation>
                <xsd:documentation>The subject of the message, if
 available.</xsd:documentation>
              </xsd:annotation>
            </xsd:element>
            <xsd:element name="contentType" type="xsd:string"
 default="text/plain">
              <xsd:annotation>
                <xsd:documentation>The MIME type of the message. e.g.
 text/plain, text/html, text/xml.</xsd:documentation>
              </xsd:annotation>
            </xsd:element>
            <xsd:element name="content" type="xsd:string">
              <xsd:annotation>
                <xsd:documentation>The main body of the message. Textual
 content only (no binary content).</xsd:documentation>
              </xsd:annotation>
            </xsd:element>
            <xsd:element name="parameters" type="tns:parameter" minOccurs="0"
 maxOccurs="unbounded">
              <xsd:annotation>
                <xsd:documentation>Additional key-value pairs. This interface
 does not define any specific key-value pair meanings. Use of such parameters
 is defined on a private basis by particular implementations of this interface.
   </xsd:documentation>
              </xsd:annotation>
            </xsd:element>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:complexType name="parameter">
        <xsd:sequence>
          <xsd:element name="name" type="xsd:string">
            <xsd:annotation>
              <xsd:documentation>Parameter name</xsd:documentation>
            </xsd:annotation>
          </xsd:element>
          <xsd:element name="value" type="xsd:string">
            <xsd:annotation>
              <xsd:documentation>Parameter value</xsd:documentation>
            </xsd:annotation>
          </xsd:element>
        </xsd:sequence>
      </xsd:complexType>
      <xsd:element name="notificationResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="messageId" type="xsd:string" minOccurs="0"
 maxOccurs="1">
              <xsd:annotation>
                <xsd:documentation>A message identifier returned in response to
 successfully accepting the message. If returned, the identifier should be
 unique. Note: A fault is raised if the message cannot be
 accepted.</xsd:documentation>
              </xsd:annotation></xsd:element>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="notificationFault">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="code" type="xsd:string"/>
            <xsd:element name="message" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </wsdl:types>
  <wsdl:message name="notifyRequest">
    <wsdl:part element="tns:notification" name="parameters" />
  </wsdl:message>
  <wsdl:message name="notifyResponse">
    <wsdl:part element="tns:notificationResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="notifyException">
    <wsdl:part element="tns:notificationFault" name="parameters"/>
  </wsdl:message>
  <wsdl:portType name="Notify">
    <wsdl:operation name="invoke">
      <wsdl:input message="tns:notifyRequest"/>
      <wsdl:output message="tns:notifyResponse"/>
      <wsdl:fault message="tns:notifyException" name="NotifyException"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="NotifySOAPBinding" type="tns:Notify">
    <soap:binding style="document"
 transport="http://schemas.xmlsoap.org/soap/http" />
    <wsdl:operation name="invoke">
      <soap:operation
        soapAction="http://www.oracle.com/ucs/messaging/extension/" />
      <wsdl:input>
        <soap:body use="literal" />
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal" />
      </wsdl:output>
      <wsdl:fault name="NotifyException">
        <soap:fault name="NotifyException" use="literal"/>
      </wsdl:fault>
    </wsdl:operation>
  </wsdl:binding>
 
  <wsdl:service name="NotifyService">
    <wsdl:port binding="tns:NotifySOAPBinding" name="Notify">
      <soap:address location="http://localhost:8001/NotifyService"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

Configure the extension driver by performing the following tasks:
1. Target the predeployed extension driver called usermessagingdriver-extension (or a new deployment) to the appropriate server where UMS (usermessagingserver) is running and start the driver.
2. In Enterprise Manager Fusion Middleware Control, navigate to the usermessagingserver home page.
3. Click User Messaging Service and navigate to Driver Properties.
4. Select and edit the driver usermessagingdriver-extension or create a new driver with the same name as your new driver deployment.
5. Under Driver-Specific Configuration, add a new extension endpoint configuration group and specify the properties. EndpointURL is the URL to the web service listener endpoint that you created in Step one. Protocol is the value of the new messaging channel for which you want to add notification support (for example, myProtocol).
6. Under Common Configuration, update Supported Protocols with a comma-separated list of protocols defined in each Extension Endpoint group.
7. Click OK to save the configuration.
  
  This completes the configuration and integration of a new messaging channel (protocol) in UMS using the extension driver.
To send notifications to this new channel (protocol), recipients must be specified for the URI delivery type using the following URI addressing format:

URI:scheme:scheme-specific-address-value

where, scheme is the protocol. The URI delivery type is optional. For example, if the extension driver was configured to support the protocol, myProtocol, an application can compose a message to myProtocol:john.doe@example.com.

End users can also declare their messaging preferences by creating a new messaging channel for the new channel type in the User Communication Preferences UI. Note that user preferences are only applied when applications send user-based notifications (that is, to recipients of the form USER:username).

3.5 Twitter Driver

The Twitter driver is a UMS driver that communicates with the Twitter API server. It provides a bi-directional messaging service to, or from the Twitter server. Thus, the Twitter driver enables the application users to publish their Twitter feed and receive response for the same.

The following are some features of the Twitter driver:

Multiple Authentication Modes: The Twitter REST API allows the following two forms of authentication:
- OAuth: This is a Single Sign-On type of authentication mode. You can enable this authentication mode from the Fusion Middleware Control (EM) page. On the driver specific EM page, you must set the Authentication Mode parameter to Oauth, and configure two pairs of keys, namely, Customer key, Customer Secret, Access Token, and Access Token Secret. For more information about these keys, see Table 4-12, "Custom Properties of the Twitter Driver".
- xAuth: This authentication mode is based on OAuth. The Twitter driver grants xAuth only to those applications that do not meet the requirements of OAuth. The user must provide the username and password at each request in order to enable this authentication mode.
Mutiple Options for Messaging: The following are the two categories of messages that a user comes across when using the Twitter driver:
- Outbound Message: The messages sent from a UMS client application to the Twitter server are called Outbound messages. These messages could be treated as Tweets or Direct Messages.
  - Tweets: The messages sent to the username, that is configured with the Twitter driver, are posted as tweets. For instance, if the Twitter driver is configured with the credentials of user TW, then all messages sent to URI:twitter:TW will be posted as tweets from user TW.
  - Direct Message: The messages sent from the username of the configured user to another Twitter user can be treated as Direct messages. Twitter allows a configured user to send direct messages to his direct followers only. If the recipient of a direct message is not a registered user of Twitter and is not a direct follower of the sender, then the delivery of the message will fail and an error message will be displayed.
- Inbound Message: The messages received by the Twitter driver from the Twitter server are called Inbound messages. Inbound messages can be of the following types:
  - Timeline Message: This is a list of tweets posted by the configured user or a Twitter user who is followed by the configured user.
  - Direct Message: This is a private message sent to the configured user by a Twitter user, who is followed by the configured user.
Limited Size of the Tweet: Twitter limits the length of each tweet to 140 bytes. Any tweet exceeding this limit is rejected by the Twitter server. The Twitter driver truncates long tweets before sending them to the Twitter server.
Limited Rate of Tweets: Twitter limits the usage of tweets per user. For information about all Twitter limits, see the About Twitter Limits page. If the rate limit of a user exceeds the rate limit of that Twitter user, then the delivery of outbound messages fail and the reception of inbound messages are ceased.

If you are using UMS behind a firewall, then you must configure proxy settings for WebLogic Server. For information about configuring proxy settings for WebLogic Server, see "Using System Properties to Specify the Proxy Server" in Oracle Fusion Middleware Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

3.5.1 Scalability notes

The Twitter Driver can be scaled out to multiple nodes.

3.5.2 High Availability notes

When there are connection problems towards the Twitter server, the Twitter Driver polls the server with reduced frequency ranging from once every 4 minutes to once every 16 minutes until the Twitter server is back to its normal state. During normal operations, the driver polls the Twitter server with a frequency ranging from once every minute to once every 4 minutes.

Twitter actively monitors the usage of their services. If the limit of a user is reached, it may refuse to provide services requested by that client with an error message that states the reason. All limits are listed on the current limits page. When usage is limited by the Twitter server, the driver first waits for 30 minutes then it polls the server with a reduced frequency ranging from once every 4 minutes to once every 16 minutes.

3.5.3 Compatibility notes

The Twitter Driver was introduced in 12.1.2.0.0.

3.5.4 UMS API Programmer notes

For outgoing messages, that is, when posting a tweet or sending a direct message, the tweet text is the UMS Message Subject concatenated with the UMS Message Content. For incoming tweets and direct messages, the text is placed in the UMS Message Content.

Table 3-4 lists the metadata used for outbound messages

Name space: ”UMS-TWITTER”

Table 3-4 Metadata used by Twitter Driver for Outbound Messages

Name	Description	Note
retweet_id	The twitter id of the message to be retweeted. This id is available when receiving a message/tweet.	This metadata is for the recipient Address object.
reply_to_id	The twitter id of the message to reply to. This id is available when receiving a message/tweet.	This metadata is for the recipient Address object.
geo_location	Latitude and longitude expressed as latitude,longitude where latitude and longitude will be converted to the java primitive data type, double.	This metadata is for the Message object.

3.6 APNS Driver

The APNS driver is available in User Messaging Service (UMS) 12.2.1 and onwards. It provides support for sending a UMS message as a notification to Apple iOS devices such as an iPhone or an iPad.

The following are some features of the APNS driver:

Otbound Message: Messages sent from a UMS client application to an Apple Device via APNs are called outbound messages in the UMS terminology. In Apple terminology, it is a notification. A Message sent to recipient "uri:apns:token" is handled by the UMS APNS driver. The UMS APNS driver extracts the token from the recipient address and creates an empty Apple Push Notification Payload. Given the information in the UMS Message, Apple Push Notification Payload is populated and finally sent to APNs.

Delivery Type Supported

Delivery type URI is supported. Protocol apns is supported.
Mime types supported

Mime types of text/plain and application/json are supported.
Delivery status types supported

The UMS API defines various status types. The APNS driver uses the following:
- DELIVER_TO_DRIVER_SUCCESS
  
  The message has been received by the driver for further processing.
- DELIVERY_TO_GATEWAY_FAILURE
  
  The notification could not be sent to APNs.
- DELIVERY_TO_GATEWAY_SUCCESS
  
  The notification was sent to APNs. However, note that since APNs does not guarantee delivery and UMS does not know if the message was sent to the device or not, the APNS driver can never return DELIVERY_TO_DEVICE_SUCCESS.
- DELIVERY_TO_DEVICE_FAILURE
  
  The APNS driver has for instance found out that the address used is invalid. Typically the user has unregistered the application on its device.

Mapping to external protocol

Table 3-5 shows how UMS Message properties maps to the APNs protocol.

Table 3-5 GCM Metadata for Outbound Messages

UMS message property	APNs protocol	Value Type	Description
Recipient address e.g. 'uri:apns:token'	device token	UMS address	The token part of the recipient address is used as device token towards the APNs.
Content	alert	string	UMS Message text content is used as payload in the alert message. If the content type is text/plain then the content will be used in the alert. Metadata properties (see table below) are added to the payload. If content type is application/json the content is passed as is to APNs and the metadata properties will be ignored.
Expiration (on the MessageInfo) in seconds. Default `zero`.	expiry	integer	UMS property Expiration specifies a time to live in seconds; zero or negative means that the message shall never expire. If Expiration is negative or zero then expiry will be set to MAX_INT otherwise expiry property will be calculated as current time in seconds + Expiration. Push notifications that expire before being delivered are not considered a failed delivery and don't impact the feedback service.
Subject	-	-	Subject on the UMS message will be ignored.

Table Table 3-6 lists the optional UMS Message metadata.

Table 3-6 Optional UMS Message Metadata

Name	Description
badge	The number to display as the badge of the application icon. If this property is absent, the badge is not changed. To remove the badge, set the value of this property to `0`.
sound	The name of a sound file in the application bundle. The sound in this file is played as an alert. If the sound file doesn't exist or `default.aiff` is specified as the value, the default alert sound is played.
action-loc-key	If a string is specified, displays an alert with two buttons. However, iOS uses the string as a key to get a localized string in the current localization to use for the right button's title instead of 'View'. If the value is null, the system displays an alert with a single OK button that simply dismisses the alert when tapped.
loc-key	A key to an alert-message string in a Localizable.strings file for the current localization (which is set by the user's language preference). The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in `loc-args`
launch-image	The filename of an image file in the application bundle; it may include the extension or omit it. The image is used as the launch image when users tap the action button or move the action slider. If this property is not specified, the system either uses the previous snapshot, uses the image identified by the UILaunchImageFile key in the application's Info.plist file, or falls back to `Default.png`.
custom	To add custom values to the Apple Push Payload use metadata name 'custom' and a JSON formatted String as value. The JSON object will be passed as is to the device application. Custom values must use the JSON structured and primitive types: dictionary (object), array, string, number and boolean. The JSON object will be appended to the payload.

Driver specific message validation

The device token and the message size will be validated. If the device token is not of proper length the message will not be sent and a fail status will be generated. If the message size exceeds 256 bytes the message will not be sent and a failed status will be generated.

In case of content type application/json or that a custom JSON object is added in the metadata property, a JSON sanity check is done to see if the JSON object is parsable, if not the message will not be sent and a failed status will be generated.
Send raw JSON

By setting the content type to application/json the complete APNs message can be set. UMS will handover the JSON data as is to APNs. When the content type is set to application/json all driver specific metadata properties are ignored.

This will also allow other message types to APNs, like MDM (Mobile Device Management) messages.
Multiple application support

The APNS driver supports multi configuration so that multiple independent application can use the APNS driver. In order to select the proper APNS driver for a message the UMS core feature of driver selection is used. The preferred way is to use the SupportedApplicationNames or the SupportedCarriers driver configuration properties.

The message must in case of SupportedCarriers have the corresponding Carrier property set on the message's info object (oracle.sdp.messaging.MessageInfo).
```
message.getMessageInfo().setCarrier("myapp");
```
In case of SupportedApplicationNames, the default value for the application name property is the application's deployment name so in normal cases that can be used. If for some reason some other value must be used the application name property can be set when the MessagingClient is created, like this:
```
Map<String, Object> parameters = new HashMap<String, Object>();

parameters.put(ApplicationInfo.APPLICATION_NAME, "myapp");

messagingClient = MessagingClientFactory.createMessagingClient(parameters);
```

Inbound Message - Feedback service: Inbound message consists of reports from the APNs feedback service. The feedback service will report devices that are not reachable any more due to for instance that the user has uninstalled the iOS application. The APNS driver will poll the feedback service for invalid device tokens for this device application and report those in an inbound message to the provider application. In order for the provider application to receive those messages it needs to register an access point with the same values as the driver is configured with e.g. 'uri:apns:myapp'

The feedback service will return all unreachable device tokens for the device application that the TLS connection indicates. It is not possible to only retrieve a subset of device tokens.

Apple APNs documentation strongly recommends using the feedback service. By using this information to stop sending push notifications that will fail to be delivered, the application will reduce unnecessary message overhead and improve overall system performance. APNs monitors providers for their diligence in checking the feedback service and refraining from sending push notifications to non-existent applications on devices.

The format of the message will be in JSON. The message is an array of JSON objects with device token and expiry date (in Epoch milliseconds as long):
```
[
  {
    "deviceToken" : "ad123e45f6f78c9041dd234e5a6f7890",
    "expiry" : 134567878222112333
  },
  {
    "deviceToken" : "bb223e45f6f78c9041dd234e5a6f1234",
    "expiry" : 133577878222123456
  }
]
```
Same Information Provider Application for different customers: In case the provider application is to be used by several customers (installed on premises or in the cloud) then the client side of the application (the device application) cannot be directly reused. The device application needs to be delivered to the customers using unique bundle identities. This is due to the fact that different TLS certificates needs to be used for each customer when the feedback service is to be polled for unreachable device tokens. The APNS driver needs to use different TLS certificates for each customer, otherwise unreachable device tokens for some other customer will be retrieved.

to add more text.

3.6.1 Scalability notes

The APNS Driver supports as many messages sending as a resource adapter can handle given the JEE platform.

The scalability of the driver is limited by the scalability of the JMS solution. UMS, and the driver, can be deployed on multiple nodes.

3.6.2 High Availability notes

If the call to APNs fails then the message is marked as delivery to gateway failure.

UMS, and the APNS driver, can be deployed on multiple nodes.

Note:

Delivery of Push Notification is not guaranteed by APNs! Data transfer should not be performed using Push Notifications, only send a notification saying that data is available.

3.6.3 Compatibility notes

The APNS Driver is introduced in 12.2.1.0.0.

3.6.4 UMS API Programmer notes

When the UMS APNS driver is deployed into a mid-tier server, the 'uri:apns' delivery channel should be available to all UMS clients. For more information, refer to the code samples below:

3.6.4.1 Send Push Notification

To send a push notification, just send a message to the device token. Suppose the token is '1234567890…1234567890'. The following java snippet will push a notification to that device:

String recipient = "uri:apns:1234567890..1234567890";
Message message = MessagingFactory.createTextMessage("New Lenny K clips");
message.addRecipient(MessagingFactory.createAddress(recipient));
String id = mMessagingClient.send(message);

3.6.4.2 Send Push Notification With Additional Data

To send a push notification specifying badge number and sound file, add meta data to the UMS Message as shown in following java snippet:

String recipient = "uri:apns:1234567890..1234567890";
Message message = MessagingFactory.createTextMessage("New Lenny K clips");
message.addRecipient(MessagingFactory.createAddress(recipient));
message.setMetaData("UMS-APNS", "badge", "3");
message.setMetaData("UMS-APNS", "sound", "Rocknroll.aiff");
String id = mMessagingClient.send(message);

To send a push notification specifying localized alert text with arguments, add meta data to the UMS Message as shown in following java snippet:

String recipient = "uri:apns:1234567890..1234567890";
Message message = MessagingFactory.createTextMessage("New Lenny K clips");
message.addRecipient(MessagingFactory.createAddress(recipient));
message.setMetaData("UMS-APNS", "loc-key", "GAME_PLAY_REQUEST_FORMAT");
message.setMetaData("UMS-APNS", "loc-args", "Jenna,Frank");
String id = mMessagingClient.send(message);

The above will result in a notification payload looking like this:

{
    "aps" : {
        "alert" : {
            "loc-key" : "GAME_PLAY_REQUEST_FORMAT",
            "loc-args" : ["Jenna", "Frank"]
        }
    }
}

3.6.4.3 Send Push Notification With Additional Custom Data

To send a push notification specifying custom data, create a JSON formatted String representing the custom data and add it as metadata "custom" to the UMS Message as shown in following java snippet:

String customDataAsJson = "{\"myCustomDataSection\":{\"mykey1\":\"value1\",\"mykey2\":\"value2\"}, \"section2\":4711}";
String recipient = "uri:apns:1234567890..1234567890";
Message message = MessagingFactory.createTextMessage("New Lenny K clips");
message.addRecipient(MessagingFactory.createAddress(recipient));
message.setMetaData("UMS-APNS", "custom", customDataAsJson);
String id = mMessagingClient.send(message);

The resulting notification payload will look like this:

{
    "aps" : {
        "alert" : "New Lenny K clips",
    },
    "myCustomDataSection" : {
        "mykey1" : "value1",
        "mykey2" : "value2",
    },
    "section2" : 4711
}

Note:

JSON formatted Strings can be created from various objects, for instance using the com.fasterxml.jackson package already available in WebLogic.

3.6.4.4 Send Push Notification With Raw JSON data

To send a push notification specifying the APS payload data, create a JSON formatted String representing the payload:

String rawJson = "{\"aps\":{\"alert\":\"UMS rocks\"}}";
String recipient = "uri:apns:1234567890..1234567890";
Message message = MessagingFactory.createMessage();
message.addRecipient(MessagingFactory.createAddress(recipient));
message.setContent(rawJson,"application/json; charset=\"UTF-8\"");
String id = mMessagingClient.send(message);

3.6.4.5 Send Push Notification With Raw JSON data, MDM payload

To send a push notification specifying the MDM payload data, create a JSON formatted String representing the payload:

String rawJson = "{\"mdm\":\"the_push_magic_token\"}";
String recipient = "uri:apns:1234567890..1234567890";
Message message = MessagingFactory.createMessage();
message.addRecipient(MessagingFactory.createAddress(recipient));
message.setContent(rawJson,"application/json");
String id = mMessagingClient.send(message);

3.6.4.6 Receive unreachable device tokens

The APNS driver will poll the feedback services regularly to get a list of unreachable device tokens. Once the list of device tokens is retrieved the feedback service clears its information about the device tokens. So it is not possible to retrieve the same device token again (unless it has registered again and then again become unreachable).

The application needs to register an UMS access point that corresponds to the access point that the APNS driver is configured with.

import com.fasterxml.jackson.databind.*;
String address = "uri:apns:myapp";
AccessPoint accessPoint = AccessPointFactory.createAccessPoint(MessagingFactory.createAddress(address));
messagingClient.registerAccessPoint(accessPoint);
Message[] messages = messagingClient.receive();
byte[] content = (byte[]) messages[0].getContent();
JsonNode devices = new ObjectMapper().readTree(content);
for (JsonNode device : devices) {
  System.out.println("deviceToken: " + device.get("deviceToken").asText());
  System.out.println("expiry: " + new Date(device.get("expiry").asLong()));
}

3.6.4.7 Send Push Notification With Unicode Characters

If non-ASCII characters shall be used then the charset on the UMS message must be set accordingly, e.g. to UTF-8. Below is a sample code that illustrates creating messages with the character 'ä' and the emoticon .

// message with 'ä'
Message message1 = MessagingFactory.createTextMessage("\u00e4", "UTF-8");
// message with SMILING FACE WITH SUNGLASSES (U+1F60E)
Message message2 = MessagingFactory.createTextMessage("\ud83d\ude0e", "UTF-8");