Commands
========

The Commands API is designed to offer a user-friendly interface for creating, updating, or deleting commands through REST endpoints.
Commands can exclusively be added to encounter, review, or data import notes.
It is important to note that encounter and review notes must be unlocked and should not be deleted.

Schema Fields
-------------
There are a number of available field types that each command can implement.


.. include:: commands/fields/fields.rst


Available Commands
------------------
Every command is associated with a unique ``schema_key``, which should be used when creating the respective command.
To retrieve the schema fields for a command, utilize the ``fields`` endpoint.

.. include:: commands/assess.rst

.. include:: commands/diagnose.rst

.. include:: commands/goal.rst

.. include:: commands/hpi.rst

.. include:: commands/instruct.rst

.. include:: commands/labOrder.rst

.. include:: commands/medicationStatement.rst

.. include:: commands/perform.rst

.. include:: commands/plan.rst

.. include:: commands/prescribe.rst

.. include:: commands/questionnaire.rst

.. include:: commands/reasonForVisit.rst

.. include:: commands/stopMedication.rst

.. include:: commands/updateGoal.rst

.. include:: commands/educationalMaterial.rst

Basic Usage
-----------

.. warning::


   Trailing slash is required for POST, PUT, PATCH and DELETE operations


.. http:get:: /core/api/v1/commands/{command_uuid}

   Retrieves the information about a specific command

   **Example request**:

   .. sourcecode:: http

      GET /core/api/v1/commands/23f9f649-7cbb-4111-ac21-72e5f16319ed HTTP/1.1
      Host: example.com
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK

      {
        "uuid": "23f9f649-7cbb-4111-ac21-72e5f16319ed",
        "state": "committed",
        "created_at": "2024-01-04T12:28:28.563080Z",
        "updated_at": "2024-01-04T12:30:55.326076Z",
        "schema_key": "plan",
        "patient_key": "06693bde986c4b3c90049315c14d8250",
        "note_key": "acb56588-da8f-40ea-b5b7-dd222193cd24",
        "originated_by": "4150cd20de8a470aa570a852859ac87e",
        "edited_by": [
            "4150cd20de8a470aa570a852859ac87e"
        ],
        "committed_by": "4150cd20de8a470aa570a852859ac87e",
        "entered_in_error_by": null,
        "data": {
            "narrative": "test"
        }
      }

   :query string command_uuid: The command UUID
   :reqheader Authorization: OAuth token to authenticate
   :>json string uuid: Command UUID
   :>json string state: State of the command (staged, committed or entered_in_error).
   :>json string created_at: Date when the command was created
   :>json string updated_at: Date when the command was last updated
   :>json string schema_key: Type of the command (plan, hpi, etc.)
   :>json string patient_key: Patient that the command is associated to
   :>json string note_key: Note where the command was inserted in
   :>json string originated_by: Key of the user who created the command
   :>json string edited_by: Key of the user who edited the command
   :>json string committed_by: Key of the user who committed the command
   :>json string entered_in_error_by: Key of the user who entered in error the command
   :>json dict data: Command's field values
   :statuscode 200: Success.
   :statuscode 404: Command not found.


.. http:get:: /core/api/v1/commands

   Retrieves all commands that fits the query params

   **Example request**:

      Filter committed commands for a specific patient that were created before 2024-01-05

   .. sourcecode:: http

      GET /core/api/v1/commands?patient_key=06693bde986c4b3c90049315c14d8250&state=committed&created_at__lte=2024-01-05 HTTP/1.1
      Host: example.com
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK

      {
            "count": 1,
            "next": null,
            "previous": null,
            "results": [
                {
                    "uuid": "23f9f649-7cbb-4111-ac21-72e5f16319ed",
                    "state": "committed",
                    "created_at": "2024-01-04T12:28:28.563080Z",
                    "updated_at": "2024-01-04T12:30:55.326076Z",
                    "schema_key": "plan",
                    "patient_key": "06693bde986c4b3c90049315c14d8250",
                    "note_key": "acb56588-da8f-40ea-b5b7-dd222193cd24",
                    "originated_by": "4150cd20de8a470aa570a852859ac87e",
                    "edited_by": [
                        "4150cd20de8a470aa570a852859ac87e"
                    ],
                    "committed_by": "4150cd20de8a470aa570a852859ac87e",
                    "entered_in_error_by": null,
                    "data": {
                        "narrative": "test"
                    }
                }
            ]
      }

   :query string patient_key: Key of the patient
   :query string note_key: Key of the note
   :query string originator_key: Key of the user who created the command
   :query string committer_key: Key of the user who committed the command
   :query string schema_key: Type of the command (plan, hpi, etc.)
   :query string state: State of the command (staged, committed or entered_in_error)
   :query string created_at: Date when the command was created (allows filtering before or after by adding __lt(e) or __gt(e))
   :query string updated_at: Date when the command was last updated (allows filtering before or after by adding __lt(e) or __gt(e))
   :reqheader Authorization: OAuth token to authenticate
   :>jsonarr string uuid: Command UUID
   :>jsonarr string state: State of the command (staged, committed or entered_in_error)
   :>jsonarr string created_at: Date when the command was created
   :>jsonarr string updated_at: Date when the command was last updated
   :>jsonarr string schema_key: Type of the command (plan, hpi, etc.)
   :>jsonarr string patient_key: Patient that the command is associated to
   :>jsonarr string note_key: Note where the command was inserted in
   :>jsonarr string originated_by: Key of the user who created the command
   :>jsonarr string edited_by: Key of the user who edited the command
   :>jsonarr string committed_by: Key of the user who committed the command
   :>jsonarr string entered_in_error_by: Key of the user who entered in error the command
   :>jsonarr dict data: Command's field values
   :statuscode 200: Success.


.. http:get:: /core/api/v1/commands/{command_uuid}

   Retrieves the information about a specific command

   **Example request**:

   .. sourcecode:: http

      GET /core/api/v1/commands/23f9f649-7cbb-4111-ac21-72e5f16319ed HTTP/1.1
      Host: example.com
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK

      {
        "uuid": "23f9f649-7cbb-4111-ac21-72e5f16319ed",
        "state": "committed",
        "created_at": "2024-01-04T12:28:28.563080Z",
        "updated_at": "2024-01-04T12:30:55.326076Z",
        "schema_key": "plan",
        "patient_key": "06693bde986c4b3c90049315c14d8250",
        "note_key": "acb56588-da8f-40ea-b5b7-dd222193cd24",
        "originated_by": "4150cd20de8a470aa570a852859ac87e",
        "edited_by": [
            "4150cd20de8a470aa570a852859ac87e"
        ],
        "committed_by": "4150cd20de8a470aa570a852859ac87e",
        "entered_in_error_by": null,
        "data": {
            "narrative": "test"
        }
      }

   :query string command_uuid: The command UUID
   :reqheader Authorization: OAuth token to authenticate
   :>json string uuid: Command UUID
   :>json string state: State of the command (staged, committed or entered_in_error).
   :>json string created_at: Date when the command was created
   :>json string updated_at: Date when the command was last updated
   :>json string schema_key: Type of the command (plan, hpi, etc.)
   :>json string patient_key: Patient that the command is associated to
   :>json string note_key: Note where the command was inserted in
   :>json string originated_by: Key of the user who created the command
   :>json string edited_by: Key of the user who edited the command
   :>json string committed_by: Key of the user who committed the command
   :>json string entered_in_error_by: Key of the user who entered in error the command
   :>json dict data: Command's field values
   :statuscode 200: Success.
   :statuscode 404: Command not found.


.. http:get:: /core/api/v1/commands/{command_uuid}/fields/

   Retrieves all command's fields.

   **Example request**:

      Get a plan command's schema fields

   .. sourcecode:: http

      GET /core/api/v1/commands/8839374a-f0a0-4502-a379-4b3942aba024/fields/ HTTP/1.1
      Host: example.com
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK

      {
            "schema": "plan"
            "fields": [
                {
                   "name": "narrative",
                   "type": "MultiLineTextField,
                   "required": true,
                   "choices": []
                }
            ]
      }

   :query string command_uuid: The command UUID
   :reqheader Authorization: OAuth token to authenticate
   :>json string schema: Command schema key
   :>json array<dict> fields: Command schema available fields
   :statuscode 200: Success.


.. http:get:: /core/api/v1/commands/{command_uuid}/fields/{field_name}/autocomplete/

   Retrieve response options for a specific field of a particular command.
   Utilize this information to enhance the understanding of available choices or autocomplete suggestions.

   **Example request**:

      Get ``aspirin`` medications for a medication statement command

   .. sourcecode:: http

      GET /core/api/v1/commands/affa8dc3-96b4-4b7a-8fc2-d9d5cfa0db77/fields/medication/autocomplete/?search_term=aspirin' HTTP/1.1
      Host: example.com
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK

      [
          {
              "text": "aspirin 500 mg tablet",
              "value": "{"text\": \"aspirin 500 mg tablet\", \"disabled\": false, \"description\": null, \"annotations\": null, \"extra\": {\"coding\": [{\"code\": 216092, \"display\": \"aspirin 500 mg tablet\", \"system\": \"http://www.fdbhealth.com/\"}, {\"code\": \"198471\", \"display\": \"aspirin 500 mg tablet\", \"system\": \"http://www.nlm.nih.gov/research/umls/rxnorm\"}]}, \"value\": 216092}"
          },
          {
              "text": "aspirin 325 mg tablet",
              "value": "{\"text\": \"aspirin 325 mg tablet\", \"disabled\": false, \"description\": null, \"annotations\": null, \"extra\": {\"coding\": [{\"code\": 172480, \"display\": \"aspirin 325 mg tablet\", \"system\": \"http://www.fdbhealth.com/\"}, {\"code\": \"212033\", \"display\": \"aspirin 325 mg tablet\", \"system\": \"http://www.nlm.nih.gov/research/umls/rxnorm\"}]}, \"value\": 172480}"
          }
      ]

   :query string command_uuid: The command UUID
   :query string field_name: The field name
   :query string search_term: The term to use in the search
   :reqheader Authorization: OAuth token to authenticate
   :>jsonarr string text: Display text of the option
   :>jsonarr jsonstring value: Value used to update the field
   :statuscode 200: Success.
   :statuscode 400: Field does not support autocomplete.


.. http:post:: /core/api/v1/commands/

   Create a command

   **Example request**:

   .. sourcecode:: http

      POST /core/api/v1/commands/ HTTP/1.1
      Host: example.com
      Content-Type: application/json

      { "schemaKey": "plan", "noteKey": "45b819e7-9ee0-4e2e-82a4-a90f74864f84", "values":{ "narrative": "test via api"}}

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 201 CREATED

      {
        "uuid": "c532af8b-ed51-4c99-be23-9849a219a71d",
        "state": "staged",
        "created_at": "2024-01-16T12:14:30.787243Z",
        "updated_at": "2024-01-16T12:14:30.835402Z",
        "schema_key": "plan",
        "patient_key": "2371271908f6491294d940c7d320e30c",
        "note_key": "45b819e7-9ee0-4e2e-82a4-a90f74864f84",
        "originated_by": "4150cd20de8a470aa570a852859ac87e",
        "edited_by": [
            "4150cd20de8a470aa570a852859ac87e"
        ],
        "committed_by": null,
        "entered_in_error_by": null,
        "data": {
            "narrative": "test via api"
        }
      }

   :<json string schemaKey: Type of the command (plan, hpi, etc.)
   :<json string noteKey: Key of the note where to create the command
   :<json dict values: optional values to created a command with pre-filled values.
   :reqheader Authorization: OAuth token to authenticate
   :>json string uuid: Command UUID
   :>json string state: State of the command (staged, committed or entered_in_error).
   :>json string created_at: Date when the command was created
   :>json string updated_at: Date when the command was last updated
   :>json string schema_key: Type of the command (plan, hpi, etc.)
   :>json string patient_key: Patient that the command is associated to
   :>json string note_key: Note where the command was inserted in
   :>json string originated_by: Key of the user who created the command
   :>json string edited_by: Key of the user who edited the command
   :>json string committed_by: Key of the user who committed the command
   :>json string entered_in_error_by: Key of the user who entered in error the command
   :>json dict data: Command's field values
   :statuscode 201: Created.
   :statuscode 400: Note has an invalid type or state.
   :statuscode 400: Note does not exist.


.. http:patch:: /core/api/v1/commands/{command_uuid}/

   Update a command data values.
   The ``state`` will automatically change upon committing or entering an error.
   The ``committed_by`` field will automatically update upon committing the command
   The ``entered_in_error_by`` field will automatically update when marking the command as entered in error.
   The ``edited_by`` field will automatically update when the command is modified.

   **Example request**:

   .. sourcecode:: http

      PATCH /core/api/v1/commands/c532af8b-ed51-4c99-be23-9849a219a71d/ HTTP/1.1
      Host: example.com
      Content-Type: application/json

      { "values":{ "narrative": "update this value via API"}}

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK

      {
        "uuid": "c532af8b-ed51-4c99-be23-9849a219a71d",
        "state": "staged",
        "created_at": "2024-01-16T12:14:30.787243Z",
        "updated_at": "2024-01-16T12:14:30.835402Z",
        "schema_key": "plan",
        "patient_key": "2371271908f6491294d940c7d320e30c",
        "note_key": "45b819e7-9ee0-4e2e-82a4-a90f74864f84",
        "originated_by": "4150cd20de8a470aa570a852859ac87e",
        "edited_by": [
            "4150cd20de8a470aa570a852859ac87e"
        ],
        "committed_by": null,
        "entered_in_error_by": null,
        "data": {
            "narrative": "update this value via API"
        }
      }

   :query string command_uuid: The command UUID
   :<json dict values: values to update the command with
   :reqheader Authorization: OAuth token to authenticate
   :>json string uuid: Command UUID
   :>json string state: State of the command (staged, committed or entered_in_error).
   :>json string created_at: Date when the command was created
   :>json string updated_at: Date when the command was last updated
   :>json string schema_key: Type of the command (plan, hpi, etc.)
   :>json string patient_key: Patient that the command is associated to
   :>json string note_key: Note where the command was inserted in
   :>json string originated_by: Key of the user who created the command
   :>json string edited_by: Key of the user who edited the command
   :>json string committed_by: Key of the user who committed the command
   :>json string entered_in_error_by: Key of the user who entered in error the command
   :>json dict data: Command's field values
   :statuscode 200: Success.
   :statuscode 400: Command is not staged.
   :statuscode 400: Note has an invalid type or state.


.. http:delete:: /core/api/v1/commands/{command_uuid}/

  Deletes a staged command.

  **Example request**:

  .. sourcecode:: http

      DELETE /core/api/v1/commands/c532af8b-ed51-4c99-be23-9849a219a71d/ HTTP/1.1
      Host: example.com
      Accept: application/json

  **Example response**:

  .. sourcecode:: http

      HTTP/1.1 200 OK


  :query string command_uuid: The command UUID
  :reqheader Authorization: OAuth token to authenticate
  :statuscode 200: Success.
  :statuscode 400: Note has an invalid type or state
  :statuscode 404: Command not found.


.. http:post:: /core/api/v1/commands/{command_uuid}/commit/

   Commit a staged command.

   **Example request**:

   .. sourcecode:: http

      POST /core/api/v1/commands/2af6d2b5-1547-4051-b3b5-583f1f4956c6/commit/ HTTP/1.1
      Host: example.com
      Content-Type: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK

      {
          "uuid": "2af6d2b5-1547-4051-b3b5-583f1f4956c6",
          "state": "committed",
          "created_at": "2024-01-20T09:59:25.918682Z",
          "updated_at": "2024-01-20T10:00:27.813827Z",
          "schema_key": "plan",
          "patient_key": "3b44f1387e604f86bef4b6ef56a821bd",
          "note_key": "b0a8a25c-f0bd-44a3-ae8b-31eb3e3fafea",
          "originated_by": "4150cd20de8a470aa570a852859ac87e",
          "edited_by": [
              "4150cd20de8a470aa570a852859ac87e"
          ],
          "committed_by": "4150cd20de8a470aa570a852859ac87e",
          "entered_in_error_by": null,
          "data": {
              "narrative": "this is the narrative"
          }
      }

   :query string command_uuid: The command UUID
   :reqheader Authorization: OAuth token to authenticate
   :>json string uuid: Command UUID
   :>json string state: State of the command (staged, committed or entered_in_error).
   :>json string created_at: Date when the command was created
   :>json string updated_at: Date when the command was last updated
   :>json string schema_key: Type of the command (plan, hpi, etc.)
   :>json string patient_key: Patient that the command is associated to
   :>json string note_key: Note where the command was inserted in
   :>json string originated_by: Key of the user who created the command
   :>json string edited_by: Key of the user who edited the command
   :>json string committed_by: Key of the user who committed the command
   :>json string entered_in_error_by: Key of the user who entered in error the command
   :>json dict data: Command's field values
   :statuscode 201: Created.
   :statuscode 400: Command is not staged.
   :statuscode 400: Note has an invalid type or state.


.. http:post:: /core/api/v1/commands/{command_uuid}/enter-in-error/

   Mark a committed command as entered in error

   **Example request**:

   .. sourcecode:: http

      POST /core/api/v1/commands/2af6d2b5-1547-4051-b3b5-583f1f4956c6/enter-in-error/ HTTP/1.1
      Host: example.com
      Content-Type: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK

      {
          "uuid": "2af6d2b5-1547-4051-b3b5-583f1f4956c6",
          "state": "entered_in_error",
          "created_at": "2024-01-20T09:59:25.918682Z",
          "updated_at": "2024-01-20T11:00:27.813827Z",
          "schema_key": "plan",
          "patient_key": "3b44f1387e604f86bef4b6ef56a821bd",
          "note_key": "b0a8a25c-f0bd-44a3-ae8b-31eb3e3fafea",
          "originated_by": "4150cd20de8a470aa570a852859ac87e",
          "edited_by": [
              "4150cd20de8a470aa570a852859ac87e"
          ],
          "committed_by": "4150cd20de8a470aa570a852859ac87e",
          "entered_in_error_by": "4150cd20de8a470aa570a852859ac87e",
          "data": {
              "narrative": "this is the narrative"
          }
      }

   :query string command_uuid: The command UUID
   :reqheader Authorization: OAuth token to authenticate
   :>json string uuid: Command UUID
   :>json string state: State of the command (staged, committed or entered_in_error).
   :>json string created_at: Date when the command was created
   :>json string updated_at: Date when the command was last updated
   :>json string schema_key: Type of the command (plan, hpi, etc.)
   :>json string patient_key: Patient that the command is associated to
   :>json string note_key: Note where the command was inserted in
   :>json string originated_by: Key of the user who created the command
   :>json string edited_by: Key of the user who edited the command
   :>json string committed_by: Key of the user who committed the command
   :>json string entered_in_error_by: Key of the user who entered in error the command
   :>json dict data: Command's field values
   :statuscode 201: Created.
   :statuscode 400: Command is not committed.
   :statuscode 400: Note has an invalid type or state.