History API Reference

A detailed history of events is recorded for Enterprise Sequence Hub users, workgroups, and domains. The events are available as feeds on an HTTP service.

Retrieving a history feed

  1. Create a GET request with the following endpoint: https://api.basespace.illumina.com/v1pre3/users/current.
    1. To retrieve the history feed for a user or workgroup, use the 'HrefHistory' field value. This field will only appear for enterprise users in a private domain.
    2. To retrieve the history feed for domain, use the 'HrefHistoryDomain' field value. This field will only appear domain administrators.
  2. Obtain an access token to authenticate your request to view history.
    1. You can use the BaseSpaceCLI to easily create tokens. For example, 'bs authenticate --scopes "AUDIT USER"' or 'bs authenticate --scopes "AUDIT DOMAIN"'.
    2. The token must have AUDIT USER permission to view user or workgroup history feeds.
    3. The token must have AUDIT DOMAIN permission to view a domain history feed.
  3. Create a GET request with the history Href from step 1.
    1. Authenticate your request by including 'Authorization = Bearer XYZ' in the header, where XYZ is an access token.
    2. The following query parameters are optional:
      • SortDir - sort direction; possible values: Desc (default, recent events listed first), 'Asc'
      • Limit - page size; possible values: 1-1000; default 10 events per API response
      • After - page index; eg. 13105947299000401
    3. The resulting JSON response will contain a paged list of events.

The history API's paging supports consistency across all events and pages in a feed. This enables reliable downloading all events in a feed across pages, even when new events have arrived in between queries.

BaseSpaceCLI also has a command-line tool, 'bs history', to call the history API and return the response in CSV format.

Example:

{
    "Items": [ /* collection of events */
        {
            "Id": "bca5277e-4a24-4bf2-a7db-3f16660c85b3_Project_1197200", /* unique id for this event instance */
            "DateCreated": "2016-06-17T22:02:30.4328909Z", /* date and time event took place */
            "ResourceType": "Project", /* associated resource of event */
            "ResourceId": "1197200", /* id of associated resource */
            "ActingUserId": "3003", /* id of acting user (could be different than LoggedInUserId) */
            "LoggedInUserId": "3003", /* id of logged-in/authenticated user */
            "IpAddress": "127.0.0.1", /* ip address of user's network request */
            "EventType": "Update", /* type of event, i.e. action on resource */
            "FieldChanges": { /* collection of affected changes */
                "description": { /* (example) affected resource field name */
                    "OldValue": "My project descrption with a typo", /* value before event */
                    "NewValue": "My project description without a typo" /* value after event */
                }
            },
            "Metadata": { /* collection of unaffected but related resource field name and values */
                "name": "MyProject" /* (example) field name and value */
            }
        }
    ],
    "Paging": { /* paging information */
        "TotalCount": 1, /* total count of items in data store */
        "DisplayedCount": 1, /* count of items in this response */
        "Limit": 10, /* page item count */
        "SortBy": "DateCreated", /* sorting field */
        "SortDir": "desc", /* sorting direction */
        "After": "14594550263483129", /* next sort key */
        "Before": "14594744179923375" /* before sort key */
    }
}

Response Elements

Below is a listing of possible ResourceTypes in history feeds and descriptions of their fields.

Lane:

  • Run: Associated Run (ID)
  • LaneNumber: Number of lane
  • Status: Status of the Lane; possible values are Initial, QcPassed, QcFailed, PendingQc
  • LibraryPool: The Pool (ID) that was contained in the Lane.

AppResult:

  • Name: Name of AppResult
  • Description: Description of AppResults
  • AppSession: AppSession (ID) that generated the AppResult
  • OwnerUser: Owner (User ID) of AppResult
  • StorageStatus: (OnSite only) Example values are 'Online', 'OnlineArchiving', 'OfflineArchived', 'ActiveOnlineArchived'
  • DataStatus: Deletion or archive status. Examples: TRASH, ARCHIVE (OnSite only), OKTOPURGE (emptied from trash)

ApiOAuthV2Token:

  • ApiApplication: Associated App (ID)
  • ResourceOwnerUser: Associated User (ID)
  • Scope: The token's scope, eg., GLOBAL BROWSE
  • AccessTokenIssuedOn: Date/Time of creation
  • AccessTokenDisabled: True if token is invalidated/deleted
  • AccessTokenDisabledOn: Date/Time of invalidation/deletion
  • AccessTokenDisabledReason: System generated reasons for invalidation/deletion; examples: 'Automatic re-launch of app...', 'User requested ...'
  • UserAction: Possible needed user action. Examples: UNDEFINED, PENDING, GRANTED, DENIED, ERRORED

Project:

  • Name: Name of project.
  • Description: Description of project.
  • OwnerUser: Owner (User ID) of the project.
  • DataStatus: Deletion or archive status. Examples: TRASH, ARCHIVE (OnSite only), OKTOPURGE (emptied from trash)

Invite:

An Invite is created when a user invites another user to receive access to a resource via sharing or transfer. Once the Invite is accepted a Grant is created, which grants the receiving user access to the resource.

  • InviteStatus: The status of the Invite. Examples: Pending, Accepted, Declined, Canceled
  • Run: The Run (ID) that is the subject of the Invite.
  • Project: Information about project (ID) that is shared.
  • InvitedUser: User (ID) with whom resource is being invited
  • InvitedEmail: Email address of user with whom resource is invited
  • Note: Any additional information the inviting user wants to send to the invited user
  • IsMultiUser: Is true for Share By Link
  • PermissionFlags: Permissions granted to invited user. Examples: BROWSE, READ, CREATE, WRITE

Grant:

Permissions that are granted to a user or application for a particular resource. Grants are created when resources are shared or transferred. They are also created when a user grants an application access to data, such as when launching an app.

  • User: User (ID) whose permissions are added or updated
  • OAuthV2Token: Token (ID) used in grant process, if the grant is to an application
  • Run: The Run (ID) that is the resource of the grant
  • Sample: The Sample (ID) that is the resource of the grant
  • AnalysisResults: The Appresult (ID) that is the resource of the grant
  • Dataset: The Dataset (ID) that is the resource of the grant
  • Project: The Project (ID) that is the resource of the grant
  • PermissionFlags: Permission granted to user
  • IsActive: True if this grant is currently valid
  • DisabledByUser: User (ID) information who disabled this Grant
  • DisableDate: When was the grant disabled
  • Invite: The Invite (ID) that was accepted to initiate the Grant

Sample:

  • Name: Name of Sample
  • SampleNumber: Number of Sample
  • Genome: Associated Genome (ID)
  • AppSession: The AppSession (ID) that generated the Sample
  • SampleSheetSampleId: The SampleSheet Sample Id of the Sample
  • ExperimentName: Name of experiment
  • OwnerUser: Owner (User ID) of the Sample
  • IsPairedEnd: True if the Sample is paired-end
  • Read1: Number of cycles of Read1
  • Read2: Number of cycles of Read2 (if paired-end)
  • NumReadsRaw: Number of raw reads; if paired end read then half the count
  • NumReadsPF: Number of pass-filter reads; if paired end read then half the count
  • IsMerged: True if sample came from merged samples
  • DataStatus: Deletion or archive status. Examples: TRASH, ARCHIVE (OnSite only), OKTOPURGE (emptied from trash)

LoginSession:

Represents a logged in user's (website) authenticated session, holding user attributes valid while user remains logged into website.

  • LoggedInUser: User (ID) that logged in
  • ActingUser: Acting-as user (ID)
  • LoggedOffOn: Log off date/time

Run:

  • InstrumentRunNumber: The instrument Run number
  • ExperimentName: The name of the experiment from the SampleSheet
  • InstrumentRunId: The instrument Run (ID)
  • ReagentBarcode: Barcode of reagent
  • FlowcellBarcode: The Flowcell barcode of the run
  • BufferBarcode: The buffer barcode
  • AnalysisWorkflowType: The type of Analyses executed after Run sequencing is finished
  • RunState: State of the Run. Examples: New, Ready, Running, Paused, Stopped, InstrumentCompleted, Completed, Deleted, Failed, Rehybing
  • Instrument: Associated instrument (ID)
  • UploadedByUser: Information about the user (ID) who uploaded the run
  • OwnerUser: Owner (User ID) of the Project
  • DataStatus: Deletion or archive status. Examples: TRASH, ARCHIVE (OnSite only), OKTOPURGE (emptied from trash).
  • LimsStatus: LIMS status of the Run. Examples: NoLims, AwaitingFlowcellDetails, LimsSampleSheetGenerating, LimsSampleSheetGenerated, BarcodeNotFound, UserSampleSheet, LibraryMappingsCleared, LibraryMappingError
  • LaneAndQcStatus: Lane QC status of the Run. Examples: Initial, LaneQcFailed, QcPassed, Rehybed, LanePendingQc

User:

  • Email: User's email address
  • Name: User's full ([first] [last]) name

Events when Files are Viewed or Downloaded

The system records history events when files are viewed or downloaded.

Sequencing Runs

A single event is recorded per Run when any of its files are viewed/downloaded. For the 30-minute window after this event, no further viewing events are recorded if other files from the same Run are viewed.

Example response:

{
    "Id": "a7effb28-2435-4306-baed-a2dd23b5a19a_Run_9226150",
    "DateCreated": "2016-07-11T19:30:00.0000000Z",
    "ResourceType": "Run",
    "ResourceId": "9226150",
    "ActingUserId": "12341234",
    "LoggedInUserId": "12341234",
    "LoggedInUserName": "BaseSpace User",
    "ActingUserName": "BaseSpace User",
    "IpAddress": "192.08.01.198",
    "EventType": "Read",
    "Metadata": {
        "fileaccesseventdurationseconds": "1800"
    }
}

Sample and AppResult Files

A single event is recorded per file when the file is viewed/downloaded. For the 10-minute window after this event, no further viewing events are recorded if the same Sample or AppResult file is viewed again.

Example response:

{
    "Id": "7a17304e-2f4a-4d8b-abb9-e5283e39bd15_Sample_9250270",
    "DateCreated": "2016-07-11T19:35:00.0000000Z",
    "ResourceType": "Sample",
    "ResourceId": "9250270",
    "ActingUserId": "12341234",
    "LoggedInUserId": "12341234",
    "LoggedInUserName": "BaseSpace User",
    "ActingUserName": "BaseSpace User",
    "IpAddress": "192.08.01.198",
    "EventType": "Read",
    "Metadata": {
        "filename": "Phix_S1_L001_R1_001.fastq.gz",
        "filepath": "Data/Intensities/BaseCalls/Phix_S1_L001_R1_001.fastq.gz",
        "sizeinbytes": "194622809",
        "fileid": "90130482",
        "fileaccesseventdurationseconds": "600",
        "projectids": "5552555"
    }
}