dcTrackClient

Sunbird dcTrack API clients in Python and JavaScript

Installation

dcTrackClient can be installed from the package manager of your choice.

Python

pip install dcTrackClient==%VERSION%

JavaScript

npm i dctrackclient@%VERSION%

Initialize a connection to the dcTrack API

Authentication is by using a base URL (the same URL to access the GUI) and a username and password, or a base URL and an API token.

Python

from dcTrackClient import Client
## Using a username and password ##
api = Client('https://dctrack.example.com/', username='user', password='pass')
## Using an API token ##
api = Client('https://dctrack.example.com/', apiToken='token')

JavaScript

import { Client } from 'dctrackclient';
// Using a username and password // 
const api = new Client('https://dctrack.example.com/', { username: 'user', password: 'pass' });
// Using an API token //
const api = new Client('https://dctrack.example.com/', { apiToken: 'token' });

Advanced: Initialize a connection with a proxy

Proxies can be used for either authentication method (username/password or API token) for both libraries. For the Python library, specify an HTTP or HTTPS proxy, or both. These can also be SOCKS proxies. For the JavaScript library, only 1 proxy is required and https proxies can either be HTTP or HTTPS. HTTPS will automatically upgraded to TLS.

Python

api = Client('https://dctrack.example.com/', username='user', password='pass', httpProxy='http://proxy:port', httpsProxy='https://proxy:port')

JavaScript

const api = new Client('https://dctrack.example.com/', { username: 'user', password: 'pass' }, { https: 'http://proxy:port', socks: 'socks://proxy:port' });

Obtain an API Token

Obtain an API token using the Client.generateToken() function provided. Re-authentication is not necessary, as the API token will automatically be used in subsequent API calls. The function returns the token's value in case the user wants to store the token for the next initialization of the API.

Python

token = api.generateToken()

JavaScript

Notice the await keyword before the function call. This is because the JavaScript library is asynchronous and returns a Promise to the return value. All the API calls in this library require that keyword.

const token = await api.generateToken();

Usage Example

This section demonstrates item manipulation with the API client.

Create an item

This example shows the minimum attributes required to create an item using the createItem function. View the comprehensive list of item attributes in the official documentation. Make sure to capture the return value of this function to see the created item details, such as the unique numeric item ID, or to determine if an error occurred while creating an item.

Python

# Set `returnDetails = True` to return the complete item field list.
response = api.createItem(False, {
    'cmbLocation': 'item location',
    'tiName': 'item name',
    'cmbMake': 'item make',
    'cmbModel': 'item model'
})
print(response)

JavaScript

See the JavaScript section on obtaining an API token why the await keyword is required.

// Set `returnDetails = true` to return the complete item field list.
let response = await api.createItem(false, {
    'cmbLocation': 'item location',
    'tiName': 'item name',
    'cmbMake': 'item make',
    'cmbModel': 'item model'
});
console.log(response);

On Success

This function returns the JSON object for the newly created item. This is an example response if returnDetails was set to false.

{ "item": { "id": 1234, "tiName": "item name" } }

On Failure

This function returns a JSON object containing the error message.

Retrieve item details

This example shows the usage of the getItem function. This function requires the unique item's ID, shown in the create item example. It returns the full list of item attributes.

Python

response = api.getItem(1234)

JavaScript

let response = await api.getItem(1234);

Returns

{
    "item": {
        "cmbLocation": "item location",
        "tiName": "item name",
        ...
    }
}

Modify an existing item

This example shows the usage of the updateItem function. Any number of attributes can be included in the payload to be modified. The returnDetails parameter behaves in the same way as in the create item example.

Python

response = api.updateItem(1234, False, {'tiSerialNumber': 12345})

JavaScript

let response = await api.updateItem(1234, false, { 'tiSerialNumber': 12345 });

Search for an item

This example demonstrates usage of the searchItems function. Follow this guide for details on creating the request payload. In this example, the API searches for an item based on the tiName field.

Python

response = api.searchItems(0, 0, {
    'columns': [
        {'name': 'tiName', 'filter': {'eq': 'item name'}}
    ],
    'selectedColumns': [
        {'name': 'id'},
        {'name': 'tiName'},
    ]
})

JavaScript

let response = await api.searchItems(0, 0, {
    'columns': [
        { 'name': 'tiName', 'filter': { 'eq': 'item name' } }
    ],
    'selectedColumns': [
        { 'name': 'id' },
        { 'name': 'tiName' },
    ]
});

Returns

{
    "selectedColumns": [],
    "totalRows": 1,
    "pageNumber": 0,
    "pageSize": 0,
    "searchResults": {
        "items": [
            {"id": "1234", "tiName": "item name"}
        ]
    }
}

Delete an item

This example demonstrates usage of the deleteItem function.

Python

api.deleteItem(1234)

JavaScript

await api.deleteItem(1234);

Returns

{ "itemId": 1234 }

Official DcTrack Documentation

Visit this link for the official documentation on request bodies and attrribute names.

https://www.sunbirddcim.com/help/dcTrack/v911/API/en/Default.htm

Package Documentation

The section below shows all the functions contained within this client along with basic usage.