Business Rule Groups
====================

.. code-block:: http

    /api/repositories/{repository}/entities/{entityID}/businessrules/{ruleID}/groups

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

    repository, string, The name of the :doc:`repository` the entity is in
    entityID, int, The ID of the :doc:`entity` the rule belongs to
    ruleID, int, The ID of the desired rule


.. _leg_show_all:

Show All
~~~~~~~~

.. http:get:: /api/repositories/(string:repository)/entities/(int:entityID)/businessrules/(int:ruleID)/groups
    :synopsis: List all groups for the business rule

    List all groups of the :ref:`business rule <ebr_show_all>` from the :doc:`repository <repository>`

.. code-block:: http

    GET /api/repositories/jupiter/entities/1/businessrules/1/groups HTTP/1.1
    Accept: application/json

If you require a subset of this data (filtering, sorting, or columns), POST to this URL with the :doc:`standard request <standard-request>` body.

:ref:`Paging <query_string_paging>` is supported for this GET request using :doc:`standard-url-query-string`.

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 is a :doc:`standard response <standard-response>`. Each datarow contains the details of a group within the rule. If :ref:`external JSON format <external_json_get>` parameter was set then each datarow will be returned in a :ref:`JSON key/value pair <external_json_response>` format.

The ``columns`` array will contain the list of columns for each data row:

The columns displayed for each group are:

.. csv-table::
    :header: Column Name, Human Name, Description
    :widths: 25, 25, 50

    "value", "Value", "Value."
    "_pass_count", "Passing Rows", "Number of Rows that Pass the Test."
    "fail_count", "Failing Rows", "Number of Rows that Pass the Test."
    "_passing_fraction", "Passing Fraction", "Percentage of Rows that pass in the Group."
    "_failing_fraction", "Failing Fraction", "Percentage of Rows that fail in the Group."
    "total", "Total Number of Rows", "Total Number of Rows in the Group."
    "aggregate_pass", "Aggregate over Passing Rows", "Aggregate over the Passing Rows in the Group."
    "aggregate_fail", "Aggregate over Failing Rows", "Aggregate over the Failing Rows in the Group."

The ``rows`` array will contain one element for each group requested, returned in a :ref:`internal JSON format <internal_json_response>` format:

.. code-block:: json

    {
        "rows": [
            {
                "dataRow": [
                    "B",
                    "485",
                    "2",
                    "99.589",
                    "0.411",
                    "487",
                    "",
                    ""
                ]
            },
            {
                "dataRow": [
                    "Lloyds UTC Bank",
                    "1",
                    "0",
                    "100",
                    "0",
                    "1",
                    "",
                    ""
                ]
            },
            {
                "dataRow": [
                    "R",
                    "1103",
                    "13",
                    "98.835",
                    "1.165",
                    "1116",
                    "",
                    ""
                ]
            }
        ]
    }


If :ref:`external JSON format <external_json_get>` parameter was set then the data rows in a :ref:`JSON key/value pair <external_json_response>` will be returned as follows:

.. code-block:: json

    {
        "rows": [
            {
                "Value": "B",
                "Passing Rows": "485",
                "Failing Rows": "2",
                "Passing Fraction": "99.589",
                "Failing Fraction": "0.411",
                "Total Number of Rows": "487",
                "Aggregate over Passing Rows": "",
                "Aggregate over Failing Rows": ""
            },
            {
                "Value": "Lloyds UTC Bank",
                "Passing Rows": "1",
                "Failing Rows": "0",
                "Passing Fraction": "100",
                "Failing Fraction": "0",
                "Total Number of Rows": "1",
                "Aggregate over Passing Rows": "",
                "Aggregate over Failing Rows": ""
            },
            {
                "Value": "R",
                "Passing Rows": "1103",
                "Failing Rows": "13",
                "Passing Fraction": "98.835",
                "Failing Fraction": "1.165",
                "Total Number of Rows": "1116",
                "Aggregate over Passing Rows": "",
                "Aggregate over Failing Rows": ""
            }
        ]
    }


.. _leg_show_group:

Show Group
~~~~~~~~~~

.. http:post:: /api/repositories/(string:repository)/entities/(int:entityID)/businessrules/(int:ruleID)/groups
    :synopsis: List a specific group for the :ref:`business rule <ebr_show_all>`


The POST request requires a :doc:`standard request <standard-request>` to identify the group to show, and to specify any options.

.. code-block:: http

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

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

The group name may contain spaces or be an empty string.

Group name is empty:

.. code-block:: http

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

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

Group name is a single space:

.. code-block:: http

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

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

Group name contains spaces:

.. code-block:: http

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

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

The response is a :doc:`standard-response`. The ``rows`` array will contain a single element. See :ref:`leg_show_all` above.


.. _leg_export:

Export Group
~~~~~~~~~~~~

.. http:post:: /api/repositories/(string:repository)/entities/(int:entityID)/businessrules/(int:ruleID)/groups
    :synopsis: Export the list of groups to a file

.. code-block:: http

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

    {
        "command": "export",
        "data": {
            "filename": "filename.csv"
        }
    }

When export is required, the filename for the exported file must be specified. The file will be exported in CVS 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 for a get is a :doc:`standard-response`, with the details of the groups of the :ref:`business rule <ebr_show_all>`.

The response for an export 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"
    }