Managing Services

Service Configuration Overview

Types

The resource system supports 3 general types of services:

Blue services can only be configured/created by a system administrator.

  1. Scheduled - Services that have a start time and ending time for each use.
    1. Per Hour - Services that charge based on the duration of use
    2. Per Run - Services that charge the same amount per use regardless of duration
  2. Line Item - Services that have a quantity and price per unit
    1. Line Item - A blank line item form that allows the submitter to specify all aspects of the order (Rates, Quantity, Descriptions). Note: Line Item services are forced to be "Manager Only" by system convention.
    2. Order Form Template - A pre-filled line item form that allows the submitter to specify just the desired quantities with all other information provided as a fixed submission.
    3. Genome Processing - A Sanger Genome Sequencing specialized BBSP variant. (highly customized submission system. Works with an outside processing script to provide quick-turn around file delivery of 96-Well Sanger Robotics results. Generates Line Item orders.
    4. Black Box Sample Processing (BBSP) - A generalized sample processing / submission system that includes file storage. Generates Line Item orders.
    5. Mass Spectrometry Sample Processing (MSSP) - A Mass Spectrometry specialized BBSP variant that generates line item orders.
    6. FASTA Sample Processing (FASTA) - A DNA Sequencing specialized BBSP variant that generates line item orders.
  3. Data Collection/Other - Services that do not have a price but are instead for collecting data
    1. Custom - Links to a custom subsystem or ordering form. (Requires developer involvement)
    2. Link - A hyperlink to a fixed or outside page. Primarily used for linking to training or other informational documents
    3. Data Form Template - A configurable data collection form. Does not generate an order/charge.
  4. Walkup - A cousin of the scheduled service, walkup services are services that record usage in real time and create a charge event based on the start and end times.

All service types except data collection services will generate an order record with associated events (scheduled) and line items. Services can be configured to automatically exclude created orders from the billing process if the services are provided for free.

Scheduled Service Configuration

Scheduled services for the resource system represent an order for services that are intended to take place on a specific instrument at a given time. Schedules services may be configured to have as many selectable rates as desired. Configuration of a scheduled service is broken down into a number of sections identified below.

Creating a new service

A new service can be created by clicking the "Create New Service" button located above the service list search box

ServiceConfig-CreateButton.png

Newly created services will not exist until saved after initial configuration. This means that some functionality that needs an id number such as creating service rates will not be available until the user click the "Save" button to save a newly created service.

ServiceConfig-NewRecord.png

Identifiers

ServiceConfig-Identifiers.png

Visuals

ServiceConfig-Visuals.png

Contact Information

ServiceConfig-Contacts.png

General Config

ServiceConfig-General.png

Tags

ServiceConfig-Tags.png

Tag strings used by the system for categorization and certain actions. No special tags are defined for services at this time.

Scheduler Config

ServiceConfig-Scheduled.png

Blocked/Off-Hours Times

ServiceConfig-BlockedTimes.png

This section controls what times during the week are treated as Off or Blocked hours during which altered rates may be applied or access may be blocked entirely. Time formats are in 24 hour formats. Defaults to no limits. Common times are 00:00 - 09:00 and 17:00 - 24:00 to give a 9am to 5pm working day.

Custom Data Config

ServiceConfig-DataConfig.png

ServiceConfig-DataConfigDetail.png

Some services may require additional information to perform. Up to 5 custom data fields may be enabled for the scheduling user to enter custom information. These custom fields will appear as text input boxes at the bottom of the event details with the provided data label/query.

Custom Data Field Label Config

Custom data fields may also be marked as required and/or displayed as a dropdown selection list using the following configurations in the Data Label field

<data_label_text>::required::<comma_separated_list_of_options> - Required Option Dropdown

<data_label_text>::required - Required Text Field

<data_label_text>::<comma_separated_list_of_options> - Optional Option Dropdown

Example Config

image-1684508885829.png

image-1684508939224.png

Service Rate Config

ServiceRatesUpdated.png

Each service can have as many rates as desired. Users will have the option to select these rates in a dropdown when scheduling. Rates for scheduled events have 7 needed configuration options:

  1. Rate Name - The name displayed in the rate dropdown.
  2. Type - The type of the rate charge
    • Per Hour - Charge based on the length of the event in question split correspondingly over the on and off hours used
    • Per Run - Charge a flat fee for the event regardless of duration
  3. On Hours Rate  - The rate to charge at for usage that occurs during On Hours as defined in the "Blocked/Off-Hours" configuration section. This rate should be the "At Cost" internal charge rate.
  4. Off Hours Rate  - The rate to charge at for usage that occurs during Off Hours as defined in the "Blocked/Off-Hours" configuration section. This rate should be the "At Cost" internal charge rate.
  5. Commercial On Hours Rate  - The rate to charge at for usage that occurs during On Hours as defined in the "Blocked/Off-Hours" configuration section. This rate can be any rate but should be no less than the internal cost.
  6. Commercial Off Hours Rate  - The rate to charge at for usage that occurs during Off Hours as defined in the "Blocked/Off-Hours" configuration section. This rate can be any rate but should be no less than the internal cost.
  7. Display Color - The color that any event scheduled at this rate should be appear as when viewed on the calendar. Accepts any valid CSS color string. Can be blank.

All config fields MUST be filled out except the display color regardless of whether you expect to be handling commercial orders on the service. Since users are responsible for selecting their own accounts you cannot control which type of account might be selected for charging the order. If you do not have commercial rates for your services using 2x the internal rate is a safe choice. All fields must ALSO be filled out if you are doing "Per Run" rates.

Service Rate Permissions

Service Rates can be restricted to group managers only. Click on the lock icon and check the "Manager Only" box

ServiceRatePermission.png

Rates marked as such will appear to users as disabled.

DisabledServicRate.png

Service Auto-Charges / Fees Config

Each service can also be configured to automatically attach separate fees for service (apart from the hourly charge) to events created. These charges will be attached at the time that the event is created and can be either Fixed Fees or Duration Linked. In both cases the line item description will be the information provided in the "Fee Description" field.

EventServiceFee.png

  1. Fixed Fee - Fixed Fees are attached to the order as a line item and will remain the same regardless of event duration. This can be used to apply setup fees or other one time charges.
  2. Duration Linked - Duration linked fees are applied to events on the basis of their total duration. The charge will be equal to the Rate * Rate Multiplier * Total Event Duration in hours. This can be used to attach charges for consumables usage.

Line Item Service Configuration

Line Item services for the resource system represent an order for services that have an item quantity and price per item. Generally this means that any service that is not a scheduled service is treated as a line item service. Configuration of a line item service is broken down into a number of sections identified below. Line Item services share most of their configuration with scheduled services.

Creating a new service

A new service can be created by clicking the "Create New Service" button located above the service list search box

ServiceConfig-CreateButton.png

Newly created services will not exist until saved after initial configuration. This means that some functionality that needs an id number such as creating service rates will not be available until the user click the "Save" button to save a newly created service.

ServiceConfig-NewRecord.png

Identifiers

ServiceConfig-Identifiers.png

Visuals

ServiceConfig-Visuals.png

Contact Information

ServiceConfig-Contacts.png

General Config

ServiceConfig-General.png

Tags

ServiceConfig-Tags.png

Tag strings used by the system for categorization and certain actions. No special tags are defined for services at this time.

Custom Data Config

ServiceConfig-DataConfig.png

ServiceConfig-LineItemDataField.png

Some services may require additional information to perform. Up to 5 custom data fields may be enabled for the ordring user to enter custom information. These custom fields will appear as text input boxes at the bottom of the line details with the provided data label/query.

Service Presets

ServiceConfig-LineItemPresetConfig.png

Line item services have presets instead of rates. These presets serve a variety of purposes depending on the the type of service. For "Line Item" and "Order Form" type services the line presets serve as pre-filled lines. The only difference between a "Line Item"  and "Order Form" service is that "Line Item" services allow ordering users to add manual lines to the order. Line item services can have zero or more presets. Generally "Line Item" type services will have no presets and serve as a manager only order form. Service presets have 7 configuration fields of which the first 4 are required:

  1. Label - The Description to be attached to this line item
  2. Type - The line preset type
    • Per Item - A fully configurable/removable line item
      ServiceConfig-LineItemPresetFullyEditable.png
    • Per Item (Required - Editable) - A order form line item with a alterable quantity
      ServiceConfig-LineItemPresetPartiallyEditable.png
    • Per Item (Required - Fixed) - An uneditable "fee" style line item
      ServiceConfig-LineItemPresetFixed.png
  3. Per Item Rate - The cost per item to default to or enforce
  4. Commercial Rate - The cost per item to default to or enforce for commercial accounts
  5. Minimum Quantity - The smallest number of this item the user can select. (Serves as the default field value, only enforced on (Required) preset types)
  6. Maximum Quantity - The largest number of this item the user can order. Defaults to 0 where 0 allows unlimited quantities. (Only enforced on (Required) preset types for values above 0)
  7. Conditional Fee - Used by the BBSP and other Sample Processing service types. No effect for general line item services.

Order Form Service Configuration

Line Item services for the resource system represent an order for services that have an item quantity and price per item. Generally this means that any service that is not a scheduled service is treated as a line item service. Configuration of a line item service is broken down into a number of sections identified below. Line Item services share most of their configuration with scheduled services.

Creating a new service

A new service can be created by clicking the "Create New Service" button located above the service list search box

ServiceConfig-CreateButton.png

Newly created services will not exist until saved after initial configuration. This means that some functionality that needs an id number such as creating service rates will not be available until the user click the "Save" button to save a newly created service.

ServiceConfig-NewRecord.png

Identifiers

ServiceConfig-Identifiers.png

Visuals

ServiceConfig-Visuals.png

Contact Information

ServiceConfig-Contacts.png

General Config

ServiceConfig-General.png

Tags

ServiceConfig-Tags.png

Tag strings used by the system for categorization and certain actions. No special tags are defined for services at this time.

Custom Data Config

ServiceConfig-DataConfig.png

ServiceConfig-LineItemDataField.png

Some services may require additional information to perform. Up to 5 custom data fields may be enabled for the ordring user to enter custom information. These custom fields will appear as text input boxes at the bottom of the line details with the provided data label/query.

Service Presets

ServiceConfig-LineItemPresetConfig.png

Line item services have presets instead of rates. These presets serve a variety of purposes depending on the the type of service. For "Line Item" and "Order Form" type services the line presets serve as pre-filled lines. The only difference between a "Line Item"  and "Order Form" service is that "Line Item" services allow ordering users to add manual lines to the order. Line item services can have zero or more presets. Generally "Line Item" type services will have no presets and serve as a manager only order form. Service presets have 7 configuration fields of which the first 4 are required:

  1. Label - The Description to be attached to this line item
  2. Type - The line preset type
    • Per Item - A fully configurable/removable line item
      ServiceConfig-LineItemPresetFullyEditable.png
    • Per Item (Required - Editable) - A order form line item with a alterable quantity
      ServiceConfig-LineItemPresetPartiallyEditable.png
    • Per Item (Required - Fixed) - An uneditable "fee" style line item
      ServiceConfig-LineItemPresetFixed.png
  3. Per Item Rate - The cost per item to default to or enforce
  4. Commercial Rate - The cost per item to default to or enforce for commercial accounts
  5. Minimum Quantity - The smallest number of this item the user can select. (Serves as the default field value, only enforced on (Required) preset types)
  6. Maximum Quantity - The largest number of this item the user can order. Defaults to 0 where 0 allows unlimited quantities. (Only enforced on (Required) preset types for values above 0)
  7. Conditional Fee - Used by the BBSP and other Sample Processing service types. No effect for general line item services.

Black Box Sample Processing Service Config

Black Box Sample Processing (BBSP) services for the resource system represent an order for services that have an item quantity and price per item. BBSP Services also include limited sample configuration and data storage ability.

Creating a new service

A new service can be created by clicking the "Create New Service" button located above the service list search box

ServiceConfig-CreateButton.png

Newly created services will not exist until saved after initial configuration. This means that some functionality that needs an id number such as creating service rates will not be available until the user click the "Save" button to save a newly created service.

ServiceConfig-NewRecord.png

Identifiers

ServiceConfig-Identifiers.png

Visuals

ServiceConfig-Visuals.png

Contact Information

ServiceConfig-Contacts.png

General Config

ServiceConfig-General.png

Tags

ServiceConfig-Tags.png

Tag strings used by the system for categorization and certain actions. No special tags are defined for services at this time.

Custom Data Config

ServiceConfig-DataConfig.png

ServiceConfig-LineItemDataField.png

Some services may require additional information to perform. Up to 5 custom data fields may be enabled for the ordring user to enter custom information. These custom fields will appear as text input boxes at the bottom of the line details with the provided data label/query.

Service Presets

Service presets for the BBSP system function as 

ServiceConfig-BBSPPresetConfig.png

  1. Process Type - The name of the process to be selected. Users will be able to select among the provided presets.
  2. Type - Whether the preset should be treated as a required fee or as a process to be performed on samples
    • Process - Charge Per Sample
    • Unused (1) - Can be selected if service is converted from another service type
    • Unused (2) - Can be selected if service is converted from another service type
  3. $/Sample - The rate to charge per sample
  4. $/Sample (Commercial) - The rate to charge per sample
  5. Min Sample # - The minimum number of samples a user needs to submit to be able to select this process
  6. Maximum Quantity - The maximum number of samples a user can to submit to be able to select this process

Data Collection Form Config

Black Box Sample Processing (BBSP) services for the resource system represent an order for services that have an item quantity and price per item. BBSP Services also include limited sample configuration and data storage ability.

Creating a new service

A new service can be created by clicking the "Create New Service" button located above the service list search box

ServiceConfig-CreateButton.png

Newly created services will not exist until saved after initial configuration. This means that some functionality that needs an id number such as creating service rates will not be available until the user click the "Save" button to save a newly created service.

ServiceConfig-NewRecord.png

Identifiers

ServiceConfig-Identifiers.png

Visuals

ServiceConfig-Visuals.png

Contact Information

ServiceConfig-Contacts.png

General Config

ServiceConfig-General.png

Tags

ServiceConfig-Tags.png

Tag strings used by the system for categorization and certain actions. No special tags are defined for services at this time.

Form Configuration Manager

Custom data collection forms can be configured to collect any desired data including digital signatures from submitters.

ServiceConfig-DataFormConfig.png

  1. Title - The title of the form
  2. Allow Editing
    1. Yes (all) - Allow users to edit form submissions after submission
    2. Yes (Recieved Only) - Allow users to edit form submission as long as they are in the "Received" state
    3. No - Disallow form editing after submission
  3. Current Fields - Control and edit the forms for this data collection form

ServiceConfig-DataFormFieldConfig.png

  1. Label Field - Used to set the name of the field
  2. Data Key Field - Defines the name of the storage variable. Should be unique across all fields
  3. Field Type Selector
    • Markdown Block - Display a markdown formatted section of text
    • Text Field - Single Line Text Field
    • Text Area - Multi-line text field
    • Number - Floating point number field
    • Select - Single Item select
    • Multi-Select - multiple item select
    • Section Divider - Section Divider with or without  title
    • Signature Block - Email target for signature request
  4. Field Details/Config Button - Displays field type configurations
    • Markdown Block 
      DataFieldConfig - Markdown.png
    • Text Field - Single Line Text Field
    • Text Area - Multi-line text field
    • Number - Floating point number field
      DataFieldConfig - Text.png
    • Select - Single Item select
    • Multi-Select - multiple item select
      DataFieldConfig - Select.png
    • Section Divider - Section Divider with or without  title
    • Signature Block - Email target for signature request
  5. Move Field Up - Alters display position of field
  6. Move Field Down - Alters display position of field
  7. Copy Field Button
  8. Remove Field Button

Webhook / Interlock Configuration

Overview

Occasionally it can be desirable to trigger remote actions in response to actions that occur in the resource system. Use cases include remote logging or instrument interlock control. To support these remote actions the resource system provides HTTP webhooks for the following actions:

Using the Service Webhook Manager facility staff can configure single or multiple webhooks to be triggered when any of the above events occur. 

ServiceWebhookManager.png

Configurations can be specified for HTTP Headers, HTTP Auth, request HTTP Verb/Type and request body data.

Note: all request bodies will be encoded as "application/json"

HTTP Verb/Type settings can be set to standard or "insecure". Insecure requests will ignore all TLS certificate errors and are not recommended.

Payload

By default the payload for requests will include the following in the request body: 

Any additional data elements as configured by the webhook settings will be attached to the data object.

Data keyed with the same key as any of the above will be OVERWRITTEN by the system provided value

Multiple Webhooks

Multiple webhooks on the same event can be configured. Order of execution is NOT guaranteed.

Interlock Configuration

Interlocks are a special use case for webhooks. Scheduled instruments/services can be configured to display an interlock control UI element by attaching the has_interlock tag to the service in question under the "Service Tags" configuration using the "Manual Tag Wizard"

HasInterlocksSTW.png

After event creation / during event viewing services with this tag will display a set of interlock controls

EventInterlockControls.png

Facility Staff and System Administrators will see interlock controls at all times and on all events. Instrument Users will only see the interlock controls between 5 minutes before the scheduled start of the event and 30 minutes after the scheduled end of the event.

The 3 actions correspond to the "interlock" action type and subtype.

InterlockWebhook.png

The lock and unlock actions are "push-only" webhooks. Any response traffic to these calls is discarded. Valid HTTP Error codes will generate an error message with the reason for the error displayed.

The "Query Lock Status" action will parse the response from the target and expects an "application/json" body with a "status" key containing either a "locked" or "unlocked" value.

Walkup Service Configuration

For services that are publicly accessible and do not need to be scheduled in advance the resource system supports "Walkup" events. Rather than creating a reservation event these services create a timed record of use. The system creates a "pending" walkup event at the time that use is started and closes out the the event when use is completed by creating an event and order based on the walkup event duration. It is important to note that walkup events do NOT check for collisions when they are created and so overlapping usages can occur.

Unlike scheduled services, Walkup service events cannot be edited after creation. While there is a calendar view for the events this is primarily for user convenience and events cannot be altered from the calendar.

Creating a new service

A new walkup service can be created by clicking the "Create New Service" button located above the service list search box. Walkup services are functionally identical to a scheduled service from a configuration standpoint. 

WalkupService.png

Newly created services will not exist until saved after initial configuration. This means that some functionality that needs an id number such as creating service rates will not be available until the user click the "Save" button to save a newly created service.

ServiceConfig-NewRecord.png

Identifiers

ServiceConfig-Identifiers.png

Visuals

ServiceConfig-Visuals.png

Contact Information

ServiceConfig-Contacts.png

The contact email configuration does NOT override the general "Notification Verbosity" setting for the service. If a service is configured to suppress all notification messages then no emails will be sent regardless of the contact email configuration

General Config

ServiceConfig-General.png

Tags

ServiceConfig-Tags.png

Tag strings used by the system for categorization and certain actions. No special tags are defined for services at this time.

Scheduler Config

ServiceConfig-Scheduled.png

Blocked/Off-Hours Times

ServiceConfig-BlockedTimes.png

This section controls what times during the week are treated as Off or Blocked hours during which altered rates may be applied or access may be blocked entirely. Time formats are in 24 hour formats. Defaults to no limits. Common times are 00:00 - 09:00 and 17:00 - 24:00 to give a 9am to 5pm working day.

Custom Data Config

This config section has no effect on Walkup Services

Service Rate Config

ServiceConfig-ScheduledRates.png

Each service can have as many rates as desired. Users will have the option to select these rates in a dropdown when scheduling. Rates for scheduled events have 7 needed configuration options:

  1. Rate Name - The name displayed in the rate dropdown.
  2. Type - The type of the rate charge
    • Per Hour - Charge based on the length of the event in question split correspondingly over the on and off hours used
    • Per Run - Charge a flat fee for the event regardless of duration
  3. On Hours Rate  - The rate to charge at for usage that occurs during On Hours as defined in the "Blocked/Off-Hours" configuration section. This rate should be the "At Cost" internal charge rate.
  4. Off Hours Rate  - The rate to charge at for usage that occurs during Off Hours as defined in the "Blocked/Off-Hours" configuration section. This rate should be the "At Cost" internal charge rate.
  5. Commercial On Hours Rate  - The rate to charge at for usage that occurs during On Hours as defined in the "Blocked/Off-Hours" configuration section. This rate can be any rate but should be no less than the internal cost.
  6. Commercial Off Hours Rate  - The rate to charge at for usage that occurs during Off Hours as defined in the "Blocked/Off-Hours" configuration section. This rate can be any rate but should be no less than the internal cost.
  7. Display Color - The color that any event scheduled at this rate should be appear as when viewed on the calendar. Accepts any valid CSS color string. Can be blank.

All config fields MUST be filled out except the display color regardless of whether you expect to be handling commercial orders on the service. Since users are responsible for selecting their own accounts you cannot control which type of account might be selected for charging the order. If you do not have commercial rates for your services using 2x the internal rate is a safe choice. All fields must ALSO be filled out if you are doing "Per Run" rates.

Service Auto-Charges / Fees Config

Each service can also be configured to automatically attach separate fees for service (apart from the hourly charge) to events created. These charges will be attached at the time that the event is created and can be either Fixed Fees or Duration Linked. In both cases the line item description will be the information provided in the "Fee Description" field.

EventServiceFee.png

  1. Fixed Fee - Fixed Fees are attached to the order as a line item and will remain the same regardless of event duration. This can be used to apply setup fees or other one time charges.
  2. Duration Linked - Duration linked fees are applied to events on the basis of their total duration. The charge will be equal to the Rate * Rate Multiplier * Total Event Duration in hours. This can be used to attach charges for consumables usage.