IMPORTANT: ORSCF V2 was not relased – THIS IS AN ALPHA STATE!
V1 can be found here
see also: Swagger/OpenAPI definition
ORSCF-BillingData Schema Specification
| Info | |
|---|---|
| author: | ORSCF ("Open Research Study Communication Formats") / T.Korn |
| license: | Apache-2 |
| version: | 2.0.0 |
| timestamp: | 2024-11-03 00:00 |
Contents
- . BillingItem
- . StudyExecutionScope
- ........\ BillableItem
- ........\ BillingDemand
- ........\ Invoice
Model:
BillingItem
Respresents a Snapshot, containig al the values, which are required to be fixed in relation to a concrete invoice or demand
Fields
| Name | Type | Required | Fix |
|---|---|---|---|
| BillingItemId (PK) | int64 | YES | no |
| CreationDateUtc | datetime | YES | no |
| SponsorValidationDateUtc | datetime | no | no |
| ExecutorValidationDateUtc | datetime | no | no |
| BillingDemandId (FK) | guid | no | no |
| InvoiceId (FK) | guid | no | no |
| FixedExecutionState | int32 | YES | no |
| FixedPriceOfItem | decimal | YES | no |
| FixedPriceOfTasks | decimal | YES | no |
| FixedTaxPercentage | decimal | YES | no |
| TasksRelatedInfo | string | YES | no |
| BillableItemUid (FK) | guid | no | no |
| Description | string | YES | no |
Unique Keys
- BillingItemId (primary)
BillingItem.BillingItemId (Field)
- this field represents the identity (PK) of the record
- this identity is a internal record id, so that it must not be exposed to other systems or displayed to end-users!
BillingItem.SponsorValidationDateUtc (Field)
- this field is optional, so that 'null' values are supported
BillingItem.ExecutorValidationDateUtc (Field)
- this field is optional, so that 'null' values are supported
BillingItem.BillingDemandId (Field)
- this field is optional, so that 'null' values are supported
- this field is used as foreign key to address the related 'AssignedDemand'
BillingItem.InvoiceId (Field)
- this field is optional, so that 'null' values are supported
- this field is used as foreign key to address the related 'AssignedInvoice'
BillingItem.FixedPriceOfItem (Field)
Including 'FixedPriceOfTasks' but excluding Taxes
BillingItem.FixedPriceOfTasks (Field)
An additional info which is only relevant when declaing Subtasks
BillingItem.BillableItemUid (Field)
- this field is optional, so that 'null' values are supported
- this field is used as foreign key to address the related 'BillableItem'
Relations
| Navigation-Name | Role | Target-Type | Target-Multiplicity |
|---|---|---|---|
| AssignedDemand | Lookup | BillingDemand | 1 (required) |
| AssignedInvoice | Lookup | Invoice | 1 (required) |
| BillableItem | Lookup | BillableItem | 1 (required) |
AssignedDemand (lookup from this BillingItem)
Target Type: BillingDemand Addressed by: BillingDemandId.
AssignedInvoice (lookup from this BillingItem)
Target Type: Invoice Addressed by: InvoiceId.
BillableItem (lookup from this BillingItem)
Target Type: BillableItem Addressed by: BillableItemUid.
StudyExecutionScope
Fields
| Name | Type | Required | Fix |
|---|---|---|---|
| StudyExecutionIdentifier (PK) | guid | YES | YES |
| ExecutingInstituteIdentifier | string | YES | YES |
| StudyWorkflowName | string (100) | YES | YES |
| StudyWorkflowVersion | string (20) | YES | YES |
| ExtendedMetaData | string | no | no |
| SiteRelatedTaxPercentage | decimal | YES | no |
| SiteRelatedCurrency | string | YES | no |
Unique Keys
- StudyExecutionIdentifier (primary)
StudyExecutionScope.StudyExecutionIdentifier (Field)
a global unique id of a concrete study execution (dedicated to a concrete institute) which is usually originated at the primary CRF or study management system ('SMS')
- this field represents the identity (PK) of the record
- after the record has been created, the value of this field must not be changed any more!
StudyExecutionScope.ExecutingInstituteIdentifier (Field)
the institute which is executing the study (this should be an invariant technical representation of the company name or a guid)
- after the record has been created, the value of this field must not be changed any more!
StudyExecutionScope.StudyWorkflowName (Field)
the official invariant name of the study as given by the sponsor
- the maximum length of the content within this field is 100 characters.
- after the record has been created, the value of this field must not be changed any more!
StudyExecutionScope.StudyWorkflowVersion (Field)
version of the workflow
- the maximum length of the content within this field is 20 characters.
- after the record has been created, the value of this field must not be changed any more!
StudyExecutionScope.ExtendedMetaData (Field)
optional structure (in JSON-format) containing additional metadata regarding this record, which can be used by 'StudyExecutionSystems' to extend the schema
- this field is optional, so that 'null' values are supported
StudyExecutionScope.SiteRelatedCurrency (Field)
ISO 3-Letter Code (USD, EUR, ...)
Relations
| Navigation-Name | Role | Target-Type | Target-Multiplicity |
|---|---|---|---|
| BillingDemands | Childs | BillingDemand | * (multiple) |
| Invoices | Childs | Invoice | * (multiple) |
BillingDemands (childs of this StudyExecutionScope)
Target: BillingDemand
Invoices (childs of this StudyExecutionScope)
Target: Invoice
BillableItem
Fields
| Name | Type | Required | Fix |
|---|---|---|---|
| BillableItemUid (PK) | guid | YES | no |
| StudyExecutionIdentifier (FK) | guid | YES | no |
| ParticipantIdentifier | string (50) | YES | no |
| VisitProcedureName | string | YES | no |
| UniqueExecutionName | string | YES | no |
| ExecutionEndDateUtc | datetime | no | no |
| Description | string | no | no |
| RelatedTo | string | YES | no |
Unique Keys
- BillableItemUid (primary)
BillableItem.BillableItemUid (Field)
a global unique id of a concrete study-visit execution which is usually originated at the primary CRF or study management system ('SMS')
- this field represents the identity (PK) of the record
BillableItem.StudyExecutionIdentifier (Field)
a global unique id of a concrete study execution (dedicated to a concrete institute) which is usually originated at the primary CRF or study management system ('SMS')
- this field is used as foreign key to address the related 'StudyExecution'
BillableItem.ParticipantIdentifier (Field)
identity of the patient which can be a randomization or screening number (the exact semantic is defined per study)
- the maximum length of the content within this field is 50 characters.
BillableItem.VisitProcedureName (Field)
unique invariant name of the visit-procedure as defined in the 'StudyWorkflowDefinition' (originated from the sponsor)
BillableItem.UniqueExecutionName (Field)
title of the visit execution as defined in the 'StudyWorkflowDefinition' (originated from the sponsor)
BillableItem.ExecutionEndDateUtc (Field)
- this field is optional, so that 'null' values are supported
BillableItem.Description (Field)
- this field is optional, so that 'null' values are supported
BillableItem.RelatedTo (Field)
One of the following values: 'General' / 'Site' / 'Paticipant' (Requires a ParticipantIdentifier) / 'Visit' (Requires a ParticipantIdentifier and UniqueExecutionName)
Relations
| Navigation-Name | Role | Target-Type | Target-Multiplicity |
|---|---|---|---|
| StudyExecution | Parent | StudyExecutionScope | 0/1 (optional) |
StudyExecution (parent of this BillableItem)
Target Type: StudyExecutionScope Addressed by: StudyExecutionIdentifier.
BillingDemand
created by the sponsor
Fields
| Name | Type | Required | Fix |
|---|---|---|---|
| Id (PK) | guid | YES | no |
| OfficialNumber | string | YES | no |
| StudyExecutionIdentifier (FK) | guid | YES | no |
| TransmissionDateUtc | datetime | no | no |
| CreationDateUtc | datetime | YES | no |
| CreatedByPerson | string | YES | no |
Unique Keys
- Id (primary)
BillingDemand.Id (Field)
- this field represents the identity (PK) of the record
BillingDemand.StudyExecutionIdentifier (Field)
- this field is used as foreign key to address the related 'StudyExecution'
BillingDemand.TransmissionDateUtc (Field)
- this field is optional, so that 'null' values are supported
Relations
| Navigation-Name | Role | Target-Type | Target-Multiplicity |
|---|---|---|---|
| StudyExecution | Parent | StudyExecutionScope | 0/1 (optional) |
| BillingItems | Referers | BillingItem | * (multiple) |
StudyExecution (parent of this BillingDemand)
Target Type: StudyExecutionScope Addressed by: StudyExecutionIdentifier.
BillingItems (refering to this BillingDemand)
Target: BillingItem
Invoice
created by the executor-company
Fields
| Name | Type | Required | Fix |
|---|---|---|---|
| Id (PK) | guid | YES | YES |
| OfficialNumber | string | YES | YES |
| StudyExecutionIdentifier (FK) | guid | YES | YES |
| OffcialInvoiceDate | datetime | YES | YES |
| TransmissionDateUtc | datetime | no | no |
| CreationDateUtc | datetime | YES | no |
| CreatedByPerson | string | YES | no |
| PaymentSubmittedDateUtc | datetime | no | no |
| PaymentReceivedDateUtc | datetime | no | no |
| CorrectionOfInvoiceId (FK) | guid | no | no |
Unique Keys
- Id (primary)
Invoice.Id (Field)
- this field represents the identity (PK) of the record
- after the record has been created, the value of this field must not be changed any more!
Invoice.OfficialNumber (Field)
the invoice number
- after the record has been created, the value of this field must not be changed any more!
Invoice.StudyExecutionIdentifier (Field)
- this field is used as foreign key to address the related 'StudyExecution'
- after the record has been created, the value of this field must not be changed any more!
Invoice.OffcialInvoiceDate (Field)
- after the record has been created, the value of this field must not be changed any more!
Invoice.TransmissionDateUtc (Field)
- this field is optional, so that 'null' values are supported
Invoice.PaymentSubmittedDateUtc (Field)
- this field is optional, so that 'null' values are supported
Invoice.PaymentReceivedDateUtc (Field)
- this field is optional, so that 'null' values are supported
Invoice.CorrectionOfInvoiceId (Field)
- this field is optional, so that 'null' values are supported
- this field is used as foreign key to address the related 'CorrectionOf'
Relations
| Navigation-Name | Role | Target-Type | Target-Multiplicity |
|---|---|---|---|
| BillingItems | Referers | BillingItem | * (multiple) |
| StudyExecution | Parent | StudyExecutionScope | 0/1 (optional) |
| Corrections | Referers | Invoice | * (multiple) |
| CorrectionOf | Lookup | Invoice | 1 (required) |
BillingItems (refering to this Invoice)
Target: BillingItem
StudyExecution (parent of this Invoice)
Target Type: StudyExecutionScope Addressed by: StudyExecutionIdentifier.
Corrections (refering to this Invoice)
Target: Invoice
CorrectionOf (lookup from this Invoice)
Target Type: Invoice Addressed by: CorrectionOfInvoiceId.