Class PhysicalDocument
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Implements
Inherited Members
Namespace: SuperOffice.CRM.Documents
Assembly: SoDataBase.dll
Syntax
public sealed class PhysicalDocument : IStreamProviderRemarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.Properties
ArchiveProvider
The numeric plugin ID of the plugin responsible for this physical document
Declaration
public int ArchiveProvider { get; }Property Value
| Type | Description |
|---|---|
| int |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.DocumentId
ID of document row this physical document is related to
Declaration
public int DocumentId { get; }Property Value
| Type | Description |
|---|---|
| int |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.DocumentInfo
Document Info object - created by this class from documentId if needed
Declaration
public IDocumentInfo DocumentInfo { get; }Property Value
| Type | Description |
|---|---|
| IDocumentInfo |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.Length
Length (in bytes) of the document.
Declaration
public long Length { get; }Property Value
| Type | Description |
|---|---|
| long |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.Methods
AssociateRename(string, string)
Invokes document plugins that implements the IAssociateRename interface.
Declaration
public static void AssociateRename(string oldName, string newName)Parameters
| Type | Name | Description |
|---|---|---|
| string | oldName | |
| string | newName |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.BeginReadAsync(CancellationToken)
Start reading the document.
Declaration
public Task BeginReadAsync(CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
Read bytes from the document using the Read(long, byte[], int, int) method.
Call the EndRead method to specify that you are
finished reading the document.
BeginWriteAsync(CancellationToken)
Start writing the document file.
Declaration
public Task BeginWriteAsync(CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
Use the Write(long, byte[], int, int) method to write data to the file.
As data might be written to a temporary location, the EndWrite
will archive the document to the document archive.
CheckinDocumentAsync(string[], string, string[], CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<ReturnInfo> CheckinDocumentAsync(string[] allowedReturnTypes, string versionDescription, string[] versionExtraFields, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string[] | allowedReturnTypes | |
| string | versionDescription | |
| string[] | versionExtraFields | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<ReturnInfo> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.CheckoutDocumentAsync(CancellationToken, params string[])
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<ReturnInfo> CheckoutDocumentAsync(CancellationToken cancellationToken = default, params string[] allowedReturnTypes)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken | |
| string[] | allowedReturnTypes |
Returns
| Type | Description |
|---|---|
| Task<ReturnInfo> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.CreateDefaultDocumentTemplateAsync(int, int, CancellationToken)
Create a blank default document based on the given documentTypeId. Called when creating a new template.
Declaration
public static Task<string> CreateDefaultDocumentTemplateAsync(int documentTypeKey, int documentTemplateId, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| int | documentTypeKey | Id for a document type. Ignored if document plugin does not use document types. |
| int | documentTemplateId | Document template id |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> | Extref/Filename for new template. This value is written to the template's Filename property in the database. |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.CreateDefaultDocumentTemplateLanguageAsync(IDocumentTemplateInfo, string, CancellationToken)
Create a new template language alternative based on the existing template
Declaration
public static Task CreateDefaultDocumentTemplateLanguageAsync(IDocumentTemplateInfo docInfo, string languageCode, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentTemplateInfo | docInfo | |
| string | languageCode | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.CreateFilenameForNewTemplateAsync(IDocumentTemplateInfo, string, CancellationToken)
Calculates a new name for a template based on the properties from an existing template. Should only be used when copying existing templates.
Declaration
public static Task<string> CreateFilenameForNewTemplateAsync(IDocumentTemplateInfo sourceTemplateInfo, string newTemplateName, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentTemplateInfo | sourceTemplateInfo | |
| string | newTemplateName | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> | newer null |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.CreateNewEmptyAsync(IDocumentInfo, string, string[], string, string[], CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Task<(string extRef, string actualFileName)> CreateNewEmptyAsync(IDocumentInfo incomingInfo, string fileName, string[] extraFields, string versionDecription, string[] versionExtraFields, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentInfo | incomingInfo | |
| string | fileName | |
| string[] | extraFields | |
| string | versionDecription | |
| string[] | versionExtraFields | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<(string value, string tooltip)> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.CreateNewEmptyByRefAsync(IDocumentInfo, string, string[], string, string[])
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Task<(string extRef, IDocumentInfo documentInfo, string actualFileName)> CreateNewEmptyByRefAsync(IDocumentInfo incomingInfo, string fileName, string[] extraFields, string versionDecription, string[] versionExtraFields)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentInfo | incomingInfo | |
| string | fileName | |
| string[] | extraFields | |
| string | versionDecription | |
| string[] | versionExtraFields |
Returns
| Type | Description |
|---|---|
| Task<(string extRef, IDocumentInfo documentInfo, string actualFileName)> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.CreateNewFromTemplateAsync(IDocumentInfo, string, string[], string, string[], string, CancellationToken)
Create a new document in the document archive without replacing template tags
Declaration
public static Task<(string extRef, string fileName)> CreateNewFromTemplateAsync(IDocumentInfo incomingInfo, string fileName, string[] extraFields, string versionDecription, string[] versionExtraFields, string uiCulture, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentInfo | incomingInfo | |
| string | fileName | |
| string[] | extraFields | |
| string | versionDecription | |
| string[] | versionExtraFields | |
| string | uiCulture | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<(string value, string tooltip)> | Reference to the newly created document in the document archive. |
Remarks
This method will create a new physical document, using the physical template unchanged. No template tag substitution will be attempted, no document conversions, nothing.
The method is generally used for creating mailmerge template documentsCreateNewFromTemplateWithTagsAsStreamAsync(int, string, TagContainer, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Task<Stream> CreateNewFromTemplateWithTagsAsStreamAsync(int templateId, string uiCulture, TagContainer templateTags, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| int | templateId | |
| string | uiCulture | |
| TagContainer | templateTags | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<Stream> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.CreateNewFromTemplateWithTagsAsync(IDocumentInfo, string, string[], string, string[], TagContainer, string, CancellationToken)
Create a new document in the document archive, replacing template tags
Declaration
public static Task<(string extRef, string fileName)> CreateNewFromTemplateWithTagsAsync(IDocumentInfo incomingInfo, string fileName, string[] extraFields, string versionDecription, string[] versionExtraFields, TagContainer templateTags, string uiCulture, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentInfo | incomingInfo | |
| string | fileName | |
| string[] | extraFields | |
| string | versionDecription | |
| string[] | versionExtraFields | |
| TagContainer | templateTags | |
| string | uiCulture | UI Language (en-US or nb-NO) - used to select appropriate doc template |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<(string value, string tooltip)> | Reference to the newly created document in the document archive. |
Remarks
This method will create a new physical document, using the physical template and replacing all tags passed in through the TagContainer parameter.
DeleteDocumentAsync(CancellationToken, params string[])
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<ReturnInfo> DeleteDocumentAsync(CancellationToken cancellationToken = default, params string[] allowedReturnTypes)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken | |
| string[] | allowedReturnTypes |
Returns
| Type | Description |
|---|---|
| Task<ReturnInfo> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.DeleteDocumentTemplateLanguageAsync(IDocumentTemplateInfo, string, CancellationToken)
Deletes the document template language.
Declaration
public static Task DeleteDocumentTemplateLanguageAsync(IDocumentTemplateInfo templateInfo, string languageCode, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentTemplateInfo | templateInfo | Information about the template. The fields id and external reference must be filled out |
| string | languageCode | The language code ('en-US, 'nb-NO', etc). Field cannot be empty. |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.EndReadAsync(CancellationToken)
Express that you are finished reading the file. If the file is read from a temporary location, it will be removed from it.
Declaration
public Task EndReadAsync(CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.EndWriteAsync(CancellationToken)
Specify that the writing of the document is completed and that the document can be archived in the document archive.
Declaration
public Task EndWriteAsync(CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.ExecuteDocumentCommand(string, string[], string, params string[])
Execute a custom command on a specified document and version
Declaration
public ReturnInfo ExecuteDocumentCommand(string versionId, string[] allowedReturnTypes, string command, params string[] additionalData)Parameters
| Type | Name | Description |
|---|---|---|
| string | versionId | Version identifier, blank implies 'latest' version |
| string[] | allowedReturnTypes | Array of names of allowed return types; if this array is empty then no limits are placed on return type. |
| string | command | Command name, taken from an earlier call to GetDocumentCommands(params string[]) - or any other command name that is understood by the provider. 'Private' commands that are not declared in GetDocumentCommands but are known to the authors of custom GUI code or OK. |
| string[] | additionalData | Array of strings containing whatever additional data the command
may need. This parameter is intended for authors of more complex custom GUI's and works as
a tunnel between the ultimate client and the document plugin. Standard GUI made by SuperOffice,
such as a context menu connected to a document item in an archive, will not populate this
member. |
Returns
| Type | Description |
|---|---|
| ReturnInfo | Return value object, specifying failure or success plus any optional, additional processing to be triggered |
Remarks
This command is called when the user chooses an action item from a dropdown/context menu. It is also reflected in the DocumentAgent service interface, so that custom GUI’s and external code can directly execute document plugin commands; this is useful if a plugin also has some corresponding custom GUI that needs to execute commands depending on user interaction.
The parameterallowedReturnTypes can be used by clients to hint to the plugin
what kind of return value processing is available. For instance, a mobile client might
only offer None and Message, and this information can be used by the document plugin to adapt
the processing of a command, if it wants to (for instance, use default values instead of
triggering some more advanced workflow).
The command is obtained from the GetDocumentCommands(params string[]) method.
ExistsAsync(CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<bool> ExistsAsync(CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<bool> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetAllDocPlugins()
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Dictionary<int, string> GetAllDocPlugins()Returns
| Type | Description |
|---|---|
| Dictionary<int, string> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetCheckoutStateAsync(CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<CheckoutInfo> GetCheckoutStateAsync(CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<CheckoutInfo> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDatabaseLanguageCodeAsync(CancellationToken)
Returns the database language for the current SuperOffice installation as stored in the ProductVersion table "SuperOffice" "DatabaseLanguage". "US"
Declaration
public static Task<string> GetDatabaseLanguageCodeAsync(CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> | SuperOffice Language code: "US", "SW", "GE" etc. NULL if nothing is configured. |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDatabaseLanguageCultureAsync(CancellationToken)
Returns the database language for the current SuperOffice installation as stored in the ProductVersion table "SuperOffice" "DatabaseLanguage". "US"
Declaration
public static Task<CultureInfo> GetDatabaseLanguageCultureAsync(CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<CultureInfo> | CultureInfo based on the neutral ISO language: "en", "sv", "de" etc. NULL if nothing is configured. |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDefaultDocumentPluginIdAsync(CancellationToken)
Get the default document plugin id
Declaration
public static Task<int> GetDefaultDocumentPluginIdAsync(CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<int> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDocument(IDocumentInfo)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static PhysicalDocument GetDocument(IDocumentInfo incomingInfo)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentInfo | incomingInfo |
Returns
| Type | Description |
|---|---|
| PhysicalDocument |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDocument(int)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static PhysicalDocument GetDocument(int documentId)Parameters
| Type | Name | Description |
|---|---|---|
| int | documentId |
Returns
| Type | Description |
|---|---|
| PhysicalDocument |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDocumentCommands(params string[])
Get a list of custom commands, applicable to a specific document. Note that commands related to standard locking and versioning operations have their own API calls and are not 'custom commands' in this sense.
Declaration
public CommandInfo[] GetDocumentCommands(params string[] allowedReturnTypes)Parameters
| Type | Name | Description |
|---|---|---|
| string[] | allowedReturnTypes | Array of names of allowed return types; if this array is empty then no limits are placed on return type. |
Returns
| Type | Description |
|---|---|
| CommandInfo[] | Array of command descriptions. If there are no custom commands available, an empty array should be returned. |
Remarks
This API is called before a menu, task button or other GUI item that gives access to document-specific commands is shown. It is used to populate the GUI with available commands for a particular document, the results are not cached by the GUI.
Depending on the return type indicated in the command, the command might be filtered by GUI. More information can be found in the CommandInfo topic.GetDocumentIdFromPathAsync(string, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Task<int> GetDocumentIdFromPathAsync(string documentNameAndPath, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | documentNameAndPath | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<int> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDocumentPropertiesAsync(string[], CancellationToken)
Get the values of certain properties, for a given document
Declaration
public Task<Dictionary<string, string>> GetDocumentPropertiesAsync(string[] requestedProperties, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string[] | requestedProperties | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<Dictionary<string, string>> | Dictionary of key=value pairs, where the key is one of the requested property strings, and the value is the value of that property for the given document. |
Remarks
Each document can have a number of properties associated with it. A set of standard properties is defined in the Constants.Properties class. Ideally, retrieving properties should be a lightweight operation.
Note that 'properties' are a one-way mechanism where the document plugin provides information about the document or certain aspects of it. This is not the same as document-specific metadata, which is handled by the LoadMetaData() and SaveMetaData(string[]) methods.GetDocumentTemplatePropertiesAsync(int, CancellationToken, params string[])
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Task<Dictionary<string, string>> GetDocumentTemplatePropertiesAsync(int documentTemplateId, CancellationToken cancellationToken = default, params string[] requestedProperties)Parameters
| Type | Name | Description |
|---|---|---|
| int | documentTemplateId | |
| CancellationToken | cancellationToken | |
| string[] | requestedProperties |
Returns
| Type | Description |
|---|---|
| Task<Dictionary<string, string>> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDocumentTemplateUrlAsync(int, bool, string, CancellationToken)
Get a WebDAV-compliant URL referring to the given document template
Declaration
public static Task<string> GetDocumentTemplateUrlAsync(int documentTemplateId, bool writableUrl, string languageCode, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| int | documentTemplateId | The id of the document template |
| bool | writableUrl | |
| string | languageCode | Language variation on the template. May be ignored by the plugin, or used to keep language specific versions of the template. |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> | URL that gives access to the document. If the document plugin does not support URL access, then a blank string should be returned. |
Remarks
Document plugins may support document access via WebDAV. This call is used to retrieve a WebDAV url that will give the specified access to the document. This URL will be passed to the ultimate client (most probably a text editor application), and control will not return to NetServer.
The string returned here should be a fully resolved URL that can be given directly to the editor application.GetDocumentTypesForDocumentTemplates(int)
Get a list of supported document template types.
Declaration
public static Dictionary<int, string> GetDocumentTypesForDocumentTemplates(int pluginId)Parameters
| Type | Name | Description |
|---|---|---|
| int | pluginId |
Returns
| Type | Description |
|---|---|
| Dictionary<int, string> | An dictionary of key=display-name for supported document types for template. Empty dictionary if no document types supported. |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDocumentUrlAsync(IDocumentInfo, string, bool, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Task<string> GetDocumentUrlAsync(IDocumentInfo incomingInfo, string versionId, bool writeableUrl, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentInfo | incomingInfo | |
| string | versionId | |
| bool | writeableUrl | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDocumentUrlAsync(string, bool, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<string> GetDocumentUrlAsync(string versionId, bool writeableUrl, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | versionId | |
| bool | writeableUrl | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetDocumentUrlAsync(CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<string> GetDocumentUrlAsync(CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetLengthAsync(string, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<long> GetLengthAsync(string versionId = null, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | versionId | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<long> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetPlugin(int)
Return the plugin specified by its plugin-id
Declaration
public static IDocumentPlugin2 GetPlugin(int pluginId)Parameters
| Type | Name | Description |
|---|---|---|
| int | pluginId |
Returns
| Type | Description |
|---|---|
| IDocumentPlugin2 |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetPluginCapabilities(int)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Dictionary<string, string> GetPluginCapabilities(int pluginId)Parameters
| Type | Name | Description |
|---|---|---|
| int | pluginId |
Returns
| Type | Description |
|---|---|
| Dictionary<string, string> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.GetTemplateExtensionAsync(int, CancellationToken)
Get the "extension" for the template, i.e., what the file extension would have been - to help identify the stream content format.
Declaration
public static Task<string> GetTemplateExtensionAsync(int documentTemplateId, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| int | documentTemplateId | Document template primary key id |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> | String equivalent to a file extension, for instance ".docx" |
Remarks
Template documents are generally created in text editors and stored as files of some kind. The file extension indicates the kind of document - doc, docx, xls, txt, and so on. While the template may be stored inside the document repository as any kind of data byte collection, a concept akin to the file extension is still needed to help identify the document format, ahead of actually reading the template content.
GetTemplateLanguagesAsync(IDocumentTemplateInfo, CancellationToken)
Return the list of language-specific variants of a given document template, excepting the default language (""). The DatabaseLanguage should be used to determine the default language.
Declaration
public static Task<string[]> GetTemplateLanguagesAsync(IDocumentTemplateInfo templateInfo, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentTemplateInfo | templateInfo | The document template info |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string[]> | Array of ISO language codes identifying language variants: ["en", "sv", "de"]. Empty array if no variants |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.Exceptions
| Type | Condition |
|---|---|
| SoIllegalOperationException | Throws if templateInfo is null or id 0 |
GetVersionList()
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public VersionInfo[] GetVersionList()Returns
| Type | Description |
|---|---|
| VersionInfo[] |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.IsNameValid(string)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static bool IsNameValid(string name)Parameters
| Type | Name | Description |
|---|---|---|
| string | name |
Returns
| Type | Description |
|---|---|
| bool |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.LoadDocumentStreamAsync(IDocumentInfo, string, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Task<Stream> LoadDocumentStreamAsync(IDocumentInfo incomingInfo, string versionId, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentInfo | incomingInfo | |
| string | versionId | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<Stream> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.LoadDocumentStreamAsync(string, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<Stream> LoadDocumentStreamAsync(string versionId, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | versionId | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<Stream> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.LoadDocumentStreamAsync(CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<Stream> LoadDocumentStreamAsync(CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<Stream> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.LoadDocumentTemplateStreamAsync(int, string, CancellationToken)
Get data stream for document template
Declaration
public static Task<(Stream stream, string templateExtension)> LoadDocumentTemplateStreamAsync(int documentTemplateId, string uiCulture, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| int | documentTemplateId | Identity of document template |
| string | uiCulture | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<(Stream stream, string templateExtension)> | Opens stream with data for document template |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.LoadDocumentTemplateStreamAsync(string, bool, string, CancellationToken)
Retrieve data stream for a document template based on an identifier(Ex: the filename). All available document plugins are searched. The first available template is returned.
Declaration
public static Task<Stream> LoadDocumentTemplateStreamAsync(string templateIdentifier, bool allowPersonalTemplate, string uiCulture, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | templateIdentifier | Identifier for a template. Ex: "myTemplate.txt" |
| bool | allowPersonalTemplate | Should we search for personal templates before central |
| string | uiCulture | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<Stream> | Data stream for template or null if not found |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.LoadMetaData()
Retrieve metadata owned by the plugin/repository, related to one document (excluding version-dependent metadata)
Declaration
public string[] LoadMetaData()Returns
| Type | Description |
|---|---|
| string[] | Array of name=value strings, each representing one key and one value. |
Remarks
A document plugin may consume and provide an arbitrary number of metadata fields. These are placed in a string, string dictionary, representing name/value pairs. This call should not retrieve metadata related to any particular version, only data related to the document as a whole.
The NetServer service call DocumentAgent.GetDocumentEntity will (among other things) result in a call to this API to populate the ExtraFields property of the document entity carrier. Note, however, that the carrier handed over to the client may contain other fields in addition to those supplied by the document plugin, since the extrafields mechanism is generic and there may be other metadata providers along the line. Attribute names should be prefixed with the name of the document plugin, to maintain global uniqueness. It is strongly suggested that non-string data be formatted according to the rules followed by the CultureDataFormatter class, to avoid problems when parsing dates and floating-point types between different cultures and platforms.LoadVersionInfo(string)
Retrieve metadata owned by the plugin/repository, related to one particular version of one document
Declaration
public VersionInfo LoadVersionInfo(string versionId)Parameters
| Type | Name | Description |
|---|---|---|
| string | versionId | Version identifier, blank implies 'latest' version |
Returns
| Type | Description |
|---|---|
| VersionInfo | Fully populated version info structure |
Remarks
A document plugin may consume and provide an arbitrary number of metadata fields. These are placed in a string, string dictionary, representing name/value pairs. This call should only retrieve metadata related to a version.
The NetServer service call DocumentAgent.GetDocumentEntity will (among other things) result in a call to this API to populate the VersionInfo property of the document entity carrier. Attribute names should be prefixed with the name of the document plugin, to maintain global uniqueness. It is strongly suggested that non-string data be formatted according to the rules followed by the CultureDataFormatter class, to avoid problems when parsing dates and floating-point types between different cultures and platforms. To efficiently retrieve information about all versions, use the GetVersionList(IDocumentInfo) method, instead of iterating over this method.Read(long, byte[], int, int)
Sync version of Read, eternally required by the double sync/async contracts of the Stream class
Declaration
public int Read(long filePosition, byte[] buffer, int bufferStartPosition, int lenght)Parameters
| Type | Name | Description |
|---|---|---|
| long | filePosition | |
| byte[] | buffer | |
| int | bufferStartPosition | |
| int | lenght |
Returns
| Type | Description |
|---|---|
| int |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.ReadAsync(long, byte[], int, int, CancellationToken)
Read data from the document
Declaration
public Task<int> ReadAsync(long filePosition, byte[] buffer, int bufferStartPosition, int length, CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| long | filePosition | Position in the file to start reading from. |
| byte[] | buffer | Buffer to put the data read. |
| int | bufferStartPosition | Position in buffer to start filling it. |
| int | length | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<int> | Number of bytes actually read from the file. This should only be less then the file when the end of file is reached. |
Remarks
BeginRead must be called before this method. It is not requred that BeginRead is called within the scope of this method. It is required that it is called on bahalf of the same user and on the same document and that either this method or BeginRead is called during the last time period specified in the configuration. Default time period is 24 hours.
RenameDocumentAsync(string, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<string> RenameDocumentAsync(string suggestedNewName, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | suggestedNewName | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.SaveDocumentFromStreamAsync(IDocumentInfo, string[], Stream, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Task<ReturnInfo> SaveDocumentFromStreamAsync(IDocumentInfo incomingInfo, string[] allowedReturnTypes, Stream content, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentInfo | incomingInfo | |
| string[] | allowedReturnTypes | |
| Stream | content | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<ReturnInfo> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.SaveDocumentFromStreamAsync(string[], Stream, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<ReturnInfo> SaveDocumentFromStreamAsync(string[] allowedReturnTypes, Stream content, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string[] | allowedReturnTypes | |
| Stream | content | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<ReturnInfo> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.SaveDocumentTemplateStreamAsync(int, Stream, string, int, string, CancellationToken)
Create or update the document template contents. Usually used when uploading a file to a new document template.
Declaration
public static Task<TemplateInfo> SaveDocumentTemplateStreamAsync(int documentTemplateId, Stream content, string uiCulture, int pluginId, string providedFilename = null, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| int | documentTemplateId | Document template record id the database. |
| Stream | content | Stream containing file content |
| string | uiCulture | Language variation on the template. May be ignored by the plugin, or used to keep language specific versions of the template. |
| int | pluginId | If negative, use the plugin specified in the document template's load-from-plugin-id field |
| string | providedFilename | If provided and non-ewmpty, will be used to override extref value passed along to document plugin. Required to support replacing file-formats for existing templates (among other things) |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<TemplateInfo> | Template information with ExtRef/Filename and MimeType filled in. These values are saved in the DocTmpl record. |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.SaveMetaData(string[])
Store/update plugin-dependent document metadata in the repository
Declaration
public void SaveMetaData(string[] pluginData)Parameters
| Type | Name | Description |
|---|---|---|
| string[] | pluginData | Name=value array containing metadata |
Remarks
This call is made when the document metadata should be stored, and is the complement of the LoadMetaData(IDocumentInfo) method. The document plugin should extract whatever elements it recognizes from the pluginData name/value dictionary. Failure to recognize an element should not cause an exception, as there may be other plugins along the line (not document plugins, but service-level field providers) that own the data. Likewise, absence of a value should be taken to imply “no change” to that value - not "delete".
It is strongly suggested that non-string data be formatted according to the rules followed by the CultureDataFormatter class, to avoid problems when parsing dates and floating-point types between different cultures and platforms.SetDocumentTemplateFromDocumentTemplateAsync(IDocumentTemplateInfo, IDocumentTemplateInfo, CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public static Task<TemplateInfo> SetDocumentTemplateFromDocumentTemplateAsync(IDocumentTemplateInfo sourceTemplateInfo, IDocumentTemplateInfo destTemplateInfo, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| IDocumentTemplateInfo | sourceTemplateInfo | |
| IDocumentTemplateInfo | destTemplateInfo | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<TemplateInfo> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.SuggestFilenameAsync(CancellationToken)
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<string> SuggestFilenameAsync(CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.UndoCheckoutDocumentAsync(CancellationToken, params string[])
Facade for the Document Plugin system, and one-stop-shop for physical-document operations
Declaration
public Task<ReturnInfo> UndoCheckoutDocumentAsync(CancellationToken cancellationToken = default, params string[] allowedReturnTypes)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken | |
| string[] | allowedReturnTypes |
Returns
| Type | Description |
|---|---|
| Task<ReturnInfo> |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.Write(long, byte[], int, int)
Sync version of Write, eternally required by the double sync/async contracts of the Stream class
Declaration
public void Write(long filePosition, byte[] buffer, int bufferStartPosition, int lenght)Parameters
| Type | Name | Description |
|---|---|---|
| long | filePosition | |
| byte[] | buffer | |
| int | bufferStartPosition | |
| int | lenght |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.WriteAsync(long, byte[], int, int, CancellationToken)
Write a block of data
Declaration
public Task WriteAsync(long filePosition, byte[] buffer, int bufferStartPosition, int length, CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| long | filePosition | |
| byte[] | buffer | |
| int | bufferStartPosition | |
| int | length | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
An instance of this class represents a physical document in a document archive, and can be used to manipulate (Load, Save) that document and its metadata. Instances are constructed using a static factory function, always based on an already existing information in the database.
Static methods also provide access to document template functions and other non-document specific functions.Exceptions
| Type | Condition |
|---|---|
| SoIllegalOperationException |