Client

class Client(url: str = 'http://localhost:8000/', check_certificates: Optional[bool] = 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: Optional[str] = None, check_certificates: Optional[bool] = 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: Optional[str] = None, password: Optional[str] = None, token: Optional[str] = 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: Optional[str] = None, label: Optional[str] = None, version: Optional[str] = None, default: Optional[bool] = 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: Optional[str] = None, extra_params: Optional[Dict] = 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: Optional[str] = None, pk: Optional[str] = None, status: Optional[Union[ScopeStatus, str]] = '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
activities(name: Optional[str] = None, pk: Optional[str] = None, scope: Optional[str] = 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
parts(name: Optional[str] = None, pk: Optional[str] = None, model: Optional[Part] = None, category: Optional[Union[Category, str]] = 'INSTANCE', scope_id: Optional[str] = None, parent: Optional[str] = None, activity: Optional[str] = None, widget: Optional[str] = None, limit: Optional[int] = None, batch: Optional[int] = 100, **kwargs) PartSet[source]

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
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
properties(name: Optional[str] = None, pk: Optional[str] = None, category: Optional[Union[Category, str]] = '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
services(name: Optional[str] = None, pk: Optional[str] = None, scope: Optional[str] = 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
service_executions(name: Optional[str] = None, pk: Optional[str] = None, scope: Optional[str] = None, service: Optional[str] = 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
users(username: Optional[str] = None, pk: Optional[str] = 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
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_user(username: str, email: str, name: Optional[str] = None, team_ids: Optional[Union[Team, str, UUID]] = None, timezone: Optional[str] = None, language_code: Optional[LanguageCodes] = None, send_passwd_link: bool = False, **kwargs) User[source]

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: Optional[str] = None, pk: Optional[str] = None, is_hidden: Optional[bool] = 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
widgets(pk: Optional[str] = None, activity: Optional[Union[Activity, str]] = 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: Union[Activity, str], name: str, activity_type: ActivityType = 'TASK', ref: Optional[str] = None, status: ActivityStatus = 'OPEN', description: Optional[str] = None, start_date: Optional[datetime] = None, due_date: Optional[datetime] = None, classification: Optional[ActivityClassification] = None, tags: Optional[List[str]] = 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
clone_activities(activities: List[Union[Activity, str]], activity_parent: Union[Activity, str], activity_update_dicts: Optional[Dict] = None, include_part_models: Optional[bool] = False, include_part_instances: Optional[bool] = False, include_children: Optional[bool] = True, excluded_parts: Optional[List[str]] = None, part_parent_model: Optional[Union[Part, str]] = None, part_parent_instance: Optional[Union[Part, str]] = None, part_model_rename_template: Optional[str] = None, part_instance_rename_template: Optional[str] = None, asynchronous: Optional[bool] = False, **kwargs) List[Activity][source]

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: Optional[str] = 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
create_model(parent: Union[Part, str], name: str, multiplicity: Optional[Multiplicity] = '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
create_model_with_properties(parent: Union[Part, str], name: str, multiplicity: Optional[Multiplicity] = 'ZERO_MANY', properties_fvalues: Optional[List[Dict]] = 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

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: Optional[Multiplicity] = '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
create_property(model: Part, name: str, description: Optional[str] = None, property_type: Optional[Union[PropertyType, str]] = 'CHAR_VALUE', default_value: Optional[Any] = None, unit: Optional[str] = None, options: Optional[Dict] = None, **kwargs) Union[Property, MultiReferenceProperty, AttachmentProperty, SelectListProperty, DatetimeProperty, Property2, MultiReferenceProperty2, AttachmentProperty2, SelectListProperty2, DatetimeProperty2, ActivityReferencesProperty, ScopeReferencesProperty, UserReferencesProperty, FormReferencesProperty, ContextReferencesProperty, StatusReferencesProperty][source]

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
create_service(name: str, scope: Scope, description: Optional[str] = None, version: Optional[str] = None, service_type: Optional[ServiceType] = 'PYTHON SCRIPT', environment_version: Optional[ServiceEnvironmentVersion] = '3.8', run_as: Optional[ServiceScriptUser] = 'kenode', pkg_path: Optional[str] = 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_scope(name: str, status: Optional[ScopeStatus] = 'ACTIVE', description: Optional[str] = None, tags: Optional[List[str]] = None, start_date: Optional[datetime] = None, due_date: Optional[datetime] = None, team: Optional[Union[Team, str]] = None, **kwargs) Scope[source]

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: Optional[bool] = 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_scope(source_scope: Scope, name: Optional[str] = None, status: Optional[ScopeStatus] = None, start_date: Optional[datetime] = None, due_date: Optional[datetime] = None, description: Optional[str] = None, tags: Optional[List[str]] = None, team: Optional[Union[Team, str]] = None, scope_options: Optional[Dict] = None, asynchronous: Optional[bool] = False) Optional[Scope][source]

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_team(name: str, user: Union[str, int, User], description: Optional[str] = None, options: Optional[Dict] = None, is_hidden: Optional[bool] = False) Team[source]

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
create_widget(activity: Union[Activity, str], widget_type: Union[WidgetTypes, str], meta: Dict, title: Optional[str] = None, order: Optional[int] = None, parent: Optional[Union[Widget, str]] = None, readable_models: Optional[List] = None, writable_models: Optional[List] = None, part_instance: Optional[Union[Part, str]] = None, parent_part_instance: Optional[Union[Part, str]] = None, **kwargs) Widget[source]

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
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: Union[Widget, str]) None[source]

Delete a single Widget.

Parameters

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

Returns

None

Raises
delete_widgets(widgets: List[Union[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
associations(widget: Optional[Widget] = None, activity: Optional[Activity] = None, part: Optional[Part] = None, property: Optional[Union[Property, MultiReferenceProperty, AttachmentProperty, SelectListProperty, DatetimeProperty, Property2, MultiReferenceProperty2, AttachmentProperty2, SelectListProperty2, DatetimeProperty2, ActivityReferencesProperty, ScopeReferencesProperty, UserReferencesProperty, FormReferencesProperty, ContextReferencesProperty, StatusReferencesProperty]] = None, scope: Optional[Scope] = None, limit: Optional[int] = None) List[Association][source]

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_widget_associations(widget: Union[Widget, str], readable_models: Optional[List] = None, writable_models: Optional[List] = None, part_instance: Optional[Union[Part, str]] = None, parent_part_instance: Optional[Union[Part, str]] = None, **kwargs) None[source]

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
update_widgets_associations(widgets: List[Union[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
set_widget_associations(widget: Union[Widget, str], readable_models: Optional[List] = None, writable_models: Optional[List] = None, part_instance: Optional[Union[Part, str]] = None, parent_part_instance: Optional[Union[Part, str]] = None, **kwargs) None[source]

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
set_widgets_associations(widgets: List[Union[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
clear_widget_associations(widget: Widget) None[source]

Remove all associations of a widget.

Parameters

widget (Widget) – widget to clear associations from.

Returns

None

Raises
remove_widget_associations(widget: Widget, models: Optional[List[Union[AnyProperty, str]]] = (), **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
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
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: Optional[str] = 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: Optional[str] = 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_notification(subject: str, message: str, status: Optional[NotificationStatus] = 'DRAFT', recipients: Optional[List[Union[User, str]]] = None, team: Optional[Union[Team, str]] = None, from_user: Optional[Union[User, str]] = None, event: Optional[NotificationEvent] = None, channel: Optional[NotificationChannels] = 'EMAIL', **kwargs) Notification[source]

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: Union[Notification, str]) None[source]

Delete a single Notification.

Parameters

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

Returns

None

Raises
banners(pk: Optional[str] = None, text: Optional[str] = None, is_active: Optional[bool] = 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: Optional[datetime] = None, is_active: Optional[bool] = False, url: Optional[str] = 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
expiring_downloads(pk: Optional[str] = None, expires_in: Optional[int] = 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: Optional[datetime] = None, expires_in: Optional[int] = None, content_path: Optional[str] = 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: Optional[ContextGroup] = None, activities=None, description: Optional[str] = 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

contexts(pk: Optional[Union[str, UUID]] = None, context_type: Optional[ContextType] = None, activities: Optional[List[Union[Activity, str, UUID]]] = None, scope: Optional[Union[Scope, str, UUID]] = None, context_group: Optional[ContextGroup] = None, **kwargs) List[Context][source]

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

forms(name: Optional[str] = None, pk: Optional[Union[str, UUID]] = None, category: Optional[FormCategory] = None, description: Optional[str] = None, scope: Optional[Union[Scope, str, UUID]] = None, context: Optional[List[Union[Context, str, UUID]]] = None, ref: Optional[str] = None, **kwargs) List[Form][source]

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

workflow(name: Optional[str] = None, pk: Optional[Union[str, UUID]] = None, category: Optional[WorkflowCategory] = None, description: Optional[str] = None, scope: Optional[Union[Scope, str, UUID]] = None, ref: Optional[str] = None, **kwargs) Workflow[source]

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 Contexts

Return type

Context

workflows(name: Optional[str] = None, pk: Optional[Union[str, UUID]] = None, category: Optional[WorkflowCategory] = None, description: Optional[str] = None, scope: Optional[Union[Scope, str, UUID]] = None, ref: Optional[str] = None, **kwargs) List[Workflow][source]

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: Union[str, UUID], **kwargs) Workflow[source]

Create a new Defined Workflow object in a scope.

See Workflow.create_workflow for available parameters.

Returns

a Workflow object