Rest HTTP API

By default the swagger UI is available at this URL : https://localhost:8181/swagger-ui/index.html

Creating a Log Entry

Create a log entry

PUT https://localhost:8181/Olog/logs/multipart

{
     "description":"Beam Dump due to Major power dip Current Alarms Booster transmitter switched back to lower state.",
     "level":"Info",
     "title":"Some title",
     "logbooks":[
        {
           "name":"Operations"
        }
     ],
     "attachments":[
        {"id": "82dd67fa-09df-11ee-be56-0242ac120002", "filename":"MyScreenShot.png"},
        {"id": "c02948ad-4bbd-432f-aa4d-a687a54f8d40", "filename":"MySpreadsheet.xlsx"}
     ]
}

NOTE Attachment ids must be unique, e.g. UUID. When creating a log entry - optionally with attachments - client must:

Use a multipart request and set the Content-Type to “multipart/form-data”, even if no attachments are present.
If attachments are present: add one request part per attachment file. Each file must be added using “files” as the name for the part.
The filename field of an attachment must match the originalFilename of the file part. This requirement ensures that attachment metadata and file parts can be matched. Note that a client may set an arbitrary originalFilename, it need not match the file name of the physical file subject to upload.
To support upload of files with same name, but from different directories, the filename field should be unique between all attachments/files uploaded in a log entry submission.
Add the log entry as a request part with content type “application/json”. The name of the part must be “logEntry”.

An HTTP 400 (bad request) is returned if a file part is present that does not correspond to any of the attachment objects.

Client must also be prepared to handle an HTTP 413 (payload too large) response in case the attached files exceed file and request size limits configured in the service.

Reply to a log entry

This uses the same end point as when creating a log entry, but client must send the unique id of the log entry to which the new one is a reply.

PUT https://localhost:8181/Olog/logs?inReplyTo=<id>

If <id> does not identify an existing log entry, a HTTP 400 status is returned.

Adding a single attachment

POST https://localhost:8181/Olog/logs/attachments/{logId}

Content-Type: multipart/form-data; boundary=----formBoundary
------formBoundary
Content-Disposition: form-data; name="filename"
Content-Type: application/json
{"image1.png"}
------formBoundary

Searching for Log Entries

GET https://localhost:8181/Olog/logs

Search Parameters

Keyword	Descriptions
Text search
text	A list of keywords which are present in the log entry description
fuzzy	Allow fuzzy searches
phrase	Finds log entries with the exact same word/s
owner	Finds log entries with the given owner
Time based searches
start	Search for log entries created after given time instant
end	Search for log entries created before the given time instant
includeevents	A flag to include log event times when
Meta Data searches
tags	Search for log entries with at least one of the given tags
logbooks	Search for log entries with at least one of the given logbooks
Attachments searches
attachments	To search for entries with at least one attachment
Pagination searches
size	The number of log entries to be returned within each page
page	The page number, i.e page 1 is the 1 to 1+size log entries matching the search
Sorting Search Results
sort	up\|down order the search results based on create time

For time based search requests the client may specify a tz parameter indicating the client’s time zone. The format must be recognized as a valid zone identifier, see for instance https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html. If the client does not specify the time zone, the time zone of the service is used to compute start end end timestamps. An invalid time zone specifier will result in a HTTP 400 (bad request) response.

Example:

GET https://localhost:8181/Olog/logs/search?desc=dump&logbooks=Operations

The above search request will return all log entires with the term “dump” in their descriptions and which are part of the Operations logbook.

Retrieving an attachment of a log entry

GET https://localhost:8181/Olog/logs/attachments/{logId}/{filename}

Find entries with at least one attachment of type ‘image’

GET https://localhost:8181/Olog/logs/search?attachments=image

Updating a Log Entry

POST https://localhost:8181/Olog/logs/{logId}

Update a log entry, the original log entry is archived in a separate elastic index before any of the changes are applied. This endpoint does not support upload of addtional attachments.

Note: the create date, and events cannot be modified.

{
     "owner":"log",
     "description":"Beam Dump due to Major power dip Current Alarms Booster transmitter switched back to lower state.
                    New important info appended",
     "level":"Info",
     "title":"A new title",
     "logbooks":[
        {
           "name":"Operations"
        }
     ]
}

Updating a Log Entry with additional attachments

POST https://localhost:8181/Olog/logs/multipart

Update a log entry, the original log entry is archived in a separate elastic index before any of the changes are applied.

Note: the create date, and events cannot be modified.

{
  "description":"Beam Dump due to Major power dip Current Alarms Booster transmitter switched back to lower state.",
  "level":"Info",
  "title":"Some title",
  "logbooks":[
    {
      "name":"Operations"
    }
  ],
  "attachments":[
    {"id": "82dd67fa-09df-11ee-be56-0242ac120002", "filename":"MyScreenShot.png"},
    {"id": "c02948ad-4bbd-432f-aa4d-a687a54f8d40", "filename":"MySpreadsheet.xlsx"}
}

Please check the documentation for

PUT https://localhost:8181/Olog/logs/multipart

on restrictions and requirements on the multipart request.

An HTTP 400 (bad request) is returned in the following cases:

If a file part is present that does not correspond to any of the attachment objects.
If an attachment object does not correspond to any file part and if that attachment (identified by the id field) cannot be located in the attachment repository.

Managing Logbooks, Tags and Levels

Retrieve the list of existing tags

GET https://localhost:8181/Olog/tags

Retrieve the list of existing logbooks

GET https://localhost:8181/Olog/logbooks

Retrieve the list of existing levels

GET https://localhost:8181/Olog/levels

Create a new tag

PUT https://localhost:8181/Olog/tags/{tagName}

{
     "name":"Fault",
     "state":"Active"
}

Create multiple tags

PUT https://localhost:8181/Olog/tags

[
  {"name":"Fault", "state":"Active" },
  {"name":"Alarm", "state":"Active" }
]

Create a new logbook

PUT https://localhost:8181/Olog/logbooks/{logbookName}

{
     "name":"Operations",
     "owner":"olog-logs",
     "state":"Active"
}

Create multiple logbooks

PUT https://localhost:8181/Olog/logbooks

[
  {"name":"Operations", "owner":"olog-logs", "state":"Active"},
  {"name":"DAMA",       "owner":"olog-logs", "state":"Active"}
]

Create a new level

PUT https://localhost:8181/Olog/level/{levelName}

{
     "name":"Info",
     "defaultLevel":[true|false]
}

NOTE: only one single level may be defined as default level.

Managing Properties

Retrieve the list of existing properties

GET https://localhost:8181/Olog/properties

Create a new property

PUT https://localhost:8181/Olog/properties/{propertyName}

{
     "name":"Ticket",
     "owner":"olog-logs",
     "state":"Active",
     "attributes":[
        {
           "name":"id",
           "state":"Active"
        },
        {
           "name":"url",
           "state":"Active"
        }
     ]
}

Create multiple properties

PUT https://localhost:8181/Olog/properties

[
  {
     "name":"Ticket",
     "owner":"olog-logs",
     "state":"Active",
     "attributes":[
        {"name":"id", "state":"Active"},
        {"name":"url", "state":"Active"}
     ]
  },
     {
     "name":"Scan",
     "owner":"olog-logs",
     "state":"Active",
     "attributes":[
        {"name":"id", "state":"Active"}
     ]
  }
]

Templates

Log entry templates can be added to the storage to support use cases when the same type of log entries need to be created on a regular basis. Templates have the same structure a regular log entries, except for attachments.

To add a new template, use:

PUT https://localhost:8181/Olog/templates

{
   "description":"Template text",
   "level":"Info",
   "title":"Some title",
   "logbooks":[
      {
         "name":"Operations"
      }
   ]
}

In the client UI (currently only CS Studio/Phoebus) users may select from a list of templates, if available. Upon selection of a template, the client will populate the editor’s input controls based on the template content.

GET /Olog/help/{what}

Get help

Locates the (static) help resource and returns it as a string.

Parameters:

what (string)

Query Parameters:

lang (string)

Status Codes:

200 OK – The contents of the help resource, or null if the requested resource could not be found.

GET /Olog

Get information

Get information about the Olog service

Status Codes:

200 OK – Information about the Olog service

GET /Olog/configuration

Get configuration

Get levels, logbooks and tags configuration

Status Codes:

200 OK – successful operation

GET /Olog/levels

Get all levels

GET method for retrieving the list of `null <null>`_s in the database.

Status Codes:

200 OK – list of {@link org.phoebus.olog.entity.Level}s

PUT /Olog/levels

Create a list of levels

PUT method for the null resource to support the creation of a list of `null <null>`_s

Status Codes:

200 OK – the list of {@link org.phoebus.olog.entity.Level}s created

GET /Olog/levels/{levelName}

Get a level by name

Get method for retrieving the null with name matching levelName

Parameters:

levelName (string)

Status Codes:

200 OK – the matching {@link org.phoebus.olog.entity.Level}. If not found, HTTP 404 response is triggered.

PUT /Olog/levels/{levelName}

Create a level

If the specified level is marked as default, checks are made to make sure no existing level in the database is marked as default. This is needed to ensure that only one level is defined to be the default.

Parameters:

levelName (string)

Status Codes:

200 OK – successful operation

DELETE /Olog/levels/{levelName}

Delete a level by name

Parameters:

levelName (string)

Status Codes:

200 OK – successful operation

GET /Olog/logbooks

Get all logbooks

Status Codes:

200 OK – successful operation

PUT /Olog/logbooks

Create a list of logbooks

Status Codes:

200 OK – successful operation

GET /Olog/logbooks/{logbookName}

Get a logbook by name

Parameters:

logbookName (string)

Status Codes:

200 OK – successful operation

PUT /Olog/logbooks/{logbookName}

Create a logbook

Parameters:

logbookName (string)

Status Codes:

200 OK – successful operation

DELETE /Olog/logbooks/{logbookName}

Delete a logbook by name

Parameters:

logbookName (string)

Status Codes:

200 OK – successful operation

GET /Olog/attachment/{attachmentId}

Get an attachment by Id

Parameters:

attachmentId (string)

Status Codes:

200 OK – A {@link ResponseEntity} if found, otherwise client will get HTTP 404 response. If an {@link IOException} is thrown when the input stream of the GridFS resource is requested, a HTTP 500 response is returned.

GET /Olog/logs

Finds matching log entries

See /Ologs/logs/search (alias) for parameter details.

Query Parameters:

text (string) – A list of keywords which are present in the log entry description
fuzzy (string) – Allow fuzzy searches
phrase (string) – Finds log entries with the exact same word/s
owner (string) – Finds log entries with the given owner
start (string) – Search for log entries created after given time instant
end (string) – Search for log entries created before the given time instant
includeevents (string) – A flag to include log event times when
tags (string) – Search for log entries with at least one of the given tags
logbooks (string) – Search for log entries with at least one of the given logbooks
attachments (string) – To search for entries with at least one attachment
size (string) – The number of log entries to be returned within each page
attachments – The page number, i.e page 1 is the 1 to 1+size log. entries matching the search
sort (string) – Order the search results based on create time

Status Codes:

200 OK – A {@link List} of {@link Log} objects matching the query parameters, or an empty list if no matching logs are found.

PUT /Olog/logs

Create a new log entry

Creates a new log entry. If the inReplyTo parameters identifies an existing log entry, this method will treat the new log entry as a reply.

This may return a HTTP 400 if for instance inReplyTo does not identify an existing log entry, or if the logbooks listed in the {@link Log} object contains invalid (i.e. non-existing) logbooks.

Primary use case is upload of log entry without attachments as this type of request is easier to construct, i.e. client need not create a request with multipart items.

Query Parameters:

markup (string)
notifyWsClients (boolean)
inReplyTo (string)

Status Codes:

200 OK – The persisted {@link Log} object.

Request Headers:

X-Olog-Client-Info

GET /Olog/logs/archived/{logId}

Get an archived log by Id

Parameters:

logId (string)

Status Codes:

200 OK – successful operation

GET /Olog/logs/attachments/{logId}/{attachmentName}

Get an attachment of a determined log

Parameters:

logId (string)
attachmentName (string)

Status Codes:

200 OK – successful operation

POST /Olog/logs/group

Grouf logs

Status Codes:

200 OK – successful operation

POST /Olog/logs/multipart

Query Parameters:

markup (string)

Status Codes:

200 OK – successful operation

PUT /Olog/logs/multipart

Create a new log entry (multipart)

{
   "owner":"log",
     "description":"Beam Dump due to Major power dip Current Alarms Booster transmitter switched back to lower state.",
     "level":"Info",
     "title":"Some title",
     "logbooks":[
        {
           "name":"Operations"
        }
     ],
     "attachments":[
        {"id": "82dd67fa-09df-11ee-be56-0242ac120002", "filename":"MyScreenShot.png"},
        {"id": "c02948ad-4bbd-432f-aa4d-a687a54f8d40", "filename":"MySpreadsheet.xlsx"}
     ]
}

NOTE Attachment ids must be unique, e.g. UUID. When creating a log entry - optionally with attachments - client must:

Use a multipart request and set the Content-Type to “multipart/form-data”, even if no attachments are present.

#. If attachments are present: add one request part per attachment file, in the order they appear in the log entry. Each file must be added using “files” as the name for the part. #. Add the log entry as a request part with content type “application/json”. The name of the part must be “logEntry”.

This may return a HTTP 400 if for instance inReplyTo does not identify an existing log entry, or if the logbooks listed in the {@link Log} object contains invalid (i.e. non-existing) logbooks.Client must also be prepared to handle a HTTP 413 (payload too large) response in case the attached files exceed file and request size limits configured in the service.

Query Parameters:

markup (string)
inReplyTo (string)

Status Codes:

200 OK – The persisted {@link Log} object.

Request Headers:

X-Olog-Client-Info

GET /Olog/logs/rss

Get RSS feed

GET method for retrieving an RSS feed of channels

Query Parameters:

text (string) – A list of keywords which are present in the log entry description
fuzzy (string) – Allow fuzzy searches
phrase (string) – Finds log entries with the exact same word/s
owner (string) – Finds log entries with the given owner
start (string) – Search for log entries created after given time instant
end (string) – Search for log entries created before the given time instant
includeevents (string) – A flag to include log event times when
tags (string) – Search for log entries with at least one of the given tags
logbooks (string) – Search for log entries with at least one of the given logbooks
attachments (string) – To search for entries with at least one attachment
size (string) – The number of log entries to be returned within each page
attachments – The page number, i.e page 1 is the 1 to 1+size log. entries matching the search
sort (string) – Order the search results based on create time

Status Codes:

200 OK – the name of the RSS feed view, which will be resolved to render the feed

GET /Olog/logs/search

Finds matching log entries

Finds matching log entries For time based search requests the client may specify a tz parameter indicating the client’s time zone. The format must be recognized as a valid zone identifier, see for instance https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html. If the client does not specify the time zone, the time zone of the service is used to compute start end end timestamps. An invalid time zone specifier will result in a HTTP 400 (bad request) response.

Example:

GET https://localhost:8181/Olog/logs/search?desc=dump&logbooks=Operations

The above search request will return all log entires with the term “dump” in their descriptions and which are part of the Operations logbook.

Retrieving an attachment of a log entry

GET https://localhost:8181/Olog/logs/attachments/{logId}/{filename}

Find entries with at least one attachment of type ‘image’

GET https://localhost:8181/Olog/logs/search?attachments=image

Query Parameters:

text (string) – A list of keywords which are present in the log entry description
fuzzy (string) – Allow fuzzy searches
phrase (string) – Finds log entries with the exact same word/s
owner (string) – Finds log entries with the given owner
start (string) – Search for log entries created after given time instant
end (string) – Search for log entries created before the given time instant
includeevents (string) – A flag to include log event times when
tags (string) – Search for log entries with at least one of the given tags
logbooks (string) – Search for log entries with at least one of the given logbooks
attachments (string) – To search for entries with at least one attachment
size (string) – The number of log entries to be returned within each page
attachments – The page number, i.e page 1 is the 1 to 1+size log. entries matching the search
sort (string) – Order the search results based on create time

Status Codes:

200 OK – A {@link SearchResult} holding matching objects, if any.

GET /Olog/logs/{logId}

Get a log by Id

Parameters:

logId (string)

Status Codes:

200 OK – successful operation

POST /Olog/logs/{logId}

Update a log entry

Updates existing log record. Data sent by client is saved, i.e. if client specifies a shorter list of logbooks or tags, the updated log record will reflect that. However, the following data is NOT updated:

Attachments
Created date
Events

Notifiers - if such have been registered - are not called.

Parameters:

logId (string)

Query Parameters:

markup (string)
notifyWsClients (boolean)

Status Codes:

200 OK – The updated log record, or HTTP status 404 if the log record does not exist. If the path variable does not match the id in the log record, HTTP status 400 (bad request) is returned.

GET /Olog/properties

Get all properties

GET method to retrieve the list of all active properties. If the inactive flag is set true

Query Parameters:

inactive (boolean)

Status Codes:

200 OK – a list of all {@link Property}s

PUT /Olog/properties

Create a list of properties

PUT method for creating multiple properties.

Status Codes:

200 OK – The list of successfully created properties

GET /Olog/properties/{propertyName}

Get a property by name

Parameters:

propertyName (string)

Status Codes:

200 OK – successful operation

PUT /Olog/properties/{propertyName}

Create a property

Parameters:

propertyName (string)

Status Codes:

200 OK – successful operation

DELETE /Olog/properties/{propertyName}

Delete a property by name

Parameters:

propertyName (string)

Status Codes:

200 OK – successful operation

GET /Olog/tags

Get all tags

GET method for retrieving the list of tags in the database.

Status Codes:

200 OK – list of tags

PUT /Olog/tags

Create a list of tags

PUT method for the tags resource to support the creation of a list of tags

Status Codes:

200 OK – the list of tags created

GET /Olog/tags/{tagName}

Get a tag by name

Get method for retrieving the tag with name matching tagName

Parameters:

tagName (string)

Status Codes:

200 OK – the matching tag, or null

PUT /Olog/tags/{tagName}

Create a tag

PUT method for creating a tag.

Parameters:

tagName (string)

Status Codes:

200 OK – the created tag

DELETE /Olog/tags/{tagName}

Delete a tag by name

Parameters:

tagName (string)

Status Codes:

200 OK – successful operation

GET /Olog/templates

Get all templates

Status Codes:

200 OK – A potentially empty {@link List} of all existing {@link LogTemplate}s.

PUT /Olog/templates

Create a new template

Log entry templates can be added to the storage to support use cases when the same type of log entries need to be created on a regular basis. Templates have the same structure a regular log entries, except for attachments. In the client UI (currently only CS Studio/Phoebus) users may select from a list of templates, if available. Upon selection of a template, the client will populate the editor’s input controls based on the template content.

Status Codes:

200 OK – The persisted {@link LogTemplate} object.

GET /Olog/templates/{logTemplateId}

Get a template by Id

Parameters:

logTemplateId (string)

Status Codes:

200 OK – successful operation

DELETE /Olog/templates/{logTemplateId}

Delete a template

Delete a template based on its unique id

Parameters:

logTemplateId (string)

Status Codes:

200 OK – successful operation