Before You Begin
This document is a reference for the configuration of flat file data sources that are used as input the Connect batch sending system. The information provided here will assist in providing a standardized structure for flat-file inputs to conversions.
As the batch file is highly flexible, this document should be used only as a guide, specific unique requirements should be handled as necessary
Sending Protocol Specifications
We require a Public SSH key from our clients for authentication to the SFTP server. Please provide to your Stella Connect implementation manager, and we will then confirm completion.
- SSH Key Type: RSA key 2048 bits or higher
- DNS name: sftp-v2.stellaconnect.net/
Optional: If PGP is Required
If PGP is required, our Stella Connect Public PGP key allows the client to encrypt the files before sending is as follows (please notify your account manager when doing do):
-----BEGIN PGP PUBLIC KEY BLOCK-----
mQENBF9j4eQBCADBjbg092k62tkMdlMgvdvSjXNob8q/2Y8rQjqE6qDgrcYtg34O
PfEDJhEAhGVU+93QBH4lgTrrz2WScn2dFf69Kw+ZcGrRbGKa+YP7o0xbqLfCKOve
KkjDaGqXgGi8wr4SfCAihlBm2tQAsdZIoxpeLIOkEF/LIiR8nisTw12WIcrGGRJy
bftWGXbLoJZWCKrhv/GSgbfgUIIxWjZSoEpEF3LNn/8wvcWBjCNnYRj63DA1yTg8
67iuiDPZZ5hh/mny/+FC5VuMRZxGJmux8+lq1h04Qc21DIIOF+4hSU1yE6j959vT
VmNhjquWFWeBk0R7VcmKt0vBFXyDPN47NJR5ABEBAAG0DVN0ZWxsYUNvbm5lY3SJ
AVQEEwEIAD4WIQRbfPqvBiSU3gCDbviPoEUMwlCh1gUCX2Ph5AIbAwUJA8JnAAUL
CQgHAgYVCgkICwIEFgIDAQIeAQIXgAAKCRCPoEUMwlCh1kX1B/4vJcKs4VOn1JXX
8/0foh6PSquI2xuxseTKmJSLXECU0U4ycBshzszsXvbnO7eFqNJO6B1Ui+chiTmN
wOeBqVt+Pcmg91cOYV5cfWcmou0CoZQkDiaqYRPiyPkMIAGb6RAHO9GXt21NSzW1
k+aoyqgvlX86baPy5q9Bg70JuSkBMEn6xwCc7kZIej367KlTR/PF1H6pyXVSGFfe
UujMGQMrxQG2pwj75V5sQPihhkwpt0ZSl7tEUVPsOlOn7TIiGHQcOdWInbcaNQ27
YMxyoVHDARHMT55vZ61h9wBeWJ33cP9ZNmL34xKz9xyG/I/oQ6pJMjtrekN++yII
f0+b/pdwuQENBF9j4eQBCADhlQpuQHnZmJve76jdSIlFAvr8hCqdDVqbbU9BDiNv
AcHhQWDS2quh6I99PQQsBybdtdwyLirsj1F4PjsUih2pqb41GoHasjdbPb4x88Mw
WPmS9NoBIQj5IBN4AGjNjRJzTPIt11fRChwAurS9Q2oaZTDlwqB2FkR+0tYxfWoa
PLmHCbJ6xIabtKASJwvNKpm59aXgX+foW24F8M9yH7xDySSf7I1wKUZLGLPGWcCl
034n/zI5gRHNnNyFqb4XSkLNSKDwOmKJdGHZBc6sYBuSPCJp0TH2r2lwJ8w698rz
eLDUGCKeRDqz903h1aad7L+PVt5Kz4KSoEKg9m/OL2EZABEBAAGJATwEGAEIACYW
IQRbfPqvBiSU3gCDbviPoEUMwlCh1gUCX2Ph5AIbDAUJA8JnAAAKCRCPoEUMwlCh
1p2wB/98BcSMZsE1KJfHYvcW6M5szFa2nbEhdpmrFumMnc18G8VJzcMlg2kUdlOO
+WVL4lDnFOqKbN8bpl+MurND+tAPu8jHqXwsDBfpxeXX45aIMITaDVJf8PhdWx2S
F9KxWmV+bptUmEA9eiwiP95y4nJpde+vuaNkCuNWx+7ynpdijaNA87fKM4MRsE+R
6jJF3xdcGMIGhcTfj7v1fQExDaaXEjq4PkwEjpoGgIS9KVbNVwO3nFbGlLDCCK2f
fcrCLVAAhW0qaIy9kmauO/Z1XBCkVOJykm+n0Clv8g1vmP4jkIZ2ZhnttBfWW3gR
i8EBQI/QHT2tmO0Kedn8wcyHir/e
=eWLf
-----END PGP PUBLIC KEY BLOCK-----
Key expires: 9/17/2022
File Naming Conventions
All files delivered should have a name with one of the following structures.
- CSV files
<company_subdomain>_yyyymmddhhmmss.csv - PGP files
<company_subdomain>_yyyymmddhhmmss.csv.gpg
Your "<company_subdomain>" is a unique name for a data source that will not change and can be referenced within the Connect application to uniquely identify the company the batch file is used, if you need help please contact your client services manager.
Character Codes
All files should be in ASCII format. Files should not contain any non-readable characters.
Batch File - Field Delimiter
A field delimiter must be chosen. The preferred delimiter is the “|” (‘pipe’) character.
However, to use the “|” as a delimiter, it must be guaranteed that “|” will never occur naturally in any of the data in the file. If this is not possible, another delimiter must be chosen which satisfies this constraint. Once chosen, this character will be known as the ‘field delimiter’.
Batch File - String Data Type
The string data type should be wrapped in opening and closing quotation marks (“”).
An example of a string data type:
“this is a string”
Batch File - Boolean Data Type
The boolean data type only has valid values of: "true" or "false"'.
They should be wrapped in opening and closing quotation marks (“”).
An example of a boolean data type:
“true”
Batch File - Array Data Type
The array data type is a collection of string data types that are separated by a comma (‘,’).
They should be wrapped in opening and closing quotation marks (“”).
They should not contain spaces, leading, trailing, or in between words.
To separate words, dashes (-) or underscores (_) can be used.
An example of an array data type:
"product-defect,return,vip"
Batch File - Header Row
The first row of the file should be a header row that denotes field labels. This is a delimiter record that names each field in the Data section. This is the ‘schema’ for the data.
The position (left to right order) of each field label must correspond to the position of the data for that field in the Data section. The field labels are delimited by the chosen field delimiter.
Field labels should be wrapped in opening and closing quotation marks (“”).
The Header row must be delimited by a newline character (‘\n’).
An example of a header row:
“customer name”|”customer email”|”employee email”|”do not send”|”channel”|”external interaction id”|”external url”|”tags”
Batch File - Data Row
The second and all subsequent rows are the data section. Each row must be homogenous, containing the same number of fields in each row, each field having the same meaning in each row and matching the field labels in the header row. Each field is delimited by the chosen field delimiter.
Field labels should be wrapped in opening and closing quotation marks (“”).
Each Data row must be delimited by a newline character (‘\n’).
An example of a data row:
“Simone”|”simone@example.com”|”paul@blancapeak.com”|”false”|”chat”|”49288523”|"https://blancapeak.your-source-system.com/cases/49288523"|”product-defect,return,vip"
Batch File - Suggested Rows
The following fields and rows are suggested in the flat file.
Fields in bold are required for our system to successfully process a valid request.
customer
- custom_id
- name
do_not_send
language
tags
country
brand
external_interaction_id
Employee (Only one of either custom_id or email)
- custom_id
channel
external_url
For an explanation of these fields click here
Batch File - Sample CSV File
Filename: blancapeak_20180828.csv
Decided field delimiter: “|”
CSV content:
"customer name"|"customer email"|"employee email"|"do not send"|"channel"|"external interaction id"|"external url"|"tags"
“Simone"|"simone@example.com"|"paul@blancapeak.com"|"false"|"chat"|"49288523"|"https://blancapeak.your-source-system.com/cases/49288523"|"product-defect,return,vip"
“John"|"john@example.com"|"paul@blancapeak.com"|"false"|"chat"|""|""|"return"
“Jane"|"jane@example.com"|"paul@blancapeak.com"|"false"|"chat"|"112233"|"https://blancapeak.your-source-system.com/cases/112233"|"return,vip"
Uploading and Next Steps
We always advise uploading one sample file first after following all of the above recommendations before going-live. This allows us to map the .csv headers to the relevant data points in Stella Connect to confirm surveys will be processed correctly. We will then re-process the file on our end and then work with you on a go-live date/time.
Comments
0 comments
Please sign in to leave a comment.