REST API for Clinical One Platform

V3.0

get

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

The V3 API retrieves detailed lock records for a specific item within a form/event/subject. It provides not only the lock history and current status, but introduces a new field `subjectLockStatus` indicating if the subject as a whole is LOCKED or UNLOCKED.

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 DataActionsDTO2

DTO representing details of a data action in API v3, including lock status at subject level.

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

Nested Schema : DataActionsDTO2

Type: object

DTO representing details of a data action in API v3, including lock status at subject level.

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
subjectLockStatus: string

Lock status of the subject for the action, can be of LOCKED, UNLOCKED.

Example: LOCKED
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"
        },
        "subjectLockStatus":{
            "type":"string",
            "description":"Lock status of the subject for the action, can be of LOCKED, UNLOCKED.",
            "example":"LOCKED"
        }
    },
    "description":"DTO representing details of a data action in API v3, including lock status at subject level."
}

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