Description

Defines a new Entity. Event Types are grouped in Domains and then Entities. Entities are generally associated with the business application that is raising the Event. They are also defined to belong a specific domain.

This makes the new Entity visible on the Administrative Portal. The Administrative Portal is used by developers to manage their subscriptions.

 
URL Structure
{Base URL}/entities
HTTP Method POST  
Authentication Required  
Request Headers none
Parameters none  
Request Body
<entity_definition xmlns="http://ws.byu.edu/namespace/event-hub/v1">
   <entity/>             --required
   <description/>        --optional
   <domain/>             --required
   <entity_ega/>         --Administrative use only
</entity_definition>
<entity_definition xmlns="http://ws.byu.edu/namespace/event-hub/v1">
   <entity>AIM WaitListing</entity>
   <description>
      Wait List module adds classes as space allows
   </description>
   <domain>edu.byu</domain>
   <entity_ega>388211692</entity_ega>
</entity_definition>
{
  "entity_definition": {
    "entity": "AIM WaitListing",
    "description": 
      "Wait List module adds classes as space allows",
    "domain": "edu.byu"
  }
}
Returns
<entity_definition xmlns="http://ws.byu.edu/namespace/event-hub/v1">
   <entity/>             --from request
   <description/>        --from request
   <domain/>             --from request
   <entity_ega/>         --from request
</entity_definition>
<entity_definition xmlns="http://ws.byu.edu/namespace/event-hub/v1">
   <entity>AIM WaitListing</entity>
   <description>
      Wait List module adds classes as space allows
   </description>
   <domain>edu.byu</domain>
   <entity_ega>388211692</entity_ega>
</entity_definition>
{
  "entity_definition": {
    "entity": "AIM WaitListing",
    "description": 
      "Wait List module adds classes as space allows",
    "domain": "edu.byu",
    "entity_ega": "388211692"
  }
}

Errors

Return Code Additional Explanation
400 Missing Key Values
401 Entity EGA is not a valid Person ID
401 Entity does not match the name associated with the Entity EGA
409 Domain-Entity combination already exitst.
<fault_message xmlns:"http://ws.byu.edu/namespace/event-hub/v1">
  <return_code/>    -- http return code
  <explanation/>    -- see the table above
  <error_data/>     -- from request
</fault_message>
<fault_message xmlns:"http://ws.byu.edu/namespace/event-hub/v1">
   <return_code>401</return_code>
   <explanation>
      Entity EGA is not a valid Person ID
   </explanation>
   <error_data>585241162</error_data>
</fault_message>
{
  "fault_message": {
    "return_code": "401",
    "explanation": "Entity EGA is not a valid Person ID",
    "error_data": "585241162"
  }
}
Notes

In order to define an entity, you must authenticate as:

  • An Event Hub administrator,
  • The Entity EGA itself, or
  • An administrator of the Entity EGA (future implementation).