﻿eLogbook@openK - Backend REST-Service documentation
===================================================
:Author: Frank Dietrich
:Email: frank.dietrich@pta.de
:Date: 2017-07-12
:Revision: 1
:icons:
:source-highlighter: highlightjs
:highlightjs-theme: solarized_dark


== Base-URL
[source,text]
----
http://<host>:<port>/<name-of-war>/rest/beservice
----
{blank}

== Common Features
All services may return the following http status codes:

.Http-Status-Codes
[options="header,footer"]
|=========================================================
|Code|Description|Usage within the application
|200|OK|-
|400|Bad Request|The structure of the request (for example a JSON within a post request) is not correct
|401|Unauthorized|Login-credentials are wrong or there is an invalid session token
|404|Not found|A resource cannot be found (for example trying to get an entity with an invalid id)
|423|Locked|A resource is locked, because another user has blocked it
|500|Internal Server Error|An unexpected error occurred
|=========================================================

If there is a special service behavior regarding the returned http status code, then it will be explained within the service description.

== Protection
There are two components that are involved, for the authentication of the services:

 . HTTP-Header-Parameter: Authorization

The “login”-services provides both tokens, when called with valid user-credentials. The client of the service has to pass over a valid Authorization, which belongs to Cookie. Other the protected services will come back with a 401-Unauthorized HTTP-Status code.

The protection of a service can be

* None  (The service is unprotected)
* Normal (The service is available for all logged in users)
* High (The service is only available for administrators)

The backend server itself determines the secure level of the session. All services that have a
protection which is not “None” need to provide “Authorization” and “COOKIESESSION-TOKEN”!

== General Services
=== Receive Version Information
This service returns the current version of the backend implementation and the version of the database structure.

*URL:* /versionInfo

*Method:* GET

*Request-Headers*:

*Produces*: application/json

*Response*:
[source,json]
----
{
    "dbVersion": "0.1.1_Snapshot",
    "backendVersion": "0.1.1-Snapshot"
}
----
{blank}

*Protection*: none

*Remarks*:

=== Login
This service receives login credentials in order to perform the authentication. If the login succeeds,
it provides the session-token and a session cookie, used for accessing other services later on.

*URL:* /login

*Method:* POST

*Request-Headers*:

* Authorization (Optional) – Existing JWT token

*Request-Body*:
[source,json]
----
{
  "userName": "Mustermann",
  "password": "clearpassword"
}
----
{blank}

*Produces*: application/json

*Response-Headers*:

* Authorization - JWT token
* COOKIESESSION-TOKEN - session cookie

*Response*:
[source,json]
----
{
    "id": 1,
    "selected": false,
    "username": "Mustermann",
    "name": "Max Mustermann",
    "specialUser": false
}
----
{blank}

*Protection*: none

*Remarks*: The response headers are only returned when the login was successful.


=== Logout
This services kills the server session belonging to the the given session token.

*URL:* /logout

*Method:* POST

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:

*Protection*: normal

*Remarks*:

=== Observer Control
This service checks if the authenticated session user is an observer(he has no responsibilities).

*URL:* /isObserver

*Method:* GET

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
{
    true
}
----
{blank}

*Protection*: normal

*Remarks*:

== Master Data Services

=== Receive Notification Statuses
This service returns an array of available notification statuses.

*URL:* /notificationStatuses

*Method:* GET

*Request-Headers*:

*Produces*: application/json

*Response*:
[source,json]
----
[
    {
        "id": 1,
        "name": "offen"
    },
    {
        "id": 2,
        "name": "in Arbeit"
    },
    {
        "id": 3,
        "name": "erledigt"
    },
    {
        "id": 4,
        "name": "geschlossen"
    }
]
----
{blank}

*Protection*: none

*Remarks*:

=== Receive Branches
This service returns an array of available notification statuses.

*URL:* /branches

*Method:* GET

*Request-Headers*:

*Produces*: application/json

*Response*:
[source,json]
----
[
    {
        "id": 1,
        "name": "S",
        "description": "Strom"

    },
    {
        "id": 2,
        "name": "G",
        "description": "Gas"

    },
     ...
]
----
{blank}

*Protection*: none

*Remarks*:

=== Receive GridTerritories
This service returns an array of available grid territories.

*URL:* /gridTerritories

*Method:* GET

*Request-Headers*:

*Produces*: application/json

*Response*:
[source,json]
----
[
    {
        "id": 1,
        "name": "MA",
        "description": "Mannheim",
        "fk_ref_master": 1

    },
    {
        "id": 2,
        "name": "OF",
        "description": "Offenbach",
        "fk_ref_master": 1

    },
    ...
]
----
{blank}

*Protection*: none

*Remarks*:

== Application Services
=== Receive Responsibilities
This service returns the responsibilities for the authenticated session user.

*URL:* /currentResponsibilities

*Method:* GET

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
[
    {
        "gridTerritoryDescription": "Mannheim",
        "responsibilityList": [
            {
                "id": 1,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "S",
                "isActive": true
            },
            {
                "id": 2,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "G",
                "isActive": true
            }
        ]
    },
    {
        "gridTerritoryDescription": "Offenbach",
        "responsibilityList": [
            {
                "id": 4,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "G",
                "isActive": true
            }
        ]
    }
]
----
{blank}

*Protection*: normal

*Remarks*:

=== Receive Planned Responsibilities
This service returns the planned responsibilities for the authenticated session user.

*URL:* /plannedResponsibilities

*Method:* GET

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
[
    {
        "gridTerritoryDescription": "Mannheim",
        "responsibilityList": [
            {
                "id": 1,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "S",
                "isActive": true
            },
            {
                "id": 2,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "G",
                "isActive": true
            }
        ]
    },
    {
        "gridTerritoryDescription": "Offenbach",
        "responsibilityList": [
            {
                "id": 4,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "G",
                "isActive": true
            }
        ]
    }
]
----
{blank}

*Protection*: normal

*Remarks*:

=== Receive All Responsibilities
This service returns all the responsibilities.

*URL:* /allResponsibilities

*Method:* GET

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
[
    {
        "gridTerritoryDescription": "Offenbach",
        "responsibilityList": [
            {
                "id": 5,
                "responsibleUser": "hugo",
                "branchName": "F",
                "isActive": true
            },
            {
                "id": 4,
                "responsibleUser": "admin",
                "newResponsibleUser": "otto",
                "branchName": "G",
                "isActive": true
            },
            {
                "id": 7,
                "responsibleUser": "admin",
                "newResponsibleUser": "otto",
                "branchName": "S",
                "isActive": true
            },
            {
                "id": 8,
                "responsibleUser": "hugo",
                "branchName": "W",
                "isActive": true
            }
        ]
    },
    {
        "gridTerritoryDescription": "Mannheim",
        "responsibilityList": [
            {
                "id": 1,
                "responsibleUser": "admin",
                "newResponsibleUser": "hugo",
                "branchName": "S",
                "isActive": true
            },
            {
                "id": 3,
                "responsibleUser": "admin",
                "newResponsibleUser": "otto",
                "branchName": "F",
                "isActive": true
            },
            {
                "id": 6,
                "responsibleUser": "admin",
                "newResponsibleUser": "hugo",
                "branchName": "W",
                "isActive": true
            },
            {
                "id": 2,
                "responsibleUser": "hugo",
                "branchName": "G",
                "isActive": true
            }
        ]
    }
]
----
{blank}

*Protection*: normal

*Remarks*:

=== Receive Historical Responsibilities
This service returns the responsibility history of a specific-given version.

*URL:* /historicalResponsibilities/{transactionId}

*Method:* GET

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
[
    {
        "id": 2,
        "responsibleUser": "hugo",
        "formerResponsibleUser": "max",
        "transferDate": "2017-08-04T08:53:27.502Z",
        "transactionId": 1,
        "createDate": "2017-06-19T12:34:35.881Z",
        "createUser": "admin",
        "modDate": "2017-08-04T08:53:27.502Z",
        "modUser": "hugo",
        "refGridTerritory": {
            "id": 1,
            "fkRefMaster": 1,
            "description": "Mannheim",
            "name": "MA"
        },
        "refBranch": {
            "id": 3,
            "name": "F",
            "description": "Fernwärme"
        }
    },
    {
        "id": 3,
        "responsibleUser": "hugo",
        "formerResponsibleUser": "admin",
        "transferDate": "2017-08-04T08:53:27.502Z",
        "transactionId": 1,
        "createDate": "2017-06-19T11:14:38.525Z",
        "createUser": "Otto",
        "modDate": "2017-08-04T08:53:27.502Z",
        "modUser": "hugo",
        "refGridTerritory": {
            "id": 2,
            "fkRefMaster": 2,
            "description": "Offenbach",
            "name": "OF"
        },
        "refBranch": {
            "id": 3,
            "name": "F",
            "description": "Fernwärme"
        }
    },
    {
        "id": 4,
        "responsibleUser": "hugo",
        "formerResponsibleUser": "admin",
        "transferDate": "2017-08-04T08:53:27.502Z",
        "transactionId": 1,
        "createDate": "2017-06-19T11:14:38.532Z",
        "createUser": "Otto",
        "modDate": "2017-08-04T08:53:27.502Z",
        "modUser": "hugo",
        "refGridTerritory": {
            "id": 1,
            "fkRefMaster": 1,
            "description": "Mannheim",
            "name": "MA"
        },
        "refBranch": {
            "id": 4,
            "name": "W",
            "description": "Wasser"
        }
    },
    {
        "id": 5,
        "responsibleUser": "hugo",
        "formerResponsibleUser": "otto",
        "transferDate": "2017-08-04T08:53:27.502Z",
        "transactionId": 1,
        "createDate": "2017-07-24T11:13:00.000Z",
        "createUser": "admin",
        "modDate": "2017-08-04T08:53:27.502Z",
        "modUser": "hugo",
        "refGridTerritory": {
            "id": 2,
            "fkRefMaster": 2,
            "description": "Offenbach",
            "name": "OF"
        },
        "refBranch": {
            "id": 4,
            "name": "W",
            "description": "Wasser"
        }
    }
]
----
{blank}

*Protection*: normal

*Remarks*:

=== Create Notification
This service creates a new notification in the database. It returns the same entity which the Ids and the version provided by the database.

*URL:* /notifications/create

*Method:* PUT

*Request-Headers*:

* Authorization – Existing JWT token

*Consumes*: application/json

*Request*:
[source,json]
----
{
  "status": "offen",
  "notificationText": null,
  "freeText": "",
  "freeTextExtended": "extended",
  "responsibilityForwarding": "",
  "responsibilityControlPoint": "Abteilung 4",
  "reminderDate": null,
  "futureDate": null,
  "createdDate": "2017-03-09T15:27:17",
  "expectedFinishDate": null,
  "finishedDate": null,
  "creator": "MasterAndCreator",
  "modDate": "2017-03-09T15:27:17",
  "modUser": "_fd",
  "fkRefBranch": 1,
  "fkRefNotificationStatus": 2,
  "fkRefGridTerritories": 2
}
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
{
    "id": 27,
    "incidentId": 18,
    "version": 1,
    "selected": false,
    "status": "in Arbeit",
    "notificationText": "Meldung X:Y",
    "freeText": "",
    "freeTextExtended": "extended",
    "responsibilityForwarding": "",
    "responsibilityControlPoint": "Abteilung 4",
    "createdDate": "2017-03-09T15:27:17",
    "creator": "MasterAndCreator",
    "modDate": "2017-03-09T15:27:17",
    "modUser": "_fd",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 2,
	"fkRefGridTerritories": 1
}
----
{blank}

*Protection*: normal

*Remarks*:

=== Update Notification
This service stores a modified notification by inserting a new version of it into the database.  It returns the same
entity with a new version number and the user modifications.

*URL:* /notifications/update

*Method:* POST

*Request-Headers*:

* Authorization – Existing JWT token

*Consumes*: application/json

*Request*:
[source,json]
----
{
    "id": 27,
    "incidentId": 18,
    "version": 1,
    "selected": false,
    "status": "in Arbeit",
    "notificationText": "Meldung X:Y",
    "freeText": " Meldung ergänzt um diesen Text ",
    "freeTextExtended": "extended",
    "responsibilityForwarding": "",
    "responsibilityControlPoint": "Abteilung 4",
    "createdDate": "2017-03-09T15:27:17",
    "creator": "MasterAndCreator",
    "modDate": "2017-03-09T15:27:17",
    "modUser": "_fd",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 2
}
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
{
    "id": 31,
    "incidentId": 18,
    "version": 2,
    "selected": false,
    "status": "in Arbeit",
    "notificationText": "Meldung X:Y",
    "freeText": "Meldung ergänzt um diesen Text",
    "freeTextExtended": "extended",
    "responsibilityForwarding": "",
    "responsibilityControlPoint": "Abteilung 4",
    "createdDate": "2017-03-09T15:27:17",
    "creator": "MasterAndCreator",
    "modDate": "2017-03-09T15:27:17",
    "modUser": "_fd",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 2
}
----
{blank}

*Throws*: BtbLocked (Http StatusCode: 423) : Is thrown if the notification status is locked and the service is called

*Protection*: normal

*Remarks*:

=== Get Notification
This retrieves a notification from the database.

*URL:* /notification/{id}

*Method:* GET

*Path-Parameter*: id

* The primary key of the notification

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
{
    "id": 27,
    "incidentId": 18,
    "version": 2,
    "selected": false,
    "status": "in Arbeit",
    "notificationText": "Meldung X:Y",
    "freeText": "Meldung ergänzt um diesen Text",
    "freeTextExtended": "extended",
    "responsibilityForwarding": "",
    "responsibilityControlPoint": "Abteilung 4",
    "createdDate": "2017-03-09T15:27:17",
    "creator": "MasterAndCreator",
    "modDate": "2017-03-09T15:27:17",
    "modUser": "_fd",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 2
}
----
{blank}

*Protection*: normal

*Remarks*:

=== Get Notifications
This service retrieves a list of notifications from the database. The selection is based on the given filter-object.
With no filter value specified, the collection returned contains all active notifications. With filter value(s) set, only
notifications matching the filter values are returned.

The following list explains the available filter values:

* The filter-values “dateFrom” and “dateTo” are compared against the “begin_date” of the notifications (closed interval).
* The filter values in "responsibilityFilterList" are compared against the id of the notifications.
* If the boolean filter value "historicalFlag" is "true" historical notifcations are returned.
* If the boolean filter value is null or "false", active notifications are returned.
* With historicalFlag set, the corresponding "shiftChangeTransactionId must also be set to obtain a valid result. In this
case, other filter values do not make sense and are not evaluated.

*URL:* /notifications/{listType}

*Method:* POST

*Path-Parameters*:

* listType - The type of the list for which the data will be loaded: "PAST", "OPEN", "FUTURE"

*Request-Headers*:

* Authorization – Existing JWT token


*Consumes*: application/json

*Request*:
[source,json]
----
{
  "dateFrom": "2017-03-09T15:27:17.666Z",
  "dateTo": "2017-04-09T15:27:17.666Z",
    "responsibilityFilterList": [
                                    1, 6
                                ]
}
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
[
  {
    "id": 1161,
    "incidentId": 337,
    "version": 10,
    "selected": false,
    "status": "in Arbeit",
    "beginDate": "2017-05-24T07:11:00.000Z",
    "notificationText": "UW4 Wartungsarbeiten LSA",
    "freeText": "Hr. xxx vor Ort",
    "freeTextExtended": "Hr.yyy ist auch vor Ort",
    "responsibilityForwarding": "Müller",
    "responsibilityControlPoint": "Administrator",
    "expectedFinishDate": "2017-05-24T14:00:00.000Z",
    "createUser": "admin",
    "createDate": "2017-05-24T07:03:54.429Z",
    "modDate": "2017-08-18T14:15:10.355Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 2,
    "fkRefGridTerritory": 1,
    "adminFlag": false
  },
  {
    "id": 601,
    "incidentId": 566,
    "version": 8,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-06-17T11:37:00.000Z",
    "notificationText": "FD #5",
    "freeText": "fd",
    "freeTextExtended": "",
    "responsibilityControlPoint": "Administrator",
    "expectedFinishDate": "2017-06-19T23:01:00.000Z",
    "finishedDate": "2017-06-19T13:27:11.333Z",
    "createUser": "admin",
    "createDate": "2017-06-19T11:38:17.369Z",
    "modDate": "2017-06-19T13:27:12.598Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 1,
    "adminFlag": false
  }
]
----
{blank}

*Request for historical notifications*:
[source,json]
----
{
 "historicalFlag": true,
 "shiftChangeTransactionId": 33
 }
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
[
  {
    "id": 1191,
    "incidentId": 750,
    "version": 11,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-07-25T22:00:00.000Z",
    "notificationText": "c--d ddddddd",
    "responsibilityControlPoint": "Max Mustermann",
    "expectedFinishDate": "2017-07-27T22:00:00.000Z",
    "finishedDate": "2017-07-31T07:24:43.959Z",
    "createUser": "admin",
    "createDate": "2017-07-24T12:20:13.232Z",
    "modDate": "2017-08-21T11:24:32.855Z",
    "modUser": "max",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 2,
    "adminFlag": false
  },
  {
    "id": 994,
    "incidentId": 825,
    "version": 6,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-08-07T09:41:12.082Z",
    "notificationText": "dddd",
    "freeText": "53w5",
    "freeTextExtended": "terterwrew",
    "responsibilityControlPoint": "Administrator",
    "finishedDate": "2017-08-08T10:19:36.001Z",
    "createUser": "admin",
    "createDate": "2017-08-07T09:41:55.048Z",
    "modDate": "2017-08-08T10:19:37.454Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 2,
    "adminFlag": false
  }
]
----
{blank}

*Protection*: normal

*Remarks*:


=== Get Notifications by Incident-ID
This service retrieves a list of notifications from the database. All the returned
notifications are all versions of the given incident-ID. The sort-order is version descending.


*URL:* /notificationsByIncident/{incidentId}

*Method:* GET

*Path-Parameters*:

* incidentId - The incident-ID of all the versions to be returned

*Request-Headers*:

* Authorization – Existing JWT token


*Produces*: application/json

*Response*:
[source,json]
----
[
  {
    "id": 199,
    "incidentId": 2,
    "version": 3,
    "selected": false,
    "status": "offen",
    "beginDate": "2017-05-14T12:30:00",
    "notificationText": "sfg",
    "freeText": "freetext11",
    "freeTextExtended": "freetext_extended",
    "reminderDate": "2017-05-19T18:05:00",
    "createUser": "Creator",
    "createDate": "2017-05-15T14:30:09",
    "modDate": "2017-05-18T14:21:48",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 1
  },
  {
    "id": 171,
    "incidentId": 2,
    "version": 2,
    "selected": false,
    "status": "offen",
    "beginDate": "2017-05-14T12:30:00",
    "notificationText": "sfg",
    "freeText": "freetext11_old",
    "freeTextExtended": "freetext_extended",
    "reminderDate": "2017-05-19T18:05:00",
    "createUser": "Creator",
    "createDate": "2017-05-15T14:30:09",
    "modDate": "2017-05-18T13:21:48",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 1
  },
  {
    "id": 101,
    "incidentId": 2,
    "version": 1,
    "selected": false,
    "status": "offen",
    "beginDate": "2017-05-14T12:30:00",
    "notificationText": "sfg",
    "freeText": "freetext11_old_older",
    "freeTextExtended": "freetext_extended",
    "reminderDate": "2017-05-19T18:05:00",
    "createUser": "Creator",
    "createDate": "2017-05-15T14:30:09",
    "modDate": "2017-05-18T12:21:48",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 1
  },
]
----
{blank}

*Protection*: normal

*Remarks*:


=== Get Notifications With Reminder
This service retrieves a list of notifications from the database. The selection is based on the given filter-object.
With no filter value specified, the collection returned contains all active open and in progress notifications. With filter value(s) set, only
notifications matching the filter values are returned.

The following list explains the available filter values:

* The filter-value “reminderDate” is compared against the “reminder_date” of the notifications.
* The filter values in "responsibilityFilterList" are compared against the id of the notifications.

*URL:* /currentReminders

*Method:* POST

*Path-Parameter*: none

*Request-Headers*:

* Authorization – Existing JWT token

*Consumes*: application/json

*Request*:
[source,json]
----
{
    "reminderDate":"2017-08-30T09:00:23.538Z",
    "responsibilityFilterList":
                                [
                                    1, 2, 3
                                ]
}
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
[
     {
          "id": 1218,
          "incidentId": 572,
          "version": 9,
          "selected": false,
          "status": "offen",
          "beginDate": "2017-06-19T11:50:19.096Z",
          "notificationText": "FD #9",
          "freeText": "fd_",
          "freeTextExtended": "",
          "responsibilityControlPoint": "Administrator",
          "reminderDate": "2017-08-22T22:00:00.000Z",
          "createUser": "admin",
          "createDate": "2017-06-19T11:50:37.391Z",
          "modDate": "2017-08-25T08:57:51.890Z",
          "modUser": "admin",
          "fkRefBranch": 1,
          "fkRefNotificationStatus": 1,
          "fkRefGridTerritory": 1,
          "adminFlag": false
     },
     {
          "id": 1222,
          "incidentId": 881,
          "version": 3,
          "selected": false,
          "status": "offen",
          "beginDate": "2017-08-07T14:48:46.873Z",
          "notificationText": "ich bin eine anweisung mit dem admin flag",
          "freeText": "sfas",
          "freeTextExtended": "safas",
          "responsibilityControlPoint": "Administrator",
          "reminderDate": "2017-08-29T22:00:00.000Z",
          "createUser": "admin",
          "createDate": "2017-08-07T14:49:09.598Z",
          "modDate": "2017-08-30T07:47:45.021Z",
          "modUser": "admin",
          "fkRefNotificationStatus": 1,
          "adminFlag": true
     }
]
----
{blank}

*Protection*: normal

*Remarks*:


=== Get Historical Shift-Change List
This service retrieves a list of documented shift changes (who transferred/took the shift including the timestamp)
where the list can be narrowed by start date and end date.


*URL:* /shiftChangeList

*Method:* POST

*Path-Parameters*: none

*Request-Headers*:

* Authorization – Existing JWT token

*Consumes*: application/json

*Request*:
[source,json]
----
{
  "transferDateFrom": "2017-06-01T15:27:17.666Z",
  "transferDateTo": "2017-08-09T15:27:17.666Z",
}
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
[
{
  "startDate": "2017-06-01T15:27:17.666Z",
  "endDate": "2017-08-09T15:27:17.666Z",
  "historicalResponsibilities": [
    {
      "id": 2,
      "responsibleUser": "hugo",
      "formerResponsibleUser": "max",
      "transferDate": "2017-08-04T08:53:27.502Z",
      "transactionId": 1,
      "createDate": "2017-06-19T12:34:35.881Z",
      "createUser": "admin",
      "modDate": "2017-08-04T08:53:27.502Z",
      "modUser": "hugo",
      "refGridTerritory": {
        "id": 1,
        "fkRefMaster": 1,
        "description": "Mannheim",
        "name": "MA"
      },
      "refBranch": {
        "id": 3,
        "name": "F",
        "description": "Fernwärme"
      }
    },
    {
      "id": 10,
      "responsibleUser": "max",
      "formerResponsibleUser": "admin",
      "transferDate": "2017-08-08T13:50:10.862Z",
      "transactionId": 3,
      "createDate": "2017-06-19T12:34:35.881Z",
      "createUser": "admin",
      "modDate": "2017-08-08T13:50:10.861Z",
      "modUser": "max",
      "refGridTerritory": {
        "id": 1,
        "fkRefMaster": 1,
        "description": "Mannheim",
        "name": "MA"
      },
      "refBranch": {
        "id": 3,
        "name": "F",
        "description": "Fernwärme"
      }
    },
    {
      "id": 11,
      "responsibleUser": "max",
      "formerResponsibleUser": "admin",
      "transferDate": "2017-08-08T13:50:10.862Z",
      "transactionId": 3,
      "createDate": "2017-07-23T22:00:00.000Z",
      "createUser": "max",
      "modDate": "2017-08-08T13:50:10.861Z",
      "modUser": "max",
      "refGridTerritory": {
        "id": 3,
        "fkRefMaster": 3,
        "description": "Darmstadt",
        "name": "DA"
      },
      "refBranch": {
        "id": 1,
        "name": "S",
        "description": "Strom"
      }
    }
]
----
{blank}

*Protection*: normal

*Remarks*:

=== Receive Users
This service returns an array of all users.

*URL:* /users

*Method:* GET

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
[
    {
        "id": 1,
        "selected": false,
        "username": "Mustermann",
        "password": "Mustermann",
        "name": "Max Mustermann",
        "specialUser": false
    },
    {
        "id": 2,
        "selected": false,
        "username": "admin",
        "password": "admin",
        "name": "Administrator",
        "specialUser": true
    },
    {
        "id": 3,
        "selected": false,
        "username": "Otto",
        "password": "Otto",
        "name": "Otto Normalverbraucher",
        "specialUser": false
    }
]
----
{blank}

*Protection*: normal

*Remarks*:

=== Plan Responsibility-Transfer
This service prepares the responsibilities-transfer to another user. It returns an OK status
in case of success. If the responsibilities of the current user have changed in the meantime, the updated data is returned.

*URL:* /planResponsibilities

*Method:* POST

*Request-Headers*:

* Authorization – Existing JWT token

*Consumes*: application/json

*Request*:
[source,json]
----
[
    {
        "gridTerritoryDescription": "Mannheim",
        "responsibilityList": [
            {
                "id": 1,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "S",
                "isActive": true
            },
            {
                "id": 2,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "G",
                "isActive": true
            }
        ]
    },
    {
        "gridTerritoryDescription": "Offenbach",
        "responsibilityList": [
            {
                "id": 4,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "G",
                "isActive": true
            }
        ]
    }
]
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
{
    "ret": "OK"
}
----
{blank}

*Protection*: normal

*Remarks*:

=== Fetch Responsibility-Transfer
This service prepares the responsibilities-transfer for the current user. The user is about to fetch responsibilities
of another user.
The service returns an OK status in case of success. If the responsibilities of the current user have changed in the meantime, the updated data is returned.
For security reasons the currently logged in user is only allowed to set the *newResponsibleUser*
to himself.

*URL:* /fetchResponsibilities

*Method:* POST

*Request-Headers*:

* Authorization – Existing JWT token

*Consumes*: application/json

*Request*:
[source,json]
----
[
    {
        "gridTerritoryDescription": "Mannheim",
        "responsibilityList": [
            {
                "id": 1,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "S",
                "isActive": true
            },
            {
                "id": 2,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "G",
                "isActive": true
            }
        ]
    },
    {
        "gridTerritoryDescription": "Offenbach",
        "responsibilityList": [
            {
                "id": 4,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "G",
                "isActive": true
            }
        ]
    }
]
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
{
    "ret": "OK"
}
----
{blank}

*Protection*: normal

*Remarks*:


=== Confirm Responsibility-Transfer
This service is used to confirm the planned responsibilities for the authenticated session user. It returns an OK status in case of success. If the
responsibilities of the current user have changed in the meantime, the updated data is returned.

*URL:* /confirmResponsibilities

*Method:* POST

*Request-Headers*:

* Authorization – Existing JWT token

*Consumes*: application/json

*Request*:
[source,json]
----
[
    {
        "gridTerritoryDescription": "Mannheim",
        "responsibilityList": [
            {
                "id": 1,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "S",
                "isActive": true
            },
            {
                "id": 2,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "G",
                "isActive": true
            }
        ]
    },
    {
        "gridTerritoryDescription": "Offenbach",
        "responsibilityList": [
            {
                "id": 4,
                "responsibleUser": "admin",
                "newResponsibleUser": "Otto",
                "branchName": "G",
                "isActive": true
            }
        ]
    }
]
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
{
    "ret": "OK"
}
----
{blank}

*Protection*: normal

*Remarks*:

=== Receive Assigned User Suggestions
This service returns user suggestions for the 'Responsibility Forwarding' input field.

*URL:* /assignedUserSuggestions

*Method:* GET

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
[
    "Hermann Meister",
    "Hugo Normalverbraucher",
    "Max Mustermann",
    "Michael Müller"
]
----
{blank}

*Protection*: normal

*Remarks*:

=== Get SearchResults
This service obtains a search filter with different search criteria. The service retrieves a list of those notifications from the database which match all search criteria. 

The following search criteria are available to select/deselect:

* Search string: Any string literal whose occurence will be searched in notification text, free text and extended free text column.
  The input is case-insensitive.
* Responsibility/forwarded to: Any string literal whose occurence will be searched in responsibility forwarding column.
  The input is case-insensitive.
* Branch: All branches or only one special branch can be included in search, default: ALL
* Grid Territory: All grid territories or only one special grid territory can be included in search, default: ALL
* Status: A checkbox for each status to be included into search, default: all checkboxes are selected
* Fast search: If selected, only entries created or changed within the last two hundred days are included in search, default: selected

*URL:* /getSearchResults

*Method:* POST

*Request-Headers*:

* Authorization – Existing JWT token

*Consumes*: application/json

*Request*:
[source,json]
----
{
"searchString": "TAriflichen",
"responsibilityForwarding": "",
"statusOpenSelection": true,
"statusInWorkSelection": true,
"statusDoneSelection": true,
"statusClosedSelection": false,
"fkRefBranch": 1,
 "fkRefGridTerritory": 2,
  "fastSearchSelected": true
}
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
[
  {
    "id": 1074,
    "incidentId": 966,
    "version": 28,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-08-08T08:25:26.920Z",
    "notificationText": "Anweisung zur Einhaltung der Arbeitsschutzrichtlinien",
    "freeText": "Änderung Bereich dazu!",
    "freeTextExtended": "gilt nur für die tariflichen Mitarbeiter",
    "responsibilityForwarding": "Hermann Meister",
    "responsibilityControlPoint": "Administrator",
    "createUser": "admin",
    "createDate": "2017-08-08T08:26:03.140Z",
    "modDate": "2017-08-09T17:02:08.049Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 2,
    "adminFlag": false
  },
  {
    "id": 1064,
    "incidentId": 966,
    "version": 19,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-08-08T08:25:26.920Z",
    "notificationText": "Anweisung für alle tariflichen Mitarbeiter",
    "freeText": "Änderung Bereich dazu!",
    "freeTextExtended": "ddddddd",
    "responsibilityForwarding": "Hermann Meister",
    "responsibilityControlPoint": "Administrator",
    "createUser": "admin",
    "createDate": "2017-08-08T08:26:03.140Z",
    "modDate": "2017-08-09T12:58:13.568Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 2,
    "adminFlag": false
  }
]
----
{blank}

*Request for historical notifications*:
[source,json]
----
{
 "historicalFlag": true,
 "shiftChangeTransactionId": 33
 }
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
[
  {
    "id": 1191,
    "incidentId": 750,
    "version": 11,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-07-25T22:00:00.000Z",
    "notificationText": "c--d ddddddd",
    "responsibilityControlPoint": "Max Mustermann",
    "expectedFinishDate": "2017-07-27T22:00:00.000Z",
    "finishedDate": "2017-07-31T07:24:43.959Z",
    "createUser": "admin",
    "createDate": "2017-07-24T12:20:13.232Z",
    "modDate": "2017-08-21T11:24:32.855Z",
    "modUser": "max",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 2,
    "adminFlag": false
  },
  {
    "id": 994,
    "incidentId": 825,
    "version": 6,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-08-07T09:41:12.082Z",
    "notificationText": "dddd",
    "freeText": "53w5",
    "freeTextExtended": "terterwrew",
    "responsibilityControlPoint": "Administrator",
    "finishedDate": "2017-08-08T10:19:36.001Z",
    "createUser": "admin",
    "createDate": "2017-08-07T09:41:55.048Z",
    "modDate": "2017-08-08T10:19:37.454Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 2,
    "adminFlag": false
  }
]
----
{blank}

*Protection*: normal

*Remarks*:

=== Get Notifications
This service retrieves a list of notifications from the database. The selection is based on the given filter-object.
With no filter value specified, the collection returned contains all active notifications. With filter value(s) set, only
notifications matching the filter values are returned.

The following list explains the available filter values:

* The filter-values “dateFrom” and “dateTo” are compared against the “begin_date” of the notifications (closed interval).
* The filter values in "responsibilityFilterList" are compared against the id of the notifications.
* If the boolean filter value "historicalFlag" is "true" historical notifcations are returned.
* If the boolean filter value is null or "false", active notifications are returned.
* With historicalFlag set, the corresponding "shiftChangeTransactionId must also be set to obtain a valid result. In this
case, other filter values do not make sense and are not evaluated.

*URL:* /notifications/{listType}

*Method:* POST

*Path-Parameters*:

* listType - The type of the list for which the data will be loaded: "PAST", "OPEN", "FUTURE"

*Request-Headers*:

* Authorization – Existing JWT token

*Consumes*: application/json

*Request*:
[source,json]
----
{
  "dateFrom": "2017-03-09T15:27:17.666Z",
  "dateTo": "2017-04-09T15:27:17.666Z",
    "responsibilityFilterList": [
                                    1, 6
                                ]
}
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
[
  {
    "id": 1161,
    "incidentId": 337,
    "version": 10,
    "selected": false,
    "status": "in Arbeit",
    "beginDate": "2017-05-24T07:11:00.000Z",
    "notificationText": "UW4 Wartungsarbeiten LSA",
    "freeText": "Hr. xxx vor Ort",
    "freeTextExtended": "Hr.yyy ist auch vor Ort",
    "responsibilityForwarding": "Müller",
    "responsibilityControlPoint": "Administrator",
    "expectedFinishDate": "2017-05-24T14:00:00.000Z",
    "createUser": "admin",
    "createDate": "2017-05-24T07:03:54.429Z",
    "modDate": "2017-08-18T14:15:10.355Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 2,
    "fkRefGridTerritory": 1,
    "adminFlag": false
  },
  {
    "id": 601,
    "incidentId": 566,
    "version": 8,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-06-17T11:37:00.000Z",
    "notificationText": "FD #5",
    "freeText": "fd",
    "freeTextExtended": "",
    "responsibilityControlPoint": "Administrator",
    "expectedFinishDate": "2017-06-19T23:01:00.000Z",
    "finishedDate": "2017-06-19T13:27:11.333Z",
    "createUser": "admin",
    "createDate": "2017-06-19T11:38:17.369Z",
    "modDate": "2017-06-19T13:27:12.598Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 1,
    "adminFlag": false
  }
]
----
{blank}

*Request for historical notifications*:
[source,json]
----
{
 "historicalFlag": true,
 "shiftChangeTransactionId": 33
 }
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
[
  {
    "id": 1191,
    "incidentId": 750,
    "version": 11,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-07-25T22:00:00.000Z",
    "notificationText": "c--d ddddddd",
    "responsibilityControlPoint": "Max Mustermann",
    "expectedFinishDate": "2017-07-27T22:00:00.000Z",
    "finishedDate": "2017-07-31T07:24:43.959Z",
    "createUser": "admin",
    "createDate": "2017-07-24T12:20:13.232Z",
    "modDate": "2017-08-21T11:24:32.855Z",
    "modUser": "max",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 2,
    "adminFlag": false
  },
  {
    "id": 994,
    "incidentId": 825,
    "version": 6,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-08-07T09:41:12.082Z",
    "notificationText": "dddd",
    "freeText": "53w5",
    "freeTextExtended": "terterwrew",
    "responsibilityControlPoint": "Administrator",
    "finishedDate": "2017-08-08T10:19:36.001Z",
    "createUser": "admin",
    "createDate": "2017-08-07T09:41:55.048Z",
    "modDate": "2017-08-08T10:19:37.454Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 2,
    "adminFlag": false
  }
]
----
{blank}

*Protection*: normal

*Remarks*:


=== Get Search Results
This service obtains a search string combined with a limited number of search options in a search filter. The service retrieves those notifications from the database
which fulfill the given search criteria within the search filter. 
Each search string typed in is case-insensitive. The sort order of the result tuples is as follows: branch, incident id (descending), version (descending), grid territory, begin date. 

The search filter obtained by the web service consists of the subsequent criteria:

* search string: The string whose occurence is searched in notification text, free text and extended free text, default: null
* responsibility/forwarded to: an (additional) search string to be searched in the field responsibility/forwarded, default: null
* branch: Search in all branches or specify one concrete branch, default: all
* grid territory: Search in all grid territories or specify one concrete grid territory, default: all
* status: each defined status (open, in work, finished, closed) can be (de)selected, default: all status selected
* fast search: if selected, only entries created or modified during the last two hundred days are considered in the search, default: selected

*URL:* /searchResults

*Method:* POST

*Path-Parameters*:

-

*Request-Headers*:

* Authorization – Existing JWT token

*Consumes*: application/json

*Request*:
[source,json]
----
{
	"searchString": "TAriflichen",
	"responsibilityForwarding": "",
	"statusOpenSelection": true,
	"statusInWorkSelection": true,
	"statusDoneSelection": true,
	"statusClosedSelection": false,
	"fkRefBranch": 1,
	"fkRefGridTerritory": 2,
	"fastSearchSelected": true
}
----
{blank}

*Produces*: application/json

*Response*:
[source,json]
----
[
  {
    "id": 1074,
    "incidentId": 966,
    "version": 28,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-08-08T08:25:26.920Z",
    "notificationText": "Anweisung zur Einhaltung der Arbeitsschutzrichtlinien",
    "freeText": "Änderung Bereich dazu!",
    "freeTextExtended": "gilt nur für die tariflichen Mitarbeiter",
    "responsibilityForwarding": "Hermann Meister",
    "responsibilityControlPoint": "Administrator",
    "createUser": "admin",
    "createDate": "2017-08-08T08:26:03.140Z",
    "modDate": "2017-08-09T17:02:08.049Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 2,
    "adminFlag": false
  },
  {
    "id": 1064,
    "incidentId": 966,
    "version": 19,
    "selected": false,
    "status": "erledigt",
    "beginDate": "2017-08-08T08:25:26.920Z",
    "notificationText": "Anweisung für alle tariflichen Mitarbeiter",
    "freeText": "Änderung Bereich dazu!",
    "freeTextExtended": "ddddddd",
    "responsibilityForwarding": "Hermann Meister",
    "responsibilityControlPoint": "Administrator",
    "createUser": "admin",
    "createDate": "2017-08-08T08:26:03.140Z",
    "modDate": "2017-08-09T12:58:13.568Z",
    "modUser": "admin",
    "fkRefBranch": 1,
    "fkRefNotificationStatus": 3,
    "fkRefGridTerritory": 2,
    "adminFlag": false
  }
]
----
{blank}

*Protection*: normal

*Remarks*:

=== Get Import Files
This service retrieves a list of files which are available for import. These files should be placed in the following path:
[source,text]
----
C:/FilesToImport
----
{blank}


It returns the following informations about the file:

* Name
* Creation date
* Creator name
* Size
* Type

*URL:* /getImportFiles

*Method:* GET

*Path-Parameter*:

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
[
    {
        "fileName": "test.csv",
        "creationDate": "2017-09-25T12:00:01.635887Z",
        "creator": "admin",
        "type": "csv",
        "size": 5600,
    },
    {
        "fileName": "test_file.txt",
        "creationDate": "2017-09-23T11:00:01.635887Z",
        "creator": "max",
        "type": "txt",
        "size": 8000,
    }
]
----
{blank}

*Protection*: normal

*Remarks*:


=== Get The Content of a File
This service retrieves the content of a file. The file should be a text file (.txt, .csv etc)
and the informations will be retrieved from the 9th row. The file is defined like this

[source,text]
----
                                                            PROTOKOLL_STROM
                                              08.09.2017 10:10:51  -  08.09.2017 10:22:04

Betriebsart: Prozessführung
Modus      : Spalten-Filtern
Verknüpfung: --------

.............MG.........................................................................................................................
20:19:51,425 MG Test text          Mannheim Gas
ENDE

08.09.2017 10:23:34
----
{blank}

This file has to be placed in a configured path accessible by the elogbook backend server.

It returns the following information which extracted from the file:

* Territory name
* Branch name
* Description text

*URL:* /importFile

*Method:* GET

*Path-Parameter*:

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
{
    "branchName": "W",
    "gridTerritoryName": "MA",
    "notificationText": "This is a simple test text"
}
----
{blank}

*Protection*: normal

*Remarks*:


=== Delete Imported File
This service deletes a file for a given file name. If there is a file with this name it returns true and deletes
this file. Else it returns false.

*URL:* /deleteImportedFiles/{fileName}

*Method:* DELETE

*Path-Parameter*: fileName - The name of the file that will be deleted

*Request-Headers*:

* Authorization – Existing JWT token

*Produces*: application/json

*Response*:
[source,json]
----
{
    true
}
----
{blank}

*Protection*: normal

*Remarks*: