PyRelatics2

Python package to interact with Relatics v5 webservices.

This package allows you to interact with Relatics v5 webservices in two ways:

• Get data from a "Servers for providing data" webservice.
• Submit data to a "Servers for receiving data" webservice.

Three authentication methods are supported: "OAuth 2.0 - Client credentials", "Entry code" and "Unauthenticated".

Setting up

from pyrelatics2 import RelaticsWebservices

client = RelaticsWebservices("company_subdomain", "workspace_id")

When using "OAuth 2.0 - Client credentials", the client credentials can be stored in a dedicated class instance for later use.

from pyrelatics2 import ClientCredential

cc = ClientCredential(client_id="client_id", client_secret="client_secret")

Example of getting data

Getting data with "OAuth 2.0 - Client credentials":

from pyrelatics2 import ClientCredential, RelaticsWebservices

cc = ClientCredential(client_id="client_id", client_secret="client_secret")
client = RelaticsWebservices("company_subdomain", "workspace_id")

# Optionally prepare a dictionary of parameters
parameters = {
    "sample_parameter_name_1": "sample_parameter_value_1",
    "sample_parameter_name_2": "sample_parameter_value_2",
}

client.get_result(operation_name="sample_operation", parameters=parameters, authentication=cc)

Other forms of authentication can also be used:

from pyrelatics2 import RelaticsWebservices

client = RelaticsWebservices("company_subdomain", "workspace_id")

# Authentication via entry code
entry_code = "sample_entry_code"
client.get_result(operation_name="sample_operation", parameters=None, authentication=entry_code)

# No authentication
client.get_result(operation_name="sample_operation", parameters=None, authentication=None)

Example of sending data

Sending data with "OAuth 2.0 - Client credentials", with data as list:

from pyrelatics2 import ClientCredential, RelaticsWebservices

cc = ClientCredential(client_id="client_id", client_secret="client_secret")
client = RelaticsWebservices("company_subdomain", "workspace_id")

# Prepare the data to be send
data = [
    {"name": "test name 1", "description": "test description 1"},
    {"name": "test name 2", "description": "test description 2"},
]

client.run_import(operation_name="sample_operation", data=data, authentication=cc)

Again, other forms of authentication can also be used:

from pyrelatics2 import RelaticsWebservices

client = RelaticsWebservices("company_subdomain", "workspace_id")
data = [{"name": "test 1", "description": "desc 1"},{"name": "test 2", "description": "desc 2"}]

# Authentication via entry code
entry_code = "sample_entry_code"
client.run_import(operation_name="sample_operation", data=data, authentication=entry_code)

# No authentication
client.run_import(operation_name="sample_operation", data=data, authentication=None)

Example of sending data and documents

It is possible to include documents as part of the upload, as described in Use import for uploading files. Simply add list of the filepaths to be included.

from pyrelatics2 import ClientCredential, RelaticsWebservices

cc = ClientCredential(client_id="client_id", client_secret="client_secret")
client = RelaticsWebservices("company_subdomain", "workspace_id")

# Prepare the data and documents to be send
data = [
    {"name": "test name 1", "description": "test description 1", "reference": "file_a.jpg"},
    {"name": "test name 2", "description": "test description 2", "reference": "file_b.jpg"},
]
documents=[
    "sample-data\\file_a.jpg",
    "sample-data\\file_b.jpg",
]

client.run_import(operation_name="sample_operation", data=data, authentication=cc, documents=documents)

Example of sending data from a file

Instead of supplying the data with a list, it is possible to give the filepath of a supported file type. Supported file type are defined in Supported file types for import as "MS Excel, XML and comma-separated ASCII". The code will except these file extensions: xlsx, xlsm, xlsb, xls or csv.

from pyrelatics2 import ClientCredential, RelaticsWebservices

cc = ClientCredential(client_id="client_id", client_secret="client_secret")
client = RelaticsWebservices("company_subdomain", "workspace_id")

# Prepare the data and documents to be send
data = "sample-data\\sample_data.xlsx"

client.run_import(operation_name="sample_operation", data=data, authentication=cc)

Result of get_result()

The raw response of an export will be processed into a ExportResult object ¹. When an error was registered, it will become Falsly for easy checking. The ExportResult object will contain any documents that were part of the response. They will be extracted from the raw base64 encoded zipfile in the original response, into a dict.

Result of run_import()

The raw response of an import will be processed into a ImportResult object ¹. When an error was registered, it will become Falsly for easy checking. The ImportResult object will contain all the messages, including properties to easily retrieve them by their status (Progress, Comment, Success, Warning, Error).

The ImportResult object also includes all the updated that Relatics made to instances. They contain their ID and possible ForeignKey. Properties are available to easily retrieve them by their action (Add, Update).

When the ImportResult object is print(), it will display a formatted and human presentable outcome of the import process.

Exceptions

In addition to basic Exceptions, there is a custom exceptions the code will raise:

• TokenRequestError: When the token for a "OAuth 2.0 - Client credentials" authentication could not be retrieved.

Logging

This package uses the standard Python logging functionality. Logging can be activated with:

import logging

LOG_FORMAT = "%(asctime)s %(name)s %(levelname)s %(message)s"  # Define a custom log format
logging.basicConfig(level=logging.INFO, format=LOG_FORMAT)

logging.getLogger("pyrelatics2.client").setLevel(logging.DEBUG)

Logging is available in these modules for debugging purpose: pyrelatics2.client, pyrelatics2.exceptions and pyrelatics2.result_classes.

Development

To install this package for development, use this command in your venv:

pip install -e ".[dev]"