nexusLIMS.harvesters package
Handles obtaining a certificate authority bundle from the environment.
Sub-modules include connections to calendar APIs (NEMO and Sharepoint) as well as
a class to represent a Reservation Event
nexusLIMS.harvesters.reservation_event module
A representation of calendar reservations.
This module contains a class to represent calendar reservations and
associated metadata harvest metadata from various calendar sources.
The expectation is that submodules of this module will have a method named
res_event_from_session implemented to handle fetching a ReservationEvent
object from a nexusLIMS.db.session_handler.Session object.
-
class nexusLIMS.harvesters.reservation_event.ReservationEvent(experiment_title: Optional[str] = None, instrument: Optional[Instrument] = None, last_updated: Optional[datetime] = None, username: Optional[str] = None, user_full_name: Optional[str] = None, created_by: Optional[str] = None, created_by_full_name: Optional[str] = None, start_time: Optional[datetime] = None, end_time: Optional[datetime] = None, reservation_type: Optional[str] = None, experiment_purpose: Optional[str] = None, sample_details: Optional[List[Optional[str]]] = None, sample_pid: Optional[List[Optional[str]]] = None, sample_name: Optional[List[Optional[str]]] = None, sample_elements: Optional[List[Optional[List[str]]]] = None, project_name: Optional[List[Optional[str]]] = None, project_id: Optional[List[Optional[str]]] = None, project_ref: Optional[List[Optional[str]]] = None, internal_id: Optional[str] = None, division: Optional[str] = None, group: Optional[str] = None, url: Optional[str] = None)[source]
Bases: object
A representation of a single calendar reservation.
The representation is independent of the type of calendar the reservation was
made with. ReservationEvent is a common interface that is used by the record
building code.
Any attribute can be None to indicate it was not present or no value was
provided. The as_xml() method is used to serialize the information
contained within a ReservationEvent into an XML representation that is
compatible with the Nexus Facility Experiment schema.
-
experiment_title
The title of the event
-
instrument
The instrument associated with this reservation
-
last_updated
The time this event was last updated
- Type
datetime
-
username
The username of the user indicated in this event
-
user_full_name
The full name of the user for this event
-
created_by
The username of the user that created this event
-
created_by_full_name
The full name of the user that created this event
-
start_time
The time this event was scheduled to start
-
end_time
The time this event was scheduled to end
-
reservation_type
The “type” or category of this event (such as User session, service,
etc.))
-
experiment_purpose
The user-entered purpose of this experiment
-
sample_details
A list of the user-entered sample details for this experiment. The
length of the list must match that given in sample_pid and
sample_name.
-
sample_pid
A list of sample PIDs provided by the user. The
length of the list must match that given in sample_details and
sample_name.
-
sample_name
A list of user-friendly sample names (not a PID). The
length of the list must match that given in sample_details and
sample_pid.
-
project_name
A list of the user-entered project names for this experiment. The
length of the list must match that given in project_id and
project_ref.
-
project_id
A list of the specific project IDs within a research group/division. The
length of the list must match that given in project_name and
project_ref.
-
project_ref
A list of (optional) links to this project in another database. The
length of the list must match that given in project_name and
project_id.
-
internal_id
The identifier assigned to this event (if any) by the calendaring system
-
division
An identifier of the division this experiment was performed for (i.e.
the user’s division)
-
group
An identifier of the group this experiment was performed for (i.e.
the user’s group)
-
url
A web-accessible link to a summary of this reservation
-
as_xml() → Element[source]
Get an XML representation of this ReservationEvent.
- Returns
root – The reservation event serialized as XML that matches the
Nexus Experiment schema
- Return type
Element
nexusLIMS.harvesters.sharepoint_calendar module
Communicate with a SharePoint calendar system used for instrument reservations.
Note, due to changes in NIST’s instrument configurations, the SharePoint
harvester has been deprecated as of March 2022. It _should_ continue to
work with versions of SharePoint up to 2019. It does not work with
“SharePoint in Microsoft 365” due to that platform’s lack of support for
NTLM authentication. This file is left in place for backwards compatibility,
but is no longer actively developed nor tested (since it requires a working
2019 SP - or older - server, which we do not have readily available).
-
nexusLIMS.harvesters.sharepoint_calendar.dump_calendars(instrument=None, dt_from=None, dt_to=None, filename: Optional[Path] = None)[source]
Write the results of get_events() to a file.
- Parameters
instrument (Instrument or str) – One of the NexusLIMS instruments contained in the
instrument_db database.
Controls what instrument calendar is used to get events. If value is
a string, it should be one of the instrument PIDs from the Nexus
facility
dt_from (datetime or None) – A datetime object representing the start of a
calendar event to search for, as in fetch_xml().
If dt_from and dt_to are None, no date filtering will be done.
If just dt_from is None, all events from the beginning of the
calendar record will be returned up until dt_to.
dt_to (datetime or None) – A datetime object representing the end of
calendar event to search for, as in fetch_xml().
If dt_from and dt_to are None, no date filtering will be done.
If just dt_to is None, all events from the dt_from to the
present will be returned.
filename (str) – The filename to which the events should be written
-
nexusLIMS.harvesters.sharepoint_calendar.fetch_xml(instrument, dt_from=None, dt_to=None)[source]
Get the XML from the Nexus Sharepoint calendar for one or more instruments.
- Parameters
instrument (Instrument) – As defined in get_events(),
one of the NexusLIMS instruments contained in the
instrument_db database.
Controls what instrument calendar is used to get events
dt_from (datetime or None) – A datetime object representing the start of a
calendar event to search for.
If dt_from and dt_to are None, no date filtering will be done.
If just dt_from is None, all events from the beginning of the
calendar record will be returned up until dt_to.
dt_to (datetime or None) – A datetime object representing the end of
calendar event to search for.
If dt_from and dt_to are None, no date filtering will be done.
If just dt_to is None, all events from the dt_from to the
present will be returned.
- Returns
api_response – A string containing the XML calendar information for each
instrument requested, stripped of the empty default namespace. If
dt_from and dt_to are provided, it will contain just one
“entry” representing a single event on the calendar
- Return type
str
Notes
To find the right event, an API request to the Sharepoint Calendar will
be made for all events starting on the same day as dt_from. This
could result in multiple events being returned if there is more than one
session scheduled on that microscope for that day. To find the right one,
the timespan between each event’s StartTime and EndTime returned
from the calendar will be compared with the timespan between dt_from and
dt_to. The event with the greatest overlap will be taken as the
correct one. This approach should allow for some flexibility in terms of
non-exact matching between the reserved timespans and those recorded by
the session logger.
-
nexusLIMS.harvesters.sharepoint_calendar.get_events(instrument=None, dt_from=None, dt_to=None)[source]
Get calendar events for an instrument on some date, or by some user.
- Parameters
instrument (Instrument or str) – One of the NexusLIMS instruments contained in the
instrument_db database.
Controls what instrument calendar is used to get events. If string,
value should be one of the instrument PIDs from the Nexus facility.
dt_from (datetime or None) – A datetime object representing the start of a
calendar event to search for, as in fetch_xml().
If dt_from and dt_to are None, no date filtering will be done.
If just dt_from is None, all events from the beginning of the
calendar record will be returned up until dt_to.
dt_to (datetime or None) – A datetime object representing the end of
calendar event to search for, as in fetch_xml().
If dt_from and dt_to are None, no date filtering will be done.
If just dt_to is None, all events from the dt_from to the
present will be returned.
- Returns
res_event – A ReservationEvent, containing information about a
single reservation, including title, instrument, user information,
reservation purpose, sample details, description, and date/time
information.
- Return type
ReservationEvent
-
nexusLIMS.harvesters.sharepoint_calendar.res_event_from_session(session: Session) → ReservationEvent[source]
Given a Session object, return a ReservationEvent that matches its attributes.
-
nexusLIMS.harvesters.sharepoint_calendar.res_event_from_xml(xml, date=None)[source]
Create a reservation event from Sharepoint XML.
Creates a ReservationEvent
from an xml response from fetch_xml() rather than providing values
directly. If there are multiple events in the XML, it will only process the first
one.
- Parameters
xml (str) – Output of an API query to the Sharepoint calendar that contains a
single event (which should be the case if start and end times were
provided to fetch_xml())
date (None or datetime) – (Optional) a date to use in serializing the output in case there is
no date information in the XML response (i.e. there were no
reservations found for the date range searched)
Notes
Each attribute of the resulting ReservationEvent is mapped to a node
in the XML API response, and will be None if the node cannot be found in
the XML. Timestamps are given in either Zulu time (UTC) or with a
local timestamp offset, so datetime attributes should be timezone-aware.
Mapping of attributes:
experiment_title - present at
/feed/entry/content/m:properties/d:TitleOfExperiment
instrument - fetched using the name of the calendar, present at
/feed/title
last_updated - present at /feed/entry/updated
username - present at
/feed/entry/link[@title="UserName"]/m:inline/feed/entry/content/m:properties/d:UserName
created_by - present at
/feed/entry/link[@title="CreatedBy"]/m:inline/feed/entry/content/m:properties/d:UserName
start_time - /feed/entry/content/m:properties/d:StartTime (The API
response returns this value without a timezone, in the timezone of the
sharepoint server
end_time - present at /feed/entry/content/m:properties/d:EndTime
reservation_type - /feed/entry/content/m:properties/d:CategoryValue
experiment_purpose - present at
/feed/entry/content/m:properties/d:ExperimentPurpose
sample_details - present at
/feed/entry/content/m:properties/d:SampleDetails
sample_pid - not collected by the SharePoint form at this time
project_id - a non-persistent identifier string
present at /feed/entry/content/m:properties/d:ProjectID
internal_id - present at /feed/entry/content/m:properties/d:Id
- Returns
res_event – An object representing an entry on the SharePoint calendar. Could
be empty if no entry nodes are present in XML response
- Return type
ReservationEvent
