Skip to content
Sirius Developer

Overview

The Sirius Apps allows you to receive event from Sirius through Webhook or GCP Pub/Sub.

About App

A Sirius App represents an external system that receives events from Sirius.

Sirius apps supports two transports to communicate:

  • Webhook: a URL exposed by your application which Sirius uses as event channel
  • GCP Pub/Sub: a Google Cloud Pub/Sub topic which Sirius uses as event channel

Create a Sirius App

  1. Login to Sirius, if you don't have an account, ask a Sirius owner to create one for you.

  2. Be sure your user has the "apps:full", usually the "Owner" role.

  3. Go to the admin (it could require to be connected through VPN to have admin access).

  4. Go to "Apps" section.

  5. Click on "Créer une app".

Create app

  1. Give your App a meaningful name. This name will be displayed to users.

  2. Choose a transport type between "Webhook" and "Google Cloud Pub/Sub".

Webhook Sirius App

  1. Specify a URL, this URL will be used by Sirius to make POST request.

  2. Specify a secret to secure your webhooks and ensure your server is only receiving the expected Sirius requests.

GCP Pub/Sub Sirius App

  1. Choose a GCP integration and a topic. Be careful with following points:
  • Sirius does not create the topic automatically. You have to create it by yourself
  • GCP service account must have rights to publish on the topic
  1. Configure actions.

About Events

When an action occurs in Sirius like a post published by example, an event is emitted. Events are emitted in Sirius internal system and are dispatched to all declared apps through Webhook or GCP Pub/Sub depending their configured transport.

An event is represented by:

  • A name: most of the time, it is the resource name (example: "live")
  • A payload: an object containing various data. Most of the time it contains an "action" that defines what happened to the resource

An example of event:

{
  "name": "live",
  "payload": {
    "action": "closed",
    "live": {
      "id": 1,
      "createdAt": "2020-11-26T13:04:46.777Z",
      "updatedAt": "2020-11-26T13:04:46.777Z",
      "locked": false,
      "closed": false
    }
  }
}

About App Actions

An app could declare some "actions". An action is represented by an "event" an "eventAction" and a "timeout". It literally means:

"When the event event with action eventAction will be emitted, I will do something in less than timeout."

When an app declares an action for a specific event, a status is created when the event emits.

About Event Statuses

A status keep track of the success or the failure of an action realized by an app. It gives feedback to the user to see if his action has been correctly executed.

If an action is declared by the App for a specific event, the app also receives a "statusId" in the message.

It is the responsibility of the external system to update the status using Sirius GraphQL API.

To learn how to update a status when an event is received, read statuses documentation.

About "published" events

When a publishing action is triggered in Sirius an event with a "published" action is emitted. The "published" action is available on "article", "articleBranch" and "articleBroadcast".

Before triggering the "published" event, Sirius emits a "prePublish" event. This event precedes the "published" event and gives the app the opportunity to prevent the publishing process to complete.

Sirius will wait for all "prePublish" statuses to be "success" before completing the publishing process. In other words, if you have three applications with a "prePublish" status, it will wait for the three to finish work. If one of the applications fails, the publishing process will not happen. The "published" event is triggered at the end of the publishing process, so if one of the "prePublish" status fails, the "published" event will not be triggered.

Differences between "prePublish" and "published" payload

  • "prePublish" event occurs before the publishing process, the resource you receive in the event payload is not "published".
  • "publish" event occurs after the publishing process, the resource you receive in the event payload is "published".

Publishing process could make some change in the payload, the most noticeable one will be published: true or published: false but also firstPublishedAt, etc.

When to listen "prePublish" or "published" event?

Sirius can be used with two models: blocking publishing and non-blocking publishing.

Blocking publishing

The "blocking publishing" model prevents any content to be marked as "published" in Sirius when the application has not processed data. This model is recommended if your application populates his cache only through events emitted by Sirius.

-> Sirius emits article "prePublish"
-> App populates cache
-> App updates status as success
-> Article is cached and available on the website
-> Sirius runs article publishing process
-> Sirius emits article "published"

If the "App populates cache" step fails, the article will not be published in Sirius. The status will indicate the fail, but also the article will not remain published across all Sirius interfaces.

Non-blocking publishing

The "non-blocking publishing" model allows content to be marked as "published" in Sirius but potentially not received by your application. This model is recommended if your application populates his cache "on-the-fly" using the Sirius API.

-> Sirius runs article publishing process
-> Sirius emits article "published"
  -> App populates cache (in the background)

If the "App populates cache" step fails, the article will be marked as published in Sirius. The status will indicate the fail, and it is the responsibility of users to trigger another publishing.

Edit this page on GitHub