Developer Interface

Entity API

This part of the documentation covers all the interfaces of pyPreservica EntityAPI object.

class pyPreservica.EntityAPI(username: str = None, password: str = None, tenant: str = None, server: str = None, use_shared_secret: bool = False)

A class for the Preservica Repository web services Entity API

https://us.preservica.com/api/entity/documentation.html

The EntityAPI allows users to interact with the Preservica repository

asset(reference)

Returns an asset object back by its internal reference identifier

Parameters:reference (str) – The unique identifier for the asset usually its uuid Returns:The Asset object Return type:Asset Raises:RuntimeError – if the identifier is incorrect

folder(reference)

Returns a folder object back by its internal reference identifier

Parameters:reference (str) – The unique identifier for the asset usually its uuid Returns:The Folder object Return type:Folder Raises:RuntimeError – if the identifier is incorrect

content_object(reference)

Returns a content object back by its internal reference identifier

Parameters:reference (str) – The unique identifier for the asset usually its uuid Returns:The content object Return type:ContentObject Raises:RuntimeError – if the identifier is incorrect

entity(entity_type, reference)

Returns an generic entity based on its reference identifier

Parameters:

• entity_type (EntityType) – The type of entity
• reference (str) – The unique identifier for the entity

Returns:

The entity either Asset, Folder or ContentObject

Return type:

Entity

Raises:

RuntimeError – if the identifier is incorrect

save(entity)

Updates the title and description of an entity The security tag and parent are not saved via this method call

Parameters:entity (Entity) – The entity (asset, folder, content_object) to be updated Returns:The updated entity Return type:Entity

security_tag_async(entity, new_tag)

Change the security tag of an asset or folder This is a non blocking call which returns immediately.

Parameters:

• entity (Entity) – The entity (asset, folder) to be updated
• new_tag (str) – The new security tag to be set on the entity

Returns:

A progress id which can be used to monitor the workflow

Return type:

str

security_tag_sync(entity, new_tag)

Change the security tag of an asset or folder This is a blocking call which returns after all entities have been updated.

Parameters:

• entity (Entity) – The entity (asset, folder) to be updated
• new_tag (str) – The new security tag to be set on the entity

Returns:

The updated entity

Return type:

Entity

create_folder(title, description, security_tag, parent=None)

Create a new folder in the repository below the specified parent folder. If parent is missing or None then a root level folder is created.

Parameters:

• title (str) – The title of the new folder
• description (str) – The description of the new folder
• security_tag (str) – The security tag of the new folder
• parent (str) – The identifier for the parent folder

Returns:

The new folder object

Return type:

Folder

representations(asset)

Return a set of representations for the asset

Representations are used to define how the information object are composed in terms of technology and structure.

Parameters:asset (Asset) – The asset containing the required representations Returns:Set of Representation objects Return type:set(Representation)

content_objects(representation)

Return a list of content objects for a representation

Parameters:representation (Representation) – The representation Returns:List of content objects Return type:list(ContentObject)

generations(content_object)

Return a list of Generation objects for a content object

Parameters:content_object (ContentObject) – The content object Returns:list of generations Return type:list(Generation)

bitstream_content(bitstream, filename)

Downloads the bitstream object to a local file

Parameters:

• bitstream (Bitstream) – The content object
• filename (str) – The name of the file the bytes are written to

Returns:

the number of bytes written

Return type:

int

identifiers_for_entity(entity)

Return a set of identifiers which belong to the entity

Parameters:entity (Entity) – The entity Returns:Set of identifiers as tuples Return type:set(Tuple)

identifier(identifier_type, identifier_value)

Return a set of entities with external identifiers which match the type and value

Parameters:

• identifier_type (str) – The identifier type
• identifier_value (str) – The identifier value

Returns:

Set of entity objects which have a reference and title attribute

Return type:

set(Entity)

add_identifier(entity, identifier_type, identifier_value)

Add a new external identifier to an Entity object

Parameters:

• entity (Entity) – The entity the identifier is added to
• identifier_type (str) – The identifier type
• identifier_value (str) – The identifier value

Returns:

An internal id for this external identifier

Return type:

str

delete_identifiers(entity, identifier_type=None, identifier_value=None)

Delete identifiers on an Entity object

Parameters:

• entity (Entity) – The entity the identifiers are deleted from
• identifier_type (str) – The identifier type
• identifier_value (str) – The identifier value

Returns:

entity

Return type:

Entity

metadata(uri)

Fetch the metadata document by its identifier, this is the key from the entity metadata map

Parameters:uri (str) – The metadata identifier Returns:An XML document as a string Return type:str

metadata_for_entity(entity, schema)

Fetch the first metadata document which matches the schema URI from an entity

Parameters:

• entity (Entity) – The entity containing the metadata
• schema (str) – The metadata schema URI

Returns:

The first XML document on the entity matching the schema URI

Return type:

str

add_metadata(entity, schema, data)

Add a new descriptive XML document to an entity

Parameters:

• entity (Entity) – The entity to add the metadata to
• schema (str) – The metadata schema URI
• data (data) – The XML document as a string or as a file bytes

Returns:

The updated Entity

Return type:

Entity

update_metadata(entity, schema, data)

Update an existing descriptive XML document on an entity

Parameters:

• entity (Entity) – The entity to add the metadata to
• schema (str) – The metadata schema URI
• data (data) – The XML document as a string or as a file bytes

Returns:

The updated Entity

Return type:

Entity

delete_metadata(entity, entity, schema)

Delete an existing descriptive XML document on an entity by its schema This call will delete all fragments with the same schema

Parameters:

• entity (Entity) – The entity to add the metadata to
• schema (str) – The metadata schema URI

Returns:

The updated Entity

Return type:

Entity

move_sync(entity, dest_folder)

Move an entity (asset or folder) to a new folder This call blocks until the move is complete

Parameters:

• entity (Entity) – The entity to move either asset or folder
• dest_folder (Entity) – The new destination folder. This can be None to move a folder to the root of the repository

Returns:

The updated entity

Return type:

Entity

move_async(entity, dest_folder)

Move an entity (asset or folder) to a new folder This call returns immediately and does not block

Parameters:

• entity (Entity) – The entity to move either asset or folder
• dest_folder (Entity) – The new destination folder. This can be None to move a folder to the root of the repository

Returns:

Progress ID token

Return type:

str

move(entity, dest_folder)

Move an entity (asset or folder) to a new folder This call is an alias for the move_sync (blocking) method.

Parameters:

• entity (Entity) – The entity to move either asset or folder
• dest_folder (Entity) – The new destination folder. This can be None to move a folder to the root of the repository

Returns:

The updated entity

Return type:

Entity

children(folder, maximum=50, next_page=None)

Return the child entities of a folder one page at a time. The caller is responsible for requesting the next page of results.

Parameters:

• folder (str) – The parent folder reference, None for the children of root folders
• maximum (int) – The maximum size of the result set in each page
• next_page (str) – A URL for the next page of results

Returns:

A set of entity objects

Return type:

set(Entity)

descendants(folder)

Return the immediate child entities of a folder using a lazy iterator. The paging is done internally using a default page size of 50 elements. Callers can iterate over the result to get all children with a single call.

Parameters:folder (str) – The parent folder reference, None for the children of root folders Returns:A set of entity objects (Folders and Assets) Return type:set(Entity)

all_descendants(folder)

Return all child entities recursively of a folder or repository down to the assets using a lazy iterator. The paging is done internally using a default page size of 25 elements. Callers can iterate over the result to get all children with a single call.

Parameters:folder (str) – The parent folder reference, None for the children of root folders Returns:A set of entity objects (Folders and Assets) Return type:set(Entity)

delete_asset(asset, operator_comment, supervisor_comment)

Initiate and approve the deletion of an asset.

Parameters:

• asset (Asset) – The asset to delete
• operator_comment (str) – The comments from the operator which are added to the logs
• supervisor_comment (str) – The comments from the supervisor which are added to the logs

Returns:

The asset reference

Return type:

str

delete_folder(asset, operator_comment, supervisor_comment)

Initiate and approve the deletion of a folder.

Parameters:

• asset (Folder) – The folder to delete
• operator_comment (str) – The comments from the operator which are added to the logs
• supervisor_comment (str) – The comments from the supervisor which are added to the logs

Returns:

The folder reference

Return type:

str

thumbnail(entity, filename, size=Thumbnail.LARGE)

Get the thumbnail image for an asset or folder

Parameters:

• entity (Entity) – The entity
• filename (str) – The file the image is written to
• size (Thumbnail) – The size of the thumbnail image

Returns:

The filename

Return type:

str

download(entity, filename)

Download the first generation of the access representation of an asset

Parameters:

• entity (Entity) – The entity
• filename (str) – The file the image is written to
• size (Thumbnail) – The size of the thumbnail image

Returns:

The filename

Return type:

str

updated_entities(previous_days: int = 1)

Fetch a list of entities which have changed (been updated) over the previous n days.

This method uses a generator function to make repeated calls to the server for every page of results.

Parameters:previous_days (int) – The number of days to check for changes. Returns:A list of entities Return type:list

all_events()

Returns a list of events for the user’s tenancy

This method uses a generator function to make repeated calls to the server for every page of results.

Returns:A list of events Return type:list

entity_events(entity: Entity)

Returns a list of event actions performed against this entity

This method uses a generator function to make repeated calls to the server for every page of results.

Parameters:entity (Entity) – The entity Returns:A list of events Return type:list

add_thumbnail(entity: Entity, image_file: str)

Set the thumbnail for the entity to the uploaded image

Supported image formats are png, jpeg, tiff, gif and bmp. The image must be 10MB or less in size.

Parameters:

• entity (Entity) – The entity
• image_file (str) – The path to the image

remove_thumbnail(entity: Entity)

Remove the thumbnail for the entity to the uploaded image

Parameters:image_file (str) – The path to the image

replace_generation_sync(content_object: ContentObject, file_name: str, fixity_algorithm, fixity_value)

Replace the last active generation of a content object with a new digital file.

Starts the workflow and blocks until the workflow completes.

Parameters:

• content_object (ContentObject) – The content object to replace
• file_name (str) – The path to the new content object
• fixity_algorithm (str) – Optional fixity algorithm
• fixity_value (str) – Optional fixity value

Returns:

Completed workflow status

Return type:

str

replace_generation_async(content_object: ContentObject, file_name: str, fixity_algorithm, fixity_value)

Replace the last active generation of a content object with a new digital file.

Starts the workflow and returns a process ID

Parameters:

• content_object (ContentObject) – The content object to replace
• file_name (str) – The path to the new content object
• fixity_algorithm (str) – Optional fixity algorithm
• fixity_value (str) – Optional fixity value

Returns:

Process ID

Return type:

str

get_async_progress(pid: str)

Return the status of a running process

Parameters:str (pid) – The progress ID Returns:Workflow status Return type:str

export_opex(entity: Entity, **kwargs)

Initiates export of the entity and downloads the opex package

Parameters:

• entity (Entity) – The entity to export Asset or Folder
• IncludeContent (str) – “Content”, “NoContent”
• IncludeMetadata (str) – “Metadata”, “NoMetadata”, “MetadataWithEvents”
• IncludedGenerations (str) – “LatestActive”, “AllActive”, “All”
• IncludeParentHierarchy (str) – “true”, “false”

Returns:

The path to the opex ZIP file

Return type:

str

class pyPreservica.Generation

Generations represent changes to content objects over time, as formats become obsolete new generations may need to be created to make the information accessible.

original

original generation (True or False)

active

active generation (True or False)

format_group

format for this generation

effective_date

effective date generation

bitstreams

list of Bitstream objects

class pyPreservica.Bitstream

Bitstreams represent the actual computer files as ingested into Preservica, i.e. the TIFF photograph or the PDF document

filename

The filename of the original bitstream

length

The file size in bytes of the original Bitstream

fixity

Map of fixity values for this bitstream, the key is the algorithm name and the value is the fixity value

class pyPreservica.Representation

Representations are used to define how the information object are composed in terms of technology and structure.

rep_type

The type of representation

name

The name of representation

asset

The asset the representation belongs to

class pyPreservica.Entity

Entity is the base class for assets, folders and content objects They all have the following attributes

reference

The unique internal reference for the entity

title

The title of the entity

description

The description of the entity

security_tag

The security tag of the entity

parent

The unique internal reference for this entity’s parent object

The parent of an Asset is always a Folder

The parent of a Folder is always a Folder or None for a folder at the root of the repository

The parent of a Content Object is always an Asset

metadata

A map of descriptive metadata attached to the entity.

The key of the map is the metadata identifier used to retrieve the metadata document and the value is the schema URI

entity_type

Assets have entity type EntityType.ASSET

Folders have entity type EntityType.FOLDER

Content Objects have entity type EntityType.CONTENT_OBJECT

class pyPreservica.Asset

Asset represents the information object or intellectual unit of information within the repository.

reference

The unique internal reference for the asset

title

The title of the asset

description

The description of the asset

security_tag

The security tag of the asset

parent

The unique internal reference for this asset’s parent folder

metadata

A dict of descriptive metadata attached to the asset.

The key of the dict is the metadata identifier used to retrieve the metadata document and the value is the schema URI

entity_type

Assets have entity type EntityType.ASSET

class pyPreservica.Folder

Folder represents the structure of the repository and contains both Assets and Folder objects.

reference

The unique internal reference for the folder

title

The title of the folder

description

The description of the folder

security_tag

The security tag of the folder

parent

The unique internal reference for this folder’s parent folder

metadata

A map of descriptive metadata attached to the folder.

The key of the map is the metadata identifier used to retrieve the metadata document and the value is the schema URI

entity_type

Assets have entity type EntityType.FOLDER

class pyPreservica.ContentObject

ContentObject represents the internal structure of an asset.

reference

The unique internal reference for the content object

title

The title of the content object

description

The description of the content object

security_tag

The security tag of the content object

parent

The unique internal reference for this content object parent asset

metadata

A map of descriptive metadata attached to the content object.

The key of the map is the metadata identifier used to retrieve the metadata document and the value is the schema URI

entity_type

Content objects have entity type EntityType.CONTENT_OBJECT

class pyPreservica.EntityType

Enumeration of the Entity Types

class pyPreservica.RelationshipDirection

An enumeration.

class pyPreservica.IntegrityCheck(check_type, success, date, adapter, fixed, reason)

Class to hold information about completed integrity checks

Content API

This part of the documentation covers all the interfaces of pyPreservica UploadAPI object.

class pyPreservica.ContentAPI

object_details(entity_type, reference)

Return a list of all the indexed fields in the Preservica search index.

Parameters:

• entity_type (str) – Entity type, either “IO” or “SO”
• reference (str) – Entity reference

Returns:

object attributes

Return type:

dict

indexed_fields()

Return a list of all the indexed fields in the Preservica search index.

Returns:list of index field names Return type:list

simple_search_list(query: str = "%", page_size: int = 10, *args)

Search Preservica using a simple search term across all indexed fields, the results are returned as generator

Parameters:

• query (str) – Query term
• page_size (int) – Number of results fetched between server calls
• args (tuple) – index names to include in the result

Returns:

list of search result hits

Return type:

list

simple_search_csv(query: str = "%", csv_file="search.csv", *args)

Search Preservica using a simple search term across all indexed fields, output the results to a csv file.

Parameters:

• query (str) – Query term
• page_size (int) – Number of results fetched between server calls
• args (tuple) – index names to include in the result

Upload API

This part of the documentation covers all the interfaces of pyPreservica UploadAPI object.

pyPreservica.simple_asset_package(preservation_file=None, access_file=None, export_folder=None, parent_folder=None, compress=True, **kwargs)

Create a Preservica package containing a single Asset from a single preservation file and an optional access file. The Asset contains one Content Object for each representation.

If only the preservation file is provided the asset has one representation

Parameters:

• preservation_file (str) – Path to the preservation file
• access_file (str) – Path to the access file
• export_folder (str) – The package location folder
• parent_folder (Folder) – The folder to ingest the asset into
• compress (bool) – Compress the ZIP file
• Title (str) – Asset Title
• Description (str) – Asset Description
• SecurityTag (str) – Asset SecurityTag
• CustomType (str) – Asset CustomType
• Preservation_Content_Title (str) – Title of the Preservation Representation Content Object
• Preservation_Content_Description (str) – Description of the Preservation Representation Content Object
• Access_Content_Title (str) – Title of the Access Representation Content Object
• Access_Content_Description (str) – Description of the Access Representation Content Object
• Asset_Metadata (dict) – Dictionary of Asset metadata documents
• Identifiers (dict) – Dictionary of Asset rd party identifiers

pyPreservica.complex_asset_package(preservation_files_list=None, access_files_list=None, export_folder=None, parent_folder=None, compress=True, **kwargs)

Create a Preservica package containing a single Asset from a multiple preservation files and optional access files. The Asset contains multiple Content Objects within each representation.

If only the preservation files are provided the asset has one representation

param list preservation_files_list:  Paths to the preservation files param list access_files_list:  Paths to the access files param str export_folder:  The package location folder param Folder parent_folder:  The folder to ingest the asset into param bool compress:  Compress the ZIP file param str Title:  Asset Title param str Description:  Asset Description param str SecurityTag:  Asset SecurityTag param str CustomType:  Asset CustomType param str Preservation_Content_Title:  Title of the Preservation Representation Content Object param str Preservation_Content_Description:  Description of the Preservation Representation Content Object param str Access_Content_Title:  Title of the Access Representation Content Object param str Access_Content_Description:  Description of the Access Representation Content Object param dict Asset_Metadata:  Dictionary of Asset metadata documents param dict Identifiers:  Dictionary of Asset rd party identifiers

optional kwargs map ‘Title’ Asset Title ‘Description’ Asset Description ‘SecurityTag’ Asset Security Tag ‘CustomType’ Asset Type ‘Preservation_Content_Title’ Content Object Title of the Preservation Object ‘Preservation_Content_Description’ Content Object Description of the Preservation Object ‘Access_Content_Title’ Content Object Title of the Access Object ‘Access_Content_Description’ Content Object Description of the Access Object ‘Preservation_Generation_Label’ Generation Label for the Preservation Object ‘Access_Generation_Label’ Generation Label for the Access Object ‘Asset_Metadata’ Map of metadata schema/documents to add to asset ‘Identifiers’ Map of asset identifiers ‘Preservation_files_fixity_callback’ Callback to allow external generated fixity values ‘Access_files_fixity_callback’ Callback to allow external generated fixity values ‘IO_Identifier_callback’ Callback to allow external generated Asset identifier ‘Preservation_Representation_Name’ Name of the Preservation Representation ‘Access_Representation_Name’ Name of the Access Representation

pyPreservica.cvs_to_xml(csv_file, xml_namespace, root_element, file_name_column='filename', export_folder=None, additional_namespaces=None)

Export the rows of a CSV file as XML metadata documents which can be added to Preservica assets

Parameters:

• csv_file (str) – Path to the csv file
• xml_namespace (str) – The XML namespace for the created XML documents
• root_element (str) – The root element for the XML documents
• file_name_column (str) – The CSV column which should be used to name the xml files
• export_folder (str) – The path to the export folder
• additional_namespaces (dict) – A map of prefix, uris to use as additional namespaces

class pyPreservica.UploadAPI(username: str = None, password: str = None, tenant: str = None, server: str = None, use_shared_secret: bool = False)

ingest_tweet(twitter_user=None, tweet_id: int = 0, twitter_consumer_key=None, twitter_secret_key=None, folder=None, callback=None, **kwargs)

Ingest tweets from a twitter stream by twitter username

Parameters:

• tweet_id –
• twitter_user (str) – Twitter Username
• twitter_consumer_key (str) – Optional asset title
• twitter_secret_key (str) – Optional asset description
• folder (str) – Folder to ingest into
• callback (callback) – Optional upload progress callback

Raises:

RuntimeError –

ingest_twitter_feed(twitter_user=None, num_tweets: int = 25, twitter_consumer_key=None, twitter_secret_key=None, folder=None, callback=None, **kwargs)

Ingest tweets from a twitter stream by twitter username

Parameters:

• twitter_user (str) – Twitter Username
• num_tweets (int) – The number of tweets from the stream
• twitter_consumer_key (str) – Optional asset title
• twitter_secret_key (str) – Optional asset description
• folder (str) – Folder to ingest into
• callback (callback) – Optional upload progress callback

Raises:

RuntimeError –

ingest_web_video(url=None, parent_folder=None, **kwargs)

Ingest a web video such as YouTube etc based on the URL

Parameters:

• url (str) – URL to the youtube video
• parent_folder (Folder) – The folder to ingest the video into
• Title (str) – Optional asset title
• Description (str) – Optional asset description
• SecurityTag (str) – Optional asset security tag
• Identifiers (dict) – Optional asset 3rd party identifiers
• Asset_Metadata (dict) – Optional asset additional descriptive metadata
• callback (callback) – Optional upload progress callback

Raises:

RuntimeError –

upload_buckets()

Get a list of available upload buckets

Returns:dict of bucket names and regions

upload_credentials(location_id: str)

Retrieves temporary upload credentials (Amazon STS, or Azure SAS) for this location.

Returns:dict

upload_locations()

Upload locations are configured on the Sources page as ‘SIP Upload’. :return: dict

upload_zip_package(path_to_zip_package, folder=None, callback=None, delete_after_upload=False)

Uploads a zip file package directly to Preservica and starts an ingest workflow

Parameters:

• path_to_zip_package (str) – Path to the package
• folder (Folder) – The folder to ingest the package into
• callback (Callable) – Optional callback to allow the callee to monitor the upload progress
• delete_after_upload (bool) – Delete the local copy of the package after the upload has completed

Returns:

preservica-progress-token to allow the workflow progress to be monitored

Return type:

str

Raises:

RuntimeError –

upload_zip_package_to_Azure(path_to_zip_package, container_name, folder=None, delete_after_upload=False, show_progress=False)

Uploads a zip file package to an Azure container connected to a Preservica Cloud System

Parameters:

• path_to_zip_package (str) – Path to the package
• container_name (str) – container connected to an ingest workflow
• folder (Folder) – The folder to ingest the package into
• delete_after_upload (bool) – Delete the local copy of the package after the upload has completed

upload_zip_package_to_S3(path_to_zip_package, bucket_name, folder=None, callback=None, delete_after_upload=False)

Uploads a zip file package to an S3 bucket connected to a Preservica Cloud System

Parameters:

• path_to_zip_package (str) – Path to the package
• bucket_name (str) – Bucket connected to an ingest workflow
• folder (Folder) – The folder to ingest the package into
• callback (Callable) – Optional callback to allow the callee to monitor the upload progress
• delete_after_upload (bool) – Delete the local copy of the package after the upload has completed

Retention Management API

https://eu.preservica.com/api/entity/documentation.html#/%2Fretention-policies

class pyPreservica.RetentionPolicy(name: str, reference: str)

class pyPreservica.RetentionAssignment(entity_reference: str, policy_reference: str, api_id: str, start_date, expired=False)

class pyPreservica.RetentionAPI(username=None, password=None, tenant=None, server=None, use_shared_secret=False)

add_assignments(entity: pyPreservica.common.Entity, policy: pyPreservica.retentionAPI.RetentionPolicy) → pyPreservica.retentionAPI.RetentionAssignment

Assign a retention policy to an Asset.

Parameters:

• entity (Entity) – The Preservica Entity to assign a policy to
• policy (RetentionPolicy) – The RetentionAssignment

Returns:

The RetentionAssignment

Return type:

RetentionAssignment

assignable_policy(reference: str, status: bool)

Make a policy assignable

Parameters:

• reference (str) – The policy ID
• status (bool) – The assignable status

Returns:

assignments(entity: pyPreservica.common.Entity) → Set[pyPreservica.retentionAPI.RetentionAssignment]

Return a list of retention policies for an entity.

Parameters:entity (class:Entity) – The entity to fetch assignments for Returns:Set of policy assignments Return type:Set[RetentionAssignment]

create_policy(**kwargs)

Create a new policy

Arguments are kwargs map

Name Description SecurityTag StartDateField Period PeriodUnit ExpiryAction ExpiryActionParameters Restriction Assignable

delete_policy(reference: str)

Delete a retention policy

Parameters:reference (str) – The policy reference

policies() → Set[pyPreservica.retentionAPI.RetentionPolicy]

Return a list of all retention policies Only returns the first 250 policies in the system

Returns:Set of retention policies Return type:Set[RetentionPolicy]

policy(reference: str) → pyPreservica.retentionAPI.RetentionPolicy

Return a retention policy by reference

Parameters:reference (str) – The policy reference Returns:The retention policy Return type:RetentionPolicy

policy_by_name(name: str) → pyPreservica.retentionAPI.RetentionPolicy

Return a retention policy by name

Parameters:name (str) – The policy name Returns:The retention policy Return type:RetentionPolicy

remove_assignments(retention_assignment: pyPreservica.retentionAPI.RetentionAssignment)

Delete a retention policy from an asset

Parameters:retention_assignment (RetentionAssignment) – The Preservica Entity to assign a policy to Returns:The Asset Reference Return type:str

update_policy(reference: str, **kwargs)

Update an existing policy

Arguments are kwargs map

Name Description SecurityTag StartDateField Period PeriodUnit ExpiryAction ExpiryActionParameters Restriction Assignable

Workflow API

Note

The Workflow API is available for Enterprise Preservica users

https://eu.preservica.com/api/admin/documentation.html

class pyPreservica.WorkflowContext(workflow_id, workflow_name: str)

Defines a workflow context. The workflow context is the pre-defined workflow which is ready to run

Parameters:

• workflow_name (str) – The Workflow context name
• workflow_id (str) – The Workflow context id

class pyPreservica.WorkflowInstance(instance_id: int)

Defines a workflow Instance. The workflow Instance is context which has been executed

Parameters:instance_id (int) – The Workflow instance Id

class pyPreservica.WorkflowAPI(username: str = None, password: str = None, tenant: str = None, server: str = None, use_shared_secret: bool = False)

A class for calling the Preservica Workflow API

This API can be used to programmatically manage the Preservica Workflows.

https://preview.preservica.com/sdb/rest/workflow/documentation.html

get_workflow_contexts(definition: str)

Return a list of Workflow Contexts which have the same Workflow Definition

Parameters:definition (str) – The Workflow Definition ID Returns:List of Workflow Contexts Return type:list

get_workflow_contexts_by_type(workflow_type: str)

Return a list of Workflow Contexts which have the same Workflow type

Parameters:workflow_type (str) – The Workflow type Ingest, Access, Transformation or DataManagement Returns:List of Workflow Contexts Return type:list

start_workflow_instance(workflow_context: pyPreservica.workflowAPI.WorkflowContext, **kwargs)

Start a workflow context

Returns a Correlation Id which is used to monitor the workflow progress

Parameters:

• workflow_context (WorkflowContext) – The workflow context to start
• kwargs – Key/Values to pass to the workflow instance

Returns:

correlation_id

Return type:

str

terminate_workflow_instance(instance_ids)

Terminate a workflow by its instance id

Parameters:instance_ids (int or a list of int) – The Workflow instance

workflow_instance(instance_id: int) → pyPreservica.workflowAPI.WorkflowInstance

Return a workflow instance by its Id

Parameters:instance_id (int) – The Workflow instance Returns:workflow_instance Return type:WorkflowInstance

workflow_instances(workflow_state: str, workflow_type: str, **kwargs)

Return a list of Workflow instances

Parameters:

• workflow_state – The Workflow state Aborted, Active, Completed, Finished_Mixed_Outcome, Pending, Suspended, Unknown, or Failed
• workflow_type – The Workflow type Ingest, Access, Transformation or DataManagement

Administration and Management API

Note

The Administration and Management API needs to be enabled by the help desk.

https://eu.preservica.com/sdb/rest/workflow/documentation.html

class pyPreservica.AdminAPI(username: str = None, password: str = None, tenant: str = None, server: str = None, use_shared_secret: bool = False)

add_security_tag(tag_name) → str

Create a new security tag

Parameters:tag_name (str) – The new security tag Returns:The new security tag Return type:str

add_system_role(role_name) → str

Create a new user roles

Parameters:role_name (str) – The new role Returns:The new role Return type:str

add_user(username: str, full_name: str, roles: list, externally_authenticated: bool = False)

Add a new user

Parameters:

• externally_authenticated –
• username (str) – email address of the preservica user
• full_name (str) – Users real name
• roles (list) – List of roles assigned to the user

Returns:

dictionary of user attributes

Return type:

dict

add_xml_document(name: str, xml_data: Any, document_type: str = 'MetadataTemplate')

Add a new XML document to Preservica The default type of XML document is a descriptive metadata template

Options are:

MetadataDropdownLists -> Authority Lists CustomIndexDefinition -> Custom Search Indexes MetadataTemplate -> Metadata Template UploadWizardConfigurationFile -> Upload Wizard Config ConfigurationFile -> Heritrix Config File

Parameters:

• name (str) – The name of the xml document
• xml_data – The xml schema as a UTF-8 string or as a file like object
• document_type (str) – The type of the XML document, defaults to descriptive metadata templates

Returns:

None

Return type:

None

add_xml_schema(name: str, description: str, originalName: str, xml_data: Any)

Add a new XSD document to Preservica

Parameters:

• name (str) – Name for the XSD schema
• description (str) – Description for the XSD schema
• originalName (str) – The original file name for the schema on disk
• xml_data (Any) – The xml schema as a UTF-8 string or a file like object

Returns:

None

Return type:

None

add_xml_transform(name: str, input_uri: str, output_uri: str, purpose: str, originalName: str, xml_data: Any)

Add a new XML transform to Preservica

Parameters:

• name (str) – The name of the XML transform
• input_uri (str) – The URI of the input XML document
• output_uri (str) – The URI of the output XML document
• purpose (str) – The purpose of the transform, “transform” , “edit”, “view”
• originalName (str) – The original file name of the transform
• xml_data (Any) – The transform xml as a string or file like object

Returns:

None

Return type:

None

all_users() → list

Return a list of all users in the system

Return list of usernames:   Return type:list

change_user_display_name(username: str, new_display_name: str) → dict

Change the user display name

Parameters:

• username (str) – email address of the preservica user
• new_display_name (str) – Users real name

Returns:

dictionary of user attributes

Return type:

dict

delete_security_tag(tag_name)

Delete a security tag

Parameters:tag_name (str) – The security tag to delete

delete_system_role(role_name)

Delete a system role

Parameters:role_name (str) – The role to delete

delete_user(username: str)

Delete a user

Parameters:username (str) – email address of the preservica user

delete_xml_document(uri: str)

Delete a XML document from Preservica

Parameters:uri (str) – The URI of the xml document to delete Returns:None Return type:None

delete_xml_schema(uri: str)

Delete an XML schema from Preservica

Parameters:uri (str) – The URI of the xml schema to delete Returns:None Return type:None

delete_xml_transform(input_uri: str, output_uri: str)

Delete a XSD document from Preservica

Parameters:

• input_uri (str) – The URI of the input XML document
• output_uri (str) – The URI of the output XML document

Returns:

None

Return type:

None

disable_user(username)

Disable a Preservica User to prevent them logging in

Parameters:username (str) – email address of the preservica user

security_tags() → list

List all the security tags in the system

Returns:list of security tags Return type:list

system_roles() → list

List all the user access roles in the system

Returns:list of roles Return type:list

user_details(username: str) → dict

Get the details of a user by their username

Parameters:username (str) – email address of the preservica user Returns:dictionary of user attributes Return type:dict

user_report(report_name='users.csv')

Create a report on all tenancy users :return:

xml_document(uri: str) → str

fetch the metadata XML document as a string by its URI

Parameters:uri (str) – The URI of the xml document Returns:The XML document as a string Return type:str

xml_documents() → List

fetch the list of XML documents stored in Preservica

Returns:List of XML documents stored in Preservica Return type:list

xml_schema(uri: str) → str

fetch the metadata schema XSD document as a string by its URI

Parameters:uri (str) – The URI of the xml schema Returns:The XML schema as a string Return type:str

xml_schemas() → List

fetch the list of metadata schema XSD documents stored in Preservica

Returns:List of XML schema’s stored in Preservica Return type:list

xml_transform(input_uri: str, output_uri: str) → str

fetch the XML transform as a string by its URIs

Parameters:

• input_uri (str) – The URI of the input XML document
• output_uri (str) – The URI of the output XML document

Returns:

The XML transform as a string

Return type:

str

xml_transforms() → List

fetch the list of xml transforms stored in Preservica

Returns:List of XML transforms stored in Preservica Return type:list

Process Monitor API

https://us.preservica.com/api/processmonitor/documentation.html

class pyPreservica.MonitorStatus

An enumeration.

class pyPreservica.MonitorCategory

An enumeration.

class pyPreservica.MonitorAPI(username: str = None, password: str = None, tenant: str = None, server: str = None, use_shared_secret: bool = False)

A class for the Preservica Repository Process Monitor API

https://us.preservica.com/api/processmonitor/documentation.html

API for retrieving and updating monitoring information about processes.

messages(monitor_id, status: pyPreservica.monitorAPI.MessageStatus = None) → Generator

List of messages for a process

Parameters:

• monitor_id (str) – The Process ID
• status (MessageStatus) – The message status, info, warning, error etc

Returns:

Generator for each message, each message is a dict object

monitors(status: pyPreservica.monitorAPI.MonitorStatus = None, category: pyPreservica.monitorAPI.MonitorCategory = None) → Generator

Get a filtered list of non-abandoned process monitors

Parameters:

• status (MonitorStatus) – process status values (Pending, Running, Succeeded, Failed, Suspended, Recoverable)
• category (MonitorCategory) – process categories (Ingest, Export, DataManagement, Automated)

Returns:

Generator for each monitor

timeseries(monitor_id)

Get the historical record of progress for a single monitor

Parameters:monitor_id (str) – The Process ID Returns:List of timeseries information