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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Return the status of a running process

Parameters:str (pid) – The progress ID
Returns:Workflow status
Return type:str
export_opex(entity: Entity, **kwargs)[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

Enumeration of the Entity Types

class pyPreservica.RelationshipDirection[source]

An enumeration.

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

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[source]
object_details(entity_type, reference)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]
ingest_tweet(twitter_user=None, tweet_id: int = 0, twitter_consumer_key=None, twitter_secret_key=None, folder=None, callback=None, **kwargs)[source]

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)[source]

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)[source]

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()[source]

Get a list of available upload buckets

Returns:dict of bucket names and regions
upload_credentials(location_id: str)[source]

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

Returns:dict
upload_locations()[source]

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)[source]

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)[source]

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)[source]

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)[source]
class pyPreservica.RetentionAssignment(entity_reference: str, policy_reference: str, api_id: str, start_date, expired=False)[source]
class pyPreservica.RetentionAPI(username=None, password=None, tenant=None, server=None, use_shared_secret=False)[source]
add_assignments(entity: pyPreservica.common.Entity, policy: pyPreservica.retentionAPI.RetentionPolicy) → pyPreservica.retentionAPI.RetentionAssignment[source]

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)[source]

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][source]

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)[source]

Create a new policy

Arguments are kwargs map

Name Description SecurityTag StartDateField Period PeriodUnit ExpiryAction ExpiryActionParameters Restriction Assignable

delete_policy(reference: str)[source]

Delete a retention policy

Parameters:reference (str) – The policy reference
policies() → Set[pyPreservica.retentionAPI.RetentionPolicy][source]

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[source]
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[source]
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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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[source]

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)[source]

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)[source]
add_security_tag(tag_name) → str[source]

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[source]

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)[source]

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')[source]

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)[source]

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)[source]

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[source]

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[source]

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)[source]

Delete a security tag

Parameters:tag_name (str) – The security tag to delete
delete_system_role(role_name)[source]

Delete a system role

Parameters:role_name (str) – The role to delete
delete_user(username: str)[source]

Delete a user

Parameters:username (str) – email address of the preservica user
delete_xml_document(uri: str)[source]

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)[source]

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)[source]

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)[source]
Disable a Preservica User to prevent them logging in
Parameters:username (str) – email address of the preservica user
security_tags() → list[source]

List all the security tags in the system

Returns:list of security tags
Return type:list
system_roles() → list[source]

List all the user access roles in the system

Returns:list of roles
Return type:list
user_details(username: str) → dict[source]

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')[source]

Create a report on all tenancy users :return:

xml_document(uri: str) → str[source]

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[source]

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[source]
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[source]
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[source]

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[source]

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.MonitorAPI(username: str = None, password: str = None, tenant: str = None, server: str = None, use_shared_secret: bool = False)[source]

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[source]

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[source]

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)[source]

Get the historical record of progress for a single monitor

Parameters:monitor_id (str) – The Process ID
Returns:List of timeseries information
class pyPreservica.MonitorStatus[source]

An enumeration.

class pyPreservica.MonitorCategory[source]

An enumeration.