Skip to main content
Version: 12.10.0

viktor.api_v1

User

class viktor.api_v1.User(*, first_name, last_name, email, job_title)

User information.

Parameters
  • first_name (str) – user’s first name

  • last_name (str) – user’s last name

  • email (str) – user’s email address

  • job_title (str) – user’s job title

property full_name: str

User’s full name (first name + last name).

Return type

str

EntityType

class viktor.api_v1.EntityType(name, id_)
Parameters
  • name (str) – Entity type name (not label).

  • id – Unique ID of the entity type.

EntityRevision

class viktor.api_v1.EntityRevision(params, created_date)
Parameters
  • params (Munch) – Stored params in the entity’s revision.

  • created_date (datetime) – Date(time) of creation of the entity’s revision.

Entity

class viktor.api_v1.Entity(api, origin_id, operations, resolved=None)

Warning

Do not instantiate this class directly in an application. It is created by the API.

property name: str
Return type

str

property entity_type: viktor.api_v1.EntityType
Return type

EntityType

property id: int
Return type

int

property last_saved_params: munch.Munch

Get the params of the last saved entity revision.

Return type

Munch

property last_saved_summary: munch.Munch

Get the summary of the last saved entity revision.

Return type

Munch

parent(*, privileged=False)

Get the parent of the entity.

Parameters

privileged (bool) –

bypass the user access restrictions managed by the admin of an application.

Warning

If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

  • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

  • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

Entity

children(*, include_params=True, entity_type_names=None, privileged=False)

Get the child entities.

Parameters
  • include_params (bool) – True to include the parameters of the child entities.

  • entity_type_names (Optional[List[str]]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

EntityList

siblings(*, include_params=True, entity_type_names=None, privileged=False)

Get the sibling entities.

Parameters
  • include_params (bool) – True to include the parameters of the sibling entities.

  • entity_type_names (Optional[List[str]]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

EntityList

get_file()

Get the file of the entity.

Return type

File

Returns

File object (SourceType.URL)

Raises

ValueError – if file does not have a file associated with it.

create_child(entity_type_name, name, *, params=None, privileged=False)

Create a child entity with given name and type.

Warning

It is currently not possible to create a file-type entity

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. API.get_entity_children) within the same job because of internal caching.

Parameters
  • entity_type_name (str) – type of the entity to be created (type must be a child-type of the parent entity).

  • name (str) – name of the entity to be created.

  • params (Union[dict, Munch, None]) – params to be stored on the newly created entity.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

Entity

revisions()

Get all revisions of the entity.

Return type

List[EntityRevision]

delete(*, privileged=False)

Delete the entity.

Parameters

privileged (bool) –

bypass the user access restrictions managed by the admin of an application.

Warning

If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

  • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

  • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

None

set_params(params, *, privileged=False)

Create a new revision of the entity, storing given params.

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. Entity.last_saved_params) within the same job because of memoization.

Parameters
  • params (Union[dict, Munch]) – params to be stored on the newly created entity revision.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

Entity

rename(name, *, privileged=False)

Rename the entity (creates a revision).

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. Entity.name) within the same job because of memoization.

Parameters
  • name (str) – name of the newly created entity revision.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

Entity

EntityList

class viktor.api_v1.EntityList(api, relation, origin, entity_type_names, include_params, *, privileged=False)

Warning

Do not instantiate this class directly in an application. It is created by the API.

Object which resembles a list of Entity’s.

Most commonly used list operations are supported:

# indexing
children = entity.children()
children[0]  # first child entity
children[-1]  # last child entity

# length
number_of_children = len(children)

# for loop
for child in children:
    # perform operation on child

API

class viktor.api_v1.API

Starting point of making an API call to, for example, retrieve properties of a parent or child entity.

Note that the permissions of a user (group) are reflected on the permissions of this API call, e.g. if a user only has read-navigate or read-basic permission, calling the properties (read-all) of the object using this API will NOT work for this specific user.

Example:

current_entity = API().get_entity(entity_id)
parent = entity.parent()
parent_params = parent.last_saved_params
get_entity(id_, *, privileged=False)

Get the entity with given id.

Parameters
  • id – entity_id

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

Entity

get_entities_by_type(entity_type_name, *, include_params=True, privileged=False)

Get all entities of the given type.

Parameters
  • entity_type_name (str) – entity type to get all entities for.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

EntityList

get_root_entities(*, include_params=True, entity_type_names=None, privileged=False)

Get the root entities.

Parameters
  • include_params (bool) – True to include the parameters of the root entities.

  • entity_type_names (Optional[List[str]]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

EntityList

get_entity_parent(entity_id, *, privileged=False)

Get the parent entity of the entity with given id.

Parameters

privileged (bool) –

bypass the user access restrictions managed by the admin of an application.

Warning

If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

  • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

  • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

Entity

get_entity_children(entity_id, *, include_params=True, entity_type_names=None, privileged=False)

Get the child entities of the entity with given id.

Parameters
  • include_params (bool) – True to include the parameters of the child entities.

  • entity_type_names (Optional[List[str]]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

EntityList

get_entity_siblings(entity_id, *, include_params=True, entity_type_names=None, privileged=False)

Get the sibling entities of the entity with given id.

Parameters
  • include_params (bool) – True to include the parameters of the sibling entities.

  • entity_type_names (Optional[List[str]]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

EntityList

get_entity_revisions(entity_id, *, privileged=False)

Get all revisions of the entity with given id.

Parameters
  • entity_id (int) – id of the entity to get the revisions from.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

List[EntityRevision]

get_entity_file(entity_id, *, privileged=False)

Get the file of the entity with given id.

Parameters
  • entity_id (int) – id of the entity to get the file from.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

File

Returns

File object (SourceType.URL)

Raises

ValueError – if file does not have a file associated with it.

get_current_user()
Return type

User

create_child_entity(parent_entity_id, entity_type_name, name, *, params=None, privileged=False)

Create a child entity with given name and type from parent entity with given id.

Warning

It is currently not possible to create a file-type entity

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. API.get_entity_children) within the same job because of memoization.

Parameters
  • parent_entity_id (int) – id of the parent entity to create the child from.

  • entity_type_name (str) – type of the entity to be created (type must be a child-type of the parent entity).

  • name (str) – name of the entity to be created.

  • params (Union[dict, Munch, None]) – params to be stored on the newly created entity.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

Entity

delete_entity(entity_id, *, privileged=False)

Delete the entity with given id.

Parameters
  • entity_id (int) – id of the entity to be deleted.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

None

rename_entity(entity_id, name, *, privileged=False)

Rename the entity with given id (creates a revision).

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. Entity.name) within the same job because of memoization.

Parameters
  • entity_id (int) – id of the entity to rename.

  • name (str) – name of the newly created entity revision.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

Entity

set_entity_params(entity_id, params, *, privileged=False)

Create a new revision of the entity with given id, storing given params.

Warning

Be aware that changes made using this method might not be reflected in subsequent API calls (e.g. Entity.last_saved_params) within the same job because of memoization.

Parameters
  • entity_id (int) – id of the entity to create a revision for.

  • params (Union[dict, Munch]) – params to be stored on the newly created entity revision.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

Entity

PrivilegedAPI

class viktor.api_v1.PrivilegedAPI

For making API calls that bypass the user access restrictions managed by the admin of an application.

Warning

If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this class:

  • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

  • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

Note

API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

get_entity(id_, *, privileged=False)

Get the entity with given id.

Parameters
  • id – entity_id

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

Entity

get_root_entities(*, include_params=True, entity_type_names=None, privileged=False)

Get the root entities.

Parameters
  • include_params (bool) – True to include the parameters of the root entities.

  • entity_type_names (Optional[List[str]]) – Only filters the entities of the defined type(s) (default = None, returns all).

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

EntityList

get_entity_file(entity_id, *, privileged=False)

Get the file of the entity with given id.

Parameters
  • entity_id (int) – id of the entity to get the file from.

  • privileged (bool) –

    bypass the user access restrictions managed by the admin of an application.

    Warning

    If not used properly, (confidential) information which SHOULD NOT be accessible by a user may leak (for instance by including data in a view). Please consider the following when using this flag:

    • Make sure the app’s admin is aware that the code circumvents certain permissions at specific places.

    • Make sure to test the implementation thoroughly, to ensure no confidential data is leaked.

    API calls can only bypass the restrictions if the key uses_privileged_api is set to true in the manifest. This is to provide an additional layer of security / awareness.

Return type

File

Returns

File object (SourceType.URL)

Raises

ValueError – if file does not have a file associated with it.

get_current_user()
Return type

User