Skip to content

ComponentDB API

Jump to bottom
Dariusz Jarosz edited this page Aug 12, 2025 · 5 revisions

Component Database API Python Client Documentation

Package Name: ComponentDB-API
API Version: 3.16.1.dev3
Specification: OpenAPI 3.0.1
Contact: [email protected]
License: Copyright (c) UChicago Argonne, LLC. All rights reserved.
(License Details)

The Component Database API provides access to various types of data such as components, cables, machine designs, locations, logs, and more. The Python client—generated from the OpenAPI definition—allows you to interact with the API via high‑level methods and model classes rather than dealing with raw REST calls.

Table of Contents

  1. Getting Started with CdbApiFactory
  2. Installation and Setup
  3. Using the API Endpoints
  4. Fetching Supporting Classes (Technical Systems & Functions)
  5. Error Handling
  6. Additional Notes

1. Getting Started with CdbApiFactory

Before using any API endpoints, create a factory instance, authenticate your user, and import the exception type.

from CdbApiFactory import CdbApiFactory
from cdbApi import OpenAPIException

# Create the factory instance with your API's base URL.
cdb_api_factory = CdbApiFactory('https://cdb-url')

# Authenticate the user. This call raises an OpenAPIException if authentication fails.
cdb_api_factory.authenticateUser(username="your_username", password="your_password")

# For long‑running processes, verify that the token remains valid.
if cdb_api_factory.testAuthenticated():
    print("Authentication is valid!")
else:
    print("Token may have expired. Re‑authenticate.")

# When finished, log out the user.
cdb_api_factory.logOutUser()

After authentication, retrieve each API interface with one‑line calls. For example:

app_api = cdb_api_factory.get_app_items_api()
inventory_api = cdb_api_factory.get_component_inventory_items_api()
connector_api = cdb_api_factory.get_connector_types_api()
domain_api = cdb_api_factory.get_domain_api()

2. Installation and Setup

Install the client package from PyPI using pip:

pip install ComponentDB-API

3. Using the API Endpoints

Below are examples for each API class. In each section, the first code block stores the API instance in a variable. For API calls that require an input object, the object is created and immediately passed to the API call within the same code block. When creating new items, do not provide a field named exactly "id". For update calls, fields ending with "Id" are assigned literal random values (for example, 4321, 9876, 42, or 8765).

3.1 AppItemsApi

First, obtain the AppItems API instance:

app_api = cdb_api_factory.get_app_items_api()

Create App Item (PUT /api/AppItems/create)
Input: NewAppInformation

  • name (str): The name of the application.
  • description (str): A brief description.
  • technicalSystemList (list): One or more item category objects (also known as technical systems).
  • typeList (list): One or more item type objects (also known as functions).
from cdbApi import NewAppInformation

try:
    new_app = NewAppInformation(
        name="My New App",
        description="A sample application",
        technicalSystemList=[],  # e.g. [system_obj1, system_obj2]
        typeList=[]              # e.g. [type_obj1, type_obj2]
    )
    created_app = app_api.create_app(new_app)
    print("Created App Item:", created_app)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.2 CableCatalogItemsApi

cable_catalog_api = cdb_api_factory.get_cable_catalog_items_api()

Get Cable Catalog Item List (GET /api/CableCatalogItems/all)

try:
    cable_catalog_item = cable_catalog_api.get_cable_catalog_item_list()
    print("Cable Catalog Item List:", catalog_list)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Cable Catalog Item by ID (GET /api/CableCatalogItems/ById/{id})

try:
    cable_catalog_item = cable_catalog_api.get_cable_catalog_item_by_id(100)
    print("Cable Catalog Item by ID:", catalog_item)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Cable Catalog Item by Name (GET /api/CableCatalogItems/ByName/{name})

try:
    cable_catalog_item = cable_catalog_api.get_cable_catalog_item_by_name("CableName")
    print("Cable Catalog Item by Name:", catalog_item)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Cable Catalog API Notes

Cable catalog items fetched from this API endpoint will include a connector_list.

connector_list = cable_catalog_item.catalog_item

3.3 CableDesignItemsApi

cable_design_api = cdb_api_factory.get_cable_design_items_api()

Get Cable Design Metadata (GET /api/CableDesignItems/CableDesignMetadata/{cableDesignId})

try:
    metadata = cable_design_api.get_cable_design_metadata(10)
    print("Cable Design Metadata:", metadata)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Cable Design Connection List (GET /api/CableDesignItems/ConnectionList/{cableDesignId})

try:
    connection_list = cable_design_api.get_cable_design_connection_list(10)
    print("Cable Design Connection List:", connection_list)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Cable Design Item List (GET /api/CableDesignItems/all)

  • This call optionally populates the connection_list and loads machine design endpoint location reference.
try:
    design_list = cable_design_api.get_cable_design_item_list(includeConnections=False, include_md_locations=False)
    print("Cable Design Item List:", design_list)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Cable Design Item by ID (GET /api/CableDesignItems/ById/{id})

  • This call also populates the connection_list and loads machine design endpoint location reference.
try:
    design_item = cable_design_api.get_cable_design_item_by_id(20)
    print("Cable Design Item by ID:", design_item)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Cable Design Item by Name (GET /api/CableDesignItems/ByName/{name})

  • This call also populates the connection_list and loads machine design endpoint location reference.
try:
    design_item = cable_design_api.get_cable_design_item_by_name("DesignName")
    print("Cable Design Item by Name:", design_item)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Add or Update Cable Design (POST /api/CableDesignItems/CableDesignAddUpdate)
Input: Cable design parameters.

  • For new items, do not pass any field named exactly "id".
  • If you need a cable type or other references (e.g. technical systems), see Section 4.
try:
    cable_design = cable_design_api.add_or_update_cable_design(
        name="Design A",
        alternateName="Alt A",
        description="Sample cable design",
        itemProjectIds=[101, 102],
        technicalSystemIds=[201],
        cableTypeId=1,
        end1MachineDesignId=301,
        end1DevicePortName="DP1",
        end1ConnectorName="C1",
        end2MachineDesignId=302,
        end2DevicePortName="DP2",
        end2ConnectorName="C2"
    )
    print("Cable Design:", cable_design)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Update Cable Design Metadata (POST /api/CableDesignItems/CableDesignMetadataUpdate)
Input: ItemDomainCableDesignMetadata

from cdbApi import ItemDomainCableDesignMetadata

try:
    metadata_instance = ItemDomainCableDesignMetadata(
        cableDesignId=4321,
        externalCableName="External Cable Name",
        importCableId="Import123",
        alternateCableId="Alt123",
        laying="Overhead",
        voltage="110V",
        routedLength="15m",
        route="Route A",
        totalReqLength="20m",
        notes="Some notes",
        endpoint1Description="Endpoint 1 desc",
        endpoint1Route="Route 1",
        endpoint1EndLength="5m",
        endpoint1Termination="Termination1",
        endpoint1Pinlist="Pinlist1",
        endpoint1Notes="Endpoint 1 notes",
        endpoint1Drawing="Drawing1.png",
        endpoint2Description="Endpoint 2 desc",
        endpoint2Route="Route 2",
        endpoint2EndLength="5m",
        endpoint2Termination="Termination2",
        endpoint2Pinlist="Pinlist2",
        endpoint2Notes="Endpoint 2 notes",
        endpoint2Drawing="Drawing2.png"
    )
    updated_metadata = cable_design_api.update_cable_design_metadata(metadata_instance)
    print("Updated Cable Design Metadata:", updated_metadata)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Update Cable Type ID (POST /api/CableDesignItems/UpdateCableTypeId)
Input: UpdateCableDesignAssignedItemInformation

from cdbApi import UpdateCableDesignAssignedItemInformation

try:
    update_info = UpdateCableDesignAssignedItemInformation(
        cdItemId=4321,
        cableTypeId=42,
        cableTypeName="New Cable Type",
        inventoryId=8765,
        inventoryTag="INV-5678",
        isInstalled=True
    )
    result = cable_design_api.update_cable_type_id(update_info)
    print("Updated Cable Type ID:", result)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Cable Design API Notes

Cable design items fetched from this API endpoint by id, by name, or list (with includeConnections=True) will include a connection_list.

connection_list = cable_design_item.connection_list

(Other update calls like clear_cable_type, update_assigned_inventory_name, update_installation_status, etc. follow a similar pattern. Refer to the preceding examples.)

3.4 CableImportApi

The new CableImportApi allows users to import cable data into the Component Database. This functionality simplifies batch uploads and integrations with external systems.

cable_import_api = cdb_api_factory.get_cable_import_api()

Import Cable Data (POST /api/CableImport/upload)

try:
    result = cable_import_api.upload_cable_data(file_upload_object)
    print("Cable Data Import Successful:", result)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Validate Cable Import File (POST /api/CableImport/validate)

try:
    validation_result = cable_import_api.validate_cable_import(file_upload_object)
    print("Validation Result:", validation_result)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.5 ComponentCatalogItemsApi

catalog_items_api = cdb_api_factory.get_component_catalog_items_api()

Add Catalog Element (PUT /api/ComponentCatalogItems/createElement/{catalogItemId})
Input: NewCatalogElementInformation

from cdbApi import NewCatalogElementInformation

try:
    new_catalog_element_info = NewCatalogElementInformation(
        catalogItemId=123,
        partName="Part X",
        partDescription="Description for Part X"
    )
    element = catalog_items_api.add_catalog_element(123, new_catalog_element_info)
    print("Catalog Element Added:", element)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Create Catalog Item (PUT /api/ComponentCatalogItems/create)
Input: NewCatalogInformation

from cdbApi import NewCatalogInformation

try:
    new_catalog_info = NewCatalogInformation(
        name="Catalog Item X",
        modelNumber="Model 001",
        alternateName="Alt X",
        description="Description for Catalog Item X",
        technicalSystemList=[],  # item categories (technical systems)
        functionList=[],         # item types (functions)
        itemProjectsList=[]
    )
    catalog = catalog_items_api.create_catalog(new_catalog_info)
    print("Catalog Item Created:", catalog)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.6 ComponentInventoryItemsApi

inventory_api = cdb_api_factory.get_component_inventory_items_api()

Create Inventory Item (PUT /api/ComponentInventoryItems/create)
Input: NewInventoryInformation

from cdbApi import NewInventoryInformation

try:
    new_inventory = NewInventoryInformation(
        catalogId=456,
        tag="INV-12345",
        serialNumber="SN-98765",
        description="Inventory item for component X",
        qrId=789
    )
    created_inventory = inventory_api.create_inventory(new_inventory)
    print("Created Inventory Item:", created_inventory)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.7 ConnectorTypesApi

connector_api = cdb_api_factory.get_connector_types_api()

Get Connector Type List (GET /api/ConnectorTypes/all)

try:
    connector_types = connector_api.get_connector_type_list()
    print("Connector Types:", connector_types)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Connector Type by ID (GET /api/ConnectorTypes/ById/{id})

try:
    connector = connector_api.get_connector_type_by_id(5)
    print("Connector Type by ID:", connector)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Connector Type by Name (GET /api/ConnectorTypes/ByName/{name})

try:
    connector = connector_api.get_connector_type_by_name("TypeName")
    print("Connector Type by Name:", connector)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.8 DomainApi

domain_api = cdb_api_factory.get_domain_api()

Get Allowed Entity Type List (GET /api/Domains/ById/{id}/EntityTypes)

try:
    allowed_types = domain_api.get_allowed_entity_type_list(1)
    print("Allowed Entity Types:", allowed_types)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Domain Type List (GET /api/Domains/ById/{id}/Types)

try:
    domain_types = domain_api.get_domain_type_list(1)
    print("Domain Types:", domain_types)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Item Category by ID (GET /api/Domains/Category/ById/{id})
(Remember that item categories are also known as technical systems.)

try:
    category = domain_api.get_item_category_by_id(10)
    print("Item Category (Tech System) by ID:", category)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Item Type by ID (GET /api/Domains/Type/ById/{id})
(Item types are also known as functions.)

try:
    item_type = domain_api.get_item_type_by_id(20)
    print("Item Type (Function) by ID:", item_type)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.9 DownloadsApi

downloads_api = cdb_api_factory.get_downloads_api()

Get Image (GET /api/Downloads/PropertyValue/Image/{imageName}/{scaling})
Allowed scaling values: "scaled", "thumbnail", "original".

try:
    image_data = downloads_api.get_image("sample_image.png", "scaled")
    print("Downloaded image data.")
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Download by Property Value ID (GET /api/Downloads/PropertyValue/{propertyValueId})

try:
    file_data = downloads_api.get_download_by_property_value_id(50)
    print("Downloaded File Data:", file_data)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.10 ItemApi

item_api = cdb_api_factory.get_item_api()

Get Item by ID (GET /api/Items/ById/{itemId})

try:
    item = item_api.get_item_by_id(123)
    print("Item Details:", item)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Update Item Status (POST /api/Items/UpdateStatus/{itemId})
Input: ItemStatusBasicObject
Dates should be in the format %a %b %d 00:00:00 CDT %Y.

from cdbApi import ItemStatusBasicObject

try:
    status_update = ItemStatusBasicObject(
        status="Active",
        effectiveFromDate="Sat Mar 01 00:00:00 CDT 2025"
    )
    updated_status = item_api.update_item_status(123, status_update)
    print("Updated Status:", updated_status)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Upload Document (POST /api/Items/uploadDocument/{itemId})

try:
    result = item_api.upload_document(123, file_upload_obj)
    print("Document Uploaded:", result)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Upload Image (POST /api/Items/uploadImage/{itemId})

try:
    result = item_api.upload_image(123, file_upload_obj)
    print("Image Uploaded:", result)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Delete Item by ID (DELETE /api/Items/DeleteById/{itemId})

try:
    item_api.delete_item_by_id(123)
    print("Item deleted successfully.")
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.11 IOCItemsApi

ioc_api = cdb_api_factory.get_ioc_items_api()

Add or Update IOC (POST /api/IOCItems/IOCAddUpdate)

try:
    ioc_item = ioc_api.add_or_update_ioc(
        name="IOC-001",
        description="Sample IOC",
        item_project_ids=[101, 102],
        parent_machine_id=301,
        machine_tag="MACH01",
        function_tag="FUNC01",
        deployment_status="Development",
        preboot_instructions="Preboot instructions here",
        postboot_instructions="Postboot instructions here",
        power_cycle_instructions="Power cycle instructions here",
        additional_instructions="Additional instructions here"
    )
    print("IOC Item:", ioc_item)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Convert Machine to IOC (POST /api/IOCItems/convertToIOC/{mdId})

try:
    converted_ioc = ioc_api.convert_machine_to_ioc(
        123,
        machine_tag="MACH02",
        function_tag="FUNC02",
        deployment_status="Production"
    )
    print("Converted to IOC:", converted_ioc)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Allowed Deployment Statuses (GET /api/IOCItems/allowedValues/deploymentStatus)

try:
    deployment_statuses = ioc_api.get_allowed_deployment_statuses()
    print("Allowed Deployment Statuses:", deployment_statuses)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Allowed Function Tags (GET /api/IOCItems/allowedValues/functionTag)

try:
    function_tags = ioc_api.get_allowed_function_tags()
    print("Allowed Function Tags:", function_tags)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Allowed Machine Tags (GET /api/IOCItems/allowedValues/machineTag)

try:
    machine_tags = ioc_api.get_allowed_machine_tags()
    print("Allowed Machine Tags:", machine_tags)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get IOC Item Core Property Type (GET /api/IOCItems/coreMetadataPropertyType)

try:
    property_type = ioc_api.get_ioc_item_core_property_type()
    print("IOC Core Property Type:", property_type)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get IOC Item List (GET /api/IOCItems/all)

try:
    ioc_list = ioc_api.get_ioc_item_list()
    print("IOC Item List:", ioc_list)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.11 LocationItemsApi

location_api = cdb_api_factory.get_location_items_api()

Get Location Items by Name (GET /api/LocationItems/ByName/{name})

try:
    locations = location_api.get_location_items_by_name("Warehouse")
    print("Location Items:", locations)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Full Location Item List (GET /api/LocationItems/all)

try:
    loc_list = location_api.get_location_item_list()
    print("Location Item List:", loc_list)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Inventory Located Here (GET /api/LocationItems/InventoryHere/{locationId})

try:
    inventory_here = location_api.get_inventory_located_here(5)
    print("Inventory Located Here:", inventory_here)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Update Location Parent (POST /api/LocationItems/UpdateLocationParent/{locationItemId}/{newParentId})

try:
    updated_location = location_api.update_location_parent(10, 20)
    print("Updated Location Parent:", updated_location)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.12 LogApi

log_api = cdb_api_factory.get_log_api()

Get Successful Login Logs (GET /api/Logs/System/LoginInfo)

try:
    logs = log_api.get_successful_login_log()
    print("Successful Login Logs:", logs)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Unsuccessful Login Logs (GET /api/Logs/System/LoginWarning)

try:
    warnings = log_api.get_unsuccessful_login_log()
    print("Unsuccessful Login Logs:", warnings)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.13 MAARCItemsApi

maarc_api = cdb_api_factory.get_maarc_items_api()

Get MAARC Item by Name (GET /api/MAARCItems/ByName/{name})

try:
    item = maarc_api.get_maarc_item_by_name("UniqueItemName")
    print("MAARC Item:", item)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get MAARC Connection Relationship List (GET /api/MAARCItems/getMaarcRelationshipList/{maarcID})

try:
    relationships = maarc_api.get_maarc_connection_relationship_list(100)
    print("MAARC Connection Relationship List:", relationships)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Create MAARC Relationship (PUT /api/MAARCItems/createRelationship/{maarcID}/{relatedItemId})

try:
    relationship = maarc_api.create_maarc_relationship(100, 200)
    print("MAARC Relationship Created:", relationship)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Create MAARC Item (PUT /api/MAARCItems/create)
Input: NewMAARCInformation
For new items, do not pass a field named exactly "id".

from cdbApi import NewMAARCInformation

try:
    new_maarc_info = NewMAARCInformation(
        name="MAARC Item X",
        description="Description for MAARC item X",
        entityTypeList=[],        # e.g. from domain_api or search_api
        itemProjectsList=[],      # from item_api or domain_api
        ownerUser=None,           # from users_api
        ownerGroup=None,          # from users_api
        parentItemId=123,
        parentElementName="Parent Element",
        experimentFilePath="/path/to/experiment",
        experimentName="Experiment X"
    )
    created_maarc = maarc_api.create(new_maarc_info)
    print("Created MAARC Item:", created_maarc)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.14 MachineDesignItemsApi

machine_design_api = cdb_api_factory.get_machine_design_items_api()

Get Machine Design Connector List (GET /api/MachineDesignItems/ConnectorListForMachine/{machineId})

try:
    connectors = machine_design_api.get_machine_design_connector_list(10)
    print("Machine Design Connector List:", connectors)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Machine Design Item List (GET /api/MachineDesignItems/all)

try:
    design_list = machine_design_api.get_machine_design_item_list()
    print("Machine Design Item List:", design_list)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Machine Design Item by ID (GET /api/MachineDesignItems/ById/{id})

  • This call optionally populates machine_design.location_item when provided optional argument include_location=True.
try:
    design_item = machine_design_api.get_machine_design_item_by_id(10, include_location=False)
    print("Machine Design Item by ID:", design_item)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Machine Design Items by Name (GET /api/MachineDesignItems/ByName/{name})

  • This call optionally populates machine_design.location_item when provided optional argument include_location=True.
try:
    design_items = machine_design_api.get_machine_design_items_by_name("MD:ITEM", include_location=False)
    print("Machine Design Items by Name:", design_items)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Create Control Element (PUT /api/MachineDesignItems/createControlElement)
Input: NewMachinePlaceholderOptions

from cdbApi import NewMachinePlaceholderOptions

try:
    new_control = NewMachinePlaceholderOptions(
        name="Control Element",
        alternateName="Ctrl-01",
        description="Control element description",
        projectId=202
    )
    control_element = machine_design_api.create_control_element(new_control)
    print("Created Control Element:", control_element)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Create Control Relationship (PUT /api/MachineDesignItems/createControlRelationship)
Input: NewControlRelationshipInformation

from cdbApi import NewControlRelationshipInformation

try:
    new_control_relationship_info = NewControlRelationshipInformation(
        controlledMachineId=101,
        controllingMachineId=102,
        linkedParentMachineRelationshipId=None,
        controlInterfaceToParent="Interface A"
    )
    relationship = machine_design_api.create_control_relationship(new_control_relationship_info)
    print("Created Control Relationship:", relationship)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

(Other advanced calls like promote_assembly_element_to_machine, unassign_template_from_machine_element, etc. follow a similar pattern.)

3.15 PropertyTypeApi

property_type_api = cdb_api_factory.get_property_type_api()

Get All Property Types (GET /api/PropertyTypes/all)

try:
    types = property_type_api.get_all()
    print("All Property Types:", types)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Property Type by ID (GET /api/PropertyTypes/ById/{id})

try:
    prop_type = property_type_api.get_property_type_by_id(1)
    print("Property Type by ID:", prop_type)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Add Allowed Value (PUT /api/PropertyTypes/ById/{id}/AllowedValue)

from cdbApi import AllowedPropertyValue

try:
    allowed_value = AllowedPropertyValue(
        value="NewValue",
        units="unit",
        description="A new allowed value",
        sortOrder=1.0
    )
    result = property_type_api.add_allowed_value(1, allowed_value)
    print("Added Allowed Value:", result)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.16 PropertyValueApi

property_value_api = cdb_api_factory.get_property_value_api()

Get Property Values by Property Type ID (GET /api/PropertyValues/ByPropertyTypeId/{propertyTypeId})

try:
    values = property_value_api.get_property_values_by_property_type_id(1)
    print("Property Values by Type ID:", values)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Property Value (GET /api/PropertyValues/ById/{id})

try:
    prop_val = property_value_api.get_property_value(5)
    print("Property Value:", prop_val)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Delete a Property Value (DELETE /api/PropertyValues/DeleteById/{propertyValueId})

try:
    property_value_api.delete_property_by_id(5)
    print("Property Value deleted successfully.")
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Add or Update Property Value Metadata by Map (POST /api/PropertyValues/ById/{id}/AddUpdateMetadata)

try:
    metadata_list = property_value_api.add_or_update_property_value_metadata_by_map(
        5, {"key": "value"}
    )
    print("Updated Metadata:", metadata_list)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.17 SearchApi

search_api = cdb_api_factory.get_search_api()

Search Entities (POST /api/Search/Entities)
Input: SearchEntitiesOptions

from cdbApi import SearchEntitiesOptions

try:
    search_options = SearchEntitiesOptions(
        searchText="component",
        includeCatalog=True,
        includeInventory=True,
        includeCableDesign=True,
        includeMachineDesign=True,
        includeItemLocation=True,
        includeMAARC=True,
        includeItemElement=True,
        includeItemType=True,
        includeItemCategoy=True,
        includePropertyType=True,
        includePropertyTypeCategory=True,
        includeSource=True,
        includeUser=True,
        includeUserGroup=True
    )
    results = search_api.search_entities(search_options)
    print("Search Results:", results)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.18 SourcesApi

sources_api = cdb_api_factory.get_sources_api()

Get Source List (GET /api/Sources/all)

try:
    sources = sources_api.get_source_list()
    print("Sources:", sources)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Source by ID (GET /api/Sources/ById/{id})

try:
    source = sources_api.get_source_by_id(1)
    print("Source by ID:", source)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Source by Name (GET /api/Sources/ByName/{name})

try:
    source = sources_api.get_source_by_name("SourceName")
    print("Source by Name:", source)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.19 TestApi

test_api = cdb_api_factory.get_test_api()

Verify Authentication (GET /api/Test/Auth)

try:
    auth_status = test_api.verify_authenticated_1()
    print("Authenticated Test:", auth_status)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Verify Connection (No-Auth) (GET /api/Test/NoAuth)

try:
    connection_status = test_api.verify_connection()
    print("No-Auth Test:", connection_status)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get Sample Error Message (GET /api/Test/SampleErrorMessage)

try:
    error_message = test_api.get_sample_error_message()
    print("Sample Error Message:", error_message)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

3.20 UsersApi

users_api = cdb_api_factory.get_users_api()

Get All Users (GET /api/Users/all)

try:
    users = users_api.get_all_1()
    print("All Users:", users)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get User by Username (GET /api/Users/ByUsername/{username})

try:
    user = users_api.get_user_by_username("john_doe")
    print("User Info:", user)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

Get All Groups (GET /api/Users/allGroups)

try:
    groups = users_api.get_all_groups()
    print("All Groups:", groups)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

4. Fetching Supporting Classes (Technical Systems & Functions)

Many endpoints require references to item categories (technical systems) or item types (functions). Below are some common ways to fetch them:

  1. Item Categories / Technical Systems

    • Use DomainApi to fetch categories:

      domain_api.get_item_category_by_id(10)
domain_api.get_domain_category_list(domain_id)

    • These can be included in calls such as technicalSystemList=[...] or technicalSystemIds=[...].

  2. Item Types / Functions

    • Use DomainApi to fetch item types:

      domain_api.get_item_type_by_id(20)
domain_api.get_domain_type_list(domain_id)

    • These can be included in calls such as functionList=[...] or typeList=[...].

  3. Other references

    • Projects can be found via SearchApi or by scanning items in ItemApi.
    • Users or Groups can be found via UsersApi.
    • Connector types can be found via ConnectorTypesApi.
    • Property types can be found via PropertyTypeApi.

Once retrieved, you pass the resulting object(s) or IDs into the relevant request body or parameter.

5. Error Handling

All API methods raise exceptions of type OpenAPIException. Use the factory’s utility function to parse these exceptions. For example:

from cdbApi import OpenAPIException

try:
    result = cdb_api_factory.get_item_api().some_method(...)
except OpenAPIException as e:
    print(cdb_api_factory.parseApiException(e))

This approach standardizes error messages and facilitates easier debugging.

6. Additional Notes

Below is a quick snippet showing how to generate a date string in Python using the format %a %b %d 00:00:00 CDT %Y, which is requested for certain fields like effectiveFromDate:

import datetime

# Create a date object (example: March 1, 2025)
dt = datetime.datetime(2025, 3, 1)

# Format the date string
date_string = dt.strftime('%a %b %d 00:00:00 CDT %Y')
print(date_string)
# Example output: Sat Mar 01 00:00:00 CDT 2025
  • Method and Model Naming: Method names (e.g., create_app, get_item_by_id) and model class names (e.g., NewInventoryInformation, ItemDomainMachineDesign) are generated from the OpenAPI definition, providing an abstraction over raw HTTP calls.
  • Image Scaling Values: When calling get_image(imageName, scaling), the allowed scaling values are "scaled", "thumbnail", or "original".
  • Customization: The generated client is fully customizable. You can extend models, add request interceptors, or modify the configuration as needed.
  • Reference: For a full list of endpoints and model details, refer to your local OpenAPI document or the compiled specification for version 3.16.1.dev1.

This documentation fully covers usage for version 3.16.1.dev1 of the Python client, clarifies how item types are also known as functions, item categories are also known as technical systems, and includes references for fetching the supporting classes needed for these fields.

Clone this wiki locally