Skip to content

Latest commit

 

History

History
179 lines (133 loc) · 6 KB

SenecaProtocolV1.md

File metadata and controls

179 lines (133 loc) · 6 KB
Raw

Seneca Protocol (version 1)
Announcements Microservice

Announcements microservice implements a Seneca compatible API. Seneca port and protocol can be specified in the microservice configuration.

var seneca = require('seneca')();

seneca.client({
    type: 'tcp', // Microservice seneca protocol
    localhost: 'localhost', // Microservice localhost
    port: 8080, // Microservice seneca port
});

The microservice responds on the following requests:

seneca.act(
    {
        role: 'announcements',
        version: 1,
        cmd: ...cmd name....
        ... Arguments ...
    },
    function (err, result) {
        ...
    }
);

Data types

AttachmentV1 class

Contains reference to a document attachment

Properties:

  • id: string - unique feedback id
  • name: string - document (file) name

PartyReferenceV1 class

Contains reference to sending or replying party

Properties:

  • id: string - unique feedback id
  • name: string - party name
  • email: string - (optional) party email address (optional)

LocationV1 class

Contains location on a map

Properties:

  • name: string - Logical location name or address
  • pos: any - Position coordinates in GeoJSON

AnnouncementV1 class

Represents a system announcement.

Properties:

  • id: string - unique announcement id
  • category: string - announcement category, i.e. 'maintenance', 'product update', etc.
  • app: string - (optional) application name
  • creator: PartyReferenceV1 - party who created the announcement
  • create_time: Date - date and time when announcement was created
  • title: MultiString - (optional) announcement title in multiple languages
  • content: MultiString - announcement textual content in multiple languages
  • loc: LocationV1 - (optional) location associated with this announcement
  • start_time: Date - (optional) start of a time interval associated with this announcement
  • end_time: Date - (optional) end of a time interval associated with this announcement
  • pic_ids: [string] - (optional) array of picture block ids in storage attached to this announcement
  • docs: [AttachmentV1] - (optional) array of attached documents
  • tags: [string] - (optional) explicit tags with annoucement topic for searching
  • all_tags: [string] - (readonly) normalized array of explicit and hash tags used by search
  • status: string - editing status: 'new', 'writing', 'translating', 'completed' (default: 'new')
  • importance: int - (optional) importance: 0 - low, 1000 - high (default: 0)
  • custom_hdr: Object - custom data summary that is always returned (in list and details)
  • custom_dat: Object - custom data details that is returned only when a single object is returned (details)

Operations

Cmd: 'get_announcements'

Retrieves a list of announcements by specified criteria

Arguments:

  • filter: object - filter parameters
    • category: string - (optional) announcement category
    • app: string - (optional) application name
    • status: string - (optional) editing status
    • from_create_time: Date - (optional) start of announcement created interval
    • to_create_time: Date - (optional) end of announcement created interval
    • tags: [string] - search tags
    • search: string - string for full text search in title, content and creator name
  • paging: object - paging parameters
    • skip: int - (optional) start of page (default: 0). Operation returns paged result
    • take: int - (optional) page length (max: 100). Operation returns paged result

Returns:

  • err: Error - occured error or null for success
  • result: DataPage - retrieved page with Announcement objects

Cmd: 'get_random_announcement'

Retrieves a random announcement from filtered resultset

Arguments:

  • filter: object - filter parameters
    • category: string - (optional) announcement category
    • app: string - (optional) application name
    • status: string - (optional) editing status
    • from_create_time: Date - (optional) start of announcement created interval
    • to_create_time: Date - (optional) end of announcement created interval
    • tags: [string] - search tags
    • search: string - string for full text search in title, content and creator name

Returns:

  • err: Error - occured error or null for success
  • result: AnnouncementV1 - random Announcement or null if nothing was found

Cmd: 'get_announcement_by_id'

Retrieves announcement by its unique id.

Arguments:

  • announcement_id: string - unique announcement id

Returns:

  • err: Error - occured error or null for success
  • result: AnnouncementV1 - retrieved Announcement object

Cmd: 'create_announcement'

Creates a new system announcement.

Arguments:

  • announcement: AnnouncementV1 - a new annoucement to be created

Returns:

  • err: Error - occured error or null for success
  • result: AnnouncementV1 - created Announcement object

Cmd: 'update_announcement'

Updates announcement.

Arguments:

  • announcement: AnnouncementV1 - new announcement values (partial updates are supported)

Returns:

  • err: Error - occured error or null for success
  • result: AnnouncementV1 - updated Announcement object

Cmd: 'delete_announcement_by_id'

Deletes system announcement specified by its unique id.

Arguments:

  • announcement_id: string - unique announcement id

Returns:

  • err: Error - occured error or null for success
  • result: AnnouncementV1 - deleted Announcement object