Xurrent Module
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
Contributing
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.