Skip to main content
Developer Portal
Mendix

BYU Eventhub v1

This is a client for Mendix users to consume and create BYU events in Mendix applications.

Documentation

Description

This module is comprised of snippets and microflows to help you with creating/consuming events in your Mendix applications. These events are something that services or websites can listen for and do something when triggered.

Typical Usage Scenario

This is used when you need to create events or consume events made by a BYU service. For example, if a student changes their Net ID, an event can be created that other services are listening for. When that event is detected, the Net ID can be updated in the listening services.

Features and Limitations

The module contains the following in the USE_ME folder:

  • Consumption:
    • PRS_GetEvents
      • This will call Eventhub and get all the events for your recent subscriptions (due to limitations of Mendix this can only get one event at a time.)
    • Snip_SubscriptionsView
      • This snippet will show you all of the subscriptions for the user whose credentials you are using. Using this widget, you can create and delete subscriptions using the buttons
    • Snip_WebhooksView
      • This snippet will manage the webhook for your account. If you have already made a webhook, use the get webhook item, and do not make a new one (your account can only have one webhook. You will need to have multiple persons if you want to have more than one webhook.) You can create and or delete webhooks if you would like through this snippet.
  • Creation:
    • PRS_CreateEvent
      • Use this microflow to create an event. Call it and pass in the parameters, and the event will be raised.
    • Snip_ManageDomains
      • This allows you make a domain, as long as the name is not already in use.
      • You cannot delete a domain while there are entities using it.
    • Snip_ManageEntities
      • This allows you to create an entity. You must have a domain to make this.
      • You cannot delete an entity while there are event types using it.
    • Snip_ManageEventTypes
      • This allows you to make custom event types for a given entity (thus an entity is required)

Detailed Description of Content

Subscriptions

  • Subscriptions can be managed through the snippet "Snip_SubscriptionsView"
  • This snippet contains all of the logic for creating and deleting subscriptions to endpoints, all of which is done through REST calls
  • For more information on what events are available to subscribe to, see developer.byu.edu under the events tab.
  • These details are what you will pass in when making new subscriptions(the ones you already have will be displayed)

Webhooks

  • Webhooks can be managed through the snippet "Snip_WebhooksView"
  • This snippet will show the webhook you have made if you have one, and will allow you to register one if you have not. A user can only have one webhook, while they can have multiple subscriptions. If you want to have multiple webhooks, you will need to have multiple non-person users.
  • If a webhook already exists, you can use the Get Existing Webhook button to retrieve it.
  • Here is what you will need to pass in to make a new webhook:
    • Entity Name = The name of the entity that you want to associate the webhook with
    • Security Option = This allows you to make a password. For default use 'None'
    • Push Option = How you want to be notified for the event. Normally use 'Push Message'
    • Entity ID = The ID of the entity (you can see this by making an entity in that snippet)
    • Content Type = The content that you want back (for example, 'application/json')
    • Endpoint = The endpoint where events will be sent to (for example, https://api.byu.edu)

Before Making Events

  • Before you make an event you will need to make a domain, an entity, and an event type. All three of these objects (domain, entity, event-type) are tied to the ID in the JWT used to access the Eventhub

Domains

  • The 'Snip_ManageDomains' snippet does all of the function calls you will need and shows all currently existing domains.
  • When making a domain, you will need to pass in the following:
    • Domain = the name for the new domain
    • Description = the description for the domain
  • Alternatively, anyone can use the "byu.edu" domain

Entity

  • The 'Snip_ManageEntities' snippet helps you manage entities. It, by default, will show you all of the entities that are currently published in Eventhub.
  • When making an entity, you will need to pass in the following:
    • Entity = the name of the new entity
    • Domain = the name for the domain that the entity is under
    • Description = the description for the entity

Event Type

  • The 'Snip_ManageEventTypes' snippet helps with managing event types. It will display all of the current event types
  • When making a new event type, you will need to pass in the following:
    • Event Type = The name of the new event type
    • Entity = the name of the entity the event type is associated with
    • Domain = the name for the domain that the entity is under
    • Description = the description for the entity

Creating Events

You can create events by calling the microflow "CWS_CreateEvent". Here is how you do it:

  1. Add the microflow at the place where you want to send off the event
  2. You will need to pass in the following parameters
    • SourceDateTime: the currentDateTime
    • EventDateTime: the time when the event occurred
    • Entity: The entity you are classifying the event under
    • EventType: The event type for the entity you are classifying the event under
    • Domain: The domain you are classifying the event under
    • EventId: The ID for the event
    • EventBody: the body that is returned with the event. This is an unlimited string, where you will pass in a JSON object with all the data that you want to give to a user who is subscribed to your event.
  3. The microflow has error handling. So if it runs to completion, it should send off your event.

Receiving Events

Events are complicated because they have a standardized header, but the body depends on what event you triggered. Right now in USE_ME there is a sample microflow. Here is how you use it:

  1. In your own microflow, call the CWS_GetEvents to get a string containing the JSON returned by the call (due to the unique nature of each event, it is impossible to map events.)
  2. Use the "contains" function to figure out what event was returned to you based on the event header (this will need to be done on an application by application basis, because what is returned depends entirely on your subscribed events). The rest call is set to only return one event at time.
  3. Add the logic to handle your event. (You may want to map the response body to a non-presistable entity to make using it easier)
    • To map the string, use the import with mapping action, using a mapping that maps to the event body that you want. An example mapping (with an event body) is in the resources folder, titled IMp_GetEvents. You will want to copy this and the associated JSON (JSON_GetEvents) and modify the event body to fit your needs.

Dependencies

These dependencies are included in the BYU Starter App and are updated regularly.

Installation

  1. Download the module here. It will save as Eventhub.mpk
    1. Note: If you are using Mendix Studio Pro 8.8.* or 8.9.* downloading private app store modules/widgets was turned off due to security concerns. All the BYU Private App Store content can still be downloaded from the Company Content page in the Mendix App Store and then imported into those versions of Studio Pro. Upgrading to a newer version of Mendix Studio Pro fixes the problem.
  2. After the download finishes, import BYU Eventhub v1 into your project.
    1. Right click on your Project Explorer
    2. Select Import Module Package
    3. Select the module you just downloaded and click Open

More Resources

Learn how to install a module in Mendix.

Configuration

Make sure that you have your credentials configured through BYU Open Authentication, and drop in the snippets that you want to use.

Slack

For additional help, refer to the appropriate slack channels in their respective workspaces:

  1. BYU-OIT workspace
    1. #api-management
    2. #mendix
  2. BYU-Web workspace
    1. #mendix-user-group