New document notification for subscriptions

Overview

CloudStreet Portal version 3 includes a helper function that will tell you which subscribers have requested to be notified when new documents are uploaded to the portal. This allows you to then create email notifications and send them to these subscribers. The system works like this:

  1. At an interval you choose (usually 10-15 min), the system will query the database looking for any new documents that have been uploaded.
  2. The system will then scan the subscription records looking for subscriptions where the user has asked to be notified when new documents matching the subscription have been added.
  3. If it finds subscriptions whereby users asked to be notified of new documents and there are new documents for those subscriptions, then an XML file will be generated and placed into the csp_notifications directory in the format of "notifyNewDoc_yyyymmdd_hhmmss.xml:
  4. This XML file will contain all of the details about each 'hit' including full user information (including email address) and all of the relevant information about the new document (e.g., doc reference, customer reference, database row number, document type, transaction date, total value, etc.)
  5. The XML file's <notice> containers will contain all of the information you will need to generate emails to your users.
  6. The <notice> containers in the file are ordered in a way that makes it easy to iterate the XML containers in top-down order knowing that all notifications for a user will be grouped together in order and not scattered throughout the XML file. The ordering is:
    1. by subscriber id
    2. then by division code
    3. then by customer id
    4. then by document type
    5. then document id
    6. then by document reference number
    7. then by total value
  7. Note: Ordering criteria 6 and 7 were added to accommodate a future project to allow administrator selection of ordering criteria and is largely ignored in this release)
  8. Once the XML file is written to the notifications directory, the document in the database is marked so that it will not be placed into the next notification XML record (you won't been told about it again.)
  9. Your mission is to poll the notifications directory (as you already do), pickup the XML file(s) and then iterate the XML and send out emails as you wish (using the information provided to you in the XML and, optionally, other information you may wish to collect and include from your ERP server.)

 

Example (excerpted)

<?xml version="1.0"?>
<NOTIFICATION>
  <timestamp>2018-03-17 22:52:11</timestamp>
  <notices>
    <notice>
      <notice_type>notifySubscriberOfNewDocument</notice_type>
      <action>NOTIFY_EMAIL</action>
      <subscriber_id>672</subscriber_id>
      <name>CloudStreet Master</name>
      <username>bdecker</username>
      <email>This email address is being protected from spambots. You need JavaScript enabled to view it.</email>
      <division_code>002</division_code>
      <division_name>Division 002</division_name>
      <customer_id>00005051</customer_id>
      <document_type>invoice</document_type>
      <id>10</id>
      <doc_reference>002.00005051.54795</doc_reference>
      <cust_ref>618019014</cust_ref>
      <total_value>4364.80</total_value>
      <trans_date>2003-11-12 00:00:00</trans_date>
    </notice>
    <notice>
      <notice_type>notifySubscriberOfNewDocument</notice_type>
      <action>NOTIFY_EMAIL</action>
      <subscriber_id>672</subscriber_id>
      <name>CloudStreet Master</name>
      <username>bdecker</username>
      <email>This email address is being protected from spambots. You need JavaScript enabled to view it.</email>
      <division_code>002</division_code>
      <division_name>Division 002</division_name>
      <customer_id>00005443</customer_id>
      <document_type>invoice</document_type>
      <id>9</id>
      <doc_reference>002.00005443.179612</doc_reference>
      <cust_ref>677028/993609306</cust_ref>
      <total_value>3896.00</total_value>
      <trans_date>2016-12-21 00:00:00</trans_date>
    </notice>
    <notice>
      <notice_type>notifySubscriberOfNewDocument</notice_type>
      <action>NOTIFY_EMAIL</action>
      <subscriber_id>674</subscriber_id>
      <name>Jim Sales</name>
      <username>jsales</username>
      <email>This email address is being protected from spambots. You need JavaScript enabled to view it.</email>
      <division_code>002</division_code>
      <division_name>Division 002</division_name>
      <customer_id>00005051</customer_id>
      <document_type>invoice</document_type>
      <id>10</id>
      <doc_reference>002.00005051.54795</doc_reference>
      <cust_ref>618019014</cust_ref>
      <total_value>4364.80</total_value>
      <trans_date>2003-11-12 00:00:00</trans_date>
    </notice>
    <notice>
      <notice_type>notifySubscriberOfNewDocument</notice_type>
      <action>NOTIFY_EMAIL</action>
      <subscriber_id>674</subscriber_id>
      <name>Jim Sales</name>
      <username>jsales</username>
      <email>This email address is being protected from spambots. You need JavaScript enabled to view it.</email>
      <division_code>002</division_code>
      <division_name>Division 002</division_name>
      <customer_id>00005403</customer_id>
      <document_type>invoice</document_type>
      <id>8</id>
      <doc_reference>002.00005403.54796</doc_reference>
      <cust_ref>141557</cust_ref>
      <total_value>3505.00</total_value>
      <trans_date>2003-11-12 00:00:00</trans_date>
    </notice>
  </notices>
</NOTIFICATION>

 

Format and ordering

The XML will be formatted as shown in the example above. Multiple <notice> containers may exist depending on the number of new documents and the number of subscribers for the document type that have requested notification in their subscription record(s).

See ordering criteria as defined above.

Triggering event

In the current release, the notifyNewDoc notification records is produced by a cron job that is set to run on an interval you can specify (notify your CloudStreet Portal account manager). In a future release, this event may be triggered to automatically execute at the end of any document import event.

Removal of Notification

You are responsible for polling and removing notification records. This can be performed using your FTP Client. Use caution and do not remove all documents or all notifications from the notifications directory.