<p>Cloudstreet Portal works by accepting XML documents from an external source then importing them into the CloudStreet Portal database.  Access to the documents is controlled via a security mechanism known as subscriptions.  An export of the subscriptions table will provide you with the information necessary to determine which documents should be uploaded to the web site as users register for the site.  By uploading only the documents to which users are subscribed, you can determine which documents to send to CloudStreet Portal.  The other approach is to begin sending all documents and then review subscriptions to determine which documents can be removed from CloudStreet Portal.  The choice is up to you.</p>
<p><strong>The Procedure</strong></p>
<ol>
<li>You must be a site administrator to perform this function.</li>
<li>Login to your CloudStreet Portal web site</li>
<li>Choose Site Administration &gt; Site-Wide Subscriptions from the menu</li>
<li>At the top of the subscriptions list page, you will see a toolbar</li>
</ol>
<p><img src="/images/cloudstreet/Help/subscriptions_list2.PNG" width="75%" /></p>
<p>The <img src="/images/cloudstreet/Help/subscriptions_csv.PNG" alt="" />button will export the selected scriptions to excel and allow you to download the list.</p>
<p><img src="/images/cloudstreet/Help/export_CSV.PNG" width="391" height="274" /></p>
<p> <img src="/images/cloudstreet/Help/subscriptions_save.PNG" width="540" height="403" /></p>
<p>Once it opens in excel, the data may be explored but it may open all in one column instead of broken into individual columns like this:</p>
<p><img src="/images/cloudstreet/Help/subscriptions_inexcel.PNG" width="75%" /></p>
<p> In excel, you can break the data into individual columns by <strong>selecting column A</strong> (where the data is stored), then choosing the <strong>Data</strong> menu then <strong>Text to Columns</strong>.</p>
<p><img src="/images/cloudstreet/Help/excel_textToColumns.PNG" width="50%" /></p>
<p>Choose the <strong>Delimited</strong> option then press <strong>Next</strong>.</p>
<p><img src="/images/cloudstreet/Help/subscriptions_delimiter.PNG" width="50%" /></p>
<p>Press Finish and the data will be broken into individual columns.</p>
<p>A program can be written to parse this CSV output then to compare it with the the controls on the ERP server the determine which division, document type and customers should have their documents uploaded to the cloudstreet portal server.</p>
<h2>Another use for Subscriptions Export</h2>
<p>Another use for this export would be as a feed for a bulk mail or email system.  You can extract the required information to generate outbound messages using the site email tool or another tool of your choosing.</p>
<p> </p>

Overview

CloudStreet Portal version 3 incorporates a new helper function that can notify your host when a portal user requests a subscription for a divisionCode-customerId-documentType combination that is not currently on file in the portal's document database.

To use this feature, you can use your FTP access to your FTP account then simply create a new directory called csp_notifications (if it is not already present).

When CloudStreet Portal sees that this directory name exists in your FTP account, it will automatically write an xml file into that directory each time an administrator on the CloudStreet Portal site approves a subscription for a divisionCode-customerId-documentType combination that does not already exist in the CloudStreet Portal document database.

Your host can poll this directory using FTP and when it finds an xml file, it can import and delete the document from the directory. The XML file contains all of the information your host may need in order to push the required documents to the portal.

Example of the XML file that is created in the csp_notifications directory:

<?xml version="1.0"?>
<notification>
  <timeDate>2017-07-05 20:39:43</timeDate>
  <type>subscription</type>
  <event>approval</event>
  <subscriberId>1001</subscriberId>
  <subscriberName>testuser</subscriberName>
  <subscriberUsername>testuser</subscriberUsername>
  <subscriberEmail>This email address is being protected from spambots. You need JavaScript enabled to view it./subscriberEmail>
  <divisionCode>030</divisionCode>
  <divisionName>Selma</divisionName>
  <documentType>invoice</documentType>
  <customerId>12345</customerId>
  <myCompanyName>Bruce Decker</myCompanyName>
  <reachMeAt>303.905.4110</reachMeAt>
  <customerNotes>Please let me in</customerNotes>
  <approvedByUserId>840</approvedByUserId>
  <approvedByUserName>bdecker</approvedByUserName>
  <approvedByName>Bruce Decker</approvedByName>
  <advice>Zero documents in database for this divisionCode-customerId-documentType combination. Consider importing them into Cloudstreet Portal.</advice>
</notification>

Normal Sequence of Events

1. A user adds a new subscription request for a specific division code, document type and customer ID to their MySubscriptions tab in the portal as a pending_approval status subscription request.
2. A portal administrator approves the subscriptions.
3. Cloudstreet Portal performs a series of checks to determine if CSP should place a notification file into the csp_notification directory. These checks are:
   • The 'Host Update' field in the subscriptions field must be blank
   • The Subscription status must be 'approved'
   • There must not be any documents already on file in the document database for the combination of DivisionCode, DocumentType and CustomerId
   • The directory in your FTP account called 'csp_notification' must exist
4. If all of the above criteria are met, then CSP will generate an XML record and write it into the csp_notification directory. Otherwise, it will skip the notification write logic and simply save the subscription.
5. The host should periodically poll the csp_notification directory looking for new files.
6. When the host finds a file in the cspc_notification directory, it should download it via FTP to the host then host MUST delete the file from the csp_notification directory.
7. The host should parse the XML to gather the divisionCode, CustomerId and DocumentType information.
8. The host will generate the requested XML documents for the subcription and place them in the ftp account's csp_in directory (e.g., csp_in)
9. The host or administrator will import the documents into CloudStreet Portal using one of the supported document import methods.
10. The portal user will now be able to access the documents.

The response time between subscription submission and document availability will vary depending on:

1) The time required to approve the subscription

2) The polling interval of the host to the csp_notification directory

3) The time required for the host to generate the XML documents for the portal

4) The time required to transmit the generated XML documents to the portal

5) The time required to commence the document import function on the portal

6) The time required to import the documents into the portal

Tips

Forcing a notification to be sent from Cloudstreet Portal

The criteria defined above is used by CSP to determine if a notification record should be sent. The first criterion is to check to see if the field 'Host Update' has been set to a valid date time value. If the field contains a value, then CloudStreet Portal assumes that the host has already been updated. To override this check, simply clear the value from the Host Update field and save the subscription. Assuming the other criteria are met, the xml file will be regenerated into the csp_notification directory and the Host Update field will be set to the current date and time to indicate that the subscription notification has been sent.

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.

Overview

The Joomla Framework on which CloudStreet Portal is based allows the web administrator to create web pages using a simple web-based page editor. Each page is known as an article. All of the help pages and the splash page are simple articles that you can edit if you have administrator privileges. There are two primary ways to create and edit articles:

1) Login to the back-end of the web site (assuming you have permissions) and create or edit articles using the 'Content -> Article' menu.

2) Navigate to a page and click the small 'paper and pencil' icon in the upper right corner of the page to bring that page into the editor

CloudStreet Portal uses these articles as templates for displaying your document information to an end-user. You can 'paint' a document page to suit your requires (examples, Invoice, Statement, etc.) Into the article (template) you will put special [placeholder] tags to identify where fields from your document will be injected to the article. Placeholders are indentified in your page by surrounding them with an opening and closing square brackets. At run time, CloudStreet Portal will load the document data for the document and then it will replace each [placeholder] with the text from the document.

You as a document designer simply need to know the [placeholder] names within the document.

Placeholders

There are three types of placeholders available to you as a form designer:

Automatic Placeholders

Automatic placeholders perform tasks such as providing automatic numbing of table rows.

CloudStreet Placeholders

These are placeholders whose values are set by the CloudStreet Portal engine and that are available for you to use within your document templates

The bpi_edoc_header class exposes the header containers for the referenced document

The Division Class exposes information about the division for the referenced document. This values are not passed to CloudStreet Portal via XML but instead are the values that you have created for a division using the 'division' menu option in the administrator menu.

Document-Specific Placeholders

Document-specific placeholders are initialized by your loading scrupt and generally explose the specific containers of your XML document but may contain other placeholders that can perform more advanced functions such as reaching back into the ERP system for real-time updates or status.

See your CloudStreet Portal Administrator for documentation for your specific documents.

EXAMPLE TEMPLATE

[invheader.div_name] [[bpi_edoc_hdr.division_code]] [invheader.div_addr] [invheader.div_city], [invheader.div_state] [invheader.div_zip] [invheader.div_phone]

Manufacturing Plant and Office [invheader.div_city], [invheader.div_state] [invheader.div_addr] [invheader.div_city] [invheader.div_state]

{artdatatable defaultRowCount=500}

{/artdatatable}

Placeholder Formatting Modifiers

Placeholders will inject dynamic data from the referenced document into the template. Sometimes, data being injected may not be in the precise format you desire for end user ease of use. For example, dates are generally stored in unix time/date format ( yyyy-mm-dd HH:MM_SS). This format is foreign to not technical users of the documet so it may be desirable to reformat the date into something more palateable to the end-user. In situations like this, formatting codes can be added to the placeholder to modify the display of the placeholder's data.

Placeholder Documentation

TinyButStrong (TBS) -- The little content engine that could.

CloudStreet Portal provides a Joomla Plug-in known as Tiny But Strong (TBS). The TBS templating engine allows CloudStreet Portal to extend the normal capabilities of Joomla to work more easily and seamlessly with dynamic data you are providing from your ERP host. In the documentation below, you will see references to TBS. This is referring to the CloudStreet Portal TBS Plug-in that allows the placeholder (aka tag) system to function.

<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>The main template</title>
  [onshow.store.default]
</head>
<body>
  Here is a component :
  <div>
    [onload;file=component1.htm;getpart=body;store=(script)+(style)]
  </div>
</body>
</html>

$data = array(
 array('date' => '2013-10-13', 'thin' => 156, 'heavy' => 128, 'total' => 284),
 array('date' => '2013-10-14', 'thin' => 233, 'heavy' =>  25, 'total' => 284),
 array('date' => '2013-10-15', 'thin' => 110, 'heavy' => 412, 'total' => 130),
 array('date' => '2013-10-16', 'thin' => 258, 'heavy' => 522, 'total' => 258),
);
$TBS->MergeBlock('b', $data);

$configuration = array(
 // Name of the parent entity. The process will be limited to this element and its childs.
 'parent' => 'table',
 // Names of tags that must be simply ignored. Such start and ending tags are ignored but childs are not ignored.
 // For elements that must be completely ignored including childs, you just have to not mentioned it in the configuration.
 'ignore' => array('!--', 'caption', 'thead', 'thbody', 'thfoot'),
 // Names of entities recognized as column's definitions, and their span attributes ('' for no span attribute).
 // Such entities must always be placed before the row entities.
 'cols'   => array(),
 // Names of entities recognized as rows.
 'rows'   => array('tr'),
 // Names of entities recognized as cells, and their span attibute ('' for no span attribute).
 'cells'  => array(
   'td' => 'colspan',
   'th' => 'colspan',
  ),
);
// Save the new configuratin with its ID.
$TBS->SetOption('parallel_conf', 'tbs:table',  $configuration);
    

$data = array(
  array('name'=>'Peter', 'spokenlg'=>array( 'US', 'FR' ) ),
  array('name'=>'Paul',  'spokenlg'=>array( 'US' ) ),
  array('name'=>'Jack',  'spokenlg'=>array( 'FR', 'ES', 'IT') ),
);
$TBS->MergeBlock('body', $data);

$data = array();
$data['group1'] = array();
$data['group1'][] = array('id'=>1, 'name'=>'peter');
$data['group1'][] = array('id'=>2, 'name'=>'paul');
$data['group2'] = array();
$data['group2'][] = array('id'=>3, 'name'=>'jules');
$data['group2'][] = array('id'=>4, 'name'=>'jim');

$TBS->MergeBlock('blk', $cnx_id, "SELECT town,country FROM t_geo WHERE (country='%p1%')");

global $data_town; // the coutry code is the main key of the array
$TBS->MergeBlock('blk', 'array', 'data_town[%p1%]');

$TBS->MergeBlock('main', $cnx_id, 'SELECT country,cntr_id FROM t_country');
$TBS->MergeBlock('sub', $cnx_id, 'SELECT town FROM t_town WHERE (cntr_id=%p1%)';

$TBS->MergeBlock('main', $data_county);
global $data_town; // the coutry code is the main key of the array
$TBS->MergeBlock('blk', 'array', 'data_town[%p1%]');

[onload;file=header.htm]
[onload;file=[var.file_header]]
[onload.sub1;file=[val]]
[onload;file=[var.insert;if [val]=1;then 'header.html';else '']]

[onload.file;script=specialbox.php;subtpl]

<?php
  echo('* Here include a subtemplate *');
  $this->LoadTemplate($CurrVal);
  $this->MergeBlock('blk1',$GLOBALS['conn_id'],'SELECT * FROM table1');
  $this->Show(); 
?>

[onload.user_mode;onformat=f_user_info;subtpl]

function f_user_info($FieldName,&$CurrVal,&$CurrPrm,&$TBS) {
  if ($CurrVal==1) { // User is logged in
    $TBS->LoadTemplate('user_info.htm');
    $TBS->MergeBlock('blk1',$GLOBALS['conn_id'],'SELECT * FROM table1');
    $TBS->Show();
  } else { // User not logged in
    echo('You are not logged in.');
  }
}

$TBS->SetOption('block_alias', 'row', 'tr'); // the alias replace one tag
$TBS->SetOption('block_alias', 'dblrow', 'tr+tr'); // the alias replace several tags
$TBS->SetOption('block_alias', 'my_alias', array($myObj, 'findBounds') ); // the alias call a custom function to find the bounds

[blk1;block=row] or [blk1;block=row+row] or even [blk1;block=th+row]
[blk2;block=dblrow]
[blk3;block=my_alias]

class clsTest {
 /** 
  * Function findBound() will be call two times for finding the bounds of the block. Once with $Forward=true, and once with $Forward=false.
  * It is supposed to return the position of the inner bounds of the block. 
  * It can return false if an error occurs of if the template source is inconsistent for finding the block at the given position.
  *
  * @param string  $Tag The name of the block alias
  * @param string  $Txt The source of the template
  * @param integer $Pos The position of the TBS field in $Txt
  * @param boolean $Forward The direction of the search
  * @param mixed   $LevelStop Encapsulation level in a block of the same type. Ignore this in your code if your block type does not support self-encapsulation. 
  * @return integer
  */
	function findBound($Tag, $Txt, $Pos, $Forward, $LevelStop) {
		if ($Forward) {
			return strpos($Txt, '}', $Pos);
		} else {
			return strrpos(substr($Txt, 0, $Pos+1), '{');
		}
	}
}

function tbsdb_XXX_open(&$Source, &$Query) 

function tbsdb_XXX_fetch(&$Rs [,$RecNum]) 

function tbsdb_XXX_close(&$Rs) 

class MyCustomClass {
  function tbsdb_open(&$Source, &$Query) {...}
  function tbsdb_fetch(&$Rs ,$RecNum) {...}
  function tbsdb_close(&$Rs) {...}
}
$Source = new MyCustomClass();
$TBS->MergeBlock($BlockName, $Source, $Query);    

class MyCustomClass {
  function XXX_open(&$Source, &$Query) {...}
  function XXX_fetch(&$Rs ,$RecNum) {...}
  function XXX_close(&$Rs) {...}
  function YYY_open(&$Source, &$Query) {...}
  function YYY_fetch(&$Rs ,$RecNum) {...}
  function YYY_close(&$Rs) {...}
}
$TBS->ObjectRef = new MyCustomClass();
...
$TBS->MergeBlock($BlockName, '~XXX', $Query);

// TBS plug-in XXX 
define('TBS_XXX','clsTbsPlugIng_XXX'); // That is the plug-in's key 
class clsTbsPlugIng_XXX() {
  function OnInstall(...) {...} // That is the OnInstall event 
  ...
}

define('TBS_XXX', 'xxx');
function tbspi_xxx_OnInstall(...) {...}
...