Business Rule Group - Failing Rows
==================================

.. http:get:: /api/repositories/(string:repository)/entities/(int:entityID)/businessrules/(int:ruleID)/groups/(string:groupName)/failingrows
    :synopsis: Get all rows in a group that failed the rule

    Get all the rows in a group that failed the rule.

.. http:post:: /api/repositories/(string:repository)/entities/(int:entityID)/businessrules/(int:ruleID)/groups/(string:groupName)/failingrows
    :synopsis: List, filter, sort or export the rows in a group that failed the rule

    + Filter the list of failing rows
    + Sort the list of failing rows
    + Page the list of failing rows
    + Export the failing rows


.. csv-table::
    :header: Parameter, Type, Purpose
    :widths: 20, 20, 60
    :stub-columns: 1

    repository, string, The name of the :doc:`repository` to access
    entityID, int, The ID of the entity to view
    ruleID, int, The ID of the desired rule
    groupName, string, The name of the group


.. _brgfr_all:

All Failing Rows
~~~~~~~~~~~~~~~~

Show all failing rows in a group for the given rule.

.. code-block:: http

    GET /api/repositories/alpha/entities/1/businessrules/1/groups/B/failingrows HTTP/1.1
    Accept: application/json

:ref:`Paging <query_string_paging>` is supported for this GET request using :doc:`standard-url-query-string`. Depending on the rule and the dataset, the number of failing rows may be quite large, so paging the data is recommended.

The underlying data rows can be returned in a :ref:`JSON key/value pair <external_json_response>` by setting the :ref:`external JSON format <external_json_get>` parameter. This allows access by different external tools that requires the JSON data in a key/value pair instead of standard array of row data with columns names defined separately.

The response for a get is a :doc:`standard response <standard-response>` containing a list of all the rows that fail the business rule. If :ref:`external JSON format <external_json_get>` parameter was set then each datarow for a list of the rows in the group that failed the business rule will be returned in a :ref:`JSON key/value pair <external_json_response>` format.


.. _brgfr_specificgrp:

Failing Rows for a Specific Group
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Show all failing rows a given group for a particular rule. Use this API when group name is an empty string, a single space or multiple spaces.

.. code-block:: http

    POST /api/repositories/alpha/entities/1/businessrules/1/groups/failingrows HTTP/1.1
    Content-type:: application/json

    {
        "command": "get",
        "data": {
            "groupName": ""
        }
    }

The ``groupName`` can be any string name, including an empty string, a single space or multiple spaces.

The response is a :doc:`standard-response` containing the list of passing rows matching the criteria.


.. _brgfr_some:

Some Failing Rows
~~~~~~~~~~~~~~~~~

The list of failing rows can be filtererd, sorted or paged; these options may be combined (for example, sorted and paged). The request requires a :doc:`standard-request`.

The underlying data rows can be returned in a :ref:`JSON key/value pair <external_json_response>` by setting the :ref:`external JSON format <external_json_post>` parameter. This allows access by different external tools that requires the JSON data in a key/value pair instead of standard array of row data with columns names defined separately.

.. code-block:: http

    POST /api/repositories/jupiter/entities/1/businessrules/1/groups/B/failingrows HTTP/1.1
    Content-type:: application/json

    {
        "command": "get",
        "options": {
            "pageStart": 1,
            "pageSize": 10
        }
    }

The response is a :doc:`standard-response` containing the list of failing rows matching the criteria. If :ref:`external JSON format <external_json_post>` parameter was set then each datarow for a list of failing rows matching the criteria will be returned in a :ref:`JSON key/value pair <external_json_response>` format.


.. _brgfr_export:

Export Failing Rows
~~~~~~~~~~~~~~~~~~~

Some or all of the failing rows may be exported as a scheduled task.

.. code-block:: http

    POST /api/repositories/jupiter/entities/1/businessrules/1/groups/B/failingrows HTTP/1.1
    Content-type:: application/json

    {
        "command": "export",
        "options": {
            "columns": [
                "column_name1",
                "column_name2",
                "column_name3"
            ],
            "where": "where clause"
        },
        "data": {
            "filename": "filename.csv"
        }
    }

When export is required, the filename for the exported file must be specified. The file will be exported in CSV format using the native encoding of the server.

.. csv-table::
    :header: Response Code, Reason
    :widths: 25, 75

    200, No error
    500, Server error

The response will contain the URL of the scheduled task and the link to download the exported file.

.. code-block:: json

    {
        "job": "/api/repositories/jupiter/scheduler/1",
        "file": "/api/repositories/jupiter/download/filename.csv"
    }

.. _brgfr_export_specificgrp:

Export Failing Rows for a Specific Group
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some or all of the failing rows may be exported as a scheduled task for a given group for a particular rule. Use this API when group name is an empty string, a single space or multiple spaces.

.. code-block:: http

    POST /api/repositories/jupiter/entities/1/businessrules/1/groups/failingrows HTTP/1.1
    Content-type:: application/json

    {
        "command": "export",
        "options": {
            "columns": [
                "column_name1",
                "column_name2",
                "column_name3"
            ],
            "where": "where clause"
        },
        "data": {
            "filename": "filename.csv"
            "groupName": ""
        }
    }

When export is required, the filename for the exported file must be specified. The file will be exported in CSV format using the native encoding of the server.

The ``groupName`` can be any string name, including an empty string, a single space or multiple spaces.

.. csv-table::
    :header: Response Code, Reason
    :widths: 25, 75

    200, No error
    500, Server error

The response will contain the URL of the scheduled task and the link to download the exported file.

.. code-block:: json

    {
        "job": "/api/repositories/jupiter/scheduler/1",
        "file": "/api/repositories/jupiter/download/filename.csv"
    }