Cloudstreet Portal comes with a document importer that reads XML data input.
Your system will need to generate the XML as follows:
- One XML file for each document
- The filename must end in ".xml"
- The filename must be unique and should be salted with recognizable elements such as
- <docType>_<divisionCode>_<customerId>_<docReference>.xml
- Example: inv_050_1000_12345-170101.xml
- The file content must follow our prescribed XML schema described in this document
- You may transmit the XML file to the portal using
- ftp/sftp (recommended)
- http (post)
The XML Schema
The XML may be any valid XML however we recommend that for at least the <csp_header> container, that all tags be present even if you do not intend to use them. This makes the XML easier to compare and eliminates questions about whether containers were intentionally or unintentionally omitted. Since the tag names used within our document template articles are derived from these XML container names, having them present ensures that they will be loaded and ready for all documents, even if the tag contains nothing. This allows for fewer 'exceptions' when modeling document templates and can streamline your development of new templates.
Basic Rules for XML Values
Must be valid XML
When developing your XML files, the easiest way to validate them is to use an on-line XML validator. Simply copy/paste your XML into the validator and press 'validate'. The Validator will show you the errors in your XML or declare it to be valid. An XML validator that we use commonly is at http://www.xmlvalidation.com/
Monetary Values
You should include only the numerals and a decimal (if applicable). Do not embed currency symbols or commas. There are masking options in the template creator that will allow you to inject commas into your numeric values. Keeping the numerics pure can make it easier to format the data for presentation and allow other power functions such as filtering and ordering within Javascript.
Dates
We need dates to be presented within the XML as a valid Unix Time Date format. This means yyyy-mm-dd HH:MM:SS. You do not necessarily have to specify the time portion and in those cases, midnight will be assumed (00:00:00). However, the year must be four digit numeric, the month must be two digit numeric and the day must be two digit numeric. In the template editor, masking options will allow you to display the date in any valid date format you wish. But for the purposes of filtering and ordering, the dates should be passed in the Unix Time Date format to ensure smooth operation and full functionality. Passing dates as strings, will not allow for proper filtering or ordering of those fields and will prevent the use of features such as the pop-up calendars that are a part of the user interface.
<doc_reference>
The <doc_reference> container within the <csp_header> container must contain a value that is unique for this document. Refer to the first section of this article for a recommendation for the doc_reference.
Sections within the XML
The XML schema consists of two main containers:
| Container Section | Description |
| <csp_header> |
The container that holds all metadata used by CloudStreet Portal to index the document within the document database and to control import and admin operations. Each of these containers has a corresponding field within the document editing and view functions on the portal web site. We recommend that every container be defined whether you intend to use it or not. |
| <csp_document> | The container that holds all of your document payload. You may place any valid XML within this container |
Container Definitions
| Parent | Container Name | Req | Value | Description |
| <csp_header> | <csp_version> | Y | Recommended | This contains the version of CloudStreet Portal's XML specification used when generating this document. Currently, the value of 1.0 is appropriate. This can be helpful over time if the cloudstreet portal xml schema is changed with upgrades to ensure that there is a clear way to separate documents generated at various cloudstreet portal releases. Currently a value of 3.0 is recommended. |
| <csp_header> | <date_time> | Y | Recommended | This is the time that the xml was generated. This is not the document transaction date. See date rules (above) |
| <csp_header> | <doc_parent> | Y | Optional | Can be used in cases where a document is a child of a parent document such as a invoice that is the child of a statement for example. This should contain the <doc_reference> value of the parent document. |
| <csp_header> | <operation> | Y | Required | This is the database operation to be performed. Possible values are insert, update, delete, upsert. The import utility uses this value to determine the database operation to perform against the <doc_reference> record in the database. The stock importer considers insert to be upsert. No delete operation is performed by the standard importer. We recommend setting this field to 'insert' for all insert or update operations when using the standard importer. |
| <csp_header> | <expiration> | Y | Optional | Not currently supported in CloudStreet Portal, this function may be implemented in the future. This will allow the host system to declare the date that the document will expire. This date can be used for taking document off-line or purging it from the database. This date must be encoded using the date rules described above. |
| <csp_header> | <last_access_id> | Y | Recommended | We recommend passing the value zero (0) to the importer. It will then update the last access user id to zero in the metadata. This value will be updated each time the document is accessed and the user id will be placed in this field. |
| <csp_header> | <last_access_date> | Y | Recommended | We recommend that this container hold the date that the xml file was generated in unix time date format yyyy-mm-dd HH:MM:SS |
| <csp_header> | <division_code> | Y | Required | This is the division code for this document. The division codes must be defined in the divisions table (see Site Administation > Divisions). The importer will look-up the division code in the division table and validate that it is correct before allowing the import of this document. If the division code passed is not found in the division table, the xml file will be passed into the csp_error folder. |
| <csp_header> | <doc_type> | Y | Required | This is the document type name (e.g., invoice, statement). This document type name must be defined in the document_type table (see Site Administration > Document Types). The importer will look-up the document type for the division passed in <division_code>. If it does not find the <document_type> passed has been defined for this <division_code> then the importer will reject the document and place the xml file into the csp_error folder. |
| <csp_header> | <doc_reference> | Y | Required | This is a primary key for the document and must be unique. If the <doc_reference> value already exists in the database, then the document will overlay the existing document in the document database. We recommend the construction of a doc_reference that includes division_code, document_type, customer_id, and perhaps additional values that will ensure that the <doc_reference> value is unique. See the example in the sample XML below. |
| <csp_header> | <doc_version> | Y | Recommended | This container can be used to hold a version number for the document passed. This is not to be confused with <csp_version> which contains the version of XML required by cloudstreetportal, this container can be used for you to track versions of the xml payload that you pass within the <csp_document> container. |
| <csp_header> | <doc_status> | Y | Recommended | This contains a status that you wish to assign to the document. CloudStreet Portal does not ascribe any meaning to the status. It is a field intended for user convenience and for any purpose you wish. |
| <csp_header> | <doc_parser> | Y | Optional | Future release. Recommend you leave this blank. |
| <csp_header> | <assigned_to> | Y | Optional | This is a convenience field intended to be used in cases where you wish to assign certain document or accounts to different administrators for review and management. |
| <csp_header> | <doc_stage> | Y | Required | This should contain the word 'published'. It is used by CloudStreet Portal to determine if a document should be on-line or off-line. Other values include 'unpublished' |
| <csp_header> | <trans_date> | Y | Required | This must contain the transaction date of the document. For invoices, this is normally the invoice date. Even if you have this date defined within your own container in <bpi_edoc_document> you must ALSO include that date in this container. You must follow unix date time convention of yyyy-mm-dd HH:MM:SS. If the time portion of the Date Time is omitted, midnight will be assumed. |
| <csp_header> | <rep_reference> | Y | Optional | If this document is associated with a representative at your company (e.g., a sales person) then place their salesperson code in this field. This will allow you to add content such as a photo of the sales person, contact information or even a skype link to your document. |
| <csp_header> | <rep_name> | Y | Optional | Related to <rep_reference> is the abilty to place additional information such as the full name of the representative associated with this document. |
| <csp_header> | <reference> | Y | Optional | Another field for your use. You may place additional information such as a project id or cost center code (or anything else) in this container. |
| <csp_header> | <cust_id> | Y | Required | This contains the customer id associated with the document. This value is matched to the customer id placed into the user's subscriptions. It is imperative that the <customer_id> passed in the XML exactly match the customer id in the subscription record including any zero padding or special characters. For example, 0123 does not match 123 and 1-23 does not match 123. It must be an exact match. |
| <csp_header> | <cust_rep_ref> | Y | Optional | This can contain the name of the person at the client (customer's) location that is associated with the document. This can be a code or a name or any other data |
| <csp_header> | <cust_ref> | Y | Optional | This can contain a customer provided reference associated with this document. For invoices, this is commonly the customer's purchase order or contract number. |
| <csp_header> | <total_value> | Y | Recommended | If there is a 'value' (monetary, point, grading or other metric) associated with this document, we recommend placing it here. Common use of this container is to place an invoice or statement total. This becomes part of document's metadata and is searchable, filterable and the user can order his documents based on value. It is highly recommended, even if you have a total within the <csp_document> container to duplicate that value into this container. |
| <csp_header> | <doc_erp_status> | Y | Optional | This can hold a status from the ERP system (pushed to the portal as an update to the record). It can contain the current status of the document on the ERP system. Possible values include 'open', 'unpaid', 'paid', 'canceled', 'delivered' or whatever you can imagine is applicable for this type of document. |
| <csp_header> | <doc_checksum> | Y | Optional | This can hold a checksum that you can generate on the ERP server. It can be retrieved within the loading script to validate that the content of the XML has not been manually altered from its original form. |
| <csp_header> | <doc_tags> | Y | Optional |
These are word tags that will be loaded into a tag field to facilitate searching of documents. The tags may be any value you wish to use. For example (net30,special_terms,hazmat, zip12345 etc.). Separate each tag with a comma |
| <csp_header> | <user1_text> | N | Optional |
An indexed field into which you can pass text. Added at release 5.2 |
| <csp_header> | <user2_text> | N | Optional |
An indexed field into which you can pass text. Added at release 5.2 |
| <csp_header> | <user3_text> | N | Optional |
An indexed field into which you can pass text. Added at release 5.2 |
| <csp_header> | <user4_text> | N | Optional |
An indexed field into which you can pass text. Added at release 5.2 |
| <csp_header> | <user5_text> | N | Optional |
An indexed field into which you can pass text. Added at release 5.2 |
| <csp_header> | <user6_text> | N | Optional |
An indexed field into which you can pass text. Added at release 5.2 |
| <csp_header> | <user7_text> | N | Optional |
An indexed field into which you can pass text. Added at release 5.2 |
| <csp_header> | <user8_text> | N | Optional |
An indexed field into which you can pass text. Added at release 5.2 |
| <csp_header> | <user8_date> | N | Optional |
An indexed field into which you can pass a date. Added at release 5.2 |
| <csp_header> | <user9_date> | N | Optional |
An indexed field into which you can pass a date. Added at release 5.2 |
| <csp_header> | <notification> | N | Optional |
Pass a notification date in the format yyyy-mm-dd HH:mm:ss to the portal. By not sending this container or and empty container, the portal will mark the document that users subscribing to it should be notified. After the users are notified, the portal will automatically update this field with the date and time that the notifications were sent to users. If you do not want notifications to be sent to users (for example, when an update to the document is sent to the portal), then pass in a date and time in the format specified above and it will prevent the portal from sending notifications to subscribed users. |
| <csp_header> | <user_notes> | N | Optional |
Normally, user notes are entered by the user on the portal and you will not pass user_notes from the server. If you do not pass the <user_notes> container in the XML payload, or if you pass the container that is empty, then the user_notes that exist in the database on the portal will be preserved even when a document is updated. If you pass a value within the <user_notes> container, then it will overwrite the user_notes field in the portal database. |
Sample XML for an Invoice
<document_root>
<csp_header>
<csp_version>1.0</bpi_edoc_version>
<date_time>2017-05-25 23:00:09</date_time>
<doc_reference>inv.1390.11-754140</doc_reference>
<doc_parent></doc_parent>
<operation>insert</operation>
<expiration></expiration>
<last_access_id>0</last_access_id>
<last_access_date>2017-05-25 23:00:09</last_access_date>
<doc_type>invoice</doc_type>
<doc_version>v2017-05-25 23:00:09</doc_version>
<doc_status>0</doc_status>
<doc_parser></doc_parser>
<assigned_to>436</assigned_to>
<doc_stage>published</doc_stage>
<trans_date>2017-05-25 00:00:00</trans_date>
<rep_reference>436</rep_reference>
<rep_name>436</rep_name>
<reference>436</reference>
<cust_id>1390</cust_id>
<cust_rep_ref></cust_rep_ref>
<cust_ref>5061</cust_ref>
<total_value>286.02</total_value>
<doc_erp_status></doc_erp_status>
<doc_checksum></doc_checksum>
<edoc_tags></edoc_tags>
</csp_header>
<csp_document>
<invheader>
<store_no>11</store_no>
<store_name>Smyth - Hillsboro</store_name>
<store_addr>220 West Main Street</store_addr>
<store_addr2></store_addr2>
<store_city>Hillsboro</store_city>
<store_state>OH</store_state>
<store_zip>45133</store_zip>
<store_country>USA</store_country>
<store_email></store_email>
<store_phone>9373935737</store_phone>
<store_fax></store_fax>
<store_user1></store_user1>
<store_user2></store_user2>
<store_user3></store_user3>
<cust_no>211-020</cust_no>
<cust_name>WEST MAIN AUTO REPAIR</cust_name>
<cust_addr>949 WEST MAIN STREET</cust_addr>
<cust_addr2></cust_addr2>
<cust_city>HILLSBORO</cust_city>
<cust_state>OH</cust_state>
<cust_zip>45133</cust_zip>
<cust_country>USA</cust_country>
<cust_email></cust_email>
<cust_phone>9373935562</cust_phone>
<cust_fax></cust_fax>
<cust_po>5061</cust_po>
<inv_no>11-754140</inv_no>
<inv_date>2017-05-25 00:00:00</inv_date>
<inv_print></inv_print>
<inv_writer>436</inv_writer>
<inv_freight></inv_freight>
<inv_labor></inv_labor>
<inv_tax>0.00</inv_tax>
<inv_subtotal>0.00</inv_subtotal>
<inv_total>286.02</inv_total>
<inv_total_qty>1</inv_total_qty>
<inv_total_core>0.00</inv_total_core>
<inv_total_list>579.62</inv_total_list>
</invheader>
<invdetail>
<invline>
<qty></qty>
<line></line>
<part_no></part_no>
<desc></desc>
<core_chg></core_chg>
<list_price></list_price>
<net_price></net_price>
<ext_price></ext_price>
<comment>VEHICLE 34240 - 2007 CHEVROLET TAHOE V8-5328cc 5.3L F/I Vin J</comment>
<url1></url1>
<url2></url2>
<url3></url3>
<user1></user1>
<user2></user2>
<user3></user3>
</invline>
<invline>
<qty>1</qty>
<line>DPH</line>
<part_no>FG0808</part_no>
<desc>Fuel Module</desc>
<core_chg></core_chg>
<list_price>579.62</list_price>
<net_price>286.02</net_price>
<ext_price>286.02</ext_price>
<comment></comment>
<url1></url1>
<url2></url2>
<url3></url3>
<user1></user1>
<user2></user2>
<user3></user3>
</invline>
</invdetail>