Skip to main content

Xurrent Module

PyPI version Downloads License: GPL v3

This module is used to interact with the Xurrent API. It provides a class per Xurrent resource (requests, tasks, workflows, people, CIs, ...) and handles authentication (API token or OAuth client credentials), pagination and rate limits.

pip install xurrent

Documentation

The API reference has a page per class with its fields, enums, methods (with the API endpoint each one calls) and cross references to the other classes:

Class API resource Class API resource
Calendar /calendars Request /requests
ClosureCode /closure_codes RequestTemplate /request_templates
ConfigurationItem /cis Risk /risks
Contract /contracts Service /services
CustomCollection /custom_collections ServiceInstance /service_instances
CustomCollectionElement /custom_collection_elements ServiceOffering /service_offerings
EffortClass /effort_classes ShopArticle /shop_articles
Holiday /holidays ShopArticleCategory /shop_article_categories
KnowledgeArticle /knowledge_articles ShopOrderLine /shop_order_lines
Organization /organizations Site /sites
OutOfOfficePeriod /out_of_office_periods SkillPool /skill_pools
Person /people Task /tasks
Problem /problems Team /teams
Product /products TimeAllocation /time_allocations
ProductCategory /product_categories UiExtension /ui_extensions
Project /projects Workflow /workflows
ProjectTask /project_tasks WorkflowTemplate /workflow_templates
Release /releases

Change Log

ChangeLog.md

Contributing

Contributing.md

Usage

Basic Usage

    from xurrent.core import XurrentApiHelper

    apitoken = "********"

    baseUrl = "https://api.xurrent.qa/v1"
    account = "account-name"

    x_api_helper = XurrentApiHelper(baseUrl, apitoken, account)

    # change log level (default: INFO)
    x_api_helper.set_log_level("DEBUG")

    # Plain API Call
    uri = "/requests?subject=Example Subject"
    x_api_helper.api_call(uri, 'GET')

    # Convert node ID
    x_api_helper.decode_api_id('ZmFiaWFuc3RlaW5lci4yNDEyMTAxMDE0MTJANG1lLWRlbW8uY29tL1JlcS83MDU3NTU') # fabiansteiner.241210101412@4me-demo.com/Req/705755
    # this can be used to derive the ID from the nodeID

Using OAuth client credentials

You can let the helper automatically request and refresh bearer tokens by providing the OAuth client_id and client_secret that were issued to your application. The original API key flow continues to work unchanged, but only one authentication method may be used per helper instance.

    from xurrent.core import XurrentApiHelper

    baseUrl = "https://api.xurrent.qa/v1"
    account = "account-name"
    client_id = "your-client-id"
    client_secret = "your-client-secret"

    x_api_helper = XurrentApiHelper(
        baseUrl,
        api_account=account,
        client_id=client_id,
        client_secret=client_secret,
    )

    response = x_api_helper.api_call("/requests", "GET")

Configuration Items

    # Example usage of ConfigurationItem class
    from xurrent.configuration_items import ConfigurationItem
    
    # Get a Configuration Item by ID
    ci = ConfigurationItem.get_by_id(x_api_helper, <id>)
    print(ci)

    # List all Configuration Items
    all_cis = ConfigurationItem.get_configuration_items(x_api_helper)
    print(all_cis)

    # List active Configuration Items
    active_cis = ConfigurationItem.get_configuration_items(x_api_helper, predefinedFilter="active")
    print(active_cis)

    # Update a Configuration Item
    updated_ci = ci.update({"name": "Updated Name", "status": "being_repaired"})
    print(updated_ci)

    # Create a new Configuration Item
    # creating without specifying the label, takes the last ci of the product and increments the label
    # example: "wdc-02" -> "wdc-03"
    data = {"name": "New CI", "status": "in_production", "product_id": "<product_id>"}
    new_ci = ConfigurationItem.create(x_api_helper, data)
    print(new_ci)

    # Archive a Configuration Item (must be in an allowed state)
    try:
        archived_ci = ci.archive()
        print(archived_ci)
    except ValueError as e:
        print(f"Error: {e}")

    # Trash a Configuration Item (must be in an allowed state)
    try:
        trashed_ci = ci.trash()
        print(trashed_ci)
    except ValueError as e:
        print(f"Error: {e}")

    # Restore a Configuration Item
    restored_ci = ci.restore()
    print(restored_ci)

People

    from xurrent.people import Person

    person = Person.get_by_id(x_api_helper, <id>)

    api_user = Person.get_me(x_api_helper)

    # get all people with a specific name
    people = Person.get_people(x_api_helper, queryfilter={
        "name": "Werner"
    })

    # enable
    person.enable()

    #disable
    person.disable()
    #archive
    person.archive()
    #trash
    person.trash()
    #restore
    person.restore()

Requests

    from xurrent.requests import Request

    request = Request.get_by_id(x_api_helper, <id>)

    # get all requests with a specific subject
    requests = Request.get_requests(x_api_helper, queryfilter={
        "subject": "Example Subject"
    })

    # close
    request.close("closed")

    # archive
    request.archive()

    #trash
    request.trash()

    #restore

    request.restore()
Request Configuration Items
    from xurrent.requests import Request

    # Get Configuration Items for a Request
    request_id = <request_id>


    # Add a Configuration Item to a Request
    ci_id = <ci_id>
    try:
        response = Request.add_ci_to_request_by_id(x_api_helper, request_id, ci_id)
        print("CI added:", response)
    except ValueError as e:
        print(f"Error: {e}")

    cis = Request.get_cis_by_request_id(x_api_helper, request_id)
    print(cis)

    # Remove a Configuration Item from a Request
    try:
        response = Request.remove_ci_from_request_by_id(x_api_helper, request_id, ci_id)
        print("CI removed:", response)
    except ValueError as e:
        print(f"Error: {e}")

    # Instance-based example
    req = Request.get_by_id(x_api_helper, request_id)

    # Add a CI to this request
    try:
        response = req.add_ci(ci_id)
        print("CI added:", response)
    except ValueError as e:
        print(f"Error: {e}")

    # Get CIs for this request
    cis_instance = req.get_cis()
    print(cis_instance)

    # Remove a CI from this request
    try:
        response = req.remove_ci(ci_id)
        print("CI removed:", response)
    except ValueError as e:
        print(f"Error: {e}")
Request Notes
    from xurrent.requests import Request
    
    from xurrent.requests import PredefinedNotesFilter

    request = Request.get_by_id(x_api_helper, <id>)

    # a note of the request by its ID
    request_note = request.get_note_by_id(<note_id>)

    # all public notes of the request
    request_notes = request.get_notes(predefinedFilter=PredefinedNotesFilter.public)

    # only the newest note (one API call with per_page=1); the same for tasks, problems, project tasks, ...
    newest = request.get_notes(sort="-created_at", max_results=1)

    request.add_note("This is a test note")
    request.add_note({
        "text": "This is a test note",
        "internal": True
    })

Tasks

    from xurrent.tasks import Task

    task = Task.get_by_id(x_api_helper, <id>)

    # get all tasks with a specific subject
    tasks = Task.get_tasks(x_api_helper, queryfilter={
        "subject": "Example Subject"
    })

    # get workflow of task (use expand=True to read the full workflow from the API)
    workflow = task.get_workflow(expand=True)
    # or statically, by the ID of the task
    workflow = Task.get_workflow_of_task(x_api_helper, <task_id>, expand=True)

    # close
    task.close()
    #cancel
    task.cancel() # only possible before the task is started
    #reject
    task.reject()
    #approve
    task.approve()

Project Tasks

    from xurrent.project_tasks import ProjectTask, ProjectTaskPredefinedFilter

    project_task = ProjectTask.get_by_id(x_api_helper, <id>)

    # get the project tasks assigned to the API user (at most 50)
    project_tasks = ProjectTask.get_project_tasks(x_api_helper, predefinedFilter=ProjectTaskPredefinedFilter.assigned_to_me, max_results=50)

    # notes
    notes = project_task.get_notes()
    project_task.add_note("This is a test note")
    project_task.add_note({"text": "This is a test note", "suppress_note_added_notifications": True})

Teams

    from xurrent.teams import Team, TeamPredefinedFilter

    team = Team.get_by_id(x_api_helper, <id>)

    # get all enabled teams
    teams = Team.get_teams(x_api_helper, predefinedFilter=TeamPredefinedFilter.enabled)

    # enable
    team.enable()

    #disable
    team.disable()
    #archive
    team.archive()
    #trash
    team.trash()
    #restore
    team.restore()

Workflows

    from xurrent.workflows import Workflow

    workflow = Workflow.get_by_id(x_api_helper, <id>)

    #close
    workflow.close() # completion reason: complete, note: "closed."
    # close with completion reason
    workflow.close(completion_reason="withdrawn")
    #close with completion reason and note
    workflow.close(completion_reason="withdrawn", note="This is a test note")

Limiting results

List calls follow the pagination of the API and return all records by default. Pass max_results to stop after that many records:

    from xurrent.requests import Request

    # at most 25 requests assigned to the API user
    requests = Request.get_requests(x_api_helper, predefinedFiler="assigned_to_me", max_results=25)

    # at most 10 knowledge articles matching a full-text search, sorted by relevance
    results = x_api_helper.search("printer", types=["knowledge-article"], max_results=10)

    # plain API call
    x_api_helper.api_call("/requests/open", "GET", max_results=100)

Bulk Export

    import csv
    import io

    #Request a bulk export of "people" (returns the file as bytes)
    csvdata = x_api_helper.bulk_export("people").decode("utf-8-sig")

    #Iterate fetched export rows with the csv library, where row 1 defines the column names
    for row in csv.DictReader(io.StringIO(csvdata)):
        print(row["Employee Number"])

Metadata

Release files for xurrent 0.16.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xurrent 0.16.0
File Size Uploaded Provenance Actions
xurrent-0.16.0.tar.gz 52.0 kB With provenance Details for xurrent-0.16.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xurrent 0.16.0
File Interpreter ABI Platform Actions
xurrent-0.16.0-py3-none-any.whl Python 3 none any Details for xurrent-0.16.0-py3-none-any.whl

Total release size: 136.5 kB

Release files / xurrent-0.16.0.tar.gz

Download URL xurrent-0.16.0.tar.gz
Size 52.0 kB
Tags Source
SHA-256 checksum
How to use checksums
e45d80c06e5fb8fbbf1f05a25a59d5ee9aa8199fc59cf403d6e552120141becd
BLAKE2b-256 checksum
How to use checksums
66e524fc76bfe84b35f9be211f771e817727eb99398cadc512dfb5f70cdd5677
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / xurrent-0.16.0-py3-none-any.whl

Download URL xurrent-0.16.0-py3-none-any.whl
Size 84.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1d6c429cec2744520c11e8e3afefae87f3d3bb7c38873ffd2f7aeef3db4a8391
BLAKE2b-256 checksum
How to use checksums
e9884fe686b703ef177ca71e99c03337df81f266049cf753c66f8f7a3fef2de6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for xurrent 0.16.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xurrent-0.16.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page