Overview |
|
|
|
Attachments are different types of objects (such as a file, image or reference link) that are attached to an SDI. Depending on the type, Attachments may be stored with the SDI or uploaded to an Attachment Repository.
Attachments are configured and maintained by these LabVantage components:
| • | Attachment Policy, define policy settings that determine Attachment behavior. Establish rules that will evaluate certain characteristics of your attachments to determine the appropriate storage repository. |
| • | Attachment Element, configures the Attachment Detail Element added to a Maintenance Page. |
| • | Attachment Repositories manage the upload locations for "File" type Attachments. Property trees are used to configure different repository options. |
Depending on the configuration and view chosen, the attachment Element is rendered as a detail similar to the example shown below.
|
Attachment Types |
|
|
An "Attachment Type" defines the type of object that is saved as an Attachment, as well as how it is saved. LabVantage provides the following Attachment Types:
|
|
File Type Attachments |
LabVantage provides several options for uploading and storing "File" type Attachments. A standard installation of LabVantage provides the following Attachment Repository types:
| • | Network File Repository, manages files stored on the server's local file system. |
| • | Database File Repository, manages files stored in the LIMS database. |
| • | Amazon Web Services (AWS) Cloud File Repository, manages S3 objects stored on a cloud based system. |
| NOTE: | The public API BaseAttachmentRepository can be used to create your own storage mechanisms. |
Once configured, repositories can be specified in the following ways:
| • | Using the "Attachment Classes and Rules" properties in the Attachment Policy. These rules determine (upon adding or editing an attachment) where the Attachment will be stored as well as any additional manipulation of that Attachment (such as zipping, hashing, or encrypting). These rules are used by the API (SDMS), and for Elements managing multiple file types. These rules are based on either the attachment class, or size of the file. For example, you might want to store raw data file files in a different location than operating procedures and so forth. |
| • | Directly using the Attachment Element. Any Attachments managed by that Element use the defined Repository. Each Element configuration can only reference one Attachment Repository. Multiple repositories would require multiple Element configurations. This approach can be used to override any rules you may have defined in your Attachment Policy. |
Configure an Attachment Repository |
Navigate to System Admin → Configuration → Attachment Repositories. The FileRepository List page displays.
Adding a new attachment repository type to this list will involve writing your own Java class. This requires specialized programming skills. Contact LabVantage Professional Services for help with writing this code. Use of the Delete button is restricted to Repositories that you have created. The three Repositories supplied by LabVantage cannot be deleted. If you have the need to transfer your configuration to another system, use the Export button.
To modify the properties of your Repositories, click the hyperlinked identifier.
| Network File Repository |
The Network File Repository controls how files are stored on a local network (file system based). These network paths will be relative to the machine that is hosting your LabVantage application. Each node of this tree addresses a different scenario. Most scenarios will refer to the “Managed Custom” node. If your Attachment Policy does not specifically address a node of this tree, the “Sapphire Custom” properties are used. For each network path you need to address, you will need to either identify that path in a node of this tree or add a new node of your own. The network path could be local to the application server.
Configure the Network File repository using the following properties:
| Property | Description | |||||||||
| Managed | Whether or not the repository file path is managed by the LIMS application.
|
|||||||||
| Network Path | Specify the desired upload path relative to the application server. This is where LabVantage looks for and saves files. It can be on the local host and may use relative variables like [labvantagehome] | |||||||||
| Upload Renaming |
You can upload multiple files of the same name as different Attachments without overwriting files. Attachments can be automatically renamed such that each file has a unique name after upload. This will happen when using a managed repository. When using an unmanaged repository, specify how (if at all) you would like to rename files on upload. Managed repositories use a renaming format that cannot be altered. If you have "Managed" to "No", this Upload Renaming property is not visible. The Managed renaming pattern is: SDCId_KeyId1_KeyId2_KeyId3_AttachmentNum_AuditSequence.ext where AttachmentNum and AuditSequence are the columns persisted in the SDIAttachment table (KeyId2 and KeyId3 are excluded for single-key SDCs). For unmanaged repositories, you have two options:
|
|||||||||
| Serverside Browsing | Determines whether or not server-side browsing of the server's file
system is allowed.
|
|||||||||
| Local Caching |
When "Yes", each time an Attachment is viewed or downloaded it is cached locally on the application server. If the Attachment is modified, the cache is cleared. If the file is compressed, decompression is performed on the cache, keeping the optimized version available for use. Caching is particularly useful for repositories like AWS and database where there is an overhead to download the file from the external source. However, if the Network file repository is local to the server (stored on the same box), then caching is not recommended as you are getting nothing from it unless the files are zipped. However, if the network store is over a slower connection, then caching may be used to improve performance. The general recommendation is if it is a local file system then disable caching. If not, enable caching. Caching can be switched off globally in the Attachment Policy. This is a safety switch to disable any type of caching. Disabling all caching is recommended only when trying to optimize a system or debug an issue. |
In the Attachment detail, clicking "Upload File" uploads the file and stores it on the server.
The Network File Repository is the default repository if no other repositories are configured.
| Database File Repository |
The Database File Repository controls how files are stored on a database or table. The default Mode will be "Attachment Store". This will place your attachment files into a database table called AttachmentStorge.
Configure the Database File repository using the following properties:
| Property | Description | |||||||||
| Mode | Choose a mode:
|
|||||||||
| Table ID | The name of the table you have created. Example: customattachment. See more details about this example below. | |||||||||
| ID Column | The name of the column you have created in the above custom table for the purposes of having a unique ID. Exampe: attachmentstorageid | |||||||||
| Storage Column | The name of the column that stores the attachment as a BLOB. Example: attachmentstorageblob |
In the Attachment Element, clicking "Upload File" uploads and stores the file in the database.
Example of a Custom Table Database File Repository:
- Create a table. You will need to connect directly to your database as the SCHEMA OWNER to run the below script. The TABLESPACE clause is optional but you might consider creating a tablespace specifically for attachments thereby allowing you to have more control over storage.
CREATE TABLE customattachment TABLESPACE labvantage_attachments
(attachmentstorageid VARCHAR2(40) NOT NULL,
attachmentstorageblob BLOB); - In the LabVantage Database File Repository, select the mode (above) to be "Custom Table".
- Set values as follows:
Table ID: customattachment
ID Column: attachmentstorageid
Storage Column: attachmentstorageblob - Navigate to System Admin Menu > Configuration > Policies > AttachmentPolicy > Sapphire Custom node and set File Repository Id as 'DatabaseFileRepository'.
- Log a sample and add an attachment to it.
- Run the following query on your database:
SELECT attachment, attachmentrepositoryid, externalrepository
FROM sdiattachment WHERE keyid1='<sampleid>';
ATTACHMENT: the column should display 'null'.
ATTACHMENTREPOSITORYID: DatabaseFileRepository
EXTERNALREPOSITORY: <value> - Run another query:
select * from customattachment; - Two columns should get displayed. ATTACHMENTSTORAGEID should match with the value displayed in your SDIATTACHMENT table for EXTERNALREPOSITORY. ATTACHMENTSTORAGEBLOB column should show value as 'BLOB'.
| AWS File Repository |
This File Repository controls how files are stored in AWS S3 cloud storage.
Configure the repository using the following properties:
Refer to Amazon's Simple Storage Service Guide for details.
| Property | Description | ||||||
| Managed | See the description for this property in Network File Repository properties. | ||||||
| Access Key | Provide the access key for AWS. | ||||||
| Secret Access Key | Provide the secret access key for AWS. | ||||||
| AWS bucket region | Identifies the AWS Region hosting servers to which you want to send your requests. This is typically the region closest to your users, but it can be any region. For example, you can type us-west-2 to use US West (Oregon). The Region designators used are the same names that you see in AWS Management Console URLs and service endpoints. | ||||||
| AWS Bucket Name | Identify the bucket in which you want to store the files. | ||||||
| Serverside Browsing | If yes, a browse button is presented allowing a user to choose the directory on AWS into which they will store attachments. | ||||||
| If File Exists | If the repository is unmanaged, specify whether or not you would like to rename files on upload.
|
Plain Text and Rich Text |
"Add Plain Text" lets you enter or paste unformatted text directly against the Attachment without creating a file. A plain text dialog is provided as an editor.
"Add Rich Text" lets you enter or paste formatted text directly against the Attachment without creating a file. The Formatted Text Editor for Attachments is provided.
Note that although these are not saved as files, thay are visible in the Element and attached to the SDI.
|
URL |
"URL"attaches a LabVantage URL or external URL to the SDI. This supports variable substitutions such as [sdcid], [keyid1], [keyid2], [keyid3].
|
Linked Reference |
"Linked Reference" creates a pointer to an Attachment in another SDI. No physical Attachment is added to the current SDI. The pointer can also refer to another Linked Reference for another SDI to provide a multi-level Linked Reference. These Attachments are not editable. Note that actually selecting "Linked Reference" does not let you create a Linked Reference. You must use the "Copy Attachments" property in the Copy-Down Policy to actually create a Linked Reference. After the copy-down, the linked Attachment is deleted if the primary Attachment is deleted.
The Copy-Down Policy can also be used to copy actual Attachments or Linked References between SDIs linked by foreign key. For example, if you attach a data sheet to a Product SDI (ProductId is the primary key column), then create a Sample based on that Product (Sample has the foreign key column to ProductId), the Copy-Down Policy can copy the Attachment from Product to Sample. When you update the Product Attachment, the copied Sample Attachment is updated. This is identified as type "D" in the below table.
Attachment Types in SDIAttachment |
The below descriptions are provided for system administrators. These types are not shown to users through the LabVantage interface. This flag is maintained for backwards compatibility. LabVantage automatically populates this field when users add attachments based on the attachment and its repository. Upgraded systems honor the existing types until an attachment is changed/modified.
The "TypeFlag" columnin the SDIAttachment table identifies the types as follows:
| TypeFlag | Attachment Type | LabVantage 8.5+ | LabVantage 8.4- |
| S | Stored File (Database) | No longer used except for backwards compatibility. This type will now be F or U. | Stored as a BLOB in the database SDIAttachment.Attachment |
| U | Uploaded File (File System) | Attachment file was uploaded from the client and stored in a managed repository. | A file was uploaded and then referenced to that uploaded location with the reference in the FileName column. The full path to the uploaded file is in SDIAttachment.Filename. |
| F | File | The attachment is stored in a managed repository. | The file existed on the server and a direct link to the File using the FileName was created as a pointer to this file. |
| R | Referenced File | Indicates the attachment is a physical file stored in an unmanaged repository. | File stored anywhere in the system and linked by reference using the FileName column. |
| P | Plain Text | An attachment created using the LabVantage plain text editor. Stored as a CLOB in SDIAttachment.AttachmentCLOB. | |
| D | Linked Attachment | A link to an attachment on another SDI which is mostly used in copy down. See Llinked References above. | |
| M | Rich Text | An attachment created using the LabVantage HTML editor which allows text to be marked up for font size, colors and more. | |
| L | URL | An HREF hyperlink to a web page. Stored in the URL column as a CLOB field in SDIAttachment.AttachmentCLOB. | |
Attachment Security |
|
|
The ability to edit an attachment is predicated on the ability to edit an SDI. When viewing an SDI, the ability to control the attachments is already restricted. While in edit mode for an SDI, LabVantage allows you to further restrict who can view, add, edit, lock, unlock, create revisions, promote older revisions to current, and delete. Enabling revisions and revision management as well as releasing other user's locks are controlled by the Attachment Policy. In this section, we address the ability to control view, add, edit, delete, and lock through Departmental security.
Navigate to System Admin > Configuration > SDCs. Edit the SDC to which you plan to add attachment security.
Begin by examining the settings on your Definition Options. Verify that "Allow attachments" is enabled.
Next, examine your Security/Update Options. Verify that "Access Control" is set to: Departmental.
Scroll to the bottom of this page to locate the Operations detail. Add the Operation(s) that you will restrict by Departmental membership.
The ManageAttachment operation will restrict add, edit, delete, and lock operations on attachments for this SDC. This could mean that a person will need to be an owner of the SDI to which this attachment is being made, a member of a Department, or will have unrestricted permissions that you will set in the next step of this configuration.
The ViewAttachment operation will restrict view permissions similarly to the ManageAttachment criteria. This includes the ability to view an attachment, see the thumbnail, and download.
Save all changes. Navigate to System Admin > Security > Job Types. If you are not using Job Types, navigate to Security > Users.
Select the User(s) or Job Type(s) for which you wish to grant access to attachment operations. Click SDC Access.
Complete the grid. Any user or Job Type that is not granted O, M, or W will not be able to perform these operatons on SDIs in these SDCs.
Save all changes. See Departmental Security and SDC Access for more details.
Please see the Attachment Interface help topic for more informaton about adding attachments to LabVantage.