Difference between revisions of "Zulu - Integrate Into Your FileMaker Solution"

From 360Works Product Documentation Wiki
Jump to navigation Jump to search
 
(22 intermediate revisions by 2 users not shown)
Line 1: Line 1:
==Integration: Adding Zulu 2 Calendar Support to Your FileMaker Solution==
+
: This page provides instructions on how to integrate Zulu into a pre-existing solution.  If you would prefer to use the Zulu2SampleData file, you only should be concerned about the Prerequisites section.
  
<big style="color:#cc0000">'''Note:''' Avoid periods (.) and hyphens (-) in your database & layout names.</big>
+
=Prerequisites=
  
===Install Zulu===
+
* Install Zulu - Follow these instructions to install Zulu on your FileMaker Server: [[Zulu - Installation]]
 +
* Host Your Calendar Database - If you haven't already, upload your calendar database to FileMaker Server and work on it there.
 +
* Backup your file - You'll be creating a new table in the steps that follow and you should always backup before making such changes.
 +
* Enable XML Web Publishing - Zulu uses the XML Web Publishing engine, and you may need to check that it is enabled, and your accounts have the privileges to use it.  See here for instructions: [[Enable XML FileMaker 17]]
 +
* <big style="color:#cc0000">Avoid periods (.) and hyphens (-) in your database & layout names.</big>
  
Follow these instructions to install Zulu on your FileMaker Server: [[Zulu - Installation]]
+
=Components to Import=
  
===Backup your file===
+
You will need to import the following scripts, tables, and layout components into your FileMaker solution.
  
Really. You'll be creating a new table in the steps that follow and you should always backup before making such changes. If you have FileMaker Pro Advanced, upload your file to your FileMaker Server and work on it there.
+
==Scripts==
 
 
===Scripts===
 
  
 
In the ZuluSampleData.fmp12 file, under the Scripts Workspace you'll need to copy the following scripts to your own solution on FileMaker Server:
 
In the ZuluSampleData.fmp12 file, under the Scripts Workspace you'll need to copy the following scripts to your own solution on FileMaker Server:
:"Add New Calendar"
+
*Publish Calendar
:"Publish Calendar"
+
*Validate Events
:"Validate Events"
+
*Zulu_PostEdit
:"Zulu_PostEdit"
+
*Zulu_PreDelete
:"Zulu_PreDelete"
 
  
===Tables===
+
==ZuluCalendarList Table==
 +
In short, import the ZuluCalendarList table into your solution, and create a plain layout for it that is also named "ZuluCalendarList". 
  
====ZuluCalendarList====
+
While the events table is customizable, the calendar table is not.  Zulu requires you to have a table and layout named ZuluCalendarList in your database. This table must also contain the same fields as the ZuluCalendarList table in the ZuluSampleEvents file. Set this up in your solution with one of the following options:
Copy the “ZuluCalendarList” table to your solution. This will create a layout with the same name and all the table's fields on it. You may hide the ZuluCalendarList layout, but '''do not rename it, or add/remove fields from this layout.'''
 
  
:If you don't have FileMaker Advanced (which lets you copy and paste tables from file to file) you'll need to recreate the “ ZuluCalendarList” table in your solution by hand, and then add all the fields from it to the default layout the FileMaker creates for you when you create a new table. There are only 14 simple fields here so this won't take long, but make sure you get the auto enter field options exactly the same as they are in the sample file.
+
* Copy the “ZuluCalendarList” table to your solution. This will create a layout with the same name and all the table's fields on it. You may hide the ZuluCalendarList layout, but '''do not rename it, or add/remove fields from this layout.'''
  
:You can also import the table if you don't have Advanced, but take your file off the server first. From your file select File / Import Records... / File and then select the Zulu sample file. Select the ZuluCalendarList table to import and for the target, select "New Table". FileMaker will create the new table and calcs for you.
+
* If you don't have FileMaker Advanced (which lets you copy and paste tables from file to file) you'll need to recreate the “ ZuluCalendarList” table in your solution by hand, and then add all the fields from it to the default layout the FileMaker creates for you when you create a new table. There are only 14 simple fields here so this won't take long, but make sure you get the auto enter field options exactly the same as they are in the sample file.
  
====Events Table====
+
* You can also import the table if you don't have Advanced, but take your file off the server first. From your file select File / Import Records... / File and then select the Zulu sample file. Select the ZuluCalendarList table to import and for the target, select "New Table". FileMaker will create the new table and calcs for you.
Do you have an existing "events" table? If not, copy our "ZuluSampleEvents" table to your solution.
 
  
===Field Mapping===
+
==Events Table And Field Mapping==
 +
===Overview===
 
[[File:ZuluObjectMapping.png|x150px|frame|ZuluSampleEvents layout.  The Summary field and its layout object name for the Field Mapping ]]
 
[[File:ZuluObjectMapping.png|x150px|frame|ZuluSampleEvents layout.  The Summary field and its layout object name for the Field Mapping ]]
If you integrating Zulu into your own file, first understand that Zulu derives the Field Mapping through FileMaker Layout Object Names.  If you check the ZuluSampleEvents layout in the Zulu2SampleData file, you will see all the fields have object names that correspond to a particular Field Mapping: <br/ >
+
When integrating into your own file, understand that Zulu derives the event Field Mapping through FileMaker Layout Object Names.  The Field Mapping tells Zulu which fields map to which event properties.  If you check the ZuluSampleEvents layout in the Zulu2SampleData file, you will see all the fields have object names that correspond to a particular Field Mapping.  You need to recreate this setup in your own file, setting the proper object names to the right fields.  If you don't already have an events table in your file, copy our "ZuluSampleEvents" table to your solution.<br/ >
  
This is the portion of setup that lets Zulu 2 know which fields map to which event properties. Zulu 2 uses object names make this distinction, so don't be alarmed if you see <code><Field Missing></code> when you first paste in our tab control, this is normal. <br />
+
===Setup Event Fields===
 +
The tab panels on the ZuluSampleEvents layout contain all of the fields you will need for Zulu. Also, the object names are already set up for these objects.  So the quickest way to accomplish this setup is to:
  
Copy the tab control from the “ZuluSampleEvents” layout and paste it into your solution on a new blank layout based on your events table (or the one your brought over in 4b above). There should be nothing else (or at least no other named objects, and no script triggers) on this layout.
+
* Create a new layout based on your events table. There should be no script triggers, and no other named objects on this layout.  This layout can be named anything you want, but avoid special characters (spaces, hyphens, apostrophes) if possible.
  
:You can name this layout whatever you want: this will be the name of your calendar in Apple Calendar, though you can always [[Zulu Calendar Properties|change the calendar name]] later.
+
* Copy the tab panels from the “ZuluSampleEvents” layout, and paste it into your solution onto the new layout.  Don't be alarmed if you see <Field Missing> on the pasted tab panels, this is normal and will be fixed in the next step.
  
Follow the mapping instructions on the “ZuluSampleEvents” layout, selecting the relevant fields from your file. You may need to create a couple new fields in your events table if you don't have creation and modification timestamps, and you'll almost certainly need to create the zulu_UUID and zulu_ICAL_DATA fields on the required tab. And you can't use the same field for Date Start as Date End (same with Time End): create new "end" fields if you don't have them.
+
* Assign each pasted field to an actual field in your database. Do this by double-clicking the fields in layout mode and selecting a field that best fits their purpose.
  
:You may want to copy some of these fields from the ZuluSampleEvents table in our sample file.
+
* You can see more about what these fields are for here: [[Zulu Event Properties]]
  
:Fields you probably already have...  
+
===Notes===
----
+
* You may need to create a couple new fields in your events table if you don't have creation and modification timestamps, and you'll almost certainly need to create the zulu_UUID and zulu_ICAL_DATA fields.  
Event ID  
+
* Use unique fields for each calendar property. For example don't use the same field for Date Start as Date End.
DateStart
+
* Make sure the fields you create are of the same type (number, text, or timestamp) as they are in our sample file, and that your creation and modification timestamps auto enter.
DateEnd
+
* You can copy any missing fields from the ZuluSampleEvents table in the Zulu2SampleData file included with the download.
TimeStart
+
* The zulu_UUID is not the unique ID in your table (even if you have a UUID), this is iCal's UUID for the event, so be sure to create a field for this. Your unique ID gets mapped to "Event ID". Zulu handles this field and populates it as needed, so don't worry if it doesn't have a value right away.
Time End
+
* The zulu_UUID also has an auto-enter definition you'll want to preserve (we auto-enter a blank value). Make sure you set this up exactly as it is in our sample file and that the option "Do not replace existing value of field..." is unchecked.''
Summary
 
Note
 
  
:Fields you likely don't already have...
+
=Publish your calendar=
----
 
zulu_ALARM_EMAIL_RECIPIENTS
 
zulu_ALARM_TRIGGER_MINUTES
 
zulu_ALARM_TRIGGER_TIMESTAMP
 
zulu_ALARM_TYPE
 
zulu_CREATION_TIMESTAMP
 
zulu_DELETED
 
zulu_ICAL_DATA
 
zulu_LOCATION
 
zulu_MODIFICATION_TIMESTAMP
 
zulu_URL
 
zulu_UUID
 
Exchange_Attendees_Optional
 
Exchange_Attendees_Required
 
Google_Attendees_Optional
 
Google_Attendees_Required
 
zulu_RECURRECE
 
zulu_RECURRENCEID
 
  
: Make sure the fields you create are of the same type (number, text, or timestamp) as they are in our sample file, and that your creation and modification timestamps auto enter.
+
Navigate to the field mapping layout in your file and run the "Publish Calendar" script which you pasted into your solution.
  
'''Note''' ''that this zulu_UUID is not the unique ID in your table (even if you have a UUID), this is iCal's UUID for the event, so be sure to create a field for this. Your unique ID gets mapped to "Event Primary Key". Zulu 2 handles this field and populates it as needed, so don't worry if you don't see it have a value right away.
+
Enter your FileMaker account and password when prompted. This doesn't have to be the full access account and password, but it does need to have write access to the ZuluCalendarList table. The account and password entered aren't stored anywhere. '''Note: this account must have a password. Apple Calendar will refuse to authenticate an account with only a username and no password.'''
  
The zulu_UUID also has an auto enter definition you'll want to preserve (we auto-enter a blank value). Make sure you set this up exactly as it is in our sample file and that the option "Do not replace existing value of field..." is unchecked.''
+
The "Published..." page will contain your new calendar's URL and instructions for viewing your calendar in iCal, follow these instructions to see the calendar(s) on your iPhone: configuring your iPhone.
 
 
Don't worry about calendars from [[Zulu Multiple Calendars|multiple tables]] at the moment; you can come back and get additional tables set up once you have your first table working.
 
 
 
===Enable XML Web Publishing===
 
 
 
Zulu uses the XML Web Publishing engine, and you may need to check that it is enabled, and your accounts have the privileges to use it. 
 
 
 
See here for instructions on how to do this: [[Enable XML FileMaker 17]]
 
 
 
===Publish your calendar===
 
 
 
Upload your file to your FileMaker Server if you've been doing this work locally.
 
 
 
Navigate to the field mapping layout in your file and run the "Publish Calendar" script which you pasted into your solution.
 
 
 
Enter your FileMaker account and password when prompted. This doesn't have to be the full access account and password, but it does have to have write access to the ZuluCalendarList table. The account and password entered aren't stored anywhere. '''Note: this account must have a password. Apple Calendar will refuse to authenticate an account with only a username and no password.'''
 
  
 
If you have issues running your Publish Calendar script, you may need to modify it for your own server, see this section for more details: [[Zulu - Calendars and Publishing#Customizing The Publish Script | Customizing The Publish Script]]
 
If you have issues running your Publish Calendar script, you may need to modify it for your own server, see this section for more details: [[Zulu - Calendars and Publishing#Customizing The Publish Script | Customizing The Publish Script]]
  
==That's it!==
+
=Going Further=
  
The "Published..." page will contain your new calendar's URL and instructions for viewing your calendar in iCal, follow these instructions to see the calendar(s) on your iPhone: configuring your iPhone.
+
See how to set up your calendar database with the following services:
 +
* [[Zulu - Integrating with Apple Calendars | Integrating with Apple Calendars]]
 +
* [[Zulu - Syncing with Google Calendars | Syncing with Google Calendars]]
 +
* [[Zulu - Syncing with Exchange Outlook Calendars | Syncing with Exchange Outlook Calendars]]
  
 
To see more about filtering the events for each calendar, refer to: [[Zulu - Filtering]]
 
To see more about filtering the events for each calendar, refer to: [[Zulu - Filtering]]
  
 
To see more about the components of the ZuluCalendarList table, see [[Zulu Calendar Properties]]
 
To see more about the components of the ZuluCalendarList table, see [[Zulu Calendar Properties]]

Latest revision as of 15:24, 8 July 2019

This page provides instructions on how to integrate Zulu into a pre-existing solution. If you would prefer to use the Zulu2SampleData file, you only should be concerned about the Prerequisites section.

Prerequisites

  • Install Zulu - Follow these instructions to install Zulu on your FileMaker Server: Zulu - Installation
  • Host Your Calendar Database - If you haven't already, upload your calendar database to FileMaker Server and work on it there.
  • Backup your file - You'll be creating a new table in the steps that follow and you should always backup before making such changes.
  • Enable XML Web Publishing - Zulu uses the XML Web Publishing engine, and you may need to check that it is enabled, and your accounts have the privileges to use it. See here for instructions: Enable XML FileMaker 17
  • Avoid periods (.) and hyphens (-) in your database & layout names.

Components to Import

You will need to import the following scripts, tables, and layout components into your FileMaker solution.

Scripts

In the ZuluSampleData.fmp12 file, under the Scripts Workspace you'll need to copy the following scripts to your own solution on FileMaker Server:

  • Publish Calendar
  • Validate Events
  • Zulu_PostEdit
  • Zulu_PreDelete

ZuluCalendarList Table

In short, import the ZuluCalendarList table into your solution, and create a plain layout for it that is also named "ZuluCalendarList".

While the events table is customizable, the calendar table is not. Zulu requires you to have a table and layout named ZuluCalendarList in your database. This table must also contain the same fields as the ZuluCalendarList table in the ZuluSampleEvents file. Set this up in your solution with one of the following options:

  • Copy the “ZuluCalendarList” table to your solution. This will create a layout with the same name and all the table's fields on it. You may hide the ZuluCalendarList layout, but do not rename it, or add/remove fields from this layout.
  • If you don't have FileMaker Advanced (which lets you copy and paste tables from file to file) you'll need to recreate the “ ZuluCalendarList” table in your solution by hand, and then add all the fields from it to the default layout the FileMaker creates for you when you create a new table. There are only 14 simple fields here so this won't take long, but make sure you get the auto enter field options exactly the same as they are in the sample file.
  • You can also import the table if you don't have Advanced, but take your file off the server first. From your file select File / Import Records... / File and then select the Zulu sample file. Select the ZuluCalendarList table to import and for the target, select "New Table". FileMaker will create the new table and calcs for you.

Events Table And Field Mapping

Overview

ZuluSampleEvents layout. The Summary field and its layout object name for the Field Mapping

When integrating into your own file, understand that Zulu derives the event Field Mapping through FileMaker Layout Object Names. The Field Mapping tells Zulu which fields map to which event properties. If you check the ZuluSampleEvents layout in the Zulu2SampleData file, you will see all the fields have object names that correspond to a particular Field Mapping. You need to recreate this setup in your own file, setting the proper object names to the right fields. If you don't already have an events table in your file, copy our "ZuluSampleEvents" table to your solution.

Setup Event Fields

The tab panels on the ZuluSampleEvents layout contain all of the fields you will need for Zulu. Also, the object names are already set up for these objects. So the quickest way to accomplish this setup is to:

  • Create a new layout based on your events table. There should be no script triggers, and no other named objects on this layout. This layout can be named anything you want, but avoid special characters (spaces, hyphens, apostrophes) if possible.
  • Copy the tab panels from the “ZuluSampleEvents” layout, and paste it into your solution onto the new layout. Don't be alarmed if you see <Field Missing> on the pasted tab panels, this is normal and will be fixed in the next step.
  • Assign each pasted field to an actual field in your database. Do this by double-clicking the fields in layout mode and selecting a field that best fits their purpose.

Notes

  • You may need to create a couple new fields in your events table if you don't have creation and modification timestamps, and you'll almost certainly need to create the zulu_UUID and zulu_ICAL_DATA fields.
  • Use unique fields for each calendar property. For example don't use the same field for Date Start as Date End.
  • Make sure the fields you create are of the same type (number, text, or timestamp) as they are in our sample file, and that your creation and modification timestamps auto enter.
  • You can copy any missing fields from the ZuluSampleEvents table in the Zulu2SampleData file included with the download.
  • The zulu_UUID is not the unique ID in your table (even if you have a UUID), this is iCal's UUID for the event, so be sure to create a field for this. Your unique ID gets mapped to "Event ID". Zulu handles this field and populates it as needed, so don't worry if it doesn't have a value right away.
  • The zulu_UUID also has an auto-enter definition you'll want to preserve (we auto-enter a blank value). Make sure you set this up exactly as it is in our sample file and that the option "Do not replace existing value of field..." is unchecked.

Publish your calendar

Navigate to the field mapping layout in your file and run the "Publish Calendar" script which you pasted into your solution.

Enter your FileMaker account and password when prompted. This doesn't have to be the full access account and password, but it does need to have write access to the ZuluCalendarList table. The account and password entered aren't stored anywhere. Note: this account must have a password. Apple Calendar will refuse to authenticate an account with only a username and no password.

The "Published..." page will contain your new calendar's URL and instructions for viewing your calendar in iCal, follow these instructions to see the calendar(s) on your iPhone: configuring your iPhone.

If you have issues running your Publish Calendar script, you may need to modify it for your own server, see this section for more details: Customizing The Publish Script

Going Further

See how to set up your calendar database with the following services:

To see more about filtering the events for each calendar, refer to: Zulu - Filtering

To see more about the components of the ZuluCalendarList table, see Zulu Calendar Properties