Quick Integration: Linking the Calendar
Linking DayBack to Your Own File
Who is this Quick Integration designed for.
This quick version is for folks who want to keep the calendar as a separate file-- as a second .fmp12 in their solution. This can be a great option if you need to get up and running right away, are newer to FileMaker, or want to see the calendar in a new window anyway.
If you want to embed the calendar within your solution, follow these instructions for pasting the calendar layouts and scripts into your file.
Before you get to work, you can watch a short video of the entire integration being done: it takes just about 10 minutes...
Step-by-Step Instructions: Linking the Calendar.
1. Getting Ready
Back up your file. Really.
Now move DayBack.fmp12 into the same folder as the file you'll be working with. If you'd like to rename the calendar file, do that now as well.
These instructions assume you already have a table whose records you want to see in the calendar. If you don't, you can just paste our SampleEvents table into your file and skip to step 3 below.
Using our SampleEvents table is also a great strategy if you have a record in your file (like a job or workorder) with lots of dates associated with it (start date, due date, inspection date, etc.). In that case our SampleEvents table can be a "child" of your job or workorder and these dates become records in SampleEvents instead of fields in your parent record. This means you can have as many dates as you'd like related to that parent record and reporting on those dates gets much simpler: "find me everything Jim is doing in May" is a simple find in this kind of related events table, whereas it's quite hard to do if you have five different date fields in your parent record. If you have questions about this approach, please get in touch, we can help you decide if relating our SampleEvents table to your parent record is a good approach. It's certainly one of the simplest integrations you can do.
You may also have more than one table (or more than one date field in a table) that you want to see in the calendar. Don't worry about that for now: get one table/field up and running and then you can come back and configure additional data sources.
2. Adding New Fields
You'll copy and paste some fields from our SampleEvents table into your events table: fields the calendar needs in order to run. Some of these are SeedCode's calc fields, and some are just date and time fields calendars expect. If you don't have time fields for your events, or a DateEnd field, for example, you may want to copy and paste those in at the same time. You don't need to use these fields, but the calendar expects them and having them there now makes the integration simpler and lets you take advantage of multi-day events should the scope of your events change. (Note that if you want to enforce that events never have times or never span more than 1 day you can use auto-enter calcs in these newly created fields to force them to be blank.)
Open up DayBack.fmp12 and select File / Manage / Database, selecting the "Fields" tab of the "Manage Database" window and select the "SampleEvents" table. You'll copy a few fields from here and add them to your file. If you have FileMaker Advanced this is as simple as copying all the fields you don't have and those prefaced with "DBk_" (for "DayBack"). I generally copy these, though you might already have fields to use for status and resource...
Status
Resource
DBk_ColorCalc
DBk_EventSummaryCalc
DBk_LinkedWithinProject
DBk_MilestoneSort
DBk_Notified
DBk_Repeating_id
DBk_TimestampEndCalcNum
DBk_TimestampStartCalcNum
DBk_Unused
DBk_WebViewerEventData
DBk_WebViewerSource
...and pasting them into your file. If you don't have FileMaker Advanced, please get in touch and we'd be happy to get a copy of your files and perform this step for you.
2.1 Field Definitions
You'll now edit the definition for some of the fields you pasted in, selecting your fields for the DateStart, TimeStart etc. fields used in the calculation's let statements.
Here are some notes on each of the fields you'll need to edit. Some of these fields you can come back to later after you see the calendar working with your own data. Remember, for each field you'll edit you need to remove the leading and trailing "comment" tags (the /* and */) from the calc.
Resource: If you copied our resource field you're good to go. If you're using your own you may want to copy the auto-enter calc from our field as it adds "none" to the resource field if no resource is specified. This means that when you go the resources tab you can see all the events you haven't yet assigned a resource, and then drag then to open resources to schedule them.
DBk_EventSummaryCalc: This field is used to calculate which information about your event shows on the calendar in Day, Week, and Month views. For most users this is a combination of the event title and some other fields about the event. Begin by just replacing "Summary" with the field you'd like to see in the calendar, you can use our DBk_Unused field for the rest of the items for now and then come back to fine tune this once you have the calendar working. So a quick edit of this field might leave the editable part looking like this:
s = Summary ; // the title of your event
desc = DBk_Unused ; // your event's description or notes field
cont = DBk_Unused ; // your contact's name (optional)
ph = DBk_Unused ; // your contact's phone number (optional)
em = DBk_Unused ; // your contact's email (optional)
desc = DBk_Unused ; // your event's description or notes field
cont = DBk_Unused ; // your contact's name (optional)
ph = DBk_Unused ; // your contact's phone number (optional)
em = DBk_Unused ; // your contact's email (optional)
Having done a simple mapping like this, you can come back here later and flesh this out to include all the information you'd like to see in the calendar.
DBk_WebViewerSource: This is the field we use to populate the event details popover when you click on an item in the calendar. If you don't have some of these fields, like "contactID" use can use "DBk_Unused" for now. The date and time fields are required, so are the summary and the "id" which should be the primary key of your table. Be sure this field (and none of these newly created fields) is "commented out"--that is, it shouldn't begin with /* and end with */. If it does, delete those characters.
DBk_TimestampEndCalcNum and DBk_TimestampStartCalcNum: Edit this calc to use your own date and time fields. You may not have an end date field in your solution; You may also lack the time fields mentioned in this calc. The simplest thing is to add these fields to your events table: that makes the integration simpler and lets you take advantage of multi-day events should the scope of your events change. (Note that if you want to enforce that events never have times or never span more than 1 day you can use auto-enter calcs in these newly created fields to force them to be blank.)
DBk_ColorCalc: (you can come back to this one later). This field isn't used *in* the calendar but is here in case you want to show the same calendar colors in your FileMaker Layouts. Read more about editing this field later in "Event Colors".
2.2 Auto-Enter Calcs for Times
Next, add the following Auto-Enter Calculated Value option to the TimeStart field in your events table (you can copy this here or from the definition in SampleEvents):
Case (
Self = Time ( 24 ; 0 ; 0 ) ; Time ( 24 ; 0 ; 1 ) ;
Self = Time ( 0 ; 0 ; 0 ) ; Time ( 0 ; 0 ; 1 ) ;
Self > Time ( 24 ; 0 ; 0 ) ; Self - Time ( 24 ; 0 ; 0 ) + 1 ;
Self )
Self = Time ( 24 ; 0 ; 0 ) ; Time ( 24 ; 0 ; 1 ) ;
Self = Time ( 0 ; 0 ; 0 ) ; Time ( 0 ; 0 ; 1 ) ;
Self > Time ( 24 ; 0 ; 0 ) ; Self - Time ( 24 ; 0 ; 0 ) + 1 ;
Self )
Make sure you uncheck the "Do not replace existing value" checkbox. This Auto-Enter option is needed if you want events to be able to start at midnight.
Now add the same Auto-Enter Calculated Value option to the TimeEnd field in your events table. Again, make sure you uncheck the "Do not replace existing value" checkbox. This Auto-Enter option is needed if you want events to be able to end at midnight.
2.3 Fields for Contacts and Projects.
If your events are linked to contacts and/or projects, there are two new fields you'll need to add to these tables: DBK_WebViewerSource and DBK_WebViewerData. You can copy these from the SampleContacts table that comes with DayBack. Only the first of these needs to be edited, and in it you'll specify which of your fields is the primary key in the table and which field you want to be shown as the name of the contact when you select them from a list. So edit this section of the calc...
id = id ;
name = NameFull ;
...to look something like this:
id = MyContactID ;
name = MyNameLastFirst ;
2.4 Pause and Save Your Work.
Really. It's a good habit to get into. =)
3. The Relationship Graph.
Return to DayBack.fmp12 and again select File / Manage / Database, selecting the "Relationships" tab of the Manage Database window.
Double click on the "SampleEvents" table occurrence in the graph and click in the pop-up list next to "Data Source:"-- select "Add FileMaker Data Source" from the list of options and, in the next window, select your file.
You'll now see all the tables in your file: select the one which has the records you'd like to see in the calendar. Change the name at the bottom of the "Specify Table" window back to "SampleEvents" (you can change it back later) and click "OK". You've now "pointed" the calendar's events table at the events table in your file: eventually you'll be able to delete the SampleEvents table in DayBack.fmp12, but don't do it yet as you'll need it in the next step.
Note that you'll get an error if you try to view the calendar at this point. That's normal. It will throw errors until we're done with step 4.
(I'd move on to step 4 now: once the calendar is showing your events you can come back here and wire up information about the contacts and projects related to your events.)
3.1 Contacts and Projects
Note, if your events are linked to contacts, you can do the same thing with the SampleContacts table occurrences you see in the calendar. Double click on the table occurrence, select your file (which now appears in the list of data sources) and select the contacts table in your file. Create a relationship between SampleEvents and SampleContacts using the same match fields you use for this kind of relationship in your file.
If you're using the projects or our gantt charts you'll want to do the same thing to our SampleProjects table occurrence and our SamplePhases (if you're not using Phases, you can just leave it alone). Point these at the relevant tables in your file and make sure that they are connected to SampleEvents by the unique ids in each table.
If you don't have a contacts or projects table, and wish you did, you may want to pause this integration and take a look at SeedCode Complete, which already has our calendar linked to a rich contacts and project management system.
If you deleted the sample Contact, Project, or Phase table occurrences from your graph as we do in our video, be sure to visit the script "Load Source Settings at Startup --- Describe Your Sources Here ---". There you'll see two variables declared with the name of these tables. Replace those table names with "" (blank) or the calendar will ask where they are when you run the calendar's upon opening script.
4. Field Mapping Layout
Navigate to the Source No 1 layout in DayBack.fmp12 and follow the instructions on the layout to map the fields there to the relevant fields in your events table.
A few tips on field mapping:
All fields on the Source No layout need to be mapped, and there are six tabs with fields on them. For any fields that don't have a corresponding field in your events table, map DBk_Unused in their place.
Events with just a single date should have a start date: if your event has just an end date the calendar will fail. The same goes for times: if there is only one time, make it the start time.
Don't use calcs for things like the dates, times, or resources. The calendar wants to edit these values when you drag items around, and it can't edit calcs. Use auto-enter calculations instead if you must.
Contacts & Projects
If you are using a contacts or projects table you will want to map those too. Navigate to the "Related Source No 1" layout and map your contact fields. Then you can navigate to "Related Source No 2" and map your project fields if necessary.
Once you've mapped these fields you can run the script "Upon Opening" in DayBack.fmp12 and if you haven't made any mistakes you should see your events in the calendar! If you're seeing errors you might skim through the steps above again to see if you missed anything, or checkout our troubleshooting tips. And you can always get in touch if those troubleshooting steps don't work for you: we're here to help.
Enjoy!
Going Further
Now that you've got the calendar showing your own records (congratulations!) you'll likely want to return to a few places and do a more thorough job of mapping the calendar to your events. Here are the places we like to revisit...
• Color Coding. Click on the filters tab of the calendar and edit the statuses listed there to match the values in the field you mapped to "status" on your Source No 1 layout. This is the field we'll use for color coding. Click on the gear icon beside a status to change it's name or color. Click on the "+" icon to add new ones. Read more about colors here.
• Showing Additional Fields Remember the summary calc (DBk_EventSummaryCalc) you edited when setting up your calendar? You'll want to go back to that field and add in any additional event fields you'd like to see in the calendar. You'll likely want to do the same with the field DBk_WebViewerSource. Tips for configuring both these fields can be found here: adding fields to the calendar.
• Resources. Take a look at the field you mapped to Resource and edit the Resources value list in the calendar so it matches the contents of that field: we used "location" as the resource in our video and changed the "Resources" value list in the calendar to point to an existing value list in the Meetings file. You may want to do something similar. More on resources.
• Filtering the Calendar If you need to set up more filters or point the existing ones at your own fields, then check out our notes on filters.
• General Settings. You'll also want to read through the script "Load Calendar Settings - On Startup --- Edit Configuration Here ---" making changes as necessary: this lets you change a number of the calendar's default settings and is a good read as it lets you know what's already set up for you to change.
• Renaming Sample Events. If you'd like to change the name of "sample events" in the relationships tab, you can do that now, just read about this script you'll need to edit afterwards: renaming tables.
• Linking Contacts & Projects to Events You may have just mapped the DBk_Unused field to the contact and project IDs you encountered during integration. If your events are linked to contacts or projects now is the time to teach the calendar about those relationships.
• Additional Tables (Sources). And don't forget you can show records from additional tables, not just the one your named Sample Events. We call each of these events tables "sources" and any table that has dates in it can be a source. Learn more by reading about multiple sources.
• Event List. If you've linked the calendar with your own file, and don't have your own list view for your events table, you may want to use the "Event List" layout in the calendar file. If so, sure to enter layout mode and repoint the fields and the sorts on the layout's summary parts. More here: Using the Event List Layout.
• The "Action - View Event" Layout One of DayBack's example custom actions takes you to a sample event record in a FileMaker layout called "Action - View Event". If you want to make use of this layout you'll need to repoint it to the fields in your own events table much as you did with the event list.
• To-Do Details and List. If you're using the To-Do list table that came with DayBack there is probably nothing to do here but may want to visit these two To-Do layouts and add or remove fields that don't apply to you.
• Deleting Unused Tables. Finally, if you've linked DayBack file to your file (instead of embedding it) you may want to delete the tables you're not using (like our original SampleEvents table, sample contacts, etc.)
• Displaying the DBk_ColorCalc in linked integrations. If you've linked DayBack, utilizing the DBk_ColorCalc field to display an event's status color on FileMaker layouts outside the calendar requires a few additional steps:
1. Add a "CalendarColors" table occurrence to your data file (wherever your Events table is located) based on the CalendarColors table in your DayBack file.
2. Add a new layout named "Calendar Status Colors" in your data file based on this CalendarColors table occurrence.
3. Copy the script "Load Calendar Color Coding" from DayBack and paste it in your data file.
4. At the bottom of the "Load Calendar Settings - On Startup" script, add another Perform Script step which calls the new "Load Calendar Color Coding" script from your data file.
• Getting Ready for PSOS. If you've using FileMaker Server, check that your file's start up script bails out when run on FileMaker Server. Each Perform Script on Server (PSOS) script initiated runs the start up script in any required files and that can really slow things down. Feel free to use the same routine used as the first lines of DayBack's "Upon Opening" script:
If [PatternCount ( Get ( ApplicationVersion ) ; "Server" )]
Exit Script []
End If
