Library Entity Commands
=======================

The commands that can be performed against a :doc:`library entity <libraryentity>` (or :doc:`library entities <libraryentities>`) are as follows:

.. csv-table::
    :header: Command, Purpose
    :widths: 20, 80

    :ref:`edit <lec_edit>`, Edit an existing :doc:`library entity <libraryentity>`
    :ref:`disassociate <lec_disassociate>`,Disassociate :doc:`library entities <libraryentities>` from :doc:`entities <entity>`
    :ref:`associate <lec_associate>`, Associate :doc:`library entities <libraryentities>` with :doc:`entities <entity>`
    :ref:`promote <lec_promote>`, Promote business rules from an entity to a :doc:`library entity <libraryentity>`
    :ref:`import <lec_import>`, Import one or more :doc:`library entity <libraryentity>` business rules
    :ref:`export <lec_export>`, Export one or more :doc:`library entities <libraryentities>`


Glossary
~~~~~~~~

Abbreviations used in this document:

.. csv-table::
    :header: Term, Meaning
    :widths: 30, 70

    EID, Entity ID (integer)
    LID, Library ID (integer)
    RAID, Real Attribute ID (integer)
    LAID, Library Attribute ID (integer)
    EBR, Entity Business Rule


.. _lec_edit:

Edit
~~~~

To edit a :doc:`library entity <libraryentity>`, the request may contain the fields below:

.. code-block:: json

    {
        "name": "library name",
        "description": "description for the library"
    }

The data element may contain one or both of two key-value pairs:

.. csv-table::
    :header: Key, Purpose
    :widths: 30, 70

    name, The new name of the entity
    description, The new description for the entity

If the command is successful, the response will have no body.


.. _lec_disassociate:

Disassociate
~~~~~~~~~~~~

The disassociate command may either disassociate a :doc:`library entity <libraryentity>` from one or more real :doc:`entities <entity>` or one or more :doc:`library entities <libraryentity>` from a real :doc:`entity <entity>`.

To disassociate a :doc:`library entity <libraryentity>` from one or more real :doc:`entities <entity>`, the request would look like:

.. code-block:: http

    POST /api/repositories/jupiter/library/entities/1 HTTP/1.1
    Content-Type: application/json

    {
        "command": "disassociate",
        "data": {
            "library": "3",
            "entity": [
                "1", "2"
            ],
            "deleteRules": "1"
        }
    }

The ``library`` and ``entity`` fields are required.
The ``deleteRules`` field is optional. If set to 1, all the rules will be deleted from the corresponding real :doc:`entities <entity>` after disassociation.

All the real :doc:`entities <entity>` specified in the ``entity`` array will be disassociated from the :doc:`library entity <libraryentity>` specified in the ``library`` field.

To disassociate one or more :doc:`library entities <libraryentity>` from a real :doc:`entity <entity>`, the request would look like:

.. code-block:: http

    POST /api/repositories/jupiter/library/entities HTTP/1.1
    Content-Type: application/json

    {
        "command": "disassociate",
        "data": {
            "entity": "1",
            "library": [
                "2", "3"
            ],
            "deleteRules": "1"
        }
    }

The ``entity`` and ``library`` fields are required.
``deleteRules`` field is optional. If set to 1, all the rules will be deleted from the corresponding real :doc:`entity <entity>` after disassociation.

All :doc:`library entities <libraryentities>` specified in the ``library`` array will be disassociated from the real :doc:`entity <entity>` specified in the ``entity`` field.

A job is scheduled to run the disassociation in the background; the response to the request will contain the URL of the scheduled task.

.. code-block:: json

    {
        "url": "/api/repositories/jupiter/scheduler/45"
    }


.. _lec_associate:

Associate
~~~~~~~~~~

The associate command may either associate a :doc:`library entity <libraryentity>` with one or more real :doc:`entities <entity>` or one or more :doc:`library entities <libraryentity>` with a real :doc:`entity <entity>`.

To associate a :doc:`library entity <libraryentity>` with one or more real :doc:`entities <entity>`, the request would look like:

.. code-block:: http

    POST /api/repositories/jupiter/library/entities/1 HTTP/1.1
    Content-Type: application/json

    {
        "command": "associate",
        "data": {
            "library": "1",
            "entity": [
                {
                    "id": "2",
                    "mapping": [
                        {
                            "realAttr": "1",
                            "libAttr": "1"
                        }
                    ]
                }
            ]
        }
    }

The ``library`` and ``entity`` fields are required.

``library`` should contain the library ID of the :doc:`library entity <libraryentity>` to associated with the :doc:`entities <entity>`.

``entity`` is an array; each element contains an entity ID and the attributes to be mapped.

``mapping`` is an array of real and library attribute IDs to be mapped. All the real :doc:`entities <entity>` specified in the ``entity`` array will be associated with the :doc:`library entity <libraryentity>` specified in the ``library`` field.

To associate one or more real :doc:`entities <entity>` to a :doc:`library entity <libraryentity>`, the request would look like:

.. code-block:: http

    POST /api/repositories/jupiter/library/entities HTTP/1.1
    Content-Type: application/json

    {
        "command": "associate",
        "data": {
            "entity": "1",
            "library": [
                {
                    "id": "2",
                    "mapping": [
                        {
                            "realAttr": "2",
                            "libAttr": "1"
                        }
                    ]
                }
            ]
        }
    }

The ``entity`` and ``library`` fields are required.

``entity`` will contain the entity ID of a real :doc:`entity <entity>` to associate with the :doc:`library entities <libraryentity>` in ``library``.

``library`` is an array; each element contains a library ID and the attributes to be mapped.

``mapping`` is an array of real and library attribute IDs to be mapped. The real :doc:`entity <entity>` specified in ``entity`` field will be associated with the :doc:`library entities <libraryentity>` specified in the ``library`` array.

A job is scheduled to run the association in the background; the response to the request will contain the URL of the scheduled task.

.. code-block:: json

    {
        "url": "/api/repositories/jupiter/scheduler/43"
    }


.. _lec_promote:

Promote
~~~~~~~~

The Promote command is used to promote one or more :doc:`business rules <businessrule>` from a real :doc:`entity <entity>` to a :doc:`library entity <libraryentity>`.

To promote one or more :doc:`rules <businessrule>` to a new :doc:`library entity <libraryentity>`, the request would look like:

.. code-block:: json

    {
        "command": "promote",
        "data": {
            "entity": "1",
            "rules": ["1", "2"],
            "library": {
                "name": "my library",
                "description": "my business rules library"
            },
            "operation": "COPY",
            "mapping" : [
                {
                    "realAttr": "1",
                    "libAttrName": "lib attribute"
                }
            ]
        }
    }

To promote one or more :doc:`rules <businessrule>` to an existing :doc:`library entity <libraryentity>`, the request would look like:

.. code-block:: json

    {
        "command": "promote",
        "data": {
            "entity": "1",
            "rules": ["1", "2"],
            "library": {
                "id": "2"
            },
            "operation": "ASSOC",
            "mapping" : [
                {
                    "realAttr": "1",
                    "libAttr": "1"
                }
            ]
        }
    }

The ``library``, ``entity``, ``rules`` and ``operation`` fields are required. The ``mapping`` field is optional.

``entity`` should contain the entity ID of the real :doc:`entity <entity>` where the :doc:`rules <businessrule>` are defined.

``library`` should contain the library ID of the :doc:`library entity <libraryentity>` to which the :doc:`rules <businessrule>` will be promoted.

.. code-block:: json

    {
        "library": {
            "id": "2"
        }
    }

To promote the rules to a new :doc:`library entity <libraryentity>`, ``LIBRARY`` should contain the ``NAME`` and ``DESCRIPTION`` of the new :doc:`library entity <libraryentity>`.

.. code-block:: json

    {
        "library": {
            "name": "lib1",
            "description": "my library"
        }
    }

``operation`` can be one of the three following options:

.. csv-table::
    :header: Value, Purpose
    :widths: 20, 80

    COPY, Copy rules to a model entity. The ``mapping`` field is required in this case
    ASSOC, Promote rules to the library and associate entity to the library entity
    MOVE, Promote rules to the library entity and delete original rules from the entity

For existing library attributes, ``mapping`` is an array of real and library attribute IDs to be mapped.

.. code-block:: json

    {
        "mapping" : [
            {
                "realAttr": "1",
                "libAttr": "1"
            }
        ]
    }

For a new :doc:`library entity <libraryentity>`, ``mapping`` should be an array of real attribute ID and library attribute name. All the real :doc:`entities <entity>` specified in the ``entity`` field will be associated with the :doc:`library entity <libraryentity>` specified in the ``library`` field.

.. code-block:: json

    {
        "mapping" : [
            {
                "realAttr": "1",
                "libAttrName": "library attribute"
            }
        ]
    }


.. _lec_import:

Import
~~~~~~

To import one or more :doc:`library entity <libraryentity>` :doc:`business rules <businessrule>`, the request will look like:

.. code-block:: json

    {
        "command": "import",
        "data": {
            "filenames": ["library1.ebr", "library2.ebr", "library3.ebr"],
            "importType": "SERVER",
            "fileType": "ebr"
        }
    }

The ``filenames`` field is required; it should contain a list of the names of the EBR/XML/JSON file(s) to be imported. It should include the virtual path on the server where it resides. Please note that when importing a JSON file you must only specify a single JSON file to import:

.. code-block:: json

    {
        "command": "import",
        "data": {
            "filenames": ["library.json"],
            "importType": "SERVER",
            "fileType": "json"
        }
    }

The ``importType`` field is optional; it specifies whether the user wants to import the rules from the server file system or local filesystem. The values can be ``SERVER`` or ``CLIENT``. Default value is ``SERVER``.

The ``fileType`` field is required; the supported file types are: ebr, xml and json.

If the import is successful, a link to the import job scheduled will be returned to the client. For example:

.. code-block:: json

    {
        "url": "/api/repositories/jupiter/scheduler/202"
    }

If you are importing rules from the local filesystem, you must first call :doc:`upload <upload>` to upload the file to the server. The return value of this call should be passed in as the value of ``filenames`` field. See the :doc:`upload` for more details.

The :doc:`file upload <upload>` uploads files to a temporary location and the files will be removed from that location once import is done, if ``importType`` is ``CLIENT``.


.. _lec_export:

Export
~~~~~~

One or more :doc:`entities <libraryentity>` can be exported from the library using the ``export`` command. The export may be a scheduled task.

.. code-block:: json

    {
        "command": "export",
        "data": {
            "filename": "myrules",
            "fileType":"ebr",
            "libEntity": ["2", "3", "4"]
        }
    }

The ``filename`` value is required; it does not need to include the path.

The ``fileType`` value is required; the supported file types are: ``ebr``, ``xml`` and ``json``.

If the ``fileType`` is ``json``, the export will happen as a foreground task; if the ``fileType`` is ``xml`` or ``ebr``, the export will happen as a scheduled task.

The ``libEntity`` list is optional if the :doc:`library entity <libraryentity>` ID is given in the URL. If ``libEntity`` is present, it should contain one or more :doc:`library entity <libraryentity>` IDs to be exported. If the ``fileType`` is ``json``, only a single :doc:`library entity <libraryentity>` ID is supported.

The table below shows all the fields that are available for edit:

.. csv-table::
    :header: Field, Description, Values
    :widths: 20, 25, 55

    filename, Export Filename
    fileType, Supported Export Format, ``ebr`` ``xml`` ``json``
    libEntity, Library Entity ID(s)

If the export is successful and the ``fileType`` is ``json``, an array of link(s) to download the exported file is returned to the client. For example:

.. code-block:: json

    [
        "/api/repositories/jupiter/download/myrules-LibInput-10.json"
    ]

If the ``fileType`` is ``xml`` or ``ebr``, a link to the scheduled task is returned to the client.

.. code-block:: json

    {
        "url": "/api/repositories/jupiter/scheduler/462"
    }

Once the scheduled task is complete, the exported file (or files) can be viewed using the :doc:`file endpoint <listfiles>`  and subsequently downloaded using the :doc:`download <download>` endpoint.

For an export in ``xml`` or ``json`` format, the :doc:`library entity <libraryentity>` name and ID will be appended to the filename; any white space in the name will be replaced with "_", as filenames with spaces are not supported when importing library business rules.

For example:

.. code-block:: json

    [
        "/api/repositories/jupiter/download/myrules-Branches-2.xml",
        "/api/repositories/jupiter/download/myrules-Services-3.xml",
        "/api/repositories/jupiter/download/myrules-Sales_Person-4.xml"
    ]


.. _lec_unused:

Delete Unused Attributes
~~~~~~~~~~~~~~~~~~~~~~~~

To delete unused attributes from :doc:`library entity <libraryentity>`, the request may contain the fields below:

.. code-block:: json

    {
        "command": "deleteUnusedAttributes",
        "data": {
            "libEntity": ["lid1", "lid2", "lidN"]
        }
    }



The ``libEntity`` list is optional. If ``libEntity`` is present, it should contain one or more :doc:`library entity <libraryentity>` IDs to be exported. IF libEntity is not present, it will be fetched from the url.

If the command is successful, the response will have no body.