Below are the curl commands necessary to perform an import operation using a CSV file. The steps will:
1. Initiate the import
2. Check its status
3. Get the report information
4. Poll the status of the exception report
5. Get the exception report
6. Parse or copy the errors and warnings to a file
7. Approve the import
8. Check its status one more time.
Be sure to enter a valid username and password. Canadian utilities that login to BEACON via https://beaconama.ca should change the URLs in these samples to api.beaconama.ca.
Verbose curl output has been shortened in the samples below.
# set username and password
$ export BDEUSER="<username>"
$ export BDEPASS="<password>"
# combine them into curl auth parameter
$ export BDEAUTH="-u $BDEUSER:$BDEPASS"
# define destination BDE API host (https://api.beaconama.net)
$ export BDEAPI=https://api.beaconama.net
# (1) create a new import using 'import_file.csv'
$ curl -v $BDEAUTH -F data=@import_file.csv $BDEAPI/v1/bde/import
HTTP/1.1 202 Accepted
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json
Date: Wed, 09 Nov 2016 20:41:03 GMT
Content-Length: 82
Connection: keep-alive
{
"bdeUUID":"6149697131109497959",
"statusUrl":"/v1/bde/import/6149697131109497959"
}
# record BDEUUID returned from the import-call
$ export BDEUUID=6149697131109497959
# (2) check on the status of the import until you see "state"="done"
$ curl -v $BDEAUTH $BDEAPI/v1/bde/import/$BDEUUID
HTTP/1.1 200 OK
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json
Date: Wed, 09 Nov 2016 20:42:21 GMT
Content-Length: 125
Connection: keep-alive
{
"dryRun":true,
"importFile": "import_file.csv",
"reportUrl":"/v1/bde/import/6149697131109497959/report",
"message":"import operation succeeded",
"state":"done"
}
# (3) get the report information
$ curl -v $BDEAUTH $BDEAPI/v1/bde/import/$BDEUUID/report
HTTP/1.1 200 OK
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json
Date: Wed, 09 Nov 2016 20:43:33 GMT
Vary: Accept-Encoding
Content-Length: 401
Connection: keep-alive
{
"mDryRun":true,
"dryRun":true,
"dateCreated":"2016-11-09T20:43:13Z",
"warningCount":5,
"errorCount":5,
"okCount":1,
"originalUrl":"/v1/content/8022223330445118400/imports/6149697131109497959/import_source.txt",
"errorUrl":"/v1/content/8022223330445118400/imports/6149697131109497959/unique_exceptions.json",
"errorSheetUrl":"/v1/content/8022223330445118400/imports/6149697131109497959/import_troubles.csv"
}
# (4) get the Location of the exception report
$ curl -v $BDEAUTH -X GET $BDEAPI/v1/content/8022223330445118400/imports/6149697131109497959/import_troubles.csv
HTTP/1.1 200 OK
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json
Date: Wed, 09 Nov 2016 21:45:33 GMT
Content-Length: 230
Connection: keep-alive
Location: https://bmi-prod-portfolios.s3.amazonaws.com/123456789/imports/6149697131109497959/import_troubles.csv?Signature=abcdefg%3D&Expires=1522769025&AWSAccessKeyId=ASIAABCDEFGHIJKLMN&x-amz-security-token=FQoCVCAPBa904fL/SKiA/cD7/lGvrvZYu4bgvL29KsIsO4p5yPD7u4WLciTgx1h4K4A7huRi4r6uamKhjWhU0YtR65h
...
# (5) Get via the Location header above, do not send authentication
$ curl -v -X GET https://bmi-prod-portfolios.s3.amazonaws.com/123456789/imports/6149697131109497959/import_troubles.csv?Signature=abcdefg%3D&Expires=1522769025&AWSAccessKeyId=ASIAABCDEFGHIJKLMN&x-amz-security-token=FQoCVCAPBa904fL/SKiA/cD7/lGvrvZYu4bgvL29KsIsO4p5yPD7u4WLciTgx1h4K4A7huRi4r6uamKhjWhU0YtR65h
Date: Tue, 03 Apr 2018 15:07:47 GMT
Last-Modified: Tue, 03 Apr 2018 15:07:40 GMT
x-amz-expiration: expiry-date="Thu, 04 Apr 2019 00:00:00 GMT", rule-id="DE expiry"
ETag: "b81ee6536413445da7fc120b3"
x-amz-meta-content-type: text/csv
Accept-Ranges: bytes
Content-Type: binary/octet-stream
Content-Length: 16287
Server: AmazonS3
record number,errors,warnings,account_id,account_first_name,account_last_name,account_full_name,account_email,account_phone,account_phone_extension,billing_address_line1,billing_address_line2,billing_address_line3,billing_city,billing_state,billing_zip,billing_country,person_id,account_status,account_portal_status,account_billing_cycle,location_id,location_name,location_address_parity,location_address_line1,location_address_line2,location_address_line3,location_city,location_state,location_zip,location_county_name,location_country,location_latitude,location_longitude,location_building_type,location_building_number,location_site,location_funding,location_main_use,location_water_type,location_area,location_irrigated_area,location_population,location_irrigation,location_year_built,location_pool,location_bathrooms,location_district,location_dhs_code,location_parcel_number,location_et_jan,location_et_feb,location_et_mar,location_et_apr,location_et_may,location_et_jun,location_et_jul,location_et_aug,location_et_sep,location_et_oct,location_et_nov,location_et_dec,service_point_id,service_point_type,service_point_cycle,service_point_route,service_point_class_code,service_point_class_code_normalized,service_point_latitude,service_point_longitude,service_point_timezone,meter_id,meter_sn,meter_manufacturer,meter_model,meter_size,meter_note,meter_continuous_flow,register_number,register_unit_of_measure,register_resolution,meter_install_date,meter_install_start_read,meter_removal_date,meter_removal_end_read,sa_start_date,sa_end_date,endpoint_sn,endpoint_type,endpoint_install_date,endpoint_removal_date,read_sequence,alert_code,high_read_limit,low_read_limit,utility_use_1,utility_use_2
...
# (6) the list of errors and warnings will be returned in the response body, which you should parse in your code or save to a file and open in a program such as Microsoft Excel.
# (7) approve the same import
$ curl -v $BDEAUTH -X PUT $BDEAPI/v1/bde/import/$BDEUUID
HTTP/1.1 200 OK
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json
Date: Wed, 09 Nov 2016 21:53:12 GMT
Content-Length: 82
Connection: keep-alive
{"bdeUUID":"6149697131109497959","statusUrl":"/v1/bde/import/6149697131109497959"}
# (8) check again on the status of the import
$ curl -v $BDEAUTH $BDEAPI/v1/bde/import/$BDEUUID
HTTP/1.1 200 OK
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json
Date: Wed, 09 Nov 2016 21:53:25 GMT
Content-Length: 126
Connection: keep-alive
