REST API for Clinical One Cloud Service

V3.0

get

/ec-designer-svc/rest/v3.0/studies/{studyId}/{mode}/forms

Retrieves the forms available in a study for the selected mode and form category. The response includes each form's ID, reference name, title, summary item details when item details are available, form category, and form subcategories.

Request

Path Parameters

mode(required): string
Study mode used to return forms. Allowed values: test, training, active.
Example:
```
test
```
studyId(required): string(uuid)
Study ID (UUID, 32-character uppercase hexadecimal string). Required.
Example:
```
F054C951EB74443C93716CA714AB686E
```
version(required): string
Study version path segment. Required. Example: "1.0.0.1".
Example:
```
1.0.0.1
```

Query Parameters

excludeItemType: string
Optional form item type to exclude from returned item summaries.

Allowed Values: [ "instructionalText" ]
Example:
```
instructionalText
```
formCategory: string
Optional form category used to filter returned forms. Defaults to DCS.

Default Value: DCS

Allowed Values: [ "DCS", "NSF", "ALL" ]
Example:
```
DCS
```

There's no request body for this operation.

Response

Supported Media Types

application/json

200 Response

Successful operation.

Root Schema : schema

Type: array

Show Source

Array of: object FormSummaryDto v3.0

Title: FormSummaryDto v3.0

Summary information for a study form returned by the V3.0 query forms API.

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/Form Summary DTO V3"
    }
}

Nested Schema : FormSummaryDto v3.0

Type: object

Title: FormSummaryDto v3.0

Summary information for a study form returned by the V3.0 query forms API.

Show Source

formCategory: string

Allowed Values: [ "DataCollection", "ClinicalSuppliesData" ]

Form category returned for the form.

Example: DataCollection
formSubcategory: array formSubcategory

Form subcategories returned for the form.
id: string (uuid)

Form ID. UUID, 32-character uppercase hexadecimal string.
items: array items

Form item summaries.
refname: string

Reference name for the form.

Example: DEMOGRAPHICS
title: string

Display title for the form.

Example: Demographics

{
    "title":"FormSummaryDto v3.0",
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"Form ID. UUID, 32-character uppercase hexadecimal string.",
            "format":"uuid"
        },
        "refname":{
            "type":"string",
            "description":"Reference name for the form.",
            "example":"DEMOGRAPHICS"
        },
        "title":{
            "type":"string",
            "description":"Display title for the form.",
            "example":"Demographics"
        },
        "items":{
            "type":"array",
            "description":"Form item summaries.",
            "example":[
                {
                    "id":"9F4A6C7E1B8F4D56A23C9F3A0C7D4E77",
                    "refname":"AGE",
                    "questionType":"numeric",
                    "questionLabel":"Age"
                }
            ],
            "items":{
                "$ref":"#/components/schemas/Form Item Summary DTO V3"
            }
        },
        "formCategory":{
            "type":"string",
            "description":"Form category returned for the form.",
            "example":"DataCollection",
            "enum":[
                "DataCollection",
                "ClinicalSuppliesData"
            ]
        },
        "formSubcategory":{
            "type":"array",
            "description":"Form subcategories returned for the form.",
            "example":[
                "Screening"
            ],
            "items":{
                "type":"string",
                "example":"Screening"
            }
        }
    },
    "description":"Summary information for a study form returned by the V3.0 query forms API.",
    "example":{
        "id":"2F9A6C7E1B8F4D56A23C9F3A0C7D4E11",
        "refname":"DEMOGRAPHICS",
        "title":"Demographics",
        "items":[
            {
                "id":"9F4A6C7E1B8F4D56A23C9F3A0C7D4E77",
                "refname":"AGE",
                "questionType":"numeric",
                "questionLabel":"Age"
            }
        ],
        "formCategory":"DataCollection",
        "formSubcategory":[
            "Screening"
        ]
    }
}

Example:

{
    "id":"2F9A6C7E1B8F4D56A23C9F3A0C7D4E11",
    "refname":"DEMOGRAPHICS",
    "title":"Demographics",
    "items":[
        {
            "id":"9F4A6C7E1B8F4D56A23C9F3A0C7D4E77",
            "refname":"AGE",
            "questionType":"numeric",
            "questionLabel":"Age"
        }
    ],
    "formCategory":"DataCollection",
    "formSubcategory":[
        "Screening"
    ]
}

Nested Schema : formSubcategory

Type: array

Form subcategories returned for the form.

Show Source

Array of: string

Example: Screening

{
    "type":"array",
    "description":"Form subcategories returned for the form.",
    "example":[
        "Screening"
    ],
    "items":{
        "type":"string",
        "example":"Screening"
    }
}

Example:

[
    "Screening"
]

Nested Schema : items

Type: array

Form item summaries.

Show Source

Array of: object FormItemSummaryDto v3.0

Title: FormItemSummaryDto v3.0

Summary information for a form item returned by the V3.0 query forms API.

{
    "type":"array",
    "description":"Form item summaries.",
    "example":[
        {
            "id":"9F4A6C7E1B8F4D56A23C9F3A0C7D4E77",
            "refname":"AGE",
            "questionType":"numeric",
            "questionLabel":"Age"
        }
    ],
    "items":{
        "$ref":"#/components/schemas/Form Item Summary DTO V3"
    }
}

Example:

[
    {
        "id":"9F4A6C7E1B8F4D56A23C9F3A0C7D4E77",
        "refname":"AGE",
        "questionType":"numeric",
        "questionLabel":"Age"
    }
]

Nested Schema : FormItemSummaryDto v3.0

Type: object

Title: FormItemSummaryDto v3.0

Summary information for a form item returned by the V3.0 query forms API.

Show Source

id: string (uuid)

Form item ID. UUID, 32-character uppercase hexadecimal string.
questionLabel: string

Display label for the question.

Example: Age
questionType: string

Title: FormItemType

Allowed Values: [ "text", "instructionalText", "numeric", "datetime", "choice", "questionGroup", "table", "label", "section", "existingData", "fileUpload" ]

Question type for the form item.

Example: numeric
refname: string

Reference name for the form item.

Example: AGE
subItemIds: string (uuid)

Title: Sub item ids

IDs of sub-items for a question group. Each ID is a UUID, 32-character uppercase hexadecimal string.

{
    "title":"FormItemSummaryDto v3.0",
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"Form item ID. UUID, 32-character uppercase hexadecimal string.",
            "format":"uuid"
        },
        "refname":{
            "type":"string",
            "description":"Reference name for the form item.",
            "example":"AGE"
        },
        "questionType":{
            "title":"FormItemType",
            "type":"string",
            "description":"Question type for the form item.",
            "example":"numeric",
            "enum":[
                "text",
                "instructionalText",
                "numeric",
                "datetime",
                "choice",
                "questionGroup",
                "table",
                "label",
                "section",
                "existingData",
                "fileUpload"
            ]
        },
        "questionLabel":{
            "type":"string",
            "description":"Display label for the question.",
            "example":"Age"
        },
        "subItemIds":{
            "title":"Sub item ids",
            "type":"string",
            "description":"IDs of sub-items for a question group. Each ID is a UUID, 32-character uppercase hexadecimal string.",
            "format":"uuid"
        }
    },
    "description":"Summary information for a form item returned by the V3.0 query forms API.",
    "example":{
        "id":"9F4A6C7E1B8F4D56A23C9F3A0C7D4E77",
        "refname":"AGE",
        "questionType":"numeric",
        "questionLabel":"Age"
    }
}

Example:

{
    "id":"9F4A6C7E1B8F4D56A23C9F3A0C7D4E77",
    "refname":"AGE",
    "questionType":"numeric",
    "questionLabel":"Age"
}

Examples

500 Response

Returned when the request cannot be completed due to validation failure, authorization failure, or an unexpected server-side condition.

Root Schema : ErrorResponseData

Type: object

Title: ErrorResponseData

Error Response Details Information

Show Source

details: object Object

Title: Object

Object with error details information.
errorCode: string

Error code which is stored in ErrorCode enum. Example : C1-003

Example: C1-003
errorMessage: string

Error message which is stored in service property file. Example : Cannot modify object after a study version has been approved

Example: Cannot modify object after a study version has been approved

{
    "title":"ErrorResponseData",
    "type":"object",
    "properties":{
        "errorCode":{
            "type":"string",
            "description":"Error code which is stored in ErrorCode enum. Example : C1-003",
            "example":"C1-003"
        },
        "errorMessage":{
            "type":"string",
            "description":"Error message which is stored in service property file. Example : Cannot modify object after a study version has been approved",
            "example":"Cannot modify object after a study version has been approved"
        },
        "details":{
            "title":"Object",
            "type":"object",
            "description":"Object with error details information.",
            "example":{
                "field":"studyId",
                "reason":"Invalid value"
            }
        }
    },
    "description":"Error Response Details Information"
}

Nested Schema : Object

Type: object

Title: Object

Object with error details information.

Example:

{
    "field":"studyId",
    "reason":"Invalid value"
}