models.Activity

pykechain.models.Activity

class Activity(json, **kwargs)

A virtual object representing a KE-chain activity.

New in version 2.0.

Variables:

• id – id of the activity

• name – name of the activity

• created_at – created datetime of the activity

• updated_at – updated datetime of the activity

• description – description of the activity

• status – status of the activity. One of pykechain.enums.ActivityStatus

• classification – classification of the activity. One of :class: pykechain.enums.ActivityClassification

• activity_type – Type of the activity. One of pykechain.enums.ActivityType for WIM version 2

Construct an Activity from a json object.

refresh(*args, **kwargs)

Refresh the object in place.

property assignees: List[User]

List of assignees to the activity.

Provides a list of User objects or an empty list.

Returns:

a list of User objects or an empty list.

Return type:

list

property scope_id

Id of the scope this Activity belongs to.

This property will always produce a scope_id, even when the scope object was not included in an earlier response.

When the Scope is not included in this task, it will make an additional call to the KE-chain API.

Returns:

the scope id

Type:

uuid

Raises:

NotFoundError – if the scope could not be found

property representations

Get and set the activity representations.

is_rootlevel() → bool

Activity is at the toplevel of a project, i.e. below the root itself.

It will look for the name of the parent which should be either ActivityRootNames.WORKFLOW_ROOT or ActivityRootNames.CATALOG_ROOT. If the name of the parent cannot be found an additional API call is made to retrieve the parent object ( based on the parent_id in the json_data).

Returns:

Return True if it is a root level activity, otherwise return False

is_task() → bool

Activity is of ActivityType.TASK.

Returns:

Return True if it is a task, otherwise return False

is_subprocess() → bool

Activity is of ActivityType.PROCESS.

Returns:

Return True if it is a subprocess, otherwise return False

is_process() → bool

Activity is of ActivityType.PROCESS.

Returns:

Return True if it is a process, otherwise return False

is_workflow() → bool

Classification of the Activity is of ActivityClassification.WORKFLOW.

Returns:

Return True if it is a workflow classification activity, otherwise return False

is_app() → bool

Classification of the Activity is of ActivityClassification.APP.

Returns:

Return True if it is a App classification activity, otherwise return False

is_catalog() → bool

Classification of the Activity is of ActivityClassification.CATALOG.

Returns:

Return True if it is a catalog classification activity, otherwise return False

is_workflow_root() → bool

Classification of the Activity is of ActivityClassification.WORKFLOW and a ROOT object.

Returns:

Return True if it is a root workflow classification activity, otherwise False

is_catalog_root() → bool

Classification of the Activity is of ActivityClassification.CATALOG and a ROOT object.

Returns:

Return True if it is a root catalog classification activity, otherwise False

is_root() → bool

Activity is a ROOT object.

If you want to determine if it is also a workflow or a catalog root, use Activity.is_workflow_root() or Activity.is_catalog_root() methods.

Returns:

Return True if it is a root object, otherwise return False

is_configured() → bool

Activity is configured with input and output properties.

Makes an additional lightweight call to the API to determine if any associated models are there.

Returns:

Return True if it is configured, otherwise return False

is_customized() → bool

Activity is customized.

In other words if it has a customization. Use can use the Activity.customization() to retrieve the customization object and configure the task.

Returns:

Return True if it is customized, otherwise return False

create(*args, **kwargs) → Activity

Create a new activity belonging to this subprocess.

See pykechain.Client.create_activity() for available parameters.

Raises:

• IllegalArgumentError – if the Activity is not a PROCESS.

• APIError – if an Error occurs.

parent() → Activity

Retrieve the parent in which this activity is defined.

If this is a task on top level, it raises NotFounderror.

Returns:

a Activity

Raises:

• NotFoundError – when it is a task in the top level of a project

• APIError – when other error occurs

Example

>>> task = project.activity('Subtask')
>>> parent_of_task = task.parent()

children(**kwargs) → List[Activity]

Retrieve the direct activities of this subprocess.

It returns a combination of Tasks (a.o. UserTasks) and Subprocesses on the direct descending level. Only when the activity is a Subprocess, otherwise it raises a NotFoundError

Parameters:

kwargs – Additional search arguments, check pykechain.Client.activities() for additional info

Returns:

a list of Activity

Raises:

NotFoundError – when this task is not of type ActivityType.PROCESS

Example

>>> task = project.activity('Subprocess')
>>> children = task.children()

Example searching for children of a subprocess which contains a name (icontains searches case insensitive)

>>> task = project.activity('Subprocess')
>>> children = task.children(name__icontains='more work')

child(name: str | None = None, pk: str | None = None, **kwargs) → Activity

Retrieve a child object.

Parameters:

• name (str) – optional, name of the child

• pk – optional, UUID of the child

Type:

pk: str

Returns:

Child object

Raises:

• MultipleFoundError – whenever multiple children fit match inputs.

• NotFoundError – whenever no child matching the inputs could be found.

siblings(**kwargs) → List[Activity]

Retrieve the other activities that also belong to the parent.

It returns a combination of Tasks (a.o. UserTasks) and Subprocesses on the level of the current task, including itself. This also works if the activity is of type ActivityType.PROCESS.

Parameters:

kwargs – Additional search arguments, check pykechain.Client.activities() for additional info

Returns:

list of Activity

Raises:

NotFoundError – when it is a task in the top level of a project

Example

>>> task = project.activity('Some Task')
>>> siblings = task.siblings()

Example for siblings containing certain words in the task name >>> task = project.activity(‘Some Task’) >>> siblings = task.siblings(name__contains=’Another Task’)

all_children() → List[Activity]

Retrieve a flat list of all descendants, sorted depth-first.

Returns an empty list for Activities of type TASK.

:returns list of child objects :rtype List

count_children(**kwargs) → int

Retrieve the number of child activities using a light-weight request.

Returns:

number of Activities

:rtype int

clone(parent: Activity | str | None = None, update_dict: Dict | None = None, **kwargs) → Activity | None

Create a copy of this activity.

Parameters:

• parent (Activity) –

  15. parent Activity object or UUID

• update_dict (dict) – (O) dictionary of new values to set on the cloned activities, e.g. {“name”: “New name”}

• kwargs – additional arguments, see the Client.clone_activities() method

Returns:

clone of this activity

:rtype Activity

edit_cascade_down(start_date: ~datetime.datetime | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, due_date: ~datetime.datetime | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, assignees: ~typing.List[str] | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, assignees_ids: ~typing.List[str] | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, status: ~pykechain.enums.ActivityStatus | str | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, overwrite: bool | None = False, **kwargs) → None

Edit the activity and all its descendants with a single operation.

Parameters:

• start_date (datetime or None) – (optionally) edit the start date of the activity as a datetime object (UTC time/timezone aware preferred)

• due_date (datetime or None) – (optionally) edit the due_date of the activity as a datetime object (UTC time/timzeone aware preferred)

• assignees (list(basestring) or None) – (optionally) edit the assignees (usernames) of the activity as a list

• assignees_ids (list(basestring) or None) – (optionally) edit the assignees (user id’s) of the activity as a list

• status (ActivityStatus, basestring or None) – (optionally) edit the status of the activity as a string based on ActivityStatus

• overwrite (bool) – (optionally) whether to overwrite existing assignees (True) or merge with existing assignees (False, default)

Returns:

flat list of the current task all descendants that have been edited

:rtype list[Activity]

edit(name: str | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, description: str | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, start_date: ~datetime.datetime | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, due_date: ~datetime.datetime | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, assignees: ~typing.List[str] | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, assignees_ids: ~typing.List[str] | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, status: ~pykechain.enums.ActivityStatus | str | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, tags: ~typing.List[str] | ~pykechain.utils.Empty | None = <pykechain.utils.Empty object>, **kwargs) → None

Edit the details of an activity.

Setting an input to None will clear out the value (exception being name and status).

Parameters:

• name (basestring or None or Empty) – (optionally) edit the name of the activity. Name cannot be cleared.

• description (basestring or None or Empty) – (optionally) edit the description of the activity or clear it

• start_date (datetime or None or Empty) – (optionally) edit the start date of the activity as a datetime object (UTC time/timezone aware preferred) or clear it

• due_date (datetime or None or Empty) – (optionally) edit the due_date of the activity as a datetime object (UTC time/timzeone aware preferred) or clear it

• assignees (list(basestring) or None or Empty) – (optionally) edit the assignees (usernames) of the activity as a list, will overwrite all assignees or clear them

• assignees_ids (list(basestring) or None or Empty) – (optionally) edit the assignees (user id’s) of the activity as a list, will overwrite all assignees or clear them

• status (ActivityStatus or None or Empty) – (optionally) edit the status of the activity as a string based. Status cannot be cleared on ActivityStatus

• tags (list of basestring or None or Empty) – (optionally) replace the tags on an activity, which is a list of strings [“one”,”two”,”three”] or clear them

Raises:

• NotFoundError – if a username in the list of assignees is not in the list of scope members

• IllegalArgumentError – if the type of the inputs is not correct

• APIError – if another Error occurs

Warns:

UserWarning - When a naive datetime is provided. Defaults to UTC.

Example

>>> from datetime import datetime
>>> my_task = project.activity('Specify the wheel diameter')
>>> my_task.edit(name='Specify wheel diameter and circumference',
...     description='The diameter and circumference are specified in inches',
...     start_date=datetime.utcnow(),
...     assignee='testuser')

If we want to provide timezone aware datetime objects we can use the 3rd party convenience library pytz. Mind that we need to fetch the timezone first and use <timezone>.localize(<your datetime>) to make it work correctly.

Using datetime(2017,6,1,23,59,0 tzinfo=<tz>) does NOT work for most timezones with a daylight saving time. Check the pytz documentation.

To make it work using pytz and timezone aware datetime see the following example:

>>> import pytz
>>> start_date_tzaware = datetime.now(pytz.utc)
>>> mytimezone = pytz.timezone('Europe/Amsterdam')
>>> due_date_tzaware = mytimezone.localize(datetime(2019, 10, 27, 23, 59, 0))
>>> my_task.edit(start_date=start_date_tzaware,due_date=due_date_tzaware)

Not mentioning an input parameter in the function will leave it unchanged. Setting a parameter as None will clear its value (where that is possible). The example below will clear the due_date, but leave everything else unchanged.

>>> my_task.edit(due_date=None)

delete() → bool

Delete this activity.

Returns:

True when successful

Raises:

APIError – when unable to delete the activity

parts(*args, **kwargs)

Retrieve parts belonging to this activity.

Without any arguments it retrieves the Instances related to this task only.

This call only returns the configured properties in an activity. So properties that are not configured are not in the returned parts.

See pykechain.Client.parts for additional available parameters.

Example

>>> task = project.activity('Specify Wheel Diameter')
>>> parts = task.parts()

To retrieve the models only. >>> parts = task.parts(category=Category.MODEL)

associated_parts(*args, **kwargs)

Retrieve models and instances belonging to this activity.

This is a convenience method for the Activity.parts() method, which is used to retrieve both the Category.MODEL as well as the Category.INSTANCE in a tuple.

This call only returns the configured properties in an activity. So properties that are not configured are not in the returned parts.

If you want to retrieve only the models associated to this task it is better to use:

task.parts(category=Category.MODEL).

See pykechain.Client.parts() for additional available parameters.

Returns:

a tuple(models of PartSet, instances of PartSet)

Example

>>> task = project.activity('Specify Wheel Diameter')
>>> all_models, all_instances = task.associated_parts()

associated_object_ids() → List[Dict]

Retrieve object ids associated to this activity.

This represents a more in-depth retrieval of objects associated to the activity. Each element in the list represents a Property of Category.INSTANCE. Each element contains the following fields:

‘id’: The ID of the association ‘widget’: The ID of the widget to which the Property instance is associated ‘activity’: The ID of the activity ‘model_property’: The ID of the Property model ‘model_part’: The ID of the model of the Part containing said Property ‘instance_property’: The ID of the Property instance ‘instance_part’: The ID of the Part instance containing said Property ‘writable’: True if the Property is writable, False if is not

See pykechain.Client.parts() for additional available parameters.

Returns:

a list of dictonaries with association objects associated to the activity

Raises:

NotFoundError – When the response from the server was invalid.

Example

>>> task = project.activity('Specify Wheel Diameter')
>>> associated_object_ids = task.associated_object_ids()

widgets(**kwargs) → WidgetsManager

Widgets of the activity.

Works with KE-chain version 3.

Parameters:

kwargs – additional keyword arguments

Returns:

A WidgetManager list, containing the widgets

Return type:

WidgetManager

Raises:

• NotFoundError – when the widgets could not be found

• APIError – when the API does not support the widgets, or when API gives an error.

download_as_pdf(target_dir: str | None = None, pdf_filename: str | None = None, paper_size: PaperSize = 'a4paper', paper_orientation: PaperOrientation = 'portrait', include_appendices: bool = False, include_qr_code: bool = False, user: User | None = None, timeout: int = 180) → str

Retrieve the PDF of the Activity.

New in version 2.1.

Parameters:

• target_dir – (optional) directory path name where the store the log.txt to.

• pdf_filename – (optional) log filename to write the log to, defaults to log.txt.

• paper_size – The size of the paper to which the PDF is downloaded: - a4paper (default): A4 paper size - a3paper: A3 paper size - a2paper: A2 paper size - a1paper: A1 paper size - a0paper: A0 paper size

• paper_orientation – The orientation of the paper to which the PDF is downloaded: - portrait (default): portrait orientation - landscape: landscape orientation

• include_appendices – True if the PDF should contain appendices, False (default) if otherwise.

• include_qr_code – True if the PDF should include a QR-code, False (default) if otherwise.

• user – (optional) used to calculate the offset needed to interpret Datetime Properties. Not having a user will simply use the default UTC.

• timeout – (optional) number of seconds to wait for the PDF to be created, defaults to ASYNC_TIMEOUT_LIMIT

Raises:

• APIError – if the pdf file could not be found.

• OSError – if the file could not be written.

:returns Path to the saved pdf file :rtype str

move(parent, classification=None)

Move the Activity to a new parent.

See pykechain.Client.move_activity() for available parameters.

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

Parameters:

• parent (Union[Activity, Text]) – parent object to move activity to

• classification (ActivityClassification or None) – (optional) classification of the target parent if you want to change the classification.

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.

share_link(subject: str, message: str, recipient_users: List[User | str], from_user: User | None = None) → None

Share the link of the Activity through email.

Parameters:

• subject (basestring) – subject of email

• message (basestring) – message of email

• recipient_users (list(Union(User, Id))) – users that will receive the email

• from_user (User object) – User that shared the link (optional)

Raises:

APIError – if an internal server error occurred.

share_pdf(subject: str, message: str, recipient_users: List[User | str], paper_size: PaperSize | None = 'a3paper', paper_orientation: PaperOrientation | None = 'portrait', from_user: User | None = None, include_appendices: bool | None = False, include_qr_code: bool | None = False, **kwargs) → None

Share the PDF of the Activity through email.

Parameters:

• subject (basestring) – subject of email

• message (basestring) – message of email

• recipient_users (list(Union(User, Id))) – users that will receive the email

• paper_size (basestring (see enums.PaperOrientation)) – The size of the paper to which the PDF is downloaded: - a4paper: A4 paper size - a3paper: A3 paper size (default) - a2paper: A2 paper size - a1paper: A1 paper size - a0paper: A0 paper size

• paper_orientation – The orientation of the paper to which the PDF is downloaded: - portrait (default): portrait orientation - landscape: landscape orientation

• from_user (User object) – User that shared the PDF (optional)

• include_appendices (bool) – True if the PDF should contain appendices, False (default) if otherwise.

• include_qr_code (bool) – True if the PDF should include a QR-code, False (default) if otherwise.

Raises:

APIError – if an internal server error occurred.

context(*args, **kwargs) → Context

Retrieve a context object associated to this activity and scope.

See pykechain.Client.context for available parameters.

New in version 3.12.

Returns:

a Context object

contexts(*args, **kwargs) → List[Context]

Retrieve context objects t associated to this activity and scope.

See pykechain.Client.contexts for available parameters.

New in version 3.12.

Returns:

a list of Context objects

create_context(*args, **kwargs) → Context

Create a new Context object of a ContextType in a scope and associated it to this activity.

See pykechain.Client.create_context for available parameters.

New in version 3.12.

Returns:

a Context object

link_context(context: Context) → None

Link the current activity to an existing Context.

If you want to link multiple activities at once, use the Context.link_activities() method.

Parameters:

context – A Context object to link the current activity to.

Raises:

IllegalArgumentError – When the context is not a Context object.

unlink_context(context: Context) → None

Link the current activity to an existing Context.

If you want to unlink multiple activities at once, use the Context.unlink_activities() method.

Parameters:

context – A Context object to unlink the current activity from.

Raises:

IllegalArgumentError – When the context is not a Context object.

clone_widgets(from_activity: Activity) → None

Clone widgets from another Activity to the current one.

The two activities must be related to the same Form.

Parameters:

from_activity – An Activity object that contains the widgets that are wanted in the current one

Raises:

APIError – When the call is unsuccessful, for example when cloning cross-forms