Export revisions

This API is used to export the list of revisions satisfying the request criteria. Remember a revision represents an act of creating, modifying or deleting an OpenSpecimen object/record.

Request

Export revisions effected by the user identified by userId = 1 during the time period March 1 (startDate) to March 15 (endDate). The exported list should include the list of modified record attributes/properties during each revision. The exported file contains the list of revisions arranged in reverse chronological order i.e. the latest revision at the top and ancient revision at the bottom of the file.

Note: Request entities and OpenSpecimen Record Types mapping added at the end of page.

URL

/openspecimen/rest/ng/audit/export-revisions

Method

POST

Body

Request: Single User

{
  "startDate": 1551398400000,
  "endDate": 1552608000000,
  "userId": 1,
  "includeModifiedProps": true,
  "entities": ["Participant", "ParticipantMedicalIdentifier", "CollectionProtocolRegistration", "ParticipantExtension"]
}

Request: Multiple Users

{
  "startDate": 1551398400000,
  "endDate": 1552608000000,
  "userIds": [1, 2, 3],
  "includeModifiedProps": true,
  "entities": ["Participant", "ParticipantMedicalIdentifier", "CollectionProtocolRegistration", "ParticipantExtension"]
}

Response

The response contains the file ID that can be used to download the exported revisions file.

{
  "fileId": "0a24ef05-c1aa-4641-b2a0-4d4f060b8f75_20190325_1645"
}

The exported revisions file can downloaded using the below API request

GET /openspecimen/rest/ng/audit/revisions-file?fileId=0a24ef05-c1aa-4641-b2a0-4d4f060b8f75_20190325_1645

Note: If the export is running for more than 30 seconds, then the task is delegated to a background thread. In such cases, fileId in the API response will be null. In either case, the user, who initiated the export, will be notified by email containing the link to download the revisions file.

Request parameters

Parameter	Description
startDate	Start date of the interval for which the revisions list is queried. If not specified, startDate = endDate - 30 days
endDate	End date of the interval for which the revisions list is queried. If not specified endDate = end of today.
userId	Restrict the exported list to revisions effected by the user identified by userId. Optional parameter.
userIds	Restrict the exported list to revisions effected by the users identified by the list of userIds. Optional parameter. (Supported from v6.3)
entities	Optional parameter. Specifies the list of entities or record types whose revisions need to be exported. This is very useful when the requestor intends to review the revisions of only certain record types say Shipment and ShipmentSpecimen. This parameter was added in v6.1.RC5.
includeModifiedProps	Specifies whether the exported list should include modified attributes list for each revision.

Response parameters

Parameter

Description

fileId

a) Unique file ID to use for downloading the exported revisions file.

b) Null in case the export requires more than 30 seconds to finish.

FAQ

Q1. What is the significance of "includeModifiedProps" value in the request?

The boolean property "includeModifiedProps" determines whether the exported revisions file includes the change log for each of the modified entities during the requested time interval or not.

Given below is an example of the CSV file created when includeModifiedProps = true. Notice the change log column, it includes the list of properties that got modified during the op along with their new values.

Revision ID	Revision Time	User	User Email ID	Operation	Record Type	Record	Change Log
169879	09 Jul 2019 15:26	John Doe	john.doe@openspecimen.org	Edit	Specimen	244004	collectionStatus=Collected,createdOn=Tue Jul 09 15:26:00 IST 2019,position={id=295350}
169879	09 Jul 2019 15:26	John Doe	john.doe@openspecimen.org	Add	Storage Container Position	295354	blocked=false,container={id=514},occupyingSpecimen={id=244010},posOne=8,posOneOrdinal=8,posTwo=3,posTwoOrdinal=3

When includeModifiedProps = false, the generated CSV file is as below. Notice the change log column is empty. It goes without saying that generating this kind of file is much faster than the above one as the API has to do lesser work.

Revision ID	Revision Time	User	User Email ID	Operation	Record Type	Record	Change Log
169879	09 Jul 2019 15:26	John Doe	john.doe@openspecimen.org	Edit	Specimen	244004
169879	09 Jul 2019 15:26	John Doe	john.doe@openspecimen.org	Add	Storage Container Position	295354

The below table explains requested entity and OpenSpecimen record type mapping details.

Request Entities	OpenSpecimen Record Type
`SpecimenList`	Carts
`Specimen`	Specimen
`SpecimenExternalIdentifier`	Specimen External Identifier
`Visit`	Visit
`CollectionProtocolRegistration`	Collection Protocol Registration
`Participant`	Participant
`ParticipantMedicalIdentifier`	Participant Medical Identifier
`StorageContainerPosition`	Container Position
`ShipmentSpecimen`	Shipment Specimen
`Shipment`	Shipment
`User`	User
`StorageContainer`	Storage Container
`CollectionProtocol`	Collection Protocol
`SpecimenRequirement`	Specimen Requirement
`CollectionProtocolEvent`	Collection Protocol Event
`CollectionProtocolSite`	CP Site
`DistributionOrderItem`	Distribution Order Items
`DistributionOrder`	Distribution Order
`ContainerType`	Container Type
`Role`	Role
`RoleAccessControl`	Role Access List
`DistributionProtocol`	Distribution Protocol
`ResourceInstanceOp`	Access List Operation
`CpConsentTier`	CP Consent
`Institute`	Institute
`SubjectRole`	User Role
`Site`	Site
`ShipmentContainer`	Shipment Container
`DpRequirement`	DP Requirement
`FormContextBean`	Form Association
`CpSpecimenLabelPrintSetting`	CP Specimen Label Print Setting
`DpDistributionSite`	DP Site