Create a bulk job

In this tutorial we create a bulk job, to add multiple devices at once

Prerequisites

• A valid HERE account user
• A valid Tracking project

Log in user

Create a bulk job using CSV file

After a successful API call, the user obtains a new "jobId", which can then be used to get the job status and results. It can also be used to cancel the job.

curl -X POST \
    'https://tracking.api.here.com/bulkjobs/v4/deviceUploads?fileName=file.csv' \
    -H 'Content-Type: text/csv' \
    -H 'Authorization: Bearer {userToken}' \
    -d @file.csv

Example CSV

name,deviceId,externalDeviceId,connectorId,sendMs,sampleMs,distanceM,areaBased,type,tag:priority1,tag:priority2,tag:food,tag:Fragile,rule:74a6fe54-2077-4629-b924-3340bc88b864,rule:c096874c-0d5f-41c8-9cd8-56c25f9df23b,rule:db9403d1-64b4-48c0-a0e7-bc5f69eb624f,geofence:08e742fc-52d1-49aa-bea0-60a6cd17d8a2,geofence:2bff17e2-af05-4843-9780-878df098d35a
my at4h tracker in distance based mode,a19b2648-60c1-49fc-896c-ea450a07e98d,,,600000,300000,100,,Phone,1,,,,1,,,1,1
my super tracker in area based mode,13316aa5-3b80-414c-bf6d-86fa3ca6a31f,,,600000,100000,,1,Returnable / Reusable,,1,1,,1,1,,1,1

{
    "jobId": "BULK-6279286f-a09a-4521-9d3a-af7559e84836"
}

Create a bulk job using JSON

curl -X POST \
    'https://tracking.api.here.com/bulkjobs/v4/deviceUploads' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '[
          {
            "name": "my at4h tracker in distance based mode3",
            "sendMs": 600000,
            "sampleMs": 300000,
            "distanceM": 100,
            "type": "Phone"
          },
          {
            "name": "my c2c tracker in distance based mode3",
            "externalDeviceId": "1e50ed8d-c291-4f16-8a51-86fe03267496",
            "connectorId": "cf208b96-ef0b-4227-a3ee-224679cce07a",
            "type": "Custom type"
          }
        ]'

{
    "jobId": "BULK-5ef183dc-15f2-4b2a-959d-0e157f308ca5"
}

Create a bulk job for deleting devices using JSON

Possible variants of data:

1. Tracking ID variant: { trackingId: Tracking ID of the device we want to delete, unclaimOnly?: Flag that informs if we should only unclaim the device or also unprovision it }
2. External ID variant: { externalId: Virtual device external ID, unclaimOnly?: Flag that informs if we should only unclaim the device or also unprovision it }
3. Connector ID + external device ID variant: { connectorId: Identifier of the connector, externalDeviceId: Identifier of the device on the external cloud, unclaimOnly?: Flag that informs if we should only unclaim the device or also unprovision it, removeFromConnectorOnly?: Flag that informs if we should only remove external device from connector or also remove virtual device from tracking cloud }

curl -X POST \
    'https://tracking.api.here.com/bulkjobs/v4/deviceUploads' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '[
          {
            "externalId": "MyDevice1",
            "unclaimOnly": "true"
          }
        ]'

{
    "jobId": "BULK-e34eca5b-fdde-423b-b3d2-1656ac0c8952"
}

Get the bulk upload job IDs for a project

curl -X GET \
    'https://tracking.api.here.com/bulkjobs/v4/deviceUploads?projectId={projectId}' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}'

{
    "limit": 100,
    "items": [
        {
            "jobId": "BULK-6279286f-a09a-4521-9d3a-af7559e84836",
            "status": "pending"
        },
        {
            "jobId": "BULK-5ef183dc-15f2-4b2a-959d-0e157f308ca5",
            "status": "ongoing"
        },
        {
            "jobId": "BULK-e34eca5b-fdde-423b-b3d2-1656ac0c8952",
            "status": "completed"
        }
    ],
    "count": 3
}

Gets bulk upload status

curl -X GET \
    'https://tracking.api.here.com/bulkjobs/v4/deviceUploads/{jobId}/status' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}'

{
    "status": "pending",
    "progress": 0,
    "total": 0,
    "succeeded": 0,
    "failed": 0,
    "partiallySucceeded": 0,
    "pending": 2,
    "fileName": "file.csv"
}

Gets bulk upload results

curl -X GET \
    'https://tracking.api.here.com/bulkjobs/v4/deviceUploads/{jobId}/results' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}'

{
    "status": "completed",
    "limit": 100,
    "count": 2,
    "items": [
        {
            "name": "my at4h tracker in distance based mode",
            "deviceId": "a19b2648-60c1-49fc-896c-ea450a07e98d",
            "trackingId": "HERE-5cb2b777-7389-472b-81f0-9ab89a9c7fed"
        },
        {
            "name": "my super tracker in area based mode",
            "deviceId": "13316aa5-3b80-414c-bf6d-86fa3ca6a31f",
            "trackingId": "HERE-0d571d83-79f5-4b1a-a177-fcd6b5d47e74"
        }
    ]
}

Updates bulk upload job status

curl -X PATCH \
    'https://tracking.api.here.com/bulkjobs/v4/deviceUploads/{jobId}' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
          "action": "cancel"
        }'

{
    "status": "cancelled"
}