- TLC Home Home
- Discussions & Ideas Discussions & Ideas
- Product Guides Product Guides
- Knowledge Base Knowledge Base
- Developer Docs Developer Docs
- Education Education
- Blog TLC Blog
- Support Desk Support Desk
The Omnichannel File Status API provides detailed status information for your Omnichannel Files. The API is available to AudienceStream-enabled accounts only. This article assumes you have already uploaded the Omnichannel Files in your AudienceStream profile.
The API returns a File Status that details when the files imported and how they were processed, including any processing errors. A File Status is represented as a JSON object containing the following keys:
Name | Type | Description |
---|---|---|
account | string | Name of the AudienceStream account |
profile | string | Name of the profile (in the account) where your files are uploaded and processed |
created at | UTC timestamp | date and time when the file status was created (expressed in UTC format with the designator 'Z') |
file.name | string | Name of the file in question |
file.size | integer | File size in bytes |
file.source-type | string | Service used for uploading the file: FTP, SFTP, Tealium S3, and S3 |
file.source-host | string | Name of the service
|
line_count | integer | Number of rows in the file |
status.state | string | Indicates the processing action on the file. Possible values are: DOWNLOADING, DOWNLOADED, PROCESSING, or PROCESSED. |
status.timestamp | UTC timestamp | date and time when the [status-state] was recorded (expressed in UTC format with the designator 'Z') |
lines_successfully_processed | integer | Number of rows parsed successfully |
lines_skipped | integer | Number of rows that could not be parsed due to missing data |
lines_failed_processing | integer | Number of rows that could not be parsed due to bad data or incorrect formatting |
last_failure | string | Error due to which the row/file could not be processed (Refer to Error Glossary and Troubleshooting link_here) |
Sample File Status
{ "account": "company_xyz", "created_at": { "$date": "2016-04-04T22:27:56.993Z" }, "file": { "name": "sales-transaction_2016feb4v50.csv", "size": 2744, "checksum": "44b12d35ea9fffdeeb69f98b03004f22", "source": { "type": "s3", "host": "companyxyz:" }, "line_count": 35 }, "node_id": "bulk_downloader_i-cd504b49", "profile": "omnichannelv2", "status": [ { "state": "DOWNLOADING", "timestamp": { "$date": "2016-04-04T22:27:57.285Z" } }, { "state": "DOWNLOADED", "timestamp": { "$date": "2016-04-04T22:27:57.722Z" } }, { "state": "PROCESSING", "timestamp": { "$date": "2016-04-04T22:27:57.780Z" }, "lines_skipped": 34 }, { "state": "PROCESSED", "timestamp": { "$date": "2016-04-04T22:27:58.797Z" } } ] }
Returns the count of uploaded files. Only applies to files with the same file prefix.
The following query parameters are used:
GET /v1/omnichannel/accounts/{account}/profiles/{profile}/files/count?utk={utk token}&filePrefix={file prefix}&startDate={start date}&endDate={end date}
Curl Request
curl -i -b JSESSIONID={session_id} \ https://api.tealiumiq.com/v1/omnichannel/accounts/{account}/profiles/{profile}/files/count?utk={token}&filePrefix={file prefix}&startDate={start date}&endDate={end date}
If the file count exceeds 50, try narrowing the date range parameters.
Example Response
{ "count" : 42 }
Error Messages
Error Type | Description |
---|---|
400 Bad request |
|
GET /v1/omnichannel/accounts/{account}/profiles/{profile}/files/{file name}?utk={utk token}
Curl Request
curl -i -b JSESSIONID={session_id} \ https://api.tealiumiq.com/v1/omnichannel/accounts/{account}/profiles/{profile}/files/{filename}.csv?utk={utk token} \ -o {filename}.txt
Example Response
{ "_id": { "$oid": "5702ea6db993f8f8cbea334c" }, "account": "acme", "created_at": { "$date": "2016-04-04T22:27:56.993Z" }, "file": { "name": "sales-transaction_2016feb4v50.csv", "size": 2744, "checksum": "44b12d35ea9fffdeeb69f98b03004f22", "source": { "type": "s3", "host": "johndoe:" }, "line_count": 35 }, "node_id": "bulk_downloader_i-cd504b49", "profile": "main", "status": [ { "state": "DOWNLOADING", "timestamp": { "$date": "2016-04-04T22:27:57.285Z" } }, { "state": "DOWNLOADED", "timestamp": { "$date": "2016-04-04T22:27:57.722Z" } }, { "state": "PROCESSING", "timestamp": { "$date": "2016-04-04T22:27:57.780Z" }, "lines_skipped": 34 }, { "state": "PROCESSED", "timestamp": { "$date": "2016-04-04T22:27:58.797Z" } } ] }
Error Messages
Error Type | Description |
---|---|
404 Not Found | Supplied file name not found |
400 Bad request | File name exceeds 150 chars |
Returns an array of file statuses within the specified date range. Only applies to files with the same file prefix.
GET /v1/omnichannel/accounts/{account}/profiles/{profile}/files/search?utk={utk token}&filePrefix={file prefix}&startDate={start date}&endDate={end date}
Curl Request
curl -i -b JSESSIONID={session_id} \ https://api.tealiumiq.com/v1/omnichannel/accounts/{account}/profiles/{profile}/files/search?utk={token}&filePrefix={file prefix}&startDate={start date}&endDate={end date} \ -o {filename}.txt
Example Response
Below is a sample file status for three files that are all prefixed by "sales-transaction". Each file prefix is followed by "_" and a unique date identifier. Each file entry contains information about the file size, line count (i.e. number of rows) and number of lines processed (including any processing errors).
[ { "_id": { "$oid": "5702ea6db993f8f8cbea334c" }, "account": "acme", "created_at": { "$date": "2016-04-04T22:27:56.993Z" }, "file": { "name": "sales-transaction_2016feb4v50.csv", "size": 2744, "checksum": "44b12d35ea9fffdeeb69f98b03004f22", "source": { "type": "s3", "host": "johndoe:" }, "line_count": 35 }, "node_id": "bulk_downloader_i-cd504b49", "profile": "main", "status": [ { "state": "DOWNLOADING", "timestamp": { "$date": "2016-04-04T22:27:57.285Z" } }, { "state": "DOWNLOADED", "timestamp": { "$date": "2016-04-04T22:27:57.722Z" } }, { "state": "PROCESSING", "timestamp": { "$date": "2016-04-04T22:27:57.780Z" }, "lines_skipped": 34 }, { "state": "PROCESSED", "timestamp": { "$date": "2016-04-04T22:27:58.797Z" } } ] }, { "_id": { "$oid": "5702ea6bb993f8f8cbea334b" }, "account": "acme", "created_at": { "$date": "2016-04-04T22:27:55.562Z" }, "file": { "name": "sales-transaction_2016feb4v49.csv", "size": 2744, "checksum": "7b8f92474e220c275bf9931c0337abf3", "source": { "type": "s3", "host": "johndoe:" }, "line_count": 35 }, "node_id": "bulk_downloader_i-cd504b49", "profile": "main", "status": [ { "state": "DOWNLOADING", "timestamp": { "$date": "2016-04-04T22:27:55.601Z" } }, { "state": "DOWNLOADED", "timestamp": { "$date": "2016-04-04T22:27:55.887Z" } }, { "state": "PROCESSING", "timestamp": { "$date": "2016-04-04T22:27:56.045Z" }, "lines_skipped": 34 }, { "state": "PROCESSED", "timestamp": { "$date": "2016-04-04T22:27:56.669Z" } } ] }, { "_id": { "$oid": "5702ea69b993f8f8cbea3349" }, "account": "acme", "created_at": { "$date": "2016-04-04T22:27:53.276Z" }, "file": { "name": "sales-transaction_2016feb4v53.csv", "size": 2744, "checksum": "44b12d35ea9fffdeeb69f98b03004f22", "source": { "type": "s3", "host": "johndoe:" }, "line_count": 35 }, "node_id": "bulk_downloader_i-cd504b49", "profile": "profile", "status": [ { "state": "DOWNLOADING", "timestamp": { "$date": "2016-04-04T22:27:53.307Z" } }, { "state": "DOWNLOADED", "timestamp": { "$date": "2016-04-04T22:27:54.249Z" } }, { "state": "PROCESSING", "timestamp": { "$date": "2016-04-04T22:27:54.289Z" }, "lines_skipped": 34 }, { "state": "PROCESSED", "timestamp": { "$date": "2016-04-04T22:27:55.480Z" } } ] },
Error Messages
Error Type | Description |
---|---|
400 Bad request |
|
File processing can fail for many reasons: invalid service credentials, missing row data, internal server error, etc. In the File Status, these specific errors are logged in the value of the last_failure
key.
Here's a truncated sample of a file status:
... { "state": "PROCESSING", "timestamp": { "$date": "2016-10-05T18:09:54.014Z" }, "lines_failed_processing": 1, "last_failure": "Failed to find attribute for column with id" }, ...
Below listed errors are specific to Omnichannel Files; they are different from the API endpoint errors.
Error message | What does it mean | How to resolve |
---|---|---|
Unknown file prefix, unable to parse file | File for the supplied prefix (name) could not be found. Either the file doesn't exist or there is a typo in the prefix. | Re-upload the file and double check the file prefix in the Omnichannel Definitions tab. If the error persists, please contact your Tealium Account Manager. |
DBObject of size {###} is over Max BSON size {###} | File is too large to be processed | Split up your file data into multiple file definitions |
Failed to download (FTP, SFTP, S3) file | File could not be downloaded due to errors in your service credentials (see Omnichannel Configuration tab). |
|
Invalid connection type OR Could not find required (FTP, SFTP, S3) configuration parameters for definition |
Your service credentials (under Omnichannel Configuration tab) could not be authenticated. |
|
These errors are caused by incorrect column mappings in the Definitions tab.
Error Message | What does it mean | How to resolve |
---|---|---|
Failed to find attribute for column with id | AudienceStream could not generate an Omnichannel Attribute for the column name you mapped. | Replace the offending column header with a fresh instance and re-upload the file |
Exception thrown while processing file | Unable to parse the value of your mapped column header into the Omnichannel Attribute | Replace the offending column value and re-upload the file. |
Secondary visitor ID column= {column_name_here} does not exist in the file, unable to continue | The column header you mapped to the Visitor ID field does not exist in your file. This could be due to a typo or the header is not defined. | Make sure the column header you supplied matches what is in the file |
{date_format_here} could not be parsed as a Date | The date format you specified for the mapped column name does not exist in your file. | Make sure the date format you supplied matches what is in the file |
The number of columns to be processed {##} must match the number of CellProcessors {##}: check that the number of CellProcessors you have defined matches the expected number of columns being read/written | The column names you mapped under Omnichannel Attributes do not exist in your file. This could be due to a typo or the header is not defined. | Make sure the column header you supplied matches what is in the file |
These errors occur when the different servers processing your files are unable to communicate with each other.
Resolution: Re-upload your file(s).
Copyright All Rights Reserved © 2008-2021