LDSTechForumProjects

Church Historical Timeline data model and API

This page may need to be merged for quality to meet the LDSTech guidelines.
This page is being divided into several pages, including the Church Historical Timeline API.

User Stories

  • A user can create a timeline in any language (default is US-English "en-us"). The creator of a timeline is the owner. The timeline is created as public (anyone can subscribe to it) or private (subscribers are invited by the owner).
  • A user can create an event and assign it to a timeline.
  • A user can specify the icon (from a list of standard icons) and stylesheet class for an event.
  • A user can edit and delete an existing event.
  • An owner can publish a timeline to make it visible.
  • A user can search for public timelines by name.
  • A user can subscribe to any public timeline.
  • An owner can add subscribers to their private timeline.
  • An owner can specify the role of a subscriber (user, editor, admin).
  • An owner can delete subscribers from their private timeline.
  • An admin can assign a different owner for a timeline (owners are admins by default).

RESTful APIs

  • REST QUESTIONS:
  1. What are the URIs?
  2. What's the format?
  3. What methods are supported at each URI?
  4. What status codes could be returned?
  • FORMAT:
HTTP Method CRUD Action Description
POST Create Create a new resource
GET Retrieve Retrieve a representation of a resource
PUT Update Update a resource
DELETE Delete Delete a new resource
  • METHODS AND STATUS CODES:
Resource Method Representation Status Codes
Timeline GET Timeline List Format
Timeline POST Timeline
Timeline PUT Timeline
Timeline DELETE Timeline


API LIST

Note: the login API must be called for all RESTful APIs, except where noted

NO API

  • Timeline Add - will be done via the management app
  • Timeline Update - will be done via the management app
  • Timeline Delete - will be done via the management app
  • Role - will be done by the DBA
  • Language - will be done by the DBA


API NEEDED

  • login - must be done for everything except searching for and viewing public timelines
  • timeline:search -
  • subscriber:subscribe -
  • subscriber:add -
  • subscriber:update -
  • subscriber:delete -
  • event:search -
  • event:add -
  • event:update -
  • event:delete -

API DEFINITION

  • add subscriber: only the owner can add subscribers to a private timeline. add a subscriber who can view a timeline. If the "edit" flag is set, the subscriber can edit the timeline to which they belong.
  • add event: create an event that is associated with an existing timeline
    • Example URL: http://tech.lds.org/timeline/event/add
    • INPUT (POST): <?xml version="1.0"?><p:add xmlns:p="http://tech.lds.org" xmlns:xlink="http://www.w3.org/1999/xlink"><sessionId>trU823NbvtxuKme49G38JwOi7</sessionId><timelineId>1234abcd5678</timelineId><event><title>Angel Moroni"s Visit</title><description>Joseph Smith is visited by the Angel Moroni and told of the Book of Mormon record.</description><startDate>Sep 21 1823</startDate><endDate>Sep 22 1823</endDate><iconId>14</iconId><imageUrl></imageUrl><linkUrl></linkUrl></event></p:add>
    • OUTPUT: <?xml version="1.0"?><p:add xmlns:p="http://tech.lds.org" xmlns:xlink="http://www.w3.org/1999/xlink"><eventId>9876zyxw5432</eventId><status>success</status></p:add>


Future APIs

  • move timeline: only an owner can transfer ownership of a timeline. Once moved, an owner no longer has access to the timeline.

Data Model

Parking Lot:

  • mashups - combines groups of events together in a single display (need to track icon, style, or whatever for each mashup so that groups of events appear differently/distinctly)
  • wards/stakes become owners of their timelines (so ward/stake administrators should be able to edit them), but do we use the unit number to indicate the owner?)

Data Model

Download the SQL: https://tech.lds.org/svn/timelines/trunk/db/timelineDB.sql

Events Table

Type Name Description
BIGINT ID Globally unique ID for the given event. Also primary key.
TIMESTAMP Created_Date Date the event was created in the database.
VARCHAR(50) Created_By Username of the user that created the event.
TIMESTAMP Updated_Date Date the event was last modified.
VARCHAR(50) Updated_By Username of the user that modified/updated/edited the event.
VARCHAR(500) Title Title of the event (appears on the timeline label and at the top of the event bubble that appears when you click on any event on the timeline).
VARCHAR(4000) Description Textual description of the event that appears in the body of the event bubble.
VARCHAR(500) Start_Date The date when the event occurred (or the beginning date for an event that covers a span of time (e.g. The Life of Adam from 4000BC to 3040BC).
VARCHAR(500) End_Date The date when an event ended. If the event is an instant in time (e.g. The First Vision in the Spring of 1820) then this column is left blank. Only add an end date if an event is a span of time / duration.
INT Icon_ID (NEED LOOKUP TABLE!) The ID of the icon you want to appear for this event. Church events will appear with one standard icon, world events with another, and personal or genealogy events with a variety of selectable icons (colored circles).
VARCHAR(500) Image_URL The url of an image that will appear in the event bubble.
VARCHAR(500) Link_URL The url that the browser will be redirected to if someone clicks on the title in an event bubble.
BIGINT Timeline_ID (LOOKUP TABLE: TIMELINE) The ID of the timeline that this event is associated with.

Language Table

Type Name Description
BIGINT ID Globally unique identifier (GUID) for a timeline (church, world, personal, etc.).
TIMESTAMP Created_Date Date the timeline was created.
VARCHAR Created_By Userid of the user that created the timeline.
TIMESTAMP Updated_Date Date the timeline was last modified.
VARCHAR Updated_By Username of the user that modified the timeline.
VARCHAR Language_Code Code for a given language (en=english; fr=French; etc.) and optional dialect (us=American; uk=United Kingdom; etc.). Used in conjunction with the LANGUAGE_CODE. (en-us; en-uk; etc.).
VARCHAR Language_Name Name of the language "English (American)"; "English (United Kingdom)"; "French"; "Spanish"; etc.
VARCHAR Language_Description Description of the language (may be helpful for describing unique dialects).

Timeline Table

Type Name Description
BIGINT ID Globally unique identifier (GUID) for a timeline (church, world, personal, etc.).
TIMESTAMP Created_Date Timestamp of when the timeline was created.
VARCHAR(50) Created_By Username of the user that created the timeline (this is the "owner" of the timeline).
TIMESTAMP Updated_Date Timestamp of when the timeline was last modified.
VARCHAR(50) Updated_By Username of the user who last updated the timeline.
VARCHAR(500) Title Timeline title.
VARCHAR(4000) Description Description of the timeline purpose, events to include in the timeline, etc.
INT Accessibility Timeline is either public (viewable by anyone) or private (viewable only by subscribers).
VARCHAR Copyright Copyright notice for timeline (LDS, etc.).
BIGINT Language_ID Link to the language table for this timeline entry. (Church historical timeline events should be translated into all supported languages. Personal events can optionally be entered in multiple languages.

Timeline Subscriber Table

Type Name Description
BIGINT ID Globally unique identifier (GUID) for a this record.
BIGINT Timeline_ID Links to the Timeline table
VARCHAR(50) Subscriber Username of the user who is subscribing to the timeline
INT Role_ID Defines the role of a subscriber. A "user" role enables the subscriber to see the timeline, an "editor" role enables the subscriber to create & modify events, an "admin" role enables the subscriber to add, update, and delete events.

Role Table

Type Name Description
BIGINT ID Globally unique identifier (GUID) for a role (user, editor, admin).
TIMESTAMP Created_Date Timestamp of when the role was created.
VARCHAR(50) Created_By Username of who created the role.
TIMESTAMP Updated_Date Timestamp of when the role was last updated.
VARCHAR(50) Updated_By Username of who last updated the role.
VARCHAR(50) Name Name of the role (Subscriber, editor, admin).
VARCHAR(500) Description Description of the role (e.g., user can view, not edit, timeline events).

PERMISSIONS

  • public timelines can be viewed by anyone, no subscription is necessary
  • private timelines can only be viewed by subscribers (added by the owner)

Java Development

Object Model

org.lds.community.ch.timeline.model.Event
extends BaseEntity
Long id
String title
String description
String start
String end
Timeline timeline


org.lds.community.ch.timeline.model.Timeline
extends BaseEntity
Long id
String title
String description
List<Event> events

XML Loader

Check it out at <server:port>/timeline/xml-loader.jsf
Load one of the xml files in the src/main/webapp directory:

  • world.xml (seems to have problems)
  • lds.xml
  • tom.xml (really short and should probably be renamed) :)

Timeline JavaScript

Extract Style From JavaScript

This is being done by the Timeline development team, so no work is required from LDS development team - we simply need to adopt changes as they become available.

Make the Timeline a JQuery Plugin

We looked into this option, but the timeline is already driven via CSS and the benefit would be minimal (updating the timeline code to the latest Google version would prove more difficult going forward, if the JQuery additions were not adopted). Rhusted 19:23, 19 February 2009 (UTC)

Misc

  • timeline-list.jsf shows a list of the available timelines
  • timeline.jsf shows the timeline (loading from the database - rest style) - still has issues
This page was last modified on 7 April 2010, at 05:53.

Note: Content found in this wiki may not always reflect official Church information. See Terms of Use.