dctrackclient

WARNING: this project is still under development and may not be stable!

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==0.6.0

JavaScript

npm i dctrackclient@0.6.0

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

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

response = api.createItem(True/False, {
    'cmbLocation': 'item location',
    'tiName': 'item name',
    'cmbMake': 'item make',
    'cmbModel': 'item model'
})
print(response)

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.

let response = await api.createItem(true/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.

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.

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.

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/v900/API/en/Default.htm

Package Documentation

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

getItem(id)

Get item details using the item ID.

GET api/v2/dcimoperations/items/{id}

Parameter	Type
id	number

createItem(returnDetails, payload)

Create a new item. When returnDetails is set to true, the API call will return the full json payload. If set to false, the call returns only the "id" and "tiName".

POST api/v2/dcimoperations/items payload

Parameter	Type
returnDetails	boolean
payload	object

updateItem(id, returnDetails, payload)

Update an existing item. When returnDetails is set to true, the API call will return the full json payload. If set to false, the call returns only the "id" and "tiName".

PUT api/v2/dcimoperations/items/{id} payload

Parameter	Type
id	number
returnDetails	boolean
payload	object

deleteItem(id)

Delete an item using the item ID.

DELETE api/v2/dcimoperations/items/{id}

Parameter	Type
id	number

searchItems(pageNumber, pageSize, payload)

Search for items using criteria JSON object. Search criteria can be any of the fields applicable to items, including custom fields. Specify the fields to be included in the response. This API supports pagination. Returns a list of items with the specified information.

POST api/v2/quicksearch/items payload

Parameter	Type
pageNumber	number
pageSize	number
payload	object

getCabinetItems(CabinetId)

Returns a list of Items contained in a Cabinet using the ItemID of the Cabinet. The returned list includes all of the Cabinet's Items including Passive Items.

GET api/v2/items/cabinetItems/{CabinetId}

Parameter	Type
CabinetId	number

createItemsBulk(payload)

Add/Update/Delete Items.

POST api/v2/dcimoperations/items/bulk payload

Parameter	Type
payload	object

getMakes()

Returns a list of makes with basic information.

GET api/v2/makes

No parameters.

createMake(payload)

Add a new Make. Returns JSON entity containing Make information that was passed in from the Request payload.

POST api/v2/makes payload

Parameter	Type
payload	object

updateMake(makeId, payload)

Modify a Make. Returns JSON entity containing Make information that was passed in from the Request payload.

PUT api/v2/makes/{makeId} payload

Parameter	Type
makeId	number
payload	object

deleteMake(makeId)

Delete a Make.

DELETE api/v2/makes/{makeId}

Parameter	Type
makeId	number

searchMakes(makeName, payload)

Search for a make using the make name. Returns a list of makes with basic information.

POST api/v2/dcimoperations/search/makes/{makeName} payload

Parameter	Type
makeName	string
payload	object

getModel(modelId, usedCounts)

Get Model fields for the specified Model ID. usedCounts is an optional parameter that determines if the count of Items for the specified model is returned in the response. If set to "true" the counts will be included in the response, if omitted or set to "false" the item count will not be included in the response.

GET api/v2/models/{modelId}

Parameter	Type
modelId	number
usedCounts	number

createModel(returnDetails, proceedOnWarning, payload)

Add a new Model. Returns JSON entity containing Make information that was passed in from the Request payload. "proceedOnWarning" relates to the warning messages that are thrown in dcTrack when you try to delete custom fields that are in use. The "proceedOnWarning" value can equal either "true" or "false." If "proceedOnWarning" equals "true," business warnings will be ignored. If "proceedOnWarning" equals "false," business warnings will not be ignored. Fields that are not in the payload will remain unchanged.

POST api/v2/models payload

Parameter	Type
returnDetails	boolean
proceedOnWarning	boolean
payload	object

deleteModel(id)

Delete a Model using the Model ID.

DELETE api/v2/models/{id}

Parameter	Type
id	number

searchModels(pageNumber, pageSize, payload)

Search for models by user supplied search criteria. Returns a list of models with the "selectedColumns" returned in the payload. Search by Alias is not supported.

POST api/v2/quicksearch/models payload

Parameter	Type
pageNumber	number
pageSize	number
payload	object

deleteModelImage(id, orientation)

Delete a Mode Image using the Model ID and the Image Orientation, where id is the Model Id and orientation is either front or back

DELETE api/v2/models/images/{id}/{orientation}

Parameter	Type
id	number
orientation	string

getConnector(connectorId, usedCount)

Get a Connector record by ID. Returns a Connector with all information including Compatible Connectors. The usedCount parameter is optional. If usedCount is true, the response will include the number of times the connector is in use by Models and Items. If false, no counts are returned. If omitted the default is false.

GET api/v2/settings/connectors/{connectorId}

Parameter	Type
connectorId	number
usedCount	boolean

createConnector(payload)

Add a new Connector. Returns JSON entity containing Connector information that was passed in from the Request payload.

POST api/v2/settings/connectors payload

Parameter	Type
payload	object

updateConnector(connectorId, payload)

Update an existing Connector. Returns JSON entity containing Connector information that was passed in from the Request payload.

PUT api/v2/settings/connectors/{connectorId} payload

Parameter	Type
connectorId	number
payload	object

removeConnector(payload)

Delete one or more Connector records.

POST api/v2/settings/connectors/delete payload

Parameter	Type
payload	object

searchConnectors(pageNumber, pageSize, usedCount, payload)

Retrieve a List of Connectors. Returns JSON entity containing Connector information that was passed in from the Request payload. Please note, Compatible Connectors are not returned by this API, but can be returned when querying a single Connector using the /api/v2/settings/connectors/{connectorId} API.

POST api/v2/settings/connectors/quicksearch payload

Parameter	Type
pageNumber	number
pageSize	number
usedCount	boolean
payload	object

deleteConnectorImage(connectorId)

Delete a Connector Image using the Connector ID.

DELETE api/v2/settings/connectors/{connectorId}/images

Parameter	Type
connectorId	number

getDataPorts(itemId)

Use the REST API to retrieve details from all data ports on an item. If the operation was successful, a status code 200 is displayed, and the body contains the item's data port details. If the operation failed, an error code is returned.

GET api/v1/items/{itemId}/dataports

Parameter	Type
itemId	number

getDataPort(itemId, dataportId)

Use the REST API to read the details of an item's data port. To do this, specify the item and item data port ID. If the operation was successful, a status code 200 is displayed, and the body contains the item's data port details. If the operation failed, an error code is returned.

GET api/v1/items/{itemId}/dataports/{dataportId}

Parameter	Type
itemId	number
dataportId	number

createDataPorts(itemId, payload)

Use the REST API to create data ports for an existing item. If ports are already defined for the item because it is included in the Item Models Library, you can use the REST API to create additional ports for the item. Payload contains data port parameter details in json format. All required fields must be included.

POST api/v1/items/{itemId}/dataports payload

Parameter	Type
itemId	number
payload	object

updateDataPort(itemId, dataportId, payload)

Update an item's data port details using the REST API. To do this, specify the item and data port ID, and provide the updated parameter value(s). Payload contains data port parameter details in json format. All required fields must be included.

PUT api/v1/items/{itemId}/dataports/{dataportId} payload

Parameter	Type
itemId	number
dataportId	number
payload	object

deleteDataPort(itemId, dataportId)

Delete an item's data port using the REST API by specifying the item ID and data port ID. If the operation is successful, a status code 200 is displayed. If the operation failed, an error code is returned.

DELETE api/v1/items/{itemId}/dataports/{dataportId}

Parameter	Type
itemId	number
dataportId	number

getPowerPorts(itemId)

Use the REST API to retrieve details from all power ports on an item.

GET api/v1/items/{itemId}/powerports

Parameter	Type
itemId	number

getPowerPort(itemId, portId)

Use the REST API to retrieve details from one power port on an item.

GET api/v1/items/{itemId}/powerports/{portId}

Parameter	Type
itemId	number
portId	number

updatePowerPort(itemId, portId, proceedOnWarning, payload)

Use the REST API to create power ports for an existing item. If ports are already defined for the item because it is included in the Item Models Library, you can use the REST API to create additional ports for the item.

PUT api/v1/items/{itemId}/powerports/{portId} payload

Parameter	Type
itemId	number
portId	number
proceedOnWarning	boolean
payload	object

getCompatibleConnector(itemId, portId, connectorId)

Use the REST API to determine if a Connector is compatible with a specific Power Port.

GET api/v1/items/{itemId}/powerports/{portId}/connectors/{connectorId}/isCompatible

Parameter	Type
itemId	number
portId	number
connectorId	number

getLocations()

Returns a list for all Locations.

GET api/v1/locations

No parameters.

getLocation(locationId)

Get a single Location. Returns json containing location data for the specified ID.

GET api/v1/locations{locationId}

Parameter	Type
locationId	number

createLocation(proceedOnWarning, payload)

Add a Location. Returns the JSON entity containing location info that was passed in. Note: "proceedOnWarning" relates to the warning messages that are thrown in dcTrack when you try to delete custom fields that are in use. The "proceedOnWarning" value can equal either "true" or "false." If "proceedOnWarning" equals "true," business warnings will be ignored. If "proceedOnWarning" equals "false," business warnings will not be ignored.

POST api/v1/locations payload

Parameter	Type
proceedOnWarning	boolean
payload	object

updateLocation(locationId, proceedOnWarning, payload)

Modify Location details for a single Location. Payload contains new location details. You do not have have to provide all details, but only those that you want to modify. Returns JSON entity containing Location information that was passed in from the Request payload.

PUT api/v1/locations/{locationId} payload

Parameter	Type
locationId	number
proceedOnWarning	boolean
payload	object

deleteLocation(locationId)

Delete a Location.

DELETE api/v1/locations/{locationId}

Parameter	Type
locationId	number

searchLocations(pageNumber, pageSize, payload)

Search for Locations by user supplied search criteria. Returns a list of Locations with the "selectedColumns" returned in the payload.

POST api/v2/quicksearch/locations payload

Parameter	Type
pageNumber	number
pageSize	number
payload	object

getLocationFieldList()

Returns a list of all Location fields.

GET api/v2/quicksearch/locations/locationListFields

No parameters.

Changelog

0.6.0

• Add location API endpoints
• Minor updates to readme examples (text fixes)
• HTTP method is inferred by the function name (e.g. getItem() = GET request)
• Remove method from api.json
• Show message when no documentation is provided