Skip to main content
Version: 13

viktor.api_v1

FileResource​

class viktor.api_v1.FileResource(source_id, api=None)

File resource stored in the file manager.

Warning

Do not instantiate this class directly, it will be returned in the parameter set when using a FileField or MultiFileField.

property file: File

Returns the File object (URL-file) attached to the resource.

Return type

File

property filename: str

Returns the filename of the resource (API call required!).

Return type

str

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, it is created by the API.

property name: str
Return type

str

property entity_type: 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, **kwargs)

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, 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

Bases: _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 params (read-all) of the object using this API will NOT work for this specific user.

Example:

current_entity = API().get_entity(entity_id)
parent = current_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, **kwargs)

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