Developer Interface
Entity API
This part of the documentation covers all the interfaces of pyPreservica EntityAPI object.
- class pyPreservica.EntityAPI(username: str | None = None, password: str | None = None, tenant: str | None = None, server: str | None = None, use_shared_secret: bool = False, two_fa_secret_key: str | None = None, protocol: str = 'https', request_hook: Callable | None = None)[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:
- 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:
- 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:
- 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:
- 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
- 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.
- 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:
- 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
- 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
- update_metadata(entity, schema, data)[source]
Update an existing descriptive XML document on an entity
- delete_metadata(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
- move_sync(entity, dest_folder)[source]
Move an entity (asset or folder) to a new folder This call blocks until the move is complete
- move_async(entity, dest_folder)[source]
Move an entity (asset or folder) to a new folder This call returns immediately and does not block
- 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.
- 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
- properties
list of technical properties each property is dict object containing PUID, PropertyName and Value
- formats
list of technical formats each format is dict object containing PUID, FormatName and FormatVersion
- 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
Dictionary object 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
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 = None, password: str | None = None, tenant: str | None = None, server: str | None = None, use_shared_secret: bool = False, two_fa_secret_key: str | None = None, protocol: str = 'https', request_hook=None)[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 the 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
- upload_zip_to_Source(path_to_zip_package, container_name, folder=None, delete_after_upload=False, show_progress=False)[source]
Uploads a zip file package to either an Azure container or S3 bucket depending on the Preservica system deployment
- Parameters:
path_to_zip_package (str) – Path to the package
container_name (str) – container connected to the 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
show_progress (bool) – Show upload progress bar
Retention Management API
https://eu.preservica.com/api/entity/documentation.html#/%2Fretention-policies
- 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, two_fa_secret_key: str | None = None, protocol: str = 'https', request_hook: Callable | None = None)[source]
- add_assignments(entity: Entity, policy: RetentionPolicy) 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:
- 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: Entity) Set[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(maximum: int = 250, next_page: str | None = None) PagedSet[source]
Return a list of all retention policies Returns a maxmium of 250 policies by default
- Returns:
Set of retention policies
- Return type:
Set[RetentionPolicy]
- policy(reference: str) RetentionPolicy[source]
Return a retention policy by reference
- Parameters:
reference (str) – The policy reference
- Returns:
The retention policy
- Return type:
- policy_by_name(name: str) RetentionPolicy[source]
Return a retention policy by name
- Parameters:
name (str) – The policy name
- Returns:
The retention policy
- Return type:
- remove_assignments(retention_assignment: 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
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
- class pyPreservica.WorkflowInstance(instance_id: int)[source]
Defines a workflow Instance. The workflow Instance is a context which has been executed
- class pyPreservica.WorkflowAPI(username: str | None = None, password: str | None = None, tenant: str | None = None, server: str | None = None, use_shared_secret: bool = False, two_fa_secret_key: str | None = None, protocol: str = 'https', request_hook: Callable | None = None)[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: 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) WorkflowInstance[source]
Return a workflow instance by its Id
- Parameters:
instance_id (int) – The Workflow instance
- Returns:
workflow_instance
- Return type:
- 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 = None, password: str | None = None, tenant: str | None = None, server: str | None = None, use_shared_secret: bool = False, two_fa_secret_key: str | None = None, protocol: str = 'https', request_hook=None)[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
- enable_user(username)[source]
Enable a Preservica User
- 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
- 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
Process Monitor API
https://us.preservica.com/api/processmonitor/documentation.html
- class pyPreservica.MonitorStatus(value)[source]
An enumeration.
- FAILED = 'Failed'
- PENDING = 'Pending'
- RECOVERABLE = 'Recoverable'
- RUNNING = 'Running'
- SUCCEEDED = 'Succeeded'
- SUSPENDED = 'Suspended'
- class pyPreservica.MonitorCategory(value)[source]
An enumeration.
- AUTOMATED = 'Automated'
- DATA_MANAGEMENT = 'DataManagement'
- EXPORT = 'Export'
- INGEST = 'Ingest'
- class pyPreservica.MonitorAPI(username: str | None = None, password: str | None = None, tenant: str | None = None, server: str | None = None, use_shared_secret: bool = False, two_fa_secret_key: str | None = None, protocol: str = 'https', request_hook=None)[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: MessageStatus | None = 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: MonitorStatus | None = None, category: MonitorCategory | None = 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
WebHook API
https://us.preservica.com/api/webhook/documentation.html
- class pyPreservica.TriggerType(value)[source]
Enumeration of the Web hooks Trigger Types
- INDEXED = 'FULL_TEXT_INDEXED'
- INGEST_FAILED = 'INGEST_FAILED'
- MOVED = 'MOVED'
- SECURITY_CHANGED = 'CHANGED_SECURITY_DESCRIPTOR'
- class pyPreservica.WebHooksAPI(username: str | None = None, password: str | None = None, tenant: str | None = None, server: str | None = None, use_shared_secret: bool = False, two_fa_secret_key: str | None = None, protocol: str = 'https', request_hook=None)[source]
Class to register new webhook endpoints
- subscribe(url: str, triggerType: TriggerType, secret: str)[source]
Subscribe to a new web hook
- Parameters:
url
triggerType
secret
- Returns:
json_response
- subscriptions()[source]
Return all the current active web hook subscriptions as a json document
- Returns:
list of web hooks
Metadata Groups API
https://us.preservica.com/api/metadata/documentation.html#/%2Fgroups
The Metadata Groups API is designed allows the creation of custom metadata within NGI (New Generation Interface).
- class pyPreservica.Group(name: str, description: str)[source]
- description: str
- fields: List[GroupField]
- group_id: str
- name: str
- schemaUri: str
- class pyPreservica.GroupField(field_id: str, name: str, field_type: GroupFieldType = GroupFieldType.STRING, maxLength: int = -1, default: str = '', visible: bool = True, editable: bool = True, minOccurs: int = 0, maxOccurs: int = 1, indexed: bool = True, values: List | None = None)[source]
- default: str
- editable: bool
- field_id: str
- field_type: GroupFieldType
- indexed: bool
- maxLength: int
- maxOccurs: int
- minOccurs: int
- name: str
- values: List[str]
- visible: bool
- class pyPreservica.GroupFieldType(value)[source]
An enumeration.
- DATE = 'DATE'
- LONG_STRING = 'LONGSTRING'
- NUMBER = 'NUMBER'
- STRING = 'STRING'
- class pyPreservica.MetadataGroupsAPI(username: str | None = None, password: str | None = None, tenant: str | None = None, server: str | None = None, use_shared_secret: bool = False, two_fa_secret_key: str | None = None, protocol: str = 'https', request_hook: Callable | None = None)[source]
- add_fields(group_id: str, new_fields: List[GroupField]) dict[source]
Add new metadata fields to an existing Group
The new fields are appended to the end of the group
- Parameters:
group_id (str) – The group ID of the group to update
new_fields (List[GroupField]) – The list of new fields to add to the group
- Returns:
The updated Metadata Group as a JSON dict
- Return type:
dict
- add_form(json_form: dict | str)[source]
Create a new Metadata fORM using a JSON dictionary object or document
- Parameters:
json_form (dict) – JSON dictionary or string
- Returns:
JSON document
- Return type:
dict
- add_group(group_name: str, group_description: str, fields: List[GroupField]) dict[source]
Create a new Metadata Group GroupFields
- Parameters:
group_name (str) – The name of the new Group
group_description (str) – The description of the new Group
fields (List[GroupField]) – The list of fields
- Returns:
The new metadata Group as a JSON dict
- Return type:
dict
- add_group_json(json_object: dict | str) dict[source]
Create a new Metadata Group using a JSON dictionary object or document
- Parameters:
json_object (dict) – JSON dictionary or string
- Returns:
JSON document
- Return type:
dict
- delete_group(group_id: str)[source]
Delete a new Metadata Group using its ID
- Parameters:
group_id (str) – Group ID
- Returns:
- Return type:
None
- delete_group_namespace(schema: str)[source]
Delete a new Metadata Group using its schema URI
- Parameters:
schema (str) – The Group namespace schema URI
- Returns:
None
- Return type:
None
- form(form_id: str) dict[source]
Return a Form as a JSON dict object
- Parameters:
form_id (str) – The Form id
- Returns:
JSON document
- Return type:
dict
- forms(schema_uri: str | None = None) dict[source]
Return all the metadata Forms in the tenancy as a list of JSON dict objects
- Parameters:
schema_uri (str) – The Form schema Uri
- Returns:
List of JSON dictionary object
- Return type:
dict
- group(group_id: str) Group[source]
Return a Group object by its ID
- Parameters:
group_id (str) – The Group id
- Returns:
The metadata Group Object
- Return type:
- group_json(group_id: str) dict[source]
Return a Group as a JSON object
- Parameters:
group_id (str) – The Group id
- Returns:
JSON document
- Return type:
dict