Sunbird dcTrack API clients in Python and JavaScript

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

pip install dcTrackClient==%VERSION%

npm i dctrackclient@%VERSION%

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.

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')

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' });

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.

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

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

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.

token = api.generateToken()

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();

This section demonstrates item manipulation with the API client.

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.

# 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)

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);

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" } }

This function returns a JSON object containing the error message.

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.

response = api.getItem(1234)

let response = await api.getItem(1234);

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

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.

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

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

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.

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

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

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

This example demonstrates usage of the deleteItem function.

api.deleteItem(1234)

await api.deleteItem(1234);

{ "itemId": 1234 }

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

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

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