Setting Up and Consuming the Notifications Framework

Template Variables

If bind variables are used in the Subject or Message Text, the same must be defined in the Template Variables grid. The consumer populates the list of all values that can be used in a StringHashMap having a (Key, Value) pair, with bind variable number as the key. These values are called as Notification Context Parameter values. The required values are then used in the generic template.

Template variables can be used in any order and in any quantity. You may use only 3 or 4 variables from the entire list or maybe none. These can be any values from the list - for example, %5, %13 and %17 if we are using three variables. These values are populated at runtime and the sent mail would contain these values replacing the bind variables.

Recipients Configuration

Use this group box to indicate how the system should set the To, CC, and BCC values in the notification messages. Note that the sections (To, CC, and BCC) available in this group box vary depending on the Notification Type (channel) selected:

• E-mails (To, CC, BCC)

• Alerts (To)

• SMS (To)

• Worklists (To)

Message Text

This group box appears only if the Notification Type is Email with an Email Content Type of text/html. The formatted text is saved differently depending on the browser used. Set the Format field to Normal before creating or updating the message text.

Notification Templates

Use this grid to specify the templates that you have configured for the notification consumer on the Notification Setup page. To process notifications, the framework needs to know which templates are valid to use for sending out emails with respect to the consumer’s business process or scenario. For each of the templates, specify the application class logic which the Notifications Framework will use to identify the valid template for triggering the notification. For example, within Delegated Access, two email notifications are sent at the time that the user delegates new access to somebody. After making the data change and saving the component, one email notification is sent to the user and one to the person to whom access has been delegated. These two notifications use two different templates and are generated under a specific logic. The logic is defined in an application class. For examples of application classes containing logic to trigger a notification, look at any of the delivered Delegated Access application classes:

• SCC_DA:NOTIFICATION:DADelegGrantTemplateProvider

• SCC_DA:NOTIFICATION:DAProxyGrantTemplateProvider

• SCC_DA:NOTIFICATION:DAKnownProxyGrantTmpltProvider

• SCC_DA:NOTIFICATION:DAProxyrevokeTemplateProvider

The Application Class, configured against each consumer Template Name, is invoked (returns true or false) to determine if that particular template is to be used for sending notifications or not.

In the same AppClass created above, include logic to populate the EMPLID property of the Notification Context with the recipient’s EMPLID. This value may be left blank if the notification recipient does not have an EMPLID (for example within Delegated Access, email notifications are sent to the proxies which may or may not have an EMPLID identified).

When the Notifications Framework is used to dynamically determine the template(s) to trigger multiple notifications, the recipient(s) may be different for each notification. Therefore, on selecting a template to trigger the notification, BaseNotificationContext.EMPLID must be populated dynamically with the respective recipient EMPLID. This must be taken care of by the NFK Consumers in their respective Template Provider App Class code (an Application Class configured for each Template Name in Notification Consumer Setup page).

During NFK processing, the provided EMPLID Context value is stored in SCC_NTFREQ_DTL.EMPLID record field. Later, this stored recipient’s EMPLID information is used as part of the Notifications Center page. The page displays the notifications sent to that specific EMPLID.

Methods in Notifications Framework to be used by Consumer

Before invoking  Notifications Framework to process or send notifications, consumers can  make sure that the consumer and template set are to active. The following methods are examples of error handling:

• Method is ConsumerActive(&pSccNtfConld As string) returns Boolean;

• Method is TemplateActive(&pSccNtfreqTmpltid As string) returns Boolean;

This helps to avoid unnecessary processing by consumers/framework.

The methods that must be used by the consumer to consume or invoke the Notifications Framework are listed below:

1. Write an AppClass that extends AbstractNotification class. The Consumer ID must be passed to the Super Class constructor here, as shown in the sample code below:

   %Super = create SCC_COMMON:NOTIFICATION:AbstractNotification(&Consumer_ID);

2. Implement the abstract method createNtfContext(). This creates the context for the consumer as already explained in the previous section.

   Sample Code:

   method createNtfContext
      /+ Returns SCC_COMMON:NOTIFICATION:INotificationContext +/
      /+ Extends/implements SCC_COMMON:NOTIFICATION:AbstractNotification.createNtfContext +/
      
      Return create SCC_DA:NOTIFICATION:DANotificationContext();
      
   end-method;

3. Implement the abstract method populateNtfContext(). This method populates the context create above with the necessary values as will be required during the processing.

   Sample Code:

   /* Downcast */
      Local SCC_DA:NOTIFICATION:DANotificationContext &myNtfCntxt = &p_ntfContext As SCC_DA:NOTIFICATION:DANotificationContext;
      
      Rem Populate DANotification Context values;
      &myNtfCntxt.EMPLID = &Emplid;
      &myNtfCntxt.SCC_DA_PRXY_ID = &proxyId;

   Note: If a consumer chooses to send a single notification then it can be done by directly populating the &myNtfCntxt.SCC_NTFREQ_TMPLTID with the Template ID value. If the Notification Context property: SCC_NTFREQ_TMPLTID is not populated then the Notifications Framework uses createConsumerNotificationDetailsItems() method to dynamically create single or multiple notification items based on consumer templates setup.

4. Invoke the send(), remind(), or resend() method.

   • %This.send();

     During this processing, the framework creates objects such as Notifications Header, Notification Detail & Notification Item records using the Notification Context data populated by the consumer. Finally, the send() method for each notification item is invoked using the appropriate channel (like Email, SMS, Alert or Worklist) as per the Notification Template Setup.

   • %This.remind(Notification ID, Detail Sequence Number, Item Sequence Number)

     This method is used to create a “reminder” notification for a previously generated notification. The parameters to this method are the Notification ID, Detail Sequence Number, and Item Sequence Number of an existing notification.

     During this processing, the framework invokes the send() method to create a new notification. Then the framework stores the date/time and the keys of the new notification in the original notification.

   • %This.resend(Notification ID)

     This method is used to resend a previously generated notification. The only parameter to this method is the Notification Request ID of the notification to be resent. The notification data related to that particular Notification Request ID is retrieved, and the notification is sent again. This is applicable for only previously sent notifications. A ‘isResend’ flag decides whether the current transaction is a send or resend. As with send, the resend also invokes the save() method of message log and logs the info/warning messages generated as part of the resend.

5. Override the OnSuccess() and OnError() for custom behavior:

   Sample Code:

   method onSuccess
      
      SQLExec("Update PS_SCC_DA_PROXY set SCC_DA_NTF_REQ_ID=:1 where  EMPLID=:2 and SCC_DA_PRXY_ID=:3", %This.ntfReqID, &Emplid, &proxyId)
   
   end-method;
   
   method onError
   SQLExec(“Update PS_OUTPUT set RESULT= :1”, &p_excep.toString());  
   end-method;

The onError method in AbstractNotification, if not overridden in the implementing class, logs an error in the App Server logs – "Notification cannot be sent for Notification Consumer XXXXXXXX with Request ID YYYYYY due to following error: ACTUAL ERROR”. This behavior can be overridden in the implementing class onError method.

Nodes

Create a new External Node or use an existing Node. Oracles delivers the SCC-NTF_SMS node. Set up the properties of the Node as shown in the screenshots below.

Access Node Definitions select PeopleTools, then select Integration Broker, then select Integration Setup, then select Nodes

Image: Node Definitions Page SMS Notifications

This example illustrates the fields and controls on the Node Definitions page for SMS Notifications.

Image: Node Connectors Page SMS Notifications

This example illustrates the fields and controls on the Node Connectors page for SMS Notifications.

Image: Node Routings Page SMS Notifications

This example illustrates the fields and controls on the Node Routings page for SMS Notifications.

Ensure that there is an Active Outbound Routing from the local node to the external node. If not, create/generate an active routing.

Message

Create a new Non-Rowset based message as shown below. Access the Message Definition page (select PeopleTools, then select Integration Broker, then select Integration Setup, then select Messages).

Image: Message Definition Page SMS Notifications

This example illustrates the fields and controls on the Message Definition page for SMS Notifications.

Service Operation

Create a new Service Operation, as shown below, using the message created above. Access the Service Operation General page (select PeopleTools, then select Integration Broker, then select Integration Setup, then select Service Operations).

Image: Service Operation General Page SMS Notifications

This example illustrates the fields and controls on the Service Operation General page for SMS Notifications.

On the Routings tab, see that there is an active outbound Routing from the Local Node to the External node created above, as shown below:

Image: Service Operation Routings Page SMS Notifications

This example illustrates the fields and controls on the Service Operation Routings page for SMS Notifications.

Service

Create a new Service and add the Service Operation to the Service, as shown below. Access the Services page (select PeopleTools, then select Integration Broker, then select Integration Setup, then select Services).

Image: Services Page SMS Notifications

This example illustrates the fields and controls on the Services page for SMS Notifications.

Please note that the above service needs to be called by PeopleCode in the consumer application.

For APNS

Install the SSL distribution certificate and private cryptographic key obtained on the server computer, on which the provider code runs and from which it connects with the development or production versions of APNs. To do so, complete the following steps:

1. Open Keychain Access utility and click the My Certificates category in the left pane.

2. Find the certificate that needs to be installed and disclose its contents. Both a certificate and a private key will be displayed.

3. Select both the certificate and key, choose File > Export Items, and export them as a Personal Information Exchange (.p12) file.

4. Import this .p12 into pskey keystore on the webserver.

See https://developer.apple.com/library/mac/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ProvisioningDevelopment.html#//apple_ref/doc/uid/TP40008194-CH104-SW1.

For GCM

Import root ca certificate accepted by Google into pskey keystore on peoplesoft web server.

Download GCM Certificate (ex: Geo Trust Global CA) from the browser with URL https://android.googleapis.com/.

Service Operations

When configuring applications which use the Push Channel capability, ensure the following service operations and routings are activated:

The following screenshot is an example of the SCC_NOTIFICATIONS->SCC_APNS_SEND service operation activation. Access the Service Operation General page (select PeopleTools, then select Integration Broker, then select Integration Setup, then select Service Operations).

Image: Service Operation General Page Push Channel

This example illustrates the fields and controls on the Service Operation General page for Push Channel.

To activate the service operation, ensure the Active check box is selected.

Routings

The following screenshot is an example of the routings activation. Access the Routing Definitions page (select PeopleTools, then select Integration Broker, then select Integration Setup, then select Routings).

Image: Routing Definitions Page

This example illustrates the fields and controls on the Routing Definitions page.

To activate the routing, select the Active checkbox, save, and continue.

Queue: SCC_NTF_QUEUE

Access the Routing Definitions page (select PeopleTools, then select Integration Broker, then select Integration Setup, then select Queues).

Image: Queue Definitions Page

This example illustrates the fields and controls on the Queue Definitions page.

Ensure the Queue Status is set to Run, save, and continue.

Notification Handlers

Activate the Notification Handler for SCC_PUSH_NOTIFICATIONS in SOA registry select Set Up SACR, then select System Administration, then select Integrations, then select Notification Handlers.

Image: Notification Handlers Page

This example illustrates the fields and controls on the Notification Handlers page.