REST API for Clinical One Platform

V2.0

get

/ec-dataaction-svc/rest/v2.0/studies/{studyId}/{mode}/subjects/{subjectId}/events/{eventId}/forms/{formId}/items/{itemId}/locks

This API retrieves the lock status and history for a specific item within a subject's event and form. It does not perform locking itself, but allows clients to view whether and how the item is currently locked,V2 is the recommended version for retrieving lock status, providing updated validation, improved error logging

Request

Path Parameters

eventId(required): string(uuid)
Unique identifier(UUID, 32-character uppercase hexadecimal string) representing the clinical event like Screening, Visit 1 etc.
Example:
```
BACEFACE12345678A1B2C3D4E5F60789
```
formId(required): string(uuid)
Unique identifier(UUID, 32-character uppercase hexadecimal string) representing the clinical form.
Example:
```
D5C6B2A4C8F3E01587B96202BBAA9345
```
itemId(required): string(uuid)
Unique Item identifier (UUID, 32-character uppercase hexadecimal string) from the study Designer, associated to a form.
Example:
```
ABCDEFABCDEF1234567890ABCDEF1234
```
mode(required): string
Mode of the study, accepts: test, active, or training.
Example:
```
test
```
studyId(required): string(uuid)
Unique identifier (UUID, 32-character uppercase hexadecimal string) representing the study.
Example:
```
A1B23C45D67E89F123456789ABCDEF12
```
subjectId(required): string(uuid)
Unique subject identifier (UUID, 32-character uppercase hexadecimal string) representing the patient/participant enrolled in the study.
Example:
```
3EFD49D47C96428C9AAE2FDDE2A32D23
```

Query Parameters

eventInstanceNum: integer(int64)
Numeric value representing the instance number of the event. Used for repeated or unscheduled visits. It is null for scheduled events.
Example:
```
2
```
innerRepeat: integer(int64)
Indicates the repeat sequence number of a nested or inner repeating form within an outer repeating structure. This value is used to distinguish multiple occurrences of the same inner form for a given outer repeat instance.
Example:
```
1
```
outerRepeat: integer(int64)
Indicates the repeat sequence number of the primary or outer repeating form. This value identifies each top-level occurrence of a repeating form and serves as the parent context for any nested inner repeats.
Example:
```
0
```
parentData: boolean
Parent Data.
Example:
```
false
```
repeatFormNumber: integer(int64)
Represents the ordinal number assigned to a repeated instance of a data collection form. It uniquely identifies each occurrence of a repeating form for a subject when multiple instances of the form.
Example:
```
2
```
repeatSequenceNumber: integer(int64)
Indicates the order of occurrence for a repeating form instance, used to distinguish between multiple repetitions of the same form.
Example:
```
1
```

There's no request body for this operation.

Response

Supported Media Types

application/json

200 Response

Success

Root Schema : schema

Type: array

Show Source

Array of: object DataActionsDTO

DTO representing details of a data action and locking operations.

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/DataActionsDTO"
    }
}

Nested Schema : DataActionsDTO

Type: object

DTO representing details of a data action and locking operations.

Show Source

action: string

Action taken on the visit start date value.Acceptable values are LOCKED, UNLOCKED, NEVER_LOCKED.

Example: LOCKED
comment: string

Minimum Length: 0

Maximum Length: 2048

Additional comments about the action.

Example: Lock applied due to protocol deviation
eventId: string (UUID)

Unique identifier(UUID, 32-character uppercase hexadecimal string) representing the clinical event like Screening, Visit 1 etc.

Example: A1B23C45D67E89F123456789ABCDEF12
eventInstanceNum: integer (int64)

Numeric value representing the instance number of the event. Used for repeated or unscheduled visits. It is null for scheduled events.

Example: 1
formId: string (UUID)

Unique identifier(UUID, 32-character uppercase hexadecimal string) representing the clinical form.

Example: C9F84A1D5C7E42A8B9F56321A4B8D721
formSectionId: string (UUID)

ID (UUID, 32-character uppercase hexadecimal string) of the form section.

Example: 8877665544332211AABBCCDDEEFF0011
id: string

Unique identifier for a data action given in UUID, 32-character uppercase hexadecimal string format.

Example: A1B23C45D67E89F123456789ABCDEF12
innerRepeat: integer (int64)

Indicates the repeat sequence number of a nested or inner repeating form within an outer repeating structure. This value is used to distinguish multiple occurrences of the same inner form for a given outer repeat instance.

Example: 0
itemId: string (UUID)

Unique Item identifier (UUID, 32-character uppercase hexadecimal string) from the study Designer, associated to a form.

Example: ABCDEFABCDEF1234567890ABCDEF1234
objectVersionNumber: number (integer)

Object version number

Example: 2
operationType: string

Operation type on the record, can have values CREATED, MODIFIED or REMOVED

Example: MODIFIED
outerRepeat: integer (int64)

Indicates the repeat sequence number of the primary or outer repeating form. This value identifies each top-level occurrence of a repeating form and serves as the parent context for any nested inner repeats.

Example: 1
reason: string

Minimum Length: 0

Maximum Length: 255

Reason for the data action.

Example: Other
repeatFormNumber: integer (int64)

Form repeat number if applicable.

Example: 1
repeatSequenceNumber: integer (int64)

Indicates the order of occurrence for a repeating form instance, used to distinguish between multiple repetitions of the same form.

Example: 2
siteId: string (UUID)

Unique identifier (UUID, 32-character uppercase hexadecimal string) representing the clinical site.

Example: B1B8327AFAA6412287106192AB5984EF
softwareVersionNumber: number (integer)

Software version number

Example: 3
studyVersion: string

String representing the version of the study configuration or protocol. Helps track changes in form or study design.

Example: 2.0.0.38
subjectId: string (UUID)

Unique subject identifier (UUID, 32-character uppercase hexadecimal string) representing the patient/participant enrolled in the study.

Example: 3EFD49D47C96428C9AAE2FDDE2A32D23
userId: string

Unique Identifier (UUID, 32-character uppercase hexadecimal string) of the user

Example: E1F2D3C4B5A697887766554433221100
versionEnd: string (date-time)

The end date until which the data is applicable or valid.

Example: 2023-12-31T23:59:59Z
versionStart: string (date-time)

The timestamp marking the beginning of the validity period for this record version within the system.

Example: 2023-01-01T00:00:00Z
visitStartDateAction: string

Action performed on visit start date LOCKED, UNLOCKED, NEVER_LOCKED.

Example: UNLOCKED

{
    "type":"object",
    "properties":{
        "formSectionId":{
            "type":"string",
            "description":"ID (UUID, 32-character uppercase hexadecimal string) of the form section.",
            "format":"UUID",
            "example":"8877665544332211AABBCCDDEEFF0011"
        },
        "id":{
            "type":"string",
            "description":"Unique identifier for a data action given in UUID, 32-character uppercase hexadecimal string format.",
            "example":"A1B23C45D67E89F123456789ABCDEF12"
        },
        "versionStart":{
            "type":"string",
            "description":"The timestamp marking the beginning of the validity period for this record version within the system.",
            "format":"date-time",
            "example":"2023-01-01T00:00:00Z"
        },
        "versionEnd":{
            "type":"string",
            "description":"The end date until which the data is applicable or valid.",
            "format":"date-time",
            "example":"2023-12-31T23:59:59Z"
        },
        "operationType":{
            "type":"string",
            "description":"Operation type on the record, can have values CREATED, MODIFIED or REMOVED",
            "example":"MODIFIED"
        },
        "userId":{
            "type":"string",
            "description":"Unique Identifier (UUID, 32-character uppercase hexadecimal string) of the user",
            "example":"E1F2D3C4B5A697887766554433221100"
        },
        "objectVersionNumber":{
            "type":"number",
            "description":"Object version number",
            "format":"integer",
            "example":2
        },
        "softwareVersionNumber":{
            "type":"number",
            "description":"Software version number",
            "format":"integer",
            "example":3
        },
        "reason":{
            "maxLength":255,
            "minLength":0,
            "type":"string",
            "description":"Reason for the data action.",
            "example":"Other"
        },
        "comment":{
            "maxLength":2048,
            "minLength":0,
            "type":"string",
            "description":"Additional comments about the action.",
            "example":"Lock applied due to protocol deviation"
        },
        "siteId":{
            "type":"string",
            "description":"Unique identifier (UUID, 32-character uppercase hexadecimal string) representing the clinical site.",
            "format":"UUID",
            "example":"B1B8327AFAA6412287106192AB5984EF"
        },
        "formId":{
            "type":"string",
            "description":"Unique identifier(UUID, 32-character uppercase hexadecimal string) representing the clinical form.",
            "format":"UUID",
            "example":"C9F84A1D5C7E42A8B9F56321A4B8D721"
        },
        "subjectId":{
            "type":"string",
            "description":"Unique subject identifier (UUID, 32-character uppercase hexadecimal string) representing the patient/participant enrolled in the study.",
            "format":"UUID",
            "example":"3EFD49D47C96428C9AAE2FDDE2A32D23"
        },
        "eventId":{
            "type":"string",
            "description":"Unique identifier(UUID, 32-character uppercase hexadecimal string) representing the clinical event like Screening, Visit 1 etc.",
            "format":"UUID",
            "example":"A1B23C45D67E89F123456789ABCDEF12"
        },
        "repeatSequenceNumber":{
            "type":"integer",
            "description":"Indicates the order of occurrence for a repeating form instance, used to distinguish between multiple repetitions of the same form.",
            "format":"int64",
            "example":2
        },
        "itemId":{
            "type":"string",
            "description":"Unique Item identifier (UUID, 32-character uppercase hexadecimal string) from the study Designer, associated to a form.",
            "format":"UUID",
            "example":"ABCDEFABCDEF1234567890ABCDEF1234"
        },
        "studyVersion":{
            "type":"string",
            "description":"String representing the version of the study configuration or protocol. Helps track changes in form or study design.",
            "example":"2.0.0.38"
        },
        "eventInstanceNum":{
            "type":"integer",
            "description":"Numeric value representing the instance number of the event. Used for repeated or unscheduled visits. It is null for scheduled events.",
            "format":"int64",
            "example":1
        },
        "repeatFormNumber":{
            "type":"integer",
            "description":"Form repeat number if applicable.",
            "format":"int64",
            "example":1
        },
        "innerRepeat":{
            "type":"integer",
            "description":"Indicates the repeat sequence number of a nested or inner repeating form within an outer repeating structure. This value is used to distinguish multiple occurrences of the same inner form for a given outer repeat instance.",
            "format":"int64",
            "example":0
        },
        "outerRepeat":{
            "type":"integer",
            "description":"Indicates the repeat sequence number of the primary or outer repeating form. This value identifies each top-level occurrence of a repeating form and serves as the parent context for any nested inner repeats.",
            "format":"int64",
            "example":1
        },
        "action":{
            "type":"string",
            "description":"Action taken on the visit start date value.Acceptable values are LOCKED, UNLOCKED, NEVER_LOCKED.",
            "example":"LOCKED"
        },
        "visitStartDateAction":{
            "type":"string",
            "description":"Action performed on visit start date LOCKED, UNLOCKED, NEVER_LOCKED.",
            "example":"UNLOCKED"
        }
    },
    "description":"DTO representing details of a data action and locking operations."
}

Examples

400 Response

Bad_Request

Root Schema : RestResponse

Type: object

Show Source

errorData: object ErrorResponseData

Structure representing an error response from the reporting service. Contains an error code, human-readable message, and details.
result: object result
status: string
version: integer (int32)

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string"
        },
        "result":{
            "type":"object"
        },
        "version":{
            "type":"integer",
            "format":"int32",
            "writeOnly":true
        },
        "errorData":{
            "$ref":"#/components/schemas/ErrorResponseData"
        }
    }
}

Nested Schema : ErrorResponseData

Type: object

Structure representing an error response from the reporting service. Contains an error code, human-readable message, and details.

Show Source

details: object details

Detailed error context or debugging information such as validation error, stack trace, or field/parameter cause.
errorCode: string

Application or business-specific error code representing the error type.

Example: REPT_401
errorMessage: string

Human-readable error message describing the failure or issue.

Example: Unauthorized: User does not have access to the requested resource

{
    "type":"object",
    "properties":{
        "errorCode":{
            "type":"string",
            "description":"Application or business-specific error code representing the error type.",
            "example":"REPT_401"
        },
        "errorMessage":{
            "type":"string",
            "description":"Human-readable error message describing the failure or issue.",
            "example":"Unauthorized: User does not have access to the requested resource"
        },
        "details":{
            "type":"object",
            "description":"Detailed error context or debugging information such as validation error, stack trace, or field/parameter cause.",
            "example":"User role is missing required permission REPORTING_VIEW. Field: userId"
        }
    },
    "description":"Structure representing an error response from the reporting service. Contains an error code, human-readable message, and details."
}

Nested Schema : result

Type: object

Nested Schema : details

Type: object

Detailed error context or debugging information such as validation error, stack trace, or field/parameter cause.

Example:

User role is missing required permission REPORTING_VIEW. Field: userId