- Document Importer

Document Importer

Introduction

There are times when multiple documents need to be loaded into iPassport and the New Document feature only allows loading one at a time. To make this process more efficient, the Import Documents feature allows loading a number of documents in one operation. Some manual operations are still required to ensure the documents go to the right place, follow their intended lifecycle within iPassport and keep the relevant users informed.

System Preferences

This feature can be switched on or off for the entire account. To make it available, a global setting must be enabled by a user with Administration Editor privileges:

  1. Go to Administration > Settings > System Preferences
  2. Click the row for Miscellaneous Settings to open that page
  3. Tick the checkbox by Enable Document Importer
  4. Scroll down and click Save

Once this is enabled, only users with appropriate permissions will be able to access the feature.

Permissions

To access the Import Documents section, the user requires the same permissions as those for creating a New Document (e.g., SOPs:Create SOPs). To import authorised documents, permissions to authorise documents are additionally required (e.g., SOPs:Authorise SOPs). Note that there are specific permissions for every type of document - Policies:Create Policies, COSHHs:Create COSHHs, Documents:Create Documents, etc. If a user doesn’t have any ‘create’ permissions, they won’t even see the button, Import Documents. If they have ‘create’ permissions but not, ‘authorise’ permissions, they will only be able to import documents in draft state. If they have these permissions for only certain types of documents (e.g., can only create and authorise documents of the type Policy), the button will be visible but it will only be possible to import documents of the allowed type(s).
Furthermore, documents can only be imported to the OUs where the user has the appropriate permissions.

Import Procedure

Uploading Documents

To start the process:

  1. Go to Laboratory Records > Controlled Documents > Import Documents
  2. Load one or multiple documents simultaneously by either:
    • dragging them into the dotted line rectangle at the top of the page (’Click here or drag documents to this space to upload’)
    • or, by clicking inside the rectangle and using the browser window that pops up to find and select them.
  3. Check that for each document uploaded, a line with its name appears in the Import Queue section below, under Source File
    There is a Search tool to locate them as the list grows.
    The Status search filter helps check if any documents are not ready to import yet (more on this filter below).

Editing Fields in Bulk

Once in the staging area, each document will require basic information so that it’s named, classified and filed correctly.

The parameters, OU, Document Type, Category and Section can be set in bulk:
1. Select one or more documents by ticking the checkbox on the left of their row (they can all be selected by ticking the checkbox in the header of the Import Queue section)
2. Click the button, Update Multiple Documents

3. In the lightbox that pops up, click in the fields to expand a dropdown menu; if fields are left blank, any existing information will be left unchanged; if selections are made, they will replace existing ones
4. Click Update

This multiple selection method can also be used to Delete a number of documents from the staging area or to Import them to the account at the end of the process.

When editing more than one document the Section dropdown will populate with locations which are available in the OUs of all the documents selected. If any of the documents doesn't have an Organisational Unit set or no locations are available in all of the selected OUs, then the dropdown will be empty.

Editing Fields Individually

In addition, some parameters can be added or edited on a file by file basis to minimise the amount of work required later, when adjusting the document’s review settings.
Attachments can be uploaded in this window as well.

The parameters that can be adjusted at this stage are:
- Index - the default is, “Auto Generate” but it can be changed by replacing the text with the desired index
- Name - if not edited, the system will use the name of the uploaded file
- Controlled Document State - it is possible to edit the status of a document to draft (default safe option) or authorised; when authorised is selected, three fields automatically appear at the bottom (‘Document Authoriser(s)’, ‘Date Authorised’ and ‘Effective Date’)
- OU - the OU can also be set here
- Controlled Document Type - the Doc Type can also be set here
- Version - the default initial version is based on the system preference, ‘Versioning: doc type’, usually, v1.0
- Document Author(s) - especially important to add if the status is set to authorised
- Document Owner(s) - especially important to add if the status is set to authorised and required if the next review date is added
- Next Review Date - advisable if the status is set to authorised, according to the nature of the document (some don’t need reviewing)
- Category - if categories have been created, they can be assigned here
- Section - more than one section can be added but only the sections which are associated with the document’s OU will be listed; if no OU is selected then the dropdown will be empty

The following fields only show when the document state is set to authorised:
- Document Authoriser(s) - this field is required if the status is set to authorised
- Date Authorised - when left blank, this parameter will auto-populate with the current date if the document is set to authorised; this date can be set in the past if the document had already been authorised outside of iPassport at the time of importing it
- Effective Date - when left blank, this field will match the authorised date; this date can also be set in the past if the document had already been authorised outside of iPassport at the time of importing it

For more information about these parameters and creating controlled documents, please refer to the user guide, Creating a New Draft Controlled Document

To edit the parameters of a specific document in the staging area:

  1. Click inside its row to open a lightbox with all the parameters listed above
  2. Edit the desired parameters by clicking in the appropriate text box (some require entering a value, others have dropdown menus or a calendar; Document Authors, Document Owners, Document Authorisers and Section allow multiple selection by clicking each pertinent row; names/sections can be searched for by entering them (even partially) in the field)
  3. If there are attachments to add,
    3.1. click Choose File under Add Attachment,
    3.2. select the file(s) from the browser search-and-select tool that pops up,
    3.3. click Open (some browsers use a different word) and check the attachments are listed in the Attachments section,
    3.4. click Upload
  4. Click Save to close the lightbox and return to the staging area

Checking the Documents are Ready

The column, Status in the Import Queue section is useful to quickly check if a document is ready for importing. Files with an exclamation mark under, Status are either missing data or have incompatible parameters and need addressing prior to importing. When hovering over the ‘!’ symbol, a message appears with details about which parameters are not ready. Any complete documents will show a thumbs up symbol, indicating they can now be imported.
Sections need to be linked to an OU so they are visible within documents in that OU. Therefore, the system checks the availability of sections added to documents before approving them for import. This check doesn’t cover document review related information, since it can be added after the document is imported (as long as it’s in draft status).

The search filter Status, just above the Import Queue section, allows to isolate those documents that are still requiring information.
Just click the text-box under Status and select either:

  • Staged to bring up all the queued files (ready or not)
  • Ready to only show ones that are ready
  • Not Ready to concentrate on those still lacking fields
  • Imported to see which files have been imported already

Completing the Import

Once one or more documents are ready, they can be imported individually or in bulk by ticking the checkbox on the left of the row of each document. If all documents in the list are ready to import, they can all be selected at once by ticking the checkbox in the header section.
As soon as a selection is made, the header of the Import Queue expands to show the buttons, Update Multiple Documents, Delete and Import.
Click Import to bring up a lightbox that confirms how many documents were imported.
Click, Close and the documents will be cleared from the current Import Queue view.

The Actions column on the right allows deleting, downloading or importing individual files when they are ready.

Import Metadata

It’s also possible to use a CSV file to add or update the metadata for a number of documents in one step. A set of documents can be prepared for import and all the metadata can be entered to a template spreadsheet, obtained by clicking a link.

There are two links - one for a generic sheet that only contains one example row and is already formatted for iPassport to interpret correctly; the other link is for a sheet populated with the metadata already added to any documents sitting in the staged area. Therefore, the documents themselves need to be uploaded to the Import Queue for the Metadata CSV to produce any information. The second option is especially useful to capture the exact name of the file for iPassport to locate it easily.

To download the templates:

  1. Click Import Metadata on the right of the header section of the Import Queue to open the Update Document Metadata CSV window (lightbox)
  2. In this lightbox, click the word, “Here” in the message, “Click Here to download a blank template in a format readable by iPassport.” for an empty template (that only contains an example row)
  3. Alternatively, click the word, “Here” in the message, “Click Here to download a template pre-populated with information from the files in the queue.” for a CSV file with all the existing metadata in the files uploaded to the queue (this also includes an example row)


The fields in the template are the same as those available in the lightbox that opens when you click the row of any queued document. The importer should ignore the example row and empty rows. If any rows in the template correspond to uploaded documents that don’t need any changes in their metadata, they can be deleted or just ignored.

Once a worksheet is populated with the necessary metadata, it needs to be saved/exported in CSV format (ideally, Unicode (UTF-8)). If the system can’t interpret the CSV properly or finds errors in the content (for example, a repeated filename) or missing fields, a message with appropriate feedback will appear.

The steps to follow are:

  1. Upload the documents to the Import Queue
  2. To populate the worksheet, please ensure that,
    • the filename includes the file extension as it appears in the Import Queue
    • the index contains a valid index or the text, “Auto Generate”; if it’s left blank, it will be autogenerated
    • a document title must be entered; it doesn’t have to be the same as the filename but it can’t be blank
    • a state must be declared; either ‘draft’ or ‘authorised’
    • an OU must be declared, using its short name
    • a type must be entered, using the exact terminology - ‘SOP’, ‘Document’, ‘Policy’, ‘COSHH document’, ‘External Document’, ‘Job Description’ or ‘Health and Safety Document’; this is not case sensitive but the spelling has to be correct
    • the version field can be left blank
    • for document owners, authors and authorisers, accurate spelling of the name, as appears in the user’s record is required
    • the authorised date and next review date can be left blank; if populating, check the worksheet settings so that the field is interpreted as a date. The importer will try its best to interpret any dates entered. To avoid confusion, dates should be entered in the format, ‘yyyy-mm-dd’ (NOTE: the format ‘dd-mm-yy’ is most ambiguous and will be read backwards, as ‘yy-mm-dd’).
    • if a category is entered, correct spelling is required but it’s not case sensitive
    • for sections, the short name of the corresponding Location must be used
  3. ‘Save As’ or Export the worksheet in CSV format (Unicode (UTF-8))
  4. Click Import Metadata on the right of the Import Queue header
  5. Insert a CSV file by either,
    • dragging it into the dotted line rectangle at the top of the page (’Click here or drag in metadata .csv file to upload’)
    • or, by clicking inside the rectangle and using the browser window that pops up to find and select it
  6. Check the feedback and if necessary, make any corrections before repeating the last 3 steps above
  7. If all the information is accepted, it will be added to the pertinent queued documents upon clicking Close