Client¶

class Client(url: str = 'http://localhost:8000/', check_certificates: bool | None = None)[source]¶

The KE-chain python client to connect to a KE-chain instance.

Variables:

last_request – last executed request. Which is of type requests.Request
last_response – last executed response. Which is of type requests.Response
last_url – last called api url

Create a KE-chain client with given settings.

Parameters:

url (basestring) – the url of the KE-chain instance to connect to (defaults to http://localhost:8000)
check_certificates (bool) – if to check TLS/SSL Certificates. Defaults to True

Examples

>>> from pykechain import Client
>>> client = Client()

>>> from pykechain import Client
>>> client = Client(url='https://default-tst.localhost:9443', check_certificates=False)

classmethod from_env(env_filename: str | None = None, check_certificates: bool | None = None) → Client[source]¶

Create a client from environment variable settings.

Parameters:

env_filename (basestring) – filename of the environment file, defaults to ‘.env’ in the local dir (or parent dir)
check_certificates (bool) – if to check TLS/SSL Certificates. Defaults to True

Returns:

pykechain.Client

Example

Initiates the pykechain client from the contents of an environment file. Authentication information is optional but ensure that you provide this later in your code. Offered are both username/password authentication and user token authentication.

.env¶

 # User token here (required)
 KECHAIN_TOKEN=...<secret user token>...
 KECHAIN_URL=https://an_url.ke-chain.com

 # or use Basic Auth with username/password
 KECHAIN_USERNAME=...
 KECHAIN_PASSWORD=...

 # optional add a scope name or scope id
 KECHAIN_SCOPE=...
 KECHAIN_SCOPE_ID=...

>>> client = Client().from_env()

login(username: str | None = None, password: str | None = None, token: str | None = None) → None[source]¶

Login into KE-chain with either username/password or token.

Parameters:

username (basestring) – username for your user from KE-chain
password (basestring) – password for your user from KE-chain
token (basestring) – user authentication token retrieved from KE-chain

Examples

Using Token Authentication (retrieve user Token from the KE-chain instance)

>>> client = Client()
>>> client.login(token='<some-super-long-secret-token>')

Using Basic authentications (Username/Password)

>>> client = Client()
>>> client.login(username='user', password='pw')

>>> client = Client()
>>> client.login('username','password')

property app_versions: List[Dict]¶: List of the versions of the internal KE-chain ‘app’ modules.

property widget_schemas: Dict¶

Widget meta schemas for all widgets in KE-chain 3.

In KE-chain 3, the backend provides widget meta schema for each widgettype. A single call per pykechain client session is made (and cached forever in the client) to retrieve all widget schemas.

..versionadded:: 3.0

Returns:

list of widget meta schemas

Return type:

list of dict

Raises:

APIError – When it could not retrieve the widget schemas
NotImplementedError – When the KE-chain version is lower than 3.

widget_schema(widget_type: str) → Dict[source]¶

Widget schema for widget type.

..versionadded:: 3.0

Parameters:

widget_type (basestring) – Type of the widget to return the widgetschema for.

Returns:

dictionary with jsonschema to validate the widget meta

Return type:

dict

Raises:

APIError – When it could not retrieve the jsonschema from KE-chain
NotFoundError – When it could not find the correct schema

match_app_version(app: str | None = None, label: str | None = None, version: str | None = None, default: bool | None = False) → bool[source]¶

Match app version against a semantic version string.

Checks if a KE-chain app matches a version comparison. Uses the semver matcher to check.

match(“2.0.0”, “>=1.0.0”) => True match(“1.0.0”, “>1.0.0”) => False

Examples

>>> client = Client()
>>> client.match_app_version(label='wim', version=">=1.99")
>>> True

>>> client.match_app_version(app='kechain2.core.pim', version=">=1.0.0")
>>> True

Parameters:

app (basestring or None) – (optional) appname eg. ‘kechain.core.wim’
label (basestring or None) – (optional) app label (last part of the app name) eb ‘wim’
version (basestring) – semantic version string to match appname version against eg ‘2.0.0’ or ‘>=2.0.0’
default (bool or None) – (optional) boolean to return if the version of the app is not set but the app found. Set to None to return a NotFoundError when a version if not found in the app.

Returns:

True if the version of the app matches against the match_version, otherwise False

Raises:

IllegalArgumentError – if no app nor a label is provided
NotFoundError – if the app is not found
ValueError – if the version provided is not parseable by semver, should contain (<operand><major>.<minor>.<patch) where <operand> is ‘>,<,>=,<=,==’

reload(obj: Base, url: str | None = None, extra_params: Dict | None = None)[source]¶

Reload an object from server. The original object is immutable and it will return a new object.

The object will be refetched from KE-chain. If the object has a ‘url’ field the url will be taken from that field (KE-chain version 2 and newer). If the object does not have an ‘url’ field it will be constructed based on the class name and the id of the object itself. If extra_params are provided, these will be respected. If additional API params are needed to be included (eg. for KE-chain 3/PIM2) these will be added/updated automatically before the request is performed.

Parameters:

obj (obj) – object to reload
url (basestring or None) – (optional) url to use
extra_params (dict) – additional object specific extra query string params (eg for activity)

Returns:

a new object

Raises:

NotFoundError – if original object is not found or deleted in the mean time

scopes(name: str | None = None, pk: str | None = None, status: ScopeStatus | str | None = 'ACTIVE', **kwargs) → List[Scope][source]¶

Return all scopes visible / accessible for the logged in user.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Parameters:

name (basestring or None) – if provided, filter the search for a scope/project by name
pk (basestring or None) – if provided, filter the search by scope_id
status (basestring or None) – if provided, filter the search for the status. eg. ‘ACTIVE’, ‘TEMPLATE’, ‘LIBRARY’
kwargs – optional additional search arguments

Returns:

list of Scopes

Return type:

list(models.Scope)

Raises:

NotFoundError – if no scopes are not found.

Example

>>> client = Client(url='https://default.localhost:9443', verify=False)
>>> client.login('admin','pass')
>>> client.scopes()  
...

>>> client.scopes(name="Bike Project")  
...

>>> last_request = client.last_request  
...

scope(*args, **kwargs) → Scope[source]¶

Return a single scope based on the provided name.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Returns:

a single models.Scope

Raises:

NotFoundError – When no Scope is found
MultipleFoundError – When more than a single Scope is found

activities(name: str | None = None, pk: str | None = None, scope: str | None = None, **kwargs) → List[Activity][source]¶

Search for activities with optional name, pk and scope filter.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Parameters:

pk (basestring or None) – id (primary key) of the activity to retrieve
name (basestring or None) – filter the activities by name
scope (basestring or None) – filter by scope id

Returns:

list of models.Activity

Raises:

NotFoundError – If no Activities are found

activity(*args, **kwargs) → Activity[source]¶

Search for a single activity.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Parameters:

pk (basestring or None) – id (primary key) of the activity to retrieve
name (basestring or None) – filter the activities by name
scope (basestring or None) – filter by scope id

Returns:

a single models.Activity

Raises:

NotFoundError – When no Activity is found
MultipleFoundError – When more than a single Activity is found

Retrieve multiple KE-chain parts.

If no parameters are provided, all parts are retrieved.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Parameters:

name (basestring or None) – filter on name
pk (basestring or None) – filter on primary key
model (basestring or None) – filter on model_id
category (basestring or None) – filter on category (INSTANCE, MODEL, None)
scope_id (basestring or None) – filter on scope_id
parent (basestring or None) – filter on the parent_id, returns all children of the parent_id
activity (basestring or None) – filter on activity_id
widget – filter on widget_id
limit (int or None) – limit the return to # items (default unlimited, so return all results)
batch (int or None) – limit the batch size to # items (defaults to 100 items per batch)
kwargs – additional keyword=value arguments for the api

Returns:

models.PartSet which is an iterator of models.Part

Raises:

NotFoundError – If no Part is found

Examples

Return all parts (defaults to instances) with exact name ‘Gears’.

>>> client = Client(url='https://default.localhost:9443', verify=False)
>>> client.login('admin','pass')
>>> client.parts(name='Gears')  
...

Return all parts with category is MODEL or category is INSTANCE.

>>> client.parts(name='Gears', category=None)  
...

Return a maximum of 5 parts

>>> client.parts(limit=5)  
...

part(*args, **kwargs) → Part[source]¶

Retrieve single KE-chain part.

Uses the same interface as the parts() method but returns only a single pykechain models.Part instance.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

When only the pk is provided as an input for the part search, the detail route will be called.

Returns:

a single models.Part

Raises:

NotFoundError – When no Part is found
MultipleFoundError – When more than a single Part is found

model(*args, **kwargs) → Part[source]¶

Retrieve single KE-chain part model.

Uses the same interface as the part() method but returns only a single pykechain models.Part instance of category MODEL.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

When only the id or pk is provided, the detail route for the part id will be called.

Returns:

a single models.Part

Raises:

NotFoundError – When no Part is found
MultipleFoundError – When more than a single Part is found

properties(name: str | None = None, pk: str | None = None, category: Category | str | None = 'INSTANCE', **kwargs) → List[AnyProperty][source]¶

Retrieve properties.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Parameters:

name (basestring or None) – name to limit the search for.
pk (basestring or None) – primary key or id (UUID) of the property to search for
category (basestring or None) – filter the properties by category. Defaults to INSTANCE. Other options MODEL or None
kwargs – (optional) additional search keyword arguments

Returns:

list of models.Property

Raises:

NotFoundError – When no Property is found

property(*args, **kwargs) → AnyProperty[source]¶

Retrieve single KE-chain Property.

Uses the same interface as the properties() method but returns only a single pykechain models.Property instance.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

When only the pk is provided as an input for the part search, the detail route will be called.

Returns:

a single models.Property

Raises:

NotFoundError – When no Property is found
MultipleFoundError – When more than a single Property is found

services(name: str | None = None, pk: str | None = None, scope: str | None = None, **kwargs) → List[Service][source]¶

Retrieve Services.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Parameters:

name (basestring or None) – (optional) name to limit the search for
pk (basestring or None) – (optional) primary key or id (UUID) of the service to search for
scope (basestring or None) – (optional) id (UUID) of the scope to search in
kwargs – (optional) additional search keyword arguments

Returns:

list of models.Service objects

Raises:

NotFoundError – When no Service objects are found

service(*args, **kwargs)[source]¶

Retrieve single KE-chain Service.

Uses the same interface as the services() method but returns only a single pykechain models.Service instance.

Parameters:

kwargs – (optional) additional search keyword arguments

Returns:

a single models.Service object

Raises:

NotFoundError – When no Service object is found
MultipleFoundError – When more than a single Service object is found

service_executions(name: str | None = None, pk: str | None = None, scope: str | None = None, service: str | None = None, **kwargs) → List[ServiceExecution][source]¶

Retrieve Service Executions.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Parameters:

name (basestring or None) – (optional) name to limit the search for
pk (basestring or None) – (optional) primary key or id (UUID) of the service to search for
scope (basestring or None) – (optional) id (UUID) of the scope to search in
service (basestring or None) – (optional) service UUID to filter on
kwargs – (optional) additional search keyword arguments

Returns:

a single models.ServiceExecution object

Raises:

NotFoundError – When no ServiceExecution object is found

service_execution(*args, **kwargs)[source]¶

Retrieve single KE-chain ServiceExecution.

Uses the same interface as the service_executions() method but returns only a single pykechain models.ServiceExecution instance.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Parameters:

kwargs – (optional) additional search keyword arguments

Returns:

a single models.ServiceExecution object

Raises:

NotFoundError – When no ServiceExecution object is found
MultipleFoundError – When more than a single ServiceExecution object is found

users(username: str | None = None, pk: str | None = None, **kwargs) → List[User][source]¶

Users of KE-chain.

Provide a list of User’s of KE-chain. You can filter on username or id or any other advanced filter.

Parameters:

username (basestring or None) – (optional) username to filter
pk (basestring or None) – (optional) id of the user to filter
kwargs – Additional filtering keyword=value arguments

Returns:

List of Users

Raises:

NotFoundError – when a user could not be found

user(*args, **kwargs) → User[source]¶

User of KE-chain.

Provides single user of User of KE-chain. You can filter on username or id or an advanced filter.

Parameters:

kwargs – Additional filtering keyword=value arguments

Returns:

List of User

Raises:

NotFoundError – when a user could not be found
MultipleFoundError – when more than a single user can be found

current_user() → User[source]¶

Retrieve the User object logged in to the Client.

:raises APIError if not logged in yet. :raises NotFoundError if user could not be found. :returns User :rtype User

Create a new User in KE-chain.

The user is created in KE-chain. It is highly encouraged to provide a name for the user. Optionally one may choose to send out a forgot password link to the newly created user.

Parameters:

username – username of the user
email – email of the user
name – (optional) full human name of the user
team_ids – (optional) list of Team or Team id’s to which the user should be added.
language_code – (optional) the Language of the user. One of LanguageCodes. Eg. “nl”
timezone – (optional) the timezone name of the user. Eg. “Europe/Amsterdam”
send_passwd_link – (optional) boolean to send out a password reset link after the user is created. Defaults to False.

teams(name: str | None = None, pk: str | None = None, is_hidden: bool | None = False, **kwargs) → List[Team][source]¶

Teams of KE-chain.

Provide a list of Team’s of KE-chain. You can filter on teamname or id or any other advanced filter.

Parameters:

name (basestring or None) – (optional) teamname to filter
pk (basestring or None) – (optional) id of the team to filter
is_hidden (bool or None) – (optional) boolean to show non-hidden or hidden teams or both (None) (default is non-hidden)
kwargs – Additional filtering keyword=value arguments

Returns:

List of Teams

Raises:

NotFoundError – when a team could not be found

team(*args, **kwargs)[source]¶

Team of KE-chain.

Provides a team of Team of KE-chain. You can filter on team name or provide id.

Parameters:

kwargs – Additional filtering keyword=value arguments

Returns:

List of Team

Raises:

NotFoundError – when a user could not be found
MultipleFoundError – when more than a single user can be found

widgets(pk: str | None = None, activity: Activity | str | None = None, **kwargs) → List[Widget][source]¶

Widgets of an activity.

Only works for KE-chain version 3.

Parameters:

pk (basestring or None) – (optional) the uuid of the widget.
activity (basestring or None) – (optional) the Activity or UUID of the activity to filter the widgets for.
kwargs – additional keyword arguments

Returns:

A list of Widget objects

Return type:

List

Raises:

NotFoundError – when the widgets could not be found
APIError – when the API does not support the widgets, or when the API gives an error.

widget(*args, **kwargs) → Widget[source]¶

Retrieve a single widget.

Returns:: Widget

create_activity(parent: Activity | str, name: str, activity_type: ActivityType = 'TASK', ref: str | None = None, status: ActivityStatus = 'OPEN', description: str | None = None, start_date: datetime | None = None, due_date: datetime | None = None, classification: ActivityClassification | None = None, tags: List[str] | None = None, **kwargs) → Activity[source]¶

Create a new activity.

Parameters:

parent (basestring or models.Activity) – parent under which to create the activity
name (basestring) – new activity name
activity_type (basestring) – type of activity: TASK (default) or PROCESS
ref (basestring) – activity ref, slug
status (ActivityStatus) – status of the activity: OPEN (default) or COMPLETED
description (basestring) – description of the activity
start_date (datetime.datetime) – starting date of the activity
due_date (datetime.datetime) – due date of the activity
classification (ActivityClassification) – classification of activity: defaults to parent’s if provided, WORKFLOW otherwise.
tags (list) – list of activity tags

Returns:

the created models.Activity

Raises:

APIError – When the object could not be created
IllegalArgumentError – When an incorrect arguments are provided

Clone multiple activities.

New in version 3.7: The bulk clone activities with parts API is included in KE-chain backend since version 3.6.

Parameters:

activities (list) – list of Activity object or UUIDs
activity_parent (Activity) – parent Activity sub-process object or UUID
activity_update_dicts –
1. dict of dictionaries, each key-value combination relating to an activity

to clone and a dict of new values to assign, e.g. {activity.id: {“name”: “Cloned activity”}} :type activity_update_dicts: dict :param include_part_models: (O) whether to clone the data models configured in the activities, defaults to False :type include_part_models: bool :param include_part_instances: (O) whether to clone the part instances of the data model configured in the

activities, defaults to True

Parameters:

include_children (bool) –
1. whether to clone child parts
excluded_parts (list) – (O) list of Part2 objects or UUIDs to exclude from being cloned, maintaining the original configuration of the widgets.
part_parent_model (Part) –
1. parent Part object or UUID for the copied data model(s)
part_parent_instance (Part) –
1. parent Part object or UUID for the copied part instance(s)
part_model_rename_template (str) –
1. renaming template for part models. Must contain “{name}”
part_instance_rename_template (str) –
1. renaming template for part instances. Must contain “{name}”
asynchronous (bool) – If true, immediately returns without activities (default = False)

Returns:

list of cloned activities

Return type:

list

:raises APIError if cloned

update_activities(activities: List[Dict]) → None[source]¶

Update multiple activities in bulk.

Parameters:: activities – list of dicts, each specifying the updated data per activity.

:raises APIError :return: None

create_part(parent: Part, model: Part, name: str | None = None, **kwargs) → Part[source]¶

Create a new part instance from a given model under a given parent.

In order to prevent the backend from updating the frontend you may add suppress_kevents=True as additional keyword=value argument to this method. This will improve performance of the backend against a trade-off that someone looking at the frontend won’t notice any changes unless the page is refreshed.

Parameters:

parent (models.Part) – parent part instance of the new instance
model (models.Part) – target part model on which the new instance is based
name (basestring) – new part name
kwargs – (optional) additional keyword=value arguments

Returns:

Part (category = instance)

Returns:

models.Part with category INSTANCE

Raises:

IllegalArgumentError – When the provided arguments are incorrect
APIError – if the Part could not be created

create_model(parent: Part | str, name: str, multiplicity: Multiplicity | None = 'ZERO_MANY', **kwargs) → Part[source]¶

Create a new child model under a given parent.

In order to prevent the backend from updating the frontend you may add suppress_kevents=True as additional keyword=value argument to this method. This will improve performance of the backend against a trade-off that someone looking at the frontend won’t notice any changes unless the page is refreshed.

Parameters:

parent (models.Part) – parent part instance or a part uuid
name (basestring) – new part name
multiplicity (basestring) – choose between ZERO_ONE, ONE, ZERO_MANY, ONE_MANY or M_N enums.Multiplicity
kwargs – (optional) additional keyword=value arguments

Returns:

models.Part with category MODEL (from enums.Category)

Raises:

IllegalArgumentError – When the provided arguments are incorrect
APIError – if the Part could not be created

create_model_with_properties(parent: Part | str, name: str, multiplicity: Multiplicity | None = 'ZERO_MANY', properties_fvalues: List[Dict] | None = None, **kwargs) → Part[source]¶

Create a model with its properties in a single API request.

With KE-chain 3 backends you may now provide a whole set of properties to create using a properties_fvalues list of dicts.

The properties_fvalues list is a list of dicts containing at least the name and property_type, but other keys may provided as well in the single update eg. default_value and value_options.

Possible keys in a property dictionary are: name (req’d), property_type (req’d), description, unit, value, value_options (type: dict), order (type int).

Note

It is wise to provide an order to ensure that the properties are stored and retrieved in order. It cannot be guaranteed that the order of properties is the exact sequence of the list provided.

New in version 3.0: This version makes a model including properties in a single API call

Parameters:

parent (models.Part) – parent part instance or a part uuid
name (basestring) – new part name
multiplicity (basestring) – choose between ZERO_ONE, ONE, ZERO_MANY, ONE_MANY or M_N of enums.Multiplicity
properties_fvalues (list) – list of dicts per property, each must have fields name and property_type.
kwargs – (optional) additional keyword=value arguments

Returns:

models.Part with category MODEL (of enums.Category)

Raises:

IllegalArgumentError – When the provided arguments are incorrect
APIError – if the Part could not be created

Example

>>> from pykechain.models.validators import RequiredFieldValidator
>>> properties_fvalues = [
...     {"name": "char prop", "property_type": PropertyType.CHAR_VALUE, "order": 1},
...     {"name": "number prop", "property_type": PropertyType.FLOAT_VALUE, "value": 3.14, "order": 2},
...     {"name": "boolean_prop", "property_type": PropertyType.BOOLEAN_VALUE, "value": False,
...      "value_options": {"validators": [RequiredFieldValidator().as_json()]}, "order":3}
... ]
>>> client = Client()
>>> new_model = client.create_model_with_properties(name='A new model', parent='<uuid>',
...                                                 multiplicity=Multiplicity.ONE,
...                                                 properties_fvalues=properties_fvalues)

create_proxy_model(model: Part, parent: Part, name: str, multiplicity: Multiplicity | None = 'ZERO_MANY', **kwargs) → Part[source]¶

Add this model as a proxy to another parent model.

This will add a model as a proxy model to another parent model. It ensure that it will copy the whole sub-assembly to the ‘parent’ model.

In order to prevent the backend from updating the frontend you may add suppress_kevents=True as additional keyword=value argument to this method. This will improve performance of the backend against a trade-off that someone looking at the frontend won’t notice any changes unless the page is refreshed.

Parameters:

model (models.Part) – the catalog proxy model the new proxied model should be based upon
parent (models.Part) – parent part instance
name (basestring) – new part name
multiplicity (basestring) – choose between ZERO_ONE, ONE, ZERO_MANY, ONE_MANY or M_N, default is ZERO_MANY
kwargs – (optional) additional keyword=value arguments

Returns:

the new proxy models.Part with category MODEL

Raises:

IllegalArgumentError – When the provided arguments are incorrect
APIError – if the Part could not be created

Create a new property model under a given model.

Use the enums.PropertyType to select which property type to create to ensure that you provide the correct values to the KE-chain backend. The default is a PropertyType.CHAR_VALUE which is a single line text in KE-chain.

Changed in version 3.0: Changed for KE-chan 3 backend. Added optional additional properties.

Parameters:

model (models.Part) – parent part model
name (basestring) – property model name
description (basestring or None) – property model description (optional)
property_type (basestring or None) – choose one of the enums.PropertyType, defaults to PropertyType.CHAR_VALUE.
default_value (any) – (optional) default value used for part instances when creating a model.
unit (basestring or None) – (optional) unit of the property
options (basestring or None) – (optional) property options (eg. validators or ‘single selectlist choices’)

Returns:

a models.Property with category MODEL

Raises:

IllegalArgumentError – When the provided arguments are incorrect
APIError – if the Property model could not be created

create_service(name: str, scope: Scope, description: str | None = None, version: str | None = None, service_type: ServiceType | None = 'PYTHON SCRIPT', environment_version: ServiceEnvironmentVersion | None = '3.8', run_as: ServiceScriptUser | None = 'kenode', pkg_path: str | None = None) → Service[source]¶

Create a Service.

A service can be created only providing the name (and scope). Other information can be added later. If you provide a path to the kecpkg (or python script) to upload (pkg_path) on creation, this kecpkg will be uploaded in one go. If the later fails, the service is still there, and the package is not uploaded.

Permission to upload a script is restricted to a superuser, a user in the GG:Configurators group and a Scope Manager of the scope to which you are uploading the script.

Parameters:

name (basestring) – Name of the service
scope (models.Scope) – Scope where the create the Service under
description (basestring or None) – (optional) description of the Service
version (basestring or None) – (optional) version information of the Service
service_type (basestring or None) – (optional) service type of the service (refer to pykechain.enums.ServiceType), defaults to PYTHON_SCRIPT
environment_version (basestring or None) – (optional) execution environment of the service (refer to pykechain.enums.ServiceEnvironmentVersion), defaults to PYTHON_3_8
run_as (basestring or None) – (optional) user to run the service as. Defaults to kenode user (bound to scope)
pkg_path (basestring or None) – (optional) full path name to the kecpkg (or python script) to upload

Returns:

the created models.Service

Raises:

IllegalArgumentError – When the provided arguments are incorrect
APIError – In case of failure of the creation or failure to upload the pkg_path
OSError – In case of failure to locate the pkg_path

Create a Scope.

This will create a scope if the client has the right to do so. Sufficient permissions to create a scope are a superuser, a user in the GG:Configurators group or GG:Managers group.

..versionadded: 2.6

Parameters:

name (basestring) – Name of the scope
status (basestring or None) – choose one of the enums.ScopeStatus, defaults to ScopeStatus.ACTIVE
description (basestring or None) – (optional) Description of the scope
tags (list or None) – (optional) List of tags to be added to the new scope
start_date (datetime.datetime or None) – (optional) start date of the scope. Will default to ‘now’ if not provided.
due_date (datetime.datetime or None) – (optional) due date of the scope
team (basestring or models.Team or None) – (optional) team_id or Team object to assign membership of scope to a team.
kwargs – optional additional search arguments

Returns:

the created models.Scope

Raises:

APIError – In case of failure of the creation of new Scope

delete_scope(scope: Scope, asynchronous: bool | None = True) → bool[source]¶

Delete a scope.

This will delete a scope if the client has the right to do so. Sufficient permissions to delete a scope are a superuser, a user in the GG:Configurators group or a user that is the Scope manager of the scope to be deleted.

Parameters:

scope – Scope object to be deleted
asynchronous (bool) – (optional) if the scope deletion should be performed asynchronous (default True)

Returns:

True when the delete is a success.

Raises:

APIError – in case of failure in the deletion of the scope

Clone a Scope.

This will clone a scope if the client has the right to do so. Sufficient permissions to clone a scope are a superuser, a user in the GG:Configurators group and a user that is Scope manager of the scope to be clone and member of the GG:Managers group as well.

If no additional arguments are provided, the values of the source_scope are used for the new scope.

Parameters:

source_scope (models.Scope) – Scope object to be cloned itself
name (basestring or None) – (optional) new name of the scope
status (one of enums.ScopeStatus) – (optional) statis of the new scope
tags (list or None) – (optional) list of new scope tags
start_date (datetime or None) – (optional) start date of the to be cloned scope
due_date (datetime or None) – (optional) due data of the to be cloned scope
description (basestring or None) – (optional) description of the new scope
team (basestring or models.Team or None) – (optional) team_id or Team object to assign membership of scope to a team.
scope_options (dict or None) – (optional) dictionary with scope options (NO EFFECT)
asynchronous (bool or None) – (optional) option to use asynchronous cloning of the scope, default to False.

Returns:

New scope that is cloned

Return type:

models.Scope

Raises:

IllegalArgumentError – When the provided arguments are incorrect
APIError – When the server is unable to clone the scope (eg. permissions)

Create a team.

To create a team, a User (id or object) need to be passed for it to become owner. As most pykechain enabled script are running inside the SIM environment in KE-chain, the user having the current connection to the API is often not the user that needs to be part of the team to be created. The user provided will become ‘owner’ of the team.

Parameters:

name (basestring or None) – name of the team
user (userid or username or models.User) – user (userid, username or User) that will become owner of the team
description – (optional) description of the team
options (dict or None) – (optional) provide additional team advanced options (as dict)
is_hidden (bool or None) – (optional) if the team needs to be hidden (defaults to false)

Returns:

the created models.Team

Raises:

IllegalArgumentError – When the provided arguments are incorrect
APIError – When an API Error occurs

Create a widget inside an activity.

If you want to associate models (and instances) in a single go, you may provide a list of Property (models) to the readable_model_ids or writable_model_ids.

Alternatively you can use the alias, inputs and outputs which connect to respectively readable_model_ids and writable_models_ids.

Parameters:

activity (Activity or UUID) – activity objects to create the widget in.
widget_type – type of the widget, one of WidgetTypes
meta (dict) – meta dictionary of the widget.
title (str or None) – (optional) title of the widget
order (int or None) – (optional) order in the activity of the widget.
parent (Widget or UUID) – (optional) parent of the widget for Multicolumn and Multirow widget.
readable_models (list of properties or list of property id's) – (optional) list of property model ids to be configured as readable (alias = inputs)
writable_models (list of properties or list of property id's) – (optional) list of property model ids to be configured as writable (alias = ouputs)
part_instance (Part or UUID) – Part object or UUID to be used as instance of the widget
parent_part_instance (Part or UUID) – Part object or UUID to be used as parent of the widget
kwargs – (optional) additional keyword=value arguments to create widget

Type:

string

Returns:

the created subclass of Widget

Return type:

Widget

Raises:

IllegalArgumentError – when an illegal argument is send.
APIError – when an API Error occurs.

create_widgets(widgets: List[Dict], **kwargs) → List[Widget][source]¶

Bulk-create of widgets.

Parameters:: widgets (List[Dict]) – list of dictionaries defining the configuration of the widget.
Returns:: list of Widget objects

:rtype List[Widget]

update_widgets(widgets: List[Dict]) → List[Widget][source]¶

Bulk-update of widgets.

Parameters:: widgets (List[Dict]) – list of widget configurations.
Returns:: list of Widget objects

:rtype List[Widget]

delete_widget(widget: Widget | str) → None[source]¶

Delete a single Widget.

Parameters:

widget (Widget or basestring) – Widget or its UUID to be deleted

Returns:

None

Raises:

APIError – whenever the widget could not be deleted
IllegalArgumentError – whenever the input widget is invalid

delete_widgets(widgets: List[Widget | str]) → None[source]¶

Delete multiple Widgets.

Parameters:

widgets (List[Union[Widget, Text]]) – List, Tuple or Set of Widgets or their UUIDs to be deleted

Returns:

None

Raises:

APIError – whenever the widgets could not be deleted
IllegalArgumentError – whenever the input widgets is invalid

Retrieve a list of associations.

Parameters:

widget (Widget) – widget for which to retrieve associations
activity (Activity) – activity for which to retrieve associations
part (Part) – part for which to retrieve associations
property (AnyProperty) – property for which to retrieve associations
scope (Scope) – scope for which to retrieve associations
limit (int) – maximum number of associations to retrieve

Returns:

list of association objects

:rtype List[Association]

Update associations on this widget.

This is a patch to the list list of associations. Existing associations are not replaced.

Parameters:

widget (Widget or UUID) – widget to update associations for
readable_models (List[Property] or List[UUID] or None) – list of property models (of Property or property_ids (uuids) that has read rights
writable_models (List[Property] or List[UUID] or None) – list of property models (of Property or property_ids (uuids) that has write rights
part_instance (Part or UUID) – Part object or UUID to be used as instance of the widget
parent_part_instance (Part or UUID) – Part object or UUID to be used as parent of the widget

Returns:

None

Raises:

APIError – when the associations could not be changed
IllegalArgumentError – when the list is not of the right type

update_widgets_associations(widgets: List[Widget | str], associations: List[Tuple], **kwargs) → None[source]¶

Update associations on multiple widgets in bulk.

This is patch to the list of associations. Existing associations are not replaced.

Parameters:

widgets – list of widgets to update associations for.
associations (List[Tuple]) – list of tuples, each tuple containing 2 lists of properties (of Property or property_ids (uuids)

Returns:

None

Raises:

APIError – when the associations could not be changed
IllegalArgumentError – when the list is not of the right type

Update associations on this widget.

This is an absolute list of associations. If no property model id’s are provided, then the associations are emptied out and replaced with no associations.

Parameters:

widget (Widget or UUID) – widget to set associations for.
readable_models (List[Property] or List[UUID] or None) – list of property models (of Property or property_ids (uuids) that has read rights
writable_models (List[Property] or List[UUID] or None) – list of property models (of Property or property_ids (uuids) that has write rights
part_instance (Part or UUID) – Part object or UUID to be used as instance of the widget
parent_part_instance (Part or UUID) – Part object or UUID to be used as parent of the widget

Returns:

None

Raises:

APIError – when the associations could not be changed
IllegalArgumentError – when the list is not of the right type

set_widgets_associations(widgets: List[Widget | str], associations: List[Tuple], **kwargs) → None[source]¶

Set associations on multiple widgets in bulk.

This is an absolute list of associations. If no property model id’s are provided, then the associations are emptied out and replaced with no associations.

Parameters:

widgets – list of widgets to set associations for.
associations (List[Tuple]) – list of tuples, each tuple containing 2 lists of properties (of Property or property_ids (uuids)

Returns:

None

Raises:

APIError – when the associations could not be changed
IllegalArgumentError – when the list is not of the right type

clear_widget_associations(widget: Widget) → None[source]¶

Remove all associations of a widget.

Parameters:

widget (Widget) – widget to clear associations from.

Returns:

None

Raises:

APIError – when the associations could not be cleared.
IllegalArgumentError – if the widget is not of type Widget

remove_widget_associations(widget: Widget, models: List[AnyProperty | str] | None = (), **kwargs) → None[source]¶

Remove specific associations from a widget.

Parameters:

widget (Widget) – widget to remove associations from.
models (list) – list of Property models or their UUIDs

Returns:

None

Raises:

APIError – when the associations could not be removed
IllegalArgumentError – if the widget is not of type Widget

move_activity(activity, parent, classification=None)[source]¶

Move the Activity and, if applicable, its sub-tree to another parent.

If you want to move an Activity from one classification to another, you need to provide the target classification. The classificaiton of the parent should match the one provided in the function. This is to ensure that you really want this to happen.

New in version 2.7.

Changed in version 3.1: Add ability to move activity from one classification to another.

Parameters:

activity – The Activity object to be moved.
parent (Activity or UUID) – The parent Subprocess under which this Activity will be moved.
classification (Text) – The target classification if it is desirable to change ActivityClassification

Raises:

IllegalArgumentError – if the ‘parent’ activity_type is not enums.ActivityType.SUBPROCESS
IllegalArgumentError – if the ‘parent’ type is not Activity or UUID
APIError – if an Error occurs.

update_properties(properties: List[Dict]) → List[AnyProperty][source]¶

Update multiple properties simultaneously.

Parameters:: properties (List[Dict]) – list of dictionaries to set the properties
Raises:: IllegalArgumentError
Returns:: list of Properties

:rtype List[AnyProperty]

Examples

>>> properties = client.properties(limit=3)
>>> update_dicts = [dict(id=p.id, value=p.value) for p in properties]
>>> client.update_properties(properties=update_dicts)

notifications(pk: str | None = None, **kwargs) → List[Notification][source]¶

Retrieve one or more notifications stored on the instance.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Parameters:

pk (basestring or None) – if provided, filter the search by notification_id
kwargs – (optional) additional search keyword arguments

Returns:

list of models.Notification objects

Raises:

APIError – When the retrieval call failed due to various reasons

notification(pk: str | None = None, *args, **kwargs) → Notification[source]¶

Retrieve a single KE-chain notification.

Uses the same interface as the notifications() method but returns only a single pykechain models.Notification object.

If additional keyword=value arguments are provided, these are added to the request parameters. Please refer to the documentation of the KE-chain API for additional query parameters.

Parameters:

pk (basestring or None) – if provided, filter the search by notification_id
kwargs – (optional) additional search keyword arguments

Returns:

a single models.Notification

Raises:

NotFoundError – When no Notification is found based on the search arguments
MultipleFoundError – When more than a single Notification is found based on the search arguments

Create a single Notification.

Parameters:

subject (str) – Header text of the notification
message (str) – Content message of the notification
status (NotificationStatus) –
1. life-cycle status of the notification, defaults to “DRAFT”.
recipients (list) –
1. list of recipients, each being a User object, user ID or an email address.
team (Team object or Team UUID) –
1. team object to which the notification is constrained
from_user (User or user ID) –
1. Sender of the notification, either a User object or user ID. Defaults to script user.
event (NotificationEvent) –
1. originating event of the notification.
channel (NotificationChannels) –
1. method used to send the notification, defaults to “EMAIL”.
kwargs – (optional) keyword=value arguments

Returns:

the newly created Notification

Raises:

APIError: when the Notification could not be created

delete_notification(notification: Notification | str) → None[source]¶

Delete a single Notification.

Parameters:

notification (Notification or basestring) – Notification or its UUID to be deleted

Returns:

None

Raises:

APIError – whenever the notification could not be deleted
IllegalArgumentError – whenever the input notification is invalid

banners(pk: str | None = None, text: str | None = None, is_active: bool | None = None, **kwargs) → List[Banner][source]¶

Retrieve Banners.

Parameters:

pk – ID of the banner
text – Text displayed in the banner
is_active – Whether the banner is currently active

Returns:

list of Banner objects

:rtype list

banner(*args, **kwargs) → Banner[source]¶

Retrieve a single Banner, see banners() for available arguments.

Returns:: single banner
Return type:: Banner

create_banner(text: str, icon: str, active_from: datetime, active_until: datetime | None = None, is_active: bool | None = False, url: str | None = None, **kwargs) → Banner[source]¶

Create a new banner.

Parameters:

text (str) – Text to display in the banner. May use HTML.
icon (str) – Font-awesome icon to stylize the banner
active_from (datetime.datetime) – Datetime from when the banner will become active.
active_until (datetime.datetime) – Datetime from when the banner will no longer be active.
is_active (bool) – Boolean whether to set the banner as active, defaults to False.
url – target for the “more info” button within the banner.
url – str
kwargs – additional arguments for the request

Returns:

the new banner

Return type:

Banner

active_banner() → Banner[source]¶

Retrieve the currently active banner.

Returns:: Banner object. If no banner is active, returns None.
Return type:: Banner

:raise APIError whenever the banners could not be retrieved properly. :raises NotFoundError whenever there is no active banner. :raises MultipleFoundError whenever multiple banners are active.

expiring_download(*args, **kwargs) → ExpiringDownload[source]¶

Retrieve a single expiring download.

Returns:

a single models.ExpiringDownload

Raises:

NotFoundError – When no ExpiringDownload is found
MultipleFoundError – When more than a single ExpiringDownload is found

expiring_downloads(pk: str | None = None, expires_in: int | None = None, **kwargs) → List[ExpiringDownload][source]¶

Search for Expiring Downloads with optional pk.

Parameters:

pk (basestring or None) – if provided, filter the search for an expiring download by download_id
expires_in (int) – if provided, filter the search for the expires_in (in seconds)

Returns:

list of Expiring Downloads objects

create_expiring_download(expires_at: datetime | None = None, expires_in: int | None = None, content_path: str | None = None) → ExpiringDownload[source]¶

Create an new Expiring Download.

Parameters:

expires_at (datetime.datetime) – The moment at which the ExpiringDownload will expire
expires_in (int) – The amount of time (in seconds) in which the ExpiringDownload will expire
content_path (str) – the path to the file to be uploaded in the newly created ExpiringDownload object

Returns:

create_context(name: str, context_type: ContextType, scope: Scope, context_group: ContextGroup | None = None, activities=None, description: str | None = None, tags=None, options=None, feature_collection=None, start_date=None, due_date=None, **kwargs) → Context[source]¶

Create a new Context object of a ContextType in a scope.

New in version 3.12.

Parameters:

name – Name of the Context to be displayed to the end-user.
scope – Scope object or Scope Id where the Context is active on.
description – (optional) description of the Context
activities – (optional) associated list of Activity or activity object ID
context_group – (optional) context_group of the context. Choose from ContextGroup enumeration.
tags – (optional) list of tags
options – (optional) dictionary with options.
feature_collection – (optional) dict with a geojson feature collection to store for a STATIC_LOCATION
start_date – (optional) start datetime for a TIME_PERIOD context
due_date – (optional) start datetime for a TIME_PERIOD context

Context_type:

A type of Context, as defined in ContextType eg: STATIC_LOCATION, TIME_PERIOD

Returns:

a created Context Object

Raises:

APIError – When the object cannot be created.

delete_context(context: Context) → None[source]¶

Delete the Context.

New in version 3.12.

Parameters:: context – The context object to delete

context(*args, **kwargs) → Context[source]¶

Retrieve a single Context, see contexts() for available arguments.

New in version 3.12.

Returns:: a single Contexts
Return type:: Context

Retrieve Contexts.

New in version 3.12.

Parameters:

pk – (optional) retrieve a single primary key (object ID)
context_type – (optional) filter on context_type (should be of ContextType)
activities – (optional) filter on a list of Activities or Activity Id’s
scope – (optional) filter on a scope.

Returns:

a list of Contexts

Return type:

List[Context]

create_form_model(*args, **kwargs) → Form[source]¶

Create a single Form Model.

See the Form.create_model() method for available arguments.

Returns:: a created Form Model

instantiate_form(model, *args, **kwargs) → Form[source]¶

Create a new Form instance based on a model.

See the Form.instantiate() method for available arguments.

Returns:: a created Form Instance

form(*args, **kwargs) → Form[source]¶

Retrieve a single Form, see forms() method for available arguments.

New in version 3.20.

Returns:: a single Contexts
Return type:: Context

Retrieve Forms.

New in version 3.20.

Parameters:

pk – (optional) retrieve a single primary key (object ID)
name – (optional) name of the form to filter on
category – (optional) category of the form to search for
description – (optional) description of the form to filter on
scope – (optional) the scope of the form to filter on
context – (optional) the context of the form to filter on
ref – (optional) the ref of the form to filter on

Returns:

a list of Forms

Retrieve a single Workflow, see workflows() method for available arguments.

New in version 3.20.

Parameters:

pk – (optional) retrieve a single primary key (object ID)
name – (optional) name of the workflow to filter on
category – (optional) category of the workflow to search for
description – (optional) description of the workflow to filter on
scope – (optional) the scope of the workflow to filter on
ref – (optional) the ref of the workflow to filter on

Returns:

a single Workflows

Return type:

Workflow

Retrieve Workflows.

New in version 3.20.

Parameters:

pk – (optional) retrieve a single primary key (object ID)
name – (optional) name of the workflow to filter on
category – (optional) category of the workflow to search for
description – (optional) description of the workflow to filter on
scope – (optional) the scope of the workflow to filter on
ref – (optional) the ref of the workflow to filter on

Returns:

a list of Workflows

create_workflow(scope: str | UUID, **kwargs) → Workflow[source]¶

Create a new Defined Workflow object in a scope.

See Workflow.create for available parameters.

Returns:: a Workflow object

import_parts(file, model: Part, parent: Part, activity: Activity | None = None, async_mode: bool | None = True) → None[source]¶

Import parts from an Excel file.

Parameters:

file – the Excel file to be used
model – model of the Part
parent – Parent Part instance
activity – Optional
async_mode – (boolean) if the call should be made asynchronously

Returns:

create_stored_file(**kwargs) → StoredFile[source]¶

Create a new Stored File object in a scope.

See StoredFile.create for available parameters.

Returns:: a StoredFile object

Retrieve a single Stored File.

New in version 4.7.0.

Parameters:

pk – (optional) retrieve a single primary key (object ID)
name – (optional) name of the stored file to filter on
category – (optional) category of the stored file to search for
classification – (optional) classification of the stored file to search for
description – (optional) description of the stored file to filter on
scope – (optional) the scope of the stored file to filter on
ref – (optional) the ref of the stored file to filter on

Returns:

a single StoredFiles

Return type:

StoredFile

Retrieve a single Stored File.

New in version 4.7.0.

Parameters:

pk – (optional) retrieve a single primary key (object ID)
name – (optional) name of the stored file to filter on
category – (optional) category of the stored file to search for
classification – (optional) classification of the stored file to search for
description – (optional) description of the stored file to filter on
scope – (optional) the scope of the stored file to filter on
ref – (optional) the ref of the stored file to filter on

Returns:

a list of StoredFiles

Client¶

Navigation

Related Topics