models.Activity¶
pykechain.models.Activity¶
- class Activity(json, **kwargs)[source]¶
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.
- 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 [source]¶
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 [source]¶
Activity is of ActivityType.TASK.
- Returns
Return True if it is a task, otherwise return False
- is_subprocess() bool [source]¶
Activity is of ActivityType.PROCESS.
- Returns
Return True if it is a subprocess, otherwise return False
- is_process() bool [source]¶
Activity is of ActivityType.PROCESS.
- Returns
Return True if it is a process, otherwise return False
- is_workflow() bool [source]¶
Classification of the Activity is of ActivityClassification.WORKFLOW.
- Returns
Return True if it is a workflow classification activity, otherwise return False
- is_app() bool [source]¶
Classification of the Activity is of ActivityClassification.APP.
- Returns
Return True if it is a App classification activity, otherwise return False
- is_catalog() bool [source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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()
orActivity.is_catalog_root()
methods.- Returns
Return True if it is a root object, otherwise return False
- is_configured() bool [source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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] [source]¶
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: Optional[str] = None, pk: Optional[str] = None, **kwargs) Activity [source]¶
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] [source]¶
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] [source]¶
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 [source]¶
Retrieve the number of child activities using a light-weight request.
- Returns
number of Activities
:rtype int
- clone(parent: Optional[Union[Activity, str]] = None, update_dict: Optional[Dict] = None, **kwargs) Optional[Activity] [source]¶
Create a copy of this activity.
- Parameters
parent (Activity) –
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: ~typing.Optional[~typing.Union[~datetime.datetime, ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, due_date: ~typing.Optional[~typing.Union[~datetime.datetime, ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, assignees: ~typing.Optional[~typing.Union[~typing.List[str], ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, assignees_ids: ~typing.Optional[~typing.Union[~typing.List[str], ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, status: ~typing.Optional[~typing.Union[~pykechain.enums.ActivityStatus, str, ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, overwrite: ~typing.Optional[bool] = False, **kwargs) None [source]¶
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: ~typing.Optional[~typing.Union[str, ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, description: ~typing.Optional[~typing.Union[str, ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, start_date: ~typing.Optional[~typing.Union[~datetime.datetime, ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, due_date: ~typing.Optional[~typing.Union[~datetime.datetime, ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, assignees: ~typing.Optional[~typing.Union[~typing.List[str], ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, assignees_ids: ~typing.Optional[~typing.Union[~typing.List[str], ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, status: ~typing.Optional[~typing.Union[~pykechain.enums.ActivityStatus, str, ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, tags: ~typing.Optional[~typing.Union[~typing.List[str], ~pykechain.utils.Empty]] = <pykechain.utils.Empty object>, **kwargs) None [source]¶
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 awaredatetime
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 [source]¶
Delete this activity.
- Returns
True when successful
- Raises
APIError – when unable to delete the activity
- parts(*args, **kwargs)[source]¶
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)[source]¶
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.Example
>>> task = project.activity('Specify Wheel Diameter') >>> all_models, all_instances = task.associated_parts()
- associated_object_ids() List[Dict] [source]¶
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 [source]¶
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: Optional[str] = None, pdf_filename: Optional[str] = None, paper_size: PaperSize = 'a4paper', paper_orientation: PaperOrientation = 'portrait', include_appendices: bool = False, include_qr_code: bool = False, user: Optional[User] = None, timeout: int = 180) str [source]¶
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)[source]¶
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 UUIDAPIError – if an Error occurs.
Share the link of the Activity through email.
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 sizepaper_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 [source]¶
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] [source]¶
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 [source]¶
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 [source]¶
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 [source]¶
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.