Form Instance APIs

These APIs are only applicable for AireForms deployments with associated persistence.

Create form instances for a given patient

Route: POST /api/clinicianforms/create/ (Requires authentication) Permission: Create
Description: Create an instance of a form for a given patient

Request

{
    "patientIdentifier": "a4847fd9-7da1-49da-b5f4-be278dba0730",
    "instanceIdentifier": "70b9802a-c7d2-420c-bdc1-0a32b6d06c19",
    "formKey": "end-of-life-care",
    "formVersion": 1
}

We also support an optional property onBehalfOf. This will then create the form under the onBehalfOf user, assuming it passes the implementations authorisation checks implemented in the plugin.

Example:

{
    "patientIdentifier": "a4847fd9-7da1-49da-b5f4-be278dba0730",
    "instanceIdentifier": "70b9802a-c7d2-420c-bdc1-0a32b6d06c19",
    "formKey": "end-of-life-care",
    "formVersion": 1,
    "onBehalfOf": {
        "identifier": "user-123",
        "type": "user"
    }
}

Type can be one of the following:

• user
• subject
• system
• external
• subjectProxy

From 11.2.0 we also support an optional property of instanceContext this allows the system to pass in a dictionary of strings that are stored along with the instance and will be available in the form context. These values cannot be modified after creation.

Example:

{
    "patientIdentifier": "a4847fd9-7da1-49da-b5f4-be278dba0730",
    "instanceIdentifier": "70b9802a-c7d2-420c-bdc1-0a32b6d06c19",
    "formKey": "end-of-life-care",
    "formVersion": 1,
    "instanceContext": {
        "context-item-1": "one",
        "contest-item-2": "two"
    }
}

NOTE

Any keys are that invalid xml element names will be placed as a key attribute on a generic value element. Example:

<values>
    <valid-xml-name>value</valid-xml-name>
    <value key="1invalidxml name">value</value>
</values>

Withdraw a form instance

Route: DELETE /api/patientforms/{PatientId}/instance/{InstanceId}/withdraw (Requires authentication) Permission: Withdraw
Description: Marks a form instance and all its instance versions as being withdrawn and therefore removing it from any API responses unless explicitly requested with the query parameter includeWithdrawn=true

Request

{
    "reason": "Form created against wrong patient by mistake"
}

Reinstate a form instance

Route: PATCH /api/patientforms/{PatientId}/instance/{InstanceId}/reinstate (Requires authentication) Permission: Reinstate
Description: Marks a form instance and all its instance versions as being reinstated and therefore allowing it to be included in any API responses.

Request

{
    "reason": "Form withdrawn in error"
}

History of a particular form instance

Route: GET /api/patientforms/{patientId}/history/{instanceGuid} (Requires authentication) Permission: ListPatientForms
Description: Retrieves the history of an instance.

Example response

{
    "compositeInstanceHistory": [
        {
            "instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
            "instanceVersionGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
            "createdByUserIdentifier": "4",
            "createdDateTimeUtc": "2023-05-22T15:39:39.2878379",
            "status": "New",
            "isEditMilestone": true,
            "isCompleted": false,
            "isDeleted": false,
            "deletedByUserIdentifier": null,
            "deletedDateTimeUtc": null,
            "key": "bmi-reporting",
            "version": 1,
            "viewLink": "/patient/117536d8-9ef2-49d2-Ae9e-f5afb330c78f/instance/aa18b928-a4d5-4634-8d03-cc3a2b3a7543/version/aa18b928-a4d5-4634-8d03-cc3a2b3a7543/view"
        },
        {
            "instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
            "instanceVersionGuid": "6ee55219-1e63-4f4f-83da-7e8077820c3d",
            "createdByUserIdentifier": "4",
            "createdDateTimeUtc": "2023-05-22T15:39:45.3373301",
            "status": "Complete",
            "isEditMilestone": false,
            "isCompleted": true,
            "isDeleted": false,
            "deletedByUserIdentifier": null,
            "deletedDateTimeUtc": null,
            "key": "bmi-reporting",
            "version": 1,
            "viewLink": "/patient/117536d8-9ef2-49d2-Ae9e-f5afb330c78f/instance/aa18b928-a4d5-4634-8d03-cc3a2b3a7543/version/6ee55219-1e63-4f4f-83da-7e8077820c3d/view"
        },
        {
            "instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
            "instanceVersionGuid": "62932da8-8d40-4e1a-9bc6-68240263107d",
            "createdByUserIdentifier": "10",
            "createdDateTimeUtc": "2023-05-22T15:39:52.867569",
            "status": "Draft",
            "isEditMilestone": true,
            "isCompleted": false,
            "isDeleted": false,
            "deletedByUserIdentifier": null,
            "deletedDateTimeUtc": null,
            "key": "bmi-reporting",
            "version": 1,
            "viewLink": "/patient/117536d8-9ef2-49d2-Ae9e-f5afb330c78f/instance/aa18b928-a4d5-4634-8d03-cc3a2b3a7543/version/62932da8-8d40-4e1a-9bc6-68240263107d/view"
        },
        {
            "instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
            "instanceVersionGuid": "ec5f403e-5752-44bb-9ca4-d76375d3ef6a",
            "createdByUserIdentifier": "10",
            "createdDateTimeUtc": "2023-05-22T15:40:02.33459",
            "status": "Complete",
            "isEditMilestone": false,
            "isCompleted": true,
            "isDeleted": false,
            "deletedByUserIdentifier": null,
            "deletedDateTimeUtc": null,
            "key": "bmi-reporting",
            "version": 1,
            "viewLink": "/patient/117536d8-9ef2-49d2-Ae9e-f5afb330c78f/instance/aa18b928-a4d5-4634-8d03-cc3a2b3a7543/version/ec5f403e-5752-44bb-9ca4-d76375d3ef6a/view"
        }
    ],
    "withdrawalHistory": [
        {
            "instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
            "withdrawalStatus": "Withdrawn",
            "reason": "some reason",
            "withdrawnByUserIdentifier": "10",
            "actionTakenDateTime": "2023-05-22T15:40:07.5327879"
        },
        {
            "instanceGuid": "aa18b928-a4d5-4634-8d03-cc3a2b3a7543",
            "withdrawalStatus": "Reinstated",
            "reason": "some reason",
            "withdrawnByUserIdentifier": "4",
            "actionTakenDateTime": "2023-05-22T15:40:11.7514406"
        }
    ]
}

Error handling and standard HTTP response codes

HTTP Response Codes are used per standard REST API design. However the most commonly used codes by AireForms are listed below. a Where APIs used a different set or response codes / behaviours these are individually documented with the API

Code	Description
200	Success - The operation to load/save a form or call an API succeded. The response payload will be dependent on the URL/API called
400	Bad Request - Occurs if the API request payload (or URL parameters) fail validation or are otherwise malformed
403	Forbidden - The User does not have the correct permissions (or is not authenticated), and/or the tenantId or formKey/version configuration does not support the requested operation
404	Not Found - The requested URL / API does not exist and/or the tenantId and/or patientId does not exist and/or the formKey/formVersion does not exist or is not in a published state
500	Internal Server Error - An error has occured on the server
503	Service Unavailable - The server might be re-starting or (more likely) a proxy server cannot contact the service

Get form instances by instance identifiers

WARNING

Deprecated. Use the Subject Forms V2 APIs query endpoint instead, which combines every filter, supports sorting, and always pages. This endpoint remains for backwards compatibility.

Route: GET /api/patientforms?instanceGuid={instanceGuid} (Requires authentication) Permission: ListPatientForms
Description: Returns a list of all forms with the given instance identifiers
Example: /api/patientforms?instanceGuid=816eb663-cc1f-478d-8efe-5c068ec434f2&instanceGuid=ba63eed3-5901-4cb0-a48a-955eab32abcf

Response

    [
        {
            "instanceGuid": "816eb663-cc1f-478d-8efe-5c068ec434f2",
            "title": "End of Life Care Plan",
            "createDateTimeUtc": "2020-01-09T16:41:34.813",
            "lastModifiedDateTimeUtc": "2020-01-09T16:41:34.813",
            "status": "Draft",
            "isAmendable": true,
            "key": "eolc",
            "version": 1
        },
        {
            "instanceGuid": "ba63eed3-5901-4cb0-a48a-955eab32abcf",
            "title": "BMI Reporting",
            "createDateTimeUtc": "2019-12-02T11:22:12.6",
            "lastModifiedDateTimeUtc": "2019-12-02T11:22:32.297",
            "status": "Complete",
            "isAmendable": false,
            "key": "bmi-reporting",
            "version": 1
        }
        ...
    ]

Get form instances for a given patient

WARNING

Deprecated. Use the Subject Forms V2 APIs query endpoint instead, which combines every filter, supports sorting, and always pages. This endpoint remains for backwards compatibility.

Route: GET /api/patientforms/{patientId} (Requires authentication) Permission: ListPatientForms
Description: Returns a list of all forms associated with the patientId
Example: /api/patientforms/488edeAB-5e8F-4e50-9137-24e377cf9436

Response

[
    {
        "instanceGuid": "816eb663-cc1f-478d-8efe-5c068ec434f2",
        "title": "End of Life Care Plan",
        "createDateTimeUtc": "2020-01-09T16:41:34.813",
        "lastModifiedDateTimeUtc": "2020-01-09T16:41:34.813",
        "status": "Draft",
        "isAmendable": true,
        "key": "eolc",
        "version": 1
    },
    {
        "instanceGuid": "ba63eed3-5901-4cb0-a48a-955eab32abcf",
        "title": "BMI Reporting",
        "createDateTimeUtc": "2019-12-02T11:22:12.6",
        "lastModifiedDateTimeUtc": "2019-12-02T11:22:32.297",
        "status": "Complete",
        "isAmendable": false,
        "key": "bmi-reporting",
        "version": 1
    }
    ...
]

From 5.15.0 you can now use the following filters sent as query params:

• pageSize along with pageNumber
• correlationId